Metadata-Version: 2.5
Name: balabs-risk-kernel
Version: 1.0.0
Summary: Risk model kernels (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. This package is the **source of
truth for kernel logic**: both `core` and `core-api` install it and run the
kernels in-process.

One model namespace 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`.

The Laniakea concentration engine (`risk_kernel.concentration`, 0.3.0–0.7.x)
moved into core in office #1329 (core ADR 0006): its September 2026 methodology
is portfolio-dependent per position and reads history series at run time, so
it no longer fits a pure-constants kernel.

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.
