apsimo 1.3.0__py3-none-any.whl

apsimo/briefings/engine.py

@@ -0,0 +1,274 @@
+"""BriefingEngine — top-level coordinator for the Colony Briefing System."""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from typing import Any, List, Optional
+
+from apsimo.briefings.composer import BriefingComposer
+from apsimo.briefings.config import BriefingConfig
+from apsimo.briefings.delivery import BriefingDeliveryEngine
+from apsimo.briefings.engagement import SectionEngagementTracker
+from apsimo.briefings.enhancer import BriefingLMEnhancer
+from apsimo.briefings.models import (
+    Briefing,
+    BriefingCompletionSignal,
+    BriefingStatus,
+    BriefingType,
+    SectionEngagementRecord,
+)
+from apsimo.briefings.store import BriefingStore
+
+
+class BriefingEngine:
+    """Top-level coordinator for generating, delivering, and tracking briefings."""
+
+    def __init__(
+        self,
+        config: Optional[BriefingConfig] = None,
+        store: Optional[BriefingStore] = None,
+        delivery: Optional[BriefingDeliveryEngine] = None,
+        enhancer: Optional[BriefingLMEnhancer] = None,
+        delivery_bridge: Optional[Any] = None,  # ProactiveDeliveryBridge
+        relationship_aggregator: Optional[Any] = None,
+        calendar_aggregator: Optional[Any] = None,
+        goal_aggregator: Optional[Any] = None,
+        anomaly_aggregator: Optional[Any] = None,
+        mind_model_aggregator: Optional[Any] = None,
+        synthesis_aggregator: Optional[Any] = None,
+    ) -> None:
+        self._config = config or BriefingConfig()
+        self._store = store or BriefingStore(db_path=":memory:")
+        self._delivery = delivery or BriefingDeliveryEngine(gateways=[], default_gateway="api")
+        self._enhancer = enhancer or BriefingLMEnhancer(enabled=False)
+        self._delivery_bridge = delivery_bridge
+        # Aggregators default to stubs inside the composer; the real ones must
+        # be passed through or every briefing data section is permanently empty.
+        self._composer = BriefingComposer(
+            relationship_aggregator=relationship_aggregator,
+            calendar_aggregator=calendar_aggregator,
+            goal_aggregator=goal_aggregator,
+            anomaly_aggregator=anomaly_aggregator,
+            mind_model_aggregator=mind_model_aggregator,
+            synthesis_aggregator=synthesis_aggregator,
+            suppressed_sections=self._config.suppressed_sections,
+        )
+        self._engagement = SectionEngagementTracker(store=self._store)
+        self._scheduler = None
+
+        # Register the WhatsApp gateway if a delivery bridge is available.
+        if delivery_bridge is not None:
+            from apsimo.briefings.delivery import WhatsAppBriefingGateway
+            self._delivery.register(WhatsAppBriefingGateway(delivery_bridge=delivery_bridge))
+
+    # ------------------------------------------------------------------
+    # Generation & Delivery
+    # ------------------------------------------------------------------
+
+    def generate_and_deliver(self, briefing_type: BriefingType) -> Briefing:
+        """Generate a briefing of the given type, persist it, and deliver it.
+
+        Raises ValueError for BriefingType.TACTICAL (use fire_tactical() instead).
+        Engagement history is used to re-order sections by prior engagement score.
+        If LM enhancement is enabled, the briefing is polished before delivery.
+
+        Returns:
+            The saved Briefing object after delivery attempt. The returned
+            Briefing.status reflects the delivery outcome (DELIVERED or PENDING).
+        """
+        if briefing_type == BriefingType.TACTICAL:
+            raise ValueError("Use fire_tactical() for tactical briefings")
+
+        now = datetime.now(timezone.utc)
+        scores = self._engagement.get_section_scores()
+
+        if briefing_type == BriefingType.DAILY:
+            cfg = self._config.daily
+            briefing = self._composer.build_daily_briefing(
+                date=now.strftime("%Y-%m-%d"),
+                tz=cfg.timezone,
+                max_sections=cfg.max_sections,
+                section_order=cfg.section_order,
+                engagement_history=scores,
+            )
+        else:  # WEEKLY
+            cfg = self._config.weekly
+            from datetime import timedelta
+            week_start = now - timedelta(days=now.weekday())
+            briefing = self._composer.build_weekly_briefing(
+                period_start=week_start,
+                period_end=now,
+                engagement_history=scores,
+            )
+
+        if self._config.lm_enhancement_enabled:
+            briefing = self._enhancer.enhance_briefing(briefing)
+
+        # Resolve home channel gateway before persisting (Fix 8 point 1).
+        if not briefing.gateway:
+            briefing.gateway = self._resolve_home_channel()
+
+        # draft → saved
+        self._store.save(briefing)
+        # draft → queued
+        self._store.mark_queued(briefing.briefing_id)
+        # queued → delivering
+        self._store.mark_delivering(briefing.briefing_id)
+        result = self._delivery.deliver(briefing)
+        if result.success:
+            # delivering → delivered
+            self._store.mark_delivered(briefing.briefing_id, result.gateway)
+            briefing = self._store.get(briefing.briefing_id)
+        return briefing
+
+    def fire_tactical(
+        self,
+        trigger: str,
+        severity: str,
+        summary: str,
+        details: str,
+        suggested_actions: Optional[List[str]] = None,
+    ) -> Optional[Briefing]:
+        """Fire a tactical (event-driven) briefing if the tactical channel is enabled.
+
+        Returns None when tactical briefings are disabled in config, so callers
+        must handle the None case. When enabled, saves and delivers immediately
+        without engagement scoring.
+
+        Returns:
+            The delivered Briefing, or None if tactical is disabled.
+        """
+        if not self._config.tactical.enabled:
+            return None
+
+        briefing = self._composer.build_tactical_briefing(
+            trigger=trigger,
+            severity=severity,
+            summary=summary,
+            details=details,
+            suggested_actions=suggested_actions,
+        )
+        if not briefing.gateway:
+            briefing.gateway = self._resolve_home_channel()
+        self._store.save(briefing)
+        self._store.mark_queued(briefing.briefing_id)
+        self._store.mark_delivering(briefing.briefing_id)
+        result = self._delivery.deliver(briefing)
+        if result.success:
+            self._store.mark_delivered(briefing.briefing_id, result.gateway)
+            briefing = self._store.get(briefing.briefing_id)
+        return briefing
+
+    # ------------------------------------------------------------------
+    # Pending delivery (Fix 8 point 3 — pick up stalled drafts)
+    # ------------------------------------------------------------------
+
+    def deliver_pending(self) -> int:
+        """Attempt delivery of any DRAFT or QUEUED briefings.
+
+        Transitions each briefing through the state machine:
+            draft/queued → delivering → delivered (or back to queued on failure).
+
+        Returns the number of briefings successfully delivered.
+        """
+        count = 0
+        for status in (BriefingStatus.DRAFT, BriefingStatus.QUEUED):
+            for briefing in self._store.list_by_status(status):
+                if not briefing.gateway:
+                    briefing.gateway = self._resolve_home_channel()
+                    # Persist the resolved gateway so the delivery engine uses it.
+                    self._store.save(briefing)
+                self._store.mark_delivering(briefing.briefing_id)
+                result = self._delivery.deliver(briefing)
+                if result.success:
+                    self._store.mark_delivered(briefing.briefing_id, result.gateway)
+                    count += 1
+                    import logging as _logging
+                    _logging.getLogger(__name__).info(
+                        "deliver_pending: delivered briefing %s via %s",
+                        briefing.briefing_id,
+                        result.gateway,
+                    )
+                else:
+                    # Revert to queued so the scheduler retries next cycle.
+                    self._store.mark_queued(briefing.briefing_id)
+                    import logging as _logging
+                    _logging.getLogger(__name__).warning(
+                        "deliver_pending: failed to deliver briefing %s: %s",
+                        briefing.briefing_id,
+                        result.error,
+                    )
+        return count
+
+    def _resolve_home_channel(self) -> str:
+        """Return the home channel platform from delivery_bridge or env vars."""
+        if self._delivery_bridge is not None:
+            home = self._delivery_bridge.resolve_home_channel()
+            if home:
+                return home["platform"]
+        for platform in ("whatsapp", "telegram", "discord", "slack", "signal"):
+            if os.environ.get(f"{platform.upper()}_HOME_CHANNEL"):
+                return platform
+        return "api"
+
+    # ------------------------------------------------------------------
+    # Query
+    # ------------------------------------------------------------------
+
+    def get_pending(self) -> List[Briefing]:
+        return self._store.list_by_status(BriefingStatus.DRAFT)
+
+    def get_recent(self, limit: int = 10) -> List[Briefing]:
+        return self._store.list_recent(limit=limit)
+
+    # ------------------------------------------------------------------
+    # Engagement
+    # ------------------------------------------------------------------
+
+    def record_engagement(self, briefing_id: str, section_name: str, signal: str) -> None:
+        record = SectionEngagementRecord(
+            section_name=section_name,
+            briefing_id=briefing_id,
+            signal=signal,
+            recorded_at=datetime.now(timezone.utc),
+        )
+        self._engagement.record(record)
+        if signal == "read":
+            self._store.mark_read(briefing_id)
+
+    def get_suppression_candidates(self, **kwargs) -> List[str]:
+        return self._engagement.get_suppression_candidates(**kwargs)
+
+    def suppress_section(self, section: str, reason: str = "") -> None:
+        if section not in self._config.suppressed_sections:
+            self._config.suppressed_sections.append(section)
+
+    def emit_completion_signal(self, briefing: Briefing) -> BriefingCompletionSignal:
+        scores = self._engagement.get_section_scores()
+        active = briefing.active_sections()
+        engaged = [s.name for s in active if scores.get(s.name, 0.5) > 0.5]
+        return BriefingCompletionSignal(
+            briefing_id=briefing.briefing_id,
+            briefing_type=briefing.briefing_type,
+            sections=[s.name for s in active],
+            engaged_sections=engaged,
+            delivered_at=datetime.now(timezone.utc),
+            total_anomalies=0,
+            active_goals=0,
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def attach_scheduler(self, scheduler) -> None:
+        self._scheduler = scheduler
+
+    def start(self) -> None:
+        if self._scheduler is not None:
+            self._scheduler.start()
+
+    def stop(self) -> None:
+        if self._scheduler is not None:
+            self._scheduler.stop()

apsimo/briefings/enhancer.py

@@ -0,0 +1,99 @@
+"""Colony Briefing System — LLM Enhancement Pass.
+
+Generates natural-language narratives for briefing sections.
+Falls back gracefully when no LLM client is provided or when
+the LLM call fails.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+from .models import Briefing, BriefingSection
+
+logger = logging.getLogger(__name__)
+
+from apsimo.cognition.charter import build_system_prompt as _charter_prompt
+
+_SYSTEM_PROMPT = _charter_prompt("narrator")
+
+
+@runtime_checkable
+class LLMClientProtocol(Protocol):
+    """Minimal interface expected from an LLM client."""
+
+    def complete(self, system: str, prompt: str, max_tokens: int) -> str: ...
+
+
+class BriefingLMEnhancer:
+    """Generate natural-language narratives for briefing sections."""
+
+    def __init__(
+        self,
+        llm_client: Optional[LLMClientProtocol] = None,
+        enabled: bool = True,
+    ) -> None:
+        self._client = llm_client
+        self._enabled = enabled
+        self._tokens_used = 0
+
+    @property
+    def tokens_used(self) -> int:
+        return self._tokens_used
+
+    def enhance_section(
+        self,
+        section_name: str,
+        structured_content: Dict[str, Any],
+        max_tokens: int = 150,
+    ) -> str:
+        """Generate a natural-language narrative for a single section.
+
+        Returns an empty string if LLM is disabled, unavailable, or if
+        the content has no notable information.
+        """
+        if not self._enabled or self._client is None:
+            return ""
+
+        if not structured_content:
+            return ""
+
+        prompt = (
+            f"Section: {section_name}\n"
+            f"Data: {json.dumps(structured_content, default=str)}\n\n"
+            "Write a 1–3 sentence briefing summary for this section. "
+            "Be concise and actionable. Do not repeat the raw data literally."
+        )
+        try:
+            narrative = self._client.complete(_SYSTEM_PROMPT, prompt, max_tokens)
+            self._tokens_used += max_tokens  # conservative accounting
+            return narrative.strip()
+        except Exception as exc:
+            logger.warning("LLM enhancement failed for section '%s': %s", section_name, exc)
+            return ""
+
+    def enhance_briefing(
+        self,
+        briefing: Briefing,
+        max_tokens_per_section: int = 150,
+    ) -> Briefing:
+        """Run the LLM enhancement pass on all active sections.
+
+        Modifies section.narrative in-place. Returns the updated briefing.
+        Falls back to structured-only content on any LLM failure.
+        """
+        if not self._enabled or self._client is None:
+            return briefing
+
+        for section in briefing.active_sections():
+            if section.suppressed:
+                continue
+            section.narrative = self.enhance_section(
+                section.name,
+                section.content,
+                max_tokens=max_tokens_per_section,
+            )
+
+        return briefing

apsimo/briefings/models.py

@@ -0,0 +1,183 @@
+"""Colony Briefing System — data models.
+
+Defines the core Briefing, BriefingSection, and briefing content types
+used throughout the briefing pipeline.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class BriefingType(str, Enum):
+    DAILY = "daily"
+    TACTICAL = "tactical"
+    WEEKLY = "weekly"
+
+
+class BriefingStatus(str, Enum):
+    DRAFT = "draft"
+    QUEUED = "queued"
+    DELIVERING = "delivering"
+    DELIVERED = "delivered"
+    READ = "read"
+    ARCHIVED = "archived"
+
+
+class BriefingPriority(str, Enum):
+    LOW = "low"
+    NORMAL = "normal"
+    HIGH = "high"
+    URGENT = "urgent"
+
+
+@dataclass
+class BriefingSection:
+    """A single named content block within a briefing."""
+
+    section_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    name: str = ""
+    content: Dict[str, Any] = field(default_factory=dict)
+    narrative: str = ""
+    priority: int = 50
+    suppressed: bool = False
+    engagement: Optional[str] = None  # "read" | "dismissed" | "acted"
+
+
+@dataclass
+class Briefing:
+    """A delivered summary document."""
+
+    briefing_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    briefing_type: BriefingType = BriefingType.DAILY
+    status: BriefingStatus = BriefingStatus.DRAFT
+    sections: List[BriefingSection] = field(default_factory=list)
+    priority: BriefingPriority = BriefingPriority.NORMAL
+    triggered_by: Optional[str] = None
+    gateway: Optional[str] = None
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    delivered_at: Optional[datetime] = None
+    read_at: Optional[datetime] = None
+
+    def is_delivered(self) -> bool:
+        return self.status in {BriefingStatus.DELIVERED, BriefingStatus.READ}
+
+    def active_sections(self) -> List[BriefingSection]:
+        return [s for s in self.sections if not s.suppressed]
+
+
+# ---------------------------------------------------------------------------
+# Content types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CalendarEvent:
+    time: str  # HH:MM local time
+    title: str
+    participants: List[str]
+    prep_needed: bool = False
+    location: Optional[str] = None
+    duration_minutes: int = 30
+
+
+@dataclass
+class DailyBriefingContent:
+    date: str  # ISO-8601 date
+    calendar: List[CalendarEvent]
+    tasks: Dict[str, Any]  # overdue, due_today, blocked, highlights
+    relationships: Dict[str, Any]  # changes list
+    health: Optional[Dict[str, Any]] = None
+    anomalies: Optional[Dict[str, Any]] = None
+    initiatives: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class TacticalBriefingContent:
+    trigger: str
+    severity: str  # "critical" | "warning" | "info"
+    summary: str
+    details: str
+    suggested_actions: List[str] = field(default_factory=list)
+    related_entities: List[str] = field(default_factory=list)
+    requires_response: bool = False
+
+
+@dataclass
+class WeeklyBriefingContent:
+    period_start: str  # ISO-8601 date
+    period_end: str  # ISO-8601 date
+    task_completion_rate: float  # 0.0–1.0
+    relationship_health: Dict[str, Any]  # improved, declined, neglected
+    top_achievements: List[str]
+    areas_of_focus: List[str]
+    emerging_patterns: List[str]
+    upcoming_week: Dict[str, Any]
+    system_health: Dict[str, Any]  # uptime, errors, backup_status
+
+
+# ---------------------------------------------------------------------------
+# Intelligence integration models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BriefingCompletionSignal:
+    """Signal emitted to the synthesis engine after briefing delivery."""
+
+    briefing_id: str
+    briefing_type: BriefingType
+    sections: List[str]
+    engaged_sections: List[str]
+    delivered_at: datetime
+    total_anomalies: int
+    active_goals: int
+
+
+@dataclass
+class BriefingTelemetryEvent:
+    """Telemetry for MetaLearner briefing performance tracking."""
+
+    briefing_id: str
+    briefing_type: BriefingType
+    time_to_generate_ms: float
+    time_to_deliver_ms: float
+    lm_tokens_used: int
+    section_count: int
+    engagement_score: float
+    gateway: str
+    delivered_at: datetime
+
+
+# ---------------------------------------------------------------------------
+# Engagement
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SectionEngagementRecord:
+    """Record of user engagement with a briefing section."""
+
+    section_name: str
+    briefing_id: str
+    signal: str  # "read" | "dismissed" | "acted" | "shared"
+    recorded_at: datetime
+    context: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Schedule
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ScheduleEntry:
+    """Persisted schedule state for daily/weekly briefings."""
+
+    type: str  # "daily" | "weekly"
+    last_run: Optional[datetime] = None
+    next_run: Optional[datetime] = None