Open-source AI equity research agent with evidence-grounded reports, resilient workflow orchestration, and RAG evaluation.
FinSight turns filings, financial reports, research notes, market data, and company events into source-grounded answers and versioned AI research reports. The project is intentionally backend-heavy: it shows how to build the infrastructure around an AI agent, not just how to call a model.
Why It Exists
Most RAG demos stop at "retrieve chunks and ask an LLM." FinSight focuses on the parts that make an AI research system dependable:
long-running agent workflows with explicit state transitions;
idempotent task submission and duplicate execution control;
Redis Lua single-flight leases with fencing tokens;
report caching tied to data snapshots instead of loose prompt strings;
PostgreSQL/pgvector hybrid retrieval with evidence traceability;
RAG and agent quality evaluation for regression checks.
Highlights
| Area | What FinSight Implements |
| --- | --- |
| Agent workflow | Data ingestion, metric recalculation, document indexing, intelligence build, and AI report generation as recoverable stages |
| Concurrency control | Idempotency keys, repository-level , Redis Lua single-flight lease, fencing token, local fallback lock |
| Failure recovery | Task status machine, stage tracking, retry, dead letter state, timeout takeover scheduler |
| Trustworthy AI cache | , , , Redis/PostgreSQL-backed report reuse |
| Retrieval | PostgreSQL JSONB, full-text search, pgvector embeddings, hybrid recall, deduped evidence chunks |
| Evaluation | RAG hit rate, evidence coverage, answer coverage, hallucination risk, conclusion consistency, confidence calibration, latency |
| Demo surface | Spring Boot API, static dashboard, sample data flow, Actuator and Prometheus metrics |
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
This starts the backend, dashboard, PostgreSQL/pgvector, RabbitMQ, Redis, the FastAPI AI sidecar, and supporting infrastructure. If Ollama is not running, the AI service returns deterministic fallback analysis so the demo still works.
2. Seed and exercise the demo
In another terminal:
./scripts/quick-demo.sh
Or run the smaller flows separately:
./scripts/demo-flow.sh
./scripts/demo-workflow.sh
Useful endpoints:
GET /api/workflows/summary
POST /api/evaluations/rag/run
GET /api/companies/600519/ai-analysis/latest
GET /api/document-index/600519/search?q=现金流风险
Example demo output after ./scripts/quick-demo.sh:
The FastAPI sidecar calls OLLAMA_BASE_URL (http://localhost:11434 by default) and OLLAMA_MODEL
(qwen2.5:7b by default) from /analyze-stock. If Ollama is not installed, not running, or the model is
missing, the endpoint returns a deterministic rule-based fallback with aiGenerated=false, so the dashboard
keeps working.
Sample API Flow
POST /api/ingestion/demo seeds a sample company document and financial statements.
POST /api/metrics/recalculate/600519 calculates financial indicators and risk signals.
POST /api/analysis/ask asks a source-grounded question.
POST /api/document-index/{symbol}/rebuild rebuilds document chunks for retrieval.
POST /api/intelligence/{symbol}/rebuild builds timeline events and a lightweight knowledge graph.
Async workflow:
POST /api/ingestion/demo/async
GET /api/workflows
GET /api/document-index/600519/search?q=现金流风险
GET /api/metrics/600519/runs
GET /api/intelligence/600519/timeline
GET /api/intelligence/600519/graph
POST /api/evaluations/rag/run
Database Stage
The PostgreSQL implementation is enabled by postgres,prod profiles. Flyway creates the core schema:
companies
financial_documents
financial_statements
financial_metrics
risk_signals
workflow_tasks
company_events
rag_traces
stock_analysis_reports
user_watchlists
Default profile still uses in-memory repositories so the backend remains easy to run without Docker.
Workflow Stage
The workflow stage splits long financial data processing into task lifecycle and execution:
WorkflowOrchestrator uses Redis Lua single-flight leases, idempotency keys, and local fallback locking to prevent duplicate cross-node execution.
WorkflowRecoveryScheduler scans timed-out RUNNING tasks, marks them recoverable/dead-lettered, and republishes retryable work.
Agent stages model the long-running research flow from ingestion to metrics, indexing, intelligence build, AI analysis, success, failure, and recovery.
DOCUMENT_INDEX_BUILD chunks ingested documents and writes retrieval-ready evidence chunks.
COMPANY_INTELLIGENCE_BUILD turns documents, metrics, and risk signals into timeline events and graph relations.
STOCK_AI_ANALYSIS creates source-grounded AI stock reports and persists them for history and caching.
RabbitWorkflowListener consumes messages and moves failed messages to a dead-letter queue when RabbitMQ rejects them.
The retrieval stage indexes financial documents at evidence-chunk granularity:
DocumentChunker splits long documents with overlap and section metadata.
EmbeddingService creates deterministic 384-dimensional embeddings for local demos, and can call the FastAPI AI sidecar /embed endpoint when finsight.ai-service.enabled=true.
DocumentChunkRepository supports keyword search, vector search, and chunk replacement.
PostgreSQL profile stores chunks in document_chunks with JSONB metadata, full-text GIN index, and pgvector cosine index.
HybridRetrievalGateway merges keyword and vector channels, deduplicates chunks, and passes source-bound evidence to RAG.
Useful endpoints:
POST /api/document-index/600519/rebuild
GET /api/document-index/600519/count
GET /api/document-index/600519/search?q=现金流风险
Metric Engine Stage
The metric engine stage turns hard-coded ratios into a governed calculation pipeline:
MetricDefinitionCatalog defines source metrics, ratio metrics, year-over-year metrics, and derived spreads.
CoreFinancialMetricCalculator evaluates metrics in fiscal-year order and stores results with a plan version.
MetricCalculationRun records each calculation run with statement count, me
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
