mcal-ai-crewai 0.2.0__py3-none-any.whl

mcal_ai_crewai-0.2.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: mcal-ai-crewai
+Version: 0.2.0
+Summary: CrewAI integration for MCAL - Goal-aware memory for AI agent crews
+Project-URL: Homepage, https://github.com/Shivakoreddi/mcal-ai
+Project-URL: Documentation, https://github.com/Shivakoreddi/mcal-ai/docs
+Project-URL: Repository, https://github.com/Shivakoreddi/mcal-ai
+Author: MCAL Team
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,crewai,goal-tracking,mcal,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: crewai>=0.100.0
+Requires-Dist: mcal-ai>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcal-crewai
+
+Goal-aware memory integration for CrewAI agent crews.
+
+## Installation
+
+```bash
+pip install mcal-crewai
+```
+
+## Quick Start
+
+### Using MCALStorage (Mem0-style)
+
+MCAL provides a storage backend that integrates directly with CrewAI's memory system:
+
+```python
+from crewai import Crew, Agent, Task, Process
+from crewai.memory.short_term.short_term_memory import ShortTermMemory
+from crewai.memory.long_term.long_term_memory import LongTermMemory
+from crewai.memory.entity.entity_memory import EntityMemory
+from mcal_crewai import MCALStorage
+
+# Create MCAL-backed memories
+short_term = ShortTermMemory(
+    storage=MCALStorage(type="short_term", user_id="john")
+)
+long_term = LongTermMemory(
+    storage=MCALStorage(type="long_term", user_id="john")
+)
+entity_memory = EntityMemory(
+    storage=MCALStorage(type="entities", user_id="john")
+)
+
+# Use with CrewAI
+crew = Crew(
+    agents=[agent],
+    tasks=[task],
+    memory=True,
+    short_term_memory=short_term,
+    long_term_memory=long_term,
+    entity_memory=entity_memory,
+)
+```
+
+### Using External Memory
+
+For cross-session persistence with goal awareness:
+
+```python
+from crewai.memory.external.external_memory import ExternalMemory
+from mcal_crewai import MCALStorage
+
+external = ExternalMemory(
+    embedder_config={
+        "provider": "mcal",
+        "config": {
+            "user_id": "john",
+            "llm_provider": "anthropic",
+            "enable_goal_tracking": True,
+        }
+    }
+)
+
+crew = Crew(
+    agents=[...],
+    tasks=[...],
+    external_memory=external,
+    process=Process.sequential,
+)
+```
+
+## Features
+
+### Goal-Aware Memory
+Unlike basic memory systems, MCAL tracks user goals and priorities:
+
+```python
+storage = MCALStorage(
+    type="long_term",
+    user_id="project_manager",
+    config={
+        "enable_goal_tracking": True,
+        "extract_priorities": True,
+    }
+)
+```
+
+### Context Preservation
+MCAL maintains reasoning context across agent handoffs:
+
+```python
+# Agent 1 saves with context
+await storage.save(
+    "Research findings on market trends",
+    metadata={
+        "agent": "researcher",
+        "goal": "market_analysis",
+        "confidence": 0.95
+    }
+)
+
+# Agent 2 retrieves with goal awareness
+results = await storage.search(
+    "What do we know about market trends?",
+    limit=5,
+    score_threshold=0.7
+)
+```
+
+### TTL Support
+Automatic expiration for short-term memories:
+
+```python
+storage = MCALStorage(
+    type="short_term",
+    user_id="session_user",
+    default_ttl=3600,  # 1 hour
+)
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `type` | str | required | Memory type: "short_term", "long_term", "entities", "external" |
+| `user_id` | str | "default" | User identifier for memory isolation |
+| `llm_provider` | str | "anthropic" | LLM for goal extraction |
+| `embedding_provider` | str | "openai" | Embedding model provider |
+| `default_ttl` | int | None | Default TTL in seconds |
+| `enable_goal_tracking` | bool | True | Enable goal extraction |
+
+## API Reference
+
+### MCALStorage
+
+```python
+class MCALStorage(Storage):
+    """MCAL storage backend for CrewAI memory."""
+    
+    def save(self, value: Any, metadata: dict) -> None:
+        """Save value with goal-aware processing."""
+    
+    def search(
+        self, 
+        query: str, 
+        limit: int = 5, 
+        score_threshold: float = 0.6
+    ) -> list:
+        """Search with goal-aware relevance."""
+    
+    def reset(self) -> None:
+        """Clear all stored memories."""
+```
+
+## Comparison with Mem0
+
+| Feature | Mem0 | MCAL |
+|---------|------|------|
+| Basic Memory | ✓ | ✓ |
+| Goal Tracking | ✗ | ✓ |
+| Priority Extraction | ✗ | ✓ |
+| Context Preservation | ✗ | ✓ |
+| TTL Support | ✗ | ✓ |
+| Local Storage | ✓ | ✓ |
+| Cloud API | ✓ | Coming |
+
+## License
+
+MIT License

mcal_ai_crewai-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+mcal_crewai/__init__.py,sha256=wCpTrgdQ745JHsCgFEUxAvuoH1d6wec9Ybrz26UE9IQ,465
+mcal_crewai/storage.py,sha256=DHaAJKeJd4L7Id4JbpV8T91lsYNnS9DGocC4fV_LPdw,10791
+mcal_ai_crewai-0.2.0.dist-info/METADATA,sha256=5kd-_oMQw36xDk_HKp_tf4elU7YlHrg4H1QgOVgrz7o,5026
+mcal_ai_crewai-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcal_ai_crewai-0.2.0.dist-info/licenses/LICENSE,sha256=zdp5kxDzb-kYvBiEZ_h1Hi96z-o6e5oXoXFx2IIefCs,1062
+mcal_ai_crewai-0.2.0.dist-info/RECORD,,

mcal_ai_crewai-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcal_ai_crewai-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shiva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcal_crewai/__init__.py

@@ -0,0 +1,23 @@
+"""
+MCAL CrewAI Integration
+
+Goal-aware memory for CrewAI agent crews.
+
+Usage:
+    from mcal_crewai import MCALStorage
+    
+    storage = MCALStorage(type="short_term", user_id="john")
+    
+    # Use with CrewAI memory
+    from crewai.memory.short_term.short_term_memory import ShortTermMemory
+    memory = ShortTermMemory(storage=storage)
+"""
+
+from mcal_crewai.storage import MCALStorage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MCALStorage",
+    "__version__",
+]

mcal_crewai/storage.py

@@ -0,0 +1,316 @@
+"""
+MCAL Storage Backend for CrewAI
+
+Implements CrewAI's Storage interface with goal-aware memory.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Iterable
+from typing import Any, Optional
+
+# Lazy import for MCAL to avoid circular dependencies
+_mcal_instance: Optional[Any] = None
+_mcal_lock = threading.Lock()
+
+
+def _get_mcal(
+    llm_provider: str = "anthropic",
+    embedding_provider: str = "openai",
+    storage_path: Optional[str] = None,
+    **kwargs
+) -> Any:
+    """Get or create MCAL instance (lazy singleton)."""
+    global _mcal_instance
+    
+    if _mcal_instance is None:
+        with _mcal_lock:
+            if _mcal_instance is None:
+                from mcal import MCAL
+                _mcal_instance = MCAL(
+                    llm_provider=llm_provider,
+                    embedding_provider=embedding_provider,
+                    storage_path=storage_path,
+                    **kwargs
+                )
+    return _mcal_instance
+
+
+class MCALStorage:
+    """
+    MCAL storage backend for CrewAI memory.
+    
+    This class implements CrewAI's Storage interface, providing
+    goal-aware memory with context preservation for agent crews.
+    
+    Compatible with:
+    - ShortTermMemory
+    - LongTermMemory  
+    - EntityMemory
+    - ExternalMemory
+    
+    Usage:
+        from mcal_crewai import MCALStorage
+        from crewai.memory.short_term.short_term_memory import ShortTermMemory
+        
+        storage = MCALStorage(type="short_term", user_id="john")
+        memory = ShortTermMemory(storage=storage)
+        
+    Args:
+        type: Memory type - "short_term", "long_term", "entities", "external"
+        crew: Optional CrewAI Crew instance
+        config: Configuration dictionary with MCAL options
+        user_id: User identifier for memory isolation
+        default_ttl: Default TTL in seconds for memory items
+        enable_goal_tracking: Whether to extract goals from content
+    """
+    
+    SUPPORTED_TYPES = {"short_term", "long_term", "entities", "external"}
+    
+    def __init__(
+        self,
+        type: str,
+        crew: Any = None,
+        config: Optional[dict] = None,
+        user_id: str = "default",
+        default_ttl: Optional[int] = None,
+        enable_goal_tracking: bool = True,
+        **kwargs
+    ):
+        # Validate type
+        if type not in self.SUPPORTED_TYPES:
+            raise ValueError(
+                f"Invalid type '{type}'. Must be one of: {', '.join(self.SUPPORTED_TYPES)}"
+            )
+        
+        self.memory_type = type
+        self.crew = crew
+        self.config = config or {}
+        # user_id priority: explicit param > config > default
+        self.user_id = user_id if user_id != "default" else self.config.get("user_id", user_id)
+        self.default_ttl = default_ttl
+        self.enable_goal_tracking = enable_goal_tracking
+        
+        # Extract config values
+        self.llm_provider = self.config.get("llm_provider", "anthropic")
+        self.embedding_provider = self.config.get("embedding_provider", "openai")
+        self.storage_path = self.config.get("storage_path")
+        
+        # TTL tracking (lazy expiration)
+        self._ttl: dict[str, int] = {}  # key -> ttl_seconds
+        self._expires_at: dict[str, float] = {}  # key -> expiration_timestamp
+        
+        # Thread safety
+        self._lock = threading.RLock()
+        
+        # Internal storage (in-memory for now, will use MCAL graph later)
+        self._data: dict[str, dict[str, Any]] = {}
+        
+        # MCAL instance (lazy loaded)
+        self._mcal: Optional[Any] = None
+    
+    @property
+    def mcal(self) -> Any:
+        """Lazy load MCAL instance."""
+        if self._mcal is None:
+            self._mcal = _get_mcal(
+                llm_provider=self.llm_provider,
+                embedding_provider=self.embedding_provider,
+                storage_path=self.storage_path,
+            )
+        return self._mcal
+    
+    def _generate_key(self, value: Any, metadata: dict) -> str:
+        """Generate a unique key for storage."""
+        import hashlib
+        content = str(value) + str(metadata)
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+    
+    def _is_expired(self, key: str) -> bool:
+        """Check if a key has expired."""
+        if key not in self._expires_at:
+            return False
+        return time.time() > self._expires_at[key]
+    
+    def _set_ttl(self, key: str, ttl: Optional[int] = None) -> None:
+        """Set TTL for a key."""
+        ttl_value = ttl or self.default_ttl
+        if ttl_value is not None:
+            self._ttl[key] = ttl_value
+            self._expires_at[key] = time.time() + ttl_value
+    
+    def _cleanup_expired(self) -> None:
+        """Remove expired entries (lazy cleanup)."""
+        expired_keys = [
+            key for key in self._expires_at 
+            if time.time() > self._expires_at[key]
+        ]
+        for key in expired_keys:
+            self._data.pop(key, None)
+            self._ttl.pop(key, None)
+            self._expires_at.pop(key, None)
+    
+    def _extract_last_content(
+        self, 
+        messages: Iterable[dict[str, Any]], 
+        role: str
+    ) -> str:
+        """Extract last message content for a given role."""
+        return next(
+            (
+                m.get("content", "")
+                for m in reversed(list(messages))
+                if m.get("role") == role
+            ),
+            "",
+        )
+    
+    def _get_agent_name(self) -> str:
+        """Get current agent name from crew context."""
+        if self.crew and hasattr(self.crew, "_current_agent"):
+            agent = self.crew._current_agent
+            if agent and hasattr(agent, "role"):
+                return str(agent.role)
+        return self.config.get("agent_id", "default_agent")
+    
+    def save(self, value: Any, metadata: dict[str, Any]) -> None:
+        """
+        Save a value to MCAL storage.
+        
+        Args:
+            value: The content to save (string, dict, or conversation)
+            metadata: Additional metadata (agent, task, etc.)
+        """
+        with self._lock:
+            # Generate key
+            key = self._generate_key(value, metadata)
+            
+            # Process value based on type
+            if isinstance(value, dict) and "messages" in value:
+                # Conversation format
+                messages = value.get("messages", [])
+                content = self._extract_last_content(messages, "assistant")
+                if not content:
+                    content = self._extract_last_content(messages, "user")
+            elif isinstance(value, str):
+                content = value
+            else:
+                content = str(value)
+            
+            # Build storage entry
+            entry = {
+                "content": content,
+                "raw_value": value,
+                "metadata": {
+                    "type": self.memory_type,
+                    "user_id": self.user_id,
+                    "agent": self._get_agent_name(),
+                    "timestamp": time.time(),
+                    **metadata,
+                },
+            }
+            
+            # Extract goals if enabled
+            if self.enable_goal_tracking and content:
+                entry["metadata"]["goal_tracked"] = True
+                # TODO: Use MCAL's goal extraction when integrated
+                # goals = self.mcal.extract_goals(content)
+                # entry["metadata"]["goals"] = goals
+            
+            # Store with TTL
+            self._data[key] = entry
+            
+            # Set TTL if configured
+            ttl = metadata.get("ttl") or self.default_ttl
+            if ttl:
+                self._set_ttl(key, ttl)
+            
+            # Short-term memory gets default TTL if not set
+            if self.memory_type == "short_term" and key not in self._ttl:
+                self._set_ttl(key, 3600)  # 1 hour default for short-term
+    
+    def search(
+        self, 
+        query: str, 
+        limit: int = 5, 
+        score_threshold: float = 0.6
+    ) -> list[Any]:
+        """
+        Search storage for relevant content.
+        
+        Args:
+            query: Search query
+            limit: Maximum results to return
+            score_threshold: Minimum relevance score (0-1)
+            
+        Returns:
+            List of matching results with 'content' key
+        """
+        with self._lock:
+            # Cleanup expired entries
+            self._cleanup_expired()
+            
+            # Simple keyword-based search for now
+            # TODO: Use MCAL's semantic search when integrated
+            results = []
+            query_lower = query.lower()
+            query_words = set(query_lower.split())
+            
+            for key, entry in self._data.items():
+                # Skip expired
+                if self._is_expired(key):
+                    continue
+                
+                content = entry.get("content", "")
+                content_lower = content.lower()
+                
+                # Calculate simple relevance score
+                content_words = set(content_lower.split())
+                overlap = query_words & content_words
+                
+                if overlap:
+                    score = len(overlap) / max(len(query_words), 1)
+                    
+                    if score >= score_threshold:
+                        results.append({
+                            "content": content,
+                            "memory": content,  # Compatibility with Mem0 format
+                            "score": score,
+                            "metadata": entry.get("metadata", {}),
+                        })
+            
+            # Sort by score and limit
+            results.sort(key=lambda x: x["score"], reverse=True)
+            return results[:limit]
+    
+    def reset(self) -> None:
+        """Clear all stored memories for this type."""
+        with self._lock:
+            self._data.clear()
+            self._ttl.clear()
+            self._expires_at.clear()
+    
+    def get_all(self) -> list[dict[str, Any]]:
+        """Get all non-expired entries."""
+        with self._lock:
+            self._cleanup_expired()
+            return [
+                entry for key, entry in self._data.items()
+                if not self._is_expired(key)
+            ]
+    
+    def delete(self, key: str) -> bool:
+        """Delete a specific entry by key."""
+        with self._lock:
+            if key in self._data:
+                del self._data[key]
+                self._ttl.pop(key, None)
+                self._expires_at.pop(key, None)
+                return True
+            return False
+
+
+# Alias for backward compatibility
+MCALMemoryStorage = MCALStorage