SYNTHESIS

A multi-agent autonomous research system. Given a complex research question, SYNTHESIS plans, searches, reads, criticizes, and synthesizes a grounded report with citations.

Architecture

User Query
    │
    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          Orchestrator                                │
│                                                                       │
│   PLANNER ──▶ RETRIEVER ──▶ READER ──▶ CRITIC ──▶ SYNTHESIZER       │
│       │                                                    │         │
│       └──────────────── re-plan on critic rejection ───────┘         │
└─────────────────────────────────────────────────────────────────────┘
         │                │                  │
         ▼                ▼                  ▼
    arXiv API    Semantic Scholar     RAG Assistant
                                     (existing portfolio project)
                                             │
                                             ▼
                                         DISTILL
                                    (fine-tuned extractor)

Cross-cutting:
  ┌───────────────────────────────────────────────────────────┐
  │  Trajectory Log  │  Redis Scratchpad  │  Token Budget     │
  │     (Postgres)   │  (short-term mem)  │  + Step Watchdog  │
  └───────────────────────────────────────────────────────────┘
  ┌───────────────────────────────────────────────────────────┐
  │  Long-term Episodic Memory (Postgres + pgvector)          │
  │  Hallucination Guard │ Cost Tracker │ Eval Harness        │
  └───────────────────────────────────────────────────────────┘
  ┌───────────────────────────────────────────────────────────┐
  │  Next.js Trace Viewer  (custom LangSmith-style UI)        │
  └───────────────────────────────────────────────────────────┘

Why a custom framework?

SYNTHESIS is built from scratch before optionally porting to LangGraph. The reason is the same as implementing backprop before using PyTorch: the abstractions hide invariants you need to debug real failures. After building it, you understand exactly what LangGraph's graph execution engine, checkpointing, and streaming layers do — and you can make an informed choice about whether to use it.

Stack

Layer	Technology
API	FastAPI (async)
Database	Postgres 16 + pgvector
Cache / Scratchpad	Redis 7
LLM providers	OpenAI, Anthropic (abstracted)
Migrations	Alembic
Observability	structlog, custom trajectory tables
Trace viewer	Next.js (session 24)

Quickstart

# 1. Start infrastructure
docker compose up -d

# 2. Install Python deps
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 3. Configure environment
cp .env.example .env
# edit .env — add your OPENAI_API_KEY or ANTHROPIC_API_KEY

# 4. Run migrations
alembic upgrade head

# 5. Start the API
uvicorn synthesis.api.main:app --reload

# 6. Run tests
pytest

Session Build Log

Session	Deliverable	Status
1	Project scaffold, FastAPI skeleton, Postgres schema, Docker Compose	✓
2	Agent base class, Pydantic models
3	Tool abstraction, stub tools
4	LLM client wrapper (OpenAI + Anthropic)
5	Redis short-term memory
6	Trajectory logging
7	Token budget + step limit controllers
8	arXiv API tool
9	Semantic Scholar API tool
10	RAG assistant wrapper tool
11	PLANNER agent
12	Planner eval
13	RETRIEVER agent
14	Retriever eval
15	READER agent + DISTILL integration
16	Reader eval
17	CRITIC agent
18	SYNTHESIZER agent
19	Orchestrator
20	End-to-end smoke test
21	Long-term episodic memory
22	Hallucination guard
23	Cost tracker
24	Next.js trace viewer
25	Agent benchmark dataset (50 questions)
26	LLM-as-judge eval pipeline
27	Failure mode analysis
28	FastAPI streaming endpoint (SSE)
29	Production polish
30	Mock interview