apsimo 1.3.0__py3-none-any.whl

apsimo/intelligence/synthesis/connection_discoverer.py

@@ -0,0 +1,379 @@
+"""Connection Discoverer — find non-obvious connections across domains.
+
+Scans memories, signals, and relationships to find patterns that connect
+seemingly unrelated information (e.g., "Mom always calls after doctor
+appointments", "stress spikes correlate with late-night work sessions").
+
+Uses graph queries + signal analysis to discover temporal, causal,
+entity-based, and behavioral patterns across domain boundaries.
+"""
+
+from __future__ import annotations
+
+import logging
+import textwrap
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionType(str, Enum):
+    """Categories of cross-domain connections.
+
+    TEMPORAL: A happens before/after B (time correlation)
+    CAUSAL: A causes B (inferred from repeated co-occurrence)
+    TOPIC: Same topic surfaces across different contexts
+    ENTITY: Same person/company appears in different domains
+    BEHAVIORAL: Repeating behavior pattern across contexts
+    """
+
+    TEMPORAL = "temporal"
+    CAUSAL = "causal"
+    TOPIC = "topic"
+    ENTITY = "entity"
+    BEHAVIORAL = "behavioral"
+
+
+@dataclass
+class Connection:
+    """A discovered connection between entities or concepts.
+
+    Represents a cross-domain relationship with evidence tracking
+    and confidence scoring.
+
+    Attributes:
+        id: Unique connection identifier
+        connection_type: Category of connection
+        source_domain: Origin domain ("health", "work", "relationships")
+        target_domain: Destination domain
+        entities: Related person IDs, memory IDs, etc.
+        description: Human-readable description of the connection
+        confidence: Confidence score between 0 and 1
+        evidence: List of evidence references (memory IDs, signal IDs)
+        first_observed: When connection was first detected
+        last_observed: Most recent observation
+        observation_count: How many times this connection has been seen
+    """
+
+    id: str
+    connection_type: ConnectionType
+    source_domain: str
+    target_domain: str
+    entities: List[str]
+    description: str
+    confidence: float
+    evidence: List[str] = field(default_factory=list)
+    first_observed: Optional[datetime] = None
+    last_observed: Optional[datetime] = None
+    observation_count: int = 1
+
+
+@runtime_checkable
+class GraphClient(Protocol):
+    """Protocol for graph database access.
+
+    Any object providing these methods can serve as the graph backend
+    for connection discovery.
+    """
+
+    async def recall(
+        self,
+        query: str,
+        limit: int = 10,
+        min_strength: float = 0.1,
+    ) -> List[Dict[str, Any]]: ...
+
+    async def traverse_memory_connections(
+        self,
+        memory_id: str,
+        max_depth: int = 3,
+        min_strength: float = 0.3,
+        limit: int = 20,
+    ) -> List[Dict[str, Any]]: ...
+
+    async def run_query(
+        self,
+        cypher: str,
+        params: Dict[str, Any],
+    ) -> List[Dict[str, Any]]: ...
+
+
+class ConnectionDiscoverer:
+    """Discover cross-domain connections from graph data.
+
+    Analyzes memories, signals, and entity relationships to surface
+    patterns spanning multiple domains. Supports temporal correlation,
+    entity co-occurrence, and behavioral pattern detection.
+
+    Args:
+        graph_client: Graph database client implementing GraphClient protocol
+        signal_threshold: Minimum signal strength to consider (0-1)
+    """
+
+    def __init__(
+        self,
+        graph_client: GraphClient,
+        signal_threshold: float = 0.6,
+    ) -> None:
+        self.graph = graph_client
+        self.signal_threshold = signal_threshold
+
+    async def discover_connections(
+        self,
+        person_id: Optional[str] = None,
+        domain: Optional[str] = None,
+        min_confidence: float = 0.5,
+    ) -> List[Connection]:
+        """Find connections, optionally filtered by person or domain.
+
+        Runs temporal, entity, and behavioral pattern detectors in
+        sequence and returns results sorted by confidence descending.
+
+        Args:
+            person_id: Restrict search to this person's connections
+            domain: Restrict search to connections involving this domain
+            min_confidence: Minimum confidence threshold for results
+
+        Returns:
+            Connections sorted by confidence, highest first.
+        """
+        connections: List[Connection] = []
+
+        # Temporal patterns (e.g., "calls mom on Sundays")
+        temporal = await self._find_temporal_patterns(person_id)
+        connections.extend(temporal)
+
+        # Entity co-occurrence (same person in different contexts)
+        entity = await self._find_entity_patterns(person_id)
+        connections.extend(entity)
+
+        # Behavioral patterns (repeating actions)
+        behavioral = await self._find_behavioral_patterns(person_id)
+        connections.extend(behavioral)
+
+        # Filter by confidence and optional domain
+        filtered = [c for c in connections if c.confidence >= min_confidence]
+        if domain:
+            filtered = [
+                c
+                for c in filtered
+                if c.source_domain == domain or c.target_domain == domain
+            ]
+
+        return sorted(filtered, key=lambda c: c.confidence, reverse=True)
+
+    async def _find_temporal_patterns(
+        self,
+        person_id: Optional[str],
+    ) -> List[Connection]:
+        """Find time-based connections between events.
+
+        Queries graph for Memory node pairs that co-occur within a 4-hour
+        window and have been seen together at least 2 times in the past
+        30 days.  Confidence scales with daily co-occurrence rate.
+        """
+        if person_id is not None:
+            cypher = textwrap.dedent("""
+            MATCH (m1:Memory)-[:ABOUT]->(p:Person {id: $person_id})
+            MATCH (m2:Memory)-[:ABOUT]->(p)
+            WHERE m1.id < m2.id
+              AND abs(duration.between(m1.created_at, m2.created_at).hours) <= $window_hours
+              AND m1.created_at >= datetime() - duration({days: $lookback_days})
+            WITH m1, m2, count(*) AS co_occurrences
+            WHERE co_occurrences >= $min_count
+            RETURN m1.id AS source_id, m2.id AS target_id,
+                   m1.type AS source_type, m2.type AS target_type,
+                   m1.metadata AS source_meta, m2.metadata AS target_meta,
+                   co_occurrences,
+                   toFloat(co_occurrences) / $lookback_days AS daily_rate
+            ORDER BY daily_rate DESC
+            LIMIT 20
+            """).strip()
+            params: Dict[str, Any] = {
+                "person_id": person_id,
+                "window_hours": 4,
+                "lookback_days": 30,
+                "min_count": 2,
+            }
+        else:
+            cypher = textwrap.dedent("""
+            MATCH (m1:Memory), (m2:Memory)
+            WHERE m1.id < m2.id
+              AND abs(duration.between(m1.created_at, m2.created_at).hours) <= $window_hours
+              AND m1.created_at >= datetime() - duration({days: $lookback_days})
+            WITH m1, m2, count(*) AS co_occurrences
+            WHERE co_occurrences >= $min_count
+            RETURN m1.id AS source_id, m2.id AS target_id,
+                   m1.type AS source_type, m2.type AS target_type,
+                   m1.metadata AS source_meta, m2.metadata AS target_meta,
+                   co_occurrences,
+                   toFloat(co_occurrences) / $lookback_days AS daily_rate
+            ORDER BY daily_rate DESC
+            LIMIT 20
+            """).strip()
+            params = {
+                "window_hours": 4,
+                "lookback_days": 30,
+                "min_count": 2,
+            }
+
+        connections: List[Connection] = []
+        try:
+            rows = await self.graph.run_query(cypher, params)
+        except Exception:
+            logger.exception("_find_temporal_patterns query failed")
+            return connections
+
+        for row in rows:
+            source_type = row.get("source_type") or "unknown"
+            target_type = row.get("target_type") or "unknown"
+            daily_rate = float(row.get("daily_rate") or 0.0)
+            confidence = min(1.0, daily_rate * 7)
+            connections.append(
+                Connection(
+                    id=self._make_id(),
+                    connection_type=ConnectionType.TEMPORAL,
+                    source_domain=source_type,
+                    target_domain=target_type,
+                    entities=[row["source_id"], row["target_id"]],
+                    description=(
+                        f"Memory type '{source_type}' co-occurs with"
+                        f" '{target_type}' within 4 hours"
+                        f" ({int(row['co_occurrences'])}x in 30 days)"
+                    ),
+                    confidence=confidence,
+                    evidence=[row["source_id"], row["target_id"]],
+                )
+            )
+        return connections
+
+    async def _find_entity_patterns(
+        self,
+        person_id: Optional[str],
+    ) -> List[Connection]:
+        """Find entity co-occurrence across domains.
+
+        Detects when the same person, company, or concept appears in
+        multiple domain contexts (e.g., "Alex" in both health and work).
+        Requires an entity to appear in at least 2 distinct domains.
+        """
+        cypher = textwrap.dedent("""
+        MATCH (e:Entity)<-[:MENTIONS]-(m:Memory)
+        WHERE ($person_id IS NULL OR (m)-[:ABOUT]->(:Person {id: $person_id}))
+        WITH e, collect(DISTINCT m.id) AS mems
+        WITH e, mems, size(mems) AS mem_count
+        WHERE mem_count >= 2
+        RETURN e.name AS entity_name,
+               mem_count AS occurrence_count,
+               mems[0..5] AS evidence_sample
+        ORDER BY mem_count DESC
+        LIMIT 20
+        """).strip()
+        params = {
+            "person_id": person_id,
+            "min_domain_count": 2,
+        }
+
+        connections: List[Connection] = []
+        try:
+            rows = await self.graph.run_query(cypher, params)
+        except Exception:
+            logger.exception("_find_entity_patterns query failed")
+            return connections
+
+        for row in rows:
+            entity_name = row.get("entity_name") or "unknown"
+            domains: List[str] = list(row.get("domains") or [])
+            evidence_sample = row.get("evidence_sample") or []
+            # Flatten nested lists from collect(collect(...))
+            evidence: List[str] = []
+            for item in evidence_sample:
+                if isinstance(item, list):
+                    evidence.extend(str(x) for x in item)
+                else:
+                    evidence.append(str(item))
+            source_domain = domains[0] if domains else "unknown"
+            target_domain = domains[1] if len(domains) > 1 else "multiple"
+            confidence = min(1.0, (len(domains) - 1) * 0.3 + 0.4)
+            connections.append(
+                Connection(
+                    id=self._make_id(),
+                    connection_type=ConnectionType.ENTITY,
+                    source_domain=source_domain,
+                    target_domain=target_domain,
+                    entities=[entity_name],
+                    description=f"{entity_name} appears across {', '.join(domains)}",
+                    confidence=confidence,
+                    evidence=evidence[:5],
+                )
+            )
+        return connections
+
+    async def _find_behavioral_patterns(
+        self,
+        person_id: Optional[str],
+    ) -> List[Connection]:
+        """Find repeating behavior patterns across contexts.
+
+        Analyzes Signal sequences where signal type A is consistently
+        followed by signal type B within 24 hours, for a given person.
+        Requires person_id; returns empty list when person_id is None.
+        """
+        connections: List[Connection] = []
+        if person_id is None:
+            return connections
+
+        cypher = textwrap.dedent("""
+        MATCH (p:Person {id: $person_id})-[:EXHIBITED]->(s1:Signal)
+        MATCH (p)-[:EXHIBITED]->(s2:Signal)
+        WHERE s1.signal_type <> s2.signal_type
+          AND s2.timestamp > s1.timestamp
+          AND duration.between(s1.timestamp, s2.timestamp).hours <= $window_hours
+        WITH s1.signal_type AS type_a, s2.signal_type AS type_b,
+             count(*) AS occurrences,
+             avg(s2.normalized_value - s1.normalized_value) AS avg_delta,
+             collect(s1.id)[0..5] AS evidence
+        WHERE occurrences >= $min_occurrences
+        RETURN type_a, type_b, occurrences, avg_delta, evidence
+        ORDER BY occurrences DESC
+        LIMIT 15
+        """).strip()
+        params = {
+            "person_id": person_id,
+            "window_hours": 24,
+            "min_occurrences": 3,
+        }
+
+        try:
+            rows = await self.graph.run_query(cypher, params)
+        except Exception:
+            logger.exception("_find_behavioral_patterns query failed")
+            return connections
+
+        for row in rows:
+            type_a = row.get("type_a") or "unknown"
+            type_b = row.get("type_b") or "unknown"
+            occurrences = int(row.get("occurrences") or 0)
+            confidence = min(1.0, occurrences / 10.0)
+            connections.append(
+                Connection(
+                    id=self._make_id(),
+                    connection_type=ConnectionType.BEHAVIORAL,
+                    source_domain="signals",
+                    target_domain="signals",
+                    entities=[],
+                    description=f"Signal {type_a} consistently precedes {type_b}",
+                    confidence=confidence,
+                    evidence=list(row.get("evidence") or []),
+                )
+            )
+        return connections
+
+    @staticmethod
+    def _make_id() -> str:
+        """Generate a unique connection ID."""
+        return str(uuid.uuid4())

