adaptcompile 0.1.0__py3-none-any.whl

adaptcompile/__init__.py

@@ -0,0 +1,30 @@
+"""Public API for adaptcompile."""
+
+from importlib.metadata import version as _distribution_version
+
+from .dataset import AdaptationDataset
+from .episode import LearningEpisode
+from .errors import AdaptCompileError, SerializationError, ValidationError
+from .family import ProgramFamily
+from .geometry import AdaptationGeometry
+from .model import ModelContext
+from .program import ProgramSpec
+from .result import AdaptationResult
+from .study import AdaptationStudy
+
+__version__ = _distribution_version("adaptcompile")
+
+__all__ = [
+    "AdaptCompileError",
+    "AdaptationDataset",
+    "AdaptationGeometry",
+    "AdaptationResult",
+    "AdaptationStudy",
+    "LearningEpisode",
+    "ModelContext",
+    "ProgramFamily",
+    "ProgramSpec",
+    "SerializationError",
+    "ValidationError",
+    "__version__",
+]

adaptcompile/_validation.py

@@ -0,0 +1,46 @@
+"""Internal validation helpers."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from numbers import Real
+from types import MappingProxyType
+from typing import Any
+
+from .errors import ValidationError
+
+
+def nonempty_name(value: Any, *, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValidationError(f"{field} must be a non-empty string")
+    return value
+
+
+def string_keyed_mapping(value: Any, *, field: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ValidationError(f"{field} must be a mapping")
+    copied: dict[str, Any] = {}
+    for key, item in value.items():
+        nonempty_name(key, field=f"{field} key")
+        copied[key] = item
+    return MappingProxyType(copied)
+
+
+def score(value: Any, *, field: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise ValidationError(f"{field} must be a real number")
+    converted = float(value)
+    if not math.isfinite(converted):
+        raise ValidationError(f"{field} must be finite")
+    return converted
+
+
+def score_mapping(value: Any, *, field: str) -> Mapping[str, float]:
+    mapping = string_keyed_mapping(value, field=field)
+    return MappingProxyType(
+        {
+            name: score(item, field=f"{field}[{name!r}]")
+            for name, item in mapping.items()
+        }
+    )

adaptcompile/dataset.py

@@ -0,0 +1,160 @@
+"""Corpus-level collections of observed adaptations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable, Iterable, Iterator, Sequence
+from typing import TYPE_CHECKING, Any, TypeVar, cast, overload
+
+from .episode import EpisodeIdentityKey, _episode_identity_key
+from .errors import ValidationError
+from .result import AdaptationResult
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+
+ModelIdentityKey = tuple[str, str | None, str | None]
+GroupKey = TypeVar("GroupKey", bound=Hashable)
+
+
+class AdaptationDataset(Sequence[AdaptationResult]):
+    """An immutable corpus of observations spanning models, episodes, and programs.
+
+    Repeated ``(model, episode, program)`` observations are retained because seeds,
+    experiment runs, and measured outcomes may legitimately differ.
+    """
+
+    __slots__ = ("_results",)
+
+    def __init__(self, results: Iterable[AdaptationResult]) -> None:
+        collected = tuple(results)
+        if not collected:
+            raise ValidationError("an AdaptationDataset requires at least one result")
+        if any(not isinstance(result, AdaptationResult) for result in collected):
+            raise ValidationError(
+                "all dataset entries must be AdaptationResult instances"
+            )
+        self._results = collected
+
+    @property
+    def results(self) -> tuple[AdaptationResult, ...]:
+        return self._results
+
+    @overload
+    def __getitem__(self, index: int) -> AdaptationResult: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> tuple[AdaptationResult, ...]: ...
+
+    def __getitem__(
+        self, index: int | slice
+    ) -> AdaptationResult | tuple[AdaptationResult, ...]:
+        return self._results[index]
+
+    def __len__(self) -> int:
+        return len(self._results)
+
+    def __iter__(self) -> Iterator[AdaptationResult]:
+        return iter(self._results)
+
+    def __repr__(self) -> str:
+        return f"AdaptationDataset(n_results={len(self)})"
+
+    def by_model(self) -> dict[ModelIdentityKey, AdaptationDataset]:
+        """Group by ``ModelContext.identity_key``."""
+        return self._grouped(lambda result: result.model_context.identity_key)
+
+    def by_episode(self) -> dict[EpisodeIdentityKey, AdaptationDataset]:
+        """Group by explicit ID or conservative serialized episode configuration."""
+        return self._grouped(lambda result: _episode_identity_key(result.episode))
+
+    def by_family(self) -> dict[str | None, AdaptationDataset]:
+        """Group by conceptual fingerprint; ``None`` retains familyless programs."""
+        return self._grouped(
+            lambda result: (
+                result.program.family.fingerprint
+                if result.program.family is not None
+                else None
+            )
+        )
+
+    def by_program(self) -> dict[str, AdaptationDataset]:
+        """Group by concrete executable program fingerprint."""
+        return self._grouped(lambda result: result.program.fingerprint)
+
+    def filter(
+        self, predicate: Callable[[AdaptationResult], bool]
+    ) -> AdaptationDataset:
+        """Return observations matching *predicate*.
+
+        Like direct construction, an empty selection raises :class:`ValidationError`.
+        """
+        return AdaptationDataset(result for result in self if predicate(result))
+
+    def to_records(self) -> list[dict[str, Any]]:
+        """Return unambiguous flat observation records with nested run metadata."""
+        records: list[dict[str, Any]] = []
+        for result in self:
+            family = result.program.family
+            record: dict[str, Any] = {
+                "model_id": result.model_context.model_id,
+                "model_revision": result.model_context.revision,
+                "base_state_id": result.model_context.base_state_id,
+                "episode": result.episode.name,
+                "episode_id": result.episode.episode_id,
+                "program_family_fingerprint": (
+                    family.fingerprint if family is not None else None
+                ),
+                "program_family_name": family.name if family is not None else None,
+                "program_family_method": (
+                    family.method if family is not None else None
+                ),
+                "program_family_parameters": (
+                    family.to_dict()["parameters"] if family is not None else None
+                ),
+                "program_fingerprint": result.program.fingerprint,
+                "program_name": result.program.name,
+                "method": result.program.method,
+                "program_parameters": result.program.to_dict()["parameters"],
+                "metadata": result.to_dict()["metadata"],
+            }
+            record.update(
+                {
+                    f"before_{name}": value
+                    for name, value in result.before_geometry.items()
+                }
+            )
+            record.update(
+                {
+                    f"after_{name}": value
+                    for name, value in result.after_geometry.items()
+                }
+            )
+            record.update(
+                {
+                    f"delta_{name}": value
+                    for name, value in result.delta_geometry.items()
+                }
+            )
+            records.append(record)
+        return records
+
+    def to_dataframe(self) -> DataFrame:
+        """Return a pandas DataFrame (requires the ``dataframe`` extra)."""
+        try:
+            from pandas import DataFrame
+        except ImportError as error:  # pragma: no cover - depends on environment
+            raise ImportError(
+                "to_dataframe() requires pandas; install adaptcompile[dataframe]"
+            ) from error
+        return cast("DataFrame", DataFrame(self.to_records()))
+
+    def _grouped(
+        self, key: Callable[[AdaptationResult], GroupKey]
+    ) -> dict[GroupKey, AdaptationDataset]:
+        grouped: dict[GroupKey, list[AdaptationResult]] = {}
+        for result in self:
+            grouped.setdefault(key(result), []).append(result)
+        return {
+            identity: AdaptationDataset(results)
+            for identity, results in grouped.items()
+        }

