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

uacs/adapters/base.py

@@ -0,0 +1,261 @@
+"""Base adapter class for format translation."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Skill:
+    """Skill information."""
+
+    name: str
+    instructions: str
+    triggers: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    description: str | None = None
+    examples: list[str] = field(default_factory=list)
+
+
+class ParsedContent:
+    """Parsed content from format."""
+
+    name: str | None = None
+    description: str | None = None
+    instructions: str | None = None
+    metadata: dict[str, Any] | None = None
+    rules: str | None = None
+
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+        # Set attributes from kwargs for type safety
+        for k, v in kwargs.items():
+            if hasattr(self, k):
+                setattr(self, k, v)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return self.__dict__
+
+    def __repr__(self) -> str:
+        return f"ParsedContent({self.__dict__})"
+
+
+class BaseFormatAdapter(ABC):
+    """Base class for all format adapters."""
+
+    FORMAT_NAME: str = "base"
+    SUPPORTED_FILES: list[str] = []
+
+    def __init__(self, file_path: Path | None = None):
+        self.file_path = file_path
+        self.content = file_path.read_text() if file_path and file_path.exists() else ""
+        self.parsed = self.parse(self.content) if self.content else None
+
+    @abstractmethod
+    def parse(self, content: str) -> ParsedContent:
+        """Parse format-specific content.
+
+        Args:
+            content: Raw file content
+
+        Returns:
+            Parsed content object
+        """
+        pass
+
+    @abstractmethod
+    def to_system_prompt(self) -> str:
+        """Convert to system prompt format.
+
+        Returns:
+            Formatted system prompt string
+        """
+        pass
+
+    def to_adk_capabilities(self) -> dict[str, Any]:
+        """Convert to ADK agent card format (optional).
+
+        Returns:
+            ADK capabilities dictionary
+        """
+        return {}
+
+    def exists(self) -> bool:
+        """Check if file exists.
+
+        Returns:
+            True if file exists
+        """
+        return self.file_path and self.file_path.exists()
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get adapter statistics.
+
+        Returns:
+            Dictionary with adapter stats
+        """
+        return {
+            "format": self.FORMAT_NAME,
+            "file": str(self.file_path),
+            "exists": self.exists(),
+            "size": len(self.content),
+            "parsed": self.parsed.to_dict() if self.parsed else None,
+        }
+
+    def find_skill_by_trigger(self, query: str) -> Skill | None:
+        """Find skill that matches query trigger.
+
+        Default implementation: no matching.
+        Subclasses can override for trigger-based matching.
+
+        Args:
+            query: User query to match against triggers
+
+        Returns:
+            Matching skill or None
+        """
+        return None
+
+    @classmethod
+    def supports_file(cls, file_path: Path) -> bool:
+        """Check if this adapter supports the file.
+
+        Args:
+            file_path: Path to check
+
+        Returns:
+            True if adapter supports this file
+        """
+        return file_path.name in cls.SUPPORTED_FILES
+
+
+class FormatAdapterRegistry:
+    """Registry for format adapters."""
+
+    _adapters: dict[str, type["BaseFormatAdapter"]] = {}
+
+    @classmethod
+    def register(
+        cls, adapter_class: type["BaseFormatAdapter"]
+    ) -> type["BaseFormatAdapter"]:
+        """Register adapter class.
+
+        Args:
+            adapter_class: Adapter class to register
+
+        Returns:
+            The adapter class (for decorator usage)
+        """
+        cls._adapters[adapter_class.FORMAT_NAME] = adapter_class
+        return adapter_class
+
+    @classmethod
+    def detect_and_load(
+        cls, project_path: Path, search_parents: bool = True
+    ) -> BaseFormatAdapter | None:
+        """Auto-detect format and return adapter.
+
+        Searches for supported files in:
+        1. Project directory (project-specific config)
+        2. Parent directories up to root (following AGENTS.md spec)
+        3. User home directory (personal/global config)
+
+        Args:
+            project_path: Path to project directory
+            search_parents: Whether to search parent directories
+
+        Returns:
+            Adapter instance or None if no format detected
+        """
+        search_paths = [project_path]
+
+        # Add parent directories
+        if search_parents:
+            current = project_path
+            while current != current.parent:
+                current = current.parent
+                search_paths.append(current)
+
+        # Add user home directory for personal skills
+        home_config_paths = [
+            Path.home() / ".claude",  # Claude Code personal skills
+            Path.home() / ".config" / "uacs",  # UACS config directory
+        ]
+        search_paths.extend(home_config_paths)
+
+        # Search all paths for supported files
+        for adapter_class in cls._adapters.values():
+            for filename in adapter_class.SUPPORTED_FILES:
+                for search_path in search_paths:
+                    file_path = search_path / filename
+                    if file_path.exists():
+                        return adapter_class(file_path)
+
+        return None
+
+    @classmethod
+    def detect_and_load_all(cls, project_path: Path) -> list[BaseFormatAdapter]:
+        """Detect and load all available format adapters.
+
+        Finds all supported files in project and personal directories.
+        Also discovers multiple SKILL.md files from .claude/skills/*
+
+        Args:
+            project_path: Path to project directory
+
+        Returns:
+            List of adapter instances
+        """
+        adapters = []
+        found_files = set()
+
+        search_paths = [
+            project_path,
+            Path.home() / ".claude",
+            Path.home() / ".config" / "uacs",
+        ]
+
+        for adapter_class in cls._adapters.values():
+            for filename in adapter_class.SUPPORTED_FILES:
+                for search_path in search_paths:
+                    file_path = search_path / filename
+                    if file_path.exists() and str(file_path) not in found_files:
+                        adapters.append(adapter_class(file_path))
+                        found_files.add(str(file_path))
+
+        # Special case: Discover multiple SKILL.md files from .agent/skills/* and .claude/skills/*
+        from .agent_skill_adapter import AgentSkillAdapter
+
+        agent_skills = AgentSkillAdapter.discover_skills(project_path)
+        for skill in agent_skills:
+            if str(skill.file_path) not in found_files:
+                adapters.append(skill)
+                found_files.add(str(skill.file_path))
+
+        return adapters
+
+    @classmethod
+    def list_formats(cls) -> list[str]:
+        """List registered formats.
+
+        Returns:
+            List of format names
+        """
+        return list(cls._adapters.keys())
+
+    @classmethod
+    def get_adapter(cls, format_name: str) -> type | None:
+        """Get adapter class by format name.
+
+        Args:
+            format_name: Name of the format
+
+        Returns:
+            Adapter class or None if not found
+        """
+        return cls._adapters.get(format_name)
+
+
+__all__ = ["BaseFormatAdapter", "FormatAdapterRegistry", "ParsedContent", "Skill"]

