Deep Research Agent

Multi-step graph research pipeline with Chainlit chat UI, orchestrated with LangGraph. Features semantic memory via Chroma with Human-in-the-Loop (HITL) curation, session persistence via PostgreSQL, and full observability via LangSmith.

Inference powered by Mercury 2 (Inception Labs) — a state-of-the-art diffusion LLM.

---

Architecture

User Message (Chainlit)
↓
START → Orchestrator — Classifies intent via LLM
↓
Router — Routes to retriever, researcher, or writer based on intent
↓
┌─────────────────────────────────────────────┐
│ Retriever — Chroma vector store query │
│ ├── HIT (score < 0.3) → Writer │
│ └── MISS → Researcher │
│ │
│ Researcher — Tavily search + extract │
│ └── Writer │
└─────────────────────────────────────────────┘
↓
Writer — Generates Markdown report via LLM (with HITL middleware)
↓
END → Response streamed to Chainlit UI

State

Field	Type	Description
messages	list[BaseMessage]	Chat history (MessagesState)
intent	Literal	"conversation", "simple_search", "quick_search", "deep_research"
research_mode	Literal	"new", "existing", "quick"
query	str	Research query from user
topic	str	Search topic context ("general", "news", "finance")
retrieved_docs	list[Document]	Chroma results (add_docs reducer)
cache_hit	bool	Whether Chroma returned relevant context (< 0.3 score)
search_results	list[dict]	Tavily results (add_docs reducer)
final_report	str	Generated report
save_to_chroma	bool	HITL decision flag

Project Structure

deep_research_agent/
├── src/
│ ├── main.py → Chainlit entry point (chat UI)
│ ├── graph.py → StateGraph compilation
│ └── utils/
│ ├── state.py → ResearchState (shared state + reducers)
│ ├── nodes.py → orchestrator, retriever, researcher, writer
│ ├── tools.py → Tavily search/extract, Chroma query/save
│ ├── prompts.py → LangSmith Hub prompt retrieval
│ └── vectorstore.py → Chroma singleton
├── tests/ → pytest unit tests
├── chainlit.md → Chainlit welcome screen
├── langgraph.json → LangGraph CLI configuration
├── pyproject.toml → Dependencies (uv)
└── .env → Environment variables

Stack

• UI: Chainlit (chat interface with streaming + auth)
• Orchestration: LangGraph (StateGraph)
• LLM: Mercury 2 (Inception Labs)
• Search: Tavily (search + extract)
• Memory: Chroma (vector store) + PostgreSQL (checkpointing)
• Observability: LangSmith

Setup

# Install dependencies
uv sync
# Configure environment (.env)
INCEPTION_API_KEY=your_key # Mercury 2 LLM
TAVILY_API_KEY=your_key # Web search
LANGSMITH_API_KEY=your_key # Observability
LANGGRAPH_DATABASE_URL=postgresql://user:pass@localhost:5432/db # Session persistence
ADMIN_USER=your_admin_user # Chainlit auth
ADMIN_PASS=your_admin_pass # Chainlit auth
CHAINLIT_AUTH_SECRET=your_secret # Chainlit session encryption# Run with Chainlit (recommended)
chainlit run src/main.py
# Or run with LangGraph CLI
langgraph dev

Then open:

• Chainlit: http://localhost:8000 (with auth)
• LangGraph Studio: https://smith.langchain.com/studio → point to http://127.0.0.1:2024

Running Tests

pytest # Run all tests
pytest -v # Verbose

Environment Variables

Variable	Required	Description
INCEPTION_API_KEY	Yes	Mercury 2 API key from Inception Labs
TAVILY_API_KEY	Yes	Tavily API key for web search
LANGSMITH_API_KEY	No	LangSmith for observability/tracing
LANGGRAPH_DATABASE_URL	Yes	PostgreSQL connection for session persistence
ADMIN_USER	Yes	Chainlit admin username
ADMIN_PASS	Yes	Chainlit admin password
CHAINLIT_AUTH_SECRET	Yes	Secret for Chainlit session encryption