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

alma/harness/__init__.py

@@ -9,17 +9,17 @@ A structured framework for creating learning agents across any domain:
 """
 
 from alma.harness.base import (
-    Setting,
-    Context,
     Agent,
-    MemorySchema,
+    Context,
     Harness,
+    MemorySchema,
+    Setting,
 )
 from alma.harness.domains import (
     CodingDomain,
-    ResearchDomain,
     ContentDomain,
     OperationsDomain,
+    ResearchDomain,
 )
 
 __all__ = [

alma/harness/base.py

@@ -17,23 +17,23 @@ Flow:
     Repeat   -> Agent appears to "learn" without weight changes
 """
 
-from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Optional, List, Dict, Any, Callable
 from enum import Enum
+from typing import Any, Callable, Dict, List, Optional
 
-from alma.types import MemorySlice, MemoryScope
+from alma.types import MemoryScope, MemorySlice
 
 
 class ToolType(Enum):
     """Categories of tools available to agents."""
-    SEARCH = "search"           # Web search, semantic search
-    DATA_ACCESS = "data_access" # APIs, databases
-    EXECUTION = "execution"     # Code execution, automation
+
+    SEARCH = "search"  # Web search, semantic search
+    DATA_ACCESS = "data_access"  # APIs, databases
+    EXECUTION = "execution"  # Code execution, automation
     COMMUNICATION = "communication"  # Email, messaging
-    ANALYSIS = "analysis"       # Data processing, synthesis
-    CREATION = "creation"       # Content generation, design
+    ANALYSIS = "analysis"  # Data processing, synthesis
+    CREATION = "creation"  # Content generation, design
 
 
 @dataclass
@@ -43,6 +43,7 @@ class Tool:
 
     Tools are the building blocks agents use to accomplish tasks.
     """
+
     name: str
     description: str
     tool_type: ToolType
@@ -66,6 +67,7 @@ class Setting:
     Includes available tools and immutable constraints that don't change
     between runs. The setting defines WHAT the agent CAN do.
     """
+
     name: str
     description: str
     tools: List[Tool] = field(default_factory=list)
@@ -100,6 +102,7 @@ class Context:
     This is injected fresh each time and contains task-specific information.
     The context defines WHAT the agent should do THIS run.
     """
+
     task: str
     user_id: Optional[str] = None
     project_id: Optional[str] = None
@@ -137,6 +140,7 @@ class MemorySchema:
     This defines WHAT gets remembered and HOW, ensuring relevance
     and preventing scope creep. Each domain has its own schema.
     """
+
     domain: str
     description: str
 
@@ -195,6 +199,7 @@ class Agent:
     Agents start "dumb" but get smarter via memory injections.
     They use tools to accomplish tasks and log reflections post-run.
     """
+
     name: str
     role: str
     description: str
@@ -227,6 +232,7 @@ class Agent:
 @dataclass
 class RunResult:
     """Result of a harness run."""
+
     success: bool
     output: Any
     reflections: List[str] = field(default_factory=list)
@@ -319,7 +325,9 @@ class Harness:
             agent=self.agent.name,
             task=context.task,
             outcome="success" if result.success else "failure",
-            strategy_used=", ".join(result.tools_used) if result.tools_used else "direct",
+            strategy_used=(
+                ", ".join(result.tools_used) if result.tools_used else "direct"
+            ),
             duration_ms=result.duration_ms,
             error_message=result.error,
             feedback="; ".join(result.reflections) if result.reflections else None,
@@ -347,6 +355,7 @@ class Harness:
             RunResult with output or prompt
         """
         import time
+
         start_time = time.time()
 
         # 1. Pre-run: Get relevant memories

alma/harness/domains.py

