apsimo 1.3.0__py3-none-any.whl

apsimo/environment.py

@@ -0,0 +1,43 @@
+"""Normalize public environment names at process and instance load boundaries.
+
+Stored configuration remains unchanged. Internal COLONY_* readers receive
+explicit APSIMO_* values; conflicting explicit aliases are configuration errors.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+import os
+
+_generated: dict[str, str] = {}
+
+
+def normalize_environment(values: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Return a normalized copy, with no mutation or secret values in errors."""
+    result = dict(os.environ if values is None else values)
+    for name, value in tuple(result.items()):
+        if not name.startswith('APSIMO_'):
+            continue
+        legacy = 'COLONY_' + name[len('APSIMO_'):]
+        if legacy in result and result[legacy] != value:
+            raise ValueError(f'Conflicting environment names: {name} and {legacy}')
+        result[legacy] = value
+    return result
+
+
+def clear_environment_aliases() -> None:
+    """Remove only aliases this module generated, before selecting an instance."""
+    for name, value in _generated.items():
+        if os.environ.get(name) == value:
+            os.environ.pop(name, None)
+    _generated.clear()
+
+
+def apply_environment_aliases() -> None:
+    """Refresh generated aliases; removed canonical keys cannot leave stale reads."""
+    clear_environment_aliases()
+    original = dict(os.environ)
+    normalized = normalize_environment(original)
+    for name, value in normalized.items():
+        if name not in original:
+            os.environ[name] = value
+            _generated[name] = value

apsimo/events/__init__.py

@@ -0,0 +1,33 @@
+"""Colony event bus.
+
+Typed event dispatch for inter-component communication.
+Components emit events when state changes, and other components
+subscribe to react. The bus provides type filtering, error isolation,
+and bounded history.
+"""
+
+from .bus import EventBus, Subscription, TypedEventBus
+from .types import (
+    CognitionEvent,
+    Event,
+    IntegrationEvent,
+    MemoryEvent,
+    MeshEvent,
+    PersonEvent,
+    SignalEvent,
+)
+
+__all__ = [
+    # Bus
+    "EventBus",
+    "TypedEventBus",
+    "Subscription",
+    # Event types
+    "Event",
+    "PersonEvent",
+    "SignalEvent",
+    "MemoryEvent",
+    "MeshEvent",
+    "CognitionEvent",
+    "IntegrationEvent",
+]

apsimo/events/broadcaster.py

