apsimo 1.3.0__py3-none-any.whl

apsimo/identity/resolver.py

@@ -0,0 +1,329 @@
+"""IdentityResolver — normalize person identifiers across Colony subsystems.
+
+A person is referenced by different identifier formats depending on the
+subsystem:
+
+- Contact store: CID (``cid-<ts>-<rand>``), display name, platform handles
+- Neo4j graph: Person node ID (UUID), ``Person.name``
+- Affect store: ``contact_id`` (whatever the caller passed — historically
+  display names or CIDs)
+
+The contact store is the source of truth (Step 0 finding, v0.16.0 spec):
+a Contact record carries the CID, names, the linked Neo4j node via
+``person_node_id``, and all platform handles via the ``contact_handles``
+table. The resolver is an index over it.
+
+Owner identity rules:
+- The owner is resolved once from ``COLONY_OWNER_CONTACT_ID`` and cached.
+- ``COLONY_HOST_CONTACT_ID`` is accepted as a deprecated alias.
+- A configured-but-unresolvable owner raises :class:`OwnerIdentityError`.
+  There is NO fallback to a default string — the silent ``"owner"``
+  default was the bug this module replaces. Callers that filter the owner
+  out of generated work must fail closed (generate nothing) rather than
+  fall through.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import Any, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+_PHONE_RE = re.compile(r"^\+?[\d\s().-]{7,}$")
+
+from apsimo.channels.phone_gateways import get_phone_gateways as _get_phone_gateways
+
+
+class OwnerIdentityError(RuntimeError):
+    """The owner's identity is missing or cannot be resolved."""
+
+
+def get_owner_contact_id() -> Optional[str]:
+    """Return the configured owner contact ID, honouring the legacy alias.
+
+    ``COLONY_OWNER_CONTACT_ID`` is canonical. ``COLONY_HOST_CONTACT_ID``
+    is accepted with a deprecation warning so running deployments keep
+    their config. Returns None when neither is set — callers must treat
+    that as "owner unknown", never as a default string.
+    """
+    owner = os.environ.get("COLONY_OWNER_CONTACT_ID")
+    if owner:
+        return owner
+    legacy = os.environ.get("COLONY_HOST_CONTACT_ID")
+    if legacy:
+        logger.warning(
+            "COLONY_HOST_CONTACT_ID is deprecated, use COLONY_OWNER_CONTACT_ID"
+        )
+        return legacy
+    return None
+
+
+def get_owner_name(default: str = "the owner") -> str:
+    """Human-readable owner name for prompts/messages.
+
+    Deployment-agnostic: the generic build must never hardcode a person's name.
+    Set ``COLONY_OWNER_NAME`` in the deployment env; otherwise a neutral term
+    ("the owner") is used so the public code carries no personal identity.
+    """
+    return os.environ.get("COLONY_OWNER_NAME") or default
+
+
+def get_persona_name(default: str = "the assistant") -> str:
+    """Human-readable persona/agent name for tool descriptions and prompts.
+
+    Same rule: the deployment sets ``COLONY_PERSONA_NAME``; the generic default
+    is neutral so the public code names no specific product.
+    """
+    return os.environ.get("COLONY_PERSONA_NAME") or default
+
+
+class IdentityResolver:
+    """Resolve any identifier for a person to the set of all known forms.
+
+    Backed by the contact store (async API). When the contact store is
+    unavailable the resolver degrades to exact-match on the configured
+    value only — it never invents identifiers.
+    """
+
+    def __init__(
+        self,
+        contact_store: Any = None,
+        owner_id: Optional[str] = None,
+    ) -> None:
+        self._contact_store = contact_store
+        # Capture explicitly so tests can construct without env mutation.
+        self._owner_id = owner_id if owner_id is not None else get_owner_contact_id()
+        self._owner_set: Optional[frozenset] = None
+        self._identity_revision = None
+        # Small bounded cache of is_owner verdicts (one tick scans ~100
+        # contacts; name resolution is a full-table similarity scan).
+        self._is_owner_cache: dict = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def resolve(self, any_id: str) -> Set[str]:
+        """Given any identifier for a person, return all known forms.
+
+        Returns an empty set when the identifier is unknown or ambiguous
+        (display names are not unique — an ambiguous name must not merge
+        two people into one).
+        """
+        if not any_id or not isinstance(any_id, str):
+            return set()
+        contact = await self._lookup(any_id.strip())
+        if contact is None:
+            return set()
+        return await self._identity_set(contact)
+
+    async def is_owner(self, any_id: Any) -> bool:
+        """True if ``any_id`` resolves into the owner's identity set.
+
+        Raises :class:`OwnerIdentityError` when the owner identity itself
+        cannot be established (missing config, or config that resolves to
+        nothing). Callers in generation paths must fail closed on that.
+        """
+        if not any_id:
+            return False
+        owners = await self.owner_identities()
+        key = str(any_id).strip()
+        cached = self._is_owner_cache.get(key)
+        if cached is not None:
+            return cached
+
+        verdict = key in owners or key.lower() in owners
+        if not verdict:
+            # Cross-format check: resolve the candidate and intersect.
+            try:
+                forms = await self.resolve(key)
+            except Exception as exc:  # resolution must never break filtering
+                logger.warning("Identity resolution failed for %r: %s", key, exc)
+                forms = set()
+            verdict = bool(forms & owners)
+
+        if len(self._is_owner_cache) > 512:
+            self._is_owner_cache.clear()
+        self._is_owner_cache[key] = verdict
+        return verdict
+
+    async def owner_identities(self) -> frozenset:
+        """Resolve and cache the owner's full identity set.
+
+        Raises :class:`OwnerIdentityError` if no owner is configured, or if
+        the configured value resolves to nothing in the contact store.
+        """
+        revision_reader = getattr(self._contact_store, 'identity_revision', None)
+        if revision_reader is not None:
+            revision = await revision_reader()
+            if revision != self._identity_revision:
+                self._owner_set = None
+                self._is_owner_cache.clear()
+                self._identity_revision = revision
+        if self._owner_set is not None:
+            return self._owner_set
+
+        owner_id = self._owner_id
+        if not owner_id:
+            raise OwnerIdentityError(
+                "COLONY_OWNER_CONTACT_ID is not set. Owner-exclusion filters "
+                "cannot run; set it to the owner's contact CID, Neo4j Person "
+                "ID, or an unambiguous display name."
+            )
+
+        if self._contact_store is None:
+            # No identity index available — exact-match on the configured
+            # value (plus case folding). This is the operator's own value,
+            # not a made-up default, so it is safe to use directly.
+            logger.warning(
+                "Contact store unavailable — owner exclusion limited to "
+                "exact matches on %r", owner_id,
+            )
+            self._owner_set = frozenset({owner_id, owner_id.lower()})
+            return self._owner_set
+
+        forms = await self.resolve(owner_id)
+        if not forms:
+            raise OwnerIdentityError(
+                f"COLONY_OWNER_CONTACT_ID={owner_id!r} does not resolve to "
+                "any contact. Fix the config — refusing to guess."
+            )
+        # Always include the configured literal so equality checks against
+        # raw config values keep working.
+        forms |= {owner_id, owner_id.lower()}
+        self._owner_set = frozenset(forms)
+        logger.info(
+            "Owner identity resolved: %d identifier forms cached", len(forms)
+        )
+        return self._owner_set
+
+    def invalidate(self) -> None:
+        """Drop cached owner identity and verdicts (e.g. after a contact merge)."""
+        self._owner_set = None
+        self._is_owner_cache.clear()
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _lookup(self, any_id: str) -> Any:
+        """Find the Contact record for an identifier of any format."""
+        store = self._contact_store
+        if store is None:
+            return None
+
+        # CID — primary key lookup.
+        if any_id.startswith("cid-"):
+            return await store.get(any_id)
+
+        # Email handle.
+        if "@" in any_id:
+            return await store.resolve_handle("email", any_id)
+
+        # Phone-like handle.
+        if _PHONE_RE.match(any_id):
+            for gateway in _get_phone_gateways():
+                contact = await store.resolve_handle(gateway, any_id)
+                if contact is not None:
+                    return contact
+            return None
+
+        # Neo4j Person node ID (UUID) — forward link lives on the contact.
+        contact = await store.find_by_person_node_id(any_id)
+        if contact is not None:
+            return contact
+
+        # Display name — only when unambiguous. Names are not unique.
+        try:
+            matches = await store.find_by_name(any_id, threshold=0.9)
+        except Exception as exc:
+            logger.warning("find_by_name failed for %r: %s", any_id, exc)
+            return None
+        wanted = any_id.lower()
+        exact = [
+            m for m in matches
+            if (m.display_name or "").strip().lower() == wanted
+        ]
+        candidates = exact or matches
+        if len(candidates) == 1:
+            return candidates[0]
+        if len(candidates) > 1:
+            logger.warning(
+                "Ambiguous identity %r: %d contacts match — returning no "
+                "identity rather than merging people", any_id, len(candidates),
+            )
+        return None
+
+    async def _identity_set(self, contact: Any) -> Set[str]:
+        """All known identifier forms for a resolved contact."""
+        forms: Set[str] = {contact.contact_id}
+
+        display_name = getattr(contact, "display_name", None)
+        if display_name:
+            forms.add(display_name)
+        given = getattr(contact, "given_name", None)
+        family = getattr(contact, "family_name", None)
+        if given and family:
+            forms.add(f"{given} {family}")
+        person_node_id = getattr(contact, "person_node_id", None)
+        if person_node_id:
+            forms.add(person_node_id)
+
+        if self._contact_store is not None:
+            try:
+                handles = await self._contact_store.get_handles(contact.contact_id)
+                for handle in handles:
+                    from apsimo.contacts.identity_links import usable_handle
+                    if not usable_handle(handle):
+                        continue
+                    address = getattr(handle, "address", None)
+                    if address:
+                        forms.add(address)
+            except Exception as exc:
+                logger.debug(
+                    "Handle lookup failed for %s: %s", contact.contact_id, exc
+                )
+
+        # Case-folded variants for case-insensitive membership checks.
+        forms |= {f.lower() for f in list(forms)}
+        return forms
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+_resolver: Optional[IdentityResolver] = None
+
+
+def get_identity_resolver(contact_store: Any = None) -> IdentityResolver:
+    """Return the process-wide resolver, creating it on first use.
+
+    When ``contact_store`` is not supplied, the contact store registered
+    with the host router is used (same late-binding pattern as
+    ``SubsystemRegistry``).
+    """
+    global _resolver
+    if contact_store is None:
+        try:
+            from apsimo.api.routers import host as _host_mod
+            contact_store = getattr(_host_mod, "_contacts_store", None)
+        except Exception:
+            contact_store = None
+
+    if _resolver is None:
+        _resolver = IdentityResolver(contact_store=contact_store)
+    elif contact_store is not None and _resolver._contact_store is None:
+        # The contact store comes up after the resolver in some boot orders.
+        _resolver._contact_store = contact_store
+        _resolver.invalidate()
+    return _resolver
+
+
+def reset_identity_resolver() -> None:
+    """Reset the singleton (tests and reconfiguration)."""
+    global _resolver
+    _resolver = None

