A powerful AI research assistant that provides comprehensive research summaries by querying internal documents and web resources, powered by local Ollama models. Built for privacy and flexibility with no external API dependencies.

• Local LLM Integration: Runs entirely locally using Ollama - no API keys or cloud services required.
• Intelligent Research Planning: Creates structured research plans based on your queries.
• Web Search Capabilities: Searches and extracts relevant information from web sources.
• Document Management:
  • Index and search through local documents using vector embeddings
  • Support for multiple file types including PDFs and text files
  • Robust error handling and content extraction
• Knowledge Storage:
  • Save research summaries with meaningful filenames based on queries
  • View and manage your collection of saved summaries
  • Organized in YAML frontmatter format with metadata
• Interactive Experience:
  • Command-line interface with rich output formatting
  • Interactive mode for continuous research sessions
  • Support for dry-run preview of research plans

• Python 3.10 or higher
• Ollama installed and running
• At least one Ollama model pulled (e.g., ollama pull gemma3:latest)
• An Ollama embedding model (e.g., ollama pull nomic-embed-text)

1. Clone the repository:

   git clone https://github.com/l1v0n1/ResearchGPT.git
   cd ResearchGPT

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Set up environment variables:

   cp .env.example .env
   # Edit .env with your specific configuration

You can run ResearchGPT using our pre-built Docker images:

# Pull the lightweight version (recommended for most users)
docker pull ghcr.io/l1v0n1/researchgpt:lite
# Run the container, connecting to Ollama on the host machine
docker run --rm -it -e OLLAMA_BASE_URL=https://host.docker.internal:11434 ghcr.io/l1v0n1/researchgpt:lite

Several Dockerfile variants are available:

1. Lightweight version (recommended):

   docker build -t researchgpt:lite -f Dockerfile.lite .

2. Alpine version (full features, smaller image):

   docker build -t researchgpt:alpine -f Dockerfile .

3. Debian version (full features, better compatibility):

   docker build -t researchgpt:debian -f Dockerfile.debian .

When running the Docker container, you need to tell it how to reach Ollama:

# For macOS/Windows (Docker Desktop)
docker run --rm -it -e OLLAMA_BASE_URL=https://host.docker.internal:11434 researchgpt:lite
# For Linux
docker run --rm -it -e OLLAMA_BASE_URL=https://172.17.0.1:11434 researchgpt:lite
# OR use host networking
docker run --rm -it --network=host -e OLLAMA_BASE_URL=https://localhost:11434 researchgpt:lite

Mount volumes to persist data between container runs:

docker run --rm -it \
  -v ./data:/app/data \
  -e OLLAMA_BASE_URL=https://host.docker.internal:11434 \
  researchgpt:lite

Run a research query and get a comprehensive summary:

python -m app.cli "What are the latest advancements in quantum computing?"

When you run a query, the agent first creates a research plan:

Then it executes the plan and provides a comprehensive summary:

Start an interactive session for multiple queries and document management:

python -m app.cli --interactive

Index a document for future reference:

python -m app.cli --index-document path/to/document.pdf

List all indexed documents:

python -m app.cli --list-documents

Index all documents in a directory:

python -m app.cli --index-directory path/to/documents/

List all saved research summaries:

python -m app.cli --list-summaries

View a specific summary:

python -m app.cli --view-summary filename.md

Research summaries are saved in Markdown format with YAML frontmatter metadata:

---
title: Research Summary
query: "tell me latest news about space"
date: 2025-04-19 16:32:58
---
Okay, here's a comprehensive summary of the latest space news as of April 19, 2025:
**Latest Space News (April 19, 2025)**
Several significant developments are currently underway in the space sector:
* **SpinLaunch Progress:** Continuing its innovative approach to rocket launches
* **Artemis 2 Mission Updates:** NASA's ongoing preparations and scientific goals
* **Starship Developments:** SpaceX's ambitious spacecraft progress
* **NASA's "Origins Uncertain: 'Skull Hill' Rock":** Discovery and analysis of a unique rock formation
...

ResearchGPT/
├── agent/                # Core AI agent components
│   ├── config.py         # Configuration settings
│   ├── model.py          # Ollama wrapper
│   ├── memory.py         # Knowledge storage
│   ├── planner.py        # Research planning module
│   ├── executor.py       # Plan execution engine
│   ├── logger.py         # Logging utilities
│   └── tools/            # Research tools
│       ├── web.py        # Web search functionality
│       └── documents.py  # Document retrieval and indexing
├── app/                  # User interfaces
│   └── cli.py            # Command-line interface
├── data/                 # Data storage
│   ├── documents/        # Indexed document storage
│   └── summaries/        # Saved research summaries
├── logs/                 # Application logs
├── tests/                # Testing suite
├── docs/                 # Documentation
│   ├── summary.md        # Detailed implementation overview
│   └── checklist.md      # Feature implementation status
├── requirements.txt      # Project dependencies
└── README.md             # Project documentation

For more detailed information about the project, check out the documentation files:

• Implementation Summary - Provides a comprehensive overview of the architecture, components, and design principles of the ResearchGPT system
• Implementation Checklist - A detailed checklist tracking the implementation status of all features and components

This project is licensed under the MIT License - see the LICENSE file for details.

This project includes utilities to configure and test web search capabilities:

• Domain Configuration: Control which domains are allowed for web scraping
• Google Search API Setup: Configure and test your Google Search API credentials
• Search Testing: Test functionality with various domains and queries

Usage information can be found in the utils/README.md file.

# Example: List currently allowed domains
python utils/configure_domains.py --list
# Example: Configure Google Search API
python utils/configure_google_api.py --show