QuantMind: a typed knowledge pipeline for quantitative finance, built to be opened by an agent

What problem QuantMind solves, and for whom

Financial text arrives in incompatible shapes. An arXiv PDF has a page hierarchy and equations; a news item has a publication window and a source; a filing has sections and dates. If you feed all three into a retrieval index as raw strings, you lose the two things that matter downstream: where a claim came from, and when it was true. QuantMind's stated goal is to refine those sources into typed knowledge that downstream retrieval and reasoning can trust, where every piece carries its own text, an as_of timestamp and a light source ref, so it "persists and time-queries standalone."

The intended user is not an end investor. It is an engineer or researcher building refinement flows, and increasingly a coding agent working with a human behind it. The README is explicit that the repository is designed agent-oriented: you open the checkout, describe the pipeline you want, and an agent builds it against the repo's contracts, skills and deterministic verification. The same code is described as "a perfectly good importable Python library," so the two audiences are not mutually exclusive, but the framing tells you which one the project optimizes for.

How a source becomes a typed artifact

The pipeline has two halves, and the split is the design decision worth noticing. The first half is deterministic: fetch, parse, format and clean run with no model in the loop, so provenance is exact and replayable. The second half is the flow, where a model is involved and the output takes a typed shape.

Shapes are selected by config type, not by a runtime flag. The README gives the example of PaperStructureCfg producing a PaperStructureTree, described as a hierarchy of page-cited nodes, and PaperSemanticCfg producing a PaperSemanticResult, described as a page-aware chunk set plus one cited global summary. Flat cards exist for News, Earnings, Factor and Thesis; whole documents get a structure tree. Operations are config-driven: PaperFlow(cfg).build(input) binds an immutable build config once and applies it per input, collect_news collects a replayable source window, and batch_run fans any operation across a list of inputs. The README states you never write asyncio.gather boilerplate.

Retrieval sits above the artifacts in three layers. rag/ handles chunking plus BM25 or similarity search, library/ handles local persistence and meaning-based search, and mind/ is described as agentic, reasoning-based retrieval. The README says these together serve RAG and Agentic RAG, deep research and data-MCP serving. The README also notes the shipping surface is narrower than the diagram: PaperFlow and collect_news ship today, and the rest is on the roadmap.

Installing QuantMind and building a first paper artifact

The project uses uv for package management. The README gives the library path as a virtual environment plus an editable install from the checkout:

uv venv && source .venv/bin/activate
uv pip install -e .

According to pyproject.toml the package is named quantmind, version 0.2.0, and requires Python 3.10 or newer, which is stricter than the 3.8+ badge in the README. Note also that pyproject.toml configures a Tsinghua PyPI mirror as the default uv index, so installs resolve against that mirror unless you change it.

Before running a flow, copy .env.example to .env. It declares OPENAI_API_KEY and LLAMA_CLOUD_API_KEY, plus settings such as QUANTMIND_DATA_DIR, QUANTMIND_TEMP_DIR, QUANTMIND_MAX_WORKERS, QUANTMIND_RETRY_ATTEMPTS, QUANTMIND_TIMEOUT and QUANTMIND_ARXIV_MAX_RESULTS.

cp .env.example .env

The first real use in the README is a structure tree over one arXiv paper. The cfg type chooses the knowledge shape, the identifier selects the document, and the result exposes an id and a node count:

import asyncio

from quantmind.configs import PaperStructureCfg
from quantmind.configs.paper import ArxivIdentifier
from quantmind.flows import PaperFlow


async def main() -> None:
    flow = PaperFlow(PaperStructureCfg(model="gpt-5.6-luna"))
    tree = await flow.build(ArxivIdentifier(id="1706.03762v7"))
    print(tree.id, len(tree.nodes))


asyncio.run(main())

What you should see is a printed tree identifier and a node count. The model string is passed straight into the config, so treat it as a value you must supply rather than one the package guarantees.

The alternative entry point is the agent path, and the README recommends it. Clone the repository, start a coding agent inside it, and describe the pipeline in natural language:

git clone https://github.com/LLMQuant/quant-mind.git
cd quant-mind && claude      # or: codex

The README's example prompt asks for a source-first paper artifact for arXiv 1706.03762, persisted and then searched by summary. The agent is expected to read AGENTS.md, load the relevant contexts/ pages, write the pipeline, and run scripts/verify.sh before handing the change back.

The harness: contracts, contexts and a verify script

QuantMind's second claim is about the repository itself as the product surface, which the README calls harness engineering. The bet is stated plainly: a weak model in a good harness beats a strong model running bare.

