Bobcamgardo/research-agent

Research-Agent

      

🌟 Key Features

[image]

Research-Agent is a LangGraph-based autonomous agent that searches 10 sources in parallel (Tavily, arXiv, Wikipedia, Semantic Scholar, GitHub, Hacker News, Stack Overflow, Reddit, YouTube, local RAG), fact-checks the synthesis and flags dubious claims, then exports a cited report with word count and reading time in PDF, Word, Markdown, or HTML — all through a Streamlit UI backed by a local Ollama LLM. Cross-session memory prevents re-investigating past topics.

Features

• —Parallel Multi-Source Research: Web, Wikipedia, arXiv, Semantic Scholar, GitHub, Hacker News, Stack Overflow, Reddit, YouTube, and local RAG -- all execute concurrently via ThreadPoolExecutor.
• —Research Personas: Generalist, Market Analyst, Software Architect, Scientific Reviewer, Product Manager, or News Editor -- each shapes source selection and analysis style.
• —Local Knowledge (RAG): Upload PDFs/TXT files through the dashboard or place them in ./knowledge_base. Indexed with SQLite cache and ChromaDB vector search.
• —Fact-Check Layer: Evaluation node scans the synthesis for dubious claims and flags them as warnings in the report — no re-plan loops, no garbage propagation. Skipped entirely for Quick depth.
• —Cross-Session Memory: Past research is stored in a ChromaDB collection (session_memory). New queries automatically retrieve and cite relevant findings from previous sessions, avoiding redundant re-investigation.
• —Report Metadata: Every report includes an automatic word count and estimated reading time.
• —Export Center: One-click reports in PDF, Word, Markdown, and HTML, saved to ./reports/.
• —MCP Server: Exposes the agent as a tool via the Model Context Protocol (JSON-RPC over stdio) for use with Claude Desktop, Continue, Cline, and other MCP clients.
• —Configurable Depth: Quick (2 results/source), Standard (5), or Deep (10).
• —Multilingual: Auto-expands queries to English for global academic/technical coverage.
• —UI Language Switcher: Toggle the dashboard between English and Spanish with one click (🇪🇸/🇬🇧 buttons in the sidebar).
• —Cloud LLM Support: Works with Groq, Google Gemini, OpenAI, or any OpenAI-compatible API — no local Ollama required. Set OPENAI_API_KEY + OLLAMA_BASE_URL in .env.

Architecture

graph TD
    Start((Start)) --> Init[initialize_state]
    Init --> Plan[plan_research]
    Plan --> Parallel[parallel_search]

    subgraph ThreadPoolExecutor
        Parallel --> Web[Web / Tavily]
        Parallel --> Wiki[Wikipedia]
        Parallel --> Arxiv[arXiv]
        Parallel --> Scholar[Semantic Scholar]
        Parallel --> GH[GitHub]
        Parallel --> HN[Hacker News]
        Parallel --> SO[Stack Overflow]
        Parallel --> Reddit[Reddit]
        Parallel --> YT[YouTube search + summarize]
        Parallel --> RAG[Local RAG]
    end

    Web & Wiki & Arxiv & Scholar & GH & HN & SO & Reddit & YT & RAG --> Synth[consolidate_research]
    Synth --> Eval[evaluate_research]
    Eval --> Report[generate_report]
    Report --> Email[send_email]
    Email --> DB[save_db]
    DB --> End((End))

Flow: initialize_state → plan_research → parallel_search → consolidate_research → evaluate_research → generate_report → send_email → save_db

Sample Output

Research topic: "Graph neural networks emerging use cases" — Standard depth, Scientific Reviewer persona

Industry Applications and Success Stories

Graph Neural Networks (GNNs) are rapidly gaining traction in industries that rely on complex, interconnected data. A notable example is Google Maps, which leverages GNNs to improve arrival time predictions by analysing traffic patterns, road networks, and real-time events. In healthcare, GNNs are used for drug discovery — molecular structures represented as graphs to predict compound-protein interactions. In finance, GNNs detect fraud by analysing transaction networks for anomalous patterns.

Technical Challenges and Scalability

Sparse computations pose challenges for hardware optimisation, as traditional GPUs are not designed for irregular data structures. Recent research proposes three strategies: CPU-GPU hybrid training, graph-augmented MLPs for real-time inference, and quantisation-aware training to reduce computational cost.

Integration with Knowledge Graphs and LLMs

LLMs can automate KG creation by extracting relationships from unstructured text, which are then fed into GNNs for downstream tasks like recommendation systems or semantic search — particularly valuable in supply chain optimisation.

