macrostress 0.1.0__tar.gz

macrostress-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LeoLourson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

macrostress-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: macrostress
+Version: 0.1.0
+Summary: Portfolio stress testing over macroeconomic scenarios, as an MCP server
+Keywords: stress-testing,scenario-analysis,macroeconomic,bvar,portfolio-risk,mcp
+Author: LeoLourson
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Dist: numpy==2.4.4
+Requires-Dist: scipy==1.17.1
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: httpx==0.28.1
+Requires-Dist: fastmcp==2.14.7
+Requires-Dist: openpyxl==3.1.5
+Requires-Dist: pypdf==6.21.4
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: snowballstemmer==3.1.1
+Requires-Dist: onnxruntime==1.31.1
+Requires-Dist: tokenizers==0.23.2
+Requires-Dist: huggingface-hub==1.33.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/LeoLourson/MacroStress-DSH
+Project-URL: Documentation, https://github.com/LeoLourson/MacroStress-DSH/blob/main/docs/README.md
+Project-URL: Repository, https://github.com/LeoLourson/MacroStress-DSH
+Project-URL: Issues, https://github.com/LeoLourson/MacroStress-DSH/issues
+Project-URL: Changelog, https://github.com/LeoLourson/MacroStress-DSH/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# MacroStress
+
+[English](README.md) | [Русский](README.ru.md) | [中文](README.zh.md)
+
+[![CI](https://github.com/LeoLourson/MacroStress-DSH/actions/workflows/ci.yml/badge.svg)](https://github.com/LeoLourson/MacroStress-DSH/actions/workflows/ci.yml)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
+
+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/scenario-formalization.md](docs/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
+
+| Part | What it does |
+|---|---|
+| Series | Monthly series from MOEX, the Bank of Russia, Rosstat, and FRED, with the release date of every value |
+| Macro model | BVAR with stochastic volatility, sign restrictions, conditional forecasts, scenario severity, and checks on historical episodes |
+| Drivers | Object catalogs, hierarchical satellite models, out-of-sample checks, driver paths on the macro draws |
+| Scenario | A $(N, C, D, O)$ file with validation and paths: conditional forecast and drivers on the same draws |
+| Positions | Equity, bond, credit or deposit, housing |
+| Run and report | Positions along scenario paths, with $P_5$, $P_{50}$, $P_{95}$, ES95, and $\delta$ |
+| Extensions | A new asset type is a plugin: `python -m mst.plugin new`, contract checks, a demo run |
+| DSH plugin | Scenario from the corpus, report, drivers; the prompt section built from `workspace.json` |
+
+MCP tools: `jobs`, `series`, `corpus`, `scenario`, `run`, `portfolio`, `model`. The reference is
+in [docs/tools.md](docs/tools.md) (Russian).
+
+## Install
+
+Python 3.12 or newer and [uv](https://docs.astral.sh/uv/) are enough.
+
+```bash
+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/mcp.md](docs/mcp.md). The DeepSeek
+Harness plugin is covered in [docs/install.md](docs/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 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>)` — estimate the satellites
+   on that macro version.
+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=...)` — start a run;
+    `run(action="result", id=...)` — read $P_5$/$P_{50}$/$P_{95}$, $\delta$, and coverage.
+
+## Documentation
+
+The documentation is in Russian, except [docs/mcp.md](docs/mcp.md), which is in English.
+
+- [docs/mcp.md](docs/mcp.md) — any MCP client, the first session, troubleshooting;
+- [docs/install.md](docs/install.md) — the Python package and the DeepSeek Harness plugin;
+- [docs/architecture.md](docs/architecture.md) — packages, workspace, versions, jobs;
+- [docs/tools.md](docs/tools.md) — MCP tools and `python -m mst.*` commands;
+- [docs/plugins.md](docs/plugins.md) — a new asset type as a plugin;
+- [docs/platform.md](docs/platform.md) — the contracts: position, paths, model, registry;
+- [docs/scenario-formalization.md](docs/scenario-formalization.md) — the method and what the code
+  implements.
+
+Every package folder has its own README that names its files.
+
+## Development
+
+```bash
+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.1.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](CONTRIBUTING.md);
+vulnerabilities go through [SECURITY.md](SECURITY.md). The code is MIT-licensed, see
+[LICENSE](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](CITATION.cff).

macrostress-0.1.0/README.md

@@ -0,0 +1,117 @@
+# MacroStress
+
+[English](README.md) | [Русский](README.ru.md) | [中文](README.zh.md)
+
+[![CI](https://github.com/LeoLourson/MacroStress-DSH/actions/workflows/ci.yml/badge.svg)](https://github.com/LeoLourson/MacroStress-DSH/actions/workflows/ci.yml)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
+
+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/scenario-formalization.md](docs/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
+
+| Part | What it does |
+|---|---|
+| Series | Monthly series from MOEX, the Bank of Russia, Rosstat, and FRED, with the release date of every value |
+| Macro model | BVAR with stochastic volatility, sign restrictions, conditional forecasts, scenario severity, and checks on historical episodes |
+| Drivers | Object catalogs, hierarchical satellite models, out-of-sample checks, driver paths on the macro draws |
+| Scenario | A $(N, C, D, O)$ file with validation and paths: conditional forecast and drivers on the same draws |
+| Positions | Equity, bond, credit or deposit, housing |
+| Run and report | Positions along scenario paths, with $P_5$, $P_{50}$, $P_{95}$, ES95, and $\delta$ |
+| Extensions | A new asset type is a plugin: `python -m mst.plugin new`, contract checks, a demo run |
+| DSH plugin | Scenario from the corpus, report, drivers; the prompt section built from `workspace.json` |
+
+MCP tools: `jobs`, `series`, `corpus`, `scenario`, `run`, `portfolio`, `model`. The reference is
+in [docs/tools.md](docs/tools.md) (Russian).
+
+## Install
+
+Python 3.12 or newer and [uv](https://docs.astral.sh/uv/) are enough.
+
+```bash
+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/mcp.md](docs/mcp.md). The DeepSeek
+Harness plugin is covered in [docs/install.md](docs/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 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>)` — estimate the satellites
+   on that macro version.
+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=...)` — start a run;
+    `run(action="result", id=...)` — read $P_5$/$P_{50}$/$P_{95}$, $\delta$, and coverage.
+
+## Documentation
+
+The documentation is in Russian, except [docs/mcp.md](docs/mcp.md), which is in English.
+
+- [docs/mcp.md](docs/mcp.md) — any MCP client, the first session, troubleshooting;
+- [docs/install.md](docs/install.md) — the Python package and the DeepSeek Harness plugin;
+- [docs/architecture.md](docs/architecture.md) — packages, workspace, versions, jobs;
+- [docs/tools.md](docs/tools.md) — MCP tools and `python -m mst.*` commands;
+- [docs/plugins.md](docs/plugins.md) — a new asset type as a plugin;
+- [docs/platform.md](docs/platform.md) — the contracts: position, paths, model, registry;
+- [docs/scenario-formalization.md](docs/scenario-formalization.md) — the method and what the code
+  implements.
+
+Every package folder has its own README that names its files.
+
+## Development
+
+```bash
+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.1.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](CONTRIBUTING.md);
+vulnerabilities go through [SECURITY.md](SECURITY.md). The code is MIT-licensed, see
+[LICENSE](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](CITATION.cff).

macrostress-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "macrostress"
+version = "0.1.0"
+description = "Portfolio stress testing over macroeconomic scenarios, as an MCP server"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "stress-testing",
+    "scenario-analysis",
+    "macroeconomic",
+    "bvar",
+    "portfolio-risk",
+    "mcp",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "numpy==2.4.4",
+    "scipy==1.17.1",
+    "pydantic==2.12.5",
+    "httpx==0.28.1",
+    "fastmcp==2.14.7",
+    "openpyxl==3.1.5",
+    "pypdf==6.21.4",
+    "pyyaml==6.0.3",
+    "snowballstemmer==3.1.1",
+    "onnxruntime==1.31.1",
+    "tokenizers==0.23.2",
+    "huggingface-hub==1.33.0",
+]
+
+[[project.authors]]
+name = "LeoLourson"
+
+[project.urls]
+Homepage = "https://github.com/LeoLourson/MacroStress-DSH"
+Documentation = "https://github.com/LeoLourson/MacroStress-DSH/blob/main/docs/README.md"
+Repository = "https://github.com/LeoLourson/MacroStress-DSH"
+Issues = "https://github.com/LeoLourson/MacroStress-DSH/issues"
+Changelog = "https://github.com/LeoLourson/MacroStress-DSH/blob/main/CHANGELOG.md"
+
+[project.scripts]
+macrostress = "mst.mcp:main"
+
+[dependency-groups]
+dev = [
+    "pytest==8.4.2",
+    "pytest-timeout==2.4.0",
+    "ruff==0.12.12",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "mst"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra"
+markers = ["slow: estimates the BVAR and takes minutes"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]

macrostress-0.1.0/pyproject.toml.orig

@@ -0,0 +1,85 @@
+[project]
+name = "macrostress"
+version = "0.1.0"
+description = "Portfolio stress testing over macroeconomic scenarios, as an MCP server"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "LeoLourson" }]
+keywords = [
+  "stress-testing",
+  "scenario-analysis",
+  "macroeconomic",
+  "bvar",
+  "portfolio-risk",
+  "mcp",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+  "numpy==2.4.4",
+  "scipy==1.17.1",
+  "pydantic==2.12.5",
+  "httpx==0.28.1",
+  "fastmcp==2.14.7",
+  # Excel tables of the Bank of Russia and Rosstat archives.
+  "openpyxl==3.1.5",
+  # Corpus: PDF text extraction, the YAML header of a document, BM25 stems.
+  "pypdf==6.21.4",
+  "pyyaml==6.0.3",
+  "snowballstemmer==3.1.1",
+  # Corpus search vectors: multilingual-e5-small on the CPU through ONNX Runtime.
+  "onnxruntime==1.31.1",
+  "tokenizers==0.23.2",
+  "huggingface-hub==1.33.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/LeoLourson/MacroStress-DSH"
+Documentation = "https://github.com/LeoLourson/MacroStress-DSH/blob/main/docs/README.md"
+Repository = "https://github.com/LeoLourson/MacroStress-DSH"
+Issues = "https://github.com/LeoLourson/MacroStress-DSH/issues"
+Changelog = "https://github.com/LeoLourson/MacroStress-DSH/blob/main/CHANGELOG.md"
+
+[project.scripts]
+macrostress = "mst.mcp:main"
+
+[dependency-groups]
+dev = [
+  "pytest==8.4.2",
+  "pytest-timeout==2.4.0",
+  "ruff==0.12.12",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+# The import package is mst; the distribution is macrostress.
+[tool.uv.build-backend]
+module-name = "mst"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra"
+markers = [
+  "slow: estimates the BVAR and takes minutes",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

macrostress-0.1.0/src/mst/README.md

@@ -0,0 +1,32 @@
+# mst
+
+Ядро MacroStress: MCP-сервер, задачи, workspace и пакеты расчёта. Единственное состояние —
+файлы workspace; каждый инструмент MCP разбирает аргументы и вызывает одну функцию
+пакета или запускает задачу. Устройство целиком — в
+[../../docs/architecture.md](../../docs/architecture.md).
+
+| Модуль или пакет | Что делает |
+|---|---|
+| `mcp.py` | Сервер FastMCP с инструментами `jobs`, `series`, `corpus`, `scenario`, `run`, `portfolio`, `model` ([../../docs/tools.md](../../docs/tools.md)); `python -m mst.mcp --workspace DIR` |
+| `plugin.py` | `python -m mst.plugin new|check|demo-run`: пакет типа актива, его контракт и демо-расчёт ([../../docs/plugins.md](../../docs/plugins.md)) |
+| `jobs.py` | Задачи: дочерний процесс `python <argv>` под обёрткой `python -m mst.jobs`, которая пишет код выхода, с логом в `jobs/<id>/`, блокировка ресурса (`series`, `models`, `corpus`, `code`, `runs`), отмена дерева процессов |
+| `runs.py` | Прогон на путях сценария: запрос, мета, пути, вклады позиций и отчёт в `runs/<id>/`; `python -m mst.runs <id> --workspace DIR` |
+| `store.py` | Каталоги workspace (`Workspace`), атомарная запись JSON, канонический хеш `sha256_of`, снимок `workspace.json` |
+| `versions.py` | Версии моделей на диске: хеш по метаданным и массивам, запись через черновик, чтение с проверкой хеша и имени, список без черновиков |
+| `contracts.py` | Базовый класс контрактов pydantic (`extra="forbid"`, без NaN и бесконечностей) и общие типы: идентификатор, хеш, горизонт, сид, валюта, код объекта, статус результата |
+| `importer.py` | Копирование рядов из каталога CSV (`<source>/data/series/*.csv`) в workspace |
+| [data/](data/README.md) | Загрузка и хранение месячных рядов |
+| [macro/](macro/README.md) | Макромодель: оценка, идентификация, условный прогноз, жёсткость, бэктест |
+| [drivers/](drivers/README.md) | Драйверы: каталоги, сателлиты, их проверка и пути |
+| [corpus/](corpus/README.md) | Корпус источников: манифест, загрузка, Markdown, эпизоды, индекс и поиск |
+| [scenario/](scenario/README.md) | Сценарий: контракт, проверка и сборка путей |
+| [plugin_sdk/](plugin_sdk/README.md) | Что модель позиции объявляет, читает и возвращает: `Paths`, требования, результат; `testing.py` — конформанс-проверка |
+| [engine/](engine/README.md) | Каталог моделей, подготовка входов и расчёт позиций без ветвления по типу актива |
+| [plugins/](plugins/README.md) | Пакеты типов активов: обнаружение, реестр объявлений и модели позиций |
+| [portfolio/](portfolio/README.md) | Портфель, его проверка, стоимость позиций и отчёт прогона |
+
+Зависимости между пакетами идут в одну сторону: `data` → `macro` → `drivers`; `scenario`
+нужен `macro` и `drivers`, `corpus` — бэктесту `macro`; `engine` и `runs` — `plugin_sdk`,
+`plugins`, `scenario` и обеим версиям моделей; `portfolio` — `engine` и `scenario`.
+`plugin.py` читает реестр `plugins` и `plugin_sdk.testing`; сам `engine` конкретных плагинов
+не импортирует.

macrostress-0.1.0/src/mst/__init__.py

@@ -0,0 +1,5 @@
+"""Series, macro model, drivers, corpus, scenarios, portfolios and runs of MacroStress.
+
+The package is the core of the DSH plugin: every MCP tool in ``mst.mcp`` parses its
+arguments and calls one function here, and the workspace on disk is the only state.
+"""

macrostress-0.1.0/src/mst/contracts.py

@@ -0,0 +1,48 @@
+"""Wire conventions: money in millions of its currency, rates as fractions, time in months/days."""
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Identifier = Annotated[str, Field(min_length=1, pattern=r"\S")]
+Sha256 = Annotated[str, Field(pattern=r"^[0-9a-f]{64}$")]
+Number = Annotated[float, Field(strict=True, allow_inf_nan=False)]
+Probability = Annotated[Number, Field(ge=0, le=1)]
+NonNegative = Annotated[Number, Field(ge=0)]
+Positive = Annotated[Number, Field(gt=0)]
+Horizon = Annotated[int, Field(strict=True, ge=1, le=360)]
+Seed = Annotated[int, Field(strict=True, ge=0, le=2**32 - 1)]
+#: An ISO 4217 code: the currency of a position, a portfolio's base currency.
+Currency = Annotated[str, Field(pattern=r"^[A-Z]{3}$")]
+#: A kind of code a position carries and an object may cover (``Registry.match``).
+CodeKind = Literal["secid", "isin", "inn", "okved", "okato"]
+Status = Literal["ok", "needs_review"]
+#: The status of a calculated position: ``invalid`` never enters portfolio arithmetic.
+ResultStatus = Literal["ok", "needs_review", "invalid"]
+
+__all__ = [
+    "CodeKind",
+    "Contract",
+    "Currency",
+    "Horizon",
+    "Identifier",
+    "NonNegative",
+    "Number",
+    "Positive",
+    "Probability",
+    "ResultStatus",
+    "Seed",
+    "Sha256",
+    "Status",
+]
+
+
+class Contract(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        allow_inf_nan=False,
+        validate_default=True,
+        validate_assignment=True,
+        revalidate_instances="always",
+    )
+

macrostress-0.1.0/src/mst/corpus/README.md

@@ -0,0 +1,35 @@
+# mst.corpus
+
+Корпус источников сценария ([corpus/README.md](../../../corpus/README.md)): манифест с
+адресами оригиналов, загрузка, перевод PDF и веб-страниц в Markdown, карточки эпизодов с
+таблицами движений, индекс фрагментов и поиск по нему.
+
+```powershell
+python -m mst.corpus check --corpus DIR
+python -m mst.corpus fetch [ID ...] --corpus DIR [--force]
+python -m mst.corpus add KEY FILE [--url URL] --corpus DIR
+python -m mst.corpus convert [ID ...] --corpus DIR
+python -m mst.corpus series [SERIES ...] --corpus DIR --store DIR
+python -m mst.corpus episodes [ID ...] --corpus DIR --store DIR
+python -m mst.corpus index --corpus DIR
+python -m mst.corpus search QUERY --as-of DAY --corpus DIR
+python -m mst.corpus eval --corpus DIR
+```
+
+`--corpus` — корень корпуса в workspace (`workspace/corpus`). В git лежат только манифест,
+`series.toml`, проверочные вопросы и шаблоны (`corpus/` в корне репозитория); скачанные
+оригиналы, тексты и индекс — данные workspace.
+
+| Файл | Что делает |
+|---|---|
+| `manifest.py` | Контракты манифеста: источники и их издания, адреса оригиналов (`url` или `page` + `match`), карточки эпизодов, ряды; `Document` — один файл источника |
+| `fetch.py` | Загрузка оригиналов в `raw/`, запись в `downloads.json` с хешем и датой; файл с тем же хешем повторно не скачивается |
+| `convert.py` | PDF и веб-страница в Markdown: текстовый слой pypdf, заголовки из оглавления, колонтитулы и номера страниц выброшены, шапка с датой публикации |
+| `series.py` | Дневные ряды D1–D5 для таблиц движений: загрузчик из `mst.data` или BIS, кеш в `series/`, месячный ряд из хранилища как запасной вариант |
+| `episodes.py` | Карточка эпизода: окно, база, экстремум, изменение, дни до экстремума и восстановления; написанные руками разделы сохраняются |
+| `index.py` | Нарезка Markdown на фрагменты, `chunks.jsonl`, векторы e5, BM25 + косинус с фильтром `as_of`, recall@5 по `eval/questions.md` |
+| `embed.py` | Векторы multilingual-e5-small на CPU через ONNX Runtime |
+| `tool.py` | Операции инструмента `corpus`: `search`, `get`, `list`, `add` |
+| `cli.py`, `__main__.py` | Команда `python -m mst.corpus` |
+
+Тесты — [../../../tests/corpus](../../../tests/corpus/).

macrostress-0.1.0/src/mst/corpus/__init__.py

@@ -0,0 +1 @@
+"""The scenario corpus (corpus/README.md): manifest, downloads, texts, episode cards, search."""

macrostress-0.1.0/src/mst/corpus/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m mst.corpus``: the corpus commands, run as a task."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())