uacs/adapters/clinerules_adapter.py

@@ -0,0 +1,39 @@
+"""Adapter for Cline .clinerules format."""
+
+from .base import BaseFormatAdapter, FormatAdapterRegistry, ParsedContent
+
+
+@FormatAdapterRegistry.register
+class ClineRulesAdapter(BaseFormatAdapter):
+    """Cline .clinerules format adapter.
+
+    Cline rules are typically plain text instructions for the Cline AI assistant.
+    """
+
+    FORMAT_NAME = "clinerules"
+    SUPPORTED_FILES = [".clinerules"]
+
+    def parse(self, content: str) -> ParsedContent:
+        """Parse .clinerules format.
+
+        Args:
+            content: Raw .clinerules content
+
+        Returns:
+            ParsedContent with rules
+        """
+        return ParsedContent(rules=content.strip())
+
+    def to_system_prompt(self) -> str:
+        """Convert to system prompt.
+
+        Returns:
+            Formatted system prompt
+        """
+        if not self.parsed or not self.parsed.rules:
+            return ""
+
+        return f"# PROJECT RULES\n\n{self.parsed.rules}"
+
+
+__all__ = ["ClineRulesAdapter"]

uacs/adapters/cursorrules_adapter.py

@@ -0,0 +1,39 @@
+"""Adapter for Cursor .cursorrules format."""
+
+from .base import BaseFormatAdapter, FormatAdapterRegistry, ParsedContent
+
+
+@FormatAdapterRegistry.register
+class CursorRulesAdapter(BaseFormatAdapter):
+    """Cursor .cursorrules format adapter.
+
+    Cursor rules are typically plain text instructions for the Cursor editor.
+    """
+
+    FORMAT_NAME = "cursorrules"
+    SUPPORTED_FILES = [".cursorrules"]
+
+    def parse(self, content: str) -> ParsedContent:
+        """Parse .cursorrules format (usually plain text).
+
+        Args:
+            content: Raw .cursorrules content
+
+        Returns:
+            ParsedContent with rules
+        """
+        return ParsedContent(rules=content.strip())
+
+    def to_system_prompt(self) -> str:
+        """Convert to system prompt.
+
+        Returns:
+            Formatted system prompt
+        """
+        if not self.parsed or not self.parsed.rules:
+            return ""
+
+        return f"# PROJECT RULES\n\n{self.parsed.rules}"
+
+
+__all__ = ["CursorRulesAdapter"]

