Rust tooling for building a local, source-cited knowledge base from a Zoltan Pozsar PDF corpus, exposing it through a read-only MCP server, generating file-based cross-asset market context snapshots, and composing advisor-ready context.
The CLI can fetch historical closes from a Yahoo-compatible endpoint, but it only writes local snapshot artifacts. The MCP and advisor paths never fetch market data directly. The project does not include streaming feeds, trading signals, backtesting, portfolio management, broker or exchange adapters, or execution code.
Rust MCP server for source-cited search over a local Zoltan Pozsar macro/liquidity corpus.
星标
3
工具
—
可用率
—
Why Pozsar
Zoltan Pozsar's work is important because it connects macroeconomics to the balance-sheet plumbing that often drives markets: collateral, repo, eurodollars, FX swaps, reserves, shadow banking, safe assets, and commodity-linked money. His writing is useful for studying how liquidity moves through the financial system and why stress can appear outside the places covered by standard macro indicators.
This project turns that corpus into a local, source-cited research layer so agents and analysts can retrieve the original passages behind a macro or liquidity question instead of relying on unsourced summaries.
What It Does
Downloads and verifies source PDFs from a hash-pinned source map
Manifests local PDFs in docs/
Extracts page-level text from PDFs
Chunks extracted pages with source metadata
Tags chunks with deterministic macro/liquidity themes
Writes versioned corpus artifacts under data/knowledge/
Builds a Tantivy BM25 index over text and source metadata
Validates generated corpus artifacts with corpus inspect
Runs fixture-backed retrieval, advisor, and policy evaluations
Runs a read-only MCP server for source-cited search and evidence workflows
Prepares Qdrant-compatible payloads for future vector indexing
Builds deterministic market context JSON from local price CSV files
Fetches supported historical market closes through a Yahoo-compatible adapter
Builds deterministic advisor snapshots that combine corpus liquidity signals with market context
Builds deterministic advisor policy JSON from advisor snapshots without producing trade recommendations
Repository Layout
crates/
advisor-core/ Offline advisor snapshot composition logic
advisor-policy/ Deterministic advisor policy assessment logic
corpus-cli/ Corpus, evaluation, market-context, and advisor CLI
market-data-adapters/ Historical market-data provider abstraction and Yahoo adapter
market-context/ Offline cross-asset market context library
pozsar-common/ Artifact envelopes, typed operational errors, and exit codes
pozsar-kb/ Corpus pipeline, inspection, BM25 indexing, search, and fallback retrieval
pozsar-mcp/ Read-only MCP server over generated corpus chunks
docs/ Source map, usage docs, and ignored downloaded PDFs
data/knowledge/ Generated corpus artifacts; ignored by git
data/market/ Local/sample market CSV inputs and ignored generated JSON context
data/advisor/ Ignored generated advisor snapshots and policy artifacts
Local PDF Inputs
This repository does not redistribute Pozsar PDFs. PDF files in docs/ are ignored by git and are excluded from release archives. Users rebuild the local corpus by downloading the documents from public source links recorded in docs/SOURCE_MAP.md and Zoltan-Pozsar-Bibliography.html.
corpus download-sources can rebuild the local PDF set, and corpus verify-sources checks local PDF hashes and source URLs before corpus generation.
The default build includes the lexical index. Building corpus-cli with
--no-default-features omits Tantivy and leaves search on the compatibility keyword fallback.
Inspect The Corpus
cargo run -p corpus-cli -- inspect --out data/knowledge
The inspection command reports document/page/chunk counts, empty pages, pages without chunks, validation issues, and theme distribution. It exits nonzero if validation issues are found.
Search And Retrieval Modes
The default search path uses Tantivy BM25 over chunk text, title, canonical themes, file name,
and citation. Requests can filter by theme, document ID, file name, and page. Results report the
requested and resolved modes, warnings, BM25 score, matched terms, rank, and source citation.
lexical, vector, and hybrid are accepted mode names, but this release resolves all three to
lexical. Embeddings, vector lookup, Qdrant collection management, and lexical/vector fusion are
not implemented. When a compatible lexical_index/ is absent or stale, search attaches a warning
and uses the deterministic keyword fallback for older artifacts.
answer_pozsar_research_question is a separate deterministic evidence-bundle workflow. It plans
keyword/theme queries, returns cited passages with neighboring context, and suggests follow-ups;
it does not generate a prose answer. Liquidity-signal and advisor workflows currently build on
this evidence path rather than raw BM25 search.
Build Market Context
Generate an offline market context snapshot from a local CSV file:
The output includes per-asset returns, 20-observation trend, annualized volatility, drawdown, and a deterministic cross-asset regime summary. This is local market context only; it does not produce trade recommendations.
Fetch Historical Market Context
Fetch a point-in-time set of historical closes through the Yahoo-compatible CSV adapter, normalize them into date,symbol,close, reuse the existing market-context calculations, and write the same local MarketContext JSON format plus a health sidecar:
The supported symbols are BTC, ETH, SPY, QQQ, GLD, TLT, and DXY. The command prints a health report for freshness, missing assets, stale prices, and insufficient history. It exits nonzero if blocking health issues are found. MCP and advisor tools consume only the generated files; they do not fetch market data directly.
The output includes source-cited liquidity signals, market context, per-asset macro/market alignment, and a combined regime label such as macro_tightening_market_risk_on. It is deterministic context for a future advisor layer, not trading advice.
If --market-health is supplied, its as_of must match the market context as_of. Health status is retained in the snapshot and affects policy confidence and risk fields; an as_of mismatch is rejected. Any reported stale assets force health status to invalid, and missing health metadata caps policy confidence at low.
Build Advisor Policy
Convert an advisor snapshot into deterministic asset assessments:
The policy output includes per-asset stance, confidence, drivers, risks, and required checks. It remains context-only: no trade recommendation, position sizing, or execution instruction is emitted.
The verifier compares local ignored docs/*.pdf files with direct PDF links in the bibliography, checks each source-map URL and SHA-256 hash, and exits nonzero on mismatch.
Evaluate Retrieval
Run fixture-backed golden-query checks against a chunk artifact:
The eval command reports pass/fail per case, returned citations, expected citation ranks, missing citations, category summaries, and a summary count. Use --tool search to test raw local search or --tool research-question to test the research bundle path. Use --format json for CI or machine-readable regression artifacts. Use --output <path> to write the report to disk while printing only the output path and summary to stdout. Use --fail-fast to stop after the first failing case. It exits nonzero if any expected citation is missing or ranked too low. Keep public-safe fixtures under eval/fixtures/; use ignored local files under eval/local/ or eval/*.json for private corpus cases.
To evaluate the BM25 path specifically, select the raw search tool and lexical mode:
Eval cases can include optional max_rank to require each expected citation to appear by that rank:
{
"name": "collateral dollar liquidity",
"category": "dollar_liquidity",
"notes": "Core liquidity plumbing query; should surface Safe Asset Glut early.",
"query": "collateral dollar liquidity",
"themes": ["collateral"],
"expected_citations": ["The_Safe_Asset_Glut.pdf:7"],
"max_rank": 3
}
Run The MCP Server
By default, the MCP server reads data/knowledge/chunks/pozsar_chunks.jsonl:
cargo run -p pozsar-mcp
To point it at another chunk artifact or market context snapshot:
POZSAR_CHUNKS_JSONL=/path/to/pozsar_chunks.jsonl \
POZSAR_MARKET_CONTEXT_JSON=/path/to/context.json \
cargo run -p pozsar-mcp
Available MCP tools:
get_pozsar_kb_status
list_pozsar_docs
list_pozsar_themes
search_pozsar_kb
explain_pozsar_search
read_pozsar_source
read_pozsar_page_context
answer_pozsar_research_question
extract_pozsar_liquidity_signals
get_pozsar_advisor_snapshot
get_pozsar_advisor_policy
Search tools return a versioned envelope containing requested/resolved mode, warnings, and ranked
results. Results include citations in file_name:page format. The server is read-only, uses stdio,
and loads the chunk snapshot once at startup.
Run a raw MCP advisor snapshot demo after building the release binary and local artifacts:
scripts/demo-mcp-advisor.sh
Run the raw search and page-context demo with:
scripts/demo-mcp-search.sh
For Claude Desktop and Codex configuration examples, tool parameters, and response shapes, see docs/MCP.md.
Check the MCP binary version without starting the stdio server:
No vector search, embeddings, hybrid fusion, or reranking; Qdrant support is payload-only.
No incremental corpus builds, OCR fallback, table extraction, or structure-aware chunking.
No MCP HTTP transport, authentication, resources, prompts, pagination, or hot reload.
No generated narrative answer; research and advisor outputs are deterministic structured data.
No trading recommendations, P&L backtests, positions, portfolio risk, or order execution.
Retrieval evaluation checks expected citations and rank ceilings; it does not yet report MRR,
Recall@K, or nDCG.
License
This project's source code and documentation are distributed under the MIT License; see LICENSE.
The Pozsar PDFs are not distributed by this repository or release packages. They are downloaded by users from public source URLs listed in docs/SOURCE_MAP.md, and those documents remain subject to their original publishers' terms.