Agentic Research Workspace.

Overview

Single-tenant MVP that proves the core loop: ask a question about your own documents, get a grounded answer — every claim traceable to a retrieved chunk, progress streamed in a fixed stage vocabulary.

Key focus areas:

• Citation-backed RAG: HyDE → dense pgvector (1024d) + PostgreSQL FTS → RRF → Cohere rerank-v3 → cite chunks at retrieval time
• Agentic orchestration: LangGraph Research Agent (ReAct, ≤5 iters, 60k token / 60s caps) over a retrieve_evidence tool
• Async ingestion: upload returns immediately; arq worker does extract → Chonkie chunk → Cohere embed → Postgres in background
• Model Gateway: every LLM call via LiteLLM complete / complete_with_tools (Groq → OpenRouter fallback, swappable without touching agent code)

Impact & Results

Features

Low-Level: Ingestion

Request path (sync)
├── POST /api/ingestion/upload → write B2 + insert documents/ingestion_jobs (queued) → enqueue arq → return {document_id, job_id}
 
Worker path (async, off HTTP)
├── arq Worker picks job (same Render container, max_jobs=4)
├── Extract by source_type (Docling / whisper / tree-sitter)
├── Chonkie SemanticChunker / CodeChunker → tsvector per chunk
├── Cohere embed-english-v3.0 batch (hash fallback only in dev)
└── INSERT chunks (text + vector(1024) + tsv GIN) → stage=done

Low-Level: Research (ask → cited answer)

Client (TanStack AI useChat)
├── POST /api/research/chat {question, threadId} — opens SSE (AG-UI)
└── Renders stages + [n] markers → CUSTOM citations → final answer markdown
 
Server — LangGraph StateGraph
├── entry → planner (cheap model, 1-3 queries, fallback [question]) → researcher ⇄ loop (≤5)
│   └── synthesize → END (per specs/research-pipeline.md)
├── Researcher ReAct: thought → retrieve_evidence → observation (bounded by 60k tokens / 60s / 30s per-call)
└── Budget caps: MAX_ITERATIONS=5, AGENT_TOKEN_BUDGET=60k, AGENT_RUN_TIMEOUT=60s
 
Retrieval
├── HyDE via Model Gateway → hybrid dense+FTS (same Postgres table, RRF) → Cohere rerank-v3
└── Workspace pre-filter — no cross-workspace leakage

Data Model

Postgres (Neon) — authoritative
├── users / workspaces (workspace_id allowlist on every retrieval)
├── documents + ingestion_jobs (queued → extracting → chunking → embedding → done/failed)
├── chunks (text + embedding vector(1024) + tsv generated + GIN index + source_ref + document_id)
└── research_runs + citations (answer + [n] → chunk_id FK, persisted before streaming)

Key Architectural Decisions

Why pgvector in Postgres (not Pinecone/Turbovec)?

Single table holds chunks.text + embedding + tsv. No sync job, no rebuild. FTS ts_rank_cd + dense cosine merged by RRF in SQL. See ADR-002 addendum — Turbovec removed.

Why LangGraph?

Stateful StateGraph gives retrieve_evidence tool loop with checkpoint-ready shape (PostgresSaver planned, ADR-001). Adding Planner/Critic later is additive (nodes, not new agents).

Why LiteLLM Gateway?

ADR-003 thin interface complete / complete_with_tools. Groq primary (speed/free tier), OpenRouter fallback. Swap via env, no agent diff.

Why arq + Redis?

Ingestion is N4 async by spec — upload must return in ms. arq with rediss:// (Upstash TLS) keeps HTTP fast, worker in same Render container (max_jobs=4, free tier sleeps on idle).

Trade-offs

Pros

• Single source of truth: one Postgres for metadata, vectors, FTS — ops simple
• Grounded by construction: citation-at-retrieval prevents post-hoc fabrication
• Bounded cost: iteration/token/time caps + fixed stage vocab → predictable UX & spend

Cons

• Single-node agent: no Planner decomposition yet — multi-hop needs specs/research-pipeline.md planner node (cheap model, fallback [question])
• No Critic loop: deferred per PRD non-goals until golden dataset shows need
• Free-tier cold start: one Render service sleeps on idle; no keep-warm cron

Technical Challenges

API Reference

Reliability & Observability

Lessons Learned

• Groundedness is a data contract, not a prompt trick — citations must ride with retrieval, not be asked for after.
• One authoritative store beats two synced ones — pgvector + tsv in Postgres removed an entire sync/rebuild class.
• Bound the agent before improving it — caps + fixed stage vocab made the MVP shippable; Critic/Planner wait on golden eval data (docs/specs/evaluation.md).
• Gateway abstraction pays off — Groq → OpenRouter swap is env-only; agent code never branches on provider.

Screenshots

Expand

AG-UI Streaming + Citations

Expand

Research Workspace