uacs/api.py

@@ -0,0 +1,262 @@
+"""Universal Agent Context System - Main API
+
+See docs/uacs/README.md for details.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from uacs.adapters.agent_skill_adapter import AgentSkillAdapter
+from uacs.adapters.agents_md_adapter import AgentsMDAdapter
+from uacs.context.shared_context import SharedContextManager
+from uacs.context.unified_context import UnifiedContextAdapter
+from uacs.packages import PackageManager
+
+
+class UACS:
+    """Universal Agent Context System
+
+    Provides unified context management across:
+    - Packages (Local package management)
+    - Adapters (Format translation)
+    - Context (Shared memory + compression)
+    - Project metadata (AGENTS.md)
+
+    Example:
+        >>> uacs = UACS(project_path=Path("."))
+        >>> uacs.install_package("owner/repo")
+        >>> context = uacs.build_context(query="...", agent="claude")
+    """
+
+    def __init__(
+        self,
+        project_path: Path,
+    ):
+        """Initialize UACS.
+
+        Args:
+            project_path: Path to the project root
+        """
+        self.project_path = project_path
+
+        # Initialize components
+        self.packages = PackageManager(project_path)
+
+        # Detect and load project format adapters
+        agents_md_path = project_path / "AGENTS.md"
+
+        # Modern Agent Skills support (.agent/skills/)
+        self.agent_skills = AgentSkillAdapter.discover_skills(project_path)
+
+        self.agents_md = (
+            AgentsMDAdapter(agents_md_path) if agents_md_path.exists() else None
+        )
+
+        # Initialize shared context and unified adapter
+        self.shared_context = SharedContextManager(project_path / ".state" / "context")
+        self.unified_context = UnifiedContextAdapter(
+            agents_md_path=agents_md_path if agents_md_path.exists() else None,
+            context_storage=project_path / ".state" / "context",
+        )
+
+    def install_package(
+        self,
+        source: str,
+        validate: bool = True,
+        force: bool = False,
+    ) -> Any:
+        """Install a package from GitHub, Git URL, or local path.
+
+        Args:
+            source: Package source (owner/repo, git URL, or local path)
+            validate: Whether to validate before installing
+            force: Whether to overwrite existing package
+
+        Returns:
+            Installed package information
+        """
+        return self.packages.install(source, validate=validate, force=force)
+
+    def list_packages(self) -> list[Any]:
+        """List installed packages.
+
+        Returns:
+            List of installed packages
+        """
+        return self.packages.list_installed()
+
+    def get_capabilities(self, agent: str | None = None) -> dict[str, Any]:
+        """Get available capabilities for an agent.
+
+        Args:
+            agent: Optional agent name to filter capabilities
+
+        Returns:
+            Dictionary of capabilities
+        """
+        capabilities = self.unified_context.get_capabilities(agent_name=agent)
+
+        # Add discovered Agent Skills
+        if self.agent_skills:
+            capabilities["agent_skills"] = [
+                {
+                    "name": skill.parsed.name,
+                    "description": skill.parsed.description,
+                    "triggers": skill.parsed.triggers,
+                    "source": skill.source_directory or "local",
+                }
+                for skill in self.agent_skills
+                if skill.parsed
+            ]
+
+        return capabilities
+
+    def build_context(
+        self,
+        query: str,
+        agent: str,
+        max_tokens: int | None = None,
+        topics: list[str] | None = None,
+    ) -> str:
+        """Build context for an agent query.
+
+        Args:
+            query: The query or task
+            agent: Agent name (claude, gemini, etc.)
+            max_tokens: Optional token limit
+            topics: Optional topics to filter and prioritize context
+
+        Returns:
+            Formatted context string
+        """
+        # If topics are provided, use focused context
+        if topics:
+            focused_context = self.shared_context.get_focused_context(
+                topics=topics, agent=agent, max_tokens=max_tokens or 4000
+            )
+            # Combine with unified context
+            unified = self.unified_context.build_context(
+                query=query, agent_name=agent, max_tokens=max_tokens
+            )
+            return f"{focused_context}\n\n{unified}" if focused_context else unified
+
+        return self.unified_context.build_context(
+            query=query, agent_name=agent, max_tokens=max_tokens
+        )
+
+    def add_to_context(
+        self,
+        key: str,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+        topics: list[str] | None = None,
+    ):
+        """Add content to shared context.
+
+        Args:
+            key: Context key (used as agent name)
+            content: Content to store
+            metadata: Optional metadata
+            topics: Optional topics for semantic filtering
+
+        Example:
+            uacs.add_to_context(
+                "claude",
+                "Reviewed auth.py, found SQL injection",
+                topics=["code-review", "security"]
+            )
+        """
+        # Add to shared context with topics
+        self.shared_context.add_entry(
+            content=content,
+            agent=key,
+            metadata=metadata,
+            topics=topics,
+        )
+
+    def get_token_stats(self) -> dict[str, int]:
+        """Get token usage statistics.
+
+        Returns:
+            Dictionary of token counts
+        """
+        return self.unified_context.get_token_stats()
+
+    def export_config(self, output_path: Path):
+        """Export UACS configuration.
+
+        Args:
+            output_path: Path to save configuration
+        """
+        self.unified_context.export_unified_config(output_path)
+
+
+    def visualize_context(self, output_path: Path | None = None) -> str:
+        """Visualize context structure.
+
+        Args:
+            output_path: Optional path to save visualization
+
+        Returns:
+            Visualization string (ASCII art or HTML)
+        """
+        from uacs.visualization import ContextVisualizer
+
+        visualizer = ContextVisualizer()
+        # Get graph and stats from shared context
+        graph = self.shared_context.get_context_graph()
+        stats = self.shared_context.get_stats()
+
+        # Render the visualizations
+        graph_panel = visualizer.render_context_graph(graph)
+        stats_table = visualizer.render_stats_table(stats)
+
+        # Print to console
+        visualizer.console.print(graph_panel)
+        visualizer.console.print(stats_table)
+
+        # Optionally save to file
+        if output_path:
+            output_path.write_text(f"Context Graph: {graph}\nStats: {stats}")
+            return f"Visualization saved to {output_path}"
+
+        return "Visualization rendered to console"
+
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get comprehensive UACS statistics.
+
+        Returns:
+            Dictionary with statistics from all components
+        """
+        # Merge token stats with shared context stats
+        token_stats = self.get_token_stats()
+        context_stats = self.shared_context.get_stats()
+        token_stats.update(context_stats)
+
+        stats = {
+            "project_path": str(self.project_path),
+            "adapters": {
+                "agent_skills": {
+                    "count": len(self.agent_skills),
+                    "paths": [str(s.file_path) for s in self.agent_skills],
+                },
+                "agents_md": {
+                    "loaded": self.agents_md is not None,
+                    "path": str(self.project_path / "AGENTS.md")
+                    if self.agents_md
+                    else None,
+                },
+            },
+            "packages": {
+                "installed_count": len(self.packages.list_installed()),
+                "skills_dir": str(self.project_path / ".agent" / "skills"),
+            },
+            "context": token_stats,
+            "capabilities": self.get_capabilities(),
+        }
+
+        return stats
+
+
+__all__ = ["UACS"]

uacs/cli/__init__.py

@@ -0,0 +1,6 @@
+"""CLI commands for UACS."""
+
+from uacs.cli import context, memory, mcp, packages, skills
+from uacs.cli.main import app
+
+__all__ = ["app", "context", "skills", "packages", "memory", "mcp"]