📖 Project Overview

Modern internet research often requires manually browsing dozens of tabs, validating conflicting sources, and compiling scattered notes into structured summaries. This project solves that workflow bottleneck by introducing an autonomous multi-step research loop that runs entirely on local hardware.

Designed with a modular architecture, the system accepts a natural language research prompt, decomposes it into multiple targeted research questions, queries live search engines, fetches and cleans the target webpage contents, summarizes the evidence, detects conflicts between sources, and compiles a comprehensive, fully-cited Markdown report.

Key Architectural Workflow

                     ┌──────────────────┐
                     │     React UI     │
                     └────────┬─────────┘
                              │ Server-Sent Events / REST
                              ▼
                     ┌──────────────────┐
                     │   FastAPI API    │
                     └────────┬─────────┘
                              │
                              ▼
                  ┌──────────────────────┐
                  │ ResearchOrchestrator │
                  └──────────┬───────────┘
                             │
      ┌──────────────────────┼──────────────────────┐
      ▼                      ▼                      ▼
┌──────────┐          ┌──────────────┐       ┌──────────────┐
│ Planner  │          │ Fetcher &    │       │ Findings &   │
│ & Query  │          │ Extractor    │       │ Conflict     │
│ Generator│          │ (BS4 + HTTPx)│       │ Detector     │
└────┬─────┘          └──────┬───────┘       └──────┬───────┘
     │                       │                      │
     ▼                       ▼                      ▼
┌──────────────┐      ┌──────────────┐       ┌──────────────┐
│ Search Engine│      │ Summarizer & │       │ Report       │
│ (DuckDuckGo) │      │ LLM (Ollama) │       │ Synthesizer  │
└──────────────┘      └──────────────┘       └──────────────┘

🛠️ Technology Stack

This project is built using a modern, decoupled stack engineered for speed, clean dependency management, and high developer velocity.

Backend (Python Service)

Web Framework: FastAPI – Asynchronous python framework handling research session management and progress streaming.
Database & ORM: SQLite with SQLAlchemy – Persistent local store for research logs, source metadata, and historical reports.
Environment Management: uv – Next-generation Python package manager for ultra-fast, reproducible builds.
Search & Fetching: duckduckgo-search API & BeautifulSoup4 – Lightweight live query resolution and secure DOM parsing.
Validation: Pydantic v2 – Runtime configuration management and safe URL restriction schemas (restricting localhost/private subnet fetches).

Frontend (React App)

Core Framework: React 18 & TypeScript – Robust type safety and component-driven user interface.
Build Tool: Vite – Fast development server and optimized production bundler.
State Management: TanStack React Query v5 – Highly optimized asynchronous caching and server state syncing.
Routing: React Router v6 – Client-side view routing (History, Details, Settings, Dashboard).
Icons: Lucide React – Clean, modern vector icon set.

AI Infrastructure

Local Inference: Ollama – Local LLM hosting. Defaults to highly efficient open models like qwen3:8b or llama3.

✨ Features & Capabilities

Customizable Research Depth: Adjust query counts, target model configurations, and minimum depth parameters on a per-session basis.
Server-Sent Events (SSE): Get real-time status updates, current-step logging, and streaming report updates pushed straight to the UI.
Local LLM Integration: Use offline models via Ollama's local abstraction layer, ensuring full data privacy.
Source Conflict Detection: Detect discrepancies between different articles automatically before writing findings.
Safe URL Parsing: Prevents server-side request forgery (SSRF) by blocking internal network fetches.
Interactive Citation UI: Rendered reports include hoverable source chips linking directly back to the original source web pages.
Mock Execution Mode: Run tests and demo instances instantly without internet connections or LLM setups using mock research streams.

🚀 Installation & Setup

Prerequisites

Node.js v20 or higher
Python v3.12 or higher
uv package manager

1. Backend Configuration

Clone the repository, configure the environment variables, and start the FastAPI service:

# Navigate to backend directory
cd backend

# Initialize virtual environment and sync dependencies using uv
uv venv
uv sync

# Configure your environment
cp .env.example .env

# Start the development server
uv run uvicorn app.main:app --reload

Note: The default .env.example file configures RESEARCH_MOCK_MODE=true to enable instant offline testing. Set RESEARCH_MOCK_MODE=false for active web searches and local LLM execution.

2. Frontend Configuration

Start the Vite development server to launch the user interface:

# Navigate to frontend directory
cd ../frontend

# Install dependencies
npm install

# Start the Vite development server
npm run dev

Open http://localhost:5173 in your browser.

3. Ollama Setup (For Local LLM Execution)

If running in live mode, start your local Ollama server and pull your preferred model:

# Start the Ollama background service
ollama serve

# Pull your default model (e.g., qwen3:8b or llama3)
ollama pull qwen3:8b

Here are direct structural insights about how the Autonomous AI Research Agent operates:

How does the agent validate facts and avoid hallucinating?

The agent runs an active citation verification step. When compiling findings, it cross-references assertions against extracted content blocks. If a fact cannot be traced back to an indexable, fetched URL source, it will fail validation or will be flagged as an unverified claim.

What are the main benefits of local-first research over commercial alternatives?

Data Privacy: Zero data leaves your computer when using Ollama for summarization and reports.
No API Costs: Running search engines locally via DuckDuckGo and models via Ollama eliminates subscription fee requirements.
Offline Support: Using the pre-cached SQLite history database and Mock execution mode, the application can demonstrate, preview, and test features completely offline.

How is database state managed?

All research logs, planned query pathways, and finished Markdown reports are stored locally in a relational SQLite file (research_agent.db). Database tables are managed declaratively using SQLAlchemy ORM schemas, allowing for painless database migrations or scaling up to PostgreSQL in the future.

Autonomous AI Research Agent | Python Project

Project Screenshots

Project Description