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

alma/domains/schemas.py

@@ -0,0 +1,434 @@
+"""
+Pre-built Domain Schemas.
+
+Standard domain schemas for common use cases.
+"""
+
+from alma.domains.types import DomainSchema, EntityType, RelationshipType
+
+
+def get_coding_schema() -> DomainSchema:
+    """
+    Pre-built schema for coding workflows.
+
+    This is the formalized version of ALMA's original Helena/Victor schema.
+    Suitable for: Frontend testing, backend testing, general development.
+    """
+    schema = DomainSchema.create(
+        name="coding",
+        description="Memory schema for software development workflows",
+        learning_categories=[
+            "testing_strategies",
+            "selector_patterns",
+            "api_design_patterns",
+            "error_handling",
+            "performance_optimization",
+            "debugging_techniques",
+            "code_review_patterns",
+            "refactoring_strategies",
+        ],
+    )
+
+    # Entity types
+    schema.add_entity_type(
+        name="feature",
+        description="A software feature or capability",
+        attributes=["status", "tests", "files", "priority", "owner"],
+    )
+    schema.add_entity_type(
+        name="bug",
+        description="A software defect or issue",
+        attributes=["severity", "reproduction_steps", "fix", "status", "root_cause"],
+    )
+    schema.add_entity_type(
+        name="test",
+        description="A test case or test suite",
+        attributes=["type", "status", "coverage", "flaky", "last_run"],
+    )
+    schema.add_entity_type(
+        name="component",
+        description="A code component or module",
+        attributes=["path", "type", "dependencies", "tests"],
+    )
+    schema.add_entity_type(
+        name="api_endpoint",
+        description="An API endpoint",
+        attributes=["method", "path", "request_schema", "response_schema", "auth"],
+    )
+
+    # Relationships
+    schema.add_relationship_type(
+        name="tests",
+        description="Test covers a feature or component",
+        source_type="test",
+        target_type="feature",
+    )
+    schema.add_relationship_type(
+        name="fixes",
+        description="Commit or change fixes a bug",
+        source_type="feature",
+        target_type="bug",
+    )
+    schema.add_relationship_type(
+        name="depends_on",
+        description="Component depends on another component",
+        source_type="component",
+        target_type="component",
+    )
+    schema.add_relationship_type(
+        name="implements",
+        description="Component implements an API endpoint",
+        source_type="component",
+        target_type="api_endpoint",
+    )
+
+    return schema
+
+
+def get_research_schema() -> DomainSchema:
+    """
+    Pre-built schema for research workflows.
+
+    Suitable for: Literature review, hypothesis testing, academic research.
+    """
+    schema = DomainSchema.create(
+        name="research",
+        description="Memory schema for research and academic workflows",
+        learning_categories=[
+            "literature_review_patterns",
+            "methodology_selection",
+            "data_analysis_strategies",
+            "citation_patterns",
+            "hypothesis_formulation",
+            "experiment_design",
+            "peer_review_patterns",
+            "synthesis_techniques",
+        ],
+    )
+
+    # Entity types
+    schema.add_entity_type(
+        name="paper",
+        description="An academic paper or article",
+        attributes=["title", "authors", "year", "citations", "abstract", "venue", "doi"],
+    )
+    schema.add_entity_type(
+        name="hypothesis",
+        description="A research hypothesis",
+        attributes=["statement", "confidence", "evidence_for", "evidence_against", "status"],
+    )
+    schema.add_entity_type(
+        name="experiment",
+        description="An experiment or study",
+        attributes=["method", "results", "conclusions", "status", "sample_size"],
+    )
+    schema.add_entity_type(
+        name="dataset",
+        description="A dataset used in research",
+        attributes=["name", "size", "format", "source", "license"],
+    )
+    schema.add_entity_type(
+        name="finding",
+        description="A research finding or insight",
+        attributes=["summary", "significance", "confidence", "supporting_evidence"],
+    )
+
+    # Relationships
+    schema.add_relationship_type(
+        name="cites",
+        description="Paper cites another paper",
+        source_type="paper",
+        target_type="paper",
+    )
+    schema.add_relationship_type(
+        name="tests",
+        description="Experiment tests a hypothesis",
+        source_type="experiment",
+        target_type="hypothesis",
+    )
+    schema.add_relationship_type(
+        name="uses",
+        description="Experiment uses a dataset",
+        source_type="experiment",
+        target_type="dataset",
+    )
+    schema.add_relationship_type(
+        name="supports",
+        description="Finding supports a hypothesis",
+        source_type="finding",
+        target_type="hypothesis",
+    )
+
+    return schema
+
+
+def get_sales_schema() -> DomainSchema:
+    """
+    Pre-built schema for sales workflows.
+
+    Suitable for: Lead management, customer conversations, deal tracking.
+    """
+    schema = DomainSchema.create(
+        name="sales",
+        description="Memory schema for sales and customer engagement workflows",
+        learning_categories=[
+            "objection_handling",
+            "closing_techniques",
+            "qualification_patterns",
+            "follow_up_timing",
+            "value_proposition",
+            "discovery_questions",
+            "relationship_building",
+            "negotiation_strategies",
+        ],
+    )
+
+    # Entity types
+    schema.add_entity_type(
+        name="lead",
+        description="A potential customer or prospect",
+        attributes=["stage", "value", "next_action", "source", "company", "title"],
+    )
+    schema.add_entity_type(
+        name="objection",
+        description="A customer objection or concern",
+        attributes=["type", "response", "outcome", "context"],
+    )
+    schema.add_entity_type(
+        name="conversation",
+        description="A customer interaction",
+        attributes=["channel", "sentiment", "result", "summary", "follow_up"],
+    )
+    schema.add_entity_type(
+        name="deal",
+        description="A sales deal or opportunity",
+        attributes=["stage", "value", "close_date", "probability", "stakeholders"],
+    )
+    schema.add_entity_type(
+        name="product",
+        description="A product or service being sold",
+        attributes=["name", "price", "features", "competitors"],
+    )
+
+    # Relationships
+    schema.add_relationship_type(
+        name="converts_to",
+        description="Lead converts to a deal",
+        source_type="lead",
+        target_type="deal",
+    )
+    schema.add_relationship_type(
+        name="raised",
+        description="Lead raised an objection",
+        source_type="lead",
+        target_type="objection",
+    )
+    schema.add_relationship_type(
+        name="had",
+        description="Lead had a conversation",
+        source_type="lead",
+        target_type="conversation",
+    )
+    schema.add_relationship_type(
+        name="interested_in",
+        description="Lead is interested in a product",
+        source_type="lead",
+        target_type="product",
+    )
+
+    return schema
+
+
+def get_general_schema() -> DomainSchema:
+    """
+    Minimal schema for general-purpose agents.
+
+    This is a flexible schema that can be extended for any domain.
+    Suitable for: General assistants, tool-using agents, custom workflows.
+    """
+    schema = DomainSchema.create(
+        name="general",
+        description="Minimal, flexible schema for general-purpose agents",
+        learning_categories=[
+            "task_patterns",
+            "error_recovery",
+            "tool_usage",
+            "efficiency_patterns",
+            "user_preferences",
+            "context_switching",
+        ],
+    )
+
+    # Entity types (minimal but extensible)
+    schema.add_entity_type(
+        name="task",
+        description="A unit of work to be completed",
+        attributes=["title", "status", "priority", "category"],
+    )
+    schema.add_entity_type(
+        name="resource",
+        description="A resource used or created",
+        attributes=["type", "path", "status", "metadata"],
+    )
+    schema.add_entity_type(
+        name="goal",
+        description="An objective or target",
+        attributes=["description", "status", "deadline", "progress"],
+    )
+    schema.add_entity_type(
+        name="context",
+        description="A context or environment state",
+        attributes=["name", "state", "active"],
+    )
+
+    # Relationships (minimal)
+    schema.add_relationship_type(
+        name="achieves",
+        description="Task contributes to a goal",
+        source_type="task",
+        target_type="goal",
+    )
+    schema.add_relationship_type(
+        name="uses",
+        description="Task uses a resource",
+        source_type="task",
+        target_type="resource",
+    )
+    schema.add_relationship_type(
+        name="requires",
+        description="Task requires a context",
+        source_type="task",
+        target_type="context",
+    )
+
+    return schema
+
+
+def get_customer_support_schema() -> DomainSchema:
+    """
+    Pre-built schema for customer support workflows.
+
+    Suitable for: Ticket handling, escalation, knowledge base management.
+    """
+    schema = DomainSchema.create(
+        name="customer_support",
+        description="Memory schema for customer support workflows",
+        learning_categories=[
+            "issue_classification",
+            "resolution_patterns",
+            "escalation_criteria",
+            "customer_sentiment",
+            "knowledge_retrieval",
+            "follow_up_patterns",
+            "edge_case_handling",
+        ],
+    )
+
+    # Entity types
+    schema.add_entity_type(
+        name="ticket",
+        description="A customer support ticket",
+        attributes=["status", "priority", "category", "customer_id", "resolution"],
+    )
+    schema.add_entity_type(
+        name="article",
+        description="A knowledge base article",
+        attributes=["title", "content", "category", "views", "helpful_votes"],
+    )
+    schema.add_entity_type(
+        name="customer",
+        description="A customer profile",
+        attributes=["tier", "history", "sentiment", "preferences"],
+    )
+    schema.add_entity_type(
+        name="issue",
+        description="A known issue or problem",
+        attributes=["description", "status", "workaround", "affected_customers"],
+    )
+
+    # Relationships
+    schema.add_relationship_type(
+        name="resolves",
+        description="Article resolves a ticket",
+        source_type="article",
+        target_type="ticket",
+    )
+    schema.add_relationship_type(
+        name="submitted_by",
+        description="Ticket submitted by customer",
+        source_type="ticket",
+        target_type="customer",
+    )
+    schema.add_relationship_type(
+        name="related_to",
+        description="Ticket related to a known issue",
+        source_type="ticket",
+        target_type="issue",
+    )
+
+    return schema
+
+
+def get_content_creation_schema() -> DomainSchema:
+    """
+    Pre-built schema for content creation workflows.
+
+    Suitable for: Blog writing, social media, marketing content.
+    """
+    schema = DomainSchema.create(
+        name="content_creation",
+        description="Memory schema for content creation workflows",
+        learning_categories=[
+            "writing_patterns",
+            "engagement_optimization",
+            "audience_targeting",
+            "seo_strategies",
+            "content_formatting",
+            "voice_and_tone",
+            "visual_content_patterns",
+        ],
+    )
+
+    # Entity types
+    schema.add_entity_type(
+        name="content",
+        description="A piece of content",
+        attributes=["type", "title", "status", "platform", "performance_metrics"],
+    )
+    schema.add_entity_type(
+        name="audience",
+        description="A target audience segment",
+        attributes=["name", "demographics", "interests", "pain_points"],
+    )
+    schema.add_entity_type(
+        name="campaign",
+        description="A content campaign",
+        attributes=["name", "goal", "start_date", "end_date", "budget"],
+    )
+    schema.add_entity_type(
+        name="template",
+        description="A content template",
+        attributes=["type", "structure", "usage_count", "effectiveness"],
+    )
+
+    # Relationships
+    schema.add_relationship_type(
+        name="targets",
+        description="Content targets an audience",
+        source_type="content",
+        target_type="audience",
+    )
+    schema.add_relationship_type(
+        name="part_of",
+        description="Content is part of a campaign",
+        source_type="content",
+        target_type="campaign",
+    )
+    schema.add_relationship_type(
+        name="uses",
+        description="Content uses a template",
+        source_type="content",
+        target_type="template",
+    )
+
+    return schema

