Skip to main content
Glama

MacroStress

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

CI MIT Python 3.12+

MacroStress answers one question: what happens to a portfolio if a given event occurs. A person states only the event, in words: "the central bank raises the policy rate to 21 % and holds it for a year", or "fertiliser exports are banned". An LLM agent turns the event into a scenario, a formal record the models can compute, using a corpus of sources known at the calculation date: news, regulator decisions, descriptions of past episodes. The person checks and approves the scenario. The models then simulate the economy under it, level by level, and reprice every position on the same paths. The result is the distribution of portfolio losses month by month.

flowchart LR
    E["Event<br/>a person, in words"] --> A["LLM agent"]
    K["Corpus of sources"] -.-> A
    A --> S["Scenario"]
    S -->|approved by the person| M["Models by level"]
    M --> R["Loss distribution"]

The platform itself names no model: macro models, satellite models and asset types are plugins, and a new one is a package added without edits to the core. The agent works through MCP; every step is also a command.

Event and scenario

An event is what a person expects to happen, said in words and possibly without numbers. The models cannot compute words: they need to know which values the event decides and which outcomes it requires. The agent writes this down as a scenario $s=(N,I,\mathcal A)$:

Part

What it holds

For "the policy rate is cut to 16 % in December"

$N$

the event in text, with links to the sources of its numbers

the text and the regulator's statement

$I$

interventions: decisions of a subject outside the models, a value set or shifted, with a law when the number is not exact

the key rate set at 16 % in months 1 to 3

$\mathcal A$

observations: what the event requires of the outcome, a condition on a path, a mean or a probability

the rouble down 10 % by month 3

A statement is an intervention when a subject outside the models fixes the value: a decision on the policy rate, an export ban, the price of oil for an economy it acts on from outside. It is an observation when it names an outcome the system itself produces: the exchange rate after sanctions, the fall of output. The same number can be either, and the difference changes the consequences.

Every number in $I$ and $\mathcal A$ is labelled by its origin: the event itself, a named source, or an explicit assumption. If the event leaves the direction of a move open, the agent writes one scenario per direction, and each is computed separately. The agent does not start the calculation until the person approves the scenario.

The platform executes the interventions in the structural form the model declares: in the default form a set value replaces only its own cell and a shift moves only its own path. Then it changes the law of the other coordinates as little as possible so that the observations hold. The size of that change, $\mathrm{dist}(s)=\mathrm{KL}(P_s\Vert P)$, is reported as the scenario price: the higher it is, the less the scenario agrees with the models. A scenario names no model versions, horizon or number of paths: the calculation request names them, so one file is computed on any system of models, and the spread of the results shows how much the answer depends on that choice.

Related MCP server: PA MCP Server

Levels of the economy

Quantities are split into levels $l=0,\dots,L$, from the general to the particular: for example the economy, an industry, a company. Each level has its own model, which takes the paths of the levels above it as inputs. The last level holds the target indicators.

Level

Model

Example quantities

$0$

macro model: joint paths of the macro variables

policy rate, inflation, exchange rate, output

$1,\dots,L$

satellite model of the level: its quantities from the levels above plus its own noise

overdue loans of an industry, a company's share price, a bond spread, housing prices

flowchart LR
    H["History"] -.-> M0
    S["Scenario"] --> M0
    M0["Level 0<br/>macro model"] --> M1["Level 1<br/>satellite model"] --> ML["Level L<br/>target indicators"]
    M0 --> P["Positions<br/>loss distribution"]
    M1 --> P
    ML --> P

The definitions are in docs/concept/formalization.en.md.

Plugins

Kind

What it models

Shipped examples

macro

level 0: shocks and paths of the macro variables

bvar.sv, a Bayesian VAR with stochastic volatility; msvar.markov, a VAR with Markov-switching regimes

satellite

a level above 0: its quantities from the paths of the levels above

