apsimo 1.3.0__py3-none-any.whl

apsimo/intelligence/synthesis/insight_deliverer.py

@@ -0,0 +1,171 @@
+"""Insight Deliverer — route insights to appropriate delivery channels.
+
+Routes based on:
+- Urgency (high → push notification, low → digest)
+- User preferences (push enabled/disabled, preferred channels)
+- Channel availability
+- Time of day (avoid late-night pushes for non-critical insights)
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+class DeliveryChannel(str, Enum):
+    """Available delivery channels for insights.
+
+    PUSH: Immediate notification (WhatsApp, push notification)
+    DIGEST: Batched into daily/weekly summary
+    IN_APP: Show in next conversation naturally
+    EMAIL: Email notification for lower-urgency items
+    """
+
+    PUSH = "push"
+    DIGEST = "digest"
+    IN_APP = "in_app"
+    EMAIL = "email"
+
+
+@dataclass
+class DeliveryDecision:
+    """Routing decision for an insight.
+
+    Attributes:
+        insight_id: ID of the insight being routed
+        channel: Selected delivery channel
+        reason: Why this channel was chosen
+        scheduled_for: ISO timestamp for digest delivery (None for immediate)
+    """
+
+    insight_id: str
+    channel: DeliveryChannel
+    reason: str
+    scheduled_for: Optional[str] = None
+
+
+@runtime_checkable
+class DelivererEventBus(Protocol):
+    """Protocol for event emission from the deliverer."""
+
+    async def emit_async(self, event: Any) -> None: ...
+
+
+@runtime_checkable
+class Deliverable(Protocol):
+    """Protocol for objects that can be delivered as insights."""
+
+    @property
+    def id(self) -> str: ...
+
+    @property
+    def description(self) -> str: ...
+
+
+class InsightDeliverer:
+    """Route insights to appropriate delivery channels.
+
+    Makes routing decisions based on urgency level and user preferences.
+    High-urgency insights get pushed immediately; low-urgency insights
+    queue for the next digest.
+
+    Args:
+        event_bus: Event bus for emitting delivery events
+        user_preferences: Dict of user delivery preferences
+    """
+
+    def __init__(
+        self,
+        event_bus: DelivererEventBus,
+        user_preferences: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.events = event_bus
+        self.preferences = user_preferences or {}
+
+    async def deliver(
+        self,
+        insight: Deliverable,
+        urgency: float = 0.5,
+    ) -> DeliveryDecision:
+        """Determine delivery channel and route an insight.
+
+        Routing logic:
+        - urgency >= 0.8 and push enabled → PUSH
+        - urgency >= 0.5 → IN_APP (show in conversation)
+        - urgency < 0.5 → DIGEST (queue for summary)
+
+        Args:
+            insight: The insight to deliver
+            urgency: Urgency level between 0 and 1
+
+        Returns:
+            DeliveryDecision describing channel and reasoning.
+        """
+        if urgency >= 0.8 and self.preferences.get("push_enabled", True):
+            channel = DeliveryChannel.PUSH
+            reason = "High urgency, push enabled"
+            await self._send_push(insight)
+        elif urgency >= 0.5:
+            channel = DeliveryChannel.IN_APP
+            reason = "Moderate urgency, show in conversation"
+        else:
+            channel = DeliveryChannel.DIGEST
+            reason = "Low urgency, queue for digest"
+
+        decision = DeliveryDecision(
+            insight_id=insight.id,
+            channel=channel,
+            reason=reason,
+        )
+
+        logger.info(
+            "Insight %s routed to %s: %s",
+            insight.id,
+            channel.value,
+            reason,
+        )
+        return decision
+
+    async def deliver_batch(
+        self,
+        insights: List[tuple[Deliverable, float]],
+    ) -> List[DeliveryDecision]:
+        """Route multiple insights with their urgency levels.
+
+        Args:
+            insights: List of (insight, urgency) tuples
+
+        Returns:
+            List of DeliveryDecision objects.
+        """
+        decisions = []
+        for insight, urgency in insights:
+            decision = await self.deliver(insight, urgency)
+            decisions.append(decision)
+        return decisions
+
+    async def _send_push(self, insight: Deliverable) -> None:
+        """Send an immediate push notification for a high-urgency insight."""
+        if self.events is None:
+            logger.warning("No event bus configured; insight %s not delivered via push", insight.id)
+            return
+        try:
+            from apsimo.events.types import InsightPushEvent
+            event = InsightPushEvent(
+                id=str(uuid.uuid4()),
+                source="insight_deliverer",
+                insight_id=insight.id,
+                description=insight.description,
+                urgency=1.0,
+                delivery_channel="push",
+            )
+            await self.events.emit_async(event)
+            logger.debug("Push event emitted for insight %s", insight.id)
+        except Exception as e:
+            logger.warning("Failed to emit push event for insight %s: %s", insight.id, e)

apsimo/intelligence/synthesis/insight_store.py

@@ -0,0 +1,79 @@
+"""SQLite-backed store for dismissed-insight overlays.
+
+Insights themselves are re-computed each call by ConnectionDiscoverer —
+we don't persist the insights. This store tracks which insight IDs the
+user has dismissed so ``list_insights`` can filter them out.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import logging
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable, Iterator, Set
+
+logger = logging.getLogger(__name__)
+
+
+class InsightStore:
+    """Persistent record of dismissed insight IDs."""
+
+    def __init__(self, db_path: Path | str) -> None:
+        self._db_path = str(db_path)
+        Path(self._db_path).parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS dismissed_insights (
+                    insight_id TEXT PRIMARY KEY,
+                    dismissed_at TEXT NOT NULL
+                )
+                """
+            )
+
+    @contextmanager
+    def _connect(self) -> Iterator[sqlite3.Connection]:
+        connection = sqlite3.connect(self._db_path)
+        try:
+            with connection:
+                yield connection
+        finally:
+            connection.close()
+
+    def dismiss(self, insight_id: str) -> None:
+        """Mark the given insight as dismissed. Idempotent."""
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO dismissed_insights (insight_id, dismissed_at)
+                VALUES (?, ?)
+                ON CONFLICT(insight_id) DO NOTHING
+                """,
+                (insight_id, datetime.now(timezone.utc).isoformat()),
+            )
+
+    def is_dismissed(self, insight_id: str) -> bool:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT 1 FROM dismissed_insights WHERE insight_id=? LIMIT 1",
+                (insight_id,),
+            ).fetchone()
+            return row is not None
+
+    def list_dismissed(self) -> Set[str]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT insight_id FROM dismissed_insights"
+            ).fetchall()
+            return {r[0] for r in rows}
+
+    def undismiss(self, insight_id: str) -> bool:
+        """Remove a dismissal. Returns True if a row was removed."""
+        with self._connect() as conn:
+            cur = conn.execute(
+                "DELETE FROM dismissed_insights WHERE insight_id=?",
+                (insight_id,),
+            )
+            return cur.rowcount > 0

