mcal-ai 0.1.0__py3-none-any.whl

mcal/core/vector_index.py

@@ -0,0 +1,206 @@
+"""
+Vector Index for MCAL Graph Nodes
+
+FAISS-based vector similarity search for semantic queries on graph nodes.
+
+Performance (from pre-implementation analysis):
+- Build time: <0.2ms for 1000 nodes
+- Search time: <0.04ms per query
+- Memory: ~1.5KB per node (normalized float32)
+
+Index Type: IndexFlatIP (Inner Product)
+- With normalized vectors = cosine similarity
+- Exact search (no approximation)
+- Perfect for small-medium graphs (<10K nodes)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Optional
+
+import numpy as np
+import faiss
+
+if TYPE_CHECKING:
+    from .unified_extractor import GraphNode
+
+logger = logging.getLogger(__name__)
+
+
+class VectorIndex:
+    """
+    FAISS-based vector index for graph nodes.
+    
+    Uses IndexFlatIP (inner product) with L2 normalization for cosine similarity.
+    Designed for graphs up to ~10K nodes where exact search is fast enough.
+    
+    Usage:
+        index = VectorIndex()
+        index.add_batch([(node_id, embedding_bytes), ...])
+        results = index.search(query_embedding, k=10)
+        # results = [(node_id, similarity_score), ...]
+    """
+    
+    DIMENSION = 384  # all-MiniLM-L6-v2 output dimension
+    
+    def __init__(self, dimension: int = DIMENSION):
+        """
+        Initialize empty FAISS index.
+        
+        Args:
+            dimension: Embedding dimension (default: 384 for MiniLM)
+        """
+        self.dimension = dimension
+        self.index = faiss.IndexFlatIP(dimension)  # Inner product for cosine sim
+        self._id_map: list[str] = []  # node_id at each index position
+        self._node_count = 0
+    
+    def add(self, node_id: str, embedding: bytes) -> None:
+        """
+        Add a single node embedding to the index.
+        
+        Args:
+            node_id: Unique identifier for the node
+            embedding: Float16 binary embedding (from GraphNode.embedding)
+        """
+        vec = self._bytes_to_normalized_vector(embedding)
+        self.index.add(vec.reshape(1, -1))
+        self._id_map.append(node_id)
+        self._node_count += 1
+    
+    def add_batch(self, nodes: list[tuple[str, bytes]]) -> None:
+        """
+        Add multiple node embeddings at once (4.7x faster than individual adds).
+        
+        Args:
+            nodes: List of (node_id, embedding_bytes) tuples
+        """
+        if not nodes:
+            return
+        
+        ids = []
+        vectors = []
+        
+        for node_id, embedding in nodes:
+            ids.append(node_id)
+            vectors.append(self._bytes_to_normalized_vector(embedding))
+        
+        # Stack and add to FAISS
+        vecs = np.vstack(vectors)
+        self.index.add(vecs)
+        self._id_map.extend(ids)
+        self._node_count += len(nodes)
+    
+    def search(
+        self, 
+        query_embedding: bytes, 
+        k: int = 10
+    ) -> list[tuple[str, float]]:
+        """
+        Search for k most similar nodes.
+        
+        Args:
+            query_embedding: Float16 binary embedding for query
+            k: Number of results to return
+            
+        Returns:
+            List of (node_id, similarity_score) tuples, sorted by score descending
+        """
+        if self._node_count == 0:
+            return []
+        
+        # Ensure we don't request more than we have
+        k = min(k, self._node_count)
+        
+        # Convert and normalize query
+        query_vec = self._bytes_to_normalized_vector(query_embedding)
+        
+        # Search
+        scores, indices = self.index.search(query_vec.reshape(1, -1), k)
+        
+        # Map indices back to node IDs
+        results = []
+        for score, idx in zip(scores[0], indices[0]):
+            if 0 <= idx < len(self._id_map):
+                results.append((self._id_map[idx], float(score)))
+        
+        return results
+    
+    def search_text(
+        self, 
+        query_text: str,
+        k: int = 10
+    ) -> list[tuple[str, float]]:
+        """
+        Search using text query (embeds the query first).
+        
+        Args:
+            query_text: Text to search for
+            k: Number of results
+            
+        Returns:
+            List of (node_id, similarity_score) tuples
+        """
+        from .embeddings import EmbeddingService
+        
+        service = EmbeddingService()
+        query_embedding = service.embed_text(query_text)
+        return self.search(query_embedding, k)
+    
+    def clear(self) -> None:
+        """Clear the index and reset state."""
+        self.index = faiss.IndexFlatIP(self.dimension)
+        self._id_map = []
+        self._node_count = 0
+    
+    def _bytes_to_normalized_vector(self, data: bytes) -> np.ndarray:
+        """
+        Convert Float16 bytes to normalized Float32 vector.
+        
+        FAISS requires float32, and we normalize for cosine similarity.
+        """
+        # Convert from Float16 bytes to Float32
+        vec = np.frombuffer(data, dtype=np.float16).astype(np.float32)
+        
+        # Normalize for cosine similarity (IndexFlatIP + normalized = cosine)
+        norm = np.linalg.norm(vec)
+        if norm > 0:
+            vec = vec / norm
+        
+        return vec
+    
+    def __len__(self) -> int:
+        """Return number of vectors in index."""
+        return self._node_count
+    
+    def __contains__(self, node_id: str) -> bool:
+        """Check if a node ID is in the index."""
+        return node_id in self._id_map
+
+
+def build_index_from_nodes(nodes: list["GraphNode"]) -> VectorIndex:
+    """
+    Build a VectorIndex from a list of graph nodes.
+    
+    Only includes nodes that have embeddings.
+    
+    Args:
+        nodes: List of GraphNode objects
+        
+    Returns:
+        VectorIndex populated with node embeddings
+    """
+    index = VectorIndex()
+    
+    nodes_with_embeddings = [
+        (node.id, node.embedding)
+        for node in nodes
+        if node.embedding is not None
+    ]
+    
+    if nodes_with_embeddings:
+        index.add_batch(nodes_with_embeddings)
+        logger.debug(f"Built index with {len(nodes_with_embeddings)} nodes")
+    
+    return index

mcal/evaluation/__init__.py

@@ -0,0 +1 @@
+"""MCAL Evaluation metrics and benchmarks."""

mcal/integrations/__init__.py

@@ -0,0 +1,88 @@
+"""
+MCAL Framework Integrations
+
+Provides seamless integration with popular AI agent frameworks.
+
+Installation:
+    pip install mcal[langgraph]    # LangGraph integration
+    pip install mcal[crewai]       # CrewAI integration
+    pip install mcal[autogen]      # AutoGen integration
+    pip install mcal[integrations] # All integrations
+
+Usage:
+    # Option 1: Explicit import (recommended)
+    from mcal.integrations.langgraph import MCALMemory
+    
+    # Option 2: Namespace access
+    from mcal import integrations
+    memory = integrations.langgraph.MCALMemory()
+    
+    # Option 3: Direct shortcut
+    from mcal import LangGraphMemory
+"""
+
+from typing import TYPE_CHECKING
+
+# Lazy imports to avoid loading dependencies until needed
+if TYPE_CHECKING:
+    from mcal.integrations import langgraph
+    from mcal.integrations import crewai
+    from mcal.integrations import autogen
+    from mcal.integrations import langchain
+
+
+def __getattr__(name: str):
+    """Lazy load integrations to avoid import errors when extras not installed."""
+    if name == "langgraph":
+        try:
+            from mcal.integrations import langgraph as _langgraph
+            return _langgraph
+        except ImportError as e:
+            raise ImportError(
+                f"LangGraph integration requires extra dependencies.\n"
+                f"Install with: pip install mcal[langgraph]\n"
+                f"Original error: {e}"
+            ) from e
+    
+    elif name == "crewai":
+        try:
+            from mcal.integrations import crewai as _crewai
+            return _crewai
+        except ImportError as e:
+            raise ImportError(
+                f"CrewAI integration requires extra dependencies.\n"
+                f"Install with: pip install mcal[crewai]\n"
+                f"Original error: {e}"
+            ) from e
+    
+    elif name == "autogen":
+        try:
+            from mcal.integrations import autogen as _autogen
+            return _autogen
+        except ImportError as e:
+            raise ImportError(
+                f"AutoGen integration requires extra dependencies.\n"
+                f"Install with: pip install mcal[autogen]\n"
+                f"Original error: {e}"
+            ) from e
+    
+    elif name == "langchain":
+        try:
+            from mcal.integrations import langchain as _langchain
+            return _langchain
+        except ImportError as e:
+            raise ImportError(
+                f"LangChain integration requires extra dependencies.\n"
+                f"Install with: pip install mcal[langchain]\n"
+                f"Original error: {e}"
+            ) from e
+    
+    raise AttributeError(f"module 'mcal.integrations' has no attribute '{name}'")
+
+
+def __dir__():
+    """List available integrations."""
+    return ["langgraph", "crewai", "autogen", "langchain"]
+
+
+__all__ = ["langgraph", "crewai", "autogen", "langchain"]

mcal/integrations/autogen.py

@@ -0,0 +1,95 @@
+"""
+MCAL AutoGen Integration
+
+Provides memory components for Microsoft AutoGen agent workflows.
+
+Installation:
+    pip install mcal[autogen]
+
+Usage:
+    from mcal.integrations.autogen import MCALMemoryAgent
+    
+    memory_agent = MCALMemoryAgent(llm_provider="anthropic")
+    # Use in AutoGen group chat
+
+Status: Coming Soon
+"""
+
+from typing import Any, Dict, List, Optional
+
+# Check for AutoGen availability
+try:
+    import autogen
+    AUTOGEN_AVAILABLE = True
+except ImportError:
+    AUTOGEN_AVAILABLE = False
+
+
+def _check_autogen():
+    """Raise helpful error if AutoGen not installed."""
+    if not AUTOGEN_AVAILABLE:
+        raise ImportError(
+            "AutoGen integration requires pyautogen package.\n"
+            "Install with: pip install mcal[autogen]"
+        )
+
+
+class MCALMemoryAgent:
+    """
+    MCAL Memory agent for AutoGen workflows.
+    
+    Provides a specialized agent that manages goal-aware memory
+    for AutoGen group chats and workflows.
+    
+    Status: Coming Soon - Basic structure implemented.
+    
+    Usage:
+        from mcal.integrations.autogen import MCALMemoryAgent
+        from autogen import AssistantAgent, UserProxyAgent
+        
+        memory_agent = MCALMemoryAgent(
+            name="memory_manager",
+            llm_provider="anthropic",
+        )
+        
+        # Add to group chat
+        group_chat = GroupChat(
+            agents=[user, assistant, memory_agent],
+            ...
+        )
+    """
+    
+    def __init__(
+        self,
+        name: str = "memory_manager",
+        llm_provider: str = "anthropic",
+        embedding_provider: str = "openai",
+        storage_path: Optional[str] = None,
+        **mcal_kwargs
+    ):
+        _check_autogen()
+        
+        self.name = name
+        
+        # Import MCAL here to avoid circular imports
+        from mcal import MCAL
+        
+        self._mcal = MCAL(
+            llm_provider=llm_provider,
+            embedding_provider=embedding_provider,
+            storage_path=storage_path,
+            **mcal_kwargs
+        )
+    
+    async def process_message(self, message: str, sender: str) -> Optional[str]:
+        """Process a message and update memory."""
+        # TODO: Implement AutoGen-specific message processing
+        raise NotImplementedError("AutoGen integration coming soon")
+    
+    async def get_context(self, query: str) -> str:
+        """Get relevant context for a query."""
+        # TODO: Implement AutoGen-specific context retrieval
+        raise NotImplementedError("AutoGen integration coming soon")
+
+
+__all__ = ["MCALMemoryAgent", "AUTOGEN_AVAILABLE"]

mcal/integrations/crewai.py

@@ -0,0 +1,92 @@
+"""
+MCAL CrewAI Integration
+
+Provides memory components for CrewAI agent crews.
+
+Installation:
+    pip install mcal[crewai]
+
+Usage:
+    from mcal.integrations.crewai import MCALCrewMemory
+    
+    memory = MCALCrewMemory(llm_provider="anthropic")
+    crew = Crew(
+        agents=[...],
+        memory=memory,
+    )
+
+Status: Coming Soon
+"""
+
+from typing import Any, Dict, List, Optional
+
+# Check for CrewAI availability
+try:
+    import crewai
+    CREWAI_AVAILABLE = True
+except ImportError:
+    CREWAI_AVAILABLE = False
+
+
+def _check_crewai():
+    """Raise helpful error if CrewAI not installed."""
+    if not CREWAI_AVAILABLE:
+        raise ImportError(
+            "CrewAI integration requires crewai package.\n"
+            "Install with: pip install mcal[crewai]"
+        )
+
+
+class MCALCrewMemory:
+    """
+    MCAL Memory component for CrewAI workflows.
+    
+    Provides goal-aware memory that preserves reasoning context
+    across agent crew interactions.
+    
+    Status: Coming Soon - Basic structure implemented.
+    
+    Usage:
+        from mcal.integrations.crewai import MCALCrewMemory
+        from crewai import Crew, Agent
+        
+        memory = MCALCrewMemory(llm_provider="anthropic")
+        
+        crew = Crew(
+            agents=[agent1, agent2],
+            tasks=[task1, task2],
+            memory=memory,  # MCAL provides the memory layer
+        )
+    """
+    
+    def __init__(
+        self,
+        llm_provider: str = "anthropic",
+        embedding_provider: str = "openai",
+        storage_path: Optional[str] = None,
+        **mcal_kwargs
+    ):
+        _check_crewai()
+        
+        # Import MCAL here to avoid circular imports
+        from mcal import MCAL
+        
+        self._mcal = MCAL(
+            llm_provider=llm_provider,
+            embedding_provider=embedding_provider,
+            storage_path=storage_path,
+            **mcal_kwargs
+        )
+    
+    async def save(self, key: str, value: Any, agent_name: str = "default") -> None:
+        """Save information to memory."""
+        # TODO: Implement CrewAI-specific save
+        raise NotImplementedError("CrewAI integration coming soon")
+    
+    async def search(self, query: str, agent_name: str = "default") -> List[Dict[str, Any]]:
+        """Search memory for relevant information."""
+        # TODO: Implement CrewAI-specific search
+        raise NotImplementedError("CrewAI integration coming soon")
+
+
+__all__ = ["MCALCrewMemory", "CREWAI_AVAILABLE"]

mcal/integrations/langchain.py

@@ -0,0 +1,112 @@
+"""
+MCAL LangChain Integration
+
+Provides memory components for LangChain chains and agents.
+
+Installation:
+    pip install mcal[langchain]
+
+Usage:
+    from mcal.integrations.langchain import MCALChatMemory
+    
+    memory = MCALChatMemory(llm_provider="anthropic")
+    chain = ConversationChain(llm=llm, memory=memory)
+
+Status: Coming Soon
+"""
+
+from typing import Any, Dict, List, Optional
+
+# Check for LangChain availability
+try:
+    from langchain_core.memory import BaseMemory
+    from langchain_core.messages import BaseMessage
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    LANGCHAIN_AVAILABLE = False
+    BaseMemory = object  # Placeholder for type hints
+
+
+def _check_langchain():
+    """Raise helpful error if LangChain not installed."""
+    if not LANGCHAIN_AVAILABLE:
+        raise ImportError(
+            "LangChain integration requires langchain-core package.\n"
+            "Install with: pip install mcal[langchain]"
+        )
+
+
+class MCALChatMemory(BaseMemory if LANGCHAIN_AVAILABLE else object):
+    """
+    MCAL Memory for LangChain conversation chains.
+    
+    Provides goal-aware memory that preserves reasoning context
+    across LangChain conversations.
+    
+    Status: Coming Soon - Basic structure implemented.
+    
+    Usage:
+        from mcal.integrations.langchain import MCALChatMemory
+        from langchain.chains import ConversationChain
+        
+        memory = MCALChatMemory(llm_provider="anthropic")
+        
+        chain = ConversationChain(
+            llm=llm,
+            memory=memory,
+        )
+    """
+    
+    # LangChain memory interface
+    memory_key: str = "history"
+    return_messages: bool = True
+    
+    def __init__(
+        self,
+        llm_provider: str = "anthropic",
+        embedding_provider: str = "openai",
+        storage_path: Optional[str] = None,
+        user_id: str = "default",
+        **mcal_kwargs
+    ):
+        _check_langchain()
+        
+        if LANGCHAIN_AVAILABLE:
+            super().__init__()
+        
+        self.user_id = user_id
+        
+        # Import MCAL here to avoid circular imports
+        from mcal import MCAL
+        
+        self._mcal = MCAL(
+            llm_provider=llm_provider,
+            embedding_provider=embedding_provider,
+            storage_path=storage_path,
+            **mcal_kwargs
+        )
+        self._messages: List[Any] = []
+    
+    @property
+    def memory_variables(self) -> List[str]:
+        """Memory variables provided to prompts."""
+        return [self.memory_key]
+    
+    def load_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
+        """Load memory variables for chain."""
+        # TODO: Implement LangChain-specific memory loading
+        if self.return_messages:
+            return {self.memory_key: self._messages}
+        return {self.memory_key: ""}
+    
+    def save_context(self, inputs: Dict[str, Any], outputs: Dict[str, str]) -> None:
+        """Save context from chain run."""
+        # TODO: Implement LangChain-specific context saving
+        pass
+    
+    def clear(self) -> None:
+        """Clear memory."""
+        self._messages = []
+
+
+__all__ = ["MCALChatMemory", "LANGCHAIN_AVAILABLE"]

mcal/integrations/langgraph.py

@@ -0,0 +1,50 @@
+"""
+MCAL LangGraph Integration - Backward Compatibility Shim
+
+DEPRECATED: This module is deprecated. Use mcal-langgraph package instead.
+
+Old way (deprecated):
+    from mcal.integrations.langgraph import MCALStore
+
+New way (recommended):
+    pip install mcal-langgraph
+    from mcal_langgraph import MCALStore
+
+This module re-exports from mcal_langgraph for backward compatibility.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+# Emit deprecation warning on import
+warnings.warn(
+    "mcal.integrations.langgraph is deprecated and will be removed in v1.0. "
+    "Install mcal-langgraph and use 'from mcal_langgraph import MCALStore' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Try to import from new package first
+try:
+    from mcal_langgraph import (
+        MCALStore,
+        MCALMemory,
+        MCALMemoryConfig,
+        MCALCheckpointer,
+        LANGGRAPH_AVAILABLE,
+    )
+except ImportError:
+    # New package not installed - raise helpful error
+    raise ImportError(
+        "mcal-langgraph package is required for LangGraph integration.\n"
+        "Install with: pip install mcal-langgraph"
+    )
+
+__all__ = [
+    "MCALStore",
+    "MCALMemory",
+    "MCALMemoryConfig",
+    "MCALCheckpointer",
+    "LANGGRAPH_AVAILABLE",
+]