hier.gibbs, a hierarchical regression, the default for every quantity; reflevel2.regression, a reference second level

position

an asset type: the value of a position on the paths

equity, bond, credit (loans and deposits), housing

The macro model is chosen when it is estimated. A quantity goes to the satellite model that declares it, or to the one named explicitly. A position goes to the plugin of its asset type. Every shipped plugin describes its model in REFERENCE.en.md next to the code.

python -m mst.plugin new my_model --kind macro    # a package with plugin.py, a model and tests
python -m mst.plugin check my_model               # the contract checks
python -m mst.plugin demo-run my_model            # a calculation on a toy workspace

The platform finds a plugin in mst.plugins, through an entry point of the group mst.plugins, or in a directory listed in MST_PLUGINS_PATH. The guide is docs/howto/plugins.en.md.

The shipped models are examples under development and change between releases. The episode backtest scores every version on historical events against a random walk with drift. Its episodes and the other check sets with known answers are in bench/.

Data

The series, their sources and release lags are configuration: src/mst/data/sources.toml, the variable registry src/mst/macro/registry.toml and the driver registry src/mst/drivers/registry.toml. The shipped set is a sample. Every value keeps its release date, so a model estimated as of a date sees only what was published by then. Data are not part of the repository; you download them under each source's terms.

Output

For every month of the horizon: quantiles of the target indicators and of the portfolio loss ($P_5$, $P_{50}$, $P_{95}$), ES95 (the mean loss over the worst 5 % of paths) and the scenario price. The reverse search answers the opposite question: the worst loss among scenarios no dearer than a given price, or the cheapest scenario that reaches a given loss.

Working with an agent

The server speaks MCP, so any MCP client can drive it: Claude Desktop, Claude Code, Cursor, Codex. It offers seven tools: jobs, series, corpus, scenario, run, portfolio, model; long operations run as jobs. The dsh/ folder holds a plugin for DeepSeek Harness (DSH) with three skills, among them scenario-from-corpus, the agent's instructions for turning an event into a scenario, and a workspace summary in the agent prompt. All state lives in one workspace directory: there is no web interface, database or scheduler.

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 talks over stdio, prints only errors and waits for a client. Connecting a client: docs/howto/mcp.en.md; the DSH plugin: docs/howto/install.en.md.

First session

  1. series(action="update"): the history.

  2. model(kind="macro", action="estimate", as_of=...): level 0.

  3. series(action="update", quantity=...), then model(kind="satellites", action="estimate", version=...): the levels above.

  4. corpus(action="search", ...), scenario(action="save"), scenario(action="validate"): the scenario from the event.

  5. run(action="start"), run(action="result"): the forecast and the portfolio report.

Step by step: docs/howto/first-session.en.md.

Documentation

Layer

File

Question

Concept

docs/concept/formalization.en.md

What the system computes: levels, scenario, overlay, result, quality metrics

Concept

docs/concept/architecture.en.md

How the scheme maps to code: packages, workspace, model versions, jobs

Concept

docs/concept/bvar-method-legacy.en.md

The first BVAR method; outdated, kept for history

How-to

docs/howto/install.en.md

Installing the Python package and the DSH plugin

How-to

docs/howto/mcp.en.md

Connecting any MCP client and fixing common errors

How-to

docs/howto/first-session.en.md

The first session, from series to report

How-to

docs/howto/plugins.en.md

Adding a macro model, a satellite or an asset type as a plugin

Reference

docs/reference/tools.en.md

What the MCP tools and python -m mst.* commands take and return

Reference

docs/reference/platform.en.md

The contracts: position, paths, model, registry, run and report

Every document exists in Russian (*.md) and English (*.en.md); the index is docs/README.en.md. Every package folder has its own README naming its files.

Development

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

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

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; the license does not cover the data you download. Citations are described in CITATION.cff.

Available Tools

10 tools
corpusScenario corpusB

The scenario corpus and the model corpus. Actions: search, get, list, add, index, fetch.

