AutoResearch

AutoResearch is an agentic research system for complex technical work. It is built to take a high-level research objective, decompose it into tractable questions, retrieve evidence from papers and the web, synthesize a structured brief, and keep the execution trace inspectable.

The current repository is the Phase 1 MVP: a working end-to-end research loop with an API, async worker, browser UI, memory layer, retrieval connectors, evidence extraction, and report generation.

What It Does

• Accepts a research topic and optional goal
• Builds a research plan with questions, search queries, and report sections
• Searches web and scholar sources
• Fetches documents and extracts structured evidence cards
• Synthesizes a cited markdown report
• Tracks task events, sources, and outputs through a single task record

Why This Project Exists

Most "research agents" either stop at search + summarization or rely on brittle prompt chains that drift off-topic on long, noisy tasks. AutoResearch is being built to support a stronger workflow:

• broad exploration across multiple directions
• system-level optimization thinking
• explicit evidence grounding
• continuous iteration and trajectory tracking
• production-oriented engineering constraints

The long-term goal is a competition-grade AutoResearch system that can support serious algorithmic and systems optimization work, not just generate surface-level summaries.

Current Architecture

flowchart LR
    A["Research Task"] --> B["Planner"]
    B --> C["Retrieval"]
    C --> D["Document Fetch + Normalize"]
    D --> E["Evidence Extraction"]
    E --> F["Section Drafting"]
    F --> G["Critic / Final Report"]
    G --> H["Task Bundle"]

    I["Codex exec / GPT"] -.-> B
    I -.-> E
    I -.-> F
    I -.-> G

    J["SQLite Memory"] --- B
    J --- C
    J --- E
    J --- G

Loading

Main Modules

• packages/agent-core: planning, orchestration, LLM routing, task understanding
• packages/connectors: web search, scholar search, content fetch
• packages/memory: persistence, normalization, repository layer
• packages/paper-rag: evidence extraction and citation preparation
• packages/report-engine: outline generation, draft assembly, critic pass
• apps/api: FastAPI service
• services/worker: async research worker
• apps/web: Next.js control panel
• tests/evals: end-to-end and regression tests

Repository Layout

apps/
  api/
  web/
docs/
infra/
packages/
  agent-core/
  connectors/
  memory/
  paper-rag/
  report-engine/
  shared-schemas/
services/
  worker/
tests/
  evals/

Research Brain Providers

AutoResearch currently supports three execution modes:

1. codex exec using your logged-in ChatGPT / Codex allowance
2. OpenAI Responses API
3. heuristic fallback pipeline

The default priority is:

Codex exec -> OpenAI API -> heuristic fallback

This means the system can already run a real LLM-backed research loop even if you only want to use ChatGPT Pro / Codex quota first.

Phase 1 Scope

Phase 1 is intentionally narrow. It focuses on one outcome:

Given a technical topic, produce a structured, evidence-backed, traceable research brief.

Phase 1 does not yet include:

• autonomous experiment execution
• leaderboard submission agents
• long-horizon memory over many research cycles
• multi-user permissions and team workflows
• online learning or automated production rollout

Quickstart

1. Create the Python environment

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e .[dev]

2. Start the API

.\.venv\Scripts\python.exe -m uvicorn autoresearch.api.main:app --host 127.0.0.1 --port 8000

3. Start the worker

.\.venv\Scripts\python.exe -m autoresearch.worker.main --poll-interval 1

4. Start the web app

Set-Location apps\web
npm install
npm run dev

Local URLs

• API: http://127.0.0.1:8000
• Web UI: http://127.0.0.1:3000

LLM / Codex Setup

Option A: Use Codex via ChatGPT login

codex --version
codex login status

If codex login status shows a valid login, AutoResearch will prefer codex exec automatically.

Option B: Use OpenAI API

$env:OPENAI_API_KEY='your-api-key'
$env:AUTORESEARCH_OPENAI_FAST_MODEL='gpt-5.4-mini'
$env:AUTORESEARCH_OPENAI_QUALITY_MODEL='gpt-5.4'

Disable Codex and force fallback

$env:AUTORESEARCH_DISABLE_CODEX_EXEC='1'

Additional environment examples are available in .env.example.

API Endpoints

Health

GET /health

Create a research task

POST /tasks
Content-Type: application/json

{
  "topic": "Optimize a large-scale recommender ranking system under strict production constraints",
  "goal": "Produce a decision-ready research brief with hypotheses and experiment roadmap."
}

Fetch the full task bundle

GET /tasks/{task_id}

Returns:

• task status and current stage
• research plan
• event timeline
• source list
• final report

Stream task events

GET /tasks/{task_id}/events/stream

Example Workflow

1. Submit a topic from the UI or API
2. Worker claims the queued task
3. Planner builds questions and search queries
4. Retrieval gathers sources from web and scholar connectors
5. Evidence extraction produces evidence cards and citations
6. Report engine drafts and critiques the final markdown report
7. UI shows events, sources, and report preview

Eval and Regression Tests

.\.venv\Scripts\python.exe -m pytest -q

Current eval coverage includes:

• end-to-end pipeline execution
• LLM path smoke coverage
• complex task normalization
• off-domain retrieval filtering regression

Run the complex-task suite:

.\.venv\Scripts\python.exe tests\evals\run_complex_suite.py

It saves timestamped summaries to data/evals/.../summary.json so each iteration can be compared against the previous baseline.

Docs

• System Plan
• Target Architecture
• MVP Architecture
• Phase 1 Module Checklist

Current Status

Implemented:

• FastAPI backend
• worker-driven task execution
• SQLite-backed task memory
• web and scholar retrieval connectors
• Codex / GPT-backed planning and synthesis path
• structured report generation
• regression tests for task normalization and source filtering

In progress:

• stronger source quality policy
• cleaner content extraction from noisy webpages
• higher-quality hypothesis portfolio and experiment roadmap generation
• trajectory tracking across repeated research cycles

Roadmap

• Phase 1.5: better source ranking, stronger report templates, richer evals
• Phase 2: experiment planning, exploit/explore tracking, hypothesis portfolio management
• Phase 3: implementation agents, experiment runners, trajectory memory, competition loop

Notes

• The repo currently targets local development on Windows first, but the Python backend is structured to be portable.
• data/, virtual environments, and generated artifacts are intentionally excluded from version control.
• No license file has been added yet.