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. After ci.yml passes on main, release.yml runs python-semantic-release to create a tag and GitHub release, then dispatches publish.yml to build that tag and publish to PyPI with OIDC. Package versions come from Git tags; no version-bump commit is needed.
3. Bump the pin in consumers (core, core-api pyproject.toml).

The PyPI trusted publisher for balabs-risk-kernel must authorize the publish.yml workflow. To retry a publish, manually run Publish with the existing release tag as its tag input.

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.