agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/registry/data/auxiliary_method_profiles.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": 1,
+  "protocol": "agentinputlab.auxiliary-method-profiles.v1",
+  "method_count": 27,
+  "methods": [
+    {"method_id": "rewrite.query2doc", "release_id": "rewrite.query2doc.querygym_live", "profile_kind": "controlled_adapter"},
+    {"method_id": "rewrite.rrr", "release_id": "rewrite.rrr.common_support_prompt", "profile_kind": "controlled_adapter"},
+    {"method_id": "rewrite.reformer", "release_id": "rewrite.reformer.repo_native_r_only", "profile_kind": "controlled_adapter"},
+    {"method_id": "rewrite.infocqr", "release_id": "rewrite.infocqr.common_support_rw_zsl", "profile_kind": "controlled_adapter"},
+    {"method_id": "plan.plan_and_solve", "release_id": "plan.plan_and_solve.ps_prompt", "profile_kind": "controlled_adapter"},
+    {"method_id": "plan.decomp", "release_id": "plan.decomp.common_support_odqa", "profile_kind": "controlled_adapter"},
+    {"method_id": "plan.self_ask", "release_id": "plan.self_ask.full_loop", "profile_kind": "controlled_adapter"},
+    {"method_id": "plan.llm_compiler", "release_id": "plan.llm_compiler.common_support_planner", "profile_kind": "controlled_adapter"},
+    {"method_id": "plan.plan_and_budget", "release_id": "plan.plan_and_budget.native_regenerated_soft_budget", "profile_kind": "controlled_adapter"},
+    {"method_id": "acquire.hyde", "release_id": "acquire.hyde.paper_reimplementation", "profile_kind": "controlled_adapter"},
+    {"method_id": "acquire.ircot", "release_id": "acquire.ircot.common_support", "profile_kind": "controlled_adapter"},
+    {"method_id": "acquire.adaptive_rag", "release_id": "acquire.adaptive_rag.common_support", "profile_kind": "controlled_adapter"},
+    {"method_id": "acquire.r2ag", "release_id": "acquire.r2ag.common_support", "profile_kind": "controlled_adapter"},
+    {"method_id": "acquire.qrag", "release_id": "acquire.qrag.common_support", "profile_kind": "controlled_adapter"},
+    {"method_id": "clarify.ask_or_assume", "release_id": "clarify.ask_or_assume.intent_monitor_component", "profile_kind": "controlled_adapter"},
+    {"method_id": "clarify.udcs", "release_id": "clarify.udcs.repo_native_prompt_route", "profile_kind": "controlled_adapter"},
+    {"method_id": "clarify.future_turns", "release_id": "clarify.future_turns.future_outcome_match", "profile_kind": "controlled_adapter"},
+    {"method_id": "clarify.active_task_disambiguation", "release_id": "clarify.active_task_disambiguation.eig_uniform", "profile_kind": "controlled_adapter"},
+    {"method_id": "curate.longllmlingua", "release_id": "curate.longllmlingua.official", "profile_kind": "official_native"},
+    {"method_id": "curate.llmlingua2", "release_id": "curate.llmlingua2.xlm_roberta_official", "profile_kind": "controlled_adapter"},
+    {"method_id": "curate.recomp", "release_id": "curate.recomp.common_support_extractive", "profile_kind": "controlled_adapter"},
+    {"method_id": "curate.acon", "release_id": "curate.acon.common_support_observation", "profile_kind": "controlled_adapter"},
+    {"method_id": "recipe.smartsearch", "release_id": "rewrite.smartsearch.common_support_queries", "profile_kind": "controlled_adapter"},
+    {"method_id": "recipe.rqrag", "release_id": "recipe.rqrag.common_support_queries", "profile_kind": "controlled_adapter"},
+    {"method_id": "recipe.ace", "release_id": "recipe.ace.eval_only", "profile_kind": "controlled_adapter"},
+    {"method_id": "recipe.mce", "release_id": "recipe.mce.text_artifact_eval", "profile_kind": "controlled_adapter"},
+    {"method_id": "recipe.skillopt", "release_id": "recipe.skillopt.eval_only", "profile_kind": "controlled_adapter"}
+  ]
+}

