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

alma/__init__.py

@@ -14,7 +14,7 @@ This makes any tool-using agent appear to "learn" by injecting relevant
 memory slices before each run and updating memory after.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 # Core
 from alma.core import ALMA
@@ -47,6 +47,35 @@ from alma.harness.domains import (
     create_harness,
 )
 
+# Progress Tracking (Phase 10)
+from alma.progress import (
+    WorkItem,
+    WorkItemStatus,
+    ProgressLog,
+    ProgressSummary,
+    ProgressTracker,
+)
+
+# Session Management (Phase 10)
+from alma.session import (
+    SessionHandoff,
+    SessionContext,
+    SessionOutcome,
+    SessionManager,
+)
+
+# Domain Memory Factory (Phase 10)
+from alma.domains import (
+    DomainSchema,
+    EntityType,
+    RelationshipType,
+    DomainMemoryFactory,
+    get_coding_schema,
+    get_research_schema,
+    get_sales_schema,
+    get_general_schema,
+)
+
 __all__ = [
     # Core
     "ALMA",
@@ -72,4 +101,24 @@ __all__ = [
     "ContentDomain",
     "OperationsDomain",
     "create_harness",
+    # Progress Tracking
+    "WorkItem",
+    "WorkItemStatus",
+    "ProgressLog",
+    "ProgressSummary",
+    "ProgressTracker",
+    # Session Management
+    "SessionHandoff",
+    "SessionContext",
+    "SessionOutcome",
+    "SessionManager",
+    # Domain Memory Factory
+    "DomainSchema",
+    "EntityType",
+    "RelationshipType",
+    "DomainMemoryFactory",
+    "get_coding_schema",
+    "get_research_schema",
+    "get_sales_schema",
+    "get_general_schema",
 ]

alma/domains/__init__.py

@@ -0,0 +1,30 @@
+"""
+ALMA Domain Memory Module.
+
+Provides domain-agnostic memory schemas and factory pattern
+for creating domain-specific ALMA instances.
+"""
+
+from alma.domains.types import (
+    DomainSchema,
+    EntityType,
+    RelationshipType,
+)
+from alma.domains.factory import DomainMemoryFactory
+from alma.domains.schemas import (
+    get_coding_schema,
+    get_research_schema,
+    get_sales_schema,
+    get_general_schema,
+)
+
+__all__ = [
+    "DomainSchema",
+    "EntityType",
+    "RelationshipType",
+    "DomainMemoryFactory",
+    "get_coding_schema",
+    "get_research_schema",
+    "get_sales_schema",
+    "get_general_schema",
+]

alma/domains/factory.py

@@ -0,0 +1,356 @@
+"""
+Domain Memory Factory.
+
+Factory pattern for creating domain-specific ALMA instances.
+"""
+
+from typing import Dict, Any, Optional, List, Type
+import logging
+
+from alma.domains.types import DomainSchema, EntityType, RelationshipType
+from alma.domains.schemas import (
+    get_coding_schema,
+    get_research_schema,
+    get_sales_schema,
+    get_general_schema,
+    get_customer_support_schema,
+    get_content_creation_schema,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class DomainMemoryFactory:
+    """
+    Factory for creating domain-specific ALMA instances.
+
+    Provides:
+    - Pre-built schemas for common domains
+    - Custom schema creation from config
+    - ALMA instance creation with domain-specific settings
+
+    Usage:
+        # Use pre-built schema
+        factory = DomainMemoryFactory()
+        schema = factory.get_schema("coding")
+        alma = factory.create_alma(schema, "my-project", storage)
+
+        # Create custom schema
+        schema = factory.create_schema("my-domain", {
+            "description": "Custom domain",
+            "entity_types": [...],
+            "learning_categories": [...]
+        })
+    """
+
+    # Registry of pre-built schemas
+    _builtin_schemas: Dict[str, callable] = {
+        "coding": get_coding_schema,
+        "research": get_research_schema,
+        "sales": get_sales_schema,
+        "general": get_general_schema,
+        "customer_support": get_customer_support_schema,
+        "content_creation": get_content_creation_schema,
+    }
+
+    # Custom schema registry (for user-defined schemas)
+    _custom_schemas: Dict[str, DomainSchema] = {}
+
+    def __init__(self):
+        """Initialize the factory."""
+        pass
+
+    @classmethod
+    def list_schemas(cls) -> List[str]:
+        """List all available schema names (built-in and custom)."""
+        return list(cls._builtin_schemas.keys()) + list(cls._custom_schemas.keys())
+
+    @classmethod
+    def get_schema(cls, name: str) -> Optional[DomainSchema]:
+        """
+        Get a schema by name.
+
+        Args:
+            name: Schema name (e.g., "coding", "research")
+
+        Returns:
+            DomainSchema or None if not found
+        """
+        # Check custom schemas first
+        if name in cls._custom_schemas:
+            return cls._custom_schemas[name]
+
+        # Check built-in schemas
+        if name in cls._builtin_schemas:
+            return cls._builtin_schemas[name]()
+
+        return None
+
+    @classmethod
+    def create_schema(
+        cls,
+        name: str,
+        config: Dict[str, Any],
+        register: bool = True,
+    ) -> DomainSchema:
+        """
+        Create a new domain schema from configuration.
+
+        Args:
+            name: Schema name
+            config: Schema configuration dictionary
+            register: If True, register schema for later retrieval
+
+        Config format:
+            {
+                "description": "Schema description",
+                "entity_types": [
+                    {"name": "entity1", "description": "...", "attributes": ["a", "b"]}
+                ],
+                "relationship_types": [
+                    {"name": "rel1", "description": "...", "source": "e1", "target": "e2"}
+                ],
+                "learning_categories": ["cat1", "cat2"],
+                "excluded_categories": ["cat3"],
+                "min_occurrences_for_heuristic": 3,
+                "confidence_decay_days": 30.0
+            }
+
+        Returns:
+            Created DomainSchema
+        """
+        schema = DomainSchema.create(
+            name=name,
+            description=config.get("description", f"Custom schema: {name}"),
+            learning_categories=config.get("learning_categories", []),
+            excluded_categories=config.get("excluded_categories", []),
+            min_occurrences_for_heuristic=config.get("min_occurrences_for_heuristic", 3),
+            confidence_decay_days=config.get("confidence_decay_days", 30.0),
+        )
+
+        # Add entity types
+        for entity_config in config.get("entity_types", []):
+            schema.add_entity_type(
+                name=entity_config["name"],
+                description=entity_config.get("description", ""),
+                attributes=entity_config.get("attributes", []),
+            )
+
+        # Add relationship types
+        for rel_config in config.get("relationship_types", []):
+            schema.add_relationship_type(
+                name=rel_config["name"],
+                description=rel_config.get("description", ""),
+                source_type=rel_config.get("source_type", rel_config.get("source", "")),
+                target_type=rel_config.get("target_type", rel_config.get("target", "")),
+            )
+
+        # Validate
+        errors = schema.validate()
+        if errors:
+            logger.warning(f"Schema validation warnings for '{name}': {errors}")
+
+        # Register if requested
+        if register:
+            cls._custom_schemas[name] = schema
+            logger.info(f"Registered custom schema: {name}")
+
+        return schema
+
+    @classmethod
+    def register_schema(cls, schema: DomainSchema) -> None:
+        """Register an existing schema for later retrieval."""
+        cls._custom_schemas[schema.name] = schema
+        logger.info(f"Registered schema: {schema.name}")
+
+    @classmethod
+    def unregister_schema(cls, name: str) -> bool:
+        """Unregister a custom schema."""
+        if name in cls._custom_schemas:
+            del cls._custom_schemas[name]
+            return True
+        return False
+
+    def create_alma(
+        self,
+        schema: DomainSchema,
+        project_id: str,
+        storage: Optional[Any] = None,
+        embedding_provider: str = "mock",
+        **config,
+    ) -> Any:
+        """
+        Create ALMA instance configured for a domain.
+
+        Args:
+            schema: Domain schema to use
+            project_id: Project identifier
+            storage: Optional storage backend (FileBasedStorage created if None)
+            embedding_provider: Embedding provider ("mock", "local", "openai")
+            **config: Additional ALMA configuration
+
+        Returns:
+            Configured ALMA instance
+
+        Note:
+            This integrates with the core ALMA class.
+            The schema is used to:
+            - Configure allowed learning categories
+            - Set heuristic thresholds
+            - Initialize domain-specific entity tracking
+        """
+        # Import here to avoid circular dependency
+        from alma.storage.file_based import FileBasedStorage
+        from alma.retrieval import RetrievalEngine
+        from alma.learning import LearningProtocol
+        from alma.types import MemoryScope
+        from alma import ALMA
+
+        # Create storage if not provided
+        if storage is None:
+            import tempfile
+            from pathlib import Path
+            storage_dir = Path(tempfile.mkdtemp()) / ".alma" / project_id
+            storage = FileBasedStorage(storage_dir)
+
+        # Create retrieval engine
+        retrieval = RetrievalEngine(
+            storage=storage,
+            embedding_provider=embedding_provider,
+        )
+
+        # Create scope based on schema
+        default_agent = config.get("default_agent", "agent")
+        scopes = {
+            default_agent: MemoryScope(
+                agent_name=default_agent,
+                can_learn=schema.learning_categories,
+                cannot_learn=schema.excluded_categories,
+                min_occurrences_for_heuristic=schema.min_occurrences_for_heuristic,
+            )
+        }
+
+        # Create learning protocol
+        learning = LearningProtocol(
+            storage=storage,
+            scopes=scopes,
+        )
+
+        # Create ALMA instance
+        alma = ALMA(
+            storage=storage,
+            retrieval_engine=retrieval,
+            learning_protocol=learning,
+            scopes=scopes,
+            project_id=project_id,
+        )
+
+        # Store schema reference for domain-aware operations
+        alma._domain_schema = schema
+
+        logger.info(
+            f"Created ALMA instance for project '{project_id}' "
+            f"with domain schema '{schema.name}'"
+        )
+
+        return alma
+
+    def create_alma_for_agent(
+        self,
+        schema_name: str,
+        agent: str,
+        project_id: str,
+        storage: Optional[Any] = None,
+        scope_restrictions: Optional[List[str]] = None,
+        **config,
+    ) -> Any:
+        """
+        Create ALMA instance for a specific agent.
+
+        This is a convenience method that:
+        1. Gets the appropriate schema
+        2. Creates ALMA instance
+        3. Configures agent-specific settings
+
+        Args:
+            schema_name: Name of schema to use
+            agent: Agent identifier
+            project_id: Project identifier
+            storage: Optional storage backend
+            scope_restrictions: Categories agent cannot learn from
+            **config: Additional ALMA configuration
+
+        Returns:
+            Configured ALMA instance for the agent
+        """
+        schema = self.get_schema(schema_name)
+        if not schema:
+            raise ValueError(f"Unknown schema: {schema_name}")
+
+        # Apply scope restrictions
+        if scope_restrictions:
+            for cat in scope_restrictions:
+                schema.add_excluded_category(cat)
+
+        # Create ALMA with agent config
+        alma = self.create_alma(
+            schema=schema,
+            project_id=project_id,
+            storage=storage,
+            default_agent=agent,
+            **config,
+        )
+
+        return alma
+
+
+# Convenience functions for common patterns
+def create_coding_alma(
+    project_id: str,
+    agent: str = "developer",
+    storage: Optional[Any] = None,
+    **config,
+) -> Any:
+    """Create ALMA configured for coding workflows."""
+    factory = DomainMemoryFactory()
+    return factory.create_alma_for_agent(
+        schema_name="coding",
+        agent=agent,
+        project_id=project_id,
+        storage=storage,
+        **config,
+    )
+
+
+def create_research_alma(
+    project_id: str,
+    agent: str = "researcher",
+    storage: Optional[Any] = None,
+    **config,
+) -> Any:
+    """Create ALMA configured for research workflows."""
+    factory = DomainMemoryFactory()
+    return factory.create_alma_for_agent(
+        schema_name="research",
+        agent=agent,
+        project_id=project_id,
+        storage=storage,
+        **config,
+    )
+
+
+def create_general_alma(
+    project_id: str,
+    agent: str = "assistant",
+    storage: Optional[Any] = None,
+    **config,
+) -> Any:
+    """Create ALMA configured for general-purpose agents."""
+    factory = DomainMemoryFactory()
+    return factory.create_alma_for_agent(
+        schema_name="general",
+        agent=agent,
+        project_id=project_id,
+        storage=storage,
+        **config,
+    )