How yzyazid8-web/ledger-agent works
ledger-agent is a traceable financial-report assistant for U.S. annual and quarterly filings. Users submit a question through the Next.js interface; the API streams agent steps and returns a sourced answer or abstention. The agent gathers filing passages and typed XBRL facts, may calculate from cited inputs, and verifies numerical claims before responding. Separate ingestion and evaluation branches support the product. The graph reflects README-described capabilities where implementation excerpts were unavailable; those links cite the README rather than implying unsampled code was inspected.
Main entry points: react.py ReAct agent · nodes.py Agent workflow nodes · retrieval Hybrid filing search · toolbox.py Tool dispatch
Components 24
Data ingestion
- Filing and XBRL ingestion
backend/src/ledger_agent/ingestion
Evidence retrieval
- Typed fact store
backend/src/ledger_agent/tools/financial_facts.py - Hybrid filing search
backend/src/ledger_agent/retrieval - Query filters
backend/src/ledger_agent/retrieval/query_analysis.py - Filter relaxation
backend/src/ledger_agent/retrieval/fallback.py
Agent reasoning
- Filing search tool
backend/src/ledger_agent/tools/search_filings.py - ReAct agent
backend/src/ledger_agent/agent/react.py - Fixed-step agent
backend/src/ledger_agent/agent/graph.py - Agent workflow nodes
backend/src/ledger_agent/agent/nodes.py - Tool dispatch
backend/src/ledger_agent/agent/toolbox.py - Safe calculator
backend/src/ledger_agent/tools/calculator.py - Answer verification
backend/src/ledger_agent/agent/verify.py - Answer and trace format
backend/src/ledger_agent/pipeline.py
User interface
- Question interface
frontend/app/page.tsx - API client
frontend/lib/api.ts - API proxy
frontend/app/api/[...path]/route.ts - FastAPI routes
backend/src/ledger_agent/api/main.py - Agent service
backend/src/ledger_agent/api/service.py - Trace and evidence views
frontend/components/AgentTrace.tsx
Evaluation
- Evaluation harness
backend/src/ledger_agent/evaluation - Naive RAG baseline
backend/src/ledger_agent/baselines/naive_rag.py
Other components
- Analyst
- SEC EDGAR
- LLM provider
Connections 32
- Analyst → Question interface: asks
- Question interface → API client: submits question
frontend/app/page.tsx - API client → API proxy: sends request
frontend/lib/api.ts - API proxy → FastAPI routes: forwards request
- FastAPI routes → Agent service: routes to
backend/src/ledger_agent/api/main.py - Agent service → ReAct agent: streams steps
backend/src/ledger_agent/api/service.py - ReAct agent → Answer and trace format: formats answer
backend/src/ledger_agent/agent/react.py - Agent service → Hybrid filing search: builds retriever
backend/src/ledger_agent/api/service.py - Agent service → Fixed-step agent: builds agent
backend/src/ledger_agent/api/service.py - Filing and XBRL ingestion → SEC EDGAR: fetches filings
- Filing and XBRL ingestion → Typed fact store: loads XBRL facts
- Filing and XBRL ingestion → Hybrid filing search: indexes chunks
backend/src/ledger_agent/retrieval/query_analysis.py - ReAct agent → LLM provider: requests tool choices
- ReAct agent → Tool dispatch: dispatches tools
backend/src/ledger_agent/agent/react.py - Tool dispatch → Filing search tool: executes search
- Tool dispatch → Typed fact store: reads facts
- Tool dispatch → Safe calculator: evaluates calculation
- Filing search tool → Hybrid filing search: searches passages
backend/src/ledger_agent/tools/search_filings.py - Hybrid filing search → Query filters: extracts query entities
backend/src/ledger_agent/retrieval/query_analysis.py - Filing search tool → Filter relaxation: relaxes filters
backend/src/ledger_agent/tools/search_filings.py - Fixed-step agent → Agent workflow nodes: runs workflow
backend/src/ledger_agent/agent/graph.py - Agent workflow nodes → Filing search tool: gathers passages
backend/src/ledger_agent/agent/nodes.py - Agent workflow nodes → Typed fact store: looks up facts
backend/src/ledger_agent/agent/nodes.py - Agent workflow nodes → Safe calculator: calculates values
backend/src/ledger_agent/agent/nodes.py - Agent workflow nodes → Answer verification: checks answer
backend/src/ledger_agent/agent/nodes.py - ReAct agent → Answer verification: checks citations
backend/src/ledger_agent/agent/react.py - FastAPI routes → Question interface: streams answer
- Question interface → Trace and evidence views: renders steps
frontend/app/page.tsx - Evaluation harness → ReAct agent: evaluates configurations
backend/src/ledger_agent/evaluation/components.py - Evaluation harness → Naive RAG baseline: compares baseline
backend/src/ledger_agent/evaluation/components.py - Naive RAG baseline → Hybrid filing search: searches context
backend/src/ledger_agent/baselines/naive_rag.py - Naive RAG baseline → LLM provider: generates answer
backend/src/ledger_agent/baselines/naive_rag.py