runtime-memory 3.0.0__py3-none-any.whl

runtime_memory/tasks/outcomes.py

@@ -0,0 +1,320 @@
+"""Automatic outcome capture for Beads task integration.
+
+This module is THE key feature of Beads integration. It automatically
+records outcomes for memories when tasks complete, closing the feedback
+loop without requiring manual /outcome calls.
+
+Flow:
+    Task "bd-a3f8" marked "done"
+        → Find all memories linked to this task
+        → Record "worked" outcome for each memory
+        → Score boost (+0.2) applied automatically
+        → Bad advice naturally sinks, good advice rises
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from runtime_memory.core.models import Outcome
+from runtime_memory.tasks.linking import TaskMemoryLinker
+from runtime_memory.tasks.models import (
+    CANCELLED_TASK_PENALTY,
+    TASK_STATUS_TO_OUTCOME,
+    BeadsSyncResult,
+    BeadsTask,
+    BeadsTaskStatus,
+)
+from runtime_memory.tasks.parser import BeadsParser
+
+if TYPE_CHECKING:
+    from runtime_memory.core.engine import MemoryEngine
+
+logger = logging.getLogger(__name__)
+
+
+class OutcomeCapture:
+    """Automatically captures outcomes when Beads tasks complete.
+
+    This class monitors task status and records outcomes for linked
+    memories when tasks reach terminal states (done, cancelled).
+
+    Example:
+        >>> capture = OutcomeCapture(engine, linker, parser)
+        >>> result = await capture.on_task_completed("bd-a3f8")
+        >>> print(f"Updated {result} memories")
+    """
+
+    def __init__(
+        self,
+        engine: MemoryEngine,
+        linker: TaskMemoryLinker,
+        parser: BeadsParser | None = None,
+        auto_outcome_enabled: bool = True,
+        outcome_on_cancel: bool = False,
+        min_confidence_for_outcome: float = 0.0,
+    ) -> None:
+        """Initialize the outcome capture system.
+
+        Args:
+            engine: The Runtime Memory engine for recording outcomes.
+            linker: The task-memory linker for finding linked memories.
+            parser: Optional Beads parser for task status lookups.
+            auto_outcome_enabled: Whether to automatically record outcomes.
+            outcome_on_cancel: Whether to record "failed" on cancelled tasks.
+            min_confidence_for_outcome: Minimum memory confidence to auto-record.
+        """
+        self._engine = engine
+        self._linker = linker
+        self._parser = parser
+        self.auto_outcome_enabled = auto_outcome_enabled
+        self.outcome_on_cancel = outcome_on_cancel
+        self.min_confidence_for_outcome = min_confidence_for_outcome
+
+    async def on_task_completed(self, task_id: str) -> int:
+        """Handle a task being marked as completed (done).
+
+        Records "worked" outcome for all unresolved linked memories.
+
+        Args:
+            task_id: The Beads task ID that was completed.
+
+        Returns:
+            Number of memories that had outcomes recorded.
+        """
+        if not self.auto_outcome_enabled:
+            logger.debug(f"Auto-outcome disabled, skipping task {task_id}")
+            return 0
+
+        return await self._record_outcome_for_task(task_id, Outcome.WORKED)
+
+    async def on_task_failed(self, task_id: str) -> int:
+        """Handle a task being marked as failed/cancelled.
+
+        Records "failed" outcome for all unresolved linked memories
+        (if outcome_on_cancel is enabled).
+
+        Args:
+            task_id: The Beads task ID that failed.
+
+        Returns:
+            Number of memories that had outcomes recorded.
+        """
+        if not self.auto_outcome_enabled:
+            logger.debug(f"Auto-outcome disabled, skipping task {task_id}")
+            return 0
+
+        if not self.outcome_on_cancel:
+            logger.debug(f"Outcome on cancel disabled, skipping task {task_id}")
+            return 0
+
+        return await self._record_outcome_for_task(task_id, Outcome.FAILED)
+
+    async def on_task_blocked(self, task_id: str) -> int:
+        """Handle a task being marked as blocked.
+
+        Records "partial" outcome for all unresolved linked memories.
+        This indicates the advice was on the right track but couldn't
+        fully solve the problem.
+
+        Args:
+            task_id: The Beads task ID that was blocked.
+
+        Returns:
+            Number of memories that had outcomes recorded.
+        """
+        if not self.auto_outcome_enabled:
+            logger.debug(f"Auto-outcome disabled, skipping task {task_id}")
+            return 0
+
+        return await self._record_outcome_for_task(task_id, Outcome.PARTIAL)
+
+    async def _record_outcome_for_task(
+        self,
+        task_id: str,
+        outcome: Outcome,
+    ) -> int:
+        """Record outcome for all unresolved memories linked to a task.
+
+        Args:
+            task_id: The Beads task ID.
+            outcome: The outcome to record.
+
+        Returns:
+            Number of memories updated.
+        """
+        # Get unresolved links (memories without outcomes yet)
+        links = await self._linker.get_unresolved_links(task_id)
+
+        if not links:
+            logger.debug(f"No unresolved links for task {task_id}")
+            return 0
+
+        # Filter by minimum confidence if specified
+        memory_ids = []
+        for link in links:
+            if self.min_confidence_for_outcome > 0:
+                try:
+                    memory = await self._engine.get(link.memory_id)
+                    if memory.confidence < self.min_confidence_for_outcome:
+                        logger.debug(
+                            f"Skipping memory {link.memory_id} "
+                            f"(confidence {memory.confidence} < {self.min_confidence_for_outcome})"
+                        )
+                        continue
+                except Exception:
+                    # Memory might not exist anymore, skip it
+                    continue
+            memory_ids.append(link.memory_id)
+
+        if not memory_ids:
+            logger.debug(f"No memories passed confidence filter for task {task_id}")
+            return 0
+
+        # Record outcomes in the engine
+        try:
+            await self._engine.record_outcome(memory_ids, outcome)
+            logger.info(
+                f"Recorded {outcome.value} for {len(memory_ids)} memories "
+                f"linked to task {task_id}"
+            )
+        except Exception as e:
+            logger.error(f"Failed to record outcomes for task {task_id}: {e}")
+            return 0
+
+        # Mark links as having outcomes recorded
+        await self._linker.record_task_outcome(task_id, outcome.value)
+
+        return len(memory_ids)
+
+    async def process_task_status_change(
+        self,
+        task_id: str,
+        old_status: BeadsTaskStatus,
+        new_status: BeadsTaskStatus,
+    ) -> int:
+        """Process a task status change and record outcomes if appropriate.
+
+        Args:
+            task_id: The Beads task ID.
+            old_status: Previous task status.
+            new_status: New task status.
+
+        Returns:
+            Number of memories that had outcomes recorded.
+        """
+        # Only process transitions to terminal states
+        if new_status == BeadsTaskStatus.DONE:
+            return await self.on_task_completed(task_id)
+        elif new_status == BeadsTaskStatus.CANCELLED:
+            return await self.on_task_failed(task_id)
+        elif new_status == BeadsTaskStatus.BLOCKED:
+            return await self.on_task_blocked(task_id)
+
+        return 0
+
+    async def sync_completed_tasks(self) -> BeadsSyncResult:
+        """Sync outcomes for all completed tasks that have unresolved links.
+
+        Scans all completed tasks in Beads and records outcomes for any
+        that have memories without recorded outcomes.
+
+        Returns:
+            BeadsSyncResult with sync statistics.
+        """
+        result = BeadsSyncResult()
+
+        if not self._parser:
+            result.errors.append("No parser available for task sync")
+            return result
+
+        if not self._parser.is_available():
+            result.warnings.append("Beads directory not found")
+            return result
+
+        # Get all completed tasks
+        completed_tasks = self._parser.get_completed_tasks()
+        result.tasks_found = len(completed_tasks)
+
+        for task in completed_tasks:
+            try:
+                # Check if task has unresolved links
+                unresolved = await self._linker.get_unresolved_links(task.id)
+                if not unresolved:
+                    continue
+
+                # Record outcome based on task status
+                if task.status == BeadsTaskStatus.DONE:
+                    count = await self.on_task_completed(task.id)
+                elif task.status == BeadsTaskStatus.CANCELLED:
+                    count = await self.on_task_failed(task.id)
+                else:
+                    count = 0
+
+                result.outcomes_recorded += count
+                result.tasks_synced += 1
+
+            except Exception as e:
+                result.errors.append(f"Error processing task {task.id}: {e}")
+
+        return result
+
+    async def check_and_record(self, task_id: str) -> int:
+        """Check task status and record outcome if completed.
+
+        Convenience method that looks up the task status and calls
+        the appropriate outcome handler.
+
+        Args:
+            task_id: The Beads task ID to check.
+
+        Returns:
+            Number of memories that had outcomes recorded.
+        """
+        if not self._parser:
+            logger.warning("No parser available, cannot check task status")
+            return 0
+
+        task = self._parser.get_task(task_id)
+        if not task:
+            logger.warning(f"Task {task_id} not found")
+            return 0
+
+        if task.status == BeadsTaskStatus.DONE:
+            return await self.on_task_completed(task_id)
+        elif task.status == BeadsTaskStatus.CANCELLED:
+            return await self.on_task_failed(task_id)
+        elif task.status == BeadsTaskStatus.BLOCKED:
+            return await self.on_task_blocked(task_id)
+
+        return 0
+
+
+async def auto_capture_outcome(
+    engine: MemoryEngine,
+    linker: TaskMemoryLinker,
+    task_id: str,
+    status: BeadsTaskStatus,
+) -> int:
+    """Convenience function to capture outcome for a task.
+
+    Args:
+        engine: The Runtime Memory engine.
+        linker: The task-memory linker.
+        task_id: The Beads task ID.
+        status: The task's new status.
+
+    Returns:
+        Number of memories that had outcomes recorded.
+    """
+    capture = OutcomeCapture(engine, linker)
+
+    if status == BeadsTaskStatus.DONE:
+        return await capture.on_task_completed(task_id)
+    elif status == BeadsTaskStatus.CANCELLED:
+        return await capture.on_task_failed(task_id)
+    elif status == BeadsTaskStatus.BLOCKED:
+        return await capture.on_task_blocked(task_id)
+
+    return 0

runtime_memory/tasks/parser.py

@@ -0,0 +1,305 @@
+"""Beads file parser for reading task data from .beads/ directory.
+
+This module handles:
+- Discovery of .beads/ directory
+- Parsing JSONL task files
+- Building task index with parent-child relationships
+- Graceful handling of malformed data
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from runtime_memory.tasks.models import BeadsTask, BeadsTaskStatus
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+logger = logging.getLogger(__name__)
+
+
+class BeadsDirectoryNotFoundError(Exception):
+    """Raised when .beads/ directory cannot be found."""
+
+    pass
+
+
+class BeadsParser:
+    """Parses Beads task data from .beads/ directory.
+
+    Supports:
+    - JSONL files (one JSON object per line)
+    - Directory discovery (walks up from current dir)
+    - Environment variable override ($BEADS_DIR)
+    - Caching of parsed tasks
+
+    Example:
+        >>> parser = BeadsParser()
+        >>> tasks = parser.list_tasks()
+        >>> ready = parser.get_ready_tasks()
+    """
+
+    def __init__(self, beads_dir: Path | str | None = None):
+        """Initialize the parser.
+
+        Args:
+            beads_dir: Explicit path to .beads/ directory.
+                       If None, will auto-discover.
+        """
+        self._beads_dir: Path | None = None
+        self._explicit_dir = Path(beads_dir) if beads_dir else None
+        self._task_cache: dict[str, BeadsTask] = {}
+        self._cache_valid = False
+
+    @property
+    def beads_dir(self) -> Path | None:
+        """Get the .beads/ directory path, discovering if needed."""
+        if self._beads_dir is None:
+            self._beads_dir = self._discover_beads_dir()
+        return self._beads_dir
+
+    def _discover_beads_dir(self) -> Path | None:
+        """Discover the .beads/ directory.
+
+        Search order:
+        1. Explicit path provided to constructor
+        2. $BEADS_DIR environment variable
+        3. Walk up from current directory
+
+        Returns:
+            Path to .beads/ directory or None if not found.
+        """
+        # 1. Explicit path
+        if self._explicit_dir:
+            if self._explicit_dir.is_dir():
+                logger.debug(f"Using explicit beads dir: {self._explicit_dir}")
+                return self._explicit_dir
+            logger.warning(f"Explicit beads dir not found: {self._explicit_dir}")
+            return None
+
+        # 2. Environment variable
+        env_dir = os.environ.get("BEADS_DIR")
+        if env_dir:
+            env_path = Path(env_dir)
+            if env_path.is_dir():
+                logger.debug(f"Using $BEADS_DIR: {env_path}")
+                return env_path
+            logger.warning(f"$BEADS_DIR not found: {env_path}")
+
+        # 3. Walk up from current directory
+        current = Path.cwd()
+        for parent in [current, *current.parents]:
+            beads_path = parent / ".beads"
+            if beads_path.is_dir():
+                logger.debug(f"Found .beads/ at: {beads_path}")
+                return beads_path
+
+        logger.debug("No .beads/ directory found")
+        return None
+
+    def is_available(self) -> bool:
+        """Check if Beads is available (directory exists)."""
+        return self.beads_dir is not None
+
+    def invalidate_cache(self) -> None:
+        """Invalidate the task cache, forcing a re-parse on next access."""
+        self._task_cache.clear()
+        self._cache_valid = False
+
+    def _ensure_cache(self) -> None:
+        """Ensure the task cache is populated."""
+        if self._cache_valid:
+            return
+
+        self._task_cache.clear()
+
+        if not self.beads_dir:
+            return
+
+        # Parse all JSONL files in .beads/
+        for task in self._parse_all_files():
+            self._task_cache[task.id] = task
+
+        self._cache_valid = True
+        logger.debug(f"Cached {len(self._task_cache)} tasks")
+
+    def _parse_all_files(self) -> Iterator[BeadsTask]:
+        """Parse all JSONL files in the .beads/ directory.
+
+        Yields:
+            BeadsTask objects for each valid task entry.
+        """
+        if not self.beads_dir:
+            return
+
+        # Find all .jsonl files
+        jsonl_files = list(self.beads_dir.glob("*.jsonl"))
+        logger.debug(f"Found {len(jsonl_files)} JSONL files")
+
+        for jsonl_file in jsonl_files:
+            yield from self._parse_jsonl_file(jsonl_file)
+
+    def _parse_jsonl_file(self, file_path: Path) -> Iterator[BeadsTask]:
+        """Parse a single JSONL file.
+
+        Args:
+            file_path: Path to the JSONL file.
+
+        Yields:
+            BeadsTask objects for each valid line.
+        """
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                for line_num, line in enumerate(f, 1):
+                    line = line.strip()
+                    if not line:
+                        continue
+
+                    try:
+                        data = json.loads(line)
+                        task = BeadsTask.from_dict(data)
+                        yield task
+                    except json.JSONDecodeError as e:
+                        logger.warning(
+                            f"Malformed JSON at {file_path}:{line_num}: {e}"
+                        )
+                    except (KeyError, ValueError) as e:
+                        logger.warning(
+                            f"Invalid task data at {file_path}:{line_num}: {e}"
+                        )
+        except OSError as e:
+            logger.error(f"Failed to read {file_path}: {e}")
+
+    def get_task(self, task_id: str) -> BeadsTask | None:
+        """Get a task by ID.
+
+        Args:
+            task_id: The task ID (e.g., "bd-a3f8").
+
+        Returns:
+            The task or None if not found.
+        """
+        self._ensure_cache()
+        return self._task_cache.get(task_id)
+
+    def list_tasks(
+        self,
+        status: BeadsTaskStatus | None = None,
+        parent_id: str | None = None,
+    ) -> list[BeadsTask]:
+        """List all tasks, optionally filtered.
+
+        Args:
+            status: Filter by status (e.g., IN_PROGRESS).
+            parent_id: Filter by parent task (for subtasks).
+
+        Returns:
+            List of matching tasks.
+        """
+        self._ensure_cache()
+
+        tasks = list(self._task_cache.values())
+
+        if status is not None:
+            tasks = [t for t in tasks if t.status == status]
+
+        if parent_id is not None:
+            tasks = [t for t in tasks if t.parent_id == parent_id]
+
+        return tasks
+
+    def get_ready_tasks(self) -> list[BeadsTask]:
+        """Get tasks that are ready to work on.
+
+        A task is ready if:
+        - Status is PENDING
+        - No unresolved dependencies
+
+        Returns:
+            List of ready tasks.
+        """
+        self._ensure_cache()
+
+        ready = []
+        for task in self._task_cache.values():
+            if task.status != BeadsTaskStatus.PENDING:
+                continue
+
+            # Check if all dependencies are done
+            deps_resolved = all(
+                self._task_cache.get(dep_id, BeadsTask(id=dep_id, title="")).status
+                == BeadsTaskStatus.DONE
+                for dep_id in task.dependencies
+            )
+
+            if deps_resolved:
+                ready.append(task)
+
+        return ready
+
+    def get_in_progress_tasks(self) -> list[BeadsTask]:
+        """Get tasks currently being worked on.
+
+        Returns:
+            List of in-progress tasks.
+        """
+        return self.list_tasks(status=BeadsTaskStatus.IN_PROGRESS)
+
+    def get_subtasks(self, parent_id: str) -> list[BeadsTask]:
+        """Get subtasks for a parent task.
+
+        Args:
+            parent_id: The parent task ID.
+
+        Returns:
+            List of subtasks.
+        """
+        return self.list_tasks(parent_id=parent_id)
+
+    def get_task_hierarchy(self, task_id: str) -> dict[str, BeadsTask | list]:
+        """Get a task with its subtasks in a hierarchical structure.
+
+        Args:
+            task_id: The task ID.
+
+        Returns:
+            Dict with 'task' and 'subtasks' keys.
+        """
+        task = self.get_task(task_id)
+        if not task:
+            return {"task": None, "subtasks": []}
+
+        subtasks = self.get_subtasks(task_id)
+        return {"task": task, "subtasks": subtasks}
+
+    def get_completed_tasks(self) -> list[BeadsTask]:
+        """Get tasks that have been completed (done or cancelled).
+
+        Returns:
+            List of completed tasks.
+        """
+        self._ensure_cache()
+        return [t for t in self._task_cache.values() if t.is_completed]
+
+    def get_blocked_tasks(self) -> list[BeadsTask]:
+        """Get tasks that are blocked.
+
+        Returns:
+            List of blocked tasks.
+        """
+        return self.list_tasks(status=BeadsTaskStatus.BLOCKED)
+
+    def refresh(self) -> int:
+        """Refresh the task cache from disk.
+
+        Returns:
+            Number of tasks loaded.
+        """
+        self.invalidate_cache()
+        self._ensure_cache()
+        return len(self._task_cache)