apsimo 1.3.0__py3-none-any.whl

apsimo/models/signal.py

@@ -0,0 +1,108 @@
+"""Behavioral signal models.
+
+Signals are atomic observations about a person's communication patterns,
+sentiment, and availability. They feed into the mind model for state
+estimation and relationship scoring.
+
+Colony is a first-class participant in its own signal stream — not merely an
+observer. Colony-sourced signals (``direction="colony"``) capture Colony's own
+behavior: when it reaches out, how effective its actions are, how well its
+adapted style is received. Contact-sourced signals (``direction="contact"``)
+capture the other person's behavior. Bilateral signals (``direction="bilateral"``)
+describe the exchange pattern between Colony and a contact.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class SignalType(str, Enum):
+    """Categories of behavioral signals.
+
+    Communication patterns track message flow characteristics.
+    Sentiment signals capture emotional tone.
+    Interaction quality measures depth of engagement.
+    Availability tracks when someone is typically reachable.
+
+    Colony signals (new) capture Colony's own behavior in the signal stream.
+    These feed the colony_initiative_response, colony_effectiveness, and
+    colony_style_fit scoring dimensions.
+    """
+
+    # Communication patterns
+    MESSAGE_FREQUENCY = "message_frequency"
+    RESPONSE_TIME = "response_time"
+    INITIATION_RATE = "initiation_rate"
+
+    # Sentiment
+    SENTIMENT_POSITIVE = "sentiment_positive"
+    SENTIMENT_NEGATIVE = "sentiment_negative"
+    SENTIMENT_NEUTRAL = "sentiment_neutral"
+
+    # Interaction quality
+    ENGAGEMENT_DEPTH = "engagement_depth"
+    TOPIC_DIVERSITY = "topic_diversity"
+
+    # Availability
+    TYPICAL_ACTIVE_HOURS = "typical_active_hours"
+    AVAILABILITY_PATTERN = "availability_pattern"
+
+    # Colony-sourced signals (Colony is a participant, not just an observer)
+    COLONY_INITIATIVE = "colony_initiative"           # Colony reached out first
+    COLONY_SUGGESTION = "colony_suggestion"           # Colony made a suggestion/action
+    COLONY_EFFECTIVENESS = "colony_effectiveness"     # Outcome of Colony's action
+    CONTACT_RESPONSE_TO_COLONY = "contact_response_to_colony"  # Response to Colony-origin
+    COLONY_STYLE_SIGNAL = "colony_style_signal"       # Style adaptation feedback
+
+    # Legacy aliases kept for migration compatibility
+    OWNER_EXPLICIT = "owner_explicit"
+
+
+class SignalStrength(str, Enum):
+    """Confidence level of a signal observation.
+
+    WEAK: Low confidence, sparse data
+    MODERATE: Reasonable confidence, sufficient data
+    STRONG: High confidence, abundant data
+    """
+
+    WEAK = "weak"
+    MODERATE = "moderate"
+    STRONG = "strong"
+
+
+@dataclass
+class Signal:
+    """A single behavioral observation about a person.
+
+    Signals are the raw building blocks of Colony's understanding.
+    Each signal captures one dimension of behavior at a point in time.
+
+    Attributes:
+        id: Unique identifier
+        person_id: The person this signal relates to
+        signal_type: What kind of behavior was observed
+        value: Normalized value between 0 and 1
+        raw_value: Original unnormalized value (for debugging/recalibration)
+        strength: Confidence level of this observation
+        source: How the signal was generated ("observed", "inferred", "explicit")
+        timestamp: When the signal was captured
+        context: Additional metadata (channel, message_id, etc.)
+        direction: Who the signal is about.
+            "contact" — describes the contact's behavior (existing signals).
+            "colony"  — describes Colony's own behavior (colony_initiative etc.).
+            "bilateral" — describes the exchange pattern (e.g. initiation_ratio).
+    """
+
+    id: str
+    person_id: str
+    signal_type: SignalType
+    value: float
+    raw_value: Optional[float] = None
+    strength: SignalStrength = SignalStrength.MODERATE
+    source: str = "observed"
+    timestamp: Optional[datetime] = None
+    context: Optional[Dict[str, Any]] = None
+    direction: str = "contact"  # "contact" | "colony" | "bilateral"

apsimo/observations/__init__.py

@@ -0,0 +1,15 @@
+"""Observation store (v0.16.0) — the agent is Colony's sensor array.
+
+Colony does not own external API clients. The agent observes the world
+through its existing Hermes connections (github, terminal, web, ...)
+and reports domain snapshots here. Colony's context loaders read
+observations, never external APIs.
+"""
+
+from apsimo.observations.store import (
+    OBSERVATION_DOMAINS,
+    Observation,
+    ObservationStore,
+)
+
+__all__ = ["Observation", "ObservationStore", "OBSERVATION_DOMAINS"]

apsimo/observations/store.py

@@ -0,0 +1,277 @@
+"""SQLite store for agent-reported domain observations (v0.16.0).
+
+One row per (domain, entity_id) — the latest snapshot wins. Colony's
+initiative generators read these; the autonomy loop requests refreshes
+by posting read-only ``agent_sync_<domain>`` jobs when a domain's
+newest observation outlives its sync interval.
+
+Expected payload shapes per domain (generators are defensive — extra
+keys pass through into initiative context, missing keys skip rules):
+
+- coding:   {title, url, ci_status, review_requested, draft, author}
+- task:     {title, url, state, assignee, due, stale_days}
+- calendar: {title, start_time, location, attendees, needs_prep}
+- research: {title, url, status, last_checked}
+- project:  {title, due_on, open_issues, closed_issues}
+- system:   {status, latency_ms, error_rate, message}
+- skills:   {description, tags, path, source}  (v0.18.0 Hermes bridge)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Domains the sensor loop knows about. Adding a domain means: a sync
+# action in the action registry, a generator in the initiative engine,
+# and (if volatile) a durability entry in context_freshness.py.
+OBSERVATION_DOMAINS = (
+    "coding",
+    "task",
+    "calendar",
+    "research",
+    "project",
+    "system",
+    # v0.18.0: the agent's installed Hermes skill index, reported by the
+    # OpenClaw plugin. Push-only — the plugin scans ~/.hermes/skills on
+    # its own schedule, so this domain deliberately has NO entry in
+    # OBSERVATION_SYNC_ACTIONS and is NOT in the COLONY_SYNC_DOMAINS
+    # defaults; the autonomy loop never posts agent_sync jobs for it.
+    "skills",
+)
+
+# How old a domain's newest observation may be before the autonomy loop
+# requests a fresh sync from the agent (seconds). Coarser than the
+# context-freshness TTLs — those govern acting on one snapshot, these
+# govern re-scanning a whole domain.
+OBSERVATION_SYNC_INTERVALS: Dict[str, int] = {
+    "coding": 900,
+    "task": 3600,
+    "calendar": 900,
+    "research": 86400,
+    "project": 86400,
+    "system": 300,
+    # Informational only: the plugin pushes the Hermes skill index every
+    # 24h; the loop never requests a sync for this push-only domain.
+    "skills": 86400,
+}
+
+
+@dataclass
+class Observation:
+    domain: str
+    entity_id: str
+    payload: Dict[str, Any]
+    observed_at: Optional[datetime]
+    reported_by: Optional[str] = None
+
+    @classmethod
+    def from_row(cls, row: dict) -> "Observation":
+        payload_raw = row.get("payload") or "{}"
+        try:
+            payload = json.loads(payload_raw) if isinstance(payload_raw, str) else payload_raw
+        except (ValueError, TypeError):
+            payload = {}
+        observed_at = row.get("observed_at")
+        if isinstance(observed_at, str):
+            try:
+                observed_at = datetime.fromisoformat(observed_at.replace("Z", "+00:00"))
+            except (ValueError, TypeError):
+                observed_at = None
+        return cls(
+            domain=row["domain"],
+            entity_id=row["entity_id"],
+            payload=payload,
+            observed_at=observed_at if isinstance(observed_at, datetime) else None,
+            reported_by=row.get("reported_by"),
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "domain": self.domain,
+            "entity_id": self.entity_id,
+            "payload": self.payload,
+            "observed_at": self.observed_at.isoformat() if self.observed_at else None,
+            "reported_by": self.reported_by,
+        }
+
+
+class ObservationStore:
+    """Latest-snapshot-per-entity observation persistence."""
+
+    def __init__(self, state_dir: Optional[Path] = None):
+        if state_dir is None:
+            from apsimo.initiatives.store import get_state_dir
+            state_dir = get_state_dir()
+        self._state_dir = Path(state_dir)
+        self._state_dir.mkdir(parents=True, exist_ok=True)
+        self._db_path = self._state_dir / "observations.db"
+        self._db = self._connect()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=5000")
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS observations (
+                domain TEXT NOT NULL,
+                entity_id TEXT NOT NULL,
+                payload TEXT NOT NULL DEFAULT '{}',
+                observed_at TEXT NOT NULL,
+                reported_by TEXT,
+                PRIMARY KEY (domain, entity_id)
+            )
+            """
+        )
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_observations_domain "
+            "ON observations(domain, observed_at DESC)"
+        )
+        conn.commit()
+        return conn
+
+    # ------------------------------------------------------------------
+    # Writes
+    # ------------------------------------------------------------------
+
+    def record(
+        self,
+        domain: str,
+        entity_id: str,
+        payload: Dict[str, Any],
+        reported_by: Optional[str] = None,
+        observed_at: Optional[datetime] = None,
+    ) -> Observation:
+        """Upsert the latest snapshot for one entity."""
+        observed_at = observed_at or datetime.now(timezone.utc)
+        self._db.execute(
+            """
+            INSERT INTO observations (domain, entity_id, payload, observed_at, reported_by)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(domain, entity_id) DO UPDATE SET
+                payload = excluded.payload,
+                observed_at = excluded.observed_at,
+                reported_by = excluded.reported_by
+            """,
+            [domain, entity_id, json.dumps(payload), observed_at.isoformat(), reported_by],
+        )
+        self._db.commit()
+        return Observation(domain, entity_id, payload, observed_at, reported_by)
+
+    def record_batch(
+        self,
+        domain: str,
+        observations: List[Dict[str, Any]],
+        reported_by: Optional[str] = None,
+    ) -> int:
+        """Record many snapshots for one domain. Returns rows written."""
+        written = 0
+        for obs in observations:
+            entity_id = obs.get("entity_id")
+            if not entity_id:
+                continue
+            observed_at = obs.get("observed_at")
+            if isinstance(observed_at, str):
+                try:
+                    observed_at = datetime.fromisoformat(observed_at.replace("Z", "+00:00"))
+                except (ValueError, TypeError):
+                    continue  # An invalid supplied time is not a fresh observation.
+            self.record(
+                domain=domain,
+                entity_id=str(entity_id),
+                payload=obs.get("payload") or {},
+                reported_by=reported_by,
+                observed_at=observed_at,
+            )
+            written += 1
+        return written
+
+    def delete(self, domain: str, entity_id: str) -> bool:
+        cur = self._db.execute(
+            "DELETE FROM observations WHERE domain = ? AND entity_id = ?",
+            [domain, entity_id],
+        )
+        self._db.commit()
+        return cur.rowcount > 0
+
+    def prune(self, older_than_days: float = 30.0) -> int:
+        """Drop snapshots nothing has refreshed in a long time."""
+        cutoff = datetime.now(timezone.utc).timestamp() - older_than_days * 86400
+        cutoff_iso = datetime.fromtimestamp(cutoff, tz=timezone.utc).isoformat()
+        cur = self._db.execute(
+            "DELETE FROM observations WHERE observed_at < ?", [cutoff_iso]
+        )
+        self._db.commit()
+        return cur.rowcount
+
+    # ------------------------------------------------------------------
+    # Reads
+    # ------------------------------------------------------------------
+
+    def get(self, domain: str, entity_id: str) -> Optional[Observation]:
+        cur = self._db.execute(
+            "SELECT * FROM observations WHERE domain = ? AND entity_id = ?",
+            [domain, entity_id],
+        )
+        row = cur.fetchone()
+        return Observation.from_row(dict(row)) if row else None
+
+    def list(self, domain: str, limit: int = 100) -> List[Observation]:
+        cur = self._db.execute(
+            "SELECT * FROM observations WHERE domain = ? "
+            "ORDER BY observed_at DESC LIMIT ?",
+            [domain, limit],
+        )
+        return [Observation.from_row(dict(r)) for r in cur.fetchall()]
+
+    def domain_age_seconds(self, domain: str) -> Optional[float]:
+        """Seconds since the NEWEST observation in a domain.
+
+        None when the domain has never been observed — callers treat
+        that as maximally stale (a sync is needed to prime it).
+        """
+        cur = self._db.execute(
+            "SELECT MAX(observed_at) AS newest FROM observations WHERE domain = ?",
+            [domain],
+        )
+        row = cur.fetchone()
+        newest = row["newest"] if row else None
+        if not newest:
+            return None
+        try:
+            stamp = datetime.fromisoformat(str(newest).replace("Z", "+00:00"))
+        except (ValueError, TypeError):
+            return None
+        if stamp.tzinfo is None:
+            stamp = stamp.replace(tzinfo=timezone.utc)
+        return (datetime.now(timezone.utc) - stamp).total_seconds()
+
+    def summary(self) -> Dict[str, Dict[str, Any]]:
+        """Per-domain counts and freshness."""
+        cur = self._db.execute(
+            "SELECT domain, COUNT(*) AS n, MAX(observed_at) AS newest "
+            "FROM observations GROUP BY domain"
+        )
+        out: Dict[str, Dict[str, Any]] = {}
+        for row in cur.fetchall():
+            out[row["domain"]] = {
+                "count": row["n"],
+                "newest_observed_at": row["newest"],
+                "age_seconds": self.domain_age_seconds(row["domain"]),
+            }
+        return out
+
+    def close(self) -> None:
+        try:
+            self._db.close()
+        except Exception:
+            pass

apsimo/patterns/__init__.py

@@ -0,0 +1,6 @@
+"""Pattern Extraction — identify recurring structures in the world model."""
+
+from apsimo.patterns.store import PatternStore
+from apsimo.patterns.extract import extract_patterns
+
+__all__ = ["PatternStore", "extract_patterns"]

apsimo/patterns/extract.py

@@ -0,0 +1,187 @@
+"""Pattern extraction — pull patterns from the world model."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def extract_patterns(
+    world_store: Any = None,
+    pattern_store: Any = None,
+) -> Dict[str, Any]:
+    """Run pattern extraction against the world model.
+
+    If world_store or pattern_store is None, returns a no-op result.
+    Returns {"new": N, "updated": M, "total": T}.
+    """
+    if world_store is None or pattern_store is None:
+        return {"new": 0, "updated": 0, "total": 0, "reason": "stores_not_wired"}
+
+    results = {"new": 0, "updated": 0, "total": 0}
+
+    # Extract entity cooccurrence patterns.
+    try:
+        cooc = _extract_entity_cooccurrence(world_store)
+        for pattern in cooc:
+            result = pattern_store.create_pattern(**pattern)
+            if result.get("frequency", 1) > 1:
+                results["updated"] += 1
+            else:
+                results["new"] += 1
+    except Exception as exc:
+        logger.debug("entity cooccurrence extraction failed: %s", exc)
+
+    # Extract relation frequency patterns.
+    try:
+        rels = _extract_relation_frequency(world_store)
+        for pattern in rels:
+            result = pattern_store.create_pattern(**pattern)
+            if result.get("frequency", 1) > 1:
+                results["updated"] += 1
+            else:
+                results["new"] += 1
+    except Exception as exc:
+        logger.debug("relation frequency extraction failed: %s", exc)
+
+    # Extract attribute cluster patterns.
+    try:
+        attrs = _extract_attribute_clusters(world_store)
+        for pattern in attrs:
+            result = pattern_store.create_pattern(**pattern)
+            if result.get("frequency", 1) > 1:
+                results["updated"] += 1
+            else:
+                results["new"] += 1
+    except Exception as exc:
+        logger.debug("attribute cluster extraction failed: %s", exc)
+
+    total = pattern_store.list_patterns(active_only=True)
+    results["total"] = total.get("total", 0)
+    return results
+
+
+def _extract_entity_cooccurrence(world_store: Any) -> List[Dict[str, Any]]:
+    """Find entities that share relationships."""
+    patterns: List[Dict[str, Any]] = []
+
+    try:
+        entities = world_store.list_entities(limit=200)
+    except Exception as exc:
+        logger.debug("list_entities failed in pattern extraction: %s", exc)
+        return patterns
+
+    if not entities:
+        return patterns
+
+    # Group entities by relationship target.
+    target_map: Dict[str, List[str]] = {}
+    for entity in entities:
+        name = entity.get("name", "")
+        etype = entity.get("entity_type", "")
+        if not name:
+            continue
+        # Use entity type as a grouping key for cooccurrence.
+        if etype not in target_map:
+            target_map[etype] = []
+        target_map[etype].append(name)
+
+    # Entities that share a type are cooccurring.
+    for etype, names in target_map.items():
+        if len(names) < 2:
+            continue
+        # Create pairwise patterns for top entities.
+        for i in range(min(len(names), 5)):
+            for j in range(i + 1, min(len(names), 5)):
+                key = f"cooc:{sorted([names[i], names[j]])[0]}→{sorted([names[i], names[j]])[1]}"
+                patterns.append({
+                    "pattern_type": "entity_cooccurrence",
+                    "description": f"{names[i]} and {names[j]} both appear as {etype}",
+                    "pattern_key": key,
+                    "confidence": 0.6,
+                    "source": "extraction",
+                    "metadata": {"type": etype, "entities": [names[i], names[j]]},
+                })
+
+    return patterns
+
+
+def _extract_relation_frequency(world_store: Any) -> List[Dict[str, Any]]:
+    """Find frequently occurring relationship types."""
+    patterns: List[Dict[str, Any]] = []
+
+    try:
+        entities = world_store.list_entities(limit=200)
+    except Exception as exc:
+        logger.debug("list_entities failed in pattern extraction: %s", exc)
+        return patterns
+
+    # Count relationship types.
+    rel_counts: Dict[str, int] = {}
+    for entity in entities:
+        rels = entity.get("relationships", [])
+        if isinstance(rels, list):
+            for rel in rels:
+                rtype = rel.get("type", "") if isinstance(rel, dict) else str(rel)
+                if rtype:
+                    rel_counts[rtype] = rel_counts.get(rtype, 0) + 1
+
+    for rtype, count in rel_counts.items():
+        if count < 2:
+            continue
+        patterns.append({
+            "pattern_type": "relation_frequency",
+            "description": f"Relationship type '{rtype}' appears {count} times",
+            "pattern_key": f"rel_freq:{rtype}",
+            "frequency": count,
+            "confidence": min(1.0, 0.3 + count * 0.1),
+            "source": "extraction",
+            "metadata": {"relation_type": rtype, "count": count},
+        })
+
+    return patterns
+
+
+def _extract_attribute_clusters(world_store: Any) -> List[Dict[str, Any]]:
+    """Find entities of the same type that share attribute keys."""
+    patterns: List[Dict[str, Any]] = []
+
+    try:
+        entities = world_store.list_entities(limit=200)
+    except Exception as exc:
+        logger.debug("list_entities failed in pattern extraction: %s", exc)
+        return patterns
+
+    # Group by type, collect attribute keys.
+    type_attrs: Dict[str, Dict[str, int]] = {}
+    for entity in entities:
+        etype = entity.get("entity_type", "")
+        attrs = entity.get("attributes", {})
+        if not isinstance(attrs, dict):
+            continue
+        if etype not in type_attrs:
+            type_attrs[etype] = {}
+        for key in attrs:
+            type_attrs[etype][key] = type_attrs[etype].get(key, 0) + 1
+
+    for etype, attr_counts in type_attrs.items():
+        if len(attr_counts) < 2:
+            continue
+        # Only include attributes that appear in multiple entities.
+        common = [k for k, v in attr_counts.items() if v >= 2]
+        if len(common) < 2:
+            continue
+        common.sort()
+        key = f"attr_cluster:{etype}:{','.join(common[:5])}"
+        patterns.append({
+            "pattern_type": "attribute_cluster",
+            "description": f"{etype} entities share attributes: {', '.join(common[:5])}",
+            "pattern_key": key,
+            "confidence": 0.7,
+            "source": "extraction",
+            "metadata": {"entity_type": etype, "attributes": common[:10]},
+        })
+
+    return patterns