apsimo 1.3.0__py3-none-any.whl

apsimo/intelligence/components/task_planner.py

@@ -0,0 +1,320 @@
+"""Task Planner — break complex requests into subtasks.
+
+Capabilities:
+    - Dependency detection
+    - Parallel task identification
+    - Resource estimation
+"""
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Set
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Patterns for identifying independently-executable task types
+_INDEPENDENT_TASK_PATTERNS = [
+    re.compile(r'\b(research|look up|find out|search for)\b'),
+    re.compile(r'\b(write|draft|compose|create)\b'),
+    re.compile(r'\b(schedule|book|reserve|arrange)\b'),
+    re.compile(r'\b(notify|email|message|send)\b'),
+    re.compile(r'\b(download|fetch|retrieve)\b'),
+]
+
+# Patterns indicating an explicit sequential dependency between tasks
+_DEPENDENCY_PATTERNS = [
+    re.compile(r'\b(then|after|once|following|based on|using the|with the)\b'),
+]
+
+# Keywords indicating sequential ordering (creates dependencies)
+_SEQUENTIAL_PATTERN = re.compile(
+    r"\s+(?:then|next|finally|after that|subsequently|afterward|before)\s+",
+    re.IGNORECASE,
+)
+
+# Keywords indicating parallel tasks (no dependencies)
+_PARALLEL_PATTERN = re.compile(
+    r"\s+(?:and also|also|simultaneously|at the same time|in parallel)\s+",
+    re.IGNORECASE,
+)
+
+# Keywords that suggest higher effort
+_HIGH_EFFORT_WORDS = frozenset(
+    {"research", "analyze", "analyse", "comprehensive", "detailed",
+     "thorough", "complex", "deep", "investigate", "audit"}
+)
+
+# Keywords that suggest lower effort
+_LOW_EFFORT_WORDS = frozenset(
+    {"quick", "simple", "brief", "short", "fast", "small", "minor",
+     "trivial", "basic", "easy"}
+)
+
+# Keywords that elevate priority
+_CRITICAL_WORDS = frozenset(
+    {"critical", "urgent", "immediately", "asap", "emergency", "blocker"}
+)
+
+_HIGH_PRIO_WORDS = frozenset(
+    {"important", "priority", "soon", "required", "must"}
+)
+
+
+class TaskPriority(str, Enum):
+    """Priority levels for subtasks."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class SubTask:
+    """A subtask in a decomposition.
+
+    Attributes:
+        id: Unique subtask identifier
+        description: Human-readable description
+        priority: Execution priority
+        dependencies: IDs of subtasks that must complete first
+        estimated_effort: Relative effort units (1.0 = baseline)
+        assigned_to: Optional node ID for mesh distribution
+    """
+
+    id: str
+    description: str
+    priority: TaskPriority = TaskPriority.MEDIUM
+    dependencies: List[str] = field(default_factory=list)
+    estimated_effort: float = 1.0
+    assigned_to: Optional[str] = None
+
+
+@dataclass
+class TaskPlan:
+    """A complete task decomposition.
+
+    Attributes:
+        id: Unique plan identifier
+        description: The original request
+        subtasks: Ordered list of subtasks
+        parallel_groups: Groups of subtask IDs that can execute concurrently
+        total_effort: Sum of all subtask efforts
+    """
+
+    id: str
+    description: str
+    subtasks: List[SubTask] = field(default_factory=list)
+    parallel_groups: List[List[str]] = field(default_factory=list)
+    total_effort: float = 0.0
+
+
+class TaskPlanner:
+    """Decompose complex requests into executable plans.
+
+    Takes a natural-language request, breaks it into subtasks,
+    identifies dependencies, and groups parallelizable work.
+
+    Decomposition rules:
+    - Sequential keywords ("then", "next", "finally"…) create ordered dependencies.
+    - Parallel keywords ("and also", "simultaneously"…) create independent tasks.
+    - Plain "and" splits into parallel tasks when no sequential markers are present.
+    - A single-sentence request creates one subtask.
+
+    Args:
+        graph_client: Colony graph client for context retrieval
+    """
+
+    def __init__(self, graph_client: Any) -> None:
+        self.graph = graph_client
+
+    async def plan(self, request: str, context: Optional[Dict[str, Any]] = None) -> TaskPlan:
+        """Create execution plan for a request.
+
+        Args:
+            request: Natural-language task description
+            context: Optional context for better decomposition
+
+        Returns:
+            TaskPlan with subtasks and parallel groups
+        """
+        subtasks = await self._decompose(request)
+
+        await self._identify_dependencies(subtasks)
+
+        parallel_groups = self._find_parallel_groups(subtasks)
+
+        total_effort = sum(s.estimated_effort for s in subtasks)
+
+        plan = TaskPlan(
+            id=f"plan-{hash(request) % 10000:04d}",
+            description=request,
+            subtasks=subtasks,
+            parallel_groups=parallel_groups,
+            total_effort=total_effort,
+        )
+
+        logger.debug(
+            "Created plan %s: %d subtasks, %d parallel groups, effort=%.1f",
+            plan.id,
+            len(subtasks),
+            len(parallel_groups),
+            total_effort,
+        )
+        return plan
+
+    async def _decompose(self, request: str) -> List[SubTask]:
+        """Decompose request into subtasks using keyword rules.
+
+        Sequential markers create ordered dependencies; parallel markers
+        and plain conjunctions create independent groups.
+        """
+        # Check for sequential ordering markers first
+        seq_parts = _SEQUENTIAL_PATTERN.split(request)
+        if len(seq_parts) > 1:
+            return self._build_subtasks(seq_parts, sequential=True)
+
+        # Check for explicit parallel markers
+        par_parts = _PARALLEL_PATTERN.split(request)
+        if len(par_parts) > 1:
+            return self._build_subtasks(par_parts, sequential=False)
+
+        # Fall back to splitting on plain "and" (parallel by default)
+        and_parts = re.split(r"\s+and\s+", request, flags=re.IGNORECASE)
+        if len(and_parts) > 1:
+            return self._build_subtasks(and_parts, sequential=False)
+
+        # Single task
+        return [self._make_subtask("subtask-1", request.strip() or request)]
+
+    def _build_subtasks(self, parts: List[str], *, sequential: bool) -> List[SubTask]:
+        """Build subtask list from text parts.
+
+        Args:
+            parts: Text fragments representing individual tasks
+            sequential: If True, each task depends on the previous one
+        """
+        subtasks: List[SubTask] = []
+        for i, part in enumerate(parts):
+            part = part.strip()
+            if not part:
+                continue
+            st = self._make_subtask(f"subtask-{len(subtasks) + 1}", part)
+            if sequential and subtasks:
+                st.dependencies.append(subtasks[-1].id)
+            subtasks.append(st)
+        return subtasks or [self._make_subtask("subtask-1", "Analyse request")]
+
+    def _make_subtask(self, task_id: str, description: str) -> SubTask:
+        """Construct a SubTask, inferring priority and effort from keywords."""
+        lower = description.lower()
+
+        # Priority
+        if any(w in lower for w in _CRITICAL_WORDS):
+            priority = TaskPriority.CRITICAL
+        elif any(w in lower for w in _HIGH_PRIO_WORDS):
+            priority = TaskPriority.HIGH
+        else:
+            priority = TaskPriority.MEDIUM
+
+        # Effort
+        if any(w in lower for w in _HIGH_EFFORT_WORDS):
+            effort = 2.0
+        elif any(w in lower for w in _LOW_EFFORT_WORDS):
+            effort = 0.5
+        else:
+            effort = 1.0
+
+        return SubTask(
+            id=task_id,
+            description=description,
+            priority=priority,
+            estimated_effort=effort,
+        )
+
+    async def _identify_dependencies(self, subtasks: List[SubTask]) -> None:
+        """Heuristic dependency analysis between subtasks.
+
+        ``_decompose`` creates a linear dependency chain by default.
+        This method clears dependencies between pairs of tasks whose
+        descriptions suggest they are genuinely independent — i.e. no
+        explicit ordering language and both match independence patterns.
+
+        Sequential tasks already have dependencies set by ``_decompose``.
+        An LLM-assisted Phase 2 can be wired in future when a router is
+        available.
+        """
+        if len(subtasks) < 2:
+            return
+
+        for i, task in enumerate(subtasks):
+            if i == 0:
+                continue
+
+            desc_lower = task.description.lower()
+            has_explicit_dep = any(p.search(desc_lower) for p in _DEPENDENCY_PATTERNS)
+            if has_explicit_dep:
+                continue  # Keep the sequential dependency
+
+            is_independent_type = any(p.search(desc_lower) for p in _INDEPENDENT_TASK_PATTERNS)
+            if not is_independent_type:
+                continue
+
+            prev = subtasks[i - 1]
+            prev_lower = prev.description.lower()
+            prev_is_independent = any(p.search(prev_lower) for p in _INDEPENDENT_TASK_PATTERNS)
+            if prev_is_independent:
+                # Both tasks are independently typed — allow parallel execution
+                task.dependencies = [
+                    d for d in task.dependencies if d != prev.id
+                ]
+                logger.debug(
+                    "TaskPlanner: cleared dependency %s → %s "
+                    "(both tasks appear independent)",
+                    prev.id,
+                    task.id,
+                )
+
+    def _find_parallel_groups(self, subtasks: List[SubTask]) -> List[List[str]]:
+        """Find subtasks that can run in parallel using topological levels.
+
+        Performs a level-order topological sort: tasks at level 0 have no
+        dependencies, tasks at level 1 depend only on level-0 tasks, etc.
+        Tasks within the same level can execute concurrently.
+
+        Args:
+            subtasks: All subtasks in the plan
+
+        Returns:
+            List of groups (each group is a list of subtask IDs that can
+            run concurrently).
+        """
+        if not subtasks:
+            return []
+
+        remaining: Dict[str, SubTask] = {s.id: s for s in subtasks}
+        completed: Set[str] = set()
+        groups: List[List[str]] = []
+
+        while remaining:
+            ready = [
+                sid
+                for sid, s in remaining.items()
+                if all(dep in completed for dep in s.dependencies)
+            ]
+
+            if not ready:
+                # Cycle or unresolvable — dump remainder into one group
+                groups.append(list(remaining.keys()))
+                break
+
+            groups.append(ready)
+            for sid in ready:
+                completed.add(sid)
+                del remaining[sid]
+
+        return groups

apsimo/intelligence/components/tool_learner.py

@@ -0,0 +1,217 @@
+"""Tool Learner — learn user's preferred tools for different tasks.
+
+Tracks:
+    - Which tools are used for which task types
+    - Success rates per tool
+    - User satisfaction signals (explicit + implicit)
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ToolUsage:
+    """Record of a tool being used for a task.
+
+    Attributes:
+        tool_name: Name of the tool used
+        task_type: Category of task the tool was applied to
+        success: Whether the tool usage succeeded
+        user_feedback: Optional explicit feedback ("helpful", "not_helpful", None)
+        timestamp: When the usage occurred
+    """
+
+    tool_name: str
+    task_type: str
+    success: bool
+    user_feedback: Optional[str] = None
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class ToolPreference:
+    """Learned preference for a tool on a task type.
+
+    Attributes:
+        tool_name: Name of the preferred tool
+        task_type: Task category this preference applies to
+        success_rate: Running success rate (0-1)
+        usage_count: Total number of times this tool was used for this task type
+        last_used: Most recent usage timestamp
+        user_rating: Recency-weighted user satisfaction score (0-1)
+    """
+
+    tool_name: str
+    task_type: str
+    success_rate: float
+    usage_count: int
+    last_used: datetime
+    user_rating: float
+
+
+class ToolLearner:
+    """Learn and apply tool preferences from usage patterns.
+
+    Maintains in-memory preference records per task type, updated on
+    each recorded usage. Preferred tool selection blends success rate
+    (60%) with user rating (40%).
+
+    Args:
+        graph_client: Colony graph client for persistent storage
+    """
+
+    def __init__(self, graph_client: Any) -> None:
+        self.graph = graph_client
+        self._preferences: Dict[str, List[ToolPreference]] = {}
+
+    async def record_usage(self, usage: ToolUsage) -> None:
+        """Record a tool usage event and update preferences.
+
+        Args:
+            usage: The tool usage to record
+        """
+        key = usage.task_type
+        if key not in self._preferences:
+            self._preferences[key] = []
+
+        # Find or create preference record
+        pref = next(
+            (p for p in self._preferences[key] if p.tool_name == usage.tool_name),
+            None,
+        )
+
+        if pref:
+            old_count = pref.usage_count
+            pref.usage_count += 1
+            pref.success_rate = (
+                (pref.success_rate * old_count + (1.0 if usage.success else 0.0))
+                / pref.usage_count
+            )
+            pref.last_used = usage.timestamp
+        else:
+            self._preferences[key].append(
+                ToolPreference(
+                    tool_name=usage.tool_name,
+                    task_type=usage.task_type,
+                    success_rate=1.0 if usage.success else 0.0,
+                    usage_count=1,
+                    last_used=usage.timestamp,
+                    user_rating=0.5,
+                )
+            )
+
+        logger.debug(
+            "Recorded tool usage: %s for %s (success=%s)",
+            usage.tool_name,
+            usage.task_type,
+            usage.success,
+        )
+
+    async def get_preferred_tool(self, task_type: str) -> Optional[str]:
+        """Get the preferred tool for a task type.
+
+        Selection blends success rate (60%) with user rating (40%).
+
+        Args:
+            task_type: The task category to find a tool for
+
+        Returns:
+            Tool name or None if no preferences exist
+        """
+        if task_type not in self._preferences:
+            return None
+
+        prefs = self._preferences[task_type]
+        if not prefs:
+            return None
+
+        sorted_prefs = sorted(
+            prefs,
+            key=lambda p: (p.success_rate * 0.6 + p.user_rating * 0.4),
+            reverse=True,
+        )
+
+        return sorted_prefs[0].tool_name
+
+    async def get_all_preferences(self, task_type: str) -> List[ToolPreference]:
+        """Get all tool preferences for a task type, sorted by score.
+
+        Args:
+            task_type: The task category to query
+
+        Returns:
+            Sorted list of preferences (best first)
+        """
+        prefs = self._preferences.get(task_type, [])
+        return sorted(
+            prefs,
+            key=lambda p: (p.success_rate * 0.6 + p.user_rating * 0.4),
+            reverse=True,
+        )
+
+    async def update_user_rating(
+        self,
+        tool_name: str,
+        task_type: str,
+        rating: float,
+    ) -> None:
+        """Update the user satisfaction rating for a tool on a task type.
+
+        Uses an exponential moving average (alpha=0.3) so recent feedback
+        is weighted more heavily without fully discarding history.
+
+        Args:
+            tool_name: Name of the tool to rate
+            task_type: Task category this rating applies to
+            rating: New rating value (0-1)
+        """
+        rating = max(0.0, min(1.0, rating))
+        prefs = self._preferences.get(task_type, [])
+        pref = next((p for p in prefs if p.tool_name == tool_name), None)
+        if pref is None:
+            logger.warning("No preference record for %s on %s", tool_name, task_type)
+            return
+        alpha = 0.3
+        pref.user_rating = alpha * rating + (1 - alpha) * pref.user_rating
+        logger.debug(
+            "Updated user rating for %s on %s: %.2f",
+            tool_name,
+            task_type,
+            pref.user_rating,
+        )
+
+    async def get_usage_stats(self, task_type: str) -> Dict[str, Any]:
+        """Return summary statistics for all tools used on a task type.
+
+        Args:
+            task_type: The task category to summarise
+
+        Returns:
+            Dict with 'total_tools', 'total_usages', 'best_tool', and per-tool stats.
+        """
+        prefs = self._preferences.get(task_type, [])
+        if not prefs:
+            return {"total_tools": 0, "total_usages": 0, "best_tool": None, "tools": []}
+
+        best = await self.get_preferred_tool(task_type)
+        return {
+            "total_tools": len(prefs),
+            "total_usages": sum(p.usage_count for p in prefs),
+            "best_tool": best,
+            "tools": [
+                {
+                    "name": p.tool_name,
+                    "usage_count": p.usage_count,
+                    "success_rate": p.success_rate,
+                    "user_rating": p.user_rating,
+                    "score": p.success_rate * 0.6 + p.user_rating * 0.4,
+                }
+                for p in prefs
+            ],
+        }

