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

alma/initializer/types.py

@@ -0,0 +1,250 @@
+"""
+Initializer Types.
+
+Data structures for the Session Initializer pattern.
+"""
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+@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/integration/__init__.py

@@ -5,32 +5,32 @@ Provides integration hooks for Claude Code agents (Helena, Victor, etc).
 """
 
 from alma.integration.claude_agents import (
+    AgentIntegration,
     AgentType,
+    ClaudeAgentHooks,
     TaskContext,
     TaskOutcome,
-    ClaudeAgentHooks,
-    AgentIntegration,
     create_integration,
 )
 from alma.integration.helena import (
+    HELENA_CATEGORIES,
+    HELENA_FORBIDDEN,
+    HelenaHooks,
     UITestContext,
     UITestOutcome,
-    HelenaHooks,
     create_helena_hooks,
-    helena_pre_task,
     helena_post_task,
-    HELENA_CATEGORIES,
-    HELENA_FORBIDDEN,
+    helena_pre_task,
 )
 from alma.integration.victor import (
+    VICTOR_CATEGORIES,
+    VICTOR_FORBIDDEN,
     APITestContext,
     APITestOutcome,
     VictorHooks,
     create_victor_hooks,
-    victor_pre_task,
     victor_post_task,
-    VICTOR_CATEGORIES,
-    VICTOR_FORBIDDEN,
+    victor_pre_task,
 )
 
 __all__ = [

alma/integration/claude_agents.py

@@ -9,20 +9,21 @@ These hooks enable agents to:
 """
 
 import logging
-from typing import Optional, Dict, Any, List
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
+from typing import Any, Dict, List, Optional
 
 from alma.core import ALMA
+from alma.harness.base import Context, Harness, RunResult
 from alma.types import MemorySlice
-from alma.harness.base import Harness, Context, RunResult
 
 logger = logging.getLogger(__name__)
 
 
 class AgentType(Enum):
     """Supported Claude Code agent types."""
+
     HELENA = "helena"
     VICTOR = "victor"
     CLARA = "clara"
@@ -37,6 +38,7 @@ class TaskContext:
 
     Captures all relevant information for memory retrieval and learning.
     """
+
     task_description: str
     task_type: str
     agent_name: str
@@ -67,6 +69,7 @@ class TaskOutcome:
 
     Used for learning from task results.
     """
+
     success: bool
     strategy_used: str
     output: Any = None
@@ -272,17 +275,17 @@ class ClaudeAgentHooks:
                 sections.append(f"- [{dk.domain}] {dk.fact}")
 
         # User preferences
-        if memories.user_preferences:
+        if memories.preferences:
             if include_section_headers:
                 sections.append("\n### User Preferences:")
-            for up in memories.user_preferences:
+            for up in memories.preferences:
                 sections.append(f"- [{up.category}] {up.preference}")
 
         # Recent outcomes
-        if memories.recent_outcomes:
+        if memories.outcomes:
             if include_section_headers:
                 sections.append("\n### Recent Outcomes:")
