Integrity Pipeline
Overview
kavai.integrity turns inspection and sensor data into governed integrity findings, grounded in API 571 (damage mechanisms) and API 584 (Integrity Operating Windows). It is a set of typed stages plus packaged reference data, exposed over feature-gated contract endpoints.
Stages
integrity/stages/:
| Stage | Contract | Role |
|---|---|---|
ingest.py |
— | Normalize incoming readings / inspection records. |
classify.py |
CONTRACT-IOW-001 | IOW classification — detect Integrity-Operating-Window exceedances from validated readings + limits. |
damage_map.py |
CONTRACT-DMR-001 | Damage Mechanism Review — map exceedances (or a screening profile) to credible API 571 mechanisms. |
consistency_gate.py |
— | Cross-check findings for consistency before they surface. |
Typed I/O lives in integrity/schemas.py (ClassifyResult, IOWStatusResponse, DamageMappingResult, DamageFindingOutput, …).
Reference data
integrity/data/ (packaged YAML + loaders):
api_571_damage_mechanisms.yaml,api_571_process_unit_mappings.yaml— the API 571 catalogue and process-unit applicability, read viaapi_571.py/loader.py.api_584_iow_parameters.yaml— IOW parameter definitions.
Contract endpoints
kavai.api.integrity_contract mounts the router at /api/integrity, gated by KAVAI_FF_INTEGRITY_PIPELINE=true and backed by integrity_contract_store.py:
| Method & path | Returns | Contract |
|---|---|---|
POST /api/integrity/iow/classify |
ClassifyResult |
CONTRACT-IOW-001 |
GET /api/integrity/iow/{equipment_id}/status |
IOWStatusResponse |
CONTRACT-IOW-001 |
POST /api/integrity/dmr/identify |
DamageMappingResult |
CONTRACT-DMR-001 |
GET /api/integrity/dmr/{equipment_id}/mechanisms |
list[DamageFindingOutput] |
CONTRACT-DMR-001 |
These reuse the stage implementations and mirror the /api/v1/integrity/* routes (api/v1/integrity.py; api/v1/ also serves equipment, health, and iow).
How these findings reach the workspace UI (seeding equipment, populating equipment_damage_mechanisms, the geo-linked evidence) is covered by the integrity finding-population work in docs/proposals/, not this handbook.