@@ -0,0 +1,98 @@
+"""Shared lazy-broadcast helper for sidecar subsystems.
+
+Subsystems (consolidator, goal store, briefing store, world-model store,
+skills registry) call ``emit(type, payload)`` to push a typed event to
+all connected WebSocket subscribers. The import of ``broadcast_event``
+is lazy so modules that want to emit events don't take a hard dependency
+on the API router.
+
+Errors are swallowed — event emission must never break the subsystem
+that triggers it.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+_broadcast_fn = None
+
+# In-process consumers by event type. emit() used to reach only WebSocket
+# subscribers, so an event with no client connected simply died; subsystems
+# that need to REACT to an event (not just display it) register here.
+_subscribers: Dict[str, List[Callable[[Dict[str, Any]], Any]]] = {}
+
+
+def subscribe(event_type: str, fn: Callable[[Dict[str, Any]], Any]) -> None:
+    """Register an in-process consumer for one event type.
+
+    Consumers are invoked synchronously from ``emit()`` with the full event
+    dict (``type``/``occurred_at``/``payload``); keep them cheap. A consumer
+    error is swallowed — emission must never break the emitting subsystem.
+    """
+    _subscribers.setdefault(event_type, []).append(fn)
+
+
+def _resolve_broadcaster():
+    """Lazy-import ``broadcast_event`` from the host router.
+
+    Returns a no-op lambda if the import fails (unit-test contexts,
+    circular-import edge cases, sidecar not yet booted).
+    """
+    global _broadcast_fn
+    if _broadcast_fn is None:
+        try:
+            from apsimo.api.routers.host import broadcast_event
+            _broadcast_fn = broadcast_event
+        except ImportError:
+            # Do not cache startup/circular-import failure forever. A later
+            # emission can resolve the fully initialized host publisher.
+            return lambda _e: None
+    return _broadcast_fn
+
+
+def emit(event_type: str, payload: Optional[Dict[str, Any]] = None) -> None:
+    """Send a typed event through the durable host event publisher.
+
+    The production host publisher journals and assigns a sequence before it
+    broadcasts.  Test doubles may return ``None``; in-process consumers still
+    receive the source event in that case.
+
+    Args:
+        event_type: One of the canonical ``HostEventType`` values —
+            ``briefing``, ``anomaly``, ``goal_update``,
+            ``memory_consolidated``, ``world_model_changed``,
+            ``skill_draft_approved``, ``proactive_message``, etc.
+        payload: Arbitrary event-specific payload. Keep it small —
+            subscribers fetch full records via the REST API when they
+            need detail.
+    """
+    try:
+        broadcaster = _resolve_broadcaster()
+        event = {
+            "type": event_type,
+            "occurred_at": datetime.now(timezone.utc).isoformat(),
+            "payload": payload or {},
+        }
+        published = broadcaster(event)
+        consumer_event = published if isinstance(published, dict) else event
+
+        # In-process consumers (best-effort, each isolated)
+        for fn in _subscribers.get(event_type, ()):
+            try:
+                fn(consumer_event)
+            except Exception:
+                logger.debug("in-process consumer failed for %s",
+                             event_type, exc_info=True)
+
+    except Exception:
+        logger.debug("broadcast_event(%s) failed", event_type, exc_info=True)
+
+
+def reset_broadcaster_for_tests(fn) -> None:
+    """Inject a broadcaster for test doubles. Production code never calls this."""
+    global _broadcast_fn
+    _broadcast_fn = fn

apsimo/events/bus.py

@@ -0,0 +1,217 @@
+"""Event bus for Colony.
+
+Provides typed, filtered event dispatch with error isolation.
+Handlers subscribe to specific event types and receive only matching
+events. Handler exceptions are caught and logged, never propagated
+to other handlers or the emitter. Supports both sync and async emit.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional, Type, TypeVar
+
+from apsimo.events.types import (
+    Event,
+    MemoryEvent,
+    MeshEvent,
+    PersonEvent,
+)
+from apsimo.models.memory import Memory
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=Event)
+
+
+@dataclass
+class Subscription:
+    """Event subscription metadata.
+
+    Attributes:
+        handler: Callback to invoke when a matching event is emitted
+        event_types: Which event types this subscription listens for
+        filter_fn: Optional predicate for additional filtering
+    """
+
+    handler: Callable[[Event], None]
+    event_types: List[Type[Event]]
+    filter_fn: Optional[Callable[[Event], bool]] = None
+
+
+class EventBus:
+    """Typed event bus for Colony.
+
+    Features:
+        - Type-safe subscriptions (subscribe to specific event types)
+        - Optional filtering (predicate function per subscription)
+        - Async support (awaitable emit)
+        - Error isolation (handler errors don't crash other handlers)
+        - Bounded history (capped at max_history entries)
+    """
+
+    def __init__(self, max_history: int = 1000):
+        self._subscribers: List[Subscription] = []
+        self._event_history: List[Event] = []
+        self._max_history = max_history
+
+    def subscribe(
+        self,
+        handler: Callable[[Event], None],
+        event_types: List[Type[Event]],
+        filter_fn: Optional[Callable[[Event], bool]] = None,
+    ) -> Subscription:
+        """Subscribe to events of specific types with optional filter.
+
+        Args:
+            handler: Function called when a matching event is emitted
+            event_types: List of event classes to listen for
+            filter_fn: Optional predicate; handler only called if this returns True
+
+        Returns:
+            The Subscription instance (pass to unsubscribe to remove)
+        """
+        sub = Subscription(
+            handler=handler,
+            event_types=event_types,
+            filter_fn=filter_fn,
+        )
+        self._subscribers.append(sub)
+        return sub
+
+    def unsubscribe(self, subscription: Subscription) -> None:
+        """Remove a subscription."""
+        if subscription in self._subscribers:
+            self._subscribers.remove(subscription)
+
+    def emit(self, event: Event) -> None:
+        """Emit an event to all matching subscribers.
+
+        Handler errors are caught and logged, not propagated.
+
+        Args:
+            event: The event to dispatch
+        """
+        self._record(event)
+
+        for sub in self._subscribers:
+            if not self._matches(sub, event):
+                continue
+
+            try:
+                sub.handler(event)
+            except Exception as e:
+                logger.error(
+                    "Event handler error: %s", e,
+                    extra={"event_id": event.id, "handler": sub.handler.__name__},
+                )
+
+    async def emit_async(self, event: Event) -> None:
+        """Async emit. Handlers can be sync or async callables.
+
+        Args:
+            event: The event to dispatch
+        """
+        self._record(event)
+
+        for sub in self._subscribers:
+            if not self._matches(sub, event):
+                continue
+
+            try:
+                result = sub.handler(event)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as e:
+                logger.error(
+                    "Async event handler error: %s", e,
+                    extra={"event_id": event.id, "handler": sub.handler.__name__},
+                )
+
+    def get_history(
+        self,
+        event_types: Optional[List[Type[Event]]] = None,
+        limit: int = 100,
+    ) -> List[Event]:
+        """Get recent events, optionally filtered by type.
+
+        Args:
+            event_types: If provided, only return events matching these types
+            limit: Maximum number of events to return
+
+        Returns:
+            List of recent events, most recent last
+        """
+        events = self._event_history
+        if event_types:
+            events = [e for e in events if any(isinstance(e, et) for et in event_types)]
+        return events[-limit:]
+
+    def clear_history(self) -> None:
+        """Clear event history."""
+        self._event_history.clear()
+
+    def _record(self, event: Event) -> None:
+        """Append event to history, trimming if over capacity."""
+        self._event_history.append(event)
+        if len(self._event_history) > self._max_history:
+            self._event_history = self._event_history[-self._max_history :]
+
+    @staticmethod
+    def _matches(sub: Subscription, event: Event) -> bool:
+        """Check if an event matches a subscription's type and filter."""
+        if not any(isinstance(event, et) for et in sub.event_types):
+            return False
+        if sub.filter_fn and not sub.filter_fn(event):
+            return False
+        return True
+
+
+class TypedEventBus(EventBus):
+    """EventBus with typed emit helpers for common event types."""
+
+    def emit_person_event(
+        self,
+        person_id: str,
+        event_type: str,
+        old_value: Any = None,
+        new_value: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        """Emit a PersonEvent with convenience parameters."""
+        self.emit(
+            PersonEvent(
+                id=f"person-{person_id}-{event_type}",
+                person_id=person_id,
+                event_type=event_type,
+                old_value=old_value,
+                new_value=new_value,
+                **kwargs,
+            )
+        )
+
+    def emit_memory_event(self, memory: Memory, event_type: str) -> None:
+        """Emit a MemoryEvent for a specific memory."""
+        self.emit(
+            MemoryEvent(
+                id=f"memory-{memory.id}-{event_type}",
+                memory=memory,
+                event_type=event_type,
+            )
+        )
+
+    def emit_mesh_event(
+        self,
+        node_id: str,
+        event_type: str,
+        **kwargs: Any,
+    ) -> None:
+        """Emit a MeshEvent for a specific node."""
+        self.emit(
+            MeshEvent(
+                id=f"mesh-{node_id}-{event_type}",
+                node_id=node_id,
+                event_type=event_type,
+                **kwargs,
+            )
+        )