-            for o in memories.recent_outcomes[:3]:  # Limit to 3 most recent
+            for o in memories.outcomes[:3]:  # Limit to 3 most recent
                 status = "✓" if o.success else "✗"
                 sections.append(
                     f"- {status} {o.task_type}: {o.task_description[:50]}..."
@@ -391,10 +394,7 @@ class AgentIntegration:
 
     def get_all_stats(self) -> Dict[str, Dict[str, Any]]:
         """Get memory statistics for all registered agents."""
-        return {
-            name: hooks.get_agent_stats()
-            for name, hooks in self._agents.items()
-        }
+        return {name: hooks.get_agent_stats() for name, hooks in self._agents.items()}
 
 
 def create_integration(

alma/integration/helena.py

@@ -14,18 +14,18 @@ This module provides Helena-specific memory categories, prompts, and utilities.
 """
 
 import logging
-from typing import Optional, Dict, Any, List
 from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
 
 from alma.core import ALMA
-from alma.types import MemorySlice
 from alma.harness.domains import CodingDomain
 from alma.integration.claude_agents import (
+    AgentType,
     ClaudeAgentHooks,
     TaskContext,
     TaskOutcome,
-    AgentType,
 )
+from alma.types import MemorySlice
 
 logger = logging.getLogger(__name__)
 
@@ -55,6 +55,7 @@ class UITestContext(TaskContext):
 
     Extends TaskContext with UI testing-specific fields.
     """
+
     component_type: Optional[str] = None
     page_url: Optional[str] = None
     viewport: Optional[Dict[str, int]] = None
@@ -89,6 +90,7 @@ class UITestOutcome(TaskOutcome):
 
     Extends TaskOutcome with UI testing-specific results.
     """
+
     selectors_used: List[str] = field(default_factory=list)
     accessibility_issues: List[Dict[str, Any]] = field(default_factory=list)
     visual_diffs: List[str] = field(default_factory=list)
@@ -148,11 +150,13 @@ class HelenaHooks(ClaudeAgentHooks):
         patterns = []
         for h in memories.heuristics:
             if "selector" in h.condition.lower():
-                patterns.append({
-                    "pattern": h.strategy,
-                    "confidence": h.confidence,
-                    "occurrences": h.occurrence_count,
-                })
+                patterns.append(
+                    {
+                        "pattern": h.strategy,
+                        "confidence": h.confidence,
+                        "occurrences": h.occurrence_count,
+                    }
+                )
 
         return patterns
 
@@ -171,11 +175,13 @@ class HelenaHooks(ClaudeAgentHooks):
         strategies = []
         for h in memories.heuristics:
             if any(kw in h.condition.lower() for kw in ["form", "validation", "input"]):
-                strategies.append({
-                    "condition": h.condition,
-                    "strategy": h.strategy,
-                    "confidence": h.confidence,
-                })
+                strategies.append(
+                    {
+                        "condition": h.condition,
+                        "strategy": h.strategy,
+                        "confidence": h.confidence,
+                    }
+                )
 
         return strategies
 
@@ -194,18 +200,22 @@ class HelenaHooks(ClaudeAgentHooks):
         patterns = []
         for h in memories.heuristics:
             if any(kw in h.condition.lower() for kw in ["access", "aria", "keyboard"]):
-                patterns.append({
-                    "condition": h.condition,
-                    "strategy": h.strategy,
-                    "confidence": h.confidence,
-                })
+                patterns.append(
+                    {
+                        "condition": h.condition,
+                        "strategy": h.strategy,
+                        "confidence": h.confidence,
+                    }
+                )
 
         for dk in memories.domain_knowledge:
             if dk.domain == "accessibility_testing":
-                patterns.append({
-                    "fact": dk.fact,
-                    "source": dk.source,
-                })
+                patterns.append(
+                    {
+                        "fact": dk.fact,
+                        "source": dk.source,
+                    }
+                )
 
         return patterns
 

alma/integration/victor.py

@@ -14,18 +14,18 @@ This module provides Victor-specific memory categories, prompts, and utilities.
 """
 
 import logging
-from typing import Optional, Dict, Any, List
 from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
 
 from alma.core import ALMA
-from alma.types import MemorySlice
 from alma.harness.domains import CodingDomain
 from alma.integration.claude_agents import (
+    AgentType,
     ClaudeAgentHooks,
     TaskContext,
     TaskOutcome,
-    AgentType,
 )
+from alma.types import MemorySlice
 
 logger = logging.getLogger(__name__)
 
@@ -55,6 +55,7 @@ class APITestContext(TaskContext):
 
     Extends TaskContext with API/backend testing-specific fields.
     """
+
     endpoint: Optional[str] = None
     method: str = "GET"
     expected_status: Optional[int] = None
@@ -91,6 +92,7 @@ class APITestOutcome(TaskOutcome):
 
     Extends TaskOutcome with API/backend testing-specific results.
     """
+
     response_status: Optional[int] = None
     response_time_ms: Optional[int] = None
     response_body: Optional[Dict[str, Any]] = None
@@ -153,12 +155,14 @@ class VictorHooks(ClaudeAgentHooks):
         patterns = []
         for h in memories.heuristics:
             if "api" in h.condition.lower() or "endpoint" in h.condition.lower():
-                patterns.append({
-                    "pattern": h.strategy,
-                    "condition": h.condition,
-                    "confidence": h.confidence,
-                    "occurrences": h.occurrence_count,
-                })
+                patterns.append(
+                    {
+                        "pattern": h.strategy,
+                        "condition": h.condition,
+                        "confidence": h.confidence,
+                        "occurrences": h.occurrence_count,
+                    }
+                )
 
         return patterns
 
@@ -176,12 +180,16 @@ class VictorHooks(ClaudeAgentHooks):
 
         patterns = []
         for h in memories.heuristics:
-            if any(kw in h.condition.lower() for kw in ["error", "exception", "validation"]):
-                patterns.append({
-                    "condition": h.condition,
-                    "strategy": h.strategy,
-                    "confidence": h.confidence,
-                })
+            if any(
+                kw in h.condition.lower() for kw in ["error", "exception", "validation"]
+            ):
+                patterns.append(
+                    {
+                        "condition": h.condition,
+                        "strategy": h.strategy,
+                        "confidence": h.confidence,
+                    }
+                )
 
         return patterns
 
@@ -199,19 +207,26 @@ class VictorHooks(ClaudeAgentHooks):
 
         strategies = []
         for h in memories.heuristics:
-            if any(kw in h.condition.lower() for kw in ["performance", "cache", "query", "slow"]):
-                strategies.append({
-                    "condition": h.condition,
-                    "strategy": h.strategy,
-                    "confidence": h.confidence,
-                })
+            if any(
+                kw in h.condition.lower()
+                for kw in ["performance", "cache", "query", "slow"]
+            ):
+                strategies.append(
+                    {
+                        "condition": h.condition,
+                        "strategy": h.strategy,
+                        "confidence": h.confidence,
+                    }
+                )
 
         for dk in memories.domain_knowledge:
             if dk.domain in ["performance_optimization", "caching_strategies"]:
-                strategies.append({
-                    "fact": dk.fact,
-                    "source": dk.source,
-                })
+                strategies.append(
+                    {
+                        "fact": dk.fact,
+                        "source": dk.source,
+                    }
+                )
 
         return strategies
 
@@ -229,12 +244,17 @@ class VictorHooks(ClaudeAgentHooks):
 
         patterns = []
         for h in memories.heuristics:
-            if any(kw in h.condition.lower() for kw in ["auth", "token", "permission", "jwt"]):
-                patterns.append({
-                    "condition": h.condition,
-                    "strategy": h.strategy,
-                    "confidence": h.confidence,
-                })
+            if any(
+                kw in h.condition.lower()
+                for kw in ["auth", "token", "permission", "jwt"]
+            ):
+                patterns.append(
+                    {
+                        "condition": h.condition,
+                        "strategy": h.strategy,
+                        "confidence": h.confidence,
+                    }
+                )
 
         return patterns
 
@@ -318,11 +338,15 @@ class VictorHooks(ClaudeAgentHooks):
         sections.append(f"- **Task Type**: {test_context.task_type}")
 
         if test_context.endpoint:
-            sections.append(f"- **Endpoint**: {test_context.method} {test_context.endpoint}")
+            sections.append(
+                f"- **Endpoint**: {test_context.method} {test_context.endpoint}"
+            )
         if test_context.expected_status:
             sections.append(f"- **Expected Status**: {test_context.expected_status}")
         if test_context.request_body:
-            sections.append(f"- **Request Body**: {len(test_context.request_body)} fields")
+            sections.append(
+                f"- **Request Body**: {len(test_context.request_body)} fields"
+            )
 
         if test_context.is_auth_test:
             sections.append("- **Focus**: Authentication/Authorization")