[Full report: 1,200 words · 12 cited sources · exported as PDF, Word, Markdown]

Quick Start

Zero-config (batteries included)

No Ollama, no API keys, no .env file needed. Docker only.

git clone https://github.com/RobertoDeLaCamara/Research-Agent.git
cd Research-Agent
docker compose -f docker-compose.full.yml up

Open http://localhost:8501. The first run pulls a ~1 GB model and may take a few minutes — subsequent starts are instant.

Want a guided setup instead? Run bash scripts/quickstart.sh — it asks which LLM backend and model size you want, optionally adds API keys, then launches everything.

Option B — Bring your own Ollama

If you already have Ollama running locally:

ollama pull qwen2.5:1.5b   # or any model you prefer
cp env.example .env         # defaults work out of the box
docker compose up -d

Option C — Use OpenAI (or any compatible API)

cp env.example .env
# Edit .env: set OPENAI_API_KEY and point OLLAMA_BASE_URL to https://api.openai.com/v1
docker compose up -d

Works with any OpenAI-compatible endpoint: LM Studio, Together AI, Groq, Ollama, etc.

No API keys required for web search — the agent falls back to DuckDuckGo automatically. Add a free Tavily key (TAVILY_API_KEY) for better results.

Local Installation (no Docker)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp env.example .env   # edit OLLAMA_BASE_URL if Ollama is not on localhost
streamlit run src/app.py

📁 Knowledge Base (RAG)

You can include your own documents in the research:

Option 1: UI Upload

1. 1.Enable "Incluir base de conocimientos local" in the sidebar.
2. 2.Upload PDFs or TXT files directly through the dashboard.

Option 2: Manual Folder (For large datasets)

1. 1.Copy your PDF/TXT files to the ./knowledge_base folder in the project root.
2. 2.Enable "Incluir base de conocimientos local" in the sidebar.
3. 3.The agent will automatically detect and index these files.

📄 Output & Reports

All generated reports are automatically saved to the ./reports/ directory.

• —reporte_final.html (Interactive)
• —reporte_investigacion.pdf (Print-ready)
• —reporte_final.docx (Editable)
• —reporte_[topic].md (Raw content)

Research-Agent/
├── src/
│   ├── app.py                  # Streamlit UI entry point
│   ├── main.py                 # CLI entry point (python -m src.main)
│   ├── agent.py                # LangGraph workflow definition (8 nodes)
│   ├── state.py                # AgentState schema
│   ├── config.py               # Settings (Pydantic v2)
│   ├── validators.py           # Input validation
│   ├── db_manager.py           # SQLite session persistence
│   ├── llm.py                  # LLM factory (Ollama / OpenAI-compatible)
│   ├── i18n.py                 # Spanish / English UI strings
│   └── tools/
│       ├── parallel_tools.py   # ThreadPoolExecutor parallel search
│       ├── research_tools.py   # Web, Wiki, arXiv, Scholar, GitHub, HN, SO
│       ├── reddit_tools.py     # Reddit search
│       ├── youtube_tools.py    # YouTube transcript search + summarize
│       ├── rag_tools.py        # Local knowledge ingestion
│       ├── vector_store.py     # ChromaDB + all-MiniLM-L6-v2 embeddings
│       ├── router_tools.py     # plan_research, evaluate_research, personas
│       ├── synthesis_tools.py  # Consolidation + persona prompts + dedup
│       ├── reporting_tools.py  # PDF / Word / Markdown / HTML + word count
│       ├── chat_tools.py       # Interactive Q&A on findings
│       └── translation_tools.py # Multilingual query expansion
├── mcp_server.py               # MCP server (JSON-RPC/stdio) for external clients
├── knowledge_base/             # User-uploaded documents (PDF/TXT)
├── reports/                    # Generated research reports
├── data/
│   ├── chroma_db/              # ChromaDB vector store (RAG)
│   └── session_memory/         # Cross-session memory (past research)
├── docs/                       # Architecture, Security, Deployment, Troubleshooting
├── wiki/                       # Internal developer wiki
├── tests/                      # pytest suite
├── docker-compose.yml          # Minimal (bring your own Ollama)
├── docker-compose.full.yml     # Batteries-included (Ollama + model pre-pull)
├── Dockerfile                  # Python 3.12 slim, Streamlit on port 7860
├── env.example                 # Config template
└── requirements.txt

Configuration

See env.example for the full list.

Documentation

License

MIT -- see LICENSE.