FinSight AI: a Java reference for recoverable, evidence-grounded equity research agents

The problem FinSight AI is actually aimed at

Most LLM research demos fail in the same three places. A long task dies halfway and there is no state to resume from. Two identical requests both run, doubling the model bill. A cached answer survives a data update and quietly goes stale. FinSight AI is built around those failure modes rather than around prompt quality.

The README states the goal plainly: turn market data, financial metrics, filings and company events into structured research that "can be inspected and reproduced." The audience is narrower than the phrase equity research suggests. This is an A-share workspace, so the instrument universe is Chinese listed companies, and the project describes itself as a research aid whose output "is not investment advice." The second audience is Java engineers who want a working example of recoverable agent orchestration. The two overlap in the repository, but they are not the same reader.

How the workflow, lease and snapshot mechanisms fit together

The architecture splits ownership. A Spring Boot service holds domain state and orchestration; a FastAPI sidecar holds everything that faces a model. The README argues this boundary keeps workflow recovery and report consistency independent of the model runtime, which is a defensible reason to run two processes instead of one.

A request creates an idempotent task. RabbitMQ then dispatches five named stages: data ingestion, metric calculation, indexing, intelligence building and report generation. Redis does the duplicate suppression, and the implementation is more specific than a cache check. The README names a Redis Lua single-flight lease plus a fencing token, in RedisBackedWorkflowLeaseService. A fencing token matters because a lease can expire while the original holder is still working; without the token, the stale holder can write after a new one has taken over. Recovery is handled by WorkflowOrchestrator with explicit task states, retries, timeout takeover and dead-letter handling.

Report consistency comes from three fields: dataSnapshotHash, contextHash and reportVersion, set in StockAiAnalysisService. The report is bound to the state of its inputs, so a changed snapshot produces a different hash rather than a silently reused answer. Retrieval is hybrid. HybridRetrievalGateway combines full-text and vector recall, fuses the two result lists with reciprocal-rank fusion, then reranks. PostgreSQL with pgvector stores snapshots, vectors, evidence and reports. The final report keeps its version, snapshot hash, model source and evidence trace, which is what makes the evidence path inspectable after the fact rather than only during generation.

Installing FinSight AI and running a first research request

There are two documented paths, and the choice changes what you are evaluating. The lightweight preview runs with Java 17 and Maven against local in-memory adapters and needs no infrastructure services. Clone the repository and start the backend from the backend directory:

cd FinSight-AI/backend
mvn spring-boot:run

Open http://localhost:8080. The README positions this mode for UI review, code reading and interview demos, so expect the product surface without the durable workflow machinery.

The full stack is Docker Compose. It brings up PostgreSQL with pgvector, Redis, RabbitMQ, the Spring Boot backend and the FastAPI AI sidecar together:

docker compose up -d --build
./scripts/quick-demo.sh

The README says the default demo requires no API key. Ollama is the default local provider, and .env.example sets OLLAMA_BASE_URL to http://host.docker.internal:11434 with OLLAMA_MODEL set to qwen2.5:7b. The sidecar also carries adapters for OpenAI-compatible endpoints and the Anthropic Messages API, configured through OPENAI_COMPATIBLE_BASE_URL, OPENAI_COMPATIBLE_MODEL, OPENAI_COMPATIBLE_API_KEY, ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY. Leave the cloud keys blank until you intend to use a provider, as the file itself instructs.

One operational number to plan around: the README asks for roughly 8 GB of free memory for the complete Compose stack. Compose also wires FINSIGHT_AI_SERVICE_URL to http://ai-service:8001 and sets SPRING_PROFILES_ACTIVE to postgres,rabbitmq,redis,prod for the backend container. For profiles, environment variables, service URLs and recovery steps, the README points to docs/troubleshooting.md rather than reproducing them.

Deterministic fallbacks, and what they hide from you

The README states that if a selected model is unavailable or unconfigured, deterministic fallbacks keep the flow runnable. That is a sensible choice for a demo and a questionable one for evaluation. A pipeline that always completes tells you nothing about whether the model path works, and a fallback answer can be mistaken for a generated one unless you check the model source recorded on the report.