apsimo/intelligence/synthesis/insight_validator.py

@@ -0,0 +1,183 @@
+"""Insight Validator — ensure insights meet quality thresholds before surfacing.
+
+Validates insights against configurable criteria:
+- Minimum evidence count (don't surface guesses)
+- Confidence threshold (minimum certainty)
+- Actionability check (prefer actionable insights)
+- Data recency (stale data degrades trust)
+
+Only insights passing all checks should be delivered to the user.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ValidationResult:
+    """Result of insight validation.
+
+    Attributes:
+        valid: Whether the insight passed all checks
+        reasons: List of failure reasons (empty if valid)
+        evidence_count: Number of supporting evidence items
+        confidence: The insight's confidence score
+        data_age_hours: Age of the oldest supporting data in hours
+    """
+
+    valid: bool
+    reasons: List[str]
+    evidence_count: int
+    confidence: float
+    data_age_hours: float
+
+
+@runtime_checkable
+class Validatable(Protocol):
+    """Protocol for objects that can be validated as insights.
+
+    Insight objects must expose confidence, supporting evidence,
+    and optionally actionability flags.
+    """
+
+    @property
+    def confidence(self) -> float: ...
+
+    @property
+    def supporting_evidence(self) -> List[str]: ...
+
+
+@runtime_checkable
+class ValidatorGraphClient(Protocol):
+    """Protocol for graph access needed by insight validation."""
+
+    async def recall(
+        self,
+        query: str,
+        limit: int = 10,
+        min_strength: float = 0.1,
+    ) -> List[Dict[str, Any]]: ...
+
+
+class InsightValidator:
+    """Validate insights before surfacing to the user.
+
+    Applies configurable quality gates. An insight must pass all
+    checks to be considered valid for delivery.
+
+    Args:
+        min_evidence: Minimum number of supporting evidence items
+        min_confidence: Minimum confidence score (0-1)
+        max_data_age_hours: Maximum age of supporting data in hours
+        graph: Optional graph client for evidence timestamp lookups
+    """
+
+    def __init__(
+        self,
+        min_evidence: int = 2,
+        min_confidence: float = 0.6,
+        max_data_age_hours: float = 168.0,  # 1 week
+        graph: Optional[ValidatorGraphClient] = None,
+    ) -> None:
+        self.min_evidence = min_evidence
+        self.min_confidence = min_confidence
+        self.max_data_age_hours = max_data_age_hours
+        self._graph = graph
+
+    async def validate(self, insight: Validatable) -> ValidationResult:
+        """Check if an insight meets all quality thresholds.
+
+        Evaluates evidence count, confidence, and data recency.
+        Returns a ValidationResult with pass/fail and detailed reasons.
+
+        Args:
+            insight: The insight to validate
+
+        Returns:
+            ValidationResult indicating whether the insight is fit
+            for delivery, with failure reasons if not.
+        """
+        reasons: List[str] = []
+
+        # Evidence count
+        evidence_count = len(insight.supporting_evidence)
+        if evidence_count < self.min_evidence:
+            reasons.append(
+                f"Insufficient evidence ({evidence_count} < {self.min_evidence})"
+            )
+
+        # Confidence check
+        confidence = insight.confidence
+        if confidence < self.min_confidence:
+            reasons.append(
+                f"Low confidence ({confidence:.2f} < {self.min_confidence})"
+            )
+
+        # Data recency
+        data_age = await self._compute_data_age(insight)
+        if data_age > self.max_data_age_hours:
+            reasons.append(
+                f"Stale data ({data_age:.0f}h > {self.max_data_age_hours:.0f}h)"
+            )
+
+        valid = len(reasons) == 0
+
+        return ValidationResult(
+            valid=valid,
+            reasons=reasons,
+            evidence_count=evidence_count,
+            confidence=confidence,
+            data_age_hours=data_age,
+        )
+
+    async def validate_batch(
+        self,
+        insights: List[Validatable],
+    ) -> List[tuple[Any, ValidationResult]]:
+        """Validate multiple insights, returning paired results.
+
+        Args:
+            insights: List of insights to validate
+
+        Returns:
+            List of (insight, ValidationResult) tuples.
+        """
+        results = []
+        for insight in insights:
+            result = await self.validate(insight)
+            results.append((insight, result))
+        return results
+
+    async def _compute_data_age(self, insight: Validatable) -> float:
+        """Calculate the age of the oldest supporting data in hours."""
+        if not insight.supporting_evidence or self._graph is None:
+            return 0.0  # no evidence or no graph = treat as fresh
+
+        oldest_hours = 0.0
+        now = datetime.now(timezone.utc)
+        for evidence_id in insight.supporting_evidence:
+            try:
+                records = await self._graph.recall(
+                    evidence_id, limit=1, min_strength=0.0
+                )
+                if records:
+                    created_at = records[0].get("created_at")
+                    if created_at is not None:
+                        if hasattr(created_at, 'to_native'):
+                            created_at = created_at.to_native()
+                        elif isinstance(created_at, str):
+                            created_at = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+                        if isinstance(created_at, datetime):
+                            if created_at.tzinfo is None:
+                                created_at = created_at.replace(tzinfo=timezone.utc)
+                            age = (now - created_at).total_seconds() / 3600
+                            oldest_hours = max(oldest_hours, age)
+            except Exception as e:
+                logger.debug("Could not fetch data age for evidence %s: %s", evidence_id, e)
+        return oldest_hours

apsimo/intelligence/synthesis/novelty_scorer.py

@@ -0,0 +1,267 @@
+"""Novelty Scorer — rate how surprising or useful an insight is.
+
+Scores connections and insights based on:
+- Historical frequency (has this been observed before?)
+- Domain distance (cross-domain insights score higher)
+- Confidence delta (unexpected findings score higher)
+
+Higher novelty scores indicate insights the user is less likely to
+already know, making them more valuable to surface.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class NoveltyScore:
+    """Novelty assessment for an insight or connection.
+
+    Attributes:
+        score: Overall novelty score between 0 and 1
+        reasons: Human-readable explanations for the score
+        historical_frequency: Number of prior observations of similar connections
+        domain_distance: How far apart the involved domains are (0-1)
+        confidence_delta: How much the confidence deviates from expectation
+    """
+
+    score: float
+    reasons: List[str]
+    historical_frequency: int
+    domain_distance: float
+    confidence_delta: float
+
+
+@runtime_checkable
+class ScoringGraphClient(Protocol):
+    """Protocol for graph access needed by novelty scoring."""
+
+    async def recall(
+        self,
+        query: str,
+        limit: int = 10,
+        min_strength: float = 0.1,
+    ) -> List[Dict[str, Any]]: ...
+
+    async def run_query(
+        self,
+        cypher: str,
+        params: dict,
+    ) -> List[Dict[str, Any]]: ...
+
+
+@runtime_checkable
+class Connectable(Protocol):
+    """Protocol for objects that have source/target domain attributes."""
+
+    @property
+    def source_domain(self) -> str: ...
+
+    @property
+    def target_domain(self) -> str: ...
+
+    @property
+    def confidence(self) -> float: ...
+
+    @property
+    def description(self) -> str: ...
+
+
+# Semantic distance matrix between domains.
+# Higher values mean domains are more distant (cross-domain insights
+# spanning distant domains are scored as more novel).
+DOMAIN_DISTANCES: Dict[tuple[str, str], float] = {
+    ("work", "relationships"): 0.6,
+    ("health", "work"): 0.8,
+    ("health", "finance"): 0.9,
+    ("work", "finance"): 0.4,
+}
+
+
+class NoveltyScorer:
+    """Score how novel or useful a connection or insight is.
+
+    Combines historical frequency, domain distance, and confidence
+    deviation into a single novelty score. Lower frequency + higher
+    distance + higher confidence delta = more novel.
+
+    Args:
+        graph_client: Graph database client for historical lookups
+    """
+
+    def __init__(self, graph_client: ScoringGraphClient) -> None:
+        self.graph = graph_client
+
+    async def score_connection(self, connection: Connectable) -> NoveltyScore:
+        """Score novelty of a discovered connection.
+
+        Computes a weighted composite of three factors:
+        - Frequency factor (40%): inverse of historical frequency
+        - Domain distance (30%): semantic distance between domains
+        - Confidence delta (30%): deviation from expected confidence
+
+        Args:
+            connection: A connection or insight with domain attributes
+
+        Returns:
+            NoveltyScore with composite score and explanations.
+        """
+        freq = await self._get_historical_frequency(connection)
+        distance = await self._compute_domain_distance(
+            connection.source_domain,
+            connection.target_domain,
+        )
+        delta = await self._calculate_confidence_delta(connection)
+
+        # Composite score: lower frequency + higher distance + higher delta = more novel
+        frequency_factor = 1.0 / (1.0 + freq)
+        score = frequency_factor * 0.4 + distance * 0.3 + delta * 0.3
+
+        reasons: List[str] = []
+        if freq == 0:
+            reasons.append("Never observed before")
+        if distance > 0.5:
+            reasons.append("Cross-domain connection")
+        if delta > 0.3:
+            reasons.append("Unexpected confidence level")
+
+        return NoveltyScore(
+            score=min(1.0, score),
+            reasons=reasons,
+            historical_frequency=freq,
+            domain_distance=distance,
+            confidence_delta=delta,
+        )
+
+    async def _get_historical_frequency(self, connection: Connectable) -> int:
+        """Count how many similar connections exist in the graph."""
+        source_domain = connection.source_domain
+        target_domain = connection.target_domain
+
+        # Try run_query first (direct Cypher)
+        if hasattr(self.graph, 'run_query'):
+            try:
+                cypher = """
+MATCH (m:Memory {type: "connection"})
+WHERE (m.metadata.source_domain = $source_domain
+       AND m.metadata.target_domain = $target_domain)
+   OR (m.metadata.source_domain = $target_domain
+       AND m.metadata.target_domain = $source_domain)
+RETURN count(m) AS frequency
+"""
+                records = await self.graph.run_query(cypher, {
+                    "source_domain": source_domain,
+                    "target_domain": target_domain,
+                })
+                if records:
+                    return int(records[0].get("frequency", 0))
+            except Exception as e:
+                logger.debug("_get_historical_frequency query failed: %s", e)
+
+        # Fallback: use recall with domain pair query
+        try:
+            query = f"{source_domain} {target_domain} connection pattern"
+            results = await self.graph.recall(query, limit=50, min_strength=0.1)
+            return len(results)
+        except Exception as e:
+            logger.debug("_get_historical_frequency recall fallback failed: %s", e)
+
+        return 0
+
+    async def _compute_domain_distance(self, source: str, target: str) -> float:
+        """Compute domain distance from graph confidence data.
+
+        Queries the graph for mean confidence of historical connections between
+        the domain pair. Distance is derived as ``1 - mean_confidence``: high-
+        confidence connections indicate domains are closely related (low
+        distance); low-confidence connections indicate distant domains (high
+        distance). Falls back to ``_calculate_domain_distance`` when the graph
+        returns no data.
+
+        Args:
+            source: Source domain name.
+            target: Target domain name.
+
+        Returns:
+            Distance between 0 (same / closely related) and 1 (maximally distant).
+        """
+        if source == target:
+            return 0.0
+
+        if hasattr(self.graph, "run_query"):
+            try:
+                cypher = """
+MATCH (m:Memory {type: "connection"})
+WHERE ((m.metadata.source_domain = $source_domain
+        AND m.metadata.target_domain = $target_domain)
+    OR (m.metadata.source_domain = $target_domain
+        AND m.metadata.target_domain = $source_domain))
+  AND m.metadata.confidence IS NOT NULL
+RETURN avg(toFloat(m.metadata.confidence)) AS mean_confidence
+"""
+                records = await self.graph.run_query(
+                    cypher,
+                    {"source_domain": source, "target_domain": target},
+                )
+                if records and records[0].get("mean_confidence") is not None:
+                    mean_conf = float(records[0]["mean_confidence"])
+                    return max(0.0, min(1.0, 1.0 - mean_conf))
+            except Exception as e:
+                logger.debug("_compute_domain_distance query failed: %s", e)
+
+        return self._calculate_domain_distance(source, target)
+
+    @staticmethod
+    def _calculate_domain_distance(source: str, target: str) -> float:
+        """Calculate semantic distance between two domains.
+
+        Uses a precomputed distance matrix. Unknown pairs default to 0.5.
+        Same-domain connections have distance 0.
+
+        Args:
+            source: Source domain name
+            target: Target domain name
+
+        Returns:
+            Distance between 0 (same domain) and 1 (maximally distant).
+        """
+        if source == target:
+            return 0.0
+        return DOMAIN_DISTANCES.get(
+            (source, target),
+            DOMAIN_DISTANCES.get((target, source), 0.5),
+        )
+
+    async def _calculate_confidence_delta(self, connection: Connectable) -> float:
+        """Measure how unexpected the connection's confidence level is."""
+        source_domain = connection.source_domain
+        target_domain = connection.target_domain
+
+        # Try run_query first
+        if hasattr(self.graph, 'run_query'):
+            try:
+                cypher = """
+MATCH (m:Memory {type: "connection"})
+WHERE ((m.metadata.source_domain = $source_domain
+        AND m.metadata.target_domain = $target_domain)
+    OR (m.metadata.source_domain = $target_domain
+        AND m.metadata.target_domain = $source_domain))
+  AND m.metadata.confidence IS NOT NULL
+RETURN avg(toFloat(m.metadata.confidence)) AS mean_confidence
+"""
+                records = await self.graph.run_query(cypher, {
+                    "source_domain": source_domain,
+                    "target_domain": target_domain,
+                })
+                if records and records[0].get("mean_confidence") is not None:
+                    mean_conf = float(records[0]["mean_confidence"])
+                    return abs(connection.confidence - mean_conf)
+            except Exception as e:
+                logger.debug("_calculate_confidence_delta query failed: %s", e)
+
+        return 0.0