femic.hydrology.response_bundle Module
The femic.hydrology.response_bundle module owns P114.8 response and
flood-risk packaging. It builds deterministic consumer bundles, validates
manifest structure, audits artifact checksums, and exposes the pinned read
handshake for WS4 and FHOPS.
Use this page when you are packaging hydrology outputs or consuming a pinned bundle without re-running FEMIC.
Start Here If…
Use this page first if you are trying to:
build a versioned response bundle from a reproducible plan;
create a receptor-level flood-risk table;
inspect a bundle manifest and verify checksums;
understand required artifact roles; or
implement the WS4/FHOPS consumer read order.
Typical Usage
from pathlib import Path
from femic.hydrology.response_bundle import (
audit_hydrology_response_bundle,
build_hydrology_response_bundle,
load_hydrology_response_manifest,
)
result = build_hydrology_response_bundle(
Path("fixtures/response_plan.json"),
Path("runtime/hydrology/response-bundles/2026.10.0"),
)
manifest = load_hydrology_response_manifest(result.manifest_path)
audit = audit_hydrology_response_bundle(result.bundle_dir)
assert audit.is_valid
print(manifest.bundle_id, manifest.applicability_domain)
Key Entry Surfaces
build_hydrology_response_bundle()Materialize artifacts, write checksums, and emit the manifest.audit_hydrology_response_bundle()Validate the manifest and verify local artifact sizes and checksums.validate_hydrology_response_bundle()Validate manifest structure and the consumer contract.load_hydrology_response_plan()write_hydrology_response_plan()Read and write build plans.load_hydrology_response_manifest()Load a consumer manifest.build_flood_risk_table()write_flood_risk_table()read_flood_risk_table()Build and persist receptor-level flood-risk rows.FloodRiskRowFloodRiskTableFlood-risk row and table contracts.HydrologyResponsePlanHydrologyResponseManifestBuild-plan and consumer-manifest contracts.
Cross-References
Versioned hydrologic response and flood-risk bundles.
P114.8 packages response surfaces, surrogate state, frequency fits, flood-risk rows, and provenance into a pinned consumer bundle for WS4/FHOPS.
- class femic.hydrology.response_bundle.FloodRiskRow(receptor_id, watershed_id, return_period, baseline_peak_flow_m3s, scenario_peak_flow_m3s, ratio, exceedance_probability=None, expected_annual_damage=None)[source]
Bases:
objectOne receptor/return-period flood-risk record.
- Parameters:
receptor_id (str)
watershed_id (str)
return_period (float)
baseline_peak_flow_m3s (float)
scenario_peak_flow_m3s (float)
ratio (float)
exceedance_probability (float | None)
expected_annual_damage (float | None)
- baseline_peak_flow_m3s: float
- exceedance_probability: float | None = None
- expected_annual_damage: float | None = None
- ratio: float
- receptor_id: str
- return_period: float
- scenario_peak_flow_m3s: float
- watershed_id: str
- class femic.hydrology.response_bundle.FloodRiskTable(table_id, generated_utc, source_surface_id, baseline_name, rows, caveats=(), schema_version='femic.hydrology.flood_risk.v1')[source]
Bases:
objectVersioned receptor-level flood-risk table.
- Parameters:
table_id (str)
generated_utc (str)
source_surface_id (str)
baseline_name (str)
rows (tuple[FloodRiskRow, ...])
caveats (tuple[str, ...])
schema_version (str)
- baseline_name: str
- caveats: tuple[str, ...] = ()
- classmethod from_dict(payload)[source]
Load a flood-risk table from a mapping.
- Parameters:
payload (Mapping[str, object])
- Return type:
- generated_utc: str
- rows: tuple[FloodRiskRow, ...]
- schema_version: str = 'femic.hydrology.flood_risk.v1'
- source_surface_id: str
- table_id: str
- class femic.hydrology.response_bundle.HydrologyResponseArtifact(artifact_id, role, relative_path, schema_version, media_type, size_bytes, sha256, description='')[source]
Bases:
objectOne materialized response bundle artifact.
- Parameters:
artifact_id (str)
role (str)
relative_path (str)
schema_version (str | None)
media_type (str)
size_bytes (int)
sha256 (str)
description (str)
- artifact_id: str
- description: str = ''
- media_type: str
- relative_path: str
- role: str
- schema_version: str | None
- sha256: str
- size_bytes: int
- class femic.hydrology.response_bundle.HydrologyResponseArtifactAudit(artifact_id, role, relative_path, exists, size_bytes, expected_size_bytes, checksum_ok, issues=())[source]
Bases:
objectLocal file audit for one response artifact.
- Parameters:
artifact_id (str)
role (str)
relative_path (str)
exists (bool)
size_bytes (int | None)
expected_size_bytes (int)
checksum_ok (bool | None)
issues (tuple[str, ...])
- artifact_id: str
- checksum_ok: bool | None
- exists: bool
- expected_size_bytes: int
- issues: tuple[str, ...] = ()
- relative_path: str
- role: str
- size_bytes: int | None
- class femic.hydrology.response_bundle.HydrologyResponseAudit(bundle_id, bundle_dir, manifest_path, is_valid, is_complete, checked_utc, artifacts, errors, warnings)[source]
Bases:
objectValidation and local-file audit for a response bundle.
- Parameters:
bundle_id (str)
bundle_dir (Path)
manifest_path (Path)
is_valid (bool)
is_complete (bool)
checked_utc (str)
artifacts (tuple[HydrologyResponseArtifactAudit, ...])
errors (tuple[str, ...])
warnings (tuple[str, ...])
- artifacts: tuple[HydrologyResponseArtifactAudit, ...]
- bundle_dir: Path
- bundle_id: str
- checked_utc: str
- errors: tuple[str, ...]
- is_complete: bool
- is_valid: bool
- manifest_path: Path
- warnings: tuple[str, ...]
- class femic.hydrology.response_bundle.HydrologyResponseBuildResult(bundle_dir, manifest_path, manifest)[source]
Bases:
objectResult of a successful response bundle build.
- Parameters:
bundle_dir (Path)
manifest_path (Path)
manifest (HydrologyResponseManifest)
- bundle_dir: Path
- manifest: HydrologyResponseManifest
- manifest_path: Path
- exception femic.hydrology.response_bundle.HydrologyResponseError[source]
Bases:
RuntimeErrorRaised when a response plan, flood-risk table, or bundle is invalid.
- class femic.hydrology.response_bundle.HydrologyResponseManifest(bundle_id, bundle_name, bundle_version, generated_utc, domain_id, ledger_id, response_surface_id, artifacts, applicability_domain=<factory>, uncertainty=<factory>, response_surface=<factory>, flood_risk=<factory>, consumer_contract=<factory>, caveats=(), provenance=<factory>, schema_version='femic.hydrology.response.v1')[source]
Bases:
objectConsumer-facing hydrologic response bundle manifest.
- Parameters:
bundle_id (str)
bundle_name (str)
bundle_version (str)
generated_utc (str)
domain_id (str)
ledger_id (str)
response_surface_id (str)
artifacts (tuple[HydrologyResponseArtifact, ...])
applicability_domain (dict[str, object])
uncertainty (dict[str, object])
response_surface (dict[str, object])
flood_risk (dict[str, object])
consumer_contract (dict[str, object])
caveats (tuple[str, ...])
provenance (dict[str, object])
schema_version (str)
- applicability_domain: dict[str, object]
- artifacts: tuple[HydrologyResponseArtifact, ...]
- bundle_id: str
- bundle_name: str
- bundle_version: str
- caveats: tuple[str, ...] = ()
- consumer_contract: dict[str, object]
- domain_id: str
- flood_risk: dict[str, object]
- generated_utc: str
- ledger_id: str
- provenance: dict[str, object]
- response_surface: dict[str, object]
- response_surface_id: str
- schema_version: str = 'femic.hydrology.response.v1'
- to_dict()[source]
Return the manifest as a JSON-serializable mapping.
- Return type:
dict[str, object]
- uncertainty: dict[str, object]
- class femic.hydrology.response_bundle.HydrologyResponsePlan(bundle_version, domain_id, ledger_id, response_surface_id, artifacts, applicability_domain=<factory>, uncertainty=<factory>, caveats=(), provenance=<factory>, schema_version='femic.hydrology.response_plan.v1')[source]
Bases:
objectReproducible plan for one response bundle.
- Parameters:
bundle_version (str)
domain_id (str)
ledger_id (str)
response_surface_id (str)
artifacts (tuple[ResponseArtifactSpec, ...])
applicability_domain (dict[str, object])
uncertainty (dict[str, object])
caveats (tuple[str, ...])
provenance (dict[str, object])
schema_version (str)
- applicability_domain: dict[str, object]
- artifacts: tuple[ResponseArtifactSpec, ...]
- bundle_version: str
- caveats: tuple[str, ...] = ()
- domain_id: str
- ledger_id: str
- provenance: dict[str, object]
- response_surface_id: str
- schema_version: str = 'femic.hydrology.response_plan.v1'
- uncertainty: dict[str, object]
- class femic.hydrology.response_bundle.ResponseArtifactSpec(role, path, schema_version=None, description='')[source]
Bases:
objectOne planned bundle artifact.
- Parameters:
role (str)
path (str)
schema_version (str | None)
description (str)
- description: str = ''
- path: str
- role: str
- schema_version: str | None = None
- femic.hydrology.response_bundle.audit_hydrology_response_bundle(path, *, checked_utc=None)[source]
Validate a response manifest and audit local artifacts.
- Parameters:
path (Path)
checked_utc (str | None)
- Return type:
- femic.hydrology.response_bundle.build_flood_risk_table(rows, *, source_surface_id, baseline_name, generated_utc=None)[source]
Build a deterministic flood-risk table.
- Parameters:
rows (Sequence[FloodRiskRow])
source_surface_id (str)
baseline_name (str)
generated_utc (str | None)
- Return type:
- femic.hydrology.response_bundle.build_hydrology_response_bundle(plan_path, output_dir, *, overwrite=False, generated_utc=None)[source]
Build a versioned response bundle from a plan and local artifacts.
- Parameters:
plan_path (Path)
output_dir (Path)
overwrite (bool)
generated_utc (str | None)
- Return type:
- femic.hydrology.response_bundle.load_hydrology_response_manifest(path)[source]
Load a response bundle manifest from JSON.
- Parameters:
path (Path)
- Return type:
- femic.hydrology.response_bundle.load_hydrology_response_plan(path)[source]
Load a response plan from JSON.
- Parameters:
path (Path)
- Return type:
- femic.hydrology.response_bundle.read_flood_risk_table(path)[source]
Read and validate a flood-risk table.
- Parameters:
path (Path)
- Return type:
- femic.hydrology.response_bundle.validate_hydrology_response_bundle(manifest)[source]
Validate response-bundle manifest structure and consumer contract.
- Parameters:
manifest (HydrologyResponseManifest)
- Return type:
tuple[str, …]
- femic.hydrology.response_bundle.validate_hydrology_response_plan(plan)[source]
Validate a response-bundle plan.
- Parameters:
plan (HydrologyResponsePlan)
- Return type:
tuple[str, …]
- femic.hydrology.response_bundle.write_flood_risk_table(table, path)[source]
Write a flood-risk table as JSON.
- Parameters:
table (FloodRiskTable)
path (Path)
- Return type:
Path
- femic.hydrology.response_bundle.write_hydrology_response_plan(plan, path)[source]
Write a response plan as JSON.
- Parameters:
plan (HydrologyResponsePlan)
path (Path)
- Return type:
Path