adaptcompile/episode.py

@@ -0,0 +1,110 @@
+"""Learning episode representation."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from os import PathLike
+from typing import Any
+
+from ._validation import nonempty_name, string_keyed_mapping
+from .errors import ValidationError
+from .serialization import (
+    immutable_json_mapping,
+    json_dumps,
+    read_json,
+    to_json_safe,
+    write_json,
+)
+
+EpisodeIdentityKey = tuple[str, str]
+
+
+@dataclass(frozen=True)
+class LearningEpisode:
+    """A model-independent learning problem and its evaluation sets.
+
+    Dataset-like objects are held by reference and deliberately excluded from
+    serialization. The evaluation mapping and metadata are detached and read-only.
+    """
+
+    name: str
+    train: Any
+    evaluations: Mapping[str, Any]
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    episode_id: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "name", nonempty_name(self.name, field="name"))
+        evaluations = string_keyed_mapping(self.evaluations, field="evaluations")
+        if not evaluations:
+            raise ValidationError(
+                "evaluations must contain at least one evaluation set"
+            )
+        object.__setattr__(self, "evaluations", evaluations)
+        object.__setattr__(
+            self,
+            "metadata",
+            immutable_json_mapping(self.metadata, location="metadata"),
+        )
+        if self.episode_id is not None:
+            object.__setattr__(
+                self,
+                "episode_id",
+                nonempty_name(self.episode_id, field="episode_id"),
+            )
+
+    @property
+    def evaluation_names(self) -> tuple[str, ...]:
+        """Names of the declared evaluation sets, in construction order."""
+        return tuple(self.evaluations)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize configuration only; dataset contents are intentionally omitted."""
+        return {
+            "name": self.name,
+            "episode_id": self.episode_id,
+            "evaluation_names": list(self.evaluation_names),
+            "metadata": to_json_safe(self.metadata, location="metadata"),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> LearningEpisode:
+        """Restore configuration with ``None`` placeholders for dataset objects."""
+        try:
+            names = data["evaluation_names"]
+            evaluations = {name: None for name in names}
+            return cls(
+                name=data["name"],
+                train=None,
+                evaluations=evaluations,
+                metadata=data.get("metadata", {}),
+                episode_id=data.get("episode_id"),
+            )
+        except (KeyError, TypeError) as error:
+            raise ValidationError("malformed serialized LearningEpisode") from error
+
+    def to_json(
+        self,
+        destination: str | PathLike[str] | None = None,
+        *,
+        indent: int | None = 2,
+    ) -> str:
+        return write_json(self.to_dict(), destination, indent=indent)
+
+    @classmethod
+    def from_json(cls, source: str | PathLike[str]) -> LearningEpisode:
+        return cls.from_dict(read_json(source))
+
+    def __repr__(self) -> str:
+        return (
+            f"LearningEpisode(name={self.name!r}, train={type(self.train).__name__}, "
+            f"evaluations={list(self.evaluations)!r}, episode_id={self.episode_id!r})"
+        )
+
+
+def _episode_identity_key(episode: LearningEpisode) -> EpisodeIdentityKey:
+    """Return the conservative, dataset-independent identity used by collections."""
+    if episode.episode_id is not None:
+        return ("episode_id", episode.episode_id)
+    return ("configuration", json_dumps(episode.to_dict(), indent=None))

adaptcompile/errors.py

@@ -0,0 +1,13 @@
+"""Package-specific exceptions."""
+
+
+class AdaptCompileError(Exception):
+    """Base exception for errors raised by adaptcompile."""
+
+
+class ValidationError(AdaptCompileError, ValueError):
+    """Raised when an adaptcompile value is malformed or inconsistent."""
+
+
+class SerializationError(AdaptCompileError, TypeError):
+    """Raised when a record cannot be represented safely as JSON."""

adaptcompile/family.py

@@ -0,0 +1,103 @@
+"""Conceptual adaptation program families."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from os import PathLike
+from typing import Any
+
+from ._validation import nonempty_name
+from .errors import ValidationError
+from .serialization import (
+    immutable_json_mapping,
+    read_json,
+    to_json_safe,
+    write_json,
+)
+
+
+@dataclass(frozen=True)
+class ProgramFamily:
+    """A conceptual adaptation choice, before model-specific realization.
+
+    Structural equality includes every field. ``fingerprint`` identifies only the
+    conceptual semantics expressed by ``method`` and ``parameters``.
+    """
+
+    name: str
+    method: str
+    parameters: Mapping[str, Any]
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "name", nonempty_name(self.name, field="name"))
+        object.__setattr__(self, "method", nonempty_name(self.method, field="method"))
+        object.__setattr__(
+            self,
+            "parameters",
+            immutable_json_mapping(self.parameters, location="parameters"),
+        )
+        object.__setattr__(
+            self,
+            "metadata",
+            immutable_json_mapping(self.metadata, location="metadata"),
+        )
+
+    @property
+    def fingerprint(self) -> str:
+        """Stable SHA-256 identity derived from method and parameters only."""
+        conceptual = {
+            "method": self.method,
+            "parameters": to_json_safe(self.parameters, location="parameters"),
+        }
+        canonical = json.dumps(
+            conceptual,
+            sort_keys=True,
+            separators=(",", ":"),
+            allow_nan=False,
+        )
+        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "method": self.method,
+            "parameters": to_json_safe(self.parameters, location="parameters"),
+            "metadata": to_json_safe(self.metadata, location="metadata"),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> ProgramFamily:
+        try:
+            return cls(
+                name=data["name"],
+                method=data["method"],
+                parameters=data["parameters"],
+                metadata=data.get("metadata", {}),
+            )
+        except (KeyError, TypeError) as error:
+            raise ValidationError("malformed serialized ProgramFamily") from error
+
+    def to_json(
+        self,
+        destination: str | PathLike[str] | None = None,
+        *,
+        indent: int | None = 2,
+    ) -> str:
+        return write_json(self.to_dict(), destination, indent=indent)
+
+    @classmethod
+    def from_json(cls, source: str | PathLike[str]) -> ProgramFamily:
+        return cls.from_dict(read_json(source))
+
+    def __hash__(self) -> int:
+        canonical = json.dumps(
+            to_json_safe(self.to_dict()),
+            sort_keys=True,
+            separators=(",", ":"),
+            allow_nan=False,
+        )
+        return hash(canonical)

adaptcompile/geometry.py

@@ -0,0 +1,111 @@
+"""Multidimensional behavioral geometry."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from os import PathLike
+from typing import TYPE_CHECKING, Any, cast
+
+from ._validation import score_mapping
+from .errors import ValidationError
+from .serialization import read_json, write_json
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+
+
+class AdaptationGeometry(Mapping[str, float]):
+    """An immutable, arbitrary-dimensional mapping of behavioral measurements."""
+
+    __slots__ = ("_metrics",)
+
+    def __init__(self, metrics: Mapping[str, float]) -> None:
+        normalized = score_mapping(metrics, field="metrics")
+        if not normalized:
+            raise ValidationError("geometry must contain at least one metric")
+        self._metrics = normalized
+
+    @property
+    def metrics(self) -> Mapping[str, float]:
+        """A read-only metric mapping."""
+        return self._metrics
+
+    @property
+    def metric_names(self) -> tuple[str, ...]:
+        return tuple(self._metrics)
+
+    def __getitem__(self, name: str) -> float:
+        try:
+            return self._metrics[name]
+        except KeyError as error:
+            raise KeyError(f"unknown geometry metric {name!r}") from error
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._metrics)
+
+    def __len__(self) -> int:
+        return len(self._metrics)
+
+    def __repr__(self) -> str:
+        return f"AdaptationGeometry({dict(self._metrics)!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, AdaptationGeometry):
+            return NotImplemented
+        return dict(self._metrics) == dict(other._metrics)
+
+    def __hash__(self) -> int:
+        return hash(frozenset(self._metrics.items()))
+
+    def to_dict(self) -> dict[str, float]:
+        return dict(self._metrics)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> AdaptationGeometry:
+        return cls(data)
+
+    def to_json(
+        self,
+        destination: str | PathLike[str] | None = None,
+        *,
+        indent: int | None = 2,
+    ) -> str:
+        return write_json(self.to_dict(), destination, indent=indent)
+
+    @classmethod
+    def from_json(cls, source: str | PathLike[str]) -> AdaptationGeometry:
+        return cls.from_dict(read_json(source))
+
+    def compare(self, other: AdaptationGeometry) -> AdaptationGeometry:
+        """Return ``self - other`` after requiring identical metric dimensions."""
+        self._require_comparable(other)
+        return AdaptationGeometry(
+            {name: value - other[name] for name, value in self._metrics.items()}
+        )
+
+    def delta(self, baseline: AdaptationGeometry) -> AdaptationGeometry:
+        """Alias for :meth:`compare`, naming *baseline* explicitly."""
+        return self.compare(baseline)
+
+    def to_dataframe(self) -> DataFrame:
+        """Return a one-row pandas DataFrame (requires the ``dataframe`` extra)."""
+        try:
+            from pandas import DataFrame
+        except ImportError as error:  # pragma: no cover - depends on environment
+            raise ImportError(
+                "to_dataframe() requires pandas; install adaptcompile[dataframe]"
+            ) from error
+        return cast("DataFrame", DataFrame([self.to_dict()]))
+
+    def _require_comparable(self, other: AdaptationGeometry) -> None:
+        if not isinstance(other, AdaptationGeometry):
+            raise TypeError("other must be an AdaptationGeometry")
+        own = set(self._metrics)
+        theirs = set(other._metrics)
+        if own != theirs:
+            missing = sorted(own - theirs)
+            extra = sorted(theirs - own)
+            raise ValidationError(
+                "geometry metrics do not match "
+                f"(missing from other={missing}, extra in other={extra})"
+            )

