mcal-ai 0.1.0__py3-none-any.whl

mcal/__init__.py

@@ -0,0 +1,165 @@
+"""
+MCAL: Memory-Context Alignment Layer
+
+A standalone memory architecture for AI agents that preserves:
+- Intent graphs (goal hierarchies)
+- Reasoning chains (decision rationale)
+- Goal-aware retrieval (objective-based context)
+
+Usage:
+    from mcal import MCAL
+    
+    mcal = MCAL(
+        openai_api_key="..."  # or anthropic_api_key, or use bedrock
+    )
+    
+    # Add conversation
+    result = await mcal.add(messages, user_id="user_123")
+    
+    # Search with goal-awareness
+    context = await mcal.get_context("What's next?", user_id="user_123")
+"""
+
+__version__ = "0.1.0"
+
+# Main interface
+from .mcal import MCAL, AddResult, SearchResult, TimingMetrics, TieredBedrockProvider
+
+# Core models
+from .core.models import (
+    DecisionTrail,
+    IntentGraph,
+    IntentNode,
+    IntentStatus,
+    IntentType,
+    Memory,
+    MemoryType,
+    RetrievalConfig,
+    RetrievalResult,
+    Session,
+    Turn,
+)
+
+# Core components (for advanced usage)
+from .core.intent_tracker import IntentTracker
+from .core.reasoning_store import ReasoningStore
+from .core.goal_retriever import GoalRetriever, ContextAssembler
+
+# Streaming API (Issue #10)
+from .core.streaming import (
+    StreamEvent,
+    StreamEventType,
+    ExtractionPhase,
+    StreamProgress,
+    CacheHitInfo,
+    PhaseResult,
+)
+
+# Backends (MemoryEntry kept for compatibility)
+from .backends import (
+    MemoryBackend,
+    MemoryEntry,
+)
+
+# Deprecated: Mem0Backend and StandaloneBackend (Issue #53)
+# Use: from mcal.backends import Mem0Backend (requires pip install mcal[mem0])
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main interface
+    "MCAL",
+    "AddResult",
+    "SearchResult",
+    # Models
+    "DecisionTrail",
+    "IntentGraph",
+    "IntentNode",
+    "IntentStatus",
+    "IntentType",
+    "Memory",
+    "MemoryType",
+    "RetrievalConfig",
+    "RetrievalResult",
+    "Session",
+    "Turn",
+    # Core components
+    "IntentTracker",
+    "ReasoningStore",
+    "GoalRetriever",
+    "ContextAssembler",
+    # Backends (for advanced usage)
+    "MemoryBackend",
+    "MemoryEntry",
+    # Streaming (Issue #10)
+    "StreamEvent",
+    "StreamEventType",
+    "ExtractionPhase",
+    "StreamProgress",
+    "CacheHitInfo",
+    "PhaseResult",
+    # Integrations namespace
+    "integrations",
+    # Integration shortcuts (lazy loaded)
+    "LangGraphMemory",
+    "LangGraphStore",
+    "CrewAIMemory",
+    "AutoGenMemory",
+    "LangChainMemory",
+]
+
+
+# Lazy loading for integration shortcuts
+def __getattr__(name: str):
+    """Lazy load integration classes to avoid import errors."""
+    import importlib
+    
+    if name == "integrations":
+        return importlib.import_module("mcal.integrations")
+    
+    if name == "LangGraphMemory":
+        try:
+            mod = importlib.import_module("mcal.integrations.langgraph")
+            return mod.MCALMemory
+        except ImportError:
+            raise ImportError(
+                "LangGraph integration requires: pip install mcal[langgraph]"
+            )
+    
+    if name == "LangGraphStore":
+        try:
+            mod = importlib.import_module("mcal.integrations.langgraph")
+            return mod.MCALStore
+        except ImportError:
+            raise ImportError(
+                "LangGraph integration requires: pip install mcal[langgraph]"
+            )
+    
+    if name == "CrewAIMemory":
+        try:
+            mod = importlib.import_module("mcal.integrations.crewai")
+            return mod.MCALCrewMemory
+        except ImportError:
+            raise ImportError(
+                "CrewAI integration requires: pip install mcal[crewai]"
+            )
+    
+    if name == "AutoGenMemory":
+        try:
+            mod = importlib.import_module("mcal.integrations.autogen")
+            return mod.MCALMemoryAgent
+        except ImportError:
+            raise ImportError(
+                "AutoGen integration requires: pip install mcal[autogen]"
+            )
+    
+    if name == "LangChainMemory":
+        try:
+            mod = importlib.import_module("mcal.integrations.langchain")
+            return mod.MCALChatMemory
+        except ImportError:
+            raise ImportError(
+                "LangChain integration requires: pip install mcal[langchain]"
+            )
+    
+    raise AttributeError(f"module 'mcal' has no attribute '{name}'")

