crp.ml¶
Auto-generated reference for the crp.ml subpackage.
ml¶
crp.ml ¶
Managed ML model registry for optional-but-default-on CRP components.
ModelLoadError ¶
Bases: Exception
Raised when a model cannot be loaded within budget.
ModelManager ¶
Central registry for ML models used by CRP subsystems.
register(key, loader, *, budget_ms=50.0, load_timeout_ms=30000.0, device=None, cache_dir=None) ¶
Register a model loader without loading it.
unregister(key) ¶
Drop a model from the registry and release its instance.
is_available(key) ¶
True if the model is currently loaded and usable.
load(key) ¶
Load (or return cached) the model for key.
Returns None if the model is not registered, already failed, or cannot be loaded within its load budget. Never raises.
run(key, fn, *, budget_ms=None, fallback=None) ¶
Run fn(model) under a latency budget.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Registered model key. | required |
fn | Callable[[Any], Any] | Callable receiving the loaded model and returning a result. | required |
budget_ms | float | None | Per-call budget. Defaults to the registered spec budget. | None |
fallback | Any | Value returned if model is unavailable or fn exceeds budget. | None |
Returns:
| Type | Description |
|---|---|
Any |
|
clear() ¶
Unload all models and reset error state.
reset(key) ¶
Unload the model for key while keeping its registered spec.
Useful for test isolation: the loader stays registered so the next call to :meth:load or :meth:run will re-load the model.
shutdown() ¶
Release resources.
download_all(model_dir=None) ¶
Download every model in the manifest. Returns {key: local_path}.
download_model(key, model_dir=None) ¶
Download the model for key into model_dir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Manifest key (e.g. | required |
model_dir | str | None | Target root directory. Defaults to | None |
Returns:
| Type | Description |
|---|---|
str | Local path of the downloaded snapshot. |
load_manifest() ¶
Load the canonical model registry manifest.
model_location(key, model_dir=None) ¶
Return the local snapshot path for key if present, else the HF repo id.
Lets callers pass the result straight to from_pretrained-style loaders: a local directory when the model has been downloaded, the hub repo id otherwise.
managed_call(key, fn, *, budget_ms=None, fallback=None) ¶
Convenience wrapper around the global manager.
register_model(key, loader, *, budget_ms=50.0, load_timeout_ms=30000.0) ¶
Convenience wrapper to register a model on the global manager.
timed_fallback(budget_ms, fallback) ¶
Decorator that runs a function under budget_ms and returns fallback on timeout.
The wrapped function receives the model as its first argument; the model is fetched from the registry using the argument name model_key if present.
ml.downloader¶
crp.ml.downloader ¶
Model manifest and downloader for CRPv6 Phase A (ML-first SDK).
The canonical model registry lives in :file:crp/ml/manifest.json. This module reads that manifest and downloads models from Hugging Face via huggingface_hub.snapshot_download into CRP_MODEL_DIR (default ./crp_models/<local_name>). huggingface_hub is imported lazily inside the download functions so the zero-dependency core never pays an import-time cost.
Keys in the manifest match the registry keys used by :mod:crp.ml.registry (e.g. crp.isa.intent), so a downloaded model can be passed to the registry loaders through the same environment variables (CRP_INTENT_MODEL, CRP_SAFETY_MODEL).
load_manifest() ¶
Load the canonical model registry manifest.
download_model(key, model_dir=None) ¶
Download the model for key into model_dir.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Manifest key (e.g. | required |
model_dir | str | None | Target root directory. Defaults to | None |
Returns:
| Type | Description |
|---|---|
str | Local path of the downloaded snapshot. |
download_all(model_dir=None) ¶
Download every model in the manifest. Returns {key: local_path}.
model_location(key, model_dir=None) ¶
Return the local snapshot path for key if present, else the HF repo id.
Lets callers pass the result straight to from_pretrained-style loaders: a local directory when the model has been downloaded, the hub repo id otherwise.
ml.registry¶
crp.ml.registry ¶
Managed ML model registry - lazy, budgeted, with deterministic fallbacks.
CRP's ML-driven components are default-on when their optional dependencies are installed, but they are never allowed to block the governance loop. The registry loads models on first use, caches them, enforces a per-call latency budget, and degrades to a rule-based fallback if the model is missing, slow, or raises. This makes ML enhancement mandatory-in-presence without storming resources.
ModelSpec dataclass ¶
Specification for a lazily-loaded model.
ModelLoadError ¶
Bases: Exception
Raised when a model cannot be loaded within budget.
ModelManager ¶
Central registry for ML models used by CRP subsystems.
register(key, loader, *, budget_ms=50.0, load_timeout_ms=30000.0, device=None, cache_dir=None) ¶
Register a model loader without loading it.
unregister(key) ¶
Drop a model from the registry and release its instance.
is_available(key) ¶
True if the model is currently loaded and usable.
load(key) ¶
Load (or return cached) the model for key.
Returns None if the model is not registered, already failed, or cannot be loaded within its load budget. Never raises.
run(key, fn, *, budget_ms=None, fallback=None) ¶
Run fn(model) under a latency budget.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Registered model key. | required |
fn | Callable[[Any], Any] | Callable receiving the loaded model and returning a result. | required |
budget_ms | float | None | Per-call budget. Defaults to the registered spec budget. | None |
fallback | Any | Value returned if model is unavailable or fn exceeds budget. | None |
Returns:
| Type | Description |
|---|---|
Any |
|
clear() ¶
Unload all models and reset error state.
reset(key) ¶
Unload the model for key while keeping its registered spec.
Useful for test isolation: the loader stays registered so the next call to :meth:load or :meth:run will re-load the model.
shutdown() ¶
Release resources.
managed_call(key, fn, *, budget_ms=None, fallback=None) ¶
Convenience wrapper around the global manager.
register_model(key, loader, *, budget_ms=50.0, load_timeout_ms=30000.0) ¶
Convenience wrapper to register a model on the global manager.
timed_fallback(budget_ms, fallback) ¶
Decorator that runs a function under budget_ms and returns fallback on timeout.
The wrapped function receives the model as its first argument; the model is fetched from the registry using the argument name model_key if present.
ml.torch_threads¶
crp.ml.torch_threads ¶
Sanctioned torch intra-op thread-pool guard for model loading (U-C1).
torch.set_num_threads mutates a process-global intra-op thread pool. Library code must NEVER call it directly: a host application that has deliberately capped torch threads (e.g. WASA throttling threads under RAM pressure) would have that cap silently reset, and concurrent in-flight inference in other threads would be re-throttled mid-flight. Production audit U-C1 (wasa_crp_production_audit) classifies any bare torch.set_num_threads(cpu_count()) in library code as a HIGH-severity wedge mechanism.
All CRP model loaders route through :func:single_threaded_load, which:
- saves the host's prior setting,
- caps the pool to
CRP_TORCH_THREADS(default1, win32 only) during the load-time OpenMP duplicate-runtime race window described incrp/__init__.py, and - restores the prior value in a
finallyblock - even on load failure.
CRP_TORCH_THREADS semantics:
- unset → cap to 1 on win32 during load, restore after (default, preserves the load-time crash guard),
off/never/0→ never touch torch threads at all,- positive int → use that value as the load-time cap.
NOTE: the setting is process-global, so two threads loading simultaneously can still observe each other's cap for the duration of the load. The window is short (model weight loading only) and the prior value is always restored; a per-process loader lock is deliberately NOT taken here to avoid serialising independent loads.
load_thread_cap() ¶
Resolve the load-time thread cap from CRP_TORCH_THREADS.
Returns the cap (>=1) to apply while loading a model, or None when torch's thread pool must be left untouched entirely.
single_threaded_load() ¶
Cap torch intra-op threads for the duration of a model load, then restore.
No-op on non-Windows platforms and when CRP_TORCH_THREADS opts out. The host's prior value is restored in a finally block even if the load raises. This is the ONLY sanctioned place in the library that may call torch.set_num_threads - the conformance test tests/test_torch_thread_guard.py::test_no_bare_set_num_threads_in_library greps the tree and fails on any other call site.