apsimo 1.3.0__py3-none-any.whl

apsimo/goals/priority.py

@@ -0,0 +1,270 @@
+"""Goal Priority Scoring and Progress Tracking.
+
+GoalPriorityScorer: composite priority score with urgency decay, importance,
+    user preferences, blocking bonus, and age decay.
+
+GoalProgressTracker: weighted completion fraction and completion time estimation.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from apsimo.goals.models import Goal, GoalDAG, GoalPriority, SubtaskStatus
+
+
+@dataclass
+class PriorityScore:
+    """Composite priority score with component breakdown."""
+    total: float                    # 0.0–100.0 final score
+    urgency: float                  # Deadline proximity component
+    importance: float               # User-stated importance component
+    preference_bonus: float         # Learned preference modifier
+    blocking_penalty: float         # Bonus if goal is blocking other goals
+    age_decay: float                # Score decay for stale goals
+    breakdown: Dict[str, float] = field(default_factory=dict)
+
+
+@dataclass
+class UserPreferenceProfile:
+    """Learned user preferences influencing goal prioritization.
+
+    Attributes:
+        domain_weights:       Per-domain priority multipliers (e.g., "health": 1.3).
+        preferred_hours:      Hours of day when the user prefers work to execute.
+        completion_patterns:  Historical goal completion rates by category.
+        avoidance_domains:    Domains the user tends to defer or abandon.
+    """
+    domain_weights: Dict[str, float] = field(default_factory=dict)
+    preferred_hours: List[int] = field(default_factory=list)
+    completion_patterns: Dict[str, float] = field(default_factory=dict)
+    avoidance_domains: List[str] = field(default_factory=list)
+
+    # EMA smoothing factor for learning (α = 0.3 → weights recent behavior ~3× more)
+    ema_alpha: float = 0.3
+
+    def update_domain_completion(self, domain: str, success: bool) -> None:
+        """Update completion pattern for a domain using EMA."""
+        value = 1.0 if success else 0.0
+        if domain in self.completion_patterns:
+            old = self.completion_patterns[domain]
+            self.completion_patterns[domain] = self.ema_alpha * value + (1 - self.ema_alpha) * old
+        else:
+            self.completion_patterns[domain] = value
+
+    def update_domain_weight(self, domain: str, delta: float) -> None:
+        """Adjust domain weight using EMA."""
+        current = self.domain_weights.get(domain, 1.0)
+        new_weight = self.ema_alpha * (current + delta) + (1 - self.ema_alpha) * current
+        self.domain_weights[domain] = max(0.1, min(3.0, new_weight))
+
+
+def _deadline_urgency(goal: Goal) -> float:
+    """Compute urgency in [0, 1] based on deadline proximity.
+
+    urgency(t) = 1 / (1 + exp(-k * (t_remaining_fraction - 0.5)))
+    where k = 10 (steepness constant)
+    """
+    if goal.deadline is None:
+        return 0.0
+
+    now = datetime.now(timezone.utc)
+    if now >= goal.deadline:
+        return 1.0
+
+    total_window = (goal.deadline - goal.created_at).total_seconds()
+    if total_window <= 0:
+        return 1.0
+
+    remaining = (goal.deadline - now).total_seconds()
+    t_remaining_fraction = remaining / total_window
+
+    k = 10.0
+    urgency = 1.0 / (1.0 + math.exp(-k * (t_remaining_fraction - 0.5)))
+    # Invert so that low remaining fraction = high urgency
+    return round(1.0 - urgency, 4)
+
+
+def _base_importance(goal: Goal) -> float:
+    """Derive importance from goal's explicit priority (normalised to [0, 1])."""
+    return goal.priority.value / 100.0
+
+
+def _preference_modifier(goal: Goal, preferences: UserPreferenceProfile) -> float:
+    """Compute preference bonus in [0, 1] from user preference profile."""
+    # Use goal tags to determine domain
+    domain = goal.tags.get("domain", "")
+    if not domain:
+        return 0.0
+
+    weight = preferences.domain_weights.get(domain, 1.0)
+    # Map weight (typically 0.1–3.0) to a bonus in [0, 1]
+    bonus = min(1.0, max(0.0, (weight - 1.0) / 2.0))
+    return round(bonus, 4)
+
+
+def _blocking_bonus(goal: Goal, all_goals: Optional[List[Goal]] = None) -> float:
+    """Return 1.0 if this goal is a dependency (parent) for other active goals."""
+    if all_goals is None:
+        return 0.0
+    for other in all_goals:
+        if other.parent_goal_id == goal.goal_id and not other.is_terminal():
+            return 1.0
+    return 0.0
+
+
+def _age_decay(goal: Goal) -> float:
+    """Compute staleness penalty in [0, 1] for old untouched goals."""
+    age = goal.age_hours()
+    # Penalty grows logarithmically; at 168 hours (1 week) = ~0.5
+    if age < 1:
+        return 0.0
+    return round(min(1.0, math.log(age) / math.log(168.0)), 4)
+
+
+class GoalPriorityScorer:
+    """Compute composite priority scores for goals."""
+
+    WEIGHTS = {
+        "urgency":          0.35,
+        "importance":       0.30,
+        "preference_bonus": 0.15,
+        "blocking":         0.10,
+        "age_decay":       -0.10,  # Negative — reduces priority for very old stale goals
+    }
+
+    def score(
+        self,
+        goal: Goal,
+        preferences: Optional[UserPreferenceProfile] = None,
+        all_goals: Optional[List[Goal]] = None,
+    ) -> PriorityScore:
+        """Compute a composite priority score for a goal.
+
+        Components:
+        - urgency:    deadline_urgency(goal) — 0.0 if no deadline, 1.0 if overdue
+        - importance: base_importance(goal) — from user tags, source, explicit priority
+        - preference: preference_modifier(goal, preferences) — domain preference bonus
+        - blocking:   is_blocking_bonus(goal) — if other goals depend on this one
+        - age_decay:  stale_penalty(goal) — reduces priority for untouched old goals
+        """
+        prefs = preferences or UserPreferenceProfile()
+
+        urgency   = _deadline_urgency(goal)
+        importance = _base_importance(goal)
+        preference = _preference_modifier(goal, prefs)
+        blocking  = _blocking_bonus(goal, all_goals)
+        decay     = _age_decay(goal)
+
+        components = {
+            "urgency": urgency,
+            "importance": importance,
+            "preference_bonus": preference,
+            "blocking": blocking,
+            "age_decay": decay,
+        }
+
+        total = 100.0 * (
+            self.WEIGHTS["urgency"]          * urgency
+            + self.WEIGHTS["importance"]      * importance
+            + self.WEIGHTS["preference_bonus"] * preference
+            + self.WEIGHTS["blocking"]        * blocking
+            + self.WEIGHTS["age_decay"]       * decay   # this is negative
+        )
+        total = max(0.0, min(100.0, total))
+
+        return PriorityScore(
+            total=round(total, 2),
+            urgency=urgency,
+            importance=importance,
+            preference_bonus=preference,
+            blocking_penalty=blocking,
+            age_decay=decay,
+            breakdown=components,
+        )
+
+    def rank_goals(
+        self,
+        goals: List[Goal],
+        preferences: Optional[UserPreferenceProfile] = None,
+    ) -> List[Goal]:
+        """Return goals sorted by descending priority score."""
+        scored = [(g, self.score(g, preferences, goals).total) for g in goals]
+        scored.sort(key=lambda x: x[1], reverse=True)
+        return [g for g, _ in scored]
+
+
+class GoalProgressTracker:
+    """Track and report goal progress."""
+
+    def update_progress(self, goal_id: str, dag: GoalDAG) -> float:
+        """Recompute progress fraction from subtask statuses.
+
+        Weights subtasks on the critical path more heavily (2× weight).
+
+        Returns updated progress_pct (0.0–1.0).
+        """
+        total_weight = 0.0
+        done_weight = 0.0
+
+        for s in dag.subtasks.values():
+            weight = 2.0 if s.is_critical_path else 1.0
+            total_weight += weight
+            if s.status in {SubtaskStatus.COMPLETED, SubtaskStatus.SKIPPED}:
+                done_weight += weight
+
+        return done_weight / total_weight if total_weight > 0 else 0.0
+
+    def estimate_completion(
+        self,
+        goal: Goal,
+        dag: GoalDAG,
+        historical_perf: Optional[Dict[str, float]] = None,
+    ) -> Optional[datetime]:
+        """Estimate completion time based on critical path remaining work.
+
+        Uses three-point estimation:
+          estimated_remaining = sum(subtask.estimated_hours * perf_factor)
+          for remaining critical path subtasks.
+
+        Returns estimated completion datetime, or None if not estimable.
+        """
+        if not dag.critical_path:
+            return None
+
+        perf = historical_perf or {}
+        remaining_hours = 0.0
+        for sid in dag.critical_path:
+            subtask = dag.subtasks.get(sid)
+            if subtask is None:
+                continue
+            if subtask.status in {SubtaskStatus.COMPLETED, SubtaskStatus.SKIPPED}:
+                continue
+            est = subtask.estimated_hours if subtask.estimated_hours is not None else 1.0
+            pf = perf.get(subtask.job_type, 1.0)
+            remaining_hours += est * pf
+
+        if remaining_hours <= 0:
+            return None
+
+        from datetime import timedelta
+        return datetime.now(timezone.utc) + timedelta(hours=remaining_hours)
+
+    def check_blocked(self, goal: "Goal", dag: GoalDAG) -> Optional[str]:
+        """Return a reason string if the goal appears blocked, else None."""
+        ready = dag.ready_subtasks()
+        if ready:
+            return None  # Work available
+
+        # Check if there are non-terminal subtasks with unmet deps
+        for s in dag.subtasks.values():
+            if s.status in {SubtaskStatus.PENDING, SubtaskStatus.BLOCKED}:
+                # All deps failed?
+                for dep_id in s.depends_on:
+                    dep = dag.subtasks.get(dep_id)
+                    if dep and dep.status == SubtaskStatus.FAILED:
+                        return f"Subtask {s.subtask_id} blocked by failed dependency {dep_id}"
+        return None

