apsimo 1.3.0__py3-none-any.whl

apsimo/goals/inference.py

@@ -0,0 +1,354 @@
+"""Goal Inference Pipeline — detect implicit goals from conversation context.
+
+Architecture:
+  1. Rule-based pass (synchronous, < 5 ms) — keyword/pattern matching
+  2. GoalDeduplicator — semantic similarity check against active goals
+
+NOTE: an LLM second-pass for low-confidence candidates was envisioned but is
+NOT implemented — there is no hook or override seam in this module. Candidates
+below MIN_CONFIDENCE are simply dropped. (Wire one through the project's Anthropic
+client if low-confidence recall becomes a need; keep the rule-based path's <5 ms
+synchronous guarantee — any LLM call must be out of band.)
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+
+from apsimo.goals.models import Goal, GoalPriority, GoalSource
+
+
+class IntentSignal(str, Enum):
+    """Conversation signal types that may indicate a goal."""
+    DESIRE      = "desire"       # "I want to / I need to / I'd like to"
+    OBLIGATION  = "obligation"   # "I have to / I must / I should"
+    PROBLEM     = "problem"      # "I'm struggling with / This is broken"
+    DEADLINE    = "deadline"     # Explicit time reference with task context
+    FRUSTRATION = "frustration"  # Repeated problem mentions, negative sentiment
+    RECURRING   = "recurring"    # "Every week / daily / each morning"
+    DELEGATION  = "delegation"   # "Can you / Could you / Please"
+
+
+@dataclass
+class ConversationMessage:
+    """A single message in a conversation."""
+    message_id: str
+    role: str       # "user" | "assistant" | "system"
+    content: str
+    timestamp: Optional[float] = None   # Unix epoch
+
+
+@dataclass
+class InferenceCandidate:
+    """A candidate goal extracted from conversation context.
+
+    Attributes:
+        title:             Inferred goal title.
+        description:       Full description including supporting context.
+        signals:           Which signal types contributed to this inference.
+        confidence:        0.0–1.0 confidence that this is a real goal.
+        source_messages:   IDs of conversation messages that triggered inference.
+        suggested_deadline: Extracted deadline if any.
+        priority:          Inferred priority based on signal type.
+    """
+    title: str
+    description: str
+    signals: List[IntentSignal]
+    confidence: float
+    source_messages: List[str]
+    suggested_deadline: Optional[str] = None   # ISO-8601 if detected
+    priority: GoalPriority = GoalPriority.NORMAL
+
+    def should_auto_accept(self, threshold: float = 0.85) -> bool:
+        """Return True if confidence exceeds auto-accept threshold."""
+        return (
+            self.confidence >= threshold
+            and IntentSignal.DELEGATION in self.signals
+        )
+
+
+@dataclass
+class GoalSimilarity:
+    """Result of comparing two goals for deduplication."""
+    goal_id_a: str
+    goal_id_b: str
+    similarity_score: float    # 0.0–1.0
+    shared_keywords: List[str]
+    recommendation: str        # "duplicate" | "merge" | "related" | "distinct"
+
+
+# ── Rule-based signal patterns ────────────────────────────────────────────────
+
+_DESIRE_PATTERNS = re.compile(
+    r"\b(i want to|i need to|i'd like to|i would like to|i wish|i hope to|"
+    r"need to|want to|gotta|going to|planning to)\b",
+    re.IGNORECASE,
+)
+_OBLIGATION_PATTERNS = re.compile(
+    r"\b(i have to|i must|i should|i ought to|have to|must|should|"
+    r"need to finish|deadline|due by|due on)\b",
+    re.IGNORECASE,
+)
+_PROBLEM_PATTERNS = re.compile(
+    r"\b(struggling with|broken|not working|failing|error|bug|issue|problem|"
+    r"can't figure out|don't know how|stuck on|frustrated with|having trouble)\b",
+    re.IGNORECASE,
+)
+_DEADLINE_PATTERNS = re.compile(
+    r"\b(by (monday|tuesday|wednesday|thursday|friday|saturday|sunday)|"
+    r"by (tomorrow|tonight|end of (day|week|month))|"
+    r"before (the meeting|the call|the deadline)|"
+    r"(this|next) (monday|tuesday|wednesday|thursday|friday|week|month)|"
+    r"in (\d+) (hours?|days?|weeks?))\b",
+    re.IGNORECASE,
+)
+_RECURRING_PATTERNS = re.compile(
+    r"\b(every (day|week|month|morning|evening|monday|tuesday|wednesday|"
+    r"thursday|friday)|daily|weekly|monthly|each (morning|day|week))\b",
+    re.IGNORECASE,
+)
+_DELEGATION_PATTERNS = re.compile(
+    r"\b(can you|could you|please|would you|help me|remind me|schedule|"
+    r"set up|create|make|send|write|draft|prepare|organize)\b",
+    re.IGNORECASE,
+)
+_FRUSTRATION_PATTERNS = re.compile(
+    r"\b(frustrated|annoying|ridiculous|terrible|awful|keeps (breaking|failing)|"
+    r"still broken|why doesn'?t|why isn'?t|never works|always fails)\b",
+    re.IGNORECASE,
+)
+
+_PRIORITY_SIGNALS = {
+    IntentSignal.OBLIGATION: GoalPriority.HIGH,
+    IntentSignal.DEADLINE: GoalPriority.HIGH,
+    IntentSignal.FRUSTRATION: GoalPriority.HIGH,
+    IntentSignal.DELEGATION: GoalPriority.NORMAL,
+    IntentSignal.DESIRE: GoalPriority.NORMAL,
+    IntentSignal.PROBLEM: GoalPriority.NORMAL,
+    IntentSignal.RECURRING: GoalPriority.LOW,
+}
+
+
+def _extract_signals(text: str) -> List[Tuple[IntentSignal, float]]:
+    """Extract signals from text, returning (signal, weight) pairs."""
+    results: List[Tuple[IntentSignal, float]] = []
+    if _DESIRE_PATTERNS.search(text):
+        results.append((IntentSignal.DESIRE, 0.6))
+    if _OBLIGATION_PATTERNS.search(text):
+        results.append((IntentSignal.OBLIGATION, 0.7))
+    if _PROBLEM_PATTERNS.search(text):
+        results.append((IntentSignal.PROBLEM, 0.55))
+    if _DEADLINE_PATTERNS.search(text):
+        results.append((IntentSignal.DEADLINE, 0.65))
+    if _RECURRING_PATTERNS.search(text):
+        results.append((IntentSignal.RECURRING, 0.5))
+    if _DELEGATION_PATTERNS.search(text):
+        results.append((IntentSignal.DELEGATION, 0.75))
+    if _FRUSTRATION_PATTERNS.search(text):
+        results.append((IntentSignal.FRUSTRATION, 0.6))
+    return results
+
+
+def _compute_confidence(signals: List[Tuple[IntentSignal, float]]) -> float:
+    """Combine multiple signal weights into a single confidence score."""
+    if not signals:
+        return 0.0
+    # Combine with diminishing returns: 1 - product(1 - w)
+    combined = 1.0
+    for _, w in signals:
+        combined *= (1.0 - w)
+    return round(1.0 - combined, 4)
+
+
+def _infer_priority(signals: List[IntentSignal]) -> GoalPriority:
+    """Select highest priority implied by the signal set."""
+    best = GoalPriority.BACKGROUND
+    for sig in signals:
+        p = _PRIORITY_SIGNALS.get(sig, GoalPriority.NORMAL)
+        if p.value > best.value:
+            best = p
+    return best
+
+
+def _extract_title(text: str) -> str:
+    """Produce a short title from the message text (max 80 chars)."""
+    # Strip leading/trailing whitespace and trim to 80 chars
+    cleaned = re.sub(r"\s+", " ", text.strip())
+    # Remove common filler phrases
+    cleaned = re.sub(
+        r"^(can you|could you|please|i need to|i want to|i have to|"
+        r"i should|i must|help me)\s+",
+        "",
+        cleaned,
+        flags=re.IGNORECASE,
+    ).strip()
+    # Capitalize
+    if cleaned:
+        cleaned = cleaned[0].upper() + cleaned[1:]
+    return cleaned[:80].rstrip(".,;:")
+
+
+class GoalInferencePipeline:
+    """Detect implicit goals from conversation messages.
+
+    The rule-based pass runs synchronously on every user message. Candidates
+    below ``MIN_CONFIDENCE`` are dropped; there is no LLM second-pass wired in
+    (see module docstring).
+    """
+
+    MIN_CONFIDENCE = 0.35   # Below this, no candidate is produced
+
+    def __init__(self, min_confidence: float = MIN_CONFIDENCE) -> None:
+        self.min_confidence = min_confidence
+
+    def process_message(
+        self,
+        message: ConversationMessage,
+        history: Optional[List[ConversationMessage]] = None,
+    ) -> Optional[InferenceCandidate]:
+        """Run the rule-based inference pass on a single message.
+
+        Returns an InferenceCandidate if a goal-like signal is detected,
+        otherwise None.
+
+        Must complete in < 5 ms for typical inputs.
+        """
+        if message.role != "user":
+            return None
+
+        text = message.content
+        signals_weighted = _extract_signals(text)
+        if not signals_weighted:
+            return None
+
+        confidence = _compute_confidence(signals_weighted)
+        if confidence < self.min_confidence:
+            return None
+
+        signals = [s for s, _ in signals_weighted]
+        priority = _infer_priority(signals)
+        title = _extract_title(text)
+        if not title:
+            return None
+
+        # Extract deadline hint
+        deadline_match = _DEADLINE_PATTERNS.search(text)
+        suggested_deadline = deadline_match.group(0) if deadline_match else None
+
+        return InferenceCandidate(
+            title=title,
+            description=text.strip(),
+            signals=signals,
+            confidence=confidence,
+            source_messages=[message.message_id],
+            suggested_deadline=suggested_deadline,
+            priority=priority,
+        )
+
+    def process_history(
+        self,
+        history: List[ConversationMessage],
+    ) -> List[InferenceCandidate]:
+        """Process a conversation history, returning all detected candidates."""
+        candidates = []
+        for msg in history:
+            cand = self.process_message(msg, history=history)
+            if cand:
+                candidates.append(cand)
+        return candidates
+
+
+# ── Goal Deduplication ────────────────────────────────────────────────────────
+
+def _tokenize(text: str) -> set:
+    """Simple word-level tokenizer for keyword overlap scoring."""
+    # Remove stop words and short tokens
+    stop_words = {
+        "i", "a", "an", "the", "to", "is", "are", "was", "were",
+        "be", "been", "being", "have", "has", "had", "do", "does",
+        "did", "will", "would", "could", "should", "may", "might",
+        "shall", "can", "need", "want", "going", "get", "got",
+        "my", "me", "we", "us", "it", "its", "this", "that",
+        "and", "or", "but", "if", "in", "on", "at", "by", "for",
+        "with", "about", "as", "of", "from",
+    }
+    words = re.findall(r"[a-z]+", text.lower())
+    return {w for w in words if w not in stop_words and len(w) > 2}
+
+
+def _jaccard_similarity(a: set, b: set) -> float:
+    if not a or not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+class GoalDeduplicator:
+    """Check and merge candidate goals against the active goal set."""
+
+    DUPLICATE_THRESHOLD = 0.90
+    MERGE_THRESHOLD = 0.70
+
+    def check(
+        self,
+        candidate: InferenceCandidate,
+        existing: List[Goal],
+    ) -> Optional[GoalSimilarity]:
+        """
+        Return a GoalSimilarity if the candidate overlaps with an existing goal.
+        Returns None if the candidate is distinct from all existing goals.
+        """
+        if not existing:
+            return None
+
+        candidate_tokens = _tokenize(candidate.title + " " + candidate.description)
+        best: Optional[GoalSimilarity] = None
+
+        for goal in existing:
+            if goal.is_terminal():
+                continue
+            goal_tokens = _tokenize(goal.title + " " + goal.description)
+            score = _jaccard_similarity(candidate_tokens, goal_tokens)
+            shared = sorted(candidate_tokens & goal_tokens)
+
+            if score >= self.MERGE_THRESHOLD:
+                if score >= self.DUPLICATE_THRESHOLD:
+                    rec = "duplicate"
+                else:
+                    rec = "merge"
+
+                sim = GoalSimilarity(
+                    goal_id_a="candidate",
+                    goal_id_b=goal.goal_id,
+                    similarity_score=score,
+                    shared_keywords=shared[:10],
+                    recommendation=rec,
+                )
+                if best is None or score > best.similarity_score:
+                    best = sim
+
+        return best
+
+    def merge(self, base: Goal, candidate: InferenceCandidate) -> Goal:
+        """Enrich an existing goal with additional context from a new candidate."""
+        # Extend description if the candidate has more detail
+        if len(candidate.description) > len(base.description):
+            base.description = candidate.description
+
+        # Adopt deadline if base has none
+        if candidate.suggested_deadline and base.deadline is None:
+            base.context["inferred_deadline_hint"] = candidate.suggested_deadline
+
+        # Upgrade priority if candidate is higher
+        if candidate.priority.value > base.priority.value:
+            base.priority = candidate.priority
+
+        # Merge source message IDs into context
+        existing_msgs = base.context.get("source_messages", [])
+        combined = list(set(existing_msgs + candidate.source_messages))
+        base.context["source_messages"] = combined
+
+        return base

apsimo/goals/models.py

@@ -0,0 +1,302 @@
+"""Colony Goal Engine — core data models.
+
+Defines Goal, Subtask, GoalDAG and supporting types for the
+Colony DAG-based goal decomposition and lifecycle management system.
+"""
+
+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 GoalStatus(str, Enum):
+    """Goal lifecycle states."""
+    PROPOSED   = "proposed"    # Inferred or suggested; awaiting user acceptance
+    ACCEPTED   = "accepted"    # User confirmed; ready for decomposition
+    ACTIVE     = "active"      # Decomposed and executing
+    BLOCKED    = "blocked"     # Cannot proceed; waiting on external factor
+    COMPLETED  = "completed"   # All subtasks done; outcome achieved
+    ABANDONED  = "abandoned"   # Given up; reason recorded
+
+
+class GoalSource(str, Enum):
+    """How the goal was created."""
+    EXPLICIT   = "explicit"    # User stated the goal directly
+    INFERRED   = "inferred"    # Detected from conversation context
+    RECURRING  = "recurring"   # Generated from a recurring schedule
+    DELEGATED  = "delegated"   # Sent by another Colony agent via federation
+
+
+class GoalPriority(int, Enum):
+    """Goal scheduling priority. Higher = more urgent."""
+    BACKGROUND = 0
+    LOW        = 10
+    NORMAL     = 50
+    HIGH       = 80
+    CRITICAL   = 100
+
+
+class SubtaskStatus(str, Enum):
+    """Subtask execution states within a goal's DAG."""
+    PENDING    = "pending"     # Not yet dispatched
+    DISPATCHED = "dispatched"  # Job posted to task queue
+    RUNNING    = "running"     # Job claimed by a worker
+    COMPLETED  = "completed"   # Job finished successfully
+    FAILED     = "failed"      # Job failed; may trigger replan
+    SKIPPED    = "skipped"     # Bypassed via replan strategy
+    BLOCKED    = "blocked"     # Waiting on dependency subtasks
+
+
+@dataclass
+class GoalOutcome:
+    """Describes the desired end state of a completed goal."""
+    description: str
+    success_criteria: List[str] = field(default_factory=list)
+    measurable: bool = False
+    target_value: Optional[float] = None
+    target_unit: Optional[str] = None
+
+
+@dataclass
+class Goal:
+    """A user-level objective tracked by the Goal Engine.
+
+    Attributes:
+        goal_id:         Globally unique identifier.
+        title:           Short human-readable label (≤ 80 chars).
+        description:     Full description of the objective.
+        source:          How this goal was created.
+        status:          Current lifecycle state.
+        priority:        Scheduling priority score.
+        outcome:         Desired end state description.
+        deadline:        Optional absolute deadline.
+        parent_goal_id:  If this is a sub-goal, the parent's ID.
+        tags:            Arbitrary metadata for filtering and grouping.
+        context:         Conversation or event context that generated this goal.
+        created_at:      When the goal was created.
+        updated_at:      When the goal was last modified.
+        accepted_at:     When the user accepted the goal.
+        completed_at:    When the goal reached COMPLETED.
+        abandoned_at:    When the goal was abandoned.
+        abandon_reason:  Why the goal was abandoned.
+        replan_count:    Number of times the DAG has been replanned.
+        estimated_hours: Current completion time estimate in hours.
+        progress_pct:    Fraction of subtasks completed (0.0–1.0).
+    """
+    goal_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    title: str = ""
+    description: str = ""
+    source: GoalSource = GoalSource.EXPLICIT
+    status: GoalStatus = GoalStatus.PROPOSED
+    priority: GoalPriority = GoalPriority.NORMAL
+    outcome: Optional[GoalOutcome] = None
+    deadline: Optional[datetime] = None
+    parent_goal_id: Optional[str] = None
+    tags: Dict[str, str] = field(default_factory=dict)
+    context: Dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    accepted_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    abandoned_at: Optional[datetime] = None
+    abandon_reason: Optional[str] = None
+    replan_count: int = 0
+    estimated_hours: Optional[float] = None
+    progress_pct: float = 0.0
+
+    # Initiative management fields (v0.7.10)
+    last_initiative_at: Optional[datetime] = None
+    snoozed_until: Optional[datetime] = None
+    snooze_count: int = 0
+    dismissal_reason: Optional[str] = None
+
+    def is_terminal(self) -> bool:
+        # Compare by string value so the check is robust if GoalStatus is patched
+        # in a test environment (e.g. pytest-xdist workers that share sys.modules).
+        status_val = self.status.value if hasattr(self.status, "value") else str(self.status)
+        return status_val in ("completed", "abandoned")
+
+    def is_overdue(self) -> bool:
+        if self.deadline is None:
+            return False
+        return datetime.now(timezone.utc) > self.deadline
+
+    def age_hours(self) -> float:
+        return (datetime.now(timezone.utc) - self.created_at).total_seconds() / 3600.0
+
+
+@dataclass
+class Subtask:
+    """A concrete unit of work within a goal's DAG.
+
+    Attributes:
+        subtask_id:       Unique identifier within the goal.
+        goal_id:          Parent goal.
+        title:            Human-readable description.
+        job_type:         Task queue job type for dispatch.
+        payload:          Job-specific parameters.
+        capabilities:     Required worker capabilities.
+        depends_on:       List of subtask_ids that must complete first.
+        status:           Current execution state.
+        job_id:           Task queue job_id if dispatched.
+        result:           Job result if completed.
+        depth:            DAG depth level (root = 0).
+        is_critical_path: True if this subtask is on the critical path.
+        retry_count:      How many times this subtask has been retried.
+        max_retries:      Maximum retries before escalating to replan.
+        estimated_hours:  Expected execution duration.
+        started_at:       When the job started executing.
+        completed_at:     When the job completed.
+        error:            Error message if failed.
+    """
+    subtask_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    goal_id: str = ""
+    title: str = ""
+    job_type: str = "custom"
+    payload: Dict[str, Any] = field(default_factory=dict)
+    capabilities: List[str] = field(default_factory=list)
+    depends_on: List[str] = field(default_factory=list)
+    status: SubtaskStatus = SubtaskStatus.PENDING
+    job_id: Optional[str] = None
+    result: Optional[Dict[str, Any]] = None
+    depth: int = 0
+    is_critical_path: bool = False
+    retry_count: int = 0
+    max_retries: int = 2
+    estimated_hours: Optional[float] = None
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    error: Optional[str] = None
+
+    def is_ready(self, completed_ids: set) -> bool:
+        """Return True when all dependencies have completed."""
+        return all(dep in completed_ids for dep in self.depends_on)
+
+    def duration_hours(self) -> Optional[float]:
+        if self.started_at and self.completed_at:
+            return (self.completed_at - self.started_at).total_seconds() / 3600.0
+        return None
+
+
+@dataclass
+class GoalDAG:
+    """The directed acyclic graph of subtasks for a single goal.
+
+    Attributes:
+        goal_id:        Parent goal identifier.
+        subtasks:       All subtask nodes keyed by subtask_id.
+        root_ids:       Subtask IDs with no dependencies (entry points).
+        leaf_ids:       Subtask IDs with no dependents (exit points).
+        critical_path:  Ordered list of subtask_ids on the critical path.
+        max_depth:      Deepest level in the DAG.
+        created_at:     When this DAG version was created.
+        version:        Incremented on each replan.
+    """
+    goal_id: str
+    subtasks: Dict[str, Subtask] = field(default_factory=dict)
+    root_ids: List[str] = field(default_factory=list)
+    leaf_ids: List[str] = field(default_factory=list)
+    critical_path: List[str] = field(default_factory=list)
+    max_depth: int = 0
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    version: int = 1
+
+    def add_subtask(self, subtask: Subtask) -> None:
+        self.subtasks[subtask.subtask_id] = subtask
+
+    def ready_subtasks(self) -> List[Subtask]:
+        """Return all PENDING subtasks whose dependencies are met."""
+        completed = {
+            sid for sid, s in self.subtasks.items()
+            if s.status == SubtaskStatus.COMPLETED
+        }
+        return [
+            s for s in self.subtasks.values()
+            if s.status == SubtaskStatus.PENDING and s.is_ready(completed)
+        ]
+
+    def is_complete(self) -> bool:
+        return all(
+            s.status in {SubtaskStatus.COMPLETED, SubtaskStatus.SKIPPED}
+            for s in self.subtasks.values()
+        )
+
+    def completion_fraction(self) -> float:
+        if not self.subtasks:
+            return 0.0
+        done = sum(
+            1 for s in self.subtasks.values()
+            if s.status in {SubtaskStatus.COMPLETED, SubtaskStatus.SKIPPED}
+        )
+        return done / len(self.subtasks)
+
+    def validate(self) -> List[str]:
+        """Validate DAG structure. Returns list of error messages."""
+        errors: List[str] = []
+        ids = set(self.subtasks.keys())
+
+        # All dependencies must reference known subtasks
+        for s in self.subtasks.values():
+            for dep in s.depends_on:
+                if dep not in ids:
+                    errors.append(f"Subtask {s.subtask_id} has unknown dep {dep}")
+            # No self-dependency
+            if s.subtask_id in s.depends_on:
+                errors.append(f"Subtask {s.subtask_id} depends on itself")
+
+        # No cycles (DFS-based check)
+        visited: set = set()
+        rec_stack: set = set()
+
+        def has_cycle(node_id: str) -> bool:
+            visited.add(node_id)
+            rec_stack.add(node_id)
+            node = self.subtasks.get(node_id)
+            deps = node.depends_on if node else []
+            for dep in deps:
+                if dep not in visited:
+                    if has_cycle(dep):
+                        return True
+                elif dep in rec_stack:
+                    return True
+            rec_stack.discard(node_id)
+            return False
+
+        for sid in ids:
+            if sid not in visited:
+                if has_cycle(sid):
+                    errors.append(f"Cycle detected involving subtask {sid}")
+                    break
+
+        return errors
+
+
+@dataclass
+class GoalTransitionRecord:
+    """An audit record for a goal state transition."""
+    goal_id: str
+    from_status: str
+    to_status: str
+    trigger: str
+    created_at: datetime
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class GoalSummary:
+    """Human-readable summary for the briefing system."""
+    goal_id: str
+    title: str
+    status: str
+    priority: int
+    progress_pct: float
+    estimated_hours: Optional[float]
+    deadline: Optional[datetime]
+    subtask_count: int
+    completed_subtasks: int
+    is_overdue: bool
+    replan_count: int