agentinputlab/registry/loader.py

@@ -0,0 +1,100 @@
+"""Load and validate source or packaged algorithm registries."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from agentinputlab.contracts.errors import RegistryError
+from agentinputlab.contracts.serialization import canonical_json
+
+from .schema import RegistryDocument
+
+
+def _decode_json_compatible_yaml(text: str, source: str) -> Any:
+    """Decode the registry with the standard library.
+
+    JSON is a strict subset of YAML, so the editable ``registry.yaml`` remains
+    valid YAML while minimal installations avoid a PyYAML dependency.
+    """
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise RegistryError(
+            f"{source} is not JSON-compatible YAML: line {exc.lineno}, column {exc.colno}: "
+            f"{exc.msg}"
+        ) from exc
+
+
+def load_registry_text(text: str, *, source: str = "<memory>") -> RegistryDocument:
+    """Parse and validate a registry document from text."""
+
+    return RegistryDocument.from_mapping(_decode_json_compatible_yaml(text, source))
+
+
+def load_registry_file(path: str | Path) -> RegistryDocument:
+    """Parse and validate a registry document from a filesystem path."""
+
+    resolved = Path(path).expanduser().resolve()
+    try:
+        text = resolved.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise RegistryError(f"cannot read registry {resolved}: {exc}") from exc
+    return load_registry_text(text, source=str(resolved))
+
+
+def load_packaged_registry() -> RegistryDocument:
+    """Load the immutable snapshot distributed inside the Python package."""
+
+    resource = resources.files("agentinputlab.registry").joinpath("data", "algorithms.json")
+    try:
+        text = resource.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise RegistryError(f"cannot read packaged algorithm registry: {exc}") from exc
+    return load_registry_text(text, source="agentinputlab.registry/data/algorithms.json")
+
+
+def find_repository_registry(start: str | Path | None = None) -> Path | None:
+    """Find ``manifests/algorithms/registry.yaml`` in a source checkout."""
+
+    cursor = Path.cwd() if start is None else Path(start)
+    cursor = cursor.expanduser().resolve()
+    if cursor.is_file():
+        cursor = cursor.parent
+    for directory in (cursor, *cursor.parents):
+        candidate = directory / "manifests" / "algorithms" / "registry.yaml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def registry_documents_equal(left: RegistryDocument, right: RegistryDocument) -> bool:
+    """Compare semantic content independent of JSON formatting."""
+
+    return canonical_json(left.to_dict()) == canonical_json(right.to_dict())
+
+
+def validate_snapshot_sync(source_path: str | Path) -> tuple[RegistryDocument, RegistryDocument]:
+    """Validate a source registry and require equality with the package snapshot."""
+
+    source = load_registry_file(source_path)
+    packaged = load_packaged_registry()
+    if not registry_documents_equal(source, packaged):
+        raise RegistryError(
+            "source registry and packaged snapshot differ; run "
+            "`python scripts/check_registry.py --write`"
+        )
+    return source, packaged
+
+
+__all__ = [
+    "find_repository_registry",
+    "load_packaged_registry",
+    "load_registry_file",
+    "load_registry_text",
+    "registry_documents_equal",
+    "validate_snapshot_sync",
+]

agentinputlab/registry/result_manifest.py

@@ -0,0 +1,184 @@
+"""Fail-closed validation for a table's run-provenance index.
+
+The schema binds references to checksum-verified run directories and enforces
+one broad profile kind.  It does not itself prove that multiple runs share the
+same model/retriever/scorer setting, bind a rendered/serialized table,
+authenticate the process that produced a run, or establish scientific validity.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from agentinputlab.contracts.enums import ProfileKind
+from agentinputlab.contracts.errors import RegistryError
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _required_text(data: Mapping[str, Any], key: str, path: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise RegistryError(f"{path}.{key} must be a non-empty string")
+    return value
+
+
+def _profile_kind(value: Any, path: str) -> ProfileKind:
+    if not isinstance(value, str):
+        raise RegistryError(f"{path} must be a string")
+    try:
+        return ProfileKind(value)
+    except ValueError as exc:
+        allowed = ", ".join(item.value for item in ProfileKind)
+        raise RegistryError(f"{path} must be one of: {allowed}") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class ResultStudyReference:
+    """One checksum-consistent run reference contributing rows to a table.
+
+    These are operator-supplied references.  The beta gate re-opens ``run_path``
+    with :func:`verify_experiment_run_directory` and requires every identity to
+    match the run artifact exactly.  This detects mutation or substitution
+    relative to those identities; it is not proof that an external model,
+    scorer, or worker actually executed as claimed.
+    """
+
+    study_id: str
+    profile_kind: ProfileKind
+    profile_hash: str
+    run_path: str
+    run_identity_hash: str
+    manifest_hash: str
+    plan_hash: str
+    driver_hash: str
+
+    @classmethod
+    def from_mapping(cls, raw: Any, path: str) -> ResultStudyReference:
+        required = {
+            "study_id",
+            "profile_kind",
+            "profile_hash",
+            "run_path",
+            "run_identity_hash",
+            "manifest_hash",
+            "plan_hash",
+            "driver_hash",
+        }
+        if not isinstance(raw, Mapping) or set(raw) != required:
+            raise RegistryError(f"{path} fields must be exactly: {', '.join(sorted(required))}")
+        digests: dict[str, str] = {}
+        for key in (
+            "profile_hash",
+            "run_identity_hash",
+            "manifest_hash",
+            "plan_hash",
+            "driver_hash",
+        ):
+            value = _required_text(raw, key, path)
+            if not _SHA256.fullmatch(value):
+                raise RegistryError(f"{path}.{key} must be a lowercase SHA-256 digest")
+            digests[key] = value
+        return cls(
+            study_id=_required_text(raw, "study_id", path),
+            profile_kind=_profile_kind(raw.get("profile_kind"), f"{path}.profile_kind"),
+            profile_hash=digests["profile_hash"],
+            run_path=_required_text(raw, "run_path", path),
+            run_identity_hash=digests["run_identity_hash"],
+            manifest_hash=digests["manifest_hash"],
+            plan_hash=digests["plan_hash"],
+            driver_hash=digests["driver_hash"],
+        )
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "study_id": self.study_id,
+            "profile_kind": self.profile_kind.value,
+            "profile_hash": self.profile_hash,
+            "run_path": self.run_path,
+            "run_identity_hash": self.run_identity_hash,
+            "manifest_hash": self.manifest_hash,
+            "plan_hash": self.plan_hash,
+            "driver_hash": self.driver_hash,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ResultTableManifest:
+    """Run-provenance index and profile boundary for one prospective table.
+
+    Version 2 has no table-artifact path/hash or row-derivation mapping, so a
+    separately rendered table is not authenticated by this object alone.
+    """
+
+    table_id: str
+    profile_kind: ProfileKind
+    studies: tuple[ResultStudyReference, ...]
+    schema_version: int = 2
+
+    @classmethod
+    def from_mapping(cls, raw: Any) -> ResultTableManifest:
+        if not isinstance(raw, Mapping) or set(raw) != {
+            "schema_version",
+            "table_id",
+            "profile_kind",
+            "studies",
+        }:
+            raise RegistryError("result_table_manifest must be an object")
+        if raw.get("schema_version") != 2:
+            raise RegistryError("result_table_manifest.schema_version must equal 2")
+        raw_studies = raw.get("studies")
+        if not isinstance(raw_studies, list) or not raw_studies:
+            raise RegistryError("result_table_manifest.studies must be a non-empty array")
+        studies = tuple(
+            ResultStudyReference.from_mapping(
+                item,
+                f"result_table_manifest.studies[{index}]",
+            )
+            for index, item in enumerate(raw_studies)
+        )
+        study_ids = [item.study_id for item in studies]
+        if len(study_ids) != len(set(study_ids)):
+            raise RegistryError("result_table_manifest.studies contains duplicate study IDs")
+
+        declared_kind = _profile_kind(
+            raw.get("profile_kind"),
+            "result_table_manifest.profile_kind",
+        )
+        observed_kinds = {item.profile_kind for item in studies}
+        if observed_kinds != {declared_kind}:
+            rendered = ", ".join(sorted(item.value for item in observed_kinds))
+            raise RegistryError(
+                "one result table must not mix official_native, controlled_adapter, "
+                f"or factorial_adapter profiles; declared={declared_kind.value}, "
+                f"observed={rendered}"
+            )
+        return cls(
+            table_id=_required_text(raw, "table_id", "result_table_manifest"),
+            profile_kind=declared_kind,
+            studies=studies,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "table_id": self.table_id,
+            "profile_kind": self.profile_kind.value,
+            "studies": [item.to_dict() for item in self.studies],
+        }
+
+
+def validate_result_table_manifest(raw: Any) -> ResultTableManifest:
+    """Validate an immutable, single-profile-kind run-provenance index."""
+
+    return ResultTableManifest.from_mapping(raw)
+
+
+__all__ = [
+    "ResultStudyReference",
+    "ResultTableManifest",
+    "validate_result_table_manifest",
+]

agentinputlab/registry/runtime.py

@@ -0,0 +1,195 @@
+"""Runtime lookup, filtering, diagnostics, and lazy entry-point resolution."""
+
+from __future__ import annotations
+
+import importlib
+import threading
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from agentinputlab.contracts.enums import ReleaseTier, SemanticFamily, SupportStatus
+from agentinputlab.contracts.errors import AlgorithmUnavailableError, RegistryError
+
+from .loader import load_packaged_registry
+from .schema import AlgorithmCard, RegistryDocument, ReleaseProfile
+
+# Algorithm package initializers re-export sibling profiles. Serialize cold
+# imports across registry instances so concurrent first requests cannot acquire
+# sibling module locks in opposite orders. Warm model execution stays parallel.
+_ENTRYPOINT_IMPORT_LOCK = threading.RLock()
+
+
+@dataclass(frozen=True, slots=True)
+class RegistryDoctorReport:
+    """Human- and machine-readable registry health summary."""
+
+    ok: bool
+    method_count: int
+    release_count: int
+    core_count: int
+    optional_count: int
+    must_ship_count: int
+    entrypoint_count: int
+    locked_count: int
+    warnings: tuple[str, ...]
+    errors: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "method_count": self.method_count,
+            "release_count": self.release_count,
+            "core_count": self.core_count,
+            "optional_count": self.optional_count,
+            "must_ship_count": self.must_ship_count,
+            "entrypoint_count": self.entrypoint_count,
+            "locked_count": self.locked_count,
+            "warnings": list(self.warnings),
+            "errors": list(self.errors),
+        }
+
+
+class AlgorithmRegistry:
+    """Immutable indexed view of a validated :class:`RegistryDocument`."""
+
+    def __init__(self, document: RegistryDocument):
+        document.validate_roster()
+        self._document = document
+        self._methods = {item.method_id: item for item in document.algorithms}
+        self._releases: dict[str, tuple[AlgorithmCard, ReleaseProfile]] = {}
+        for method in document.algorithms:
+            for release in method.releases:
+                self._releases[release.id] = (method, release)
+
+    @classmethod
+    def default(cls) -> AlgorithmRegistry:
+        return cls(load_packaged_registry())
+
+    @property
+    def document(self) -> RegistryDocument:
+        return self._document
+
+    def list_methods(
+        self,
+        *,
+        family: SemanticFamily | str | None = None,
+        tier: ReleaseTier | str | None = None,
+        status: SupportStatus | str | None = None,
+    ) -> tuple[AlgorithmCard, ...]:
+        family_value = SemanticFamily(family) if isinstance(family, str) else family
+        tier_value = ReleaseTier(tier) if isinstance(tier, str) else tier
+        status_value = SupportStatus(status) if isinstance(status, str) else status
+        return tuple(
+            item
+            for item in self._document.algorithms
+            if (family_value is None or item.semantic_family is family_value)
+            and (tier_value is None or item.release_tier is tier_value)
+            and (status_value is None or item.status is status_value)
+        )
+
+    def list_releases(
+        self,
+        *,
+        family: SemanticFamily | str | None = None,
+        tier: ReleaseTier | str | None = None,
+        status: SupportStatus | str | None = None,
+        delivery_tier: str | None = None,
+    ) -> tuple[tuple[AlgorithmCard, ReleaseProfile], ...]:
+        status_value = SupportStatus(status) if isinstance(status, str) else status
+        methods = self.list_methods(family=family, tier=tier)
+        return tuple(
+            (method, release)
+            for method in methods
+            for release in method.releases
+            if (status_value is None or release.status is status_value)
+            and (delivery_tier is None or release.delivery_tier == delivery_tier)
+        )
+
+    def get_method(self, method_id: str) -> AlgorithmCard:
+        try:
+            return self._methods[method_id]
+        except KeyError as exc:
+            raise RegistryError(f"unknown algorithm method ID: {method_id}") from exc
+
+    def get_release(self, release_id: str) -> tuple[AlgorithmCard, ReleaseProfile]:
+        try:
+            return self._releases[release_id]
+        except KeyError as exc:
+            raise RegistryError(f"unknown algorithm release ID: {release_id}") from exc
+
+    def get(self, identity: str) -> AlgorithmCard | tuple[AlgorithmCard, ReleaseProfile]:
+        if identity in self._methods:
+            return self._methods[identity]
+        if identity in self._releases:
+            return self._releases[identity]
+        raise RegistryError(f"unknown algorithm or release ID: {identity}")
+
+    def resolve_entrypoint(self, release_id: str) -> Any:
+        """Import a declared adapter only when it is explicitly requested."""
+
+        _, release = self.get_release(release_id)
+        if release.entrypoint is None:
+            reasons = "; ".join(release.blocking_reasons) or "implementation is not registered"
+            raise AlgorithmUnavailableError(f"{release_id} is unavailable: {reasons}")
+        module_name, attribute_path = release.entrypoint.split(":", 1)
+        try:
+            with _ENTRYPOINT_IMPORT_LOCK:
+                value: Any = importlib.import_module(module_name)
+                for segment in attribute_path.split("."):
+                    value = getattr(value, segment)
+                return value
+        except (ImportError, AttributeError) as exc:
+            raise AlgorithmUnavailableError(
+                f"cannot resolve entrypoint {release.entrypoint!r} for {release_id}: {exc}"
+            ) from exc
+
+    def doctor(self) -> RegistryDoctorReport:
+        warnings: list[str] = []
+        errors: list[str] = []
+        for method in self._document.algorithms:
+            if method.upstream.license_id == "NOASSERTION":
+                warnings.append(
+                    f"{method.method_id}: upstream license is NOASSERTION; external/clean-room only"
+                )
+            for release in method.releases:
+                if release.must_ship and release.status not in {
+                    SupportStatus.EXPERIMENTAL,
+                    SupportStatus.SUPPORTED,
+                }:
+                    warnings.append(
+                        f"{release.id}: must-ship profile is {release.status.value}, "
+                        "not locally runnable without its declared gate"
+                    )
+                if (
+                    release.status
+                    in {
+                        SupportStatus.EXPERIMENTAL,
+                        SupportStatus.SUPPORTED,
+                    }
+                    and release.entrypoint is None
+                ):
+                    errors.append(f"{release.id}: {release.status.value} release has no entrypoint")
+        methods = self._document.algorithms
+        releases = self._document.releases
+        return RegistryDoctorReport(
+            ok=not errors,
+            method_count=len(methods),
+            release_count=len(releases),
+            core_count=sum(item.release_tier is ReleaseTier.CORE for item in methods),
+            optional_count=sum(item.release_tier is ReleaseTier.OPTIONAL for item in methods),
+            must_ship_count=sum(item.must_ship for item in releases),
+            entrypoint_count=sum(item.entrypoint_available for item in releases),
+            locked_count=sum(not item.entrypoint_available for item in releases),
+            warnings=tuple(warnings),
+            errors=tuple(errors),
+        )
+
+    def __iter__(self) -> Iterable[AlgorithmCard]:
+        return iter(self._document.algorithms)
+
+    def __len__(self) -> int:
+        return len(self._document.algorithms)
+
+
+__all__ = ["AlgorithmRegistry", "RegistryDoctorReport"]