hypermind 0.11.0__py3-none-any.whl

hypermind/__init__.py

@@ -0,0 +1,208 @@
+"""HyperMind — federated agent intelligence.
+
+Reference SDK for the `draft-hypermind-scitt-contested-claims-profile-00` profile.
+v0.1 alpha — in-process implementation suitable for sandbox/testbed use.
+
+Public surface (post-WS-F partial; ROADMAP §0.5.4–0.5.8):
+
+  - Top-level: ``HyperMindAgent``, ``CapToken``, ``Caveat``, ``Dispute``,
+    ``BlockReason``, ``open``, ``__version__``, ``__wire_version__``,
+    ``__protocol_version__``.
+  - ``hypermind.types`` — every supporting type re-exported. New code
+    SHOULD import from ``hypermind.types`` directly.
+  - ``hypermind.testing`` — ``testbed_cohort`` and other test helpers.
+
+The legacy root re-exports (``ClaimType``, ``Subscription``, etc.) remain
+available for compatibility but trigger ``PendingDeprecationWarning`` on
+attribute lookup. The shim escalates to ``DeprecationWarning`` in v0.7
+and is scheduled for removal in v1.0.
+"""
+
+from __future__ import annotations
+
+import warnings as _warnings
+from typing import TYPE_CHECKING, Any
+
+from hypermind import api as api
+from hypermind import responders as responders
+
+# Re-export storage + responders + api for one-line imports.
+# Late-binding via __getattr__ would also work, but explicit re-export
+# keeps mypy + pyright happy.
+from hypermind import storage as storage
+from hypermind.agent import HyperMindAgent
+from hypermind.capability import CapToken, Caveat
+from hypermind.consult import ConsultResult
+from hypermind.dispute import Dispute
+from hypermind.errors import (
+    AuthError,
+    BlockReason,
+    ConformanceError,
+    DisputeError,
+    HyperMindError,
+    KeyCompromiseError,
+    NetworkError,
+    ProtocolVersionError,
+    RampError,
+    RatePauseError,
+    UnresolvedPartitionError,
+)
+
+# v0.10 — install the agent-mind methods (pursue, tick, bind_deliberator,
+# .deliberator) onto HyperMindAgent. Idempotent + zero behavioural impact
+# on agents that don't call into the mind layer. See
+# docs/spec/19-autonomy-contract.md.
+from hypermind.mind import integration as _mind_integration
+from hypermind.namespace_policy import NamespacePolicy
+from hypermind.revocation import (
+    InMemoryRevocationStore,
+    RevocationEntry,
+    RevocationList,
+    RevocationStore,
+)
+from hypermind.uncertainty import Uncertainty
+
+_mind_integration.install()
+
+#: Canonical factory entry point — alias of :meth:`HyperMindAgent.open`.
+#: Use ``await hypermind.open(mode="sandbox")`` for v1.0-style code.
+open = HyperMindAgent.open
+
+#: SDK release tag. ``0.9.0a0`` reflects code-complete through ROADMAP §v0.9
+#: (conformance + wire-freeze scaffolding shipped). The trailing ``a0``
+#: is held until the §External & human gates clear (IETF I-D, IANA,
+#: third-party audit, OpenSSF acceptance, ≥3 pilots) — at that point we
+#: cut ``1.0.0`` GA. See ROADMAP.md §Status snapshot.
+__version__ = "0.11.0"
+
+#: SLSA build-provenance level committed for every release artefact.
+#: Cosign keyless signing + slsa-github-generator + PEP 740 attestations
+#: together satisfy the four SLSA L3 properties documented in
+#: docs/supply-chain/slsa.md.
+SLSA_LEVEL = 3  # documented in docs/supply-chain/slsa.md
+
+#: Wire format version — frozen at 0 through the entire v0.x line so a
+#: v0.1 verifier can still parse a v0.9 envelope. Bumps are reserved
+#: for v1.0+. See :mod:`hypermind.wire` docs.
+__wire_version__ = 0
+
+#: Protocol version negotiation primitive (ROADMAP §0.5.1). Held at 0
+#: through v0.x because ``open(protocol_version_max=…)`` advertises this
+#: number across the libp2p handshake; bumping is a federation break.
+__protocol_version__ = 0
+
+
+# ---------------------------------------------------------------------
+# v0.5 deprecation shim — types moved to ``hypermind.types`` and
+# ``hypermind.testing``. Legacy root attribute lookup fires
+# PendingDeprecationWarning (escalates in v0.7, removed in v1.0).
+# ---------------------------------------------------------------------
+
+_RELOCATED: dict[str, str] = {
+    # → hypermind.types
+    "ArgumentDAG": "hypermind.types",
+    "ArgumentEdge": "hypermind.types",
+    "CalibTruthSnapshot": "hypermind.types",
+    "ClaimEvent": "hypermind.types",
+    "ClaimType": "hypermind.types",
+    "DisputeStatus": "hypermind.types",
+    "Kid": "hypermind.types",
+    "PanelMember": "hypermind.types",
+    "PinPolicy": "hypermind.types",
+    "RouteStrategy": "hypermind.types",
+    "SignedStatement": "hypermind.types",
+    "Subscription": "hypermind.types",
+    "VouchRequest": "hypermind.types",
+    # → hypermind.testing
+    "testbed_cohort": "hypermind.testing",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy attribute lookup for deprecated root re-exports.
+
+    The legacy types still resolve to the same objects (so ``isinstance``
+    and identity checks keep working), but the lookup fires a
+    ``PendingDeprecationWarning`` pointing the caller at the new home.
+    """
+    if name in _RELOCATED:
+        target_module = _RELOCATED[name]
+        _warnings.warn(
+            f"hypermind.{name} is deprecated and will be removed in v1.0; "
+            f"import from {target_module} instead "
+            f"(e.g. ``from {target_module} import {name}``).",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
+        import importlib
+
+        mod = importlib.import_module(target_module)
+        value = getattr(mod, name)
+        return value
+    raise AttributeError(f"module 'hypermind' has no attribute {name!r}")
+
+
+if TYPE_CHECKING:  # pragma: no cover
+    # Help type checkers see the relocated symbols at the top level so
+    # `from hypermind import ClaimType` keeps working with full types.
+    from hypermind.testing import testbed_cohort
+    from hypermind.types import (
+        ArgumentDAG,
+        ArgumentEdge,
+        CalibTruthSnapshot,
+        ClaimEvent,
+        ClaimType,
+        DisputeStatus,
+        Kid,
+        PanelMember,
+        PinPolicy,
+        RouteStrategy,
+        SignedStatement,
+        Subscription,
+        VouchRequest,
+    )
+
+
+__all__ = [
+    "SLSA_LEVEL",
+    "ArgumentDAG",
+    "ArgumentEdge",
+    "AuthError",
+    "BlockReason",
+    "CalibTruthSnapshot",
+    "CapToken",
+    "Caveat",
+    "ClaimEvent",
+    "ClaimType",
+    "ConformanceError",
+    "ConsultResult",
+    "Dispute",
+    "DisputeError",
+    "DisputeStatus",
+    "HyperMindAgent",
+    "HyperMindError",
+    "InMemoryRevocationStore",
+    "KeyCompromiseError",
+    "Kid",
+    "NamespacePolicy",
+    "NetworkError",
+    "PanelMember",
+    "PinPolicy",
+    "ProtocolVersionError",
+    "RampError",
+    "RatePauseError",
+    "RevocationEntry",
+    "RevocationList",
+    "RevocationStore",
+    "RouteStrategy",
+    "SignedStatement",
+    "Subscription",
+    "Uncertainty",
+    "UnresolvedPartitionError",
+    "VouchRequest",
+    "__protocol_version__",
+    "__version__",
+    "__wire_version__",
+    "open",
+    "testbed_cohort",
+]

hypermind/_deprecations.py

@@ -0,0 +1,108 @@
+"""Centralised deprecation registry (ROADMAP §0.5.10).
+
+Every ``DeprecationWarning`` / ``PendingDeprecationWarning`` raise site
+in the SDK SHOULD look up its metadata from :data:`DEPRECATIONS` rather
+than hard-coding strings. The registry is the single source of truth
+for the N-release warning window: a release manager can grep this file
+to find all shims slated for removal in the next major.
+
+Each entry records:
+  * ``deprecated_in``  — the version that introduced the warning.
+  * ``replaced_by``    — fully-qualified name of the new symbol/path.
+  * ``removed_in``     — the version that drops the shim entirely.
+  * ``hint``           — a one-line migration tip.
+  * ``category``       — ``DeprecationWarning`` (default) or
+                         ``PendingDeprecationWarning``.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DeprecationInfo:
+    """Stable metadata for a single deprecation."""
+
+    symbol: str
+    deprecated_in: str
+    replaced_by: str
+    removed_in: str
+    hint: str
+    category: type[Warning] = DeprecationWarning
+
+    def message(self) -> str:
+        return (
+            f"{self.symbol} is deprecated since v{self.deprecated_in}; "
+            f"use {self.replaced_by} instead. "
+            f"Scheduled for removal in v{self.removed_in}. {self.hint}"
+        )
+
+
+# ---------------------------------------------------------------------
+# The registry.
+#
+# Keys are stable symbol identifiers. They are referenced by raise sites
+# and by `tests/test_deprecation_registry.py`.
+# ---------------------------------------------------------------------
+
+DEPRECATIONS: dict[str, DeprecationInfo] = {
+    "HyperMindAgent.from_env": DeprecationInfo(
+        symbol="HyperMindAgent.from_env()",
+        deprecated_in="0.7",
+        replaced_by="HyperMindAgent.open(mode=…)",
+        removed_in="1.0",
+        hint="See docs/migration/v0.7.md.",
+        category=PendingDeprecationWarning,
+    ),
+    "HyperMindAgent.testbed.list": DeprecationInfo(
+        symbol="HyperMindAgent.testbed(...) returning a plain list",
+        deprecated_in="0.5",
+        replaced_by="hypermind.testing.testbed_cohort(n=…)",
+        removed_in="1.0",
+        hint="The async-with cohort cleans up automatically.",
+    ),
+    "HyperMindAgent.classical_only": DeprecationInfo(
+        symbol="HyperMindAgent(pq=False) / legacy_ed25519=True",
+        deprecated_in="0.7",
+        replaced_by="pq=True (Composite Ed25519+ML-DSA-65)",
+        removed_in="1.0",
+        hint="Hybrid PQ is the default; classical-only is the legacy path.",
+    ),
+    "Dispute.close.no_witness_signatures": DeprecationInfo(
+        symbol="Dispute.close() without witness_signatures=…",
+        deprecated_in="0.8",
+        replaced_by="Dispute.close(witness_signatures=[…], quorum=k)",
+        removed_in="1.0",
+        hint="Single-witness sandbox path removed in v1.0; pass a k-of-n quorum "
+        "(rule HM-DISPUTE-QUORUM-001).",
+        category=FutureWarning,
+    ),
+    "hypermind.root.relocated": DeprecationInfo(
+        symbol="Top-level re-exports (ClaimType, Subscription, …)",
+        deprecated_in="0.5",
+        replaced_by="hypermind.types / hypermind.testing",
+        removed_in="1.0",
+        hint="Import the relocated symbol from its canonical module.",
+        category=PendingDeprecationWarning,
+    ),
+}
+
+
+def emit(key: str, *, stacklevel: int = 2, override_msg: str | None = None) -> None:
+    """Emit the warning registered under ``key``.
+
+    Raise ``KeyError`` if the key is not present (so a typo in the
+    raise-site fails loudly during testing).
+    """
+    info = DEPRECATIONS[key]
+    warnings.warn(override_msg or info.message(), info.category, stacklevel=stacklevel)
+
+
+def lookup(key: str) -> DeprecationInfo:
+    """Read-only access to a registry entry (raises KeyError on miss)."""
+    return DEPRECATIONS[key]
+
+
+__all__ = ["DEPRECATIONS", "DeprecationInfo", "emit", "lookup"]