alma-memory 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

alma/progress/types.py

@@ -0,0 +1,254 @@
+"""
+Progress Tracking Types.
+
+Data models for tracking work items and progress.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional, List, Dict, Any, Literal
+import uuid
+
+
+WorkItemStatus = Literal[
+    "pending",      # Not started
+    "in_progress",  # Currently being worked on
+    "blocked",      # Waiting on something
+    "review",       # Completed, awaiting review
+    "done",         # Completed and verified
+    "failed",       # Could not complete
+]
+
+
+@dataclass
+class WorkItem:
+    """
+    A trackable unit of work.
+
+    Can represent features, bugs, tasks, research questions,
+    or any domain-specific work unit.
+    """
+
+    id: str
+    project_id: str
+    agent: Optional[str]
+
+    # Work item details
+    title: str
+    description: str
+    item_type: str  # "feature", "bug", "task", "research_question", etc.
+    status: WorkItemStatus = "pending"
+    priority: int = 50  # 0-100, higher = more important
+
+    # Progress tracking
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    time_spent_ms: int = 0
+    attempt_count: int = 0
+
+    # Relationships
+    parent_id: Optional[str] = None
+    blocks: List[str] = field(default_factory=list)
+    blocked_by: List[str] = field(default_factory=list)
+
+    # Validation
+    tests: List[str] = field(default_factory=list)
+    tests_passing: bool = False
+    acceptance_criteria: List[str] = field(default_factory=list)
+
+    # Timestamps
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    # Extensible metadata
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def create(
+        cls,
+        project_id: str,
+        title: str,
+        description: str,
+        item_type: str = "task",
+        agent: Optional[str] = None,
+        priority: int = 50,
+        parent_id: Optional[str] = None,
+        **kwargs,
+    ) -> "WorkItem":
+        """Factory method to create a new work item."""
+        return cls(
+            id=str(uuid.uuid4()),
+            project_id=project_id,
+            agent=agent,
+            title=title,
+            description=description,
+            item_type=item_type,
+            priority=priority,
+            parent_id=parent_id,
+            **kwargs,
+        )
+
+    def start(self) -> None:
+        """Mark work item as started."""
+        self.status = "in_progress"
+        self.started_at = datetime.now(timezone.utc)
+        self.attempt_count += 1
+        self.updated_at = datetime.now(timezone.utc)
+
+    def complete(self, tests_passing: bool = True) -> None:
+        """Mark work item as completed."""
+        self.status = "done"
+        self.completed_at = datetime.now(timezone.utc)
+        self.tests_passing = tests_passing
+        if self.started_at:
+            self.time_spent_ms += int(
+                (self.completed_at - self.started_at).total_seconds() * 1000
+            )
+        self.updated_at = datetime.now(timezone.utc)
+
+    def block(self, blocked_by: Optional[str] = None, reason: str = "") -> None:
+        """Mark work item as blocked."""
+        self.status = "blocked"
+        if blocked_by:
+            self.blocked_by.append(blocked_by)
+        if reason:
+            self.metadata["block_reason"] = reason
+        self.updated_at = datetime.now(timezone.utc)
+
+    def fail(self, reason: str = "") -> None:
+        """Mark work item as failed."""
+        self.status = "failed"
+        if reason:
+            self.metadata["failure_reason"] = reason
+        self.updated_at = datetime.now(timezone.utc)
+
+    def is_actionable(self) -> bool:
+        """Check if work item can be worked on."""
+        return (
+            self.status in ("pending", "in_progress")
+            and len(self.blocked_by) == 0
+        )
+
+
+@dataclass
+class ProgressLog:
+    """
+    Session-level progress snapshot.
+
+    Records the state of progress at a point in time.
+    """
+
+    id: str
+    project_id: str
+    agent: str
+    session_id: str
+
+    # Progress counts
+    items_total: int
+    items_done: int
+    items_in_progress: int
+    items_blocked: int
+    items_pending: int
+
+    # Current focus
+    current_item_id: Optional[str]
+    current_action: str
+
+    # Session metrics
+    session_start: datetime
+    actions_taken: int = 0
+    outcomes_recorded: int = 0
+
+    # Timestamp
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @classmethod
+    def create(
+        cls,
+        project_id: str,
+        agent: str,
+        session_id: str,
+        items_total: int,
+        items_done: int,
+        items_in_progress: int,
+        items_blocked: int,
+        items_pending: int,
+        current_item_id: Optional[str] = None,
+        current_action: str = "",
+        session_start: Optional[datetime] = None,
+    ) -> "ProgressLog":
+        """Factory method to create progress log."""
+        return cls(
+            id=str(uuid.uuid4()),
+            project_id=project_id,
+            agent=agent,
+            session_id=session_id,
+            items_total=items_total,
+            items_done=items_done,
+            items_in_progress=items_in_progress,
+            items_blocked=items_blocked,
+            items_pending=items_pending,
+            current_item_id=current_item_id,
+            current_action=current_action,
+            session_start=session_start or datetime.now(timezone.utc),
+        )
+
+
+@dataclass
+class ProgressSummary:
+    """
+    Summary of progress for display/reporting.
+
+    A simplified view of progress state.
+    """
+
+    project_id: str
+    agent: Optional[str]
+
+    # Counts
+    total: int
+    done: int
+    in_progress: int
+    blocked: int
+    pending: int
+    failed: int
+
+    # Percentages
+    completion_rate: float  # 0-1
+    success_rate: float  # done / (done + failed)
+
+    # Current focus
+    current_item: Optional[WorkItem]
+    next_suggested: Optional[WorkItem]
+
+    # Blockers
+    blockers: List[WorkItem]
+
+    # Time tracking
+    total_time_ms: int
+    avg_time_per_item_ms: float
+
+    # Timestamps
+    last_activity: Optional[datetime]
+    generated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @property
+    def completion_percentage(self) -> int:
+        """Get completion as percentage."""
+        return int(self.completion_rate * 100)
+
+    def format_summary(self) -> str:
+        """Format as human-readable string."""
+        lines = [
+            f"Progress: {self.done}/{self.total} ({self.completion_percentage}%)",
+            f"  In Progress: {self.in_progress}",
+            f"  Blocked: {self.blocked}",
+            f"  Pending: {self.pending}",
+        ]
+        if self.current_item:
+            lines.append(f"  Current: {self.current_item.title}")
+        if self.next_suggested:
+            lines.append(f"  Next: {self.next_suggested.title}")
+        if self.blockers:
+            lines.append(f"  Blockers: {len(self.blockers)} items")
+        return "\n".join(lines)

alma/session/__init__.py

@@ -0,0 +1,19 @@
+"""
+ALMA Session Management Module.
+
+Handles session continuity, handoffs, and quick context reload.
+"""
+
+from alma.session.types import (
+    SessionHandoff,
+    SessionContext,
+    SessionOutcome,
+)
+from alma.session.manager import SessionManager
+
+__all__ = [
+    "SessionHandoff",
+    "SessionContext",
+    "SessionOutcome",
+    "SessionManager",
+]

alma/session/manager.py

@@ -0,0 +1,399 @@
+"""
+Session Manager.
+
+Manages session continuity, handoffs, and quick context reload.
+"""
+
+from datetime import datetime, timezone
+from typing import Optional, List, Dict, Any, Callable
+import uuid
+import logging
+
+from alma.session.types import (
+    SessionHandoff,
+    SessionContext,
+    SessionOutcome,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SessionManager:
+    """
+    Manage session continuity for AI agents.
+
+    Provides:
+    - Session start/end handling
+    - Handoff creation and retrieval
+    - Quick reload formatting
+    - Integration with progress tracking
+    """
+
+    def __init__(
+        self,
+        project_id: str,
+        storage: Optional[Any] = None,  # Will be StorageBackend when integrated
+        progress_tracker: Optional[Any] = None,  # Will be ProgressTracker
+        max_handoffs: int = 50,
+    ):
+        """
+        Initialize session manager.
+
+        Args:
+            project_id: Project identifier
+            storage: Optional storage backend for persistence
+            progress_tracker: Optional progress tracker integration
+            max_handoffs: Maximum handoffs to keep in memory
+        """
+        self.project_id = project_id
+        self.storage = storage
+        self.progress_tracker = progress_tracker
+        self.max_handoffs = max_handoffs
+
+        # In-memory handoff storage (keyed by agent)
+        self._handoffs: Dict[str, List[SessionHandoff]] = {}
+
+        # Active sessions
+        self._active_sessions: Dict[str, SessionHandoff] = {}
+
+        # Context enrichers (callables that add context to sessions)
+        self._context_enrichers: List[Callable[[SessionContext], SessionContext]] = []
+
+    def register_enricher(
+        self,
+        enricher: Callable[[SessionContext], SessionContext],
+    ) -> None:
+        """
+        Register a context enricher.
+
+        Enrichers are called during session start to add context
+        (e.g., git status, running services, etc.)
+        """
+        self._context_enrichers.append(enricher)
+
+    def start_session(
+        self,
+        agent: str,
+        goal: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> SessionContext:
+        """
+        Start a new session, loading previous context.
+
+        Args:
+            agent: Agent identifier
+            goal: Current session goal
+            session_id: Optional session ID (generated if not provided)
+
+        Returns:
+            SessionContext with all relevant orientation data
+        """
+        session_id = session_id or str(uuid.uuid4())
+
+        # Get previous handoff
+        previous = self.get_latest_handoff(agent)
+
+        # Create session context
+        context = SessionContext.create(
+            project_id=self.project_id,
+            agent=agent,
+            session_id=session_id,
+            previous_handoff=previous,
+        )
+
+        # Get progress if tracker available
+        if self.progress_tracker:
+            try:
+                context.progress = self.progress_tracker.get_progress_summary(agent)
+            except Exception as e:
+                logger.warning(f"Could not get progress: {e}")
+
+        # Apply enrichers
+        for enricher in self._context_enrichers:
+            try:
+                context = enricher(context)
+            except Exception as e:
+                logger.warning(f"Context enricher failed: {e}")
+
+        # Create active session handoff for this session
+        current_goal = goal or (previous.current_goal if previous else "Unknown")
+        active_handoff = SessionHandoff.create(
+            project_id=self.project_id,
+            agent=agent,
+            session_id=session_id,
+            last_action="session_start",
+            current_goal=current_goal,
+            last_outcome="unknown",
+        )
+
+        # Carry over blockers from previous session
+        if previous and previous.blockers:
+            active_handoff.blockers = previous.blockers.copy()
+
+        self._active_sessions[f"{agent}:{session_id}"] = active_handoff
+
+        logger.info(
+            f"Started session {session_id} for agent {agent} "
+            f"(previous: {'yes' if previous else 'no'})"
+        )
+
+        return context
+
+    def get_active_handoff(
+        self,
+        agent: str,
+        session_id: str,
+    ) -> Optional[SessionHandoff]:
+        """Get the active handoff for current session."""
+        return self._active_sessions.get(f"{agent}:{session_id}")
+
+    def update_session(
+        self,
+        agent: str,
+        session_id: str,
+        action: Optional[str] = None,
+        outcome: Optional[SessionOutcome] = None,
+        decision: Optional[str] = None,
+        blocker: Optional[str] = None,
+        resolved_blocker: Optional[str] = None,
+        active_file: Optional[str] = None,
+        test_result: Optional[Dict[str, bool]] = None,
+        confidence: Optional[float] = None,
+        risk: Optional[str] = None,
+    ) -> Optional[SessionHandoff]:
+        """
+        Update the active session with new information.
+
+        This should be called periodically during a session to track state.
+
+        Args:
+            agent: Agent identifier
+            session_id: Session identifier
+            action: Latest action taken
+            outcome: Outcome of latest action
+            decision: Key decision made
+            blocker: New blocker encountered
+            resolved_blocker: Blocker that was resolved
+            active_file: File currently being worked on
+            test_result: Test name -> passing status
+            confidence: Updated confidence level
+            risk: New risk identified
+
+        Returns:
+            Updated SessionHandoff or None if session not found
+        """
+        key = f"{agent}:{session_id}"
+        handoff = self._active_sessions.get(key)
+
+        if not handoff:
+            logger.warning(f"No active session found for {key}")
+            return None
+
+        if action:
+            handoff.last_action = action
+        if outcome:
+            handoff.last_outcome = outcome
+        if decision:
+            handoff.add_decision(decision)
+        if blocker:
+            handoff.add_blocker(blocker)
+        if resolved_blocker:
+            handoff.remove_blocker(resolved_blocker)
+        if active_file and active_file not in handoff.active_files:
+            handoff.active_files.append(active_file)
+        if test_result:
+            for test_name, passing in test_result.items():
+                handoff.set_test_status(test_name, passing)
+        if confidence is not None:
+            handoff.confidence_level = max(0.0, min(1.0, confidence))
+        if risk and risk not in handoff.risk_flags:
+            handoff.risk_flags.append(risk)
+
+        return handoff
+
+    def create_handoff(
+        self,
+        agent: str,
+        session_id: str,
+        last_action: str,
+        last_outcome: SessionOutcome,
+        next_steps: Optional[List[str]] = None,
+        **context,
+    ) -> SessionHandoff:
+        """
+        Create handoff at session end.
+
+        This finalizes the session and stores the handoff for the next session.
+
+        Args:
+            agent: Agent identifier
+            session_id: Session identifier
+            last_action: Final action taken
+            last_outcome: Outcome of the session
+            next_steps: Planned next actions
+            **context: Additional context to store
+
+        Returns:
+            Finalized SessionHandoff
+        """
+        key = f"{agent}:{session_id}"
+        handoff = self._active_sessions.get(key)
+
+        if handoff:
+            # Finalize existing handoff
+            handoff.finalize(last_action, last_outcome, next_steps)
+            # Add any additional context
+            handoff.metadata.update(context)
+        else:
+            # Create new handoff (session started without start_session call)
+            handoff = SessionHandoff.create(
+                project_id=self.project_id,
+                agent=agent,
+                session_id=session_id,
+                last_action=last_action,
+                current_goal=context.get("goal", "Unknown"),
+                last_outcome=last_outcome,
+                next_steps=next_steps or [],
+            )
+            handoff.session_end = datetime.now(timezone.utc)
+            handoff.metadata.update(context)
+
+        # Store handoff
+        self._store_handoff(agent, handoff)
+
+        # Clear active session
+        if key in self._active_sessions:
+            del self._active_sessions[key]
+
+        logger.info(
+            f"Created handoff for session {session_id}, "
+            f"outcome: {last_outcome}, next_steps: {len(next_steps or [])}"
+        )
+
+        return handoff
+
+    def _store_handoff(self, agent: str, handoff: SessionHandoff) -> None:
+        """Store a handoff internally and optionally to persistent storage."""
+        if agent not in self._handoffs:
+            self._handoffs[agent] = []
+
+        self._handoffs[agent].append(handoff)
+
+        # Trim to max
+        if len(self._handoffs[agent]) > self.max_handoffs:
+            self._handoffs[agent] = self._handoffs[agent][-self.max_handoffs:]
+
+        # TODO: Persist to storage backend when integrated
+
+    def get_latest_handoff(self, agent: str) -> Optional[SessionHandoff]:
+        """Get the most recent handoff for an agent."""
+        handoffs = self._handoffs.get(agent, [])
+        return handoffs[-1] if handoffs else None
+
+    def get_previous_sessions(
+        self,
+        agent: str,
+        limit: int = 5,
+    ) -> List[SessionHandoff]:
+        """
+        Get recent session handoffs for an agent.
+
+        Args:
+            agent: Agent identifier
+            limit: Maximum number of handoffs to return
+
+        Returns:
+            List of SessionHandoff, most recent first
+        """
+        handoffs = self._handoffs.get(agent, [])
+        return list(reversed(handoffs[-limit:]))
+
+    def get_quick_reload(
+        self,
+        agent: str,
+    ) -> str:
+        """
+        Get compressed context string for quick reload.
+
+        This is a formatted string that can be quickly parsed by an agent
+        for rapid context restoration.
+
+        Args:
+            agent: Agent identifier
+
+        Returns:
+            Formatted quick reload string
+        """
+        handoff = self.get_latest_handoff(agent)
+        if not handoff:
+            return f"No previous session found for agent {agent}"
+
+        return handoff.format_quick_reload()
+
+    def get_all_agents(self) -> List[str]:
+        """Get list of all agents with session history."""
+        return list(self._handoffs.keys())
+
+    def get_agent_stats(self, agent: str) -> Dict[str, Any]:
+        """
+        Get session statistics for an agent.
+
+        Returns summary of session history including:
+        - Total sessions
+        - Success rate
+        - Average duration
+        - Common blockers
+        """
+        handoffs = self._handoffs.get(agent, [])
+        if not handoffs:
+            return {
+                "agent": agent,
+                "total_sessions": 0,
+                "success_rate": 0.0,
+                "avg_duration_ms": 0,
+                "common_blockers": [],
+            }
+
+        # Calculate stats
+        total = len(handoffs)
+        successes = sum(1 for h in handoffs if h.last_outcome == "success")
+        success_rate = successes / total if total > 0 else 0.0
+
+        durations = [h.duration_ms for h in handoffs if h.duration_ms > 0]
+        avg_duration = sum(durations) / len(durations) if durations else 0
+
+        # Count blockers
+        blocker_counts: Dict[str, int] = {}
+        for h in handoffs:
+            for blocker in h.blockers:
+                blocker_counts[blocker] = blocker_counts.get(blocker, 0) + 1
+        common_blockers = sorted(
+            blocker_counts.items(), key=lambda x: x[1], reverse=True
+        )[:5]
+
+        return {
+            "agent": agent,
+            "total_sessions": total,
+            "success_rate": success_rate,
+            "avg_duration_ms": avg_duration,
+            "common_blockers": [b[0] for b in common_blockers],
+        }
+
+    def clear_history(self, agent: Optional[str] = None) -> int:
+        """
+        Clear session history.
+
+        Args:
+            agent: If provided, only clear history for this agent
+
+        Returns:
+            Number of handoffs cleared
+        """
+        if agent:
+            count = len(self._handoffs.get(agent, []))
+            self._handoffs[agent] = []
+            return count
+        else:
+            count = sum(len(h) for h in self._handoffs.values())
+            self._handoffs.clear()
+            return count