@@ -13,23 +13,22 @@ Each domain includes:
 - Agent templates
 """
 
-from dataclasses import dataclass, field
-from typing import List, Dict, Any, Optional
+from typing import Any
 
 from alma.harness.base import (
+    Agent,
+    Harness,
+    MemorySchema,
     Setting,
     Tool,
     ToolType,
-    Agent,
-    MemorySchema,
-    Harness,
 )
 
-
 # =============================================================================
 # CODING DOMAIN
 # =============================================================================
 
+
 class CodingDomain:
     """Pre-built configurations for coding/development agents."""
 
@@ -114,13 +113,19 @@ class CodingDomain:
                     name="playwright",
                     description="Browser automation for UI testing",
                     tool_type=ToolType.EXECUTION,
-                    constraints=["Use explicit waits, not sleep()", "Prefer role-based selectors"],
+                    constraints=[
+                        "Use explicit waits, not sleep()",
+                        "Prefer role-based selectors",
+                    ],
                 ),
                 Tool(
                     name="api_client",
                     description="HTTP client for API testing",
                     tool_type=ToolType.DATA_ACCESS,
-                    constraints=["Log all requests/responses", "Handle timeouts gracefully"],
+                    constraints=[
+                        "Log all requests/responses",
+                        "Handle timeouts gracefully",
+                    ],
                 ),
                 Tool(
                     name="database_query",
@@ -201,6 +206,7 @@ class CodingDomain:
 # RESEARCH DOMAIN
 # =============================================================================
 
+
 class ResearchDomain:
     """Pre-built configurations for research and analysis agents."""
 
@@ -268,7 +274,10 @@ class ResearchDomain:
                     name="synthesis",
                     description="Combine multiple sources into insights",
                     tool_type=ToolType.ANALYSIS,
-                    constraints=["Note conflicting information", "Confidence levels required"],
+                    constraints=[
+                        "Note conflicting information",
+                        "Confidence levels required",
+                    ],
                 ),
             ],
             global_constraints=[
@@ -314,6 +323,7 @@ class ResearchDomain:
 # CONTENT DOMAIN
 # =============================================================================
 
+
 class ContentDomain:
     """Pre-built configurations for content creation agents."""
 
@@ -490,6 +500,7 @@ class ContentDomain:
 # OPERATIONS DOMAIN
 # =============================================================================
 
+
 class OperationsDomain:
     """Pre-built configurations for operations and support agents."""
 
@@ -636,6 +647,7 @@ class OperationsDomain:
 # FACTORY FUNCTION
 # =============================================================================
 
+
 def create_harness(
     domain: str,
     agent_type: str,
@@ -666,7 +678,9 @@ def create_harness(
             "victor": CodingDomain.create_victor,
         },
         "research": {
-            "researcher": lambda a: ResearchDomain.create_researcher(a, kwargs.get("focus", "general")),
+            "researcher": lambda a: ResearchDomain.create_researcher(
+                a, kwargs.get("focus", "general")
+            ),
         },
         "content": {
             "copywriter": ContentDomain.create_copywriter,
@@ -678,7 +692,9 @@ def create_harness(
     }
 
     if domain not in factories:
-        raise ValueError(f"Unknown domain: {domain}. Available: {list(factories.keys())}")
+        raise ValueError(
+            f"Unknown domain: {domain}. Available: {list(factories.keys())}"
+        )
 
     if agent_type not in factories[domain]:
         raise ValueError(

alma/initializer/__init__.py

@@ -22,12 +22,12 @@ Usage:
     '''
 """
 
+from alma.initializer.initializer import SessionInitializer
 from alma.initializer.types import (
     CodebaseOrientation,
     InitializationResult,
     RulesOfEngagement,
 )
-from alma.initializer.initializer import SessionInitializer
 
 __all__ = [
     "CodebaseOrientation",

alma/initializer/initializer.py

@@ -173,7 +173,7 @@ class SessionInitializer:
         work_items = []
 
         # Simple extraction: look for bullet points and numbered items
-        lines = user_prompt.strip().split('\n')
+        lines = user_prompt.strip().split("\n")
 
         for line in lines:
             line = line.strip()
@@ -181,25 +181,29 @@ class SessionInitializer:
                 continue
 
             # Match bullet points: -, *, •
-            bullet_match = re.match(r'^[-*•]\s+(.+)$', line)
+            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,
-                ))
+                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)
+            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,
-                ))
+                work_items.append(
+                    WorkItem.create(
+                        project_id="",
+                        title=title,
+                        description=title,
+                    )
+                )
                 continue
 
         # If no structured items found, create single item from prompt
