adaptive-memory-multi-model-router 1.2.2 → 1.3.1

package/src/agents/skill_enhanced_agent.py

@@ -0,0 +1,318 @@
+"""
+TML Enhanced Agent - Agent with Skill capabilities
+
+Integrates SkillManager to provide agents with domain-specific expertise
+following Anthropic's Agent Skills specification.
+"""
+
+from typing import Dict, List, Optional, Any
+from pathlib import Path
+import json
+from datetime import datetime
+
+from .skill_manager import SkillManager, Skill
+
+
+class TMLEnhancedAgent:
+    """
+    Agent enhanced with Skill capabilities.
+
+    Uses progressive disclosure to load relevant skills only when needed,
+    following Anthropic's specification for Agent Skills.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        provider: str,
+        model: str,
+        skills_dir: str = "tmlpd-skills",
+        assigned_skills: Optional[List[str]] = None
+    ):
+        """
+        Initialize TML Enhanced Agent
+
+        Args:
+            agent_id: Unique identifier for this agent
+            provider: LLM provider (e.g., 'anthropic', 'openai')
+            model: Model name (e.g., 'claude-sonnet-4', 'gpt-4-turbo')
+            skills_dir: Directory containing skill definitions
+            assigned_skills: List of skill names assigned to this agent
+        """
+        self.agent_id = agent_id
+        self.provider = provider
+        self.model = model
+        self.assigned_skills = assigned_skills or []
+
+        # Initialize skill manager
+        self.skill_manager = SkillManager(skills_dir)
+
+        # Load metadata for assigned skills
+        for skill_name in self.assigned_skills:
+            if skill_name in self.skill_manager.skills:
+                # Metadata already loaded by SkillManager
+                pass
+
+    def execute_task(self, task: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute a task using relevant skills for context.
+
+        Args:
+            task: Task dictionary with 'description' and other metadata
+
+        Returns:
+            Result dictionary with task output
+        """
+        task_description = task.get("description", "")
+
+        # Step 1: Find relevant skills
+        relevant_skills = self._get_relevant_skills(task_description)
+
+        # Step 2: Build enhanced prompt with skill context
+        enhanced_prompt = self._build_prompt_with_skills(
+            task_description,
+            relevant_skills,
+            task
+        )
+
+        # Step 3: Execute LLM call with enhanced context
+        result = self._execute_llm_call(enhanced_prompt)
+
+        # Step 4: Store successful pattern in memory (if enabled)
+        if result.get("success"):
+            self._remember_success_pattern(task, result)
+
+        return result
+
+    def _get_relevant_skills(
+        self,
+        task_description: str,
+        top_k: int = 3
+    ) -> List[Skill]:
+        """
+        Get relevant skills for this task.
+
+        Args:
+            task_description: Task to find skills for
+            top_k: Maximum number of skills to load
+
+        Returns:
+            List of loaded Skill objects
+        """
+        # If agent has assigned skills, only consider those
+        if self.assigned_skills:
+            skill_names = self.assigned_skills[:top_k]
+        else:
+            # Otherwise, use skill discovery
+            skill_names = self.skill_manager.get_relevant_skills(
+                task_description,
+                top_k=top_k
+            )
+
+        # Load full skill content (Level 2: SKILL.md)
+        loaded_skills = []
+
+        for skill_name in skill_names:
+            try:
+                skill = self.skill_manager.load_skill(skill_name)
+                loaded_skills.append(skill)
+            except Exception as e:
+                print(f"Warning: Failed to load skill '{skill_name}': {e}")
+                continue
+
+        return loaded_skills
+
+    def _build_prompt_with_skills(
+        self,
+        task_description: str,
+        skills: List[Skill],
+        task: Dict[str, Any]
+    ) -> str:
+        """
+        Build enhanced prompt with skill context.
+
+        Args:
+            task_description: Original task description
+            skills: List of relevant loaded skills
+            task: Original task metadata
+
+        Returns:
+            Enhanced prompt with skill context
+        """
+        parts = []
+
+        # Add task context
+        parts.append(f"# Task\n{task_description}\n")
+
+        # Add additional task metadata
+        if "context" in task:
+            parts.append(f"## Context\n{task['context']}\n")
+
+        if "requirements" in task:
+            parts.append(f"## Requirements\n{task['requirements']}\n")
+
+        # Add skill contexts
+        if skills:
+            parts.append("## Relevant Skills\n")
+            parts.append(f"The following skills provide expert guidance for this task:\n")
+
+            for skill in skills:
+                parts.append(f"\n### {skill.name}\n")
+                parts.append(f"{skill.content}\n")
+
+        # Add agent information
+        parts.append(f"\n## Agent Configuration\n")
+        parts.append(f"- Agent: {self.agent_id}\n")
+        parts.append(f"- Provider: {self.provider}\n")
+        parts.append(f"- Model: {self.model}\n")
+
+        # Add execution instruction
+        parts.append("\n## Instructions\n")
+        parts.append("Please complete the task following the guidance from the relevant skills above. ")
+        parts.append("Use best practices and patterns recommended by the skills.")
+
+        return "\n".join(parts)
+
+    def _execute_llm_call(self, prompt: str) -> Dict[str, Any]:
+        """
+        Execute LLM call with the enhanced prompt.
+
+        Args:
+            prompt: Enhanced prompt with skill context
+
+        Returns:
+            Result dictionary with response, tokens, cost, etc.
+        """
+        # This is a placeholder - in production, you would call
+        # the actual LLM API based on self.provider and self.model
+
+        # Simulated response
+        return {
+            "success": True,
+            "output": f"Simulated response from {self.provider}:{self.model}",
+            "tokens_used": 100,
+            "cost": 0.01,
+            "execution_time": 2.5,
+            "timestamp": datetime.now().isoformat()
+        }
+
+    def _remember_success_pattern(self, task: Dict, result: Dict):
+        """
+        Remember a successful execution pattern.
+
+        In production, this would save to:
+        - SimpleProjectMemory for project-level learning
+        - Or episodic memory for pattern discovery
+
+        Args:
+            task: Task that was executed
+            result: Successful result
+        """
+        pattern = {
+            "task_description": task.get("description"),
+            "agent_id": self.agent_id,
+            "model": self.model,
+            "tokens": result.get("tokens_used"),
+            "cost": result.get("cost"),
+            "execution_time": result.get("execution_time"),
+            "timestamp": datetime.now().isoformat()
+        }
+
+        # Store pattern (implementation depends on memory system)
+        # For now, just log it
+        print(f"Pattern learned: {task.get('description')[:50]}...")
+
+    def get_assigned_skills(self) -> List[str]:
+        """Get list of skills assigned to this agent"""
+        return self.assigned_skills.copy()
+
+    def add_skill(self, skill_name: str):
+        """
+        Assign a skill to this agent.
+
+        Args:
+            skill_name: Name of the skill to assign
+        """
+        if skill_name not in self.assigned_skills:
+            self.assigned_skills.append(skill_name)
+
+    def remove_skill(self, skill_name: str):
+        """
+        Remove a skill from this agent.
+
+        Args:
+            skill_name: Name of the skill to remove
+        """
+        if skill_name in self.assigned_skills:
+            self.assigned_skills.remove(skill_name)
+
+    def list_available_skills(self) -> List[str]:
+        """List all available skills from skill manager"""
+        return self.skill_manager.list_skills()
+
+    def get_skill_info(self, skill_name: str) -> Optional[Dict]:
+        """Get information about a specific skill"""
+        return self.skill_manager.get_skill_info(skill_name)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert agent to dictionary representation.
+
+        Returns:
+            Dictionary with agent configuration
+        """
+        return {
+            "agent_id": self.agent_id,
+            "provider": self.provider,
+            "model": self.model,
+            "assigned_skills": self.assigned_skills,
+            "available_skills": self.list_available_skills()
+        }
+
+
+class TMLEnhancedAgentFactory:
+    """
+    Factory for creating TML Enhanced Agents with proper configuration.
+    """
+
+    @staticmethod
+    def create_from_config(config: Dict[str, Any]) -> TMLEnhancedAgent:
+        """
+        Create agent from configuration dictionary.
+
+        Args:
+            config: Configuration dictionary with keys:
+                - id: Agent ID
+                - provider: LLM provider
+                - model: Model name
+                - skills_dir: Skills directory
+                - skills: List of assigned skill names
+
+        Returns:
+            Configured TMLEnhancedAgent instance
+        """
+        return TMLEnhancedAgent(
+            agent_id=config["id"],
+            provider=config["provider"],
+            model=config["model"],
+            skills_dir=config.get("skills_dir", "tmlpd-skills"),
+            assigned_skills=config.get("skills", [])
+        )
+
+    @staticmethod
+    def create_multiple_from_config(
+        agents_config: List[Dict[str, Any]]
+    ) -> List[TMLEnhancedAgent]:
+        """
+        Create multiple agents from configuration list.
+
+        Args:
+            agents_config: List of agent configuration dictionaries
+
+        Returns:
+            List of configured TMLEnhancedAgent instances
+        """
+        return [
+            TMLEnhancedAgentFactory.create_from_config(agent_config)
+            for agent_config in agents_config
+        ]

package/src/memory/__init__.py

@@ -0,0 +1,15 @@
+"""
+TMLPD Memory Module
+
+This module provides lightweight JSON-based memory for pattern learning.
+"""
+
+from .simple_memory import (
+    SimpleProjectMemory,
+    remember_success
+)
+
+__all__ = [
+    "SimpleProjectMemory",
+    "remember_success"
+]

package/src/memory/agentic_memory.py

@@ -0,0 +1,353 @@
+"""
+Phase 3a: Episodic Memory Store
+
+JSON-based episodic memory following Memoria framework (arXiv:2512.12686)
+and A-Mem pattern (arXiv:2502.12110).
+
+Episodic memory stores specific task executions with full context.
+"""
+
+import json
+import uuid
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+from collections import defaultdict
+import re
+
+
+class EpisodicMemoryStore:
+    """
+    Episodic memory: stores specific task executions.
+
+    Based on Memoria framework (arXiv:2512.12686)
+    and A-Mem (arXiv:2502.12110)
+
+    Features:
+    - Full context storage
+    - Keyword indexing for fast retrieval
+    - Importance scoring
+    - Time-based decay
+    """
+
+    def __init__(self, base_dir: str = ".taskmaster/memory/episodic"):
+        """
+        Initialize episodic memory store.
+
+        Args:
+            base_dir: Directory to store episodic memories
+        """
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+
+        # Index: keywords -> episode IDs
+        self.index_file = self.base_dir / "index.json"
+        self.keyword_index = self._load_index()
+
+    def _load_index(self) -> Dict[str, List[str]]:
+        """Load keyword index"""
+        if self.index_file.exists():
+            with open(self.index_file, 'r') as f:
+                return json.load(f)
+        return {}
+
+    def _save_index(self):
+        """Save keyword index"""
+        with open(self.index_file, 'w') as f:
+            json.dump(self.keyword_index, f, indent=2)
+
+    def store(
+        self,
+        task: Dict[str, Any],
+        result: Dict[str, Any],
+        agent_id: str,
+        skills: List[str],
+        provider: str,
+        model: str,
+        importance: float = 0.5,
+        metadata: Optional[Dict] = None
+    ) -> str:
+        """
+        Store an episodic memory.
+
+        Args:
+            task: Task that was executed
+            result: Execution result
+            agent_id: Agent that executed
+            skills: Skills used
+            provider: LLM provider used
+            model: Model used
+            importance: Importance score (0-1)
+            metadata: Additional metadata
+
+        Returns:
+            Episode ID
+        """
+        episode_id = f"episode_{uuid.uuid4().hex[:12]}"
+
+        # Extract keywords from task description
+        keywords = self._extract_keywords(task.get("description", ""))
+
+        # Create episode
+        episode = {
+            "id": episode_id,
+            "timestamp": datetime.now().isoformat(),
+            "task": {
+                "description": task.get("description", ""),
+                "keywords": keywords,
+                "requirements": task.get("requirements", ""),
+                "context": task.get("context", "")
+            },
+            "execution": {
+                "agent_id": agent_id,
+                "provider": provider,
+                "model": model,
+                "skills": skills
+            },
+            "result": {
+                "success": result.get("success", False),
+                "tokens_used": result.get("tokens_used", 0),
+                "cost": result.get("cost", 0.0),
+                "execution_time": result.get("execution_time", 0.0),
+                "latency_ms": result.get("latency_ms", 0.0)
+            },
+            "importance": importance,
+            "metadata": metadata or {},
+            "access_count": 0,
+            "last_accessed": datetime.now().isoformat()
+        }
+
+        # Save episode to file
+        episode_file = self.base_dir / f"{episode_id}.json"
+        with open(episode_file, 'w') as f:
+            json.dump(episode, f, indent=2)
+
+        # Update keyword index
+        for keyword in keywords:
+            if keyword not in self.keyword_index:
+                self.keyword_index[keyword] = []
+            self.keyword_index[keyword].append(episode_id)
+
+        self._save_index()
+
+        return episode_id
+
+    def recall(
+        self,
+        task: Dict[str, Any],
+        top_k: int = 5,
+        min_importance: float = 0.0,
+        max_age_days: int = 30
+    ) -> List[Dict[str, Any]]:
+        """
+        Recall relevant episodes based on task similarity.
+
+        Args:
+            task: Current task
+            top_k: Maximum number of episodes to return
+            min_importance: Minimum importance threshold
+            max_age_days: Maximum age of episodes (days)
+
+        Returns:
+            List of relevant episodes with similarity scores
+        """
+        # Extract keywords from current task
+        task_keywords = self._extract_keywords(task.get("description", ""))
+
+        # Find episodes with keyword overlap
+        episode_scores = defaultdict(float)
+
+        for keyword in task_keywords:
+            if keyword in self.keyword_index:
+                for episode_id in self.keyword_index[keyword]:
+                    episode_scores[episode_id] += 1.0
+
+        # Load and score episodes
+        scored_episodes = []
+        cutoff_date = datetime.now() - timedelta(days=max_age_days)
+
+        for episode_id, score in episode_scores.items():
+            # Load episode
+            episode_file = self.base_dir / f"{episode_id}.json"
+
+            if not episode_file.exists():
+                continue
+
+            with open(episode_file, 'r') as f:
+                episode = json.load(f)
+
+            # Check age
+            episode_date = datetime.fromisoformat(episode["timestamp"])
+            if episode_date < cutoff_date:
+                continue
+
+            # Check importance
+            if episode["importance"] < min_importance:
+                continue
+
+            # Calculate final score
+            # Keyword similarity (40%)
+            keyword_score = score / max(len(task_keywords), 1)
+
+            # Recency boost (20%) - more recent = higher score
+            days_old = (datetime.now() - episode_date).days
+            recency_score = max(0, 1 - days_old / 365)  # Decays over 1 year
+
+            # Access frequency boost (20%)
+            access_score = min(episode["access_count"] / 100, 1.0)
+
+            # Importance boost (20%)
+            importance_score = episode["importance"]
+
+            total_score = (
+                keyword_score * 0.4 +
+                recency_score * 0.2 +
+                access_score * 0.2 +
+                importance_score * 0.2
+            )
+
+            scored_episodes.append({
+                "episode": episode,
+                "similarity": keyword_score,
+                "total_score": total_score
+            })
+
+            # Update access count
+            episode["access_count"] += 1
+            episode["last_accessed"] = datetime.now().isoformat()
+
+            # Save updated episode
+            with open(episode_file, 'w') as f:
+                json.dump(episode, f, indent=2)
+
+        # Sort by total score
+        scored_episodes.sort(key=lambda x: x["total_score"], reverse=True)
+
+        return scored_episodes[:top_k]
+
+    def get_episode(self, episode_id: str) -> Optional[Dict[str, Any]]:
+        """Get specific episode by ID"""
+        episode_file = self.base_dir / f"{episode_id}.json"
+
+        if not episode_file.exists():
+            return None
+
+        with open(episode_file, 'r') as f:
+            return json.load(f)
+
+    def _extract_keywords(self, text: str) -> set:
+        """
+        Extract keywords from text.
+
+        Removes common stop words and short words.
+        """
+        # Stop words
+        stop_words = {
+            "the", "a", "an", "and", "or", "but", "in", "on", "at", "to",
+            "for", "of", "with", "by", "from", "as", "is", "was", "are",
+            "been", "be", "have", "has", "had", "do", "does", "did", "will",
+            "would", "should", "could", "may", "might", "can", "this", "that"
+        }
+
+        # Extract words
+        words = re.findall(r'\w+', text.lower())
+
+        # Filter
+        keywords = {
+            w for w in words
+            if w not in stop words and len(w) > 2
+        }
+
+        return keywords
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get episodic memory statistics"""
+        total_episodes = len(list(self.base_dir.glob("*.json")))
+
+        # Calculate stats
+        total_importance = 0.0
+        total_tokens = 0
+        total_cost = 0.0
+
+        for episode_file in self.base_dir.glob("*.json"):
+            with open(episode_file, 'r') as f:
+                episode = json.load(f)
+
+            total_importance += episode.get("importance", 0)
+            total_tokens += episode["result"]["tokens_used"]
+            total_cost += episode["result"]["cost"]
+
+        return {
+            "total_episodes": total_episodes,
+            "total_keywords": len(self.keyword_index),
+            "avg_importance": total_importance / total_episodes if total_episodes > 0 else 0,
+            "total_tokens": total_tokens,
+            "total_cost": total_cost,
+            "avg_cost_per_episode": total_cost / total_episodes if total_episodes > 0 else 0
+        }
+
+    def cleanup_old_episodes(self, days_old: int = 90):
+        """
+        Remove episodes older than specified days.
+
+        Args:
+            days_old: Age threshold in days
+        """
+        cutoff_date = datetime.now() - timedelta(days=days_old)
+        removed_count = 0
+
+        for episode_file in self.base_dir.glob("*.json"):
+            with open(episode_file, 'r') as f:
+                episode = json.load(f)
+
+            episode_date = datetime.fromisoformat(episode["timestamp"])
+
+            if episode_date < cutoff_date:
+                # Remove from keyword index
+                for keyword, episode_list in self.keyword_index.items():
+                    if episode["id"] in episode_list:
+                        episode_list.remove(episode["id"])
+
+                # Delete file
+                episode_file.unlink()
+                removed_count += 1
+
+        # Save updated index
+        self._save_index()
+
+        print(f"Removed {removed_count} episodes older than {days_old} days")
+
+    def export_episodes(self, output_path: str, criteria: Optional[Dict] = None):
+        """
+        Export episodes to JSON file.
+
+        Args:
+            output_path: Path to output file
+            criteria: Optional filtering criteria
+        """
+        episodes = []
+
+        for episode_file in self.base_dir.glob("*.json"):
+            with open(episode_file, 'r') as f:
+                episode = json.load(f)
+
+            # Apply filters if provided
+            if criteria:
+                if "min_importance" in criteria:
+                    if episode["importance"] < criteria["min_importance"]:
+                        continue
+
+                if "provider" in criteria:
+                    if episode["execution"]["provider"] != criteria["provider"]:
+                        continue
+
+            episodes.append(episode)
+
+        # Write to output
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(output_path, 'w') as f:
+            json.dump(episodes, f, indent=2)
+
+        print(f"Exported {len(episodes)} episodes to {output_path}")