FinSight-AI: Recoverable Workflows and Snapshot-Bound Reports for A-Share Research

The failure mode FinSight-AI was built around

Most LLM research demos break in a predictable place. A request starts, half the pipeline runs, a model call times out, and the user is left with a partial report and no way to tell which inputs produced it. FinSight-AI treats that as the primary engineering problem rather than an edge case. The README frames the project as a backend reference for reliable AI agents, and the named components back that up: a WorkflowOrchestrator, a Redis-backed lease service, and a report model keyed by dataSnapshotHash, contextHash, and reportVersion. The intended user is a Java engineer building a research product who wants to see how recoverable stages, duplicate suppression, and provenance are implemented in one codebase. The secondary audience is anyone evaluating an A-share research tool, since the workspace covers quotes, financial metrics, filings, announcements, and a company event timeline. What it is not, per its own disclaimer, is a trading system: the README states plainly that the output is not investment advice.

How a research request moves through the stack

The architecture diagram in the README shows two processes with a deliberate split. The Spring Boot service owns domain state and orchestration; the FastAPI sidecar owns everything model-facing (embedding, reranking, generation). A request first creates an idempotent task. RabbitMQ then dispatches the stages listed in the README: data ingestion, metric calculation, indexing, intelligence building, and report generation. Redis coordinates duplicate work, and PostgreSQL with pgvector stores snapshots, vectors, evidence, and reports. Retrieval runs in the Spring Boot process against the database, combining full-text search and vector recall with reciprocal-rank fusion, then reranking, before the reranked evidence is handed to the sidecar. The final report records its version, snapshot hash, model source, and evidence trace. That last step is the point of the whole arrangement: a reader can inspect which source material supported a conclusion, and a cache entry can be invalidated when the underlying data changes rather than when a timer expires.

Two ways to run it, and what each one proves

The README documents a lightweight path and a full path. The lightweight path needs only Java 17 and Maven: clone the repository, change into the backend directory, and run mvn spring-boot:run, then open http://localhost:8080. According to the README, this mode uses local in-memory adapters and requires no infrastructure services, which makes it suitable for reading the UI and core flow. The full path uses Docker Compose to bring up PostgreSQL with pgvector, Redis, RabbitMQ, the Spring Boot backend, and the FastAPI sidecar, followed by ./scripts/quick-demo.sh. The README states the default demo needs no API key, that Ollama is the default local provider, and that the sidecar also has adapters for OpenAI-compatible APIs and Anthropic. It also gives a concrete resource figure: allow roughly 8 GB of free memory for the complete Compose stack. That number is the honest signal about which mode you are actually choosing. The lightweight profile exercises the domain model and the UI; the Compose profile is the only one that exercises leases, message dispatch, vector retrieval, and the sidecar boundary.

The snapshot hash is a real constraint, not just a cache key

Binding a report to dataSnapshotHash and reportVersion solves staleness, but it changes how you work with reports. A report is not a living document that improves as new filings arrive. It is a record of what the system knew at one point, and a new filing produces a new version rather than an update to the old one. For audit and reproducibility that is the right call. For a product where users expect a company page to reflect today's numbers, it means the application layer has to decide when to regenerate and how to present the difference between versions. The README does not describe a diff view or a version comparison UI, so that presentation work is left to whoever builds on top. The same applies to contextHash: it captures the retrieval context that fed generation, which is what makes an evaluation run reproducible, but it also means any change to the retrieval configuration invalidates prior comparisons unless you record the configuration alongside the hash.

Hybrid retrieval and the evaluation loop

The retrieval path is more specific than the phrase RAG usually implies. Full-text recall and vector recall run separately, their results are merged with reciprocal-rank fusion, and a reranking step runs before evidence reaches the generation model. The evaluation component sits on the same path: the diagram shows RAG Evaluation reading from retrieval, and the repository topics include llm-evaluation, so the intent is regression testing of retrieval quality rather than one-off spot checks. This is the part of the project most worth reading if you already run a RAG system, because the fusion and rerank stages are where most implementations quietly degrade. The README does not publish retrieval metrics, a labeled evaluation set size, or baseline numbers, so you cannot judge retrieval quality from the documentation alone. You would need to run the evaluation harness against your own corpus to learn anything about accuracy.

Where the data model stops

FinSight-AI is explicitly an A-share research workspace. The Company Research workspace searches an A-share company and shows its quote, historical close-price curve, and key financial metrics; the Evidence workspace searches filings, announcements, and structured metrics. Nothing in the supplied material describes adapters for other markets, other filing formats, or other disclosure calendars. If your target is US equities, European listings, or crypto, the ingestion and evidence layers are the wrong shape and you would be replacing them rather than configuring them. The provider layer is the opposite: it is deliberately pluggable, with Ollama as the default and OpenAI-compatible and Anthropic adapters available. So the model runtime is portable and the data model is not. That asymmetry is the single most important thing to check before adopting the project.

The fallback design and its honest trade-off

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 production, and the project does not pretend otherwise. A deterministic fallback means the pipeline completes and the report is written, but the generated text is not model output. If your application cannot distinguish a fallback report from a generated one, you will eventually ship a conclusion that no model produced. The material does not describe a flag, a status field, or a marker that surfaces which path was taken, although the report does record its model source, which is the field to check. Anyone building on this should confirm how model source is populated on the fallback path before trusting a report in an automated downstream step. This is a design detail worth reading in the code rather than the README.

A different approach: a Python RAG framework plus your own orchestration

The obvious alternative is to assemble the same capability from a Python retrieval framework and a workflow library, keeping everything in one language. The difference in approach is where the guarantees live. In that arrangement, idempotency, retries, and snapshot binding are conventions you implement in application code, and the retrieval library handles chunking, embedding, and search. FinSight-AI instead puts the guarantees in named Java components with a lease service that uses a Redis Lua single-flight pattern and fencing tokens, and treats the model runtime as a replaceable sidecar behind an HTTP boundary. The trade is real in both directions: the Python route gives you a larger ecosystem of retrieval components and one deployment artifact, while FinSight-AI gives you a typed orchestration layer and a report model that records provenance by construction. If your team is Java-first and the reproducibility requirement is contractual rather than aspirational, the second shape is easier to defend in review.

Maintenance cost, licence, and what to verify first

The licence is MIT, which permits commercial use and modification with the copyright notice retained; this is a factual note about the licence text, not legal advice, and you should read the LICENSE file for the operative terms. The maintenance cost is dominated by the service count. Five components (Spring Boot, FastAPI, PostgreSQL with pgvector, Redis, RabbitMQ) plus a local model runtime mean five upgrade paths and a Compose file that has to stay coherent. Flyway migrations indicate the schema is versioned, so database changes are tracked, but there are no published releases in the supplied material, which makes it harder to pin a version and read a changelog before upgrading. Verify the lightweight Maven profile starts without external services, check that the ai-service fallback path marks its output as fallback, and read the Flyway migrations to see whether the A-share schema can absorb your own entity types. If those three checks pass, the orchestration code is worth reading even if you never deploy the full stack.

Editorial conclusion

Adopt FinSight-AI if you are building an A-share research tool and want the orchestration patterns (idempotency keys, Redis single-flight leases, snapshot hashes, evidence traces) as working Java code you can read. Do not adopt it as a general-purpose RAG framework or as a multi-market product; the data model is A-share specific and the retrieval path is wired to filings and announcements. Before committing, verify three things in the repository: that the lightweight Maven profile really runs without infrastructure, that the deterministic fallbacks in ai-service produce usable text when Ollama is absent, and that the Flyway migrations match the schema your own data would need.

Official sources

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