@@ -209,11 +213,13 @@ class SessionInitializer:
             if len(user_prompt) > 100:
                 title += "..."
 
-            work_items.append(WorkItem.create(
-                project_id="",
-                title=title,
-                description=user_prompt,
-            ))
+            work_items.append(
+                WorkItem.create(
+                    project_id="",
+                    title=title,
+                    description=user_prompt,
+                )
+            )
 
         return work_items
 
@@ -261,7 +267,9 @@ class SessionInitializer:
                     timeout=5,
                 )
                 if result.returncode == 0:
-                    orientation.current_branch = result.stdout.strip() or "HEAD detached"
+                    orientation.current_branch = (
+                        result.stdout.strip() or "HEAD detached"
+                    )
 
                 # Check for uncommitted changes
                 result = subprocess.run(
@@ -283,7 +291,7 @@ class SessionInitializer:
                     timeout=5,
                 )
                 if result.returncode == 0:
-                    commits = result.stdout.strip().split('\n')
+                    commits = result.stdout.strip().split("\n")
                     orientation.recent_commits = [c for c in commits if c]
 
             except subprocess.TimeoutExpired:
@@ -293,18 +301,21 @@ class SessionInitializer:
 
         # 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()
-        ]
+        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()
+            "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)
@@ -336,14 +347,10 @@ class SessionInitializer:
 
         # Convert scope to rules
         if scope.can_learn:
-            rules.scope_rules = [
-                f"Learn from: {', '.join(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)}"
-            ]
+            rules.constraints = [f"Do not learn from: {', '.join(scope.cannot_learn)}"]
 
         # Default quality gates
         rules.quality_gates = [
@@ -359,7 +366,7 @@ class SessionInitializer:
         if len(work_items) == 1:
             return prompt
 
-        item_titles = [getattr(item, 'title', str(item)) for item in work_items]
+        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]:
@@ -369,17 +376,15 @@ class SessionInitializer:
 
         # Find highest priority unblocked item
         actionable = [
-            item for item in work_items
-            if getattr(item, 'status', 'pending') == 'pending'
-            and not getattr(item, 'blocked_by', [])
+            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
-            )
+            actionable.sort(key=lambda x: getattr(x, "priority", 50), reverse=True)
             return actionable[0]
 
         return work_items[0]
@@ -400,7 +405,10 @@ class SessionInitializer:
             # 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:
+            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")

alma/initializer/types.py

@@ -4,10 +4,10 @@ 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
-import uuid
 
 
 @dataclass
@@ -169,8 +169,8 @@ class InitializationResult:
         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')
+                title = getattr(item, "title", str(item))
+                status = getattr(item, "status", "pending")
                 sections.append(f"{i}. [{status}] {title}")
             sections.append("")
 
@@ -183,7 +183,7 @@ class InitializationResult:
         # Relevant memories
         if self.relevant_memories:
             sections.append("### Relevant Knowledge from Past Runs")
-            if hasattr(self.relevant_memories, 'to_prompt'):
+            if hasattr(self.relevant_memories, "to_prompt"):
                 sections.append(self.relevant_memories.to_prompt())
             else:
                 sections.append(str(self.relevant_memories))
@@ -198,7 +198,9 @@ class InitializationResult:
         # Recommended start
         if self.recommended_start:
             sections.append("### Recommended First Action")
-            title = getattr(self.recommended_start, 'title', str(self.recommended_start))
+            title = getattr(
+                self.recommended_start, "title", str(self.recommended_start)
+            )
             sections.append(f"Start with: {title}")
             sections.append("")
 
@@ -214,18 +216,22 @@ class InitializationResult:
             "original_prompt": self.original_prompt,
             "goal": self.goal,
             "work_items": [
-                item.to_dict() if hasattr(item, 'to_dict') else str(item)
+                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,
+            "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,
@@ -234,8 +240,10 @@ class InitializationResult:
             },
             "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
+                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(