Metadata-Version: 2.4
Name: balabs-risk-kernel
Version: 0.2.1
Summary: Risk model liquidation kernels (v2 + v3) — 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 liquidation kernels 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 / #537).

Two model namespaces, mirrored from core:

- `risk_kernel.v2` — the v2 liquidation-simulation kernel. Operates on
  in-memory `PricePaths` / `SellOrderbook` / `BorrowerPosition` structures
  (`risk_kernel.v2.liquidator.types`).
- `risk_kernel.v3` — the v3 market-clearing kernel: clearing kernel, impact
  law, CRR stats, liquidation-wall curve math, FHS residuals/simulator.
  Entry points `risk_kernel.v3.kernel.run_clearing_kernel` /
  `run_multi_asset_kernel` on `KernelInputs` / `MultiAssetKernelInputs`.

Loading inputs from a database is the consumer's job, never this package's.

## Consumers

- **core-api** — installs this package from PyPI (`balabs-risk-kernel`) and
  runs the kernels in-process for the estimator endpoint.
- **core** — NOT hooked up yet, deliberately out of scope for now. core keeps
  its own in-tree copies at `src/risk_model_v2/` and `src/risk_model_v3/` 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
kernels. Per-model pins (the subtrees sync at different cadences):

- **v2** source: **blockanalitica/core** `src/risk_model_v2/liquidator/`
  commit: **`c0bb2732e51cbb2338e0db5f49799088529e003c`** (main, 2026-07-03)
- **v3** source: **blockanalitica/core** `src/risk_model_v3/`
  commit: **`0d0695dda00bafe99ad3294958203a7da98f76fd`** (PR #78, 2026-07-13)

Kernel changes land in **core first** (production model), then get pulled
here, per model:

```sh
git -C ../core diff <v2-pinned-commit>..main -- src/risk_model_v2/liquidator/
git -C ../core diff <v3-pinned-commit>..main -- src/risk_model_v3/
```

Apply the changes to `src/risk_kernel/v2/` / `src/risk_kernel/v3/`, bump the
model's 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/v2/liquidator/
diff -r ../core/src/risk_model_v3/ src/risk_kernel/v3/
```

There is no test guardrail — the pins are the only drift baseline.

## Deliberate divergences from core (the ONLY ones allowed)

### v2

1. **Persistence stripped** from `v2/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.v2.liquidator` (mechanical import rewrite; tree structure is
   otherwise 1:1 so the diff above works).
3. **`v2/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 kernels import from outside the mirrored subtrees.

### v3

1. **Impure modules excluded** — only the pure compute modules are mirrored:
   `kernel`, `impact`, `stats`, `types`, `constants`,
   `liquidation_wall/{builder,flow,types}`, `fhs/{residuals,simulator}`.
   Excluded: `models`, `persistence`, `pipeline/`, `tasks`, `calibration`,
   `liquidation_wall/{fetcher,sources}`, `fhs/forecaster`. Mirrored modules
   import only numpy/stdlib/each other (`v3 → v2.constants` allowed,
   mirroring core's `fhs/simulator.py`).
2. **Package renamed**: core's `risk_model_v3` → `risk_kernel.v3`,
   `risk_model_v2` → `risk_kernel.v2` (mechanical import rewrite, applies to
   docstrings too).

Anything else diverging from core = drift = bug.