apsimo/identity_bootstrap/__init__.py

@@ -0,0 +1,5 @@
+"""Colony Identity Bootstrap — seeds every data system with self-knowledge at startup."""
+
+from apsimo.identity_bootstrap.runner import IdentityBootstrap
+
+__all__ = ["IdentityBootstrap"]

apsimo/identity_bootstrap/builder.py

@@ -0,0 +1,208 @@
+"""Colony Identity Bootstrap — IdentityBootstrapBuilder.
+
+Assembles a SelfKnowledgeCorpus at runtime by reading colony_id, version,
+network info, and public key from the running system.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Optional
+
+from apsimo.identity_bootstrap.corpus import (
+    CORPUS_VERSION,
+    GATE_LAYERS,
+    INFERENCE_TIERS,
+    API_ENDPOINTS,
+    COGNITION_PHASES,
+    LAYERS,
+    InferenceTier,
+    SelfKnowledgeCorpus,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _colony_version() -> str:
+    """Return Colony version from canonical source."""
+    # Canonical: colony_cli.__init__ (full_version_string returns "0.3.0-h6")
+    try:
+        from colony_cli import full_version_string
+        return full_version_string()
+    except Exception:
+        pass
+    # Fallback: importlib metadata (reads pyproject.toml version)
+    try:
+        from importlib.metadata import version
+        return version("colony")
+    except Exception:
+        pass
+    try:
+        from importlib.metadata import version
+        return version("colony-ai")
+    except Exception:
+        pass
+    return "0.3.0-h6"
+
+
+def _read_colony_id(chain_manager: Optional[Any]) -> str:
+    """Read colony_id from ChainManager, chain.db, or environment.
+
+    Priority order:
+    1. ChainManager.colony_id (if ChainManager is initialized)
+    2. COLONY_ID environment variable
+    3. Genesis block genesis_colony_id from chain.db (crypto identity)
+    4. Hostname-based fallback (last resort)
+    """
+    if chain_manager is not None:
+        try:
+            cid = chain_manager.colony_id
+            if cid and cid != "local":
+                return str(cid)
+        except Exception as exc:
+            logger.debug("ChainManager.colony_id unavailable: %s", exc)
+
+    env_id = os.environ.get("COLONY_ID", "")
+    if env_id:
+        return env_id
+
+    # Read genesis_colony_id directly from chain.db — this is the
+    # cryptographic identity (sha256 of Ed25519 pubkey) that proves
+    # genesis admin authority.  Avoids the hostname fallback when the
+    # ChainManager singleton hasn't been constructed yet.
+    import json
+    import sqlite3
+    colony_home = os.environ.get(
+        "COLONY_HOME",
+        os.path.join(os.path.expanduser("~"), ".colony"),
+    )
+    chain_db = os.path.join(colony_home, "chain.db")
+    if os.path.exists(chain_db):
+        try:
+            conn = sqlite3.connect(chain_db)
+            row = conn.execute(
+                "SELECT raw_json FROM chain_blocks WHERE block_index = 0"
+            ).fetchone()
+            conn.close()
+            if row:
+                genesis_data = json.loads(row[0])
+                cid = genesis_data.get("metadata", {}).get("genesis_colony_id")
+                if cid:
+                    return cid
+        except Exception as exc:
+            logger.debug("_read_colony_id chain.db fallback failed: %s", exc)
+
+    # Last resort: hostname-based stable ID
+    import socket
+    import hashlib
+    raw = f"{socket.gethostname()}-colony"
+    return "col-" + hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def _read_network_id(chain_manager: Optional[Any]) -> str:
+    try:
+        if chain_manager is not None:
+            state = getattr(chain_manager, "state", None)
+            if state is not None:
+                nid = getattr(state, "network_id", None) or getattr(state, "genesis_hash", None)
+                if nid:
+                    return str(nid)
+    except Exception:
+        pass
+    return os.environ.get("COLONY_NETWORK_ID", "local")
+
+
+def _read_public_key(chain_manager: Optional[Any]) -> Optional[str]:
+    try:
+        if chain_manager is not None:
+            keys = getattr(chain_manager, "keys", None)
+            if keys is not None:
+                pub = getattr(keys, "public_key_hex", None) or getattr(keys, "public_key", None)
+                if pub:
+                    return str(pub)
+    except Exception:
+        pass
+    return None
+
+
+def _resolve_inference_tiers() -> list[InferenceTier]:
+    """Return INFERENCE_TIERS with model names populated from the live LLMRouter config.
+
+    The static corpus stores no provider-specific model names.  This function
+    reads them from ``colony.router.tiers.DEFAULT_TIERS`` at runtime so the
+    corpus always reflects whichever models are actually configured.
+    Falls back to the static definitions (empty model lists) if the router
+    module is unavailable.
+    """
+    # Tier index → ModelTier enum value in the router
+    try:
+        from apsimo.router.tiers import DEFAULT_TIERS, ModelTier  # type: ignore[import]
+
+        tier_index_to_router: dict[int, ModelTier] = {
+            0: ModelTier.SMALL,
+            1: ModelTier.MEDIUM,
+            2: ModelTier.LARGE,
+        }
+        resolved: list[InferenceTier] = []
+        for tier in INFERENCE_TIERS:
+            router_tier = tier_index_to_router.get(tier.tier_index)
+            if router_tier is not None and router_tier in DEFAULT_TIERS:
+                model_id = DEFAULT_TIERS[router_tier].model_id
+                resolved.append(
+                    InferenceTier(
+                        name=tier.name,
+                        description=tier.description,
+                        complexity_range=tier.complexity_range,
+                        models=[model_id],
+                        tier_index=tier.tier_index,
+                    )
+                )
+            else:
+                resolved.append(tier)
+        return resolved
+    except Exception as exc:
+        logger.debug("Could not resolve inference tiers from router config: %s", exc)
+        return list(INFERENCE_TIERS)
+
+
+class IdentityBootstrapBuilder:
+    """Builds a SelfKnowledgeCorpus by introspecting the running Colony instance."""
+
+    def __init__(self, chain_manager: Optional[Any] = None) -> None:
+        self._chain_manager = chain_manager
+
+    def build(self) -> SelfKnowledgeCorpus:
+        colony_id = _read_colony_id(self._chain_manager)
+        colony_name = os.environ.get("COLONY_NAME", f"colony-{colony_id[:8]}")
+        colony_version = _colony_version()
+        network_id = _read_network_id(self._chain_manager)
+        public_key_hex = _read_public_key(self._chain_manager)
+
+        corpus = SelfKnowledgeCorpus(
+            colony_id=colony_id,
+            colony_name=colony_name,
+            colony_version=colony_version,
+            network_id=network_id,
+            public_key_hex=public_key_hex,
+            layers=list(LAYERS),
+            api_endpoints=list(API_ENDPOINTS),
+            cognition_phases=list(COGNITION_PHASES),
+            gate_layers=list(GATE_LAYERS),
+            inference_tiers=_resolve_inference_tiers(),
+            corpus_version=CORPUS_VERSION,
+            properties={
+                "colony_home": os.environ.get(
+                    "COLONY_HOME",
+                    os.path.join(os.path.expanduser("~"), ".colony"),
+                ),
+                "python_version": _python_version(),
+            },
+        )
+        return corpus
+
+
+def _python_version() -> str:
+    import sys
+    v = sys.version_info
+    return f"{v.major}.{v.minor}.{v.micro}"