mcal/backends/__init__.py

@@ -0,0 +1,42 @@
+"""MCAL Memory Backends.
+
+Issue #53: Mem0Backend and StandaloneBackend are deprecated.
+MCAL is now standalone and doesn't require external backends.
+These are kept for backward compatibility.
+"""
+
+from .base import (
+    MemoryBackend,
+    MemoryEntry,
+)
+
+# Deprecated backends - import lazily to avoid requiring mem0ai
+def __getattr__(name):
+    if name == "Mem0Backend":
+        import warnings
+        warnings.warn(
+            "Mem0Backend is deprecated. MCAL v1.0 is fully standalone. "
+            "Install with 'pip install mcal[mem0]' if needed.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        from .base import Mem0Backend
+        return Mem0Backend
+    elif name == "StandaloneBackend":
+        import warnings
+        warnings.warn(
+            "StandaloneBackend is deprecated. MCAL v1.0 is fully standalone.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        from .base import StandaloneBackend
+        return StandaloneBackend
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__all__ = [
+    "MemoryBackend",
+    "MemoryEntry",
+    # Deprecated (Issue #53)
+    "Mem0Backend",
+    "StandaloneBackend",
+]

mcal/backends/base.py

@@ -0,0 +1,383 @@
+"""
+Memory Backends
+
+Abstracts the underlying memory storage to allow pluggable backends.
+Default implementation uses Mem0 for fact storage.
+
+MCAL adds reasoning/intent layers ON TOP of these backends.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field
+
+
+def _utc_now() -> datetime:
+    """Return current UTC time (timezone-aware)."""
+    return datetime.now(timezone.utc)
+
+
+# =============================================================================
+# Backend Protocol / Abstract Base
+# =============================================================================
+
+class MemoryEntry(BaseModel):
+    """Standardized memory entry across backends."""
+    id: str
+    content: str
+    metadata: dict = Field(default_factory=dict)
+    score: Optional[float] = None  # Relevance score from search
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+class MemoryBackend(ABC):
+    """
+    Abstract base for memory backends.
+    
+    MCAL can work with different backends:
+    - Mem0Backend (default, recommended)
+    - StandaloneBackend (for testing or simple use cases)
+    - Custom backends (implement this interface)
+    """
+    
+    @abstractmethod
+    def add(
+        self,
+        messages: list[dict],
+        user_id: str,
+        metadata: Optional[dict] = None
+    ) -> list[MemoryEntry]:
+        """
+        Add messages to memory, extracting facts.
+        
+        Args:
+            messages: List of message dicts [{"role": "user", "content": "..."}]
+            user_id: User identifier
+            metadata: Optional metadata to attach
+            
+        Returns:
+            List of extracted/stored memory entries
+        """
+        pass
+    
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 10
+    ) -> list[MemoryEntry]:
+        """
+        Search memories by semantic similarity.
+        
+        Args:
+            query: Search query
+            user_id: User identifier
+            limit: Maximum results to return
+            
+        Returns:
+            List of relevant memory entries with scores
+        """
+        pass
+    
+    @abstractmethod
+    def get_all(self, user_id: str) -> list[MemoryEntry]:
+        """Get all memories for a user."""
+        pass
+    
+    @abstractmethod
+    def delete(self, memory_id: str) -> bool:
+        """Delete a specific memory."""
+        pass
+    
+    @abstractmethod
+    def delete_all(self, user_id: str) -> bool:
+        """Delete all memories for a user."""
+        pass
+
+
+# =============================================================================
+# Mem0 Backend Implementation
+# =============================================================================
+
+class Mem0Backend(MemoryBackend):
+    """
+    Mem0-based memory backend.
+    
+    Leverages Mem0's production-ready infrastructure:
+    - Intelligent fact extraction
+    - Vector + Graph + Key-Value storage
+    - Deduplication and conflict resolution
+    - 90% token reduction
+    
+    MCAL adds reasoning/intent layers on top.
+    
+    Usage:
+        backend = Mem0Backend(config={
+            "llm": {"provider": "anthropic", "config": {"model": "claude-3-5-sonnet"}},
+            "embedder": {"provider": "openai", "config": {"model": "text-embedding-3-small"}}
+        })
+        
+        # Or with API key for hosted Mem0
+        backend = Mem0Backend(api_key="your-mem0-api-key")
+    """
+    
+    def __init__(
+        self,
+        config: Optional[dict] = None,
+        api_key: Optional[str] = None
+    ):
+        """
+        Initialize Mem0 backend.
+        
+        Args:
+            config: Mem0 configuration dict (for self-hosted)
+            api_key: Mem0 API key (for hosted service)
+        """
+        try:
+            from mem0 import Memory, MemoryClient
+        except ImportError:
+            raise ImportError(
+                "mem0ai is required for Mem0Backend. "
+                "Install with: pip install mem0ai"
+            )
+        
+        if api_key:
+            # Use hosted Mem0 service
+            self._client = MemoryClient(api_key=api_key)
+            self._is_hosted = True
+        else:
+            # Use self-hosted Mem0
+            self._client = Memory.from_config(config or self._default_config())
+            self._is_hosted = False
+    
+    def _default_config(self) -> dict:
+        """Default Mem0 configuration using HuggingFace for local embeddings."""
+        return {
+            "llm": {
+                "provider": "aws_bedrock",
+                "config": {
+                    "model": "us.meta.llama3-3-70b-instruct-v1:0",
+                    "temperature": 0.1,
+                }
+            },
+            "embedder": {
+                "provider": "huggingface",
+                "config": {
+                    "model": "sentence-transformers/all-MiniLM-L6-v2"
+                }
+            },
+            "vector_store": {
+                "provider": "faiss",
+                "config": {
+                    "embedding_model_dims": 384,  # all-MiniLM-L6-v2 dimension
+                    "path": "/tmp/mcal_faiss"
+                }
+            }
+        }
+    
+    def add(
+        self,
+        messages: list[dict],
+        user_id: str,
+        metadata: Optional[dict] = None
+    ) -> list[MemoryEntry]:
+        """Add messages to Mem0, extracting facts."""
+        result = self._client.add(
+            messages=messages,
+            user_id=user_id,
+            metadata=metadata or {}
+        )
+        
+        # Convert Mem0 response to standardized format
+        entries = []
+        
+        # Handle different Mem0 response formats
+        if isinstance(result, dict):
+            results_list = result.get("results", result.get("memories", []))
+        elif isinstance(result, list):
+            results_list = result
+        else:
+            results_list = []
+        
+        for item in results_list:
+            if isinstance(item, dict):
+                entries.append(MemoryEntry(
+                    id=item.get("id", ""),
+                    content=item.get("memory", item.get("content", "")),
+                    metadata=item.get("metadata", {}),
+                    created_at=item.get("created_at"),
+                    updated_at=item.get("updated_at")
+                ))
+        
+        return entries
+    
+    def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 10
+    ) -> list[MemoryEntry]:
+        """Search Mem0 memories by semantic similarity."""
+        result = self._client.search(
+            query=query,
+            user_id=user_id,
+            limit=limit
+        )
+        
+        # Convert to standardized format
+        entries = []
+        
+        if isinstance(result, dict):
+            results_list = result.get("results", result.get("memories", []))
+        elif isinstance(result, list):
+            results_list = result
+        else:
+            results_list = []
+        
+        for item in results_list:
+            if isinstance(item, dict):
+                entries.append(MemoryEntry(
+                    id=item.get("id", ""),
+                    content=item.get("memory", item.get("content", "")),
+                    metadata=item.get("metadata") or {},
+                    score=item.get("score", item.get("similarity", 0.0))
+                ))
+        
+        return entries
+    
+    def get_all(self, user_id: str) -> list[MemoryEntry]:
+        """Get all memories for a user from Mem0."""
+        result = self._client.get_all(user_id=user_id)
+        
+        entries = []
+        if isinstance(result, dict):
+            results_list = result.get("results", result.get("memories", []))
+        elif isinstance(result, list):
+            results_list = result
+        else:
+            results_list = []
+        
+        for item in results_list:
+            if isinstance(item, dict):
+                entries.append(MemoryEntry(
+                    id=item.get("id", ""),
+                    content=item.get("memory", item.get("content", "")),
+                    metadata=item.get("metadata", {})
+                ))
+        
+        return entries
+    
+    def delete(self, memory_id: str) -> bool:
+        """Delete a specific memory from Mem0."""
+        try:
+            self._client.delete(memory_id=memory_id)
+            return True
+        except Exception:
+            return False
+    
+    def delete_all(self, user_id: str) -> bool:
+        """Delete all memories for a user from Mem0."""
+        try:
+            self._client.delete_all(user_id=user_id)
+            return True
+        except Exception:
+            return False
+
+
+# =============================================================================
+# Standalone Backend (for testing / simple use)
+# =============================================================================
+
+class StandaloneBackend(MemoryBackend):
+    """
+    Simple in-memory backend for testing or lightweight use.
+    
+    Does NOT have Mem0's intelligent extraction - just stores raw content.
+    Useful for:
+    - Unit testing
+    - Development without API keys
+    - Simple use cases
+    
+    For production, use Mem0Backend.
+    """
+    
+    def __init__(self):
+        self._memories: dict[str, dict[str, MemoryEntry]] = {}  # user_id -> {memory_id -> entry}
+        self._counter = 0
+    
+    def add(
+        self,
+        messages: list[dict],
+        user_id: str,
+        metadata: Optional[dict] = None
+    ) -> list[MemoryEntry]:
+        """Store messages as simple memories (no intelligent extraction)."""
+        if user_id not in self._memories:
+            self._memories[user_id] = {}
+        
+        entries = []
+        for msg in messages:
+            self._counter += 1
+            memory_id = f"mem_{self._counter}"
+            
+            entry = MemoryEntry(
+                id=memory_id,
+                content=msg.get("content", ""),
+                metadata={
+                    "role": msg.get("role", "unknown"),
+                    **(metadata or {})
+                },
+                created_at=_utc_now()
+            )
+            
+            self._memories[user_id][memory_id] = entry
+            entries.append(entry)
+        
+        return entries
+    
+    def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 10
+    ) -> list[MemoryEntry]:
+        """Simple keyword-based search (no semantic similarity)."""
+        if user_id not in self._memories:
+            return []
+        
+        query_lower = query.lower()
+        results = []
+        
+        for entry in self._memories[user_id].values():
+            if query_lower in entry.content.lower():
+                entry.score = 1.0  # Simple match
+                results.append(entry)
+        
+        return results[:limit]
+    
+    def get_all(self, user_id: str) -> list[MemoryEntry]:
+        """Get all memories for a user."""
+        if user_id not in self._memories:
+            return []
+        return list(self._memories[user_id].values())
+    
+    def delete(self, memory_id: str) -> bool:
+        """Delete a specific memory."""
+        for user_memories in self._memories.values():
+            if memory_id in user_memories:
+                del user_memories[memory_id]
+                return True
+        return False
+    
+    def delete_all(self, user_id: str) -> bool:
+        """Delete all memories for a user."""
+        if user_id in self._memories:
+            self._memories[user_id] = {}
+            return True
+        return False

mcal/baselines/__init__.py

@@ -0,0 +1 @@
+"""MCAL Baseline implementations for comparison."""

mcal/core/__init__.py

@@ -0,0 +1,101 @@
+"""MCAL Core Components"""
+
+from .models import (
+    DecisionTrail,
+    IntentGraph,
+    IntentNode,
+    IntentStatus,
+    IntentType,
+    Memory,
+    MemoryType,
+    RetrievalConfig,
+    RetrievalResult,
+    Session,
+    Turn,
+)
+from .intent_tracker import IntentTracker
+from .reasoning_store import ReasoningStore
+from .goal_retriever import GoalRetriever, ContextAssembler
+from .storage import MCALStorage
+from .extraction_cache import ExtractionCache, CacheStats, ExtractionState
+from .unified_extractor import (
+    UnifiedExtractor,
+    UnifiedGraph,
+    GraphNode,
+    GraphEdge,
+    NodeType,
+    EdgeType,
+    DeduplicationStrategy,
+    DeduplicationStats,
+    graph_to_memories,
+    memories_to_context_string,
+)
+from .streaming import (
+    StreamEvent,
+    StreamEventType,
+    ExtractionPhase,
+    StreamProgress,
+    CacheHitInfo,
+    PhaseResult,
+)
+from .embeddings import (
+    EmbeddingService,
+    embed_graph_nodes,
+    embedding_to_bytes,
+    bytes_to_embedding,
+    embedding_to_base64,
+    base64_to_embedding,
+    get_embedding_model,
+    clear_embedding_model,
+)
+from .vector_index import VectorIndex, build_index_from_nodes
+
+__all__ = [
+    "DecisionTrail",
+    "IntentGraph",
+    "IntentNode",
+    "IntentStatus",
+    "IntentType",
+    "Memory",
+    "MemoryType",
+    "RetrievalConfig",
+    "RetrievalResult",
+    "Session",
+    "Turn",
+    "IntentTracker",
+    "ReasoningStore",
+    "GoalRetriever",
+    "ContextAssembler",
+    "MCALStorage",
+    "ExtractionCache",
+    "CacheStats",
+    "ExtractionState",
+    # Unified Extractor (optimized)
+    "UnifiedExtractor",
+    "UnifiedGraph",
+    "GraphNode",
+    "GraphEdge",
+    "NodeType",
+    "EdgeType",
+    "graph_to_memories",
+    "memories_to_context_string",
+    # Streaming
+    "StreamEvent",
+    "StreamEventType",
+    "ExtractionPhase",
+    "StreamProgress",
+    "CacheHitInfo",
+    "PhaseResult",
+    # Embeddings (Issue #50)
+    "EmbeddingService",
+    "embed_graph_nodes",
+    "embedding_to_bytes",
+    "bytes_to_embedding",
+    "embedding_to_base64",
+    "base64_to_embedding",
+    "get_embedding_model",
+    "clear_embedding_model",
+    # Vector Search (Issue #51)
+    "VectorIndex",
+    "build_index_from_nodes",
+]