apsimo/intelligence/graph/__init__.py

@@ -0,0 +1,79 @@
+"""Colony Graph Memory System.
+
+Public API:
+    - ``ColonyGraph`` — async Neo4j client for memory storage & recall
+    - ``GraphConfig``  — connection settings dataclass
+    - ``run_migrations`` — idempotent schema setup
+    - Schema types (``Owner``, ``Person``, ``Memory``, ``Entity``, etc.)
+    - ``EdgeType`` / ``TrustTier`` enums
+    - Cypher query constants in ``queries``
+"""
+
+from .client import ColonyGraph, GraphConfig
+from .migrations import run_migrations, SCHEMA_V1
+from .queries import (
+    COMPUTE_RELATIONSHIP_SCORES,
+    DECAY_ALL,
+    ENSURE_OWNER,
+    FIND_NEGLECTED_RELATIONSHIPS,
+    FIND_SHARED_ENTITIES,
+    GET_PERSON_WITH_SIGNALS,
+    LINK_PERSON_TO_OWNER,
+    PRUNE_WEAK_MEMORIES,
+    RECALL_BY_ENTITY,
+    RECALL_BY_TYPE,
+    RECORD_SCORE_CHANGE,
+    STORE_MEMORY,
+    STORE_SIGNAL,
+    TOUCH_MEMORY,
+    TRAVERSE_MEMORY_CONNECTIONS,
+)
+from .schema import (
+    Context,
+    EdgeType,
+    Entity,
+    Memory,
+    Owner,
+    Person,
+    Prediction,
+    ScoreEvent,
+    Signal,
+    TrustTier,
+)
+
+__all__ = [
+    # Client
+    "ColonyGraph",
+    "GraphConfig",
+    # Migrations
+    "run_migrations",
+    "SCHEMA_V1",
+    # Schema — nodes
+    "Owner",
+    "Person",
+    "Memory",
+    "Entity",
+    "Signal",
+    "Context",
+    "ScoreEvent",
+    "Prediction",
+    # Schema — enums
+    "EdgeType",
+    "TrustTier",
+    # Query constants
+    "STORE_MEMORY",
+    "RECALL_BY_ENTITY",
+    "RECALL_BY_TYPE",
+    "DECAY_ALL",
+    "PRUNE_WEAK_MEMORIES",
+    "TOUCH_MEMORY",
+    "GET_PERSON_WITH_SIGNALS",
+    "STORE_SIGNAL",
+    "COMPUTE_RELATIONSHIP_SCORES",
+    "RECORD_SCORE_CHANGE",
+    "FIND_NEGLECTED_RELATIONSHIPS",
+    "TRAVERSE_MEMORY_CONNECTIONS",
+    "FIND_SHARED_ENTITIES",
+    "ENSURE_OWNER",
+    "LINK_PERSON_TO_OWNER",
+]