adaptcompile/model.py

@@ -0,0 +1,93 @@
+"""Declarative model and base-state context."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from os import PathLike
+from typing import Any
+
+from ._validation import nonempty_name
+from .errors import ValidationError
+from .serialization import immutable_json_mapping, read_json, to_json_safe, write_json
+
+
+@dataclass(frozen=True)
+class ModelContext:
+    """A declarative description of the pre-adaptation model/base state.
+
+    This record identifies a model state; it does not contain, load, or inspect
+    model weights and has no dependency on a model framework.
+    """
+
+    model_id: str
+    revision: str | None = None
+    base_state_id: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "model_id",
+            nonempty_name(self.model_id, field="model_id"),
+        )
+        if self.revision is not None:
+            object.__setattr__(
+                self,
+                "revision",
+                nonempty_name(self.revision, field="revision"),
+            )
+        if self.base_state_id is not None:
+            object.__setattr__(
+                self,
+                "base_state_id",
+                nonempty_name(self.base_state_id, field="base_state_id"),
+            )
+        object.__setattr__(
+            self,
+            "metadata",
+            immutable_json_mapping(self.metadata, location="metadata"),
+        )
+
+    @property
+    def identity_key(self) -> tuple[str, str | None, str | None]:
+        """Identity used to hold model/base state fixed within a study."""
+        return (self.model_id, self.revision, self.base_state_id)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "model_id": self.model_id,
+            "revision": self.revision,
+            "base_state_id": self.base_state_id,
+            "metadata": to_json_safe(self.metadata, location="metadata"),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> ModelContext:
+        try:
+            return cls(
+                model_id=data["model_id"],
+                revision=data.get("revision"),
+                base_state_id=data.get("base_state_id"),
+                metadata=data.get("metadata", {}),
+            )
+        except (KeyError, TypeError) as error:
+            raise ValidationError("malformed serialized ModelContext") from error
+
+    def to_json(
+        self,
+        destination: str | PathLike[str] | None = None,
+        *,
+        indent: int | None = 2,
+    ) -> str:
+        return write_json(self.to_dict(), destination, indent=indent)
+
+    @classmethod
+    def from_json(cls, source: str | PathLike[str]) -> ModelContext:
+        return cls.from_dict(read_json(source))
+
+    def __repr__(self) -> str:
+        return (
+            f"ModelContext(model_id={self.model_id!r}, revision={self.revision!r}, "
+            f"base_state_id={self.base_state_id!r})"
+        )