aihydro-core 0.1.0__tar.gz

aihydro_core-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: aihydro-core
+Version: 0.1.0
+Summary: AI-Hydro robustness substrate: hashing, provenance, Store protocol, async jobs, feature addressing
+Author-email: Mohammad Galib <mgalib@purdue.edu>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AI-Hydro/aihydro-core
+Project-URL: Repository, https://github.com/AI-Hydro/aihydro-core
+Keywords: hydrology,agentic,MCP,SDK,robustness
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: import-linter>=2.0; extra == "dev"
+
+# aihydro-core
+
+Robustness substrate for the AI-Hydro ecosystem.
+
+Provides the single hashing and provenance vocabulary (`content_hash`, `param_hash`,
+`ProvenanceRecord`) shared across all AI-Hydro packages, plus the `Store` protocol and
+`AsyncJobRegistry` used by higher-level layers.
+
+**Zero heavy dependencies** — pure Python stdlib. Designed to be the lowest layer in the
+stack so it can be safely depended on by any AI-Hydro package without pulling in numpy,
+pandas, or geo libraries.
+
+## Install
+
+```bash
+pip install aihydro-core
+```
+
+## Part of the AI-Hydro ecosystem
+
+- [aihydro-data](https://github.com/AI-Hydro/AIhydro-data) — global hydrology dataverse
+- [AI-Hydro](https://github.com/AI-Hydro/AI-Hydro) — AI-native hydrologic modelling platform

aihydro_core-0.1.0/README.md

@@ -0,0 +1,22 @@
+# aihydro-core
+
+Robustness substrate for the AI-Hydro ecosystem.
+
+Provides the single hashing and provenance vocabulary (`content_hash`, `param_hash`,
+`ProvenanceRecord`) shared across all AI-Hydro packages, plus the `Store` protocol and
+`AsyncJobRegistry` used by higher-level layers.
+
+**Zero heavy dependencies** — pure Python stdlib. Designed to be the lowest layer in the
+stack so it can be safely depended on by any AI-Hydro package without pulling in numpy,
+pandas, or geo libraries.
+
+## Install
+
+```bash
+pip install aihydro-core
+```
+
+## Part of the AI-Hydro ecosystem
+
+- [aihydro-data](https://github.com/AI-Hydro/AIhydro-data) — global hydrology dataverse
+- [AI-Hydro](https://github.com/AI-Hydro/AI-Hydro) — AI-native hydrologic modelling platform

aihydro_core-0.1.0/aihydro_core/__init__.py

@@ -0,0 +1,17 @@
+"""
+aihydro-core — the robustness substrate for AI-Hydro tools.
+
+Four cross-cutting blocks, each solving one axis of tool reliability:
+
+    primitives  — hashing, provenance (Artifact), errors (ToolError)
+    store       — Store protocol (persistence-agnostic keyed result + feature store)
+    jobs        — async execution (start/status/result/cancel/list + PID registry)
+    features    — geometry addressing (Feature registry + @feature_tool decorator)
+
+Domain packages (aihydro-tools, aihydro-data) depend on this package.
+This package has zero heavy dependencies — it is stdlib only.
+
+See AIHYDRO_CORE_DESIGN.md (local-docs/) for the full architecture.
+"""
+
+__version__ = "0.1.0"

aihydro_core-0.1.0/aihydro_core/features/__init__.py

@@ -0,0 +1,5 @@
+from .registry import FeatureRegistry
+from ..primitives.geometry import Feature
+from ..primitives.errors import FeatureNotFoundError
+
+__all__ = ["FeatureRegistry", "Feature", "FeatureNotFoundError"]

aihydro_core-0.1.0/aihydro_core/features/compute.py

@@ -0,0 +1,254 @@
+"""
+feature_compute — the @feature_tool decorator.
+
+Every spatial tool that is addressable by geometry composes from this block.
+
+Usage
+-----
+Authors write a **pure sync kernel** that receives a bare GeoJSON geometry dict
+and returns a result envelope. The decorator handles:
+
+    resolve → cache check → compute → store → provenance → commit
+
+Example::
+
+    from aihydro_core.features.compute import feature_tool
+
+    @feature_tool(product="twi", citations=["usgs_3dep", "copernicus_glo30"])
+    def _twi_stats_kernel(geom: dict, *, resolution: int = 30) -> dict:
+        # geom is already resolved — pure computation only.
+        # (The domain kernel is imported by the *caller's* package, never here:
+        #  core depends on nobody.)
+        return compute_twi_stats(geom, resolution=resolution)
+
+    # Domain-side thin wrapper (in the tools package, not core):
+    store = load_store(store_id)
+    result = _twi_stats_kernel(store=store, feature=feature_ref, resolution=30)
+
+Wrapped function signature
+--------------------------
+    fn_wrapped(store: Store, feature: str | dict | None = None, **params) -> dict
+
+Parameters
+~~~~~~~~~~
+store : Store
+    A loaded Store instance (typically a HydroSession). The caller is
+    responsible for loading and passing it. Core never imports HydroSession.
+feature : str | dict | None
+    Feature reference — resolved via FeatureRegistry. str → id/name lookup;
+    dict → inline GeoJSON (registered on the fly); None → active feature.
+**params
+    Compute parameters forwarded to the wrapped kernel unchanged. These form
+    the params_key for the three-level cache.
+
+Result
+------
+The result dict from the kernel (or a cached envelope on hit).
+Always includes ``feature_id`` and ``_cache_hit`` keys.
+
+Cache key
+---------
+``param_hash(params)`` — deterministic SHA-256 hex of the sorted JSON params.
+Same geometry + same params → hit. Different geometry → miss (different key).
+"""
+from __future__ import annotations
+
+import functools
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
+
+from ..primitives.hashing import param_hash, content_hash
+from ..features.registry import FeatureRegistry
+
+if TYPE_CHECKING:
+    from ..store.protocol import Store
+
+log = logging.getLogger("aihydro_core.features.compute")
+
+F = TypeVar("F", bound=Callable[..., dict])
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# ---------------------------------------------------------------------------
+# @feature_tool decorator
+# ---------------------------------------------------------------------------
+
+def feature_tool(
+    product: str,
+    citations: list[str] | None = None,
+) -> Callable[[F], "FeatureToolWrapper"]:
+    """
+    Decorator factory that wraps a pure sync spatial kernel.
+
+    Parameters
+    ----------
+    product : str
+        The result product name — e.g. "twi", "cn", "signatures".
+        Used as the top-level key in the three-level result store.
+    citations : list[str] | None
+        Citation keys (data source identifiers) to record on every run.
+        Accumulated in the store's citation set.
+
+    Returns
+    -------
+    A decorator that wraps ``fn(geom: dict, **params) -> dict``
+    into ``fn_wrapped(store, feature=None, **params) -> dict``.
+    """
+    _citations: list[str] = citations or []
+
+    def decorator(fn: F) -> "FeatureToolWrapper":
+
+        @functools.wraps(fn)
+        def wrapper(
+            store: "Store",
+            feature: "str | dict | list | None" = None,
+            **params: Any,
+        ) -> dict:
+            """
+            Resolve → cache check → compute → store → provenance → commit.
+
+            Parameters
+            ----------
+            store : Store
+                Loaded Store instance (e.g. HydroSession).
+            feature : str | dict | list | None
+                Feature reference. None → active/single feature.
+                **list** → batch fan-out: each element resolved independently;
+                returns ``{"batch": True, "n_features": N, "results": {...}}``.
+            **params
+                Forwarded to the kernel; also form the cache key.
+            """
+            # C3: batch fan-out — feature is a list of refs
+            if isinstance(feature, list):
+                results: dict[str, dict] = {}
+                errors: dict[str, str] = {}
+                for ref in feature:
+                    try:
+                        r = wrapper(store, feature=ref, **params)
+                        results[r.get("feature_id", str(ref))] = r
+                    except Exception as exc:
+                        fid = str(ref)
+                        errors[fid] = str(exc)
+                        log.warning(
+                            "Batch feature_tool %s failed for ref=%r: %s",
+                            product, ref, exc,
+                        )
+                return {
+                    "batch": True,
+                    "product": product,
+                    "n_features": len(feature),
+                    "n_success": len(results),
+                    "n_error": len(errors),
+                    "results": results,
+                    **({"errors": errors} if errors else {}),
+                }
+
+            # 1. Resolve feature ref → Feature
+            registry = FeatureRegistry(store)
+            feat = registry.resolve(feature)
+
+            # 2. Cache check
+            key = param_hash(params) if params else param_hash({})
+            cached = store.get_result(product, feat.feature_id, key)
+            if cached is not None:
+                log.debug(
+                    "Cache hit: product=%s feature_id=%s key=%s",
+                    product, feat.feature_id, key,
+                )
+                return {**cached, "feature_id": feat.feature_id, "_cache_hit": True}
+
+            # 3. Compute
+            log.debug(
+                "Cache miss — computing: product=%s feature_id=%s key=%s",
+                product, feat.feature_id, key,
+            )
+            raw = fn(feat.geojson, **params)
+
+            # 4. Normalise result into {data, meta} envelope
+            if isinstance(raw, dict) and "data" in raw and "meta" in raw:
+                # Kernel already returned an envelope
+                envelope: dict = dict(raw)
+                envelope["meta"] = {
+                    **raw["meta"],
+                    "computed_at": raw["meta"].get("computed_at") or _now_iso(),
+                    "feature_id": feat.feature_id,
+                    "feature_name": feat.name,
+                    "params": params,
+                }
+            else:
+                # Kernel returned bare data dict — wrap it
+                envelope = {
+                    "data": raw,
+                    "meta": {
+                        "computed_at": _now_iso(),
+                        "tool": fn.__name__,
+                        "feature_id": feat.feature_id,
+                        "feature_name": feat.name,
+                        "params": params,
+                    },
+                }
+
+            # 5. Store result
+            store.put_result(product, feat.feature_id, key, envelope)
+
+            # 6. Provenance
+            if _citations:
+                store.add_citations(_citations)
+
+            try:
+                from ..primitives.provenance import Artifact as _Artifact
+                art = _Artifact(
+                    artifact_id=f"{product}_{feat.feature_id}_{key[:8]}",
+                    type="derived",
+                    source=product,
+                    params=params,
+                    param_hash=key,
+                    content_hash=content_hash(envelope.get("data", {})),
+                )
+                store.store_artifact(art)
+            except Exception as _e:
+                log.debug("Provenance artifact recording failed (non-fatal): %s", _e)
+
+            # 7. Commit
+            store.commit()
+
+            return {**envelope, "feature_id": feat.feature_id}
+
+        # Attach metadata so callers can introspect decoration intent
+        wrapper._feature_tool_product = product          # type: ignore[attr-defined]
+        wrapper._feature_tool_citations = _citations      # type: ignore[attr-defined]
+        wrapper._feature_tool_inner = fn                  # type: ignore[attr-defined]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# FeatureToolWrapper type alias (for documentation only)
+# ---------------------------------------------------------------------------
+
+class FeatureToolWrapper:
+    """
+    Callable returned by @feature_tool.
+
+    Not instantiated directly — used only as a type annotation target so IDE
+    tooling can show the wrapper's signature.
+    """
+    _feature_tool_product: str
+    _feature_tool_citations: list[str]
+    _feature_tool_inner: Callable[..., dict]
+
+    def __call__(
+        self,
+        store: "Store",
+        feature: str | dict | None = None,
+        **params: Any,
+    ) -> dict: ...
+
+
+__all__ = ["feature_tool", "FeatureToolWrapper"]

aihydro_core-0.1.0/aihydro_core/features/registry.py

@@ -0,0 +1,183 @@
+"""
+FeatureRegistry — resolve geometry references to Feature objects.
+
+This is the agent-facing geometry-addressing layer. An agent passes a short
+string id (or name), not a raw GeoJSON blob. The registry resolves that ref
+to a fully-loaded Feature so the compute kernel receives a clean geometry.
+
+Resolution chain (resolve(ref)):
+    str  → id lookup → name lookup → GeoJSON-string parse → register-on-fly
+    dict → treat as GeoJSON, register on the fly
+    None → active feature (preserves single-watershed back-compat)
+"""
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from typing import TYPE_CHECKING
+
+from ..primitives.geometry import Feature
+from ..primitives.errors import FeatureNotFoundError
+
+if TYPE_CHECKING:
+    from ..store.protocol import Store
+
+
+def _slugify(s: str) -> str:
+    s = re.sub(r"[^a-zA-Z0-9]+", "-", s).strip("-").lower()
+    return (s[:32] or uuid.uuid4().hex[:12])
+
+
+def _extract_geometry(raw: dict) -> dict:
+    """Return the bare geometry dict from either a GeoJSON Feature or bare geometry."""
+    if raw.get("type") == "Feature":
+        return raw.get("geometry", raw)
+    return raw
+
+
+class FeatureRegistry:
+    """
+    Geometry registry backed by a Store.
+
+    Every spatial tool receives a FeatureRegistry built from the session's Store.
+    The registry is the single resolution authority — tools never read geometries
+    directly from the session.
+    """
+
+    def __init__(self, store: Store) -> None:
+        self._store = store
+
+    # ------------------------------------------------------------------ #
+    # Registration                                                         #
+    # ------------------------------------------------------------------ #
+
+    def register(
+        self,
+        geojson: dict | str,
+        name: str = "",
+        source: str = "",
+        feature_id: str | None = None,
+        set_active: bool = False,
+        area_km2: float | None = None,
+        bbox: tuple[float, float, float, float] | None = None,
+    ) -> Feature:
+        """
+        Register a geometry and return the Feature with its stable id.
+
+        Parameters
+        ----------
+        geojson : dict | str
+            GeoJSON dict or JSON string. Accepts bare geometry or GeoJSON Feature.
+        name : str
+            Human-readable label. Used as the display name and as a lookup alias.
+        source : str
+            Registration source tag ("delineate_watershed", "map_annotation", ...).
+        feature_id : str | None
+            Explicit id to assign. If None, derived from name (slugified) or UUID.
+        set_active : bool
+            If True, mark this feature as the active (default) feature.
+        """
+        if isinstance(geojson, str):
+            try:
+                geojson = json.loads(geojson)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"geojson is not valid JSON: {e}") from e
+
+        geom = _extract_geometry(geojson)
+
+        if feature_id is None:
+            feature_id = _slugify(name) if name else uuid.uuid4().hex[:12]
+
+        feature = Feature(
+            feature_id=feature_id,
+            geojson=geom,
+            name=name,
+            source=source,
+            bbox=bbox,
+            area_km2=area_km2,
+        )
+        self._store.put_feature(feature)
+        if set_active:
+            self._store.set_active_feature_id(feature_id)
+        self._store.commit()
+        return feature
+
+    # ------------------------------------------------------------------ #
+    # Resolution                                                           #
+    # ------------------------------------------------------------------ #
+
+    def resolve(self, ref: str | dict | None) -> Feature:
+        """
+        Resolve a reference to a Feature.
+
+        ref=None    → active feature (single-watershed back-compat)
+        ref=str     → id lookup, then name lookup, then GeoJSON parse
+        ref=dict    → treat as raw GeoJSON, register on the fly
+
+        Raises FeatureNotFoundError with the list of available ids if ref
+        cannot be resolved — so the error itself tells the agent what to do.
+        """
+        if ref is None:
+            return self._resolve_active()
+
+        if isinstance(ref, dict):
+            return self.register(ref, source="on-the-fly")
+
+        # --- string: id → name → GeoJSON parse → not found ---
+        feat = self._store.get_feature(ref)
+        if feat is not None:
+            return feat
+
+        for f in self._store.list_features():
+            if f.name and f.name == ref:
+                return f
+
+        try:
+            parsed = json.loads(ref)
+            if isinstance(parsed, dict):
+                return self.register(parsed, source="on-the-fly")
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+        available = [f.feature_id for f in self._store.list_features()]
+        raise FeatureNotFoundError(ref=ref, available=available)
+
+    def resolve_many(self, refs: list[str | dict]) -> list[Feature]:
+        """Resolve a list of refs; raises FeatureNotFoundError on first miss."""
+        return [self.resolve(r) for r in refs]
+
+    def _resolve_active(self) -> Feature:
+        active_id = self._store.get_active_feature_id()
+        if active_id:
+            feat = self._store.get_feature(active_id)
+            if feat is not None:
+                return feat
+        # Fall back: return the most recently registered feature if only one exists
+        features = self._store.list_features()
+        if len(features) == 1:
+            return features[0]
+        raise FeatureNotFoundError(
+            ref="<active>",
+            available=[f.feature_id for f in features] if features else None,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Listing + active                                                     #
+    # ------------------------------------------------------------------ #
+
+    def list(self) -> list[Feature]:
+        """Return all registered features."""
+        return self._store.list_features()
+
+    def set_active(self, feature_id: str) -> None:
+        """Set the active (default) feature by id."""
+        feat = self._store.get_feature(feature_id)
+        if feat is None:
+            available = [f.feature_id for f in self._store.list_features()]
+            raise FeatureNotFoundError(ref=feature_id, available=available)
+        self._store.set_active_feature_id(feature_id)
+        self._store.commit()
+
+    def get_active_id(self) -> str | None:
+        return self._store.get_active_feature_id()