apsimo/intelligence/synthesis/cross_domain_analyzer.py

@@ -0,0 +1,287 @@
+"""Cross-Domain Analyzer — synthesize insights across domains.
+
+Analyzes relationships between:
+- Health data (sleep, stress → availability predictions)
+- Work patterns (deadlines → communication shifts)
+- Social patterns (relationship dynamics → scheduling impact)
+- Financial patterns (spending → stress correlation)
+
+Produces actionable DomainInsight objects that can be validated,
+scored for novelty, and delivered through appropriate channels.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import statistics
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DomainInsight:
+    """Insight derived from cross-domain analysis.
+
+    Captures a pattern or prediction that spans multiple domains,
+    along with evidence, confidence, and an optional recommended action.
+
+    Attributes:
+        id: Unique insight identifier
+        domains: List of domains this insight spans (e.g. ["health", "work"])
+        insight_type: Category ("availability_prediction", "stress_pattern", etc.)
+        description: Human-readable description of the insight
+        confidence: Confidence score between 0 and 1
+        actionable: Whether this insight has a concrete recommended action
+        recommended_action: Suggested action if actionable
+        supporting_evidence: Memory IDs, signal IDs, or descriptions backing this insight
+    """
+
+    id: str
+    domains: List[str]
+    insight_type: str
+    description: str
+    confidence: float
+    actionable: bool
+    recommended_action: Optional[str] = None
+    supporting_evidence: List[str] = field(default_factory=list)
+
+
+@runtime_checkable
+class AnalyzerGraphClient(Protocol):
+    """Protocol for graph access needed by cross-domain analysis."""
+
+    async def recall(
+        self,
+        query: str,
+        limit: int = 10,
+        min_strength: float = 0.1,
+    ) -> List[Dict[str, Any]]: ...
+
+
+@runtime_checkable
+class AnalyzerEventBus(Protocol):
+    """Protocol for event emission from the analyzer."""
+
+    async def emit_async(self, event: Any) -> None: ...
+
+
+class CrossDomainAnalyzer:
+    """Analyze patterns spanning multiple domains.
+
+    Runs targeted analyzers for domain pairs (health+work,
+    relationships+health, etc.) and produces scored insights.
+
+    Args:
+        graph_client: Graph database client for querying cross-domain data
+        event_bus: Event bus for emitting insight discovery events
+    """
+
+    def __init__(
+        self,
+        graph_client: AnalyzerGraphClient,
+        event_bus: AnalyzerEventBus,
+    ) -> None:
+        self.graph = graph_client
+        self.events = event_bus
+
+    async def analyze(
+        self,
+        domains: Optional[List[str]] = None,
+    ) -> List[DomainInsight]:
+        """Run cross-domain analysis across specified domains.
+
+        If no domains are specified, all available analyzers run.
+        Results are sorted by confidence descending.
+
+        Args:
+            domains: Optional list of domains to include. None means all.
+
+        Returns:
+            List of DomainInsight objects, highest confidence first.
+        """
+        insights: List[DomainInsight] = []
+
+        # Health + Work: stress → availability
+        if not domains or "health" in domains or "work" in domains:
+            health_work = await self._analyze_health_work()
+            insights.extend(health_work)
+
+        # Relationships + Health: social stress patterns
+        if not domains or "relationships" in domains or "health" in domains:
+            relationships_health = await self._analyze_relationships_health()
+            insights.extend(relationships_health)
+
+        # Work + Relationships: deadline → social impact
+        if not domains or "work" in domains or "relationships" in domains:
+            work_relationships = await self._analyze_work_relationships()
+            insights.extend(work_relationships)
+
+        return sorted(insights, key=lambda i: i.confidence, reverse=True)
+
+    @staticmethod
+    def _pearson_correlation(xs: list, ys: list) -> float:
+        """Compute Pearson correlation coefficient between two lists."""
+        n = len(xs)
+        if n < 2:
+            return 0.0
+        try:
+            mean_x = sum(xs) / n
+            mean_y = sum(ys) / n
+            cov = sum((xs[i] - mean_x) * (ys[i] - mean_y) for i in range(n))
+            std_x = math.sqrt(sum((x - mean_x) ** 2 for x in xs))
+            std_y = math.sqrt(sum((y - mean_y) ** 2 for y in ys))
+            if std_x == 0.0 or std_y == 0.0:
+                return 0.0
+            return cov / (std_x * std_y)
+        except (ArithmeticError, ValueError, ZeroDivisionError) as exc:
+            logger.debug("Pearson correlation failed (treating as 0.0): %s", exc)
+            return 0.0
+
+    def _extract_date(self, mem: dict) -> Optional[datetime]:
+        """Extract datetime from a memory dict."""
+        created_at = mem.get("created_at")
+        if created_at is None:
+            return None
+        def _aware(dt):
+            # Mixed naive/aware datetimes make the later subtraction raise
+            # TypeError (swallowed upstream -> insights silently vanish).
+            if isinstance(dt, datetime) and dt.tzinfo is None:
+                return dt.replace(tzinfo=timezone.utc)
+            return dt
+        if isinstance(created_at, datetime):
+            return _aware(created_at)
+        # Neo4j DateTime object
+        if hasattr(created_at, 'to_native'):
+            return _aware(created_at.to_native())
+        # ISO string
+        try:
+            if isinstance(created_at, str):
+                return _aware(datetime.fromisoformat(created_at.replace("Z", "+00:00")))
+        except (ValueError, AttributeError) as exc:
+            logger.debug("_extract_date: unparseable created_at %r: %s", created_at, exc)
+        return None
+
+    def _correlate_domain_memories(
+        self,
+        mems_a: list,
+        mems_b: list,
+        window_days: float = 3.0,
+    ) -> tuple:
+        """Find temporally co-occurring pairs between two memory lists.
+
+        Returns (pairs, correlation) where pairs is list of (mem_a, mem_b) tuples
+        and correlation is the Pearson correlation of their strength values.
+        """
+        pairs = []
+        for ma in mems_a:
+            date_a = self._extract_date(ma)
+            if date_a is None:
+                continue
+            for mb in mems_b:
+                date_b = self._extract_date(mb)
+                if date_b is None:
+                    continue
+                diff_days = abs((date_a - date_b).total_seconds()) / 86400
+                if diff_days <= window_days:
+                    pairs.append((ma, mb))
+        if len(pairs) < 3:
+            return pairs, 0.0
+        strengths_a = [p[0].get("strength", 0.5) or 0.5 for p in pairs]
+        strengths_b = [p[1].get("strength", 0.5) or 0.5 for p in pairs]
+        corr = self._pearson_correlation(strengths_a, strengths_b)
+        return pairs, corr
+
+    async def _analyze_health_work(self) -> List[DomainInsight]:
+        """Analyze health -> work availability patterns."""
+        try:
+            health_mems = await self.graph.recall(
+                "sleep score stress energy fatigue exercise",
+                limit=50, min_strength=0.2,
+            )
+            work_mems = await self.graph.recall(
+                "deadline meeting cancelled productivity output",
+                limit=50, min_strength=0.2,
+            )
+            pairs, correlation = self._correlate_domain_memories(health_mems, work_mems, window_days=3.0)
+            if len(pairs) < 3 or abs(correlation) < 0.4:
+                return []
+            evidence = list({p[0].get("id", "") for p in pairs[:5]} | {p[1].get("id", "") for p in pairs[:5]})
+            evidence = [e for e in evidence if e][:5]
+            return [DomainInsight(
+                id=str(uuid.uuid4()),
+                domains=["health", "work"],
+                insight_type="availability_prediction",
+                description="Low sleep scores correlate with reduced work output in the following days",
+                confidence=min(1.0, abs(correlation)),
+                actionable=True,
+                recommended_action="Block focus time after poor sleep nights",
+                supporting_evidence=evidence,
+            )]
+        except Exception as e:
+            logger.debug("_analyze_health_work failed: %s", e)
+            return []
+
+    async def _analyze_relationships_health(self) -> List[DomainInsight]:
+        """Analyze relationship dynamics -> health impact."""
+        try:
+            relationship_mems = await self.graph.recall(
+                "conflict argument tension difficult person stressful interaction",
+                limit=50, min_strength=0.2,
+            )
+            health_mems = await self.graph.recall(
+                "stress anxiety sleep disruption fatigue mood",
+                limit=50, min_strength=0.2,
+            )
+            pairs, correlation = self._correlate_domain_memories(relationship_mems, health_mems, window_days=2.0)
+            if len(pairs) < 3 or abs(correlation) < 0.4:
+                return []
+            evidence = list({p[0].get("id", "") for p in pairs[:5]} | {p[1].get("id", "") for p in pairs[:5]})
+            evidence = [e for e in evidence if e][:5]
+            return [DomainInsight(
+                id=str(uuid.uuid4()),
+                domains=["relationships", "health"],
+                insight_type="stress_pattern",
+                description="Difficult relationship interactions correlate with health signal spikes within 48 hours",
+                confidence=min(1.0, abs(correlation)),
+                actionable=True,
+                recommended_action="Schedule recovery time after high-conflict interactions",
+                supporting_evidence=evidence,
+            )]
+        except Exception as e:
+            logger.debug("_analyze_relationships_health failed: %s", e)
+            return []
+
+    async def _analyze_work_relationships(self) -> List[DomainInsight]:
+        """Analyze work patterns -> relationship impact."""
+        try:
+            work_stress_mems = await self.graph.recall(
+                "deadline crunch sprint overloaded travel busy",
+                limit=50, min_strength=0.2,
+            )
+            social_mems = await self.graph.recall(
+                "cancelled plans late reply short message ignored social",
+                limit=50, min_strength=0.2,
+            )
+            pairs, correlation = self._correlate_domain_memories(work_stress_mems, social_mems, window_days=3.0)
+            if len(pairs) < 3 or abs(correlation) < 0.4:
+                return []
+            evidence = list({p[0].get("id", "") for p in pairs[:5]} | {p[1].get("id", "") for p in pairs[:5]})
+            evidence = [e for e in evidence if e][:5]
+            return [DomainInsight(
+                id=str(uuid.uuid4()),
+                domains=["work", "relationships"],
+                insight_type="communication_shift",
+                description="Heavy work stress periods correlate with reduced social responsiveness",
+                confidence=min(1.0, abs(correlation)),
+                actionable=True,
+                recommended_action="Proactively communicate reduced availability during high-load periods",
+                supporting_evidence=evidence,
+            )]
+        except Exception as e:
+            logger.debug("_analyze_work_relationships failed: %s", e)
+            return []