by juanjuandog
AI equity research agent with resilient workflows, Redis Lua single-flight, pgvector RAG, versioned reports, evidence tracing, and RAG evaluation.
# Add to your Claude Code skills
git clone https://github.com/juanjuandog/FinSight-AI
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.

Most RAG demos stop at "retrieve chunks and ask an LLM." FinSight focuses on the parts that make an AI research system dependable:
| 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 |
No comments yet. Be the first to share your thoughts!
createIfAbsentcontextHashdataSnapshotHashreportVersionflowchart LR
UI["Dashboard / REST API"] --> Backend["Spring Boot Backend"]
Backend --> Workflow["Agent Workflow Orchestrator"]
Workflow --> MQ["RabbitMQ Async Queue"]
Workflow --> Redis["Redis Lua Lease + Cache"]
Workflow --> PG["PostgreSQL + pgvector"]
Backend --> AI["FastAPI AI Service / Ollama fallback"]
PG --> Retrieval["Hybrid Retrieval + Evidence"]
Retrieval --> Backend
AI --> Report["Versioned AI Report"]
Report --> PG
Backend --> Eval["RAG / Agent Evaluation"]
More detail: Architecture Notes
./scripts/run-full-stack.sh
Then open:
open http://localhost:8080
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.
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:
| Signal | Example Result |
| --- | --- |
| Agent workflow | 1/1 tasks, 0 failed/dead-letter |
| RAG evaluation | 85 / 100, 2/3 cases passed |
| Evidence index | 6 documents, 6 chunks for 600519 |
| Intelligence graph | 20 events, 36 entities, 47 relations |
| Report cache | dataSnapshotHash + contextHash + reportVersion |
For a lightweight local backend using in-memory repositories:
cd backend
mvn spring-boot:run
open http://localhost:8080
backend: Spring Boot service for APIs, domain workflow, metrics, and RAG orchestration.ai-service: FastAPI service for document parsing, entity extraction, embedding, rerank, and answer generation stubs.docker: local infrastructure placeholders.Backend:
cd backend
mvn spring-boot:run
Dashboard:
open http://localhost:8080
Backend with PostgreSQL profile:
docker compose up -d postgres
cd backend
mvn spring-boot:run -Dspring-boot.run.profiles=postgres,prod
Backend with PostgreSQL + RabbitMQ workflow:
./scripts/run-backend-workflow.sh
Production-like stack with PostgreSQL, pgvector, RabbitMQ, FastAPI AI service, Actuator, and the dashboard:
./scripts/run-full-stack.sh
open http://localhost:8080
AI service:
cd ai-service
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8001
Optional local Ollama analysis:
ollama serve
ollama pull qwen2.5:7b
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.
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
The PostgreSQL implementation is enabled by postgres,prod profiles. Flyway creates the core schema:
companiesfinancial_documentsfinancial_statementsfinancial_metricsrisk_signalsworkflow_taskscompany_eventsrag_tracesstock_analysis_reportsuser_watchlistsDefault profile still uses in-memory repositories so the backend remains easy to run without Docker.
The workflow stage splits long financial data processing into task lifecycle and execution:
WorkflowTask stores idempotency key, status, agent stage, attempt count, payload, error message, lease owner, fencing token, and update time.WorkflowTaskPublisher has two implementations:
rabbitmq profile.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.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.Run:
./scripts/run-backend-workflow.sh
./scripts/demo-workflow.sh
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.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=现金流风险
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