FinSight AI

English | 简体中文

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.

Product Walkthrough

FinSight includes a runnable institutional research console. The UI is not just a decoration for the backend: it exposes the research workflow, report cache, evidence trace, RAG evaluation, and financial signals that the backend produces.

Market Research Workspace

• Search a company symbol and inspect quote status, price trend, moving averages, volume, and AI thesis in one workspace.
• The chart uses real market history when available and deterministic fallback data for offline demos, so the project remains easy to run in interviews.
• The AI brief summarizes rating, confidence, positive points, and risk points instead of returning an unstructured chat answer.

Agent Workflow And Report Trust

• The console surfaces the research task state machine: creation, ingestion, metric calculation, indexing, intelligence build, AI report generation, and completion.
• Each task exposes idempotency key, attempts, lease owner, and fencing-token fields, making the concurrency-control design visible instead of hidden in code.
• Report trace shows reportVersion, dataSnapshotHash, cache hit status, model source, generated time, and evidence chunks bound to the report.

Metrics, Risks, And Evidence

• Financial metrics are distilled into research-facing health cards such as profitability, growth, cash-flow quality, and debt ratio.
• Evidence search returns retrievable chunks from filings, announcements, and structured financial summaries.
• The same evidence layer powers RAG answers, report citations, hallucination-risk checks, and evaluation regression cases.

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

Architecture

flowchart 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

Documentation

• Architecture Notes
• Research API
• Agent Workflow Design
• Benchmark And Evaluation Notes
• Resume And Interview Notes
• GitHub Presentation Snippets
• Troubleshooting
• Roadmap
• Contributing

Quick Start

0. Prerequisites

docker --version
docker compose version

• Docker Engine with Docker Compose v2, such as Docker Desktop, OrbStack, Colima, or a Linux Docker daemon.
• 8 GB or more available memory is recommended for the full stack because Elasticsearch, PostgreSQL, RabbitMQ, Redis, MinIO, the Spring Boot backend, and the FastAPI sidecar run together.
• No secrets are required for the default local demo. Ollama is optional; without it, the AI sidecar returns deterministic rule-based analysis.

Optional non-Docker tooling:

• Java 17 and Maven 3.9+ for cd backend && mvn spring-boot:run.
• Python 3.12 for running ai-service directly.
• Ollama with qwen2.5:7b for local LLM-backed analysis.

1. Clone and run the full stack as a background service

git clone https://github.com/juanjuandog/FinSight-AI ~/work/FinSight-AI
cd ~/work/FinSight-AI
docker compose up -d --build

This starts the backend, dashboard, PostgreSQL/pgvector, RabbitMQ, Redis, the FastAPI AI sidecar, Elasticsearch, and MinIO in detached mode. The containers keep running after the terminal closes.

Check status and open the app:

docker compose ps
curl -fsS http://localhost:8080/actuator/health
curl -fsS http://localhost:8001/health
open http://localhost:8080

Service management:

docker compose logs -f backend
docker compose restart backend ai-service
docker compose stop
docker compose start
docker compose down

Published local URLs:

Default local credentials are defined in docker-compose.yml (finsight / finsight for PostgreSQL and RabbitMQ; finsight / finsight123 for MinIO).

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 signals after ./scripts/quick-demo.sh:

3. Run without Docker

For a lightweight local backend using in-memory repositories:

cd backend
mvn spring-boot:run
open http://localhost:8080

Modules

• 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.

Alternative Run Modes

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.

Local Configuration

The default Docker Compose setup does not require an .env file. Override these variables only when you need different local infrastructure or optional LLM behavior: