balabs-risk-kernel 0.1.1__tar.gz

balabs_risk_kernel-0.1.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+dist/

balabs_risk_kernel-0.1.1/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: balabs-risk-kernel
+Version: 0.1.1
+Summary: Risk model v2 liquidation kernel — pure compute, no DB access
+Author-email: Twigmaester <81682766+Twigmaester@users.noreply.github.com>
+Requires-Python: <3.15,>=3.13
+Requires-Dist: numpy<3,>=2.1
+Description-Content-Type: text/markdown
+
+# risk-kernel
+
+The risk model v2 liquidation-simulation kernel as a standalone package —
+pure compute (numpy + stdlib), zero DB access, no write path. Powers the
+on-demand LTV↔CRR estimator endpoint in `core-api` (office #490).
+
+The kernel operates on in-memory `PricePaths` / `SellOrderbook` /
+`BorrowerPosition` structures (`risk_kernel.liquidator.types`); loading those
+inputs from a database is the consumer's job, never this package's.
+
+## Consumers
+
+- **core-api** — installs this package from PyPI (`risk-kernel`) and runs the
+  kernel in-process for the estimator endpoint.
+- **core** — NOT hooked up yet, deliberately out of scope for now. core keeps
+  its own in-tree copy at `src/risk_model_v2/liquidator/` and remains the
+  production source of truth for kernel logic.
+
+## Source of truth & sync protocol
+
+Until core itself consumes this package, this repo is a **mirror** of core's
+kernel, pinned to:
+
+- source: **blockanalitica/core** `src/risk_model_v2/liquidator/`
+- commit: **`c0bb2732e51cbb2338e0db5f49799088529e003c`** (main, 2026-07-03)
+
+Kernel changes land in **core first** (production model), then get pulled
+here:
+
+```sh
+git -C ../core diff <pinned-commit>..main -- src/risk_model_v2/liquidator/
+```
+
+Apply the changes to `src/risk_kernel/`, bump the pin above and the package
+version, then bump the pin in consumers. The divergences below are expected
+diff noise; everything else must match, e.g.:
+
+```sh
+diff -r ../core/src/risk_model_v2/liquidator/ src/risk_kernel/liquidator/
+```
+
+There is no test guardrail — the pin is the only drift baseline.
+
+## Deliberate divergences from core (the ONLY ones allowed)
+
+1. **Persistence stripped** from `liquidator/pipeline/processors/liquidator.py`:
+   the `_persist_market_crr` / `_persist_scenario_paths` /
+   `_rewrite_market_crr_tiers` / `_prune_market_crr_snapshot24` methods, their
+   call sites in `sync()`, the `risk_model_v2.models` import block, and the
+   imports only they used (`asdict`, `timedelta`,
+   `MARKET_CRR_SNAPSHOT24_RETENTION_DAYS`, `CapturedScenarioPaths`,
+   `select_bands`). `sync()` computes and returns `CRRSummary` objects,
+   nothing else. `pipeline/scenario_paths.py` is unused after the strip but
+   kept verbatim so the drift diff stays trivial.
+2. **Package renamed**: core's `risk_model_v2.liquidator` → `risk_kernel.liquidator`
+   (mechanical import rewrite; tree structure is otherwise 1:1 so the diff
+   above works).
+3. **`constants.py` is a 3-constant subset** of core's
+   `src/risk_model_v2/constants.py` (`FORECAST_STEP`, `N_MC`, `SEED`) — the
+   only values the kernel imports from outside the liquidator subtree.
+
+Anything else diverging from core = drift = bug.

balabs_risk_kernel-0.1.1/README.md

@@ -0,0 +1,62 @@
+# risk-kernel
+
+The risk model v2 liquidation-simulation kernel as a standalone package —
+pure compute (numpy + stdlib), zero DB access, no write path. Powers the
+on-demand LTV↔CRR estimator endpoint in `core-api` (office #490).
+
+The kernel operates on in-memory `PricePaths` / `SellOrderbook` /
+`BorrowerPosition` structures (`risk_kernel.liquidator.types`); loading those
+inputs from a database is the consumer's job, never this package's.
+
+## Consumers
+
+- **core-api** — installs this package from PyPI (`risk-kernel`) and runs the
+  kernel in-process for the estimator endpoint.
+- **core** — NOT hooked up yet, deliberately out of scope for now. core keeps
+  its own in-tree copy at `src/risk_model_v2/liquidator/` and remains the
+  production source of truth for kernel logic.
+
+## Source of truth & sync protocol
+
+Until core itself consumes this package, this repo is a **mirror** of core's
+kernel, pinned to:
+
+- source: **blockanalitica/core** `src/risk_model_v2/liquidator/`
+- commit: **`c0bb2732e51cbb2338e0db5f49799088529e003c`** (main, 2026-07-03)
+
+Kernel changes land in **core first** (production model), then get pulled
+here:
+
+```sh
+git -C ../core diff <pinned-commit>..main -- src/risk_model_v2/liquidator/
+```
+
+Apply the changes to `src/risk_kernel/`, bump the pin above and the package
+version, then bump the pin in consumers. The divergences below are expected
+diff noise; everything else must match, e.g.:
+
+```sh
+diff -r ../core/src/risk_model_v2/liquidator/ src/risk_kernel/liquidator/
+```
+
+There is no test guardrail — the pin is the only drift baseline.
+
+## Deliberate divergences from core (the ONLY ones allowed)
+
+1. **Persistence stripped** from `liquidator/pipeline/processors/liquidator.py`:
+   the `_persist_market_crr` / `_persist_scenario_paths` /
+   `_rewrite_market_crr_tiers` / `_prune_market_crr_snapshot24` methods, their
+   call sites in `sync()`, the `risk_model_v2.models` import block, and the
+   imports only they used (`asdict`, `timedelta`,
+   `MARKET_CRR_SNAPSHOT24_RETENTION_DAYS`, `CapturedScenarioPaths`,
+   `select_bands`). `sync()` computes and returns `CRRSummary` objects,
+   nothing else. `pipeline/scenario_paths.py` is unused after the strip but
+   kept verbatim so the drift diff stays trivial.
+2. **Package renamed**: core's `risk_model_v2.liquidator` → `risk_kernel.liquidator`
+   (mechanical import rewrite; tree structure is otherwise 1:1 so the diff
+   above works).
+3. **`constants.py` is a 3-constant subset** of core's
+   `src/risk_model_v2/constants.py` (`FORECAST_STEP`, `N_MC`, `SEED`) — the
+   only values the kernel imports from outside the liquidator subtree.
+
+Anything else diverging from core = drift = bug.

balabs_risk_kernel-0.1.1/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "balabs-risk-kernel"
+dynamic = ["version"]
+description = "Risk model v2 liquidation kernel — pure compute, no DB access"
+authors = [{name="Twigmaester", email="81682766+Twigmaester@users.noreply.github.com"}]
+readme = "README.md"
+license-files = ["LICEN[CS]E*"]
+requires-python = ">=3.13,<3.15"
+dependencies = [
+    "numpy>=2.1,<3",
+]
+
+[dependency-groups]
+dev = [
+    "ruff==0.15.4",
+]
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+indent-width = 4
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+unfixable = []
+extend-select = [
+    "YTT", # flake8-2020
+    "B", # flake8-bugbear
+    "A", # flake8-builtins
+    "C4", # flake8-comprehensions
+    "SIM", # flake8-simplify
+    "PIE", # flake8-pie
+    "DTZ", # flake8-datetimez
+    "I", # isort
+    "E", # pycodestyle
+    "W", # pycodestyle
+    "F", # pyflakes
+    "UP", # pyupgrade
+    "N", # pep8-naming
+    "PERF", # Perflint
+]
+# Kernel code must stay diffable against core's src/risk_model_v2/liquidator/
+# (see README) — rules that would force edits there are off.
+ignore = ["B905", "SIM108", "PERF401"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "lf"
+
+[build-system]
+requires = ["hatchling>=1.29.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/risk_kernel/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/risk_kernel"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/**", "pyproject.toml", "README*", "LICENSE*"]
+
+[tool.semantic_release]
+commit_message = "chore(release): {version}"
+version_variables = ["src/risk_kernel/__init__.py:__version__"]
+allow_zero_version = true

balabs_risk_kernel-0.1.1/src/risk_kernel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

balabs_risk_kernel-0.1.1/src/risk_kernel/constants.py

@@ -0,0 +1,8 @@
+# Minimal subset of core's src/risk_model_v2/constants.py — only the values
+# the vendored liquidator kernel imports. Values must match upstream at the
+# commit pinned in README.md.
+
+FORECAST_STEP = 14
+N_MC = 10_000
+
+SEED = 0

balabs_risk_kernel-0.1.1/src/risk_kernel/liquidator/constants.py

@@ -0,0 +1,35 @@
+from decimal import Decimal
+
+# Protocols that use the Maple-style margin-call cure.
+# When MarketContext.protocol matches one of these and margin_call_enabled is
+# left as None, the liquidator turns margin calls on. Override the flag to opt
+# in/out.
+MARGIN_CALL_DEFAULT_PROTOCOLS = frozenset({"maple"})
+
+# Aave-v3 / Sparklend dual close-factor regime: hf < HF_FULL_CLOSE → liquidate 100%
+# of debt; otherwise → liquidate 50% (the standard aave-v3 close factor).
+AAVE_LIKE_PROTOCOLS = frozenset({"aave_v3", "sparklend"})
+HF_FULL_CLOSE = 0.95
+CLOSE_FACTOR_FULL = 1.0
+CLOSE_FACTOR_PARTIAL = 0.5
+
+# CRR_adj penalty steepness for the HHI concentration surcharge:
+#   crr_adj = crr_el * (1 + CRR_HHI_K * hhi)
+CRR_HHI_K = Decimal("1.0")
+
+# Hardcoded policy minimum CRR carried by every market, persisted as `crr_floor`.
+# Stored alongside the computed CRR values, never applied to them.
+CRR_FLOOR = Decimal("0.02")
+
+# Slippage cap — a forced sale recovers at least (1 - MAX_SLIPPAGE) of the
+# collateral's value at the simulated price, even when the price has fallen
+# below the snapshot book or the book is exhausted. Floors recovery at 50%.
+MAX_SLIPPAGE = 0.50
+
+# Retention for the rolling intra-day `*Snapshot24` CRR tables, pruned once at
+# the start of each run. Matches the orderbook SNAPSHOT24_RETENTION_DAYS.
+MARKET_CRR_SNAPSHOT24_RETENTION_DAYS = 2
+
+# Lower bound used when normalising into ratios — prevents div-by-zero without
+# materially perturbing the result.
+EPS = 1e-12