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.