The Problem

Quantitative finance teams need to turn raw, unstructured information—papers, news, filings—into structured knowledge that downstream retrieval and reasoning can trust. Most pipelines either dump text into a vector store without provenance or build bespoke scrapers that don't generalize. QuantMind addresses this by making every piece of knowledge typed, timestamped, and citation-bearing, so it persists and time-queries standalone.

What This Does

QuantMind is an agent-native knowledge extraction and retrieval framework. The quantmind/ package is organized around four stages: deterministic preprocessing (quantmind/preprocess/), config-driven flows (quantmind/flows/), typed knowledge shapes (quantmind/knowledge/), and retrieval layers (quantmind/mind/, quantmind/rag/, quantmind/library/). The library/ module provides local persistence via SQLite with meaning-based search, while mind/ handles agentic, reasoning-based retrieval.

The repo is designed for coding agents: .agents/ and .claude/ contain skills and references that document how to develop components, write contexts, and run tests. The contexts/ directory holds design documents for each subsystem. The README notes this shipped as a NeurIPS 2025 GenAI-in-Finance workshop paper (arXiv:2509.21507).

How It Is Wired

Execution starts at one of three entry points. The primary one is main in examples/flows/collect_news.py, which reaches 286 functions and is called from 6 places. It routes through _optional_persist_reopen to LocalKnowledgeLibrary.open, hitting the filesystem. The test entry point setUp in tests/configs/test_earnings.py reaches 166 functions and ends in build_paper_structure_tree, which performs a crypto operation via hashlib.sha256.

The most-connected modules are quantmind/knowledge/__init__.py (27 modules depend on it) and quantmind/configs/__init__.py (24 dependents). These are high-blast-radius hubs—changes to them ripple widely. The most-called functions are build_paper_result (32 call sites), _now (29), and _src (28).

File-by-file responsibility map:

  • quantmind/knowledge/paper.py — 37 functions, 27 classes; owns hashing and paper artifact identity.
  • quantmind/library/_internal/sqlite_store.py — 28 functions; owns canonical payload assembly, SQLite reads/writes, and hashing.
  • quantmind/library/local.py — 14 functions; the public persistence API (open, put, put_paper).
  • quantmind/knowledge/_tree.py — 6 functions; tree validation and traversal, used by 17 files.
  • quantmind/mind/retrieval.py — 15 functions; agentic retrieval with retrieve and collect.

The import graph shows 137 internal modules, 251 edges, and zero circular dependencies—clean structure. What's not mapped: the framework callback paths (LangChain) that invoke handlers invisibly to static analysis.

How To Use It

Setup: pyproject.toml is present; use pip install -e . or uv sync. No lockfile exists, so builds aren't reproducible.

Configuration: Copy .env.example to .env and populate any API keys or paths it requires.

Running it: The README documents PaperFlow and collect_news as the shipped flows. Run:

python examples/flows/collect_news.py
python examples/flows/paper.py

Tests: 77 test files exist under tests/, runnable with pytest.

Real-World Use

A research team ingesting financial news and academic papers daily could use collect_news to fetch and normalize PR Newswire feeds, then PaperFlow to parse PDFs into structure trees. Artifacts persist to the local library with citations and timestamps, enabling time-bounded retrieval: "what did we know about this ticker as of last quarter." The mind/ retrieval layer supports agentic reasoning over that knowledge for deeper research tasks.

Code Health & Issues

Static analysis found 52 findings (6 high, 46 medium) across 6 kinds:

  • High - Hub modules: quantmind/knowledge/__init__.py and quantmind/configs/__init__.py have 27 and 24 dependents respectively; churn here is high-blast-radius.
  • High - Deep nesting: 27 instances, max indentation depth 6, in quantmind/preprocess/fetch/http.py, rss.py, and news.py.
  • High - Oversized files: quantmind/knowledge/paper.py at 1088 lines; also sqlite_store.py and pr_newswire.py.
  • High - Duplicated code: 41 repeated 6-line blocks across 21 files.
  • Medium - Resource safety: 14 files opened without context managers.
  • Medium - Broad exceptions: Bare except in quantmind/magic.py and sqlite_store.py.

SDLC observations: CI exists but never runs the test suite—a green check that executes no assertions. GitHub Actions are pinned to mutable tags (@v3) rather than commit SHAs. No Dependabot, no dependency vulnerability scan, no job timeouts.

The Bottom Line

Solid modular architecture with zero circular dependencies and a clean separation between preprocessing, knowledge, and retrieval. The main risks are maintainability (oversized files, deep nesting) and CI that doesn't actually test anything. Worth adopting if you need citation-preserving financial knowledge extraction and can invest in the CI and refactoring debt.