Evidence-grounded equity research with recoverable workflows, snapshot-bound reports, and hybrid RAG.
Turn market data, financial metrics, filings, and company events into structured AI research that can be inspected and reproduced.
简体中文 · Architecture · API · Quick Start
FinSight AI is an open-source A-share research workspace and a backend engineering reference for reliable AI agents. It does more than call a model: long-running research tasks are recoverable, duplicate executions are controlled, reports are bound to data snapshots, and generated conclusions retain an inspectable evidence path.
FinSight is a research aid, not an automated trading system. Its output is not investment advice.
The interface separates each research activity into a dedicated workspace instead of placing every diagnostic on one dashboard.
| Workspace | Purpose |
|---|---|
| Company Research | Search an A-share company and inspect its quote, historical close-price curve, and key financial metrics |
| AI Analysis | Generate a structured conclusion with confidence, supporting factors, and risk factors |
| Evidence | Search filings, announcements, and structured metrics for verifiable source material |
| Recent Events | Review disclosures, metric changes, and risk signals on a company timeline |
| Watchlist | Keep a concise list of companies for continued research |
| Engineering problem | FinSight approach | Implementation |
|---|---|---|
| Long-running AI tasks fail halfway | Recoverable stages, explicit task states, retries, timeout takeover, and dead-letter handling | WorkflowOrchestrator |
| Identical requests amplify expensive work | Idempotency keys plus a Redis Lua single-flight lease and fencing token | RedisBackedWorkflowLeaseService |
| A cached report becomes stale when data changes | dataSnapshotHash, contextHash, and reportVersion bind a report to its source state |
StockAiAnalysisService |
| RAG answers are difficult to verify | Full-text and vector recall, reciprocal-rank fusion, reranking, evidence trace, and regression evaluation | HybridRetrievalGateway |
| Model infrastructure changes independently | Embedding, reranking, and generation run behind a FastAPI sidecar with deterministic fallbacks | ai-service |
- A research request creates an idempotent task.
- RabbitMQ dispatches data ingestion, metric calculation, indexing, intelligence building, and report generation.
- Redis coordinates duplicate work while PostgreSQL/pgvector stores snapshots, vectors, evidence, and reports.
- Hybrid retrieval supplies reranked evidence to the AI sidecar.
- The final report preserves its version, snapshot hash, model source, and evidence trace.
Use this path to inspect the product and core flow with Java 17 and Maven. It runs with local in-memory adapters and does not require infrastructure services.
git clone https://github.com/juanjuandog/FinSight-AI.git
cd FinSight-AI/backend
mvn spring-boot:runOpen http://localhost:8080.
Use Docker Compose to run PostgreSQL/pgvector, Redis, RabbitMQ, the Spring Boot backend, and the FastAPI AI sidecar together.
git clone https://github.com/juanjuandog/FinSight-AI.git
cd FinSight-AI
docker compose up -d --build
./scripts/quick-demo.shThe default demo requires no API key. Ollama is optional; deterministic fallbacks keep the flow runnable when a local model is unavailable. Allow roughly 8 GB of free memory for the complete Compose stack.
| Mode | Best for | Runtime |
|---|---|---|
| Lightweight | UI review, code reading, and interview demos | Java 17, Maven |
| Full stack | Workflow recovery, Redis coordination, pgvector retrieval, and AI sidecar integration | Docker Compose |
For profiles, environment variables, service URLs, and recovery steps, see Troubleshooting.
flowchart LR
UI["Research Workspaces"] --> API["Spring Boot API"]
API --> WF["Workflow Orchestrator"]
WF --> MQ["RabbitMQ"]
WF --> Lease["Redis Lease & Cache"]
WF --> DB["PostgreSQL / pgvector"]
API --> Retrieval["FTS + Vector + RRF"]
Retrieval --> DB
Retrieval --> Sidecar["FastAPI: Embed · Rerank · Generate"]
Sidecar -. optional .-> Ollama["Ollama"]
Sidecar --> Report["Snapshot-bound Report"]
Report --> DB
API --> Eval["RAG Evaluation"]
Eval --> Retrieval
The Spring Boot service owns domain state and orchestration. The Python sidecar owns model-facing operations. This boundary keeps workflow recovery and report consistency independent from the chosen model runtime.
Read the architecture notes for the complete request, state, and data flows.
| Layer | Stack |
|---|---|
| Core API | Java 17, Spring Boot 3.3.5, JDBC, Flyway |
| Workflow | RabbitMQ, task state machine, retry and dead-letter recovery |
| Coordination | Redis, Lua leases, fencing tokens, snapshot-aware cache |
| Retrieval | PostgreSQL JSONB, full-text search, pgvector, RRF, reranking |
| AI runtime | FastAPI, sentence embeddings, cross-encoder reranking, optional Ollama |
| Product UI | Responsive HTML, CSS, and JavaScript served by Spring Boot |
| Operations | Docker Compose, Actuator, Prometheus, GitHub Actions |
backend/ Spring Boot API, workflow, retrieval, metrics, and static UI
ai-service/ FastAPI embedding, reranking, and generation sidecar
scripts/ Demo, verification, benchmark, and screenshot workflows
docs/ Architecture, API, benchmark, product, and interview notes
docker-compose.yml
CI protects the main branch with:
- Maven unit and integration tests, including Testcontainers-backed infrastructure tests;
- shell-script syntax checks;
- Python service and benchmark-script syntax checks.
Run the backend suite locally:
cd backend
mvn test- Architecture
- Research API
- Agent Workflow Design
- Benchmark and Evaluation
- Product Requirements
- Troubleshooting
- Roadmap
- Contributing
FinSight currently targets A-share research and local, production-like demonstrations. Authentication, regulated research workflows, trade execution, portfolio advice, and multi-market coverage are outside the current scope.
Released under the MIT License.