swatplus-builder 0.4.0__py3-none-any.whl

swatplus_builder/__init__.py

@@ -0,0 +1,26 @@
+"""swatplus_builder — headless, agent-friendly generator for SWAT+ project inputs.
+
+Public surface is intentionally tiny. See :mod:`swatplus_builder.tools` for the four
+agent-facing functions, or :mod:`swatplus_builder.cli` for the Typer CLI.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+__version__ = "0.4.0"
+
+__all__ = ["__version__"]
+
+
+def _ensure_writable_matplotlib_config_dir() -> None:
+    if os.environ.get("MPLCONFIGDIR"):
+        return
+    cfg = Path(tempfile.gettempdir()) / "swatplus_builder_mplconfig"
+    cfg.mkdir(parents=True, exist_ok=True)
+    os.environ["MPLCONFIGDIR"] = str(cfg)
+
+
+_ensure_writable_matplotlib_config_dir()

swatplus_builder/artifacts/__init__.py

@@ -0,0 +1,34 @@
+"""Typed run-artifact schemas and hashing helpers.
+
+Phase 3B introduces a canonical artifact contract under ``runs/<content_hash>/``.
+This package defines the typed JSON payloads and deterministic hash utilities
+that power content-addressed caching.
+"""
+
+from .models import (
+    ArtifactMetadata,
+    ArtifactQuery,
+    ArtifactMetrics,
+    ArtifactProvenance,
+    ArtifactRecord,
+    ArtifactSummary,
+    OutletMetadata,
+    RunConfig,
+)
+from .hashing import canonical_config_json, compute_content_hash
+from .store import ArtifactStore, LocalArtifactStore
+
+__all__ = [
+    "ArtifactMetadata",
+    "ArtifactQuery",
+    "ArtifactMetrics",
+    "ArtifactProvenance",
+    "ArtifactRecord",
+    "ArtifactSummary",
+    "ArtifactStore",
+    "LocalArtifactStore",
+    "OutletMetadata",
+    "RunConfig",
+    "canonical_config_json",
+    "compute_content_hash",
+]

swatplus_builder/artifacts/hashing.py

@@ -0,0 +1,49 @@
+"""Deterministic content-hash utilities for run artifacts.
+
+Content hash contract (Roadmap Appendix A):
+
+    SHA256(canonical_json(config) || engine_version || builder_git_sha)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from .models import RunConfig
+
+
+def canonical_config_json(config: RunConfig | dict[str, object]) -> bytes:
+    """Return canonical UTF-8 JSON bytes for content hashing.
+
+    Canonicalization rules:
+    - sorted keys
+    - no extra whitespace
+    - UTF-8 encoding
+    """
+    payload: dict[str, object]
+    if isinstance(config, RunConfig):
+        payload = config.model_dump(mode="json")
+    else:
+        payload = RunConfig.model_validate(config).model_dump(mode="json")
+    txt = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return txt.encode("utf-8")
+
+
+def compute_content_hash(
+    config: RunConfig | dict[str, object],
+    *,
+    engine_version: str,
+    builder_git_sha: str,
+) -> str:
+    """Compute the Phase 3B content hash.
+
+    Failure modes:
+    - Raises `pydantic.ValidationError` when `config` is invalid.
+    """
+    h = hashlib.sha256()
+    h.update(canonical_config_json(config))
+    h.update(engine_version.encode("utf-8"))
+    h.update(builder_git_sha.encode("utf-8"))
+    return h.hexdigest()
+

swatplus_builder/artifacts/models.py