The mechanics are concrete enough to evaluate. AGENTS.md and CLAUDE.md hold always-on rules in one place for every agent that opens the repo. contexts/ holds agent-facing pages with a Quick Summary and Contents preview so an agent loads only the page a task needs. A portable skill named quantmind-dev covers contributor setup, commit, PR and component workflow, mirrored for Claude and Codex. Shared hook scripts under .claude/ and .codex/ are meant to give both agents identical hard guarantees without maintaining two copies of a rule. Finally, scripts/verify.sh runs lint, types, import boundaries and tests, fast-failing in a fixed order, and CI runs the same script.

That last point is the one that makes the harness more than documentation. A verify script that CI also runs means a change either passes the same gate locally and remotely, or it does not. The constraint is that the guarantee is only as strong as the script's coverage, and the README does not state what the coverage floor is, only that pytest-cov backs it in the dev extra.

Where QuantMind is the wrong tool

The most important limitation is stated in the README itself: the target surface is broader than what ships. The diagram shows any source flowing into typed knowledge and applications, but the caption says the shipping surface is PaperFlow and collect_news, with the rest on the roadmap. If your pipeline depends on Earnings, Factor or Thesis cards, or on mind/ agentic retrieval, you are reading a plan, not a description of the checkout.

There is no release history to pin against. The project has no retrieved releases, and the README does not mention publishing to PyPI, so the install path is an editable clone. That means upgrades are git pulls against a moving master, and the README does not document rollback, version pinning or a migration path between artifact shapes. A typed artifact you persist today has no stated compatibility guarantee with the next commit.

The dependency list is also heavy for what the library path does. It pulls openai, openai-agents, litellm, llama-index-core, llama-index-retrievers-bm25, pymupdf, trafilatura, arxiv, pydantic and more, and the optional full extra adds marker-pdf, beautifulsoup4 and sentence-transformers. If you only want deterministic fetch and parse, you are installing a large model-serving stack to get it. And because the deterministic half is deliberately model-free while the flow half is not, reproducibility stops at the boundary: the README promises replayable preprocess and a replayable source window, not deterministic model output.

How this differs from a general RAG framework

A general-purpose RAG framework such as LlamaIndex, which QuantMind itself depends on through llama-index-core and llama-index-retrievers-bm25, starts from documents and ends at a retrieval index. The chunk is the unit of work, and metadata is whatever you attach.

QuantMind inverts that. The typed artifact is the unit of work, and retrieval is one consumer of it. A PaperStructureTree is a hierarchy of page-cited nodes, and a PaperSemanticResult is a page-aware chunk set plus a cited global summary. The artifact carries its own text, an as_of timestamp and a source ref, so it can be persisted, time-queried and re-indexed without re-parsing the source. That matters in finance specifically, where the same document read at two different dates should not return the same answer.

The second difference is the delivery mechanism. A RAG framework is a library you import into your application. QuantMind is a repository you open with an agent, where AGENTS.md, contexts/ and scripts/verify.sh constrain how the pipeline gets written. If you want a dependency you call from your own service, the first model fits better. If you want a workspace where an agent produces pipelines that pass a fixed gate, that is the case QuantMind is arguing for.

Licence, maintenance and what an upgrade costs

QuantMind is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. The repository ships a LICENSE file at the root, and the README links to the main branch copy. That is where the licence facts end; questions about your own redistribution obligations belong with counsel, not with this page.

On maintenance, the last push was on 2026-08-15, so the repository is not archived and has recent activity. There are no retrieved releases, so there is no tagged version to compare against and no changelog to read before pulling. The practical cost of an upgrade is therefore a diff review against master, plus a re-run of scripts/verify.sh to confirm the import boundaries and type checks still hold in your fork.

The dependency surface is the larger recurring cost. openai, openai-agents, litellm and llama-index-core are all moving targets, and pinning them yourself is the only way to keep a working environment stable across pulls. The dev extra pins ruff to 0.11.x, and the README notes black, isort and mypy were intentionally dropped in favour of ruff and basedpyright, so any tooling you built around the older chain needs rewriting rather than reconfiguring.

Editorial conclusion

Adopt QuantMind if you already have a coding agent and want a repo whose contracts, contexts and verify script constrain how it builds financial data pipelines, or if you want a small typed artifact layer over arXiv papers and news. Do not adopt it if you need a stable released API surface, a hosted service, or retrieval quality guarantees: there are no releases, PyPI is not mentioned, and the README does not document rollback or migration. Before committing, run scripts/verify.sh, check that the pinned model identifiers in your configs are ones you can actually call, and confirm the retrieval path you need (rag/, library/ or mind/) exists in the checkout.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. LLMQuant/quant-mind on GitHub
4. Project website
5. README