Metadata-Version: 2.4
Name: balabs-risk-kernel
Version: 0.4.0
Summary: Risk model kernels (v2, v3, concentration) — 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
Provides-Extra: concentration
Requires-Dist: cvxpy; extra == 'concentration'
Requires-Dist: pandas; extra == 'concentration'
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. This package is the **source of
truth for kernel logic**: both `core` and `core-api` install it and run the
kernels in-process.

Three model namespaces plus one shared:

- `risk_kernel.common` — model-version-neutral vocabulary shared by every
  consumer: the liquidator dataclass contract (`BorrowerPosition`,
  `MarketDescriptor`, `MarketContext`, `PricePaths`, `SellOrderbook`,
  `CRRSummary`, …) and `slippage_for_amount`. Promoted out of
  `risk_kernel.v2` (office #863) so v2 can be retired without breaking the
  surviving consumers.
- `risk_kernel.v2` — the v2 liquidation-simulation kernel. Operates on
  in-memory `PricePaths` / `SellOrderbook` / `BorrowerPosition` structures
  (defined in `risk_kernel.common.types`, re-exported unchanged at
  `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`.
- `risk_kernel.concentration` — the Laniakea correlation-framework
  concentration engine: position classification, L(category, scenario) loss
  matrix, Method A/B exposure caps (`classify.classify_positions` →
  `loss.build_loss_matrix` → `caps.method_a` / `caps.method_b`).
  `calibration.py` holds the generated factor shocks / static losses; number
  changes land as ordinary constants PRs referencing the analysis-repo run.
  Needs the `concentration` extra
  (`balabs-risk-kernel[concentration]` — pandas + cvxpy); the base install
  stays numpy-only, so importing the namespace without the extra fails at
  import time.

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

## Consumers

Both install `balabs-risk-kernel` from PyPI and run the kernels in-process:

- **core** — the production risk model. Consumes the pure kernel here and keeps
  only the impure orchestration in-tree (`src/risk_model_v2/`, `src/risk_model_v3/`:
  datasources, pipelines, tasks, models, persistence, calibration). The pure
  compute modules were removed from core in office #553 — they live here now.
- **core-api** — runs the kernels for the on-demand LTV↔CRR estimator endpoint
  (office #490 / #537).

Both currently pin `balabs-risk-kernel==0.2.1`.

## Change flow

Kernel logic changes land **here first**. Release, then bump consumers:

1. Make the change in `src/risk_kernel/v2/` or `src/risk_kernel/v3/`.
2. Merge with a conventional-commit message — `release.yml` runs
   `python-semantic-release`, which bumps the version and publishes to PyPI.
3. Bump the pin in consumers (`core`, `core-api` `pyproject.toml`).

There is no per-model commit pin and no diff-against-core sync step: this repo no
longer mirrors core. core is a consumer, not the origin.

## What the package deliberately excludes

The kernels here are pure compute only — the impure layers that live in core
(datasources, pipelines, persistence, tasks, calibration, forecasters, wall
fetchers/sources) are intentionally **not** vendored.

The one non-obvious exclusion, carried over from when this repo was seeded from
core: the v2 persistence path is 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
`sync()` call sites, and the `risk_model_v2.models` import block). `sync()`
computes and returns `CRRSummary` objects, nothing else. `pipeline/scenario_paths.py`
is unused after the strip but kept verbatim.
