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

alma/initializer/__init__.py

@@ -0,0 +1,37 @@
+"""
+ALMA Initializer Module.
+
+Bootstrap pattern that orients the agent before work begins.
+
+Usage:
+    from alma.initializer import SessionInitializer, InitializationResult
+
+    initializer = SessionInitializer(alma)
+    result = initializer.initialize(
+        project_id="my-project",
+        agent="Helena",
+        user_prompt="Test the login flow",
+        project_path="/path/to/project",
+    )
+
+    # Inject into agent prompt
+    prompt = f'''
+    {result.to_prompt()}
+
+    Now proceed with the first work item.
+    '''
+"""
+
+from alma.initializer.types import (
+    CodebaseOrientation,
+    InitializationResult,
+    RulesOfEngagement,
+)
+from alma.initializer.initializer import SessionInitializer
+
+__all__ = [
+    "CodebaseOrientation",
+    "InitializationResult",
+    "RulesOfEngagement",
+    "SessionInitializer",
+]

alma/initializer/initializer.py

@@ -0,0 +1,410 @@
+"""
+Session Initializer.
+
+Bootstrap pattern that orients the agent before work begins.
+"Stage manager sets the stage, actor performs."
+"""
+
+import logging
+import re
+import subprocess
+from pathlib import Path
+from typing import Any, List, Optional
+
+from alma.initializer.types import (
+    CodebaseOrientation,
+    InitializationResult,
+    RulesOfEngagement,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SessionInitializer:
+    """
+    Bootstrap domain memory from user prompt.
+
+    The Initializer Pattern:
+    1. Expand user prompt to structured work items
+    2. Orient to current codebase state (git, files)
+    3. Retrieve relevant memories from past sessions
+    4. Set rules of engagement from agent scope
+    5. Suggest optimal starting point
+
+    Usage:
+        initializer = SessionInitializer(alma)
+
+        result = initializer.initialize(
+            project_id="my-project",
+            agent="Helena",
+            user_prompt="Test the login flow",
+        )
+
+        # Inject into agent prompt
+        prompt = f'''
+        {result.to_prompt()}
+
+        Now proceed with the first work item.
+        '''
+    """
+
+    def __init__(
+        self,
+        alma: Optional[Any] = None,
+        progress_tracker: Optional[Any] = None,
+        session_manager: Optional[Any] = None,
+    ):
+        """
+        Initialize the SessionInitializer.
+
+        Args:
+            alma: ALMA instance for memory retrieval
+            progress_tracker: ProgressTracker for work item management
+            session_manager: SessionManager for session context
+        """
+        self.alma = alma
+        self.progress_tracker = progress_tracker
+        self.session_manager = session_manager
+
+    def initialize(
+        self,
+        project_id: str,
+        agent: str,
+        user_prompt: str,
+        project_path: Optional[str] = None,
+        auto_expand: bool = True,
+        memory_top_k: int = 5,
+    ) -> InitializationResult:
+        """
+        Full session initialization.
+
+        Args:
+            project_id: Project identifier
+            agent: Agent name (e.g., "Helena", "Victor")
+            user_prompt: Raw user prompt/task
+            project_path: Optional path to project root (for git orientation)
+            auto_expand: Whether to expand prompt to work items
+            memory_top_k: How many memories to retrieve
+
+        Returns:
+            InitializationResult with everything agent needs
+        """
+        logger.info(f"Initializing session for {agent} on {project_id}")
+
+        # Create result
+        result = InitializationResult.create(
+            project_id=project_id,
+            agent=agent,
+            original_prompt=user_prompt,
+        )
+
+        # 1. Expand prompt to work items
+        if auto_expand:
+            work_items = self.expand_prompt(user_prompt)
+            result.work_items = work_items
+            if work_items:
+                result.goal = self._summarize_goal(user_prompt, work_items)
+
+        # 2. Orient to codebase
+        if project_path:
+            result.orientation = self.orient_to_codebase(project_path)
+
+        # 3. Retrieve relevant memories
+        if self.alma:
+            try:
+                memories = self.alma.retrieve(
+                    task=user_prompt,
+                    agent=agent,
+                    top_k=memory_top_k,
+                )
+                result.relevant_memories = memories
+            except Exception as e:
+                logger.warning(f"Failed to retrieve memories: {e}")
+
+        # 4. Get rules of engagement
+        if self.alma:
+            result.rules = self.get_rules_of_engagement(agent)
+
+        # 5. Suggest starting point
+        if result.work_items:
+            result.recommended_start = self._select_starting_point(result.work_items)
+
+        # 6. Get recent activity from session manager
+        if self.session_manager:
+            try:
+                context = self.session_manager.start_session(
+                    agent=agent,
+                    goal=result.goal,
+                )
+                result.session_id = context.session_id
+                if context.previous_handoff:
+                    result.recent_activity = context.previous_handoff.next_steps or []
+            except Exception as e:
+                logger.warning(f"Failed to get session context: {e}")
+
+        logger.info(
+            f"Initialization complete: {len(result.work_items)} work items, "
+            f"orientation: {'yes' if result.orientation else 'no'}, "
+            f"memories: {'yes' if result.relevant_memories else 'no'}"
+        )
+
+        return result
+
+    def expand_prompt(
+        self,
+        user_prompt: str,
+        use_ai: bool = False,
+    ) -> List[Any]:
+        """
+        Expand user prompt into structured work items.
+
+        Simple implementation: extract bullet points and numbered items.
+        AI implementation: use LLM to break down complex tasks.
+
+        Args:
+            user_prompt: Raw user prompt
+            use_ai: Whether to use AI for expansion (requires LLM)
+
+        Returns:
+            List of WorkItem objects
+        """
+        from alma.progress import WorkItem
+
+        work_items = []
+
+        # Simple extraction: look for bullet points and numbered items
+        lines = user_prompt.strip().split('\n')
+
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+
+            # Match bullet points: -, *, •
+            bullet_match = re.match(r'^[-*•]\s+(.+)$', line)
+            if bullet_match:
+                title = bullet_match.group(1).strip()
+                work_items.append(WorkItem.create(
+                    project_id="",  # Will be set by caller
+                    title=title,
+                    description=title,
+                ))
+                continue
+
+            # Match numbered items: 1., 2., etc.
+            number_match = re.match(r'^\d+\.\s+(.+)$', line)
+            if number_match:
+                title = number_match.group(1).strip()
+                work_items.append(WorkItem.create(
+                    project_id="",
+                    title=title,
+                    description=title,
+                ))
+                continue
+
+        # If no structured items found, create single item from prompt
+        if not work_items:
+            # Truncate long prompts for title
+            title = user_prompt[:100].strip()
+            if len(user_prompt) > 100:
+                title += "..."
+
+            work_items.append(WorkItem.create(
+                project_id="",
+                title=title,
+                description=user_prompt,
+            ))
+
+        return work_items
+
+    def orient_to_codebase(
+        self,
+        project_path: str,
+        max_commits: int = 5,
+    ) -> CodebaseOrientation:
+        """
+        Orient to current codebase state.
+
+        Reads git status, recent commits, and file structure.
+
+        Args:
+            project_path: Path to project root
+            max_commits: Max number of recent commits to include
+
+        Returns:
+            CodebaseOrientation with codebase state
+        """
+        path = Path(project_path)
+
+        # Default orientation
+        orientation = CodebaseOrientation(
+            current_branch="unknown",
+            has_uncommitted_changes=False,
+            recent_commits=[],
+            root_path=str(path),
+            key_directories=[],
+            config_files=[],
+        )
+
+        # Check if it's a git repo
+        git_dir = path / ".git"
+        is_git_repo = git_dir.exists()
+
+        if is_git_repo:
+            try:
+                # Get current branch
+                result = subprocess.run(
+                    ["git", "branch", "--show-current"],
+                    cwd=path,
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                if result.returncode == 0:
+                    orientation.current_branch = result.stdout.strip() or "HEAD detached"
+
+                # Check for uncommitted changes
+                result = subprocess.run(
+                    ["git", "status", "--porcelain"],
+                    cwd=path,
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                if result.returncode == 0:
+                    orientation.has_uncommitted_changes = bool(result.stdout.strip())
+
+                # Get recent commits
+                result = subprocess.run(
+                    ["git", "log", "--oneline", f"-{max_commits}"],
+                    cwd=path,
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                if result.returncode == 0:
+                    commits = result.stdout.strip().split('\n')
+                    orientation.recent_commits = [c for c in commits if c]
+
+            except subprocess.TimeoutExpired:
+                logger.warning("Git commands timed out")
+            except Exception as e:
+                logger.warning(f"Git orientation failed: {e}")
+
+        # Find key directories
+        key_dirs = ["src", "lib", "tests", "test", "app", "api", "core"]
+        orientation.key_directories = [
+            d for d in key_dirs if (path / d).is_dir()
+        ]
+
+        # Find config files
+        config_files = [
+            "package.json", "pyproject.toml", "setup.py", "Cargo.toml",
+            "go.mod", "pom.xml", "build.gradle", "Makefile", "CMakeLists.txt",
+        ]
+        orientation.config_files = [
+            f for f in config_files if (path / f).exists()
+        ]
+
+        # Generate summary
+        orientation.summary = self._generate_orientation_summary(orientation)
+
+        return orientation
+
+    def get_rules_of_engagement(
+        self,
+        agent: str,
+    ) -> RulesOfEngagement:
+        """
+        Get rules of engagement from agent scope.
+
+        Args:
+            agent: Agent name
+
+        Returns:
+            RulesOfEngagement with scope rules, constraints, quality gates
+        """
+        rules = RulesOfEngagement()
+
+        if not self.alma:
+            return rules
+
+        # Get scope from ALMA
+        scope = self.alma.scopes.get(agent)
+        if not scope:
+            return rules
+
+        # Convert scope to rules
+        if scope.can_learn:
+            rules.scope_rules = [
+                f"Learn from: {', '.join(scope.can_learn)}"
+            ]
+
+        if scope.cannot_learn:
+            rules.constraints = [
+                f"Do not learn from: {', '.join(scope.cannot_learn)}"
+            ]
+
+        # Default quality gates
+        rules.quality_gates = [
+            "All tests pass",
+            "No regressions introduced",
+            "Changes documented if significant",
+        ]
+
+        return rules
+
+    def _summarize_goal(self, prompt: str, work_items: List[Any]) -> str:
+        """Summarize goal from prompt and work items."""
+        if len(work_items) == 1:
+            return prompt
+
+        item_titles = [getattr(item, 'title', str(item)) for item in work_items]
+        return f"{prompt}\n\nBroken down into {len(work_items)} items: {', '.join(item_titles[:3])}{'...' if len(item_titles) > 3 else ''}"
+
+    def _select_starting_point(self, work_items: List[Any]) -> Optional[Any]:
+        """Select the best starting point from work items."""
+        if not work_items:
+            return None
+
+        # Find highest priority unblocked item
+        actionable = [
+            item for item in work_items
+            if getattr(item, 'status', 'pending') == 'pending'
+            and not getattr(item, 'blocked_by', [])
+        ]
+
+        if actionable:
+            # Sort by priority (higher = more important)
+            actionable.sort(
+                key=lambda x: getattr(x, 'priority', 50),
+                reverse=True
+            )
+            return actionable[0]
+
+        return work_items[0]
+
+    def _generate_orientation_summary(self, orientation: CodebaseOrientation) -> str:
+        """Generate a one-line summary of codebase orientation."""
+        parts = []
+
+        parts.append(f"Branch: {orientation.current_branch}")
+
+        if orientation.has_uncommitted_changes:
+            parts.append("has uncommitted changes")
+
+        if orientation.key_directories:
+            parts.append(f"key dirs: {', '.join(orientation.key_directories[:3])}")
+
+        if orientation.config_files:
+            # Infer project type from config files
+            if "package.json" in orientation.config_files:
+                parts.append("Node.js project")
+            elif "pyproject.toml" in orientation.config_files or "setup.py" in orientation.config_files:
+                parts.append("Python project")
+            elif "Cargo.toml" in orientation.config_files:
+                parts.append("Rust project")
+            elif "go.mod" in orientation.config_files:
+                parts.append("Go project")
+
+        return "; ".join(parts)

alma/initializer/types.py

@@ -0,0 +1,242 @@
+"""
+Initializer Types.
+
+Data structures for the Session Initializer pattern.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+import uuid
+
+
+@dataclass
+class CodebaseOrientation:
+    """Codebase orientation information."""
+
+    # Git state
+    current_branch: str
+    has_uncommitted_changes: bool
+    recent_commits: List[str]  # Last N commit messages
+
+    # File structure
+    root_path: str
+    key_directories: List[str]  # src/, tests/, etc.
+    config_files: List[str]  # package.json, pyproject.toml, etc.
+
+    # Summary
+    summary: Optional[str] = None
+
+    def to_prompt(self) -> str:
+        """Format orientation for prompt injection."""
+        lines = [
+            f"Branch: {self.current_branch}",
+            f"Uncommitted changes: {'Yes' if self.has_uncommitted_changes else 'No'}",
+        ]
+
+        if self.recent_commits:
+            lines.append("Recent commits:")
+            for commit in self.recent_commits[:5]:
+                lines.append(f"  - {commit}")
+
+        if self.key_directories:
+            lines.append(f"Key directories: {', '.join(self.key_directories)}")
+
+        if self.summary:
+            lines.append(f"Summary: {self.summary}")
+
+        return "\n".join(lines)
+
+
+@dataclass
+class RulesOfEngagement:
+    """Rules governing agent behavior during session."""
+
+    # What agent CAN do
+    scope_rules: List[str] = field(default_factory=list)
+
+    # What agent CANNOT do
+    constraints: List[str] = field(default_factory=list)
+
+    # Must pass before marking "done"
+    quality_gates: List[str] = field(default_factory=list)
+
+    def to_prompt(self) -> str:
+        """Format rules for prompt injection."""
+        lines = []
+
+        if self.scope_rules:
+            lines.append("You CAN:")
+            for rule in self.scope_rules:
+                lines.append(f"  - {rule}")
+
+        if self.constraints:
+            lines.append("You CANNOT:")
+            for constraint in self.constraints:
+                lines.append(f"  - {constraint}")
+
+        if self.quality_gates:
+            lines.append("Before marking DONE, verify:")
+            for gate in self.quality_gates:
+                lines.append(f"  - {gate}")
+
+        return "\n".join(lines)
+
+
+@dataclass
+class InitializationResult:
+    """
+    Result of session initialization.
+
+    Contains everything an agent needs to start work:
+    - Expanded goal and work items
+    - Codebase orientation
+    - Relevant memories
+    - Rules of engagement
+    - Recommended starting point
+    """
+
+    id: str
+    session_id: str
+    project_id: str
+    agent: str
+
+    # Original and expanded goal
+    original_prompt: str
+    goal: str
+
+    # Work items extracted from goal
+    work_items: List[Any] = field(default_factory=list)  # WorkItem objects
+
+    # Codebase orientation
+    orientation: Optional[CodebaseOrientation] = None
+
+    # Recent activity
+    recent_activity: List[str] = field(default_factory=list)
+
+    # Relevant memories (MemorySlice)
+    relevant_memories: Optional[Any] = None
+
+    # Rules of engagement
+    rules: RulesOfEngagement = field(default_factory=RulesOfEngagement)
+
+    # Suggested first action
+    recommended_start: Optional[Any] = None  # WorkItem
+
+    # Metadata
+    initialized_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def create(
+        cls,
+        project_id: str,
+        agent: str,
+        original_prompt: str,
+        goal: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> "InitializationResult":
+        """Create a new initialization result."""
+        return cls(
+            id=str(uuid.uuid4()),
+            session_id=session_id or str(uuid.uuid4()),
+            project_id=project_id,
+            agent=agent,
+            original_prompt=original_prompt,
+            goal=goal or original_prompt,
+        )
+
+    def to_prompt(self) -> str:
+        """
+        Format initialization result for prompt injection.
+
+        This is the "briefing" that prepares the agent.
+        """
+        sections = []
+
+        # Header
+        sections.append(f"## Session Initialization for {self.agent}")
+        sections.append(f"Project: {self.project_id}")
+        sections.append(f"Session: {self.session_id}")
+        sections.append("")
+
+        # Goal
+        sections.append("### Goal")
+        sections.append(self.goal)
+        sections.append("")
+
+        # Work items
+        if self.work_items:
+            sections.append("### Work Items")
+            for i, item in enumerate(self.work_items, 1):
+                title = getattr(item, 'title', str(item))
+                status = getattr(item, 'status', 'pending')
+                sections.append(f"{i}. [{status}] {title}")
+            sections.append("")
+
+        # Orientation
+        if self.orientation:
+            sections.append("### Codebase Orientation")
+            sections.append(self.orientation.to_prompt())
+            sections.append("")
+
+        # Relevant memories
+        if self.relevant_memories:
+            sections.append("### Relevant Knowledge from Past Runs")
+            if hasattr(self.relevant_memories, 'to_prompt'):
+                sections.append(self.relevant_memories.to_prompt())
+            else:
+                sections.append(str(self.relevant_memories))
+            sections.append("")
+
+        # Rules of engagement
+        if self.rules.scope_rules or self.rules.constraints or self.rules.quality_gates:
+            sections.append("### Rules of Engagement")
+            sections.append(self.rules.to_prompt())
+            sections.append("")
+
+        # Recommended start
+        if self.recommended_start:
+            sections.append("### Recommended First Action")
+            title = getattr(self.recommended_start, 'title', str(self.recommended_start))
+            sections.append(f"Start with: {title}")
+            sections.append("")
+
+        return "\n".join(sections)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "id": self.id,
+            "session_id": self.session_id,
+            "project_id": self.project_id,
+            "agent": self.agent,
+            "original_prompt": self.original_prompt,
+            "goal": self.goal,
+            "work_items": [
+                item.to_dict() if hasattr(item, 'to_dict') else str(item)
+                for item in self.work_items
+            ],
+            "orientation": {
+                "current_branch": self.orientation.current_branch,
+                "has_uncommitted_changes": self.orientation.has_uncommitted_changes,
+                "recent_commits": self.orientation.recent_commits,
+                "root_path": self.orientation.root_path,
+                "key_directories": self.orientation.key_directories,
+                "config_files": self.orientation.config_files,
+                "summary": self.orientation.summary,
+            } if self.orientation else None,
+            "recent_activity": self.recent_activity,
+            "rules": {
+                "scope_rules": self.rules.scope_rules,
+                "constraints": self.rules.constraints,
+                "quality_gates": self.rules.quality_gates,
+            },
+            "recommended_start": (
+                self.recommended_start.to_dict()
+                if self.recommended_start and hasattr(self.recommended_start, 'to_dict')
+                else str(self.recommended_start) if self.recommended_start else None
+            ),
+            "initialized_at": self.initialized_at.isoformat(),
+            "metadata": self.metadata,
+        }

alma/progress/__init__.py

@@ -0,0 +1,21 @@
+"""
+ALMA Progress Tracking Module.
+
+Track work items, progress, and suggest next actions.
+"""
+
+from alma.progress.types import (
+    WorkItem,
+    WorkItemStatus,
+    ProgressLog,
+    ProgressSummary,
+)
+from alma.progress.tracker import ProgressTracker
+
+__all__ = [
+    "WorkItem",
+    "WorkItemStatus",
+    "ProgressLog",
+    "ProgressSummary",
+    "ProgressTracker",
+]