corpus="model" works with the corpus of the models — the material a model's elicitation reads: episodes, the state at the date, transmission reviews, market expectations — which has its own manifest and index under corpus-model/. search and get read the index as it was on as_of; list shows what the manifest holds; add registers a file downloaded by hand under its key. index and fetch are tasks on the corpus resource. Inside a bench session every call and its answer go to the journal of the event.

Inputs: action (required), k, id, ids, +9 more. Returns: object

elicitThe questions of a model and the answers the agent writesA

Answer a macro model's questions in small resumable steps.

Start with next and model_id/as_of. It gives one small question, its schema and answer_call. Copy answer_call with your answer object as payload to answer; the result saves it and gives the next question. Continue until complete=true. Each response step asks nine numbers, not a full shock table. Partial answers survive a restart and never count as a completed input. Never substitute placeholders or ask the human for numbers. next resumes the first missing step.

A model that declares inputs is estimated from the agent's own answers, not from the series: list names every input key on the date and status repeats the summary. Full question/write operations belong to model(kind="inputs"), not this interview. The agent is the expert: the numbers are its own judgements, not the human's and not the fixtures of the tests. When nothing is missing, build the version: model(kind="macro", action="estimate", model_id=..., as_of=...) starts a job, and jobs(action="wait", id=...) holds until it ends. The same actions are kind="inputs" of the model tool.

Inputs: action (required), key, agent, as_of, +3 more. Returns: object

guideWorking guidesA
Read-onlyIdempotent

The working guides of the agent: how to do the work, whatever the client.

Without name, the list. scenario-from-corpus turns an event into a scenario; read it before scenario save.

Inputs: name. Returns: object

interviewThe interview of a model: who answers which input and how farA

Track the interview of a model: ownership, progress, review and corrections.

progress names every input key with its state, owner, answered parts and publication; call it before handing a shock to an agent. claim gives one key to one agent; a live claim of another agent refuses a second writer. release drops the caller's claim. restart resumes an agent whose run stopped — a network error, a timeout, a crashed client: it renews that agent's claim and returns the first missing part, so the same agent continues where the saved parts end and nothing is asked twice. audit lists the advisory findings of one published answer or of every one. accept records that the warnings were reviewed, with the reason; reopen asks named parts again, keeps the old answer as a version and makes the key missing until it is complete again. history lists the versions of one answer and journal the last events of the interview.

This tool never writes an answer: the numbers come only through elicit. The orchestrating agent owns the process: it hands one shock to one subagent, reads the warnings and either accepts the answer or reopens the steps they name.

Inputs: as_of (required), action (required), model_id (required), key, +5 more. Returns: object

jobsWorkspace and job stateA
Destructive

Workspace and task state. Actions: state, status, log, cancel, wait.

wait polls the job server-side, so one call replaces the loop of status and log calls an agent would otherwise run while a long job works; it returns the record status returns, and running says whether to call it again.

Inputs: action (required), id, tail, timeout_sec. Returns: object

modelModel versions and pluginsA

Model versions and plugins. kind: macro, satellites, inputs, catalog.

The episode check of the models is backtest (python -m mst.metrics). Actions for macro: list, describe, base, estimate, backtest; for satellites: list, describe, estimate; for catalog: list, the installed model plugins. base gives p5, p50 and p95 of the macro variables under the base s_0 by month, up to horizon, in the model scale, for only the variables named; it starts no job. model_id names the macro model to estimate or backtest — the only one installed when omitted; assignment maps a quantity to the satellite model that estimates it in an estimate of the satellites, overriding the model that declares it. version is the version hash describe and base read and the macro version the satellites of an estimate are built on; list takes no version.

inputs is the elicitation a model that declares inputs is estimated from; the elicit tool serves the same four actions and is the one to call when the user asks for the answers of a model's questions. list and status name every key written or missing, question gives the text the agent reads before answering and write checks the answer's form and stores it. The inputs are written by the agent itself and no human approves them — read guide(name="model-inputs") first — and model_id and as_of name the model and the date; a refused answer comes back with the field it was refused for.

