universal-agent-context 0.2.0__py3-none-any.whl

uacs/__init__.py

@@ -0,0 +1,12 @@
+"""Universal Agent Context System (UACS)
+
+Provides unified context management for AI agents:
+- Marketplace discovery (Skills + MCP)
+- Format adapters (Agent Skills, AGENTS.md, etc.)
+- Context management (shared memory + compression)
+"""
+
+from uacs.api import UACS
+
+__version__ = "0.2.0"
+__all__ = ["UACS"]

uacs/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""Format adapters for various instruction formats."""
+
+from .agent_skill_adapter import AgentSkillAdapter
+from .agents_md_adapter import AgentsMDAdapter, AgentsMDConfig, AgentsMDSection
+from .base import BaseFormatAdapter, FormatAdapterRegistry, ParsedContent
+from .clinerules_adapter import ClineRulesAdapter
+from .cursorrules_adapter import CursorRulesAdapter
+
+__all__ = [
+    "AgentSkillAdapter",
+    "AgentsMDAdapter",
+    "AgentsMDConfig",
+    "AgentsMDSection",
+    "BaseFormatAdapter",
+    "ClineRulesAdapter",
+    "CursorRulesAdapter",
+    "FormatAdapterRegistry",
+    "ParsedContent",
+]

uacs/adapters/agent_skill_adapter.py

@@ -0,0 +1,202 @@
+"""Adapter for Agent Skills SKILL.md format (individual skill files).
+
+Supports both .agent/ (recommended) and .claude/ (for importing external repos) directories.
+See https://agentskills.io for the vendor-neutral format specification.
+"""
+
+import re
+from pathlib import Path
+from typing import Any
+
+from .base import BaseFormatAdapter, FormatAdapterRegistry, ParsedContent
+
+
+@FormatAdapterRegistry.register
+class AgentSkillAdapter(BaseFormatAdapter):
+    """Agent Skills SKILL.md format adapter.
+
+    Supports the vendor-neutral Agent Skills format with YAML frontmatter:
+    ```
+    ---
+    name: skill-name
+    description: Brief description
+    ---
+    # skill-name
+
+    ## Instructions
+    ...
+    ```
+
+    See https://agentskills.io for full specification.
+    """
+
+    FORMAT_NAME = "agent_skill"
+    SUPPORTED_FILES = ["SKILL.md"]
+
+    source_directory: str | None = None
+
+    def parse(self, content: str) -> ParsedContent:
+        """Parse Claude Code SKILL.md format.
+
+        Args:
+            content: Raw SKILL.md content
+
+        Returns:
+            ParsedContent with skill metadata and instructions
+        """
+        # Parse YAML frontmatter
+        metadata = {}
+        instructions = content
+
+        # Check for YAML frontmatter (--- ... ---)
+        yaml_pattern = r"^---\s*\n(.*?)\n---\s*\n(.*)$"
+        match = re.match(yaml_pattern, content, re.DOTALL)
+
+        if match:
+            yaml_content = match.group(1)
+            instructions = match.group(2)
+
+            # Parse simple YAML (key: value pairs)
+            for line in yaml_content.split("\n"):
+                line = line.strip()
+                if ":" in line:
+                    key, value = line.split(":", 1)
+                    metadata[key.strip()] = value.strip()
+
+        return ParsedContent(
+            name=metadata.get("name", "unnamed-skill"),
+            description=metadata.get("description", ""),
+            instructions=instructions.strip(),
+            metadata=metadata,
+            triggers=self._extract_triggers(instructions),
+        )
+
+    def _extract_triggers(self, content: str) -> list[str]:
+        """Extract triggers from markdown content."""
+        triggers = []
+
+        # Look for ## Triggers section
+        trigger_section = re.search(
+            r"##\s+Triggers\s*\n(.*?)(?:\n##|$)", content, re.DOTALL | re.IGNORECASE
+        )
+        if trigger_section:
+            section_content = trigger_section.group(1)
+            # Extract list items
+            for line in section_content.split("\n"):
+                line = line.strip()
+                if line.startswith("- "):
+                    triggers.append(line[2:].strip())
+
+        return triggers
+
+    def to_system_prompt(self) -> str:
+        """Convert to system prompt.
+
+        Returns:
+            Formatted system prompt
+        """
+        if not self.parsed:
+            return ""
+
+        prompt_parts = [
+            f"# Skill: {self.parsed.name}",
+            "",
+            f"**Description**: {self.parsed.description}",
+            "",
+            "## Instructions",
+            self.parsed.instructions,
+        ]
+
+        return "\n".join(prompt_parts)
+
+    def to_adk_capabilities(self) -> dict[str, Any]:
+        """Convert to ADK capability format.
+
+        Returns:
+            ADK capability dictionary
+        """
+        if not self.parsed:
+            return {}
+
+        return {
+            "name": self.parsed.name,
+            "description": self.parsed.description,
+            "instructions": self.parsed.instructions,
+            "metadata": self.parsed.metadata,
+        }
+
+    @classmethod
+    def discover_skills(cls, project_path: Path) -> list["AgentSkillAdapter"]:
+        """Discover all SKILL.md files in project and personal directories.
+
+        Searches multiple directories with precedence:
+        1. project_path/.agent/skills/*/SKILL.md (highest priority)
+        2. ~/.agent/skills/*/SKILL.md
+        3. project_path/.claude/skills/*/SKILL.md
+        4. ~/.claude/skills/*/SKILL.md (lowest priority)
+
+        When duplicate skill names exist, .agent/ versions take precedence.
+        The .claude/ directory is supported for importing external skill repos.
+
+        Returns:
+            List of skill adapters, deduplicated by skill name
+        """
+        skills_by_name = {}  # Use dict to handle deduplication
+
+        # Search in precedence order (higher priority first)
+        search_paths = [
+            project_path / ".agent" / "skills",
+            Path.home() / ".agent" / "skills",
+            project_path / ".claude" / "skills",
+            Path.home() / ".claude" / "skills",
+        ]
+
+        for search_path in search_paths:
+            if not search_path.exists():
+                continue
+
+            # Find all SKILL.md files in subdirectories
+            for skill_dir in search_path.iterdir():
+                if not skill_dir.is_dir():
+                    continue
+
+                skill_file = skill_dir / "SKILL.md"
+                if skill_file.exists():
+                    try:
+                        adapter = cls(skill_file)
+                        skill_name = (
+                            adapter.parsed.name if adapter.parsed else skill_dir.name
+                        )
+
+                        # Only add if not already found (precedence: earlier paths win)
+                        if skill_name not in skills_by_name:
+                            # Track source directory for metadata
+                            adapter.source_directory = str(search_path)
+                            skills_by_name[skill_name] = adapter
+                    except Exception as e:
+                        # Log warning but continue discovering other skills
+                        print(f"Warning: Failed to load {skill_file}: {e}")
+
+        return list(skills_by_name.values())
+
+    def find_skill_by_trigger(self, query: str) -> bool:
+        """Check if this skill matches a query trigger.
+
+        Args:
+            query: Query string to match against triggers
+
+        Returns:
+            True if any trigger matches the query
+        """
+        if not self.parsed or not hasattr(self.parsed, "triggers"):
+            return False
+
+        query_lower = query.lower()
+        for trigger in self.parsed.triggers:
+            if trigger.lower() in query_lower or query_lower in trigger.lower():
+                return True
+
+        return False
+
+
+__all__ = ["AgentSkillAdapter"]

uacs/adapters/agents_md_adapter.py

@@ -0,0 +1,330 @@
+"""Adapter for AGENTS.md specification support.
+
+This module parses AGENTS.md files (the open standard for AI agent instructions)
+and converts them to A2A/ADK-compatible agent capabilities. The adapter follows
+the AGENTS.md specification and integrates with the Agent Development Kit (ADK)
+and Agent-to-Agent (A2A) protocol.
+
+Spec: https://agents.md/
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .base import BaseFormatAdapter, FormatAdapterRegistry, ParsedContent
+
+
+@dataclass
+class AgentsMDSection:
+    """Represents a parsed section from AGENTS.md.
+
+    Attributes:
+        title: Section title/heading text.
+        content: Section body content as markdown.
+        level: Heading level (1 for #, 2 for ##, etc.).
+        subsections: Nested child sections.
+    """
+
+    title: str
+    content: str
+    level: int
+    subsections: list["AgentsMDSection"]
+
+
+@dataclass
+class AgentsMDConfig:
+    """Parsed AGENTS.md configuration.
+
+    Attributes:
+        project_overview: High-level project description and context.
+        setup_commands: Commands for project setup/installation.
+        dev_environment_tips: Development environment recommendations.
+        code_style: Code style guidelines and conventions.
+        build_commands: Commands for building the project.
+        testing_instructions: How to run tests and validation.
+        security_considerations: Security guidelines and best practices.
+        pr_instructions: Pull request guidelines and workflow.
+        custom_sections: Additional custom sections not in the standard spec.
+    """
+
+    project_overview: str
+    setup_commands: list[str]
+    dev_environment_tips: list[str]
+    code_style: list[str]
+    build_commands: list[str]
+    testing_instructions: list[str]
+    security_considerations: list[str]
+    pr_instructions: list[str]
+    custom_sections: dict[str, str]
+
+
+@FormatAdapterRegistry.register
+class AgentsMDAdapter(BaseFormatAdapter):
+    """Adapter for parsing and using AGENTS.md files.
+
+    This adapter implements support for the AGENTS.md specification, which provides
+    a standardized way to document project context and guidelines for AI agents.
+    It parses AGENTS.md files and converts them to A2A/ADK-compatible capabilities.
+    """
+
+    FORMAT_NAME = "agents_md"
+    SUPPORTED_FILES = ["AGENTS.md"]
+
+    def __init__(self, file_path: Path | None):
+        """Initialize AGENTS.md adapter.
+
+        Args:
+            file_path: Path to AGENTS.md file
+        """
+        # Call parent init which will parse the content
+        super().__init__(file_path)
+
+        # Store parsed config for backward compatibility
+        self.config: AgentsMDConfig | None = None
+        if self.parsed:
+            self.config = self.parsed.to_dict().get("config")
+
+        # For backward compatibility
+        self.project_root = file_path.parent if file_path else None
+        self.agents_md_path = file_path
+
+    def parse(self, content: str) -> ParsedContent:
+        """Parse AGENTS.md content (required by base class).
+
+        Args:
+            content: Raw AGENTS.md content
+
+        Returns:
+            ParsedContent with parsed configuration
+        """
+        config = self._parse_agents_md_content(content)
+        return ParsedContent(config=config)
+
+    def _parse_agents_md_content(self, content: str) -> AgentsMDConfig:
+        """Parse AGENTS.md file into structured config.
+
+        Extracts standard sections (overview, setup, code style, etc.) and
+        custom sections from the AGENTS.md file into a structured configuration.
+
+        Args:
+            content: Raw AGENTS.md content
+
+        Returns:
+            Parsed AgentsMDConfig
+        """
+
+        # Initialize config with defaults
+        config = AgentsMDConfig(
+            project_overview="",
+            setup_commands=[],
+            dev_environment_tips=[],
+            code_style=[],
+            build_commands=[],
+            testing_instructions=[],
+            security_considerations=[],
+            pr_instructions=[],
+            custom_sections={},
+        )
+
+        # Parse sections
+        sections = self._parse_sections(content)
+
+        for section in sections:
+            title_lower = section.title.lower()
+
+            if "overview" in title_lower or "project" in title_lower:
+                config.project_overview = section.content.strip()
+            elif "setup" in title_lower:
+                config.setup_commands = self._extract_commands(section.content)
+            elif "dev" in title_lower or "environment" in title_lower:
+                config.dev_environment_tips = self._extract_bullets(section.content)
+            elif "style" in title_lower or "code" in title_lower:
+                config.code_style = self._extract_bullets(section.content)
+            elif "build" in title_lower:
+                config.build_commands = self._extract_commands(section.content)
+            elif "test" in title_lower:
+                config.testing_instructions = self._extract_bullets(section.content)
+            elif "security" in title_lower:
+                config.security_considerations = self._extract_bullets(section.content)
+            elif "pr" in title_lower or "pull request" in title_lower:
+                config.pr_instructions = self._extract_bullets(section.content)
+            else:
+                # Custom section
+                config.custom_sections[section.title] = section.content.strip()
+
+        return config
+
+    def _parse_sections(self, content: str) -> list[AgentsMDSection]:
+        """Parse markdown sections.
+
+        Identifies markdown headers (# ## ###) and groups content into
+        hierarchical sections with their heading levels preserved.
+
+        Args:
+            content: Markdown content
+
+        Returns:
+            List of parsed sections
+        """
+        sections = []
+        lines = content.split("\n")
+        current_section = None
+        current_content = []
+
+        for line in lines:
+            # Check for section header
+            if line.startswith("#"):
+                # Save previous section
+                if current_section:
+                    current_section.content = "\n".join(current_content)
+                    sections.append(current_section)
+
+                # Parse new section
+                level = len(re.match(r"^#+", line).group())
+                title = line.lstrip("#").strip()
+
+                current_section = AgentsMDSection(
+                    title=title, content="", level=level, subsections=[]
+                )
+                current_content = []
+            elif current_section:
+                current_content.append(line)
+
+        # Save last section
+        if current_section:
+            current_section.content = "\n".join(current_content)
+            sections.append(current_section)
+
+        return sections
+
+    def _extract_commands(self, content: str) -> list[str]:
+        """Extract command strings from content.
+
+        Finds commands in inline code (`command`) and code blocks,
+        typically used for setup, build, and test commands.
+
+        Args:
+            content: Section content
+
+        Returns:
+            List of command strings
+        """
+        commands = []
+
+        # Extract from code blocks
+        code_blocks = re.findall(r"`([^`]+)`", content)
+        commands.extend(code_blocks)
+
+        # Extract from bullets with code
+        bullets = re.findall(r"^\s*[-*]\s+.*?`([^`]+)`", content, re.MULTILINE)
+        commands.extend(bullets)
+
+        return commands
+
+    def _extract_bullets(self, content: str) -> list[str]:
+        """Extract bullet points from content.
+
+        Parses markdown list items (- or *) from the content,
+        commonly used for guidelines and recommendations.
+
+        Args:
+            content: Section content
+
+        Returns:
+            List of bullet point strings
+        """
+        bullets = []
+
+        for line in content.split("\n"):
+            line = line.strip()
+            if line.startswith("-") or line.startswith("*"):
+                bullets.append(line[1:].strip())
+
+        return bullets
+
+    def to_system_prompt(self) -> str:
+        """Convert AGENTS.md to system prompt for agents.
+
+        Returns:
+            Formatted system prompt string
+        """
+        if not self.config:
+            return ""
+
+        prompt_parts = []
+
+        if self.config.project_overview:
+            prompt_parts.append(f"# Project Context\n\n{self.config.project_overview}")
+
+        if self.config.setup_commands:
+            prompt_parts.append("\n## Setup Commands\n")
+            for cmd in self.config.setup_commands:
+                prompt_parts.append(f"- `{cmd}`")
+
+        if self.config.code_style:
+            prompt_parts.append("\n## Code Style Rules\n")
+            for rule in self.config.code_style:
+                prompt_parts.append(f"- {rule}")
+
+        if self.config.build_commands:
+            prompt_parts.append("\n## Build Commands\n")
+            for cmd in self.config.build_commands:
+                prompt_parts.append(f"- `{cmd}`")
+
+        if self.config.testing_instructions:
+            prompt_parts.append("\n## Testing Instructions\n")
+            for instruction in self.config.testing_instructions:
+                prompt_parts.append(f"- {instruction}")
+
+        if self.config.pr_instructions:
+            prompt_parts.append("\n## PR Guidelines\n")
+            for instruction in self.config.pr_instructions:
+                prompt_parts.append(f"- {instruction}")
+
+        return "\n".join(prompt_parts)
+
+    def to_adk_capabilities(self) -> dict:
+        """Convert AGENTS.md to ADK capabilities format.
+
+        Transforms the parsed AGENTS.md configuration into the capability
+        format expected by the Agent Development Kit (ADK) and A2A protocol.
+
+        Returns:
+            ADK capabilities dictionary with project context and guidelines.
+        """
+        if not self.config:
+            return {}
+
+        return {
+            "project_context": self.config.project_overview,
+            "setup": self.config.setup_commands,
+            "development": self.config.dev_environment_tips,
+            "code_style": self.config.code_style,
+            "build": self.config.build_commands,
+            "testing": self.config.testing_instructions,
+            "security": self.config.security_considerations,
+            "pr_guidelines": self.config.pr_instructions,
+            "custom": self.config.custom_sections,
+        }
+
+    def merge_with_skills(self, skills_prompt: str) -> str:
+        """Merge AGENTS.md context with agent skills prompt.
+
+        Args:
+            skills_prompt: Existing skills-based prompt
+
+        Returns:
+            Combined prompt with both contexts
+        """
+        agents_prompt = self.to_system_prompt()
+
+        if not agents_prompt:
+            return skills_prompt
+
+        return f"""{agents_prompt}
+
+---
+
+{skills_prompt}
+"""