Metadata-Version: 2.5
Name: balabs-risk-kernel
Version: 0.6.0
Summary: Risk model kernels (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.

Two 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`.
- `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/core_model/`: 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 pin an exact `balabs-risk-kernel` release in their `pyproject.toml`.

## Change flow

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

1. Make the change in `src/risk_kernel/`.
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.