Inputs: kind (required), action (required), key, only, +6 more. Returns: object

portfolioStored portfoliosB
Destructive

Stored portfolios. Actions: list, get, save, delete, check, exposure.

save checks the contract and writes portfolios/<id>.json; check names every position the scenario's macro and satellite versions cannot serve, with the reason of a driver the out-of-sample check rejected, and warns what an impact on a macro variable reaches through the positions' drivers, with the long-run loading of each one (below 0.1 it barely reacts); exposure values the positions at the calculation month of the scenario's macro version.

Inputs: action (required), id, spec, scenario. Returns: object

runScenario runsA

Runs on the paths of a scenario. Actions: start, status, result, list.

Read guide(name="run-report") first. start draws the scenario's paths and calculates a portfolio's positions — or the positions given in the call — on them, as a job on the runs resource; status reports that job and what the run has written, result the per-position results, the conditional forecast of the targets (forecast.json: P5/P50/P95 of every target driver by month, in its own unit; every driver when targets is omitted) and the report of a portfolio run, list every run of the workspace. base_currency is the base of positions; a portfolio brings its own.

Inputs: action (required), id, seed, draws, +6 more. Returns: object

scenarioStored scenariosA
Destructive

Stored scenarios. Actions: list, get, save, validate, reverse.

Read guide(name="scenario-from-corpus") before building one. save checks the contract and writes scenarios/<id>.json; validate loads the macro and satellite versions the file names and names every problem that keeps the scenario from being computed, including corpus fragments not visible on the calculation day when the index exists, and reports how the elements are marked and what the scenario leaves unsaid under labels and warnings. reverse searches the scenario's family on portfolio: the worst loss under the price kappa, or the lowest price whose loss reaches level. bench returns the text of the bench event and starts its journal of corpus calls; build the scenario by the guide, then bench_save checks spec and keeps it with the journal and notes in the bench results, beside an empty review the expert fills. A bench scenario is never approved and never computed.

Inputs: action (required), id, seed, spec, +6 more. Returns: object

seriesStored seriesC

Stored series. Actions: search, get, add, update.

update fetches the named ids; with quantity it instead discovers the objects of that driver quantity and fetches their series.

Inputs: action (required), id, ids, text, +3 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 10 tools

    Disambiguation3/5

    The tools are organized around distinct resources, but there is real overlap between elicit and model(kind="inputs"), and between jobs status/wait and run status. The rich descriptions help, but an agent can still hesitate over which tool owns an operation such as checking a run or supplying model inputs.

    Naming Consistency4/5

    Names are consistently lowercase and mostly resource-oriented, which is readable across the set. Minor deviations are 'elicit' as a verb and 'jobs' as a plural among otherwise singular resource nouns.

    Tool Count4/5

    Ten tools is a reasonable count for a complex macro stress-testing server. However, each tool packs many actions and modes, so the effective surface is much larger than the count suggests, and a few tools such as model and elicit could be cleaner if separated.

    Completeness4/5

    The surface covers the core lifecycle: series, portfolios, scenarios, models, elicitation, interviews, runs, and jobs. The main gaps are missing delete operations for several resources such as series, scenarios, and corpus entries, but these are not central blockers for the main workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides AI agents with quantitative risk tools such as VaR, expected shortfall, GARCH volatility, backtesting, stress testing, tail risk analysis, and credit scoring using synthetic or user-supplied data.
      7
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to run probabilistic portfolio analysis workflows, including input validation, instrument verification, simulation preparation, and approved interactive reporting.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables quantitative portfolio tail-risk analysis, option Greeks, Monte Carlo stochastic simulations, fixed-income duration/convexity, and Nelson-Siegel yield-curve interpolation through MCP tools.
      7
      MIT