graph.py
Supervisor Graph
The supervisor is the orchestration layer. It manages the conversation, chooses tools, merges outputs, and decides whether the final answer is safe to return.
- Compresses long conversation history.
- Checks semantic memory and follow-up context.
- Routes out-of-scope, direct-answer, clarification, retrieval, and news paths.
- Runs retrieval and news agents in parallel when needed.
- Calls the calculator only when arithmetic is required.
- Applies guardrails before final output.
agents/retrieval_agent.py
Retrieval Subgraph
The retrieval subgraph is the evidence pipeline. It turns the query into company-specific searches, retrieves documents, filters them, drafts an answer, and validates grounding.
- Rewrites query text into retrieval keywords.
- Fans out one branch per target company.
- Combines BM25 and ChromaDB results.
- Deduplicates and grades retrieved chunks.
- Synthesizes from graded annual-report excerpts.
- Retries missing or weak company coverage up to two times.
Boundary: the supervisor passes query, messages, and semantic_context into the retrieval subgraph. The retrieval subgraph returns retrieval_result. The supervisor then aggregates that result with news or calculation outputs before final answer synthesis.
What stays outside retrieval?
- Out-of-scope refusal.
- Clarification questions.
- Recent news search.
- Arithmetic calculations.
- Final citation formatting and chart extraction.
What belongs inside retrieval?
- Company-specific retrieval planning.
- BM25/vector hybrid search.
- Document deduplication.
- Financial relevance grading.
- Draft groundedness checks.
- Partial company retry behavior.