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.