MacroStress

English | Русский | 中文

MacroStress answers one question: how much does a portfolio lose under a given macroeconomic scenario? An analyst or an agent names paths for a few macro variables (say, the policy rate at 21 % for the next year) and the shocks behind them. A BVAR estimated on history completes consistent paths for the other variables, satellite models turn those paths into drivers (equity prices, bond spreads, industry overdue shares, housing prices), and every position is repriced along the same draws. The output is a loss distribution with $P_5$, $P_{50}$, $P_{95}$, ES95 and the scenario severity $\delta$. The method is described in docs/concept/scenario-formalization.md (Russian).

The server speaks MCP, so any client can drive it: Claude Desktop, Cursor, Claude Code. A DeepSeek Harness plugin in dsh/ adds three skills and a workspace snapshot for the agent prompt. All state lives in one workspace/ directory; there is no web app, no database, and no scheduler.

What it does

MCP tools: jobs, series, corpus, scenario, run, portfolio, model. The reference is in docs/reference/tools.md (Russian).

Install

Python 3.12 or newer and uv are enough.

git clone https://github.com/LeoLourson/MacroStress-DSH
cd MacroStress-DSH
uv sync
uv run macrostress --workspace C:/data/macrostress

The server speaks over stdio and prints only errors; it waits for a client. Configuration for Claude Desktop, Cursor, and any other MCP client is in docs/howto/mcp.md. The DeepSeek Harness plugin is covered in docs/howto/install.md.

First session

Once a client is connected, it sees seven tools. Long operations start jobs: a tool returns a job at once, and jobs shows the progress.

1. jobs(action="state") — what is in the workspace: model versions, corpus index, jobs.
2. series(action="update") — download the macro series. FRED needs a key in FRED_API_KEY.
3. jobs(action="status", id=...) and jobs(action="log", id=...) — wait for the job.
4. model(kind="macro", action="estimate", as_of="2026-10-29") — estimate the macro model (bvar.sv, the only one installed; model_id names another) on the data known at that date. The version is a hash.
5. series(action="update", quantity="share_price") — find the objects of a quantity and download their series; the same for bond_spread, overdue_share, housing_price_primary, housing_price_secondary.
6. model(kind="satellites", action="estimate", version=<macro hash>) — assemble the satellite bundle of that macro version: every quantity is estimated by the model assigned to it (hier.gibbs by default; assignment names another).
7. model(kind="satellites", action="describe", version=<hash>) — which drivers passed the out-of-sample check and why the rest were rejected.
8. corpus(action="search", query=..., as_of=...) — fragments known at the date; corpus(action="index") rebuilds the index as a job.
9. scenario(action="save", id=..., spec={...}) — save a scenario; scenario(action="validate", id=...) — list everything that blocks the calculation.
10. portfolio(action="save", id=..., spec={...}) — save a portfolio; portfolio(action="check", id=..., scenario=...) — check it against the scenario.
11. run(action="start", scenario=..., portfolio=..., draws=..., seed=..., targets=...) — start a run; run(action="result", id=...) — read the conditional forecast of the target indicators ($P_5$/$P_{50}$/$P_{95}$ by month) and the portfolio report with $\delta$ and coverage.
12. model(kind="macro", action="backtest", as_of=...) — the episode check: CRPS, calibration and admission of the models on historical events (mst.metrics).

Documentation

The documentation is in Russian.

• docs/concept/system-scheme.md — the general scheme: levels, the scenario $(N, D, C, O)$, the conditional forecast, and the quality metrics;
• docs/concept/scenario-formalization.md — the method and what the code implements;
• docs/concept/architecture.md — packages, workspace, versions, jobs;
• docs/howto/install.md — the Python package and the DeepSeek Harness plugin;
• docs/howto/mcp.md — any MCP client and troubleshooting;
• docs/howto/first-session.md — the first session, from series to report;
• docs/howto/plugins.md — a new asset type, macro model or satellite as a plugin;
• docs/reference/tools.md — MCP tools and python -m mst.* commands;
• docs/reference/platform.md — the contracts: position, paths, model, registry.

Every package folder has its own README that names its files.

Development

uv sync
uv run pytest -q -m "not slow"
uv run ruff check .

The slow tests estimate the BVAR and take minutes; the night workflow runs the full suite. CI runs the fast suite on Linux and Windows with Python 3.12 and 3.13.

Status

0.2.0, beta. Interfaces may change before 1.0. The data sources are the Russian market (MOEX, the Bank of Russia, Rosstat) plus FRED for global series.

Contributing and license

Contributing rules and the release process are in CONTRIBUTING.md; vulnerabilities go through SECURITY.md. The code is MIT-licensed, see LICENSE. Series from MOEX, the Bank of Russia, Rosstat, FRED, and BIS are not part of this repository: you load them under the terms of each source, and the license does not cover that data. Citations are described in CITATION.cff.