apsimo 1.3.0__py3-none-any.whl

apsimo/initiatives/approval_policy.py

@@ -0,0 +1,123 @@
+"""Graduated approval policy helpers (v0.18.0) — outbound target checks.
+
+The owner's policy: nothing waits on a manual approval unless it is
+potentially destructive or an outreach to an individual the owner hasn't
+authorized yet. The destructive half lives in the action registry's risk
+tiers; this module answers the other half — *who* an OUTBOUND action
+reaches, and whether that person is an authorized contact.
+
+An OUTBOUND :class:`~apsimo.initiatives.action_registry.ActionSpec`
+names the param holding its recipient via ``target_param``. The recipient
+value is resolved against the contact store:
+
+- ``gateway:address`` forms (``email:bob@x.com``, ``imessage:+1555...``)
+  resolve via ``resolve_handle``;
+- ``cid-...`` resolves via ``get``;
+- bare emails resolve via ``resolve_handle("email", ...)``;
+- anything else falls back to ``find_by_name`` — and only an
+  unambiguous match counts (names are not unique; an ambiguous name must
+  not authorize the wrong person).
+
+The check fails closed: missing store, missing/unresolvable target, or a
+contact with ``interaction_allowed=False`` all deny auto-approval.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional, Tuple
+
+from apsimo.contacts.models import GATEWAYS
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_target(params: Optional[Dict[str, Any]], spec: Any) -> Optional[str]:
+    """Pull the recipient value named by ``spec.target_param``.
+
+    Looks in the job params themselves, then the nested ``context`` and
+    ``params`` dicts (the autonomy loop carries initiative context under
+    ``context``).
+    """
+    key = getattr(spec, "target_param", None) if spec is not None else None
+    if not key or not isinstance(params, dict):
+        return None
+    containers = (params, params.get("context"), params.get("params"))
+    for container in containers:
+        if not isinstance(container, dict):
+            continue
+        value = container.get(key)
+        if value:
+            return str(value).strip()
+    return None
+
+
+async def _resolve_contact(target: str, contacts_store: Any) -> Optional[Any]:
+    """Resolve a recipient identifier to a Contact, or None."""
+    # gateway:address form (email:bob@x.com, imessage:+15551234567, ...)
+    if ":" in target:
+        gateway, _, address = target.partition(":")
+        gateway = gateway.strip().lower()
+        address = address.strip()
+        if gateway in GATEWAYS and address:
+            return await contacts_store.resolve_handle(gateway, address)
+
+    # Contact ID — primary key lookup.
+    if target.startswith("cid-"):
+        return await contacts_store.get(target)
+
+    # Bare email handle.
+    if "@" in target:
+        return await contacts_store.resolve_handle("email", target)
+
+    # Display name — only when unambiguous (mirrors IdentityResolver).
+    matches = await contacts_store.find_by_name(target, threshold=0.9)
+    wanted = target.lower()
+    exact = [
+        m for m in matches
+        if (getattr(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 outbound target %r: %d contacts match — refusing "
+            "to authorize", target, len(candidates),
+        )
+    return None
+
+
+async def is_authorized_target(
+    params: Optional[Dict[str, Any]],
+    spec: Any,
+    contacts_store: Any,
+) -> Tuple[bool, str]:
+    """Is the recipient of an OUTBOUND action an authorized contact?
+
+    Returns ``(True, "contact:<cid>")`` only when the recipient named by
+    ``spec.target_param`` resolves to a contact with
+    ``interaction_allowed=True``. Everything else fails closed:
+
+    - no contact store wired → ``(False, "no_contact_store")``
+    - missing/unresolvable target → ``(False, "unknown_target")``
+    - contact found but not authorized → ``(False, "contact_not_authorized")``
+    """
+    if contacts_store is None:
+        return False, "no_contact_store"
+
+    target = _extract_target(params, spec)
+    if not target:
+        return False, "unknown_target"
+
+    try:
+        contact = await _resolve_contact(target, contacts_store)
+    except Exception as exc:  # resolution must never break dispatch
+        logger.warning("Outbound target resolution failed for %r: %s", target, exc)
+        return False, "unknown_target"
+
+    if contact is None:
+        return False, "unknown_target"
+    if not getattr(contact, "interaction_allowed", False):
+        return False, "contact_not_authorized"
+    return True, f"contact:{getattr(contact, 'contact_id', 'unknown')}"

apsimo/initiatives/assignment.py

@@ -0,0 +1,263 @@
+"""Assignment Engine for multi-agent Colony.
+
+Provides:
+- Agent selection for initiatives
+- Capability matching
+- Load balancing
+- Priority handling
+"""
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Initiative type → required capabilities
+INITIATIVE_CAPABILITIES: Dict[str, List[str]] = {
+    "follow_up": [],  # Any agent
+    "relationship": ["messaging"],  # Needs messaging
+    "scheduling": ["calendar"],  # Needs calendar
+    "coding": ["coding"],  # Needs code execution
+    "health": [],  # Any agent
+}
+
+# Types that should prefer primary agent
+USER_FACING_TYPES = ["follow_up", "relationship"]
+
+# Default for unknown types
+UNKNOWN_TYPE_POLICY = "allow_any"  # "reject", "log_and_allow", "allow_any"
+
+
+class AssignmentEngine:
+    """Selects the best agent for an initiative."""
+
+    def __init__(
+        self,
+        agent_store: Any,
+        initiative_store: Any,
+        unknown_type_policy: str = UNKNOWN_TYPE_POLICY,
+    ):
+        self._agent_store = agent_store
+        self._initiative_store = initiative_store
+        self._unknown_type_policy = unknown_type_policy
+
+    def select_agent(
+        self,
+        initiative: Any,
+        agents: Optional[List[Any]] = None,
+    ) -> Optional[Any]:
+        """Select the best agent for an initiative.
+
+        Priority:
+        1. Online status
+        2. Preferred agent (if specified)
+        3. Capability match
+        4. Type restrictions
+        5. Primary designation (for user-facing)
+        6. Load balancing
+        7. Capacity check
+
+        Args:
+            initiative: Initiative to assign (StoredInitiative or dict)
+            agents: List of agents to choose from (if None, loads from store)
+
+        Returns:
+            Selected Agent or None if no suitable agent found
+        """
+        # Get initiative type
+        init_type = self._get_initiative_type(initiative)
+
+        # Check if type is known
+        if init_type not in INITIATIVE_CAPABILITIES:
+            if self._unknown_type_policy == "reject":
+                logger.warning("Unknown initiative type: %s, rejecting", init_type)
+                return None
+            elif self._unknown_type_policy == "log_and_allow":
+                logger.warning("Unknown initiative type: %s, allowing any agent", init_type)
+
+        # Get agents if not provided
+        if agents is None:
+            agents = self._agent_store.list(status=["online"])
+
+        # Step 1: Only online agents
+        candidates = [a for a in agents if a.status == "online"]
+        if not candidates:
+            return None
+
+        # Step 2: Preferred agent (if specified)
+        preferred_id = self._get_preferred_agent_id(initiative)
+        if preferred_id:
+            preferred = next(
+                (a for a in candidates if a.agent_id == preferred_id),
+                None
+            )
+            if preferred and self._has_capacity(preferred):
+                return preferred
+
+        # Step 3: Capability filter
+        required_caps = INITIATIVE_CAPABILITIES.get(init_type, [])
+        if required_caps:
+            candidates = [
+                a for a in candidates
+                if a.has_capabilities(required_caps)
+            ]
+
+        if not candidates:
+            logger.debug(
+                "No agents with capabilities %s for initiative type %s",
+                required_caps,
+                init_type,
+            )
+            return None
+
+        # Step 4: Type restrictions (excluded/included types)
+        filtered = []
+        for agent in candidates:
+            if not agent.can_handle_type(init_type):
+                continue
+            filtered.append(agent)
+
+        candidates = filtered if filtered else candidates
+
+        if not candidates:
+            return None
+
+        # Step 5: Primary preference for user-facing
+        if init_type in USER_FACING_TYPES:
+            primaries = [a for a in candidates if a.is_primary]
+            if primaries:
+                candidates = primaries
+
+        # Step 6: Sort by load (ascending), then priority (descending)
+        candidates.sort(key=lambda a: (
+            a.load,
+            -a.priority,
+        ))
+
+        # Step 7: Capacity check
+        candidates = [a for a in candidates if a.has_capacity]
+
+        return candidates[0] if candidates else None
+
+    async def assign(
+        self,
+        initiative: Any,
+        agent: Optional[Any] = None,
+    ) -> Optional[Any]:
+        """Assign initiative to agent.
+
+        Args:
+            initiative: Initiative to assign
+            agent: Specific agent to assign to (if None, auto-select)
+
+        Returns:
+            Assigned agent or None if assignment failed
+        """
+        # Get initiative ID and type
+        init_id = self._get_initiative_id(initiative)
+        if not init_id:
+            return None
+
+        # Select agent if not provided
+        if agent is None:
+            agent = self.select_agent(initiative)
+
+        if not agent:
+            logger.debug("No agent available for initiative %s", init_id)
+            return None
+
+        # Assign via store
+        assigned = self._initiative_store.assign(
+            init_id,
+            agent.agent_id,
+            agent_name=agent.name,
+        )
+
+        if assigned:
+            # Update agent assignment count
+            self._agent_store.increment_assignments(agent.agent_id)
+            logger.info(
+                "Assigned initiative %s to agent %s (%s)",
+                init_id,
+                agent.agent_id,
+                agent.name,
+            )
+            return agent
+
+        return None
+
+    async def auto_assign_pending(self, limit: int = 50) -> int:
+        """Auto-assign all pending initiatives.
+
+        Args:
+            limit: Maximum initiatives to assign
+
+        Returns:
+            Number of initiatives assigned
+        """
+        pending = self._initiative_store.list(
+            status=["pending"],
+            limit=limit,
+        )
+
+        assigned = 0
+        for initiative in pending:
+            agent = await self.assign(initiative)
+            if agent:
+                assigned += 1
+
+        return assigned
+
+    def _get_initiative_type(self, initiative: Any) -> str:
+        """Get initiative type from object or dict."""
+        if hasattr(initiative, "type"):
+            return initiative.type.value if hasattr(initiative.type, "value") else str(initiative.type)
+        if isinstance(initiative, dict):
+            return initiative.get("type", "unknown")
+        return "unknown"
+
+    def _get_initiative_id(self, initiative: Any) -> Optional[str]:
+        """Get initiative ID from object or dict."""
+        if hasattr(initiative, "id"):
+            return initiative.id
+        if isinstance(initiative, dict):
+            return initiative.get("id")
+        return None
+
+    def _get_preferred_agent_id(self, initiative: Any) -> Optional[str]:
+        """Get preferred agent ID from initiative."""
+        if hasattr(initiative, "preferred_agent_id"):
+            return initiative.preferred_agent_id
+        if isinstance(initiative, dict):
+            return initiative.get("preferred_agent_id")
+        return None
+
+    def _has_capacity(self, agent: Any) -> bool:
+        """Check if agent has capacity for more assignments."""
+        # Check max concurrent
+        if agent.current_assignments >= agent.max_concurrent:
+            return False
+
+        # Check hourly rate limit. The agents table carries a
+        # max_initiatives_per_hour column (default 10) that previously had no
+        # enforcement — counting `assigned` rows from the assignment_history
+        # within the last hour closes that gap. A value of 0 disables the
+        # limit; <0 is treated as 0 (off).
+        max_per_hour = getattr(agent, "max_initiatives_per_hour", 0) or 0
+        if max_per_hour > 0:
+            try:
+                since = datetime.now(timezone.utc) - timedelta(hours=1)
+                recent = self._initiative_store.count_agent_assignments_since(
+                    agent.agent_id, since
+                )
+                if recent >= max_per_hour:
+                    return False
+            except (AttributeError, TypeError):
+                # Store does not expose the counter (older deployments or
+                # unit-test doubles) — fall back to the max_concurrent gate
+                # rather than blocking all assignments.
+                pass
+
+        return True

apsimo/initiatives/backup_evidence.py

@@ -0,0 +1,100 @@
+"""Read a deployment-selected backup attempt receipt, without running a backup.
+
+The producer owns capture and publication. A receipt reports capture completion,
+not archive verification, restore readiness, or coverage of other destinations.
+"""
+from datetime import datetime, timezone
+import hashlib
+import json
+from pathlib import Path
+import re
+
+
+MAX_RECEIPT_BYTES = 65536
+MAX_AGE_DAYS = 7  # Preserve the existing operational backup review interval.
+
+
+def _read(path):
+    with path.open('rb') as stream:
+        raw = stream.read(MAX_RECEIPT_BYTES + 1)
+    if len(raw) > MAX_RECEIPT_BYTES:
+        raise ValueError('receipt exceeds bound')
+    return raw, json.loads(raw)
+
+
+def _time(value, now):
+    if not isinstance(value, str):
+        raise ValueError('missing timestamp')
+    parsed = datetime.fromisoformat(value.replace('Z', '+00:00'))
+    if parsed.tzinfo is None or parsed > now:
+        raise ValueError('timestamp is naive or in the future')
+    return parsed.astimezone(timezone.utc)
+
+
+def backup_review_task(configured_path: str, now: datetime):
+    """Return a scoped review or None for a recent, bound successful receipt.
+
+    Contract v1: schema_version, status, completed_at, captured_at, receipt_path,
+    receipt_sha256. A captured attempt references an immutable local receipt by
+    relative path and SHA256; a failed attempt has null capture/reference fields.
+    Only the receipt bytes are verified here, never archive bytes or restoration.
+    """
+    path = Path(configured_path).expanduser().absolute()
+    task = {
+        'entity_id': 'database_backup', 'entity_type': 'backup',
+        'evidence_scope': 'configured_backup_receipt', 'evidence_path': str(path),
+        'observed_at': now.isoformat(), 'receipt_status': 'unavailable',
+        'captured_at': None, 'completed_at': None,
+        'receipt_path': None, 'receipt_sha256': None,
+        'description': 'Review configured backup evidence: latest attempt receipt is unavailable; capture freshness and recovery coverage are unknown',
+    }
+    try:
+        _, value = _read(path)
+        required = {'schema_version', 'status', 'completed_at', 'captured_at', 'receipt_path', 'receipt_sha256'}
+        if (not isinstance(value, dict) or not required.issubset(value)
+                or value.get('schema_version') != 1):
+            raise ValueError('unsupported receipt schema')
+        status = value.get('status')
+        completed = _time(value.get('completed_at'), now)
+        if status == 'captured':
+            captured = _time(value.get('captured_at'), now)
+            if captured > completed:
+                raise ValueError('capture follows completion')
+            relative = value.get('receipt_path')
+            digest = value.get('receipt_sha256')
+            if (not isinstance(relative, str) or not relative
+                    or Path(relative).is_absolute()
+                    or not isinstance(digest, str)
+                    or not re.fullmatch('[0-9a-f]{64}', digest)):
+                raise ValueError('missing receipt reference')
+            receipt_path = (path.parent / relative).resolve()
+            if not receipt_path.is_relative_to(path.parent.resolve()):
+                raise ValueError('receipt is outside configured destination')
+            raw, receipt = _read(receipt_path)
+            if (hashlib.sha256(raw).hexdigest() != digest
+                    or not isinstance(receipt, dict)
+                    or receipt.get('status') != 'captured'
+                    or _time(receipt.get('at'), now) != captured):
+                raise ValueError('capture receipt binding mismatch')
+            age = (now - captured).total_seconds() / 86400
+            if age <= MAX_AGE_DAYS:
+                return None
+            task.update(
+                captured_at=captured.isoformat(), receipt_path=str(receipt_path),
+                receipt_sha256=digest, age_days=age,
+                description=f'Review configured backup capture: latest completed capture is {age:.0f} days old; recovery readiness is unverified',
+            )
+        elif status == 'failed':
+            if any(value.get(key) is not None for key in ('captured_at', 'receipt_path', 'receipt_sha256')):
+                raise ValueError('failed attempt claims completed capture')
+            task['description'] = 'Review configured backup capture: latest attempt failed; earlier captures and recovery readiness require inspection'
+        else:
+            raise ValueError('unsupported attempt status')
+        task.update(receipt_status=status, completed_at=completed.isoformat())
+    except FileNotFoundError:
+        task['receipt_unavailable_reason'] = 'missing'
+    except OSError:
+        task['receipt_unavailable_reason'] = 'unreadable'
+    except (ValueError, TypeError, OverflowError):
+        task['receipt_unavailable_reason'] = 'invalid'
+    return task

apsimo/initiatives/context_freshness.py

@@ -0,0 +1,103 @@
+"""Context durability and freshness rules per initiative type (v0.16.0).
+
+Context snapshots age differently per domain. ``days_since_contact`` is
+still true hours later; ``"CI failing on main"`` or ``"meeting in 30
+min"`` can become false while the initiative sits in the queue. Each
+initiative type therefore declares its context durability:
+
+- ``durable`` — snapshot at creation, safe to persist and read later.
+- ``volatile`` — must be refreshed at read time, or checked against a
+  freshness TTL before the agent acts on it.
+
+The agent-side contract: a volatile initiative's context carries
+``context_captured_at``. Observation-backed proposals retain the actual source
+observation time rather than renewing it when a stored row is read. Before acting,
+the agent checks ``is_context_fresh()``; if stale, it calls
+``POST /v1/host/initiatives/{id}/context/refresh`` which routes to the
+engine's per-entity ``rebuild_context()``.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Dict, Optional
+
+DURABLE = "durable"
+VOLATILE = "volatile"
+
+# Durability by InitiativeType value. Unlisted types default to durable
+# with a conservative short TTL applied by callers that care.
+CONTEXT_DURABILITY: Dict[str, str] = {
+    # Existing types
+    "follow_up": DURABLE,
+    "relationship": DURABLE,
+    "introduction": DURABLE,
+    "health": VOLATILE,
+    "scheduling": DURABLE,
+    "coding": VOLATILE,
+    "subsystem_health": VOLATILE,
+    "data_quality": VOLATILE,
+    "operational": DURABLE,
+    "capability_gap": DURABLE,
+    "knowledge_acquisition": DURABLE,
+    "behavioral_correction": DURABLE,
+    "agent_action": VOLATILE,
+    # Autonomous work domains (v0.16.0)
+    "commitment": DURABLE,
+    "calendar": VOLATILE,
+    "research": DURABLE,
+    "task": DURABLE,
+    "project": DURABLE,
+    "system": VOLATILE,
+}
+
+# Freshness TTL (seconds) for volatile types: how old a context snapshot
+# may be before the agent must refresh it.
+CONTEXT_FRESHNESS_TTL_SECONDS: Dict[str, int] = {
+    "calendar": 300,
+    "coding": 600,
+    "system": 300,
+    "health": 900,
+    "subsystem_health": 600,
+    "data_quality": 3600,
+    "agent_action": 600,
+}
+
+_DEFAULT_VOLATILE_TTL = 600
+
+
+def durability_for(type_value: str) -> str:
+    """Declared durability for an initiative type ('durable'/'volatile')."""
+    return CONTEXT_DURABILITY.get(type_value, DURABLE)
+
+
+def freshness_ttl_for(type_value: str) -> Optional[int]:
+    """TTL in seconds for volatile types; None for durable types."""
+    if durability_for(type_value) == DURABLE:
+        return None
+    return CONTEXT_FRESHNESS_TTL_SECONDS.get(type_value, _DEFAULT_VOLATILE_TTL)
+
+
+def is_context_fresh(
+    type_value: str,
+    captured_at: Optional[str],
+    now: Optional[datetime] = None,
+) -> bool:
+    """Whether a context snapshot is still safe to act on.
+
+    Durable contexts are always fresh. Volatile contexts without a
+    capture timestamp, or with a future timestamp, are treated as stale.
+    """
+    ttl = freshness_ttl_for(type_value)
+    if ttl is None:
+        return True
+    if not captured_at:
+        return False
+    try:
+        stamp = datetime.fromisoformat(captured_at.replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        return False
+    if stamp.tzinfo is None:
+        stamp = stamp.replace(tzinfo=timezone.utc)
+    now = now or datetime.now(timezone.utc)
+    return 0 <= (now - stamp).total_seconds() <= ttl