apsimo/goals/queue_bridge.py

@@ -0,0 +1,149 @@
+"""GoalQueueBridge — integrate Goal Engine with the distributed task queue.
+
+Converts Subtask nodes into task queue Jobs, dispatches ready subtasks,
+and processes job results to update goal/subtask state.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Dict, List, Optional, Protocol
+
+from apsimo.goals.models import (
+    Goal,
+    GoalDAG,
+    GoalPriority,
+    GoalStatus,
+    Subtask,
+    SubtaskStatus,
+)
+from apsimo.task_queue.models import (
+    Job,
+    JobCapabilityRequirement,
+    JobPriority,
+    JobResult,
+    JobType,
+)
+
+logger = logging.getLogger(__name__)
+
+# Priority mapping: GoalPriority → JobPriority
+_PRIORITY_MAP: Dict[int, JobPriority] = {
+    GoalPriority.BACKGROUND: JobPriority.BACKGROUND,
+    GoalPriority.LOW:        JobPriority.LOW,
+    GoalPriority.NORMAL:     JobPriority.NORMAL,
+    GoalPriority.HIGH:       JobPriority.HIGH,
+    GoalPriority.CRITICAL:   JobPriority.CRITICAL,
+}
+
+
+def _map_priority(goal_priority: GoalPriority) -> JobPriority:
+    return _PRIORITY_MAP.get(goal_priority.value, JobPriority.NORMAL)
+
+
+def _job_type_from_string(job_type: str) -> JobType:
+    """Convert subtask job_type string to JobType enum (with fallback)."""
+    try:
+        return JobType(job_type)
+    except ValueError:
+        return JobType.CUSTOM
+
+
+class QueueBackend(Protocol):
+    """Minimal interface expected from the task queue."""
+
+    def post(self, job: Job) -> str:
+        """Post a job and return its job_id."""
+        ...
+
+
+class InMemoryQueueBackend:
+    """Simple in-memory queue backend for testing without a real queue."""
+
+    def __init__(self) -> None:
+        self._jobs: Dict[str, Job] = {}
+        self._posted_order: List[str] = []
+
+    def post(self, job: Job) -> str:
+        self._jobs[job.job_id] = job
+        self._posted_order.append(job.job_id)
+        logger.debug("InMemoryQueue: posted job %s (type=%s)", job.job_id, job.job_type)
+        return job.job_id
+
+    def get_job(self, job_id: str) -> Optional[Job]:
+        return self._jobs.get(job_id)
+
+    def list_jobs(self) -> List[Job]:
+        return [self._jobs[jid] for jid in self._posted_order if jid in self._jobs]
+
+
+class GoalQueueBridge:
+    """Bridge between the Goal Engine and the distributed task queue."""
+
+    def __init__(self, queue: Optional[QueueBackend] = None) -> None:
+        # A missing production binding must not silently become a test queue.
+        self._queue = queue
+
+    @property
+    def available(self) -> bool:
+        """Whether a caller supplied a backend, not proof of worker liveness."""
+        return self._queue is not None
+
+    def subtask_to_job(self, goal: Goal, subtask: Subtask) -> Job:
+        """Convert a ready Subtask into a task queue Job.
+
+        Priority mapping:
+          GoalPriority.CRITICAL → JobPriority.CRITICAL
+          GoalPriority.HIGH     → JobPriority.HIGH
+          GoalPriority.NORMAL   → JobPriority.NORMAL
+          GoalPriority.LOW      → JobPriority.LOW
+          GoalPriority.BACKGROUND → JobPriority.BACKGROUND
+
+        Deadline: goal.deadline is forwarded if set.
+        """
+        return Job(
+            job_type=_job_type_from_string(subtask.job_type),
+            payload={
+                "goal_id":    goal.goal_id,
+                "subtask_id": subtask.subtask_id,
+                **subtask.payload,
+            },
+            priority=_map_priority(goal.priority),
+            capabilities=[
+                JobCapabilityRequirement(name=cap)
+                for cap in subtask.capabilities
+            ],
+            deadline=goal.deadline,
+            tags={
+                "goal_id":    goal.goal_id,
+                "goal_title": goal.title[:64],
+            },
+        )
+
+    def dispatch_ready_subtasks(self, goal: Goal, dag: GoalDAG) -> int:
+        """Dispatch all ready subtasks to the task queue.
+
+        Returns the number of jobs posted.
+        """
+        if self._queue is None:
+            return 0
+        count = 0
+        for subtask in dag.ready_subtasks():
+            job = self.subtask_to_job(goal, subtask)
+            job_id = self._queue.post(job)
+            subtask.job_id = job_id
+            subtask.status = SubtaskStatus.DISPATCHED
+            count += 1
+            logger.info(
+                "Dispatched subtask %s (job_id=%s) for goal %s",
+                subtask.subtask_id, job_id, goal.goal_id,
+            )
+        return count
+
+    def cancel_all_jobs(self, dag: GoalDAG) -> None:
+        """Cancel all dispatched/running jobs in the DAG (best-effort)."""
+        for subtask in dag.subtasks.values():
+            if subtask.status in {SubtaskStatus.DISPATCHED, SubtaskStatus.RUNNING}:
+                subtask.status = SubtaskStatus.FAILED
+                subtask.error = "Job cancelled: goal abandoned"
+                logger.info("Cancelled job for subtask %s", subtask.subtask_id)