The report does record that source, along with the evidence trace and snapshot hash, so the information needed to tell the two apart is present. The burden is on the operator to look. Anyone benchmarking output quality against this stack should confirm which provider actually served each report before drawing conclusions, because the default configuration will happily produce a complete run without one.

Where FinSight AI is the wrong tool

It is not a market data vendor. The ingestion stage consumes market data, financial metrics, filings and company events, but the repository does not present itself as the origin of that data, and the README does not document a data licensing arrangement. If your requirement is a reliable, licensed feed, this project sits downstream of that requirement, not on top of it.

The scope is A-share. Nothing in the README claims coverage of US or European listings, and the workspaces are described around A-share companies. A team researching US equities is looking at the wrong instrument universe.

It is also not a trading system, and the README says so directly. The output is a structured conclusion with confidence, supporting factors and risk factors. There is no order routing, no position management and no execution path described.

Finally, the full stack is a five-service deployment with a message broker, a cache, a vector database and a Python sidecar. For a single analyst who wants to ask a model about one filing, that is a large amount of operational surface for the task. The lightweight mode exists for exactly that reason, but it drops the workflow recovery and retrieval behaviour that make the project interesting in the first place.

How this differs from a LangChain or Python-first agent stack

The obvious alternative for an LLM research pipeline is a Python-first framework such as LangChain, where orchestration, retrieval and model calls live in one process and one language. The difference here is not the feature list; it is where the durability boundary sits.

In FinSight AI, the orchestration layer is Java with Spring Boot, JDBC and Flyway, and the model-facing layer is a separate FastAPI service. Task state, idempotency and report versioning are owned by the Java side, so they survive a model provider swap, a sidecar restart or a change of embedding model. A Python-first stack typically keeps orchestration in the same process as the model calls, which makes provider swaps and partial-failure recovery a refactor rather than a configuration change.

The cost is real. You maintain two runtimes, two dependency trees and a network hop between them, and a Java engineer cannot read the retrieval or generation code without also reading Python. Choose FinSight AI's shape when recoverability and reproducibility are the hard requirements. Choose a single-language stack when iteration speed on the prompt and retrieval side matters more, and you are willing to rebuild the durability layer later.

Licence, maintenance and the upgrade surface

The repository is MIT licensed, with the LICENSE file at the top level and a licence badge in the README. MIT is permissive: it allows commercial use and modification and requires that the copyright notice and permission notice be preserved. It provides no patent grant and no warranty. That is a general description of the licence text, not advice about your situation; read LICENSE and the notices of the bundled dependencies before shipping anything.

The repository is not archived, and the last push was on 2026-09-02. That is recent enough that the project is not dormant, but the repository publishes no releases, so there is no version tag to pin against. You would be tracking the master branch, and the README links a CI workflow on that branch.

The upgrade surface is the part to weigh. The stack pins Spring Boot 3.3.5 and Java 17, and it depends on PostgreSQL with pgvector, Redis, RabbitMQ and a Python sidecar. Each of those moves on its own schedule, and the sidecar's provider adapters track three external model APIs whose request formats change. The README directs configuration and recovery questions to docs/troubleshooting.md, which suggests the project expects operators to tune profiles and environment variables rather than to run a fixed image. Budget for that maintenance, or run the lightweight mode and treat the full stack as a reference to read.

Editorial conclusion

Adopt FinSight AI if you are building or reviewing a long-running AI workflow in Java and want to see idempotency keys, Redis single-flight leases, snapshot hashes and an evidence trace wired together in one codebase; the lightweight Maven path makes that reading possible without infrastructure. Do not adopt it as a market data feed, a trading system or a source of investment advice, and do not expect it to work without a model provider or the documented deterministic fallbacks. Before committing, verify three things against the repository itself: that the lightweight profile runs on your Java 17 and Maven versions, that your machine has the roughly 8 GB of free memory the README asks for alongside the full Compose stack, and that the A-share data sources the ingestion stages depend on are reachable from your network.

Frequently asked questions

Official sources

1. Issues
2. juanjuandog/FinSight-AI on GitHub
3. License: MIT
4. README