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.

  • FloodRiskRow

  • FloodRiskTable Flood-risk row and table contracts.

  • HydrologyResponsePlan

  • HydrologyResponseManifest Build-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: object

One 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
to_dict()[source]

Return the row as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

Versioned 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:

FloodRiskTable

generated_utc: str
rows: tuple[FloodRiskRow, ...]
schema_version: str = 'femic.hydrology.flood_risk.v1'
source_surface_id: str
table_id: str
to_dict()[source]

Return the table as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.response_bundle.HydrologyResponseArtifact(artifact_id, role, relative_path, schema_version, media_type, size_bytes, sha256, description='')[source]

Bases: object

One 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
to_dict()[source]

Return the artifact as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.response_bundle.HydrologyResponseArtifactAudit(artifact_id, role, relative_path, exists, size_bytes, expected_size_bytes, checksum_ok, issues=())[source]

Bases: object

Local 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
to_dict()[source]

Return the artifact audit as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.response_bundle.HydrologyResponseAudit(bundle_id, bundle_dir, manifest_path, is_valid, is_complete, checked_utc, artifacts, errors, warnings)[source]

Bases: object

Validation 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
to_dict()[source]

Return the audit as a JSON-serializable mapping.

Return type:

dict[str, object]

warnings: tuple[str, ...]
class femic.hydrology.response_bundle.HydrologyResponseBuildResult(bundle_dir, manifest_path, manifest)[source]

Bases: object

Result of a successful response bundle build.

Parameters:
bundle_dir: Path
manifest: HydrologyResponseManifest
manifest_path: Path
to_dict()[source]

Return the build result as a JSON-serializable mapping.

Return type:

dict[str, object]

exception femic.hydrology.response_bundle.HydrologyResponseError[source]

Bases: RuntimeError

Raised 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: object

Consumer-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: object

Reproducible 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'
to_dict()[source]

Return the plan as a JSON-serializable mapping.

Return type:

dict[str, object]

uncertainty: dict[str, object]
class femic.hydrology.response_bundle.ResponseArtifactSpec(role, path, schema_version=None, description='')[source]

Bases: object

One 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
to_dict()[source]

Return the artifact spec as a JSON-serializable mapping.

Return type:

dict[str, object]

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:

HydrologyResponseAudit

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:

FloodRiskTable

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:

HydrologyResponseBuildResult

femic.hydrology.response_bundle.load_hydrology_response_manifest(path)[source]

Load a response bundle manifest from JSON.

Parameters:

path (Path)

Return type:

HydrologyResponseManifest

femic.hydrology.response_bundle.load_hydrology_response_plan(path)[source]

Load a response plan from JSON.

Parameters:

path (Path)

Return type:

HydrologyResponsePlan

femic.hydrology.response_bundle.read_flood_risk_table(path)[source]

Read and validate a flood-risk table.

Parameters:

path (Path)

Return type:

FloodRiskTable

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:
Return type:

Path

femic.hydrology.response_bundle.write_hydrology_response_plan(plan, path)[source]

Write a response plan as JSON.

Parameters:
Return type:

Path