@@ -0,0 +1,128 @@
+"""Pydantic schemas for Phase 3B run artifacts.
+
+These models correspond to the JSON files defined in `ROADMAP.md` Appendix A:
+`config.json`, `metadata.json`, `metrics.json`, and `provenance.json`.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Literal, TypeAlias
+
+from pydantic import BaseModel, Field
+
+JsonScalar: TypeAlias = str | int | float | bool | None
+
+
+class ParameterValue(BaseModel):
+    """One calibration parameter assignment within `config.parameters`."""
+
+    value: float = Field(..., description="Numeric parameter value.")
+    scope: Literal["global", "hru", "subbasin", "channel"] = Field(
+        ..., description="Application scope for this parameter value."
+    )
+
+
+class RunConfig(BaseModel):
+    """Artifact `config.json` model used for content hashing."""
+
+    basin_id: str = Field(..., min_length=1)
+    bbox: tuple[float, float, float, float] | None = Field(
+        default=None,
+        description="Bounding box [minx, miny, maxx, maxy] in lon/lat.",
+    )
+    simulation_start: date = Field(...)
+    simulation_end: date = Field(...)
+    parameters: dict[str, ParameterValue] = Field(default_factory=dict)
+    options: dict[str, JsonScalar] = Field(default_factory=dict)
+
+
+class OutletMetadata(BaseModel):
+    """Outlet selection metadata in `metadata.json`."""
+
+    gis_id: int | None = Field(default=None)
+    auto_detected: bool = Field(default=False)
+    reason: str | None = Field(default=None)
+
+
+class ArtifactMetadata(BaseModel):
+    """Artifact `metadata.json` model (provenance, non-hash inputs)."""
+
+    run_id: str | None = Field(default=None, description="Content hash / run identifier.")
+    timestamp_utc: str = Field(..., description="UTC ISO-8601 timestamp.")
+    engine_version: str | None = Field(default=None)
+    builder_version: str | None = Field(default=None)
+    git_sha: str | None = Field(default=None)
+    outlet: OutletMetadata | None = Field(default=None)
+    soil_mode: Literal["high_fidelity", "fallback", "synthetic"] | None = Field(default=None)
+    pct_fallback_soils: float | None = Field(default=None, ge=0.0, le=1.0)
+    weather_coverage: dict[str, float] = Field(default_factory=dict)
+    n_subbasins: int | None = Field(default=None, ge=0)
+    n_hrus: int | None = Field(default=None, ge=0)
+    runtime_seconds: float | None = Field(default=None, ge=0.0)
+
+
+class MetricsPeriod(BaseModel):
+    """Evaluation period included in `metrics.json`."""
+
+    start: date = Field(...)
+    end: date = Field(...)
+
+
+class ArtifactMetrics(BaseModel):
+    """Artifact `metrics.json` model."""
+
+    outlet_id: int | None = Field(default=None)
+    period: MetricsPeriod | None = Field(default=None)
+    nse: float | None = Field(default=None)
+    log_nse: float | None = Field(default=None)
+    kge: float | None = Field(default=None)
+    pbias: float | None = Field(default=None)
+    bfi_observed: float | None = Field(default=None)
+    bfi_simulated: float | None = Field(default=None)
+    peak_flow_error_pct: float | None = Field(default=None)
+
+
+class AgentContext(BaseModel):
+    """Agent context fields in `provenance.json`."""
+
+    agent_id: str | None = Field(default=None)
+    experiment_id: str | None = Field(default=None)
+
+
+class ArtifactProvenance(BaseModel):
+    """Artifact `provenance.json` model."""
+
+    parent_run: str | None = Field(default=None)
+    proposal_source: str | None = Field(default=None)
+    agent_context: AgentContext | None = Field(default=None)
+
+
+class ArtifactRecord(BaseModel):
+    """In-memory representation of one artifact record."""
+
+    content_hash: str = Field(..., min_length=8)
+    config: RunConfig
+    metadata: ArtifactMetadata
+    metrics: ArtifactMetrics | None = Field(default=None)
+    provenance: ArtifactProvenance | None = Field(default=None)
+
+
+class ArtifactSummary(BaseModel):
+    """Lightweight listing payload used by `ArtifactStore.query()`."""
+
+    content_hash: str = Field(..., min_length=8)
+    basin_id: str = Field(..., min_length=1)
+    simulation_start: date = Field(...)
+    simulation_end: date = Field(...)
+    soil_mode: Literal["high_fidelity", "fallback", "synthetic"] | None = Field(default=None)
+    nse: float | None = Field(default=None)
+    parent_run: str | None = Field(default=None)
+
+
+class ArtifactQuery(BaseModel):
+    """Optional filters for artifact query/list operations."""
+
+    basin_id: str | None = Field(default=None)
+    soil_mode: Literal["high_fidelity", "fallback", "synthetic"] | None = Field(default=None)
+    nse_min: float | None = Field(default=None)

swatplus_builder/artifacts/store.py

@@ -0,0 +1,198 @@
+"""Local run-artifact storage (Phase 3B.2).
+
+Directory contract:
+
+    <root>/runs/<content_hash>/
+      config.json
+      metadata.json
+      metrics.json            (optional)
+      provenance.json         (optional)
+      timeseries.parquet      (optional)
+      plots/*                 (optional)
+      logs/*                  (optional)
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Iterable
+
+from .models import (
+    ArtifactMetadata,
+    ArtifactMetrics,
+    ArtifactProvenance,
+    ArtifactQuery,
+    ArtifactRecord,
+    ArtifactSummary,
+    RunConfig,
+)
+
+
+class ArtifactStore(ABC):
+    """Abstract artifact store backend."""
+
+    @abstractmethod
+    def write(
+        self,
+        record: ArtifactRecord,
+        *,
+        timeseries_parquet: Path | None = None,
+        plot_files: Iterable[Path] = (),
+        log_files: Iterable[Path] = (),
+    ) -> Path:
+        """Persist one artifact record and optional payload files."""
+
+    @abstractmethod
+    def read(self, content_hash: str) -> ArtifactRecord:
+        """Read one artifact record by hash."""
+
+    @abstractmethod
+    def exists(self, content_hash: str) -> bool:
+        """Return true when artifact directory exists."""
+
+    @abstractmethod
+    def query(self, filters: ArtifactQuery | None = None) -> list[ArtifactSummary]:
+        """List artifact summaries, optionally filtered."""
+
+    @abstractmethod
+    def lineage(self, content_hash: str) -> list[str]:
+        """Return parent chain starting at `content_hash`."""
+
+
+class LocalArtifactStore(ArtifactStore):
+    """Filesystem artifact store rooted at `<root>/runs`."""
+
+    def __init__(self, root: Path | str):
+        self.root = Path(root).expanduser().resolve()
+        self.runs_dir = self.root / "runs"
+        self.runs_dir.mkdir(parents=True, exist_ok=True)
+
+    def write(
+        self,
+        record: ArtifactRecord,
+        *,
+        timeseries_parquet: Path | None = None,
+        plot_files: Iterable[Path] = (),
+        log_files: Iterable[Path] = (),
+    ) -> Path:
+        run_dir = self._run_dir(record.content_hash)
+        run_dir.mkdir(parents=True, exist_ok=True)
+
+        self._write_json(run_dir / "config.json", record.config.model_dump(mode="json"))
+        self._write_json(run_dir / "metadata.json", record.metadata.model_dump(mode="json"))
+        if record.metrics is not None:
+            self._write_json(run_dir / "metrics.json", record.metrics.model_dump(mode="json"))
+        if record.provenance is not None:
+            self._write_json(run_dir / "provenance.json", record.provenance.model_dump(mode="json"))
+
+        if timeseries_parquet is not None:
+            dst = run_dir / "timeseries.parquet"
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(timeseries_parquet, dst)
+
+        self._copy_many(plot_files, run_dir / "plots")
+        self._copy_many(log_files, run_dir / "logs")
+        return run_dir
+
+    def read(self, content_hash: str) -> ArtifactRecord:
+        run_dir = self._run_dir(content_hash)
+        config = RunConfig.model_validate(self._read_json(run_dir / "config.json"))
+        metadata = ArtifactMetadata.model_validate(self._read_json(run_dir / "metadata.json"))
+
+        metrics_path = run_dir / "metrics.json"
+        prov_path = run_dir / "provenance.json"
+        metrics = (
+            ArtifactMetrics.model_validate(self._read_json(metrics_path))
+            if metrics_path.exists()
+            else None
+        )
+        provenance = (
+            ArtifactProvenance.model_validate(self._read_json(prov_path))
+            if prov_path.exists()
+            else None
+        )
+        return ArtifactRecord(
+            content_hash=content_hash,
+            config=config,
+            metadata=metadata,
+            metrics=metrics,
+            provenance=provenance,
+        )
+
+    def exists(self, content_hash: str) -> bool:
+        return self._run_dir(content_hash).is_dir()
+
+    def query(self, filters: ArtifactQuery | None = None) -> list[ArtifactSummary]:
+        q = filters or ArtifactQuery()
+        out: list[ArtifactSummary] = []
+        for run_dir in sorted(self.runs_dir.iterdir()):
+            if not run_dir.is_dir():
+                continue
+            try:
+                record = self.read(run_dir.name)
+            except Exception:
+                continue
+            summary = ArtifactSummary(
+                content_hash=record.content_hash,
+                basin_id=record.config.basin_id,
+                simulation_start=record.config.simulation_start,
+                simulation_end=record.config.simulation_end,
+                soil_mode=record.metadata.soil_mode,
+                nse=record.metrics.nse if record.metrics is not None else None,
+                parent_run=record.provenance.parent_run if record.provenance is not None else None,
+            )
+            if not self._match(summary, q):
+                continue
+            out.append(summary)
+        return out
+
+    def lineage(self, content_hash: str) -> list[str]:
+        chain: list[str] = []
+        seen: set[str] = set()
+        current = content_hash
+        while current and current not in seen and self.exists(current):
+            seen.add(current)
+            chain.append(current)
+            record = self.read(current)
+            parent = record.provenance.parent_run if record.provenance is not None else None
+            if not parent:
+                break
+            current = parent
+        return chain
+
+    def _run_dir(self, content_hash: str) -> Path:
+        return self.runs_dir / content_hash
+
+    @staticmethod
+    def _write_json(path: Path, payload: dict[str, object]) -> None:
+        path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+    @staticmethod
+    def _read_json(path: Path) -> dict[str, object]:
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    @staticmethod
+    def _copy_many(files: Iterable[Path], out_dir: Path) -> None:
+        copied = False
+        for src in files:
+            if not src.exists():
+                continue
+            if not copied:
+                out_dir.mkdir(parents=True, exist_ok=True)
+                copied = True
+            shutil.copy2(src, out_dir / src.name)
+
+    @staticmethod
+    def _match(summary: ArtifactSummary, q: ArtifactQuery) -> bool:
+        if q.basin_id is not None and summary.basin_id != q.basin_id:
+            return False
+        if q.soil_mode is not None and summary.soil_mode != q.soil_mode:
+            return False
+        if q.nse_min is not None:
+            if summary.nse is None or summary.nse < q.nse_min:
+                return False
+        return True
+

swatplus_builder/autoresearch/__init__.py

@@ -0,0 +1,47 @@
+"""Autoresearch loop primitives (Phase 3D)."""
+
+from .loop import (
+    LoopIterationResult,
+    LoopRequest,
+    LoopResult,
+    LoopStoppingCriteria,
+    SurrogatePrediction,
+    run_autoresearch_loop,
+)
+from .surrogate import (
+    HoldoutEvaluationCase,
+    HoldoutEvaluationReport,
+    HoldoutEvaluationRequest,
+    RoutingDecision,
+    SurrogateEnsemble,
+    SurrogateMember,
+    SurrogatePredictionEstimate,
+    SurrogateTrainingRequest,
+    decide_routing_path,
+    evaluate_surrogate_holdout,
+    make_loop_surrogate_predictor,
+    predict_with_surrogate,
+    train_surrogate_ensemble,
+)
+
+__all__ = [
+    "LoopIterationResult",
+    "LoopRequest",
+    "LoopResult",
+    "LoopStoppingCriteria",
+    "SurrogatePrediction",
+    "run_autoresearch_loop",
+    "HoldoutEvaluationCase",
+    "HoldoutEvaluationReport",
+    "HoldoutEvaluationRequest",
+    "RoutingDecision",
+    "SurrogateEnsemble",
+    "SurrogateMember",
+    "SurrogatePredictionEstimate",
+    "SurrogateTrainingRequest",
+    "decide_routing_path",
+    "evaluate_surrogate_holdout",
+    "make_loop_surrogate_predictor",
+    "predict_with_surrogate",
+    "train_surrogate_ensemble",
+]