alma/domains/types.py

@@ -0,0 +1,268 @@
+"""
+Domain Memory Types.
+
+Data models for domain-specific memory schemas.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import List, Dict, Any, Optional
+import uuid
+
+
+@dataclass
+class EntityType:
+    """
+    A type of entity in a domain.
+
+    Entities are the "things" that agents work with in a domain.
+    For example: features, bugs, tests (coding), papers, hypotheses (research).
+    """
+
+    name: str  # "feature", "test", "paper", "lead"
+    description: str
+    attributes: List[str] = field(default_factory=list)  # ["status", "priority", "owner"]
+
+    # Optional schema validation
+    required_attributes: List[str] = field(default_factory=list)
+    attribute_types: Dict[str, str] = field(default_factory=dict)  # attr -> "str", "int", "bool"
+
+    def validate_entity(self, entity: Dict[str, Any]) -> List[str]:
+        """Validate an entity instance against this type."""
+        errors = []
+        for attr in self.required_attributes:
+            if attr not in entity:
+                errors.append(f"Missing required attribute: {attr}")
+        return errors
+
+
+@dataclass
+class RelationshipType:
+    """
+    A relationship between entities in a domain.
+
+    Relationships connect entities (e.g., "feature implements spec").
+    """
+
+    name: str  # "implements", "blocks", "supports", "cites"
+    description: str
+    source_type: str  # Entity type name
+    target_type: str  # Entity type name
+
+    # Cardinality
+    many_to_many: bool = True
+    required: bool = False
+
+
+@dataclass
+class DomainSchema:
+    """
+    Defines memory structure for a specific domain.
+
+    A schema describes what entities exist in a domain, how they relate,
+    and what learning categories agents can use.
+    """
+
+    id: str
+    name: str  # "coding", "research", "sales"
+    description: str
+
+    # What entities exist in this domain
+    entity_types: List[EntityType] = field(default_factory=list)
+
+    # What relationships between entities
+    relationship_types: List[RelationshipType] = field(default_factory=list)
+
+    # Learning categories (replaces hardcoded HELENA_CATEGORIES)
+    learning_categories: List[str] = field(default_factory=list)
+
+    # What can agents in this domain NOT learn (scoping)
+    excluded_categories: List[str] = field(default_factory=list)
+
+    # Domain-specific settings
+    min_occurrences_for_heuristic: int = 3
+    confidence_decay_days: float = 30.0
+
+    # 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,
+        name: str,
+        description: str,
+        learning_categories: Optional[List[str]] = None,
+        **kwargs,
+    ) -> "DomainSchema":
+        """Factory method to create a new domain schema."""
+        return cls(
+            id=str(uuid.uuid4()),
+            name=name,
+            description=description,
+            learning_categories=learning_categories or [],
+            **kwargs,
+        )
+
+    def add_entity_type(
+        self,
+        name: str,
+        description: str,
+        attributes: Optional[List[str]] = None,
+    ) -> EntityType:
+        """Add an entity type to this schema."""
+        entity = EntityType(
+            name=name,
+            description=description,
+            attributes=attributes or [],
+        )
+        self.entity_types.append(entity)
+        self.updated_at = datetime.now(timezone.utc)
+        return entity
+
+    def add_relationship_type(
+        self,
+        name: str,
+        description: str,
+        source_type: str,
+        target_type: str,
+    ) -> RelationshipType:
+        """Add a relationship type to this schema."""
+        rel = RelationshipType(
+            name=name,
+            description=description,
+            source_type=source_type,
+            target_type=target_type,
+        )
+        self.relationship_types.append(rel)
+        self.updated_at = datetime.now(timezone.utc)
+        return rel
+
+    def add_learning_category(self, category: str) -> None:
+        """Add a learning category."""
+        if category not in self.learning_categories:
+            self.learning_categories.append(category)
+            self.updated_at = datetime.now(timezone.utc)
+
+    def add_excluded_category(self, category: str) -> None:
+        """Add an excluded category (agent cannot learn from this)."""
+        if category not in self.excluded_categories:
+            self.excluded_categories.append(category)
+            self.updated_at = datetime.now(timezone.utc)
+
+    def get_entity_type(self, name: str) -> Optional[EntityType]:
+        """Get entity type by name."""
+        for entity in self.entity_types:
+            if entity.name == name:
+                return entity
+        return None
+
+    def get_relationship_type(self, name: str) -> Optional[RelationshipType]:
+        """Get relationship type by name."""
+        for rel in self.relationship_types:
+            if rel.name == name:
+                return rel
+        return None
+
+    def is_category_allowed(self, category: str) -> bool:
+        """Check if a learning category is allowed in this domain."""
+        if self.learning_categories and category not in self.learning_categories:
+            return False
+        if category in self.excluded_categories:
+            return False
+        return True
+
+    def validate(self) -> List[str]:
+        """Validate the schema for consistency."""
+        errors = []
+
+        # Check relationship source/target types exist
+        entity_names = {e.name for e in self.entity_types}
+        for rel in self.relationship_types:
+            if rel.source_type not in entity_names:
+                errors.append(
+                    f"Relationship '{rel.name}' references unknown source type: {rel.source_type}"
+                )
+            if rel.target_type not in entity_names:
+                errors.append(
+                    f"Relationship '{rel.name}' references unknown target type: {rel.target_type}"
+                )
+
+        # Check for duplicate entity names
+        seen_names = set()
+        for entity in self.entity_types:
+            if entity.name in seen_names:
+                errors.append(f"Duplicate entity type name: {entity.name}")
+            seen_names.add(entity.name)
+
+        return errors
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert schema to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "entity_types": [
+                {
+                    "name": e.name,
+                    "description": e.description,
+                    "attributes": e.attributes,
+                }
+                for e in self.entity_types
+            ],
+            "relationship_types": [
+                {
+                    "name": r.name,
+                    "description": r.description,
+                    "source_type": r.source_type,
+                    "target_type": r.target_type,
+                }
+                for r in self.relationship_types
+            ],
+            "learning_categories": self.learning_categories,
+            "excluded_categories": self.excluded_categories,
+            "min_occurrences_for_heuristic": self.min_occurrences_for_heuristic,
+            "confidence_decay_days": self.confidence_decay_days,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DomainSchema":
+        """Create schema from dictionary."""
+        entity_types = [
+            EntityType(
+                name=e["name"],
+                description=e["description"],
+                attributes=e.get("attributes", []),
+            )
+            for e in data.get("entity_types", [])
+        ]
+
+        relationship_types = [
+            RelationshipType(
+                name=r["name"],
+                description=r["description"],
+                source_type=r["source_type"],
+                target_type=r["target_type"],
+            )
+            for r in data.get("relationship_types", [])
+        ]
+
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            name=data["name"],
+            description=data["description"],
+            entity_types=entity_types,
+            relationship_types=relationship_types,
+            learning_categories=data.get("learning_categories", []),
+            excluded_categories=data.get("excluded_categories", []),
+            min_occurrences_for_heuristic=data.get("min_occurrences_for_heuristic", 3),
+            confidence_decay_days=data.get("confidence_decay_days", 30.0),
+            metadata=data.get("metadata", {}),
+        )