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

uacs/context/unified_context.py

@@ -0,0 +1,332 @@
+"""Unified context adapter combining agent skills, AGENTS.md, and shared context.
+
+This module creates a single unified interface for all agent context sources:
+- SKILL.md: Individual skill files (Agent Skills format, recommended)
+- AGENTS.md: Project-specific instructions
+- Shared Context: Runtime agent communication with compression
+"""
+
+import json
+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.utils.paths import get_project_root
+
+
+class UnifiedContextAdapter:
+    """Unified adapter for all agent context sources."""
+
+    def __init__(
+        self,
+        agents_md_path: Path | None = None,
+        context_storage: Path | None = None,
+    ):
+        """Initialize unified adapter.
+
+        Args:
+            agents_md_path: Path to AGENTS.md or project root
+            context_storage: Path for shared context storage
+        """
+        # Initialize all adapters
+        self.agents_md = AgentsMDAdapter(agents_md_path)
+        self.shared_context = SharedContextManager(context_storage)
+        self.agent_skills = AgentSkillAdapter.discover_skills(get_project_root())
+
+    def build_agent_prompt(
+        self,
+        user_query: str,
+        agent_name: str,
+        include_history: bool = True,
+        max_context_tokens: int = 4000,
+    ) -> str:
+        """Build complete agent prompt with all context sources.
+
+        Args:
+            user_query: User's query
+            agent_name: Name of agent receiving prompt
+            include_history: Include shared context history
+            max_context_tokens: Max tokens for context
+
+        Returns:
+            Complete prompt string
+        """
+        prompt_parts = []
+
+        # 1. AGENTS.md project context (if available)
+        agents_md_prompt = self.agents_md.to_system_prompt()
+        if agents_md_prompt:
+            prompt_parts.append("# PROJECT CONTEXT (from AGENTS.md)")
+            prompt_parts.append(agents_md_prompt)
+            prompt_parts.append("")
+
+        # 2. Skills capabilities (search Agent Skills format)
+        skill_prompt = None
+
+        # Try Agent Skills format (recommended)
+        for adapter in self.agent_skills:
+            if adapter.parsed and hasattr(adapter.parsed, "triggers"):
+                query_lower = user_query.lower()
+                for trigger in adapter.parsed.triggers:
+                    if trigger.lower() in query_lower or query_lower in trigger.lower():
+                        skill_prompt = adapter.to_system_prompt()
+                        break
+            if skill_prompt:
+                break
+
+        if skill_prompt:
+            prompt_parts.append("# ACTIVE SKILL")
+            prompt_parts.append(skill_prompt)
+            prompt_parts.append("")
+
+        # 3. Shared context from other agents (if enabled)
+        if include_history:
+            # Reserve tokens for history
+            reserved_tokens = max_context_tokens // 2
+            context_history = self.shared_context.get_compressed_context(
+                agent=None,  # Include all agents
+                max_tokens=reserved_tokens,
+            )
+
+            if context_history:
+                prompt_parts.append("# SHARED CONTEXT (from other agents)")
+                prompt_parts.append(context_history)
+                prompt_parts.append("")
+
+        # 4. User query
+        prompt_parts.append("# USER REQUEST")
+        prompt_parts.append(user_query)
+
+        full_prompt = "\n".join(prompt_parts)
+
+        # Store this interaction in shared context
+        self.shared_context.add_entry(
+            content=f"Query: {user_query[:200]}...", agent=agent_name, references=[]
+        )
+
+        return full_prompt
+
+    def export_config(self, output_path: Path) -> None:
+        """Export unified context configuration.
+
+        Args:
+            output_path: Path to save configuration
+        """
+        config = {
+            "skills_path": ".agent/skills/",
+            "agents_md_path": str(self.agents_md.file_path)
+            if self.agents_md.file_path
+            else None,
+            "context_storage": str(self.shared_context.storage_path)
+            if self.shared_context.storage_path
+            else None,
+            "capabilities": self.get_unified_capabilities(),
+        }
+
+        output_path.write_text(json.dumps(config, indent=2))
+
+    def record_agent_response(
+        self, agent_name: str, response: str, references: list | None = None
+    ) -> str:
+        """Record agent response in shared context.
+
+        Args:
+            agent_name: Name of responding agent
+            response: Agent's response
+            references: IDs of context entries referenced
+
+        Returns:
+            Entry ID
+        """
+        return self.shared_context.add_entry(
+            content=response, agent=agent_name, references=references or []
+        )
+
+    def get_unified_capabilities(self) -> dict[str, Any]:
+        """Get all capabilities from all sources.
+
+        Returns:
+            Combined capabilities dictionary
+        """
+        skills_capabilities = []
+        available_skills = []
+
+        for adapter in self.agent_skills:
+            if adapter.parsed:
+                skills_capabilities.append(adapter.to_adk_capabilities())
+                available_skills.append(adapter.parsed.name)
+
+        return {
+            "skills": skills_capabilities,
+            "project_context": self.agents_md.to_adk_capabilities(),
+            "shared_context_stats": self.shared_context.get_stats(),
+            "available_skills": available_skills,
+            "agents_md_loaded": self.agents_md.config is not None,
+        }
+
+    def get_token_stats(self) -> dict[str, Any]:
+        """Get token usage statistics across all sources.
+
+        Returns:
+            Token statistics
+        """
+        context_stats = self.shared_context.get_stats()
+
+        # Estimate tokens from AGENTS.md
+        agents_md_tokens = 0
+        if self.agents_md.config:
+            agents_md_prompt = self.agents_md.to_system_prompt()
+            agents_md_tokens = len(agents_md_prompt) // 4
+
+        # Estimate tokens from Agent Skills
+        skills_tokens = 0
+        for adapter in self.agent_skills:
+            skill_prompt = adapter.to_system_prompt()
+            skills_tokens += len(skill_prompt) // 4
+
+        return {
+            "agents_md_tokens": agents_md_tokens,
+            "skills_tokens": skills_tokens,
+            "shared_context_tokens": context_stats["total_tokens"],
+            "tokens_saved_by_compression": context_stats["tokens_saved"],
+            "total_potential_tokens": agents_md_tokens
+            + skills_tokens
+            + context_stats["total_tokens"],
+            "compression_ratio": context_stats["compression_ratio"],
+        }
+
+    def optimize_context(self):
+        """Trigger context optimization (compression, summarization).
+
+        This is called automatically but can be triggered manually.
+        """
+        # The shared context manager handles this internally
+        self.shared_context._auto_compress()
+
+    def export_unified_config(self, output_path: Path):
+        """Export unified configuration to JSON.
+
+        Args:
+            output_path: Path to save configuration
+        """
+
+        config = {
+            "capabilities": self.get_unified_capabilities(),
+            "token_stats": self.get_token_stats(),
+            "context_graph": self.shared_context.get_context_graph(),
+        }
+
+        output_path.write_text(json.dumps(config, indent=2))
+
+    def visualize_context(self):
+        """Launch interactive context visualization."""
+
+    from uacs.visualization import ContextVisualizer
+
+    def create_snapshot(self, name: str) -> dict[str, Any]:
+        """Create snapshot of current context state.
+
+        Args:
+            name: Snapshot name
+
+        Returns:
+            Snapshot data
+        """
+        snapshot = {
+            "name": name,
+            "timestamp": __import__("datetime").datetime.now().isoformat(),
+            "capabilities": self.get_unified_capabilities(),
+            "token_stats": self.get_token_stats(),
+            "context_entries": len(self.shared_context.entries),
+            "summaries": len(self.shared_context.summaries),
+        }
+
+        # Save snapshot
+        snapshot_path = self.shared_context.storage_path / f"snapshot_{name}.json"
+
+        snapshot_path.write_text(json.dumps(snapshot, indent=2))
+
+        return snapshot
+
+    def get_compression_report(self) -> str:
+        """Get detailed compression report.
+
+        Returns:
+            Formatted report string
+        """
+        stats = self.shared_context.get_stats()
+        token_stats = self.get_token_stats()
+
+        report = f"""
+# Context Compression Report
+
+## Overall Statistics
+- Total Entries: {stats["entry_count"]}
+- Summaries Created: {stats["summary_count"]}
+- Compression Ratio: {stats["compression_ratio"]}
+- Storage Size: {stats["storage_size_mb"]:.2f} MB
+
+## Token Savings
+- Original Tokens: {stats["total_tokens"] + stats["tokens_saved"]:,}
+- Current Tokens: {stats["total_tokens"]:,}
+- Saved by Compression: {stats["tokens_saved"]:,}
+- Effective Reduction: {stats["compression_ratio"]}
+
+## Source Breakdown
+- AGENTS.md: {token_stats["agents_md_tokens"]:,} tokens
+- Agent Skills: {token_stats["skills_tokens"]:,} tokens (across {len(self.skills.skills)} skills)
+- Shared Context: {token_stats["shared_context_tokens"]:,} tokens
+
+## Recommendations
+"""
+
+        # Add recommendations based on stats
+        if stats["entry_count"] > 20:
+            report += "- Consider creating more summaries to reduce token usage\n"
+
+        if stats["compression_ratio"] == "0%":
+            report += (
+                "- No compression active yet - will auto-compress after 10+ entries\n"
+            )
+
+        if token_stats["shared_context_tokens"] > 4000:
+            report += "- Shared context is large - consider reviewing old entries\n"
+
+        return report
+
+    def get_capabilities(self, agent_name: str | None = None) -> dict[str, Any]:
+        """Get available capabilities for an agent.
+
+        Args:
+            agent_name: Optional agent name to filter capabilities
+
+        Returns:
+            Dictionary of capabilities
+        """
+        skill_names = [s.parsed.name for s in self.agent_skills if s.parsed]
+        return {
+            "skills": skill_names,
+            "agents_md_loaded": self.agents_md.exists(),
+            "context_entries": len(self.shared_context.entries),
+        }
+
+    def build_context(
+        self, query: str, agent_name: str, max_tokens: int | None = None
+    ) -> str:
+        """Build context for an agent query.
+
+        Args:
+            query: The query or task
+            agent_name: Agent name
+            max_tokens: Optional token limit
+
+        Returns:
+            Formatted context string
+        """
+        return self.build_agent_prompt(
+            user_query=query,
+            agent_name=agent_name,
+            max_context_tokens=max_tokens or 4000,
+        )

uacs/mcp_server_entry.py

@@ -0,0 +1,80 @@
+"""Entry point for UACS MCP Server."""
+import argparse
+import asyncio
+import sys
+import os
+
+
+async def run_sse(port: int = 3000):
+    """Run the server using SSE transport."""
+    import uvicorn
+    from starlette.applications import Starlette
+    from starlette.responses import JSONResponse, Response
+    from starlette.routing import Route, Mount
+    from mcp.server.sse import SseServerTransport
+    from uacs.protocols.mcp.skills_server import server
+
+    # Initialize SSE transport
+    # Note: '/messages/' must be a relative path for the client to post to.
+    sse = SseServerTransport("/messages/")
+
+    async def handle_sse(request):
+        """Handle SSE connection."""
+        async with sse.connect_sse(
+            request.scope, request.receive, request._send
+        ) as streams:
+            await server.run(
+                streams[0], streams[1], server.create_initialization_options()
+            )
+        return Response()
+
+    async def health_check(request):
+        """Health check endpoint."""
+        return JSONResponse({"status": "ok"})
+
+    routes = [
+        Route("/sse", endpoint=handle_sse),
+        Mount("/messages", app=sse.handle_post_message),
+        Route("/health", endpoint=health_check),
+    ]
+
+    app = Starlette(routes=routes)
+
+    # Configure uvicorn
+    config = uvicorn.Config(app, host="0.0.0.0", port=port, log_level="info")
+    server_instance = uvicorn.Server(config)
+    await server_instance.serve()
+
+async def run_stdio():
+    """Run the server using stdio transport."""
+    from uacs.protocols.mcp.skills_server import server
+    from mcp.server.stdio import stdio_server
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream, write_stream, server.create_initialization_options()
+        )
+
+def main():
+    parser = argparse.ArgumentParser(description="UACS MCP Server")
+    default_transport = os.environ.get("UACS_TRANSPORT", "stdio")
+    parser.add_argument("--transport", choices=["stdio", "sse"], default=default_transport, help="Transport mode")
+    parser.add_argument("--port", type=int, default=3000, help="Port for SSE server")
+
+    # Parse args (this will handle --help and exit automatically)
+    args = parser.parse_args()
+
+    # If we get here, args are valid
+    try:
+        if args.transport == "sse":
+            asyncio.run(run_sse(args.port))
+        else:
+            asyncio.run(run_stdio())
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

uacs/memory/__init__.py

@@ -0,0 +1,5 @@
+"""Simple JSON-based memory store for UACS."""
+
+from .simple_memory import MemoryEntry, SimpleMemoryStore
+
+__all__ = ["MemoryEntry", "SimpleMemoryStore"]

uacs/memory/simple_memory.py

@@ -0,0 +1,255 @@
+"""Simple JSON-based memory store with project/global hierarchy."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+VALID_SCOPES = {"project", "global"}
+
+
+def _utcnow_iso() -> str:
+    """Return current UTC timestamp in ISO format."""
+    return datetime.now(UTC).isoformat()
+
+
+def _sanitize_key(key: str) -> str:
+    """Convert arbitrary keys into safe filenames."""
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "-", key.strip())
+    return cleaned or "memory-entry"
+
+
+@dataclass
+class MemoryEntry:
+    """Structured representation of a memory entry."""
+
+    key: str
+    scope: str
+    data: dict[str, Any]
+    created_at: str
+    updated_at: str
+    path: Path
+
+    @classmethod
+    def from_file(cls, path: Path, scope: str) -> MemoryEntry | None:
+        """Load a memory entry from a JSON file."""
+        try:
+            raw = json.loads(path.read_text())
+        except json.JSONDecodeError:
+            return None
+
+        data_field = raw.get("data")
+        if data_field is None:
+            data_field = {k: v for k, v in raw.items() if not k.startswith("_")}
+
+        return cls(
+            key=raw.get("_key", path.stem),
+            scope=raw.get("_scope", scope),
+            data=data_field if isinstance(data_field, dict) else {},
+            created_at=raw.get("_created", raw.get("_timestamp", _utcnow_iso())),
+            updated_at=raw.get("_updated", raw.get("_timestamp", _utcnow_iso())),
+            path=path,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize entry to dictionary for JSON storage."""
+        return {
+            "_key": self.key,
+            "_scope": self.scope,
+            "_created": self.created_at,
+            "_updated": self.updated_at,
+            "data": self.data,
+        }
+
+
+class SimpleMemoryStore:
+    """Simple JSON-based key-value memory with scoped lookup."""
+
+    def __init__(
+        self,
+        project_path: Path,
+        global_path: Path | None = None,
+    ):
+        self.project_root = project_path / ".state" / "memory"
+        self.global_root = global_path or Path.home() / ".multi-agent" / "memory"
+
+    def init_storage(self, scope: str = "project") -> Path:
+        """Initialize storage directories and config for a scope."""
+        resolved_scope = self._validate_scope(scope)
+        scope_dir = self._scope_dir(resolved_scope)
+        scope_dir.mkdir(parents=True, exist_ok=True)
+
+        config_path = scope_dir.parent / "config.json"
+        if not config_path.exists():
+            payload = {
+                "storage": "simple",
+                "version": "1.0",
+                "initialized_at": _utcnow_iso(),
+                "scope": resolved_scope,
+            }
+            config_path.write_text(json.dumps(payload, indent=2))
+
+        return scope_dir
+
+    def store(
+        self,
+        key: str,
+        value: Mapping[str, Any],
+        scope: str = "project",
+    ) -> MemoryEntry:
+        """Store a memory entry and return the created entry."""
+        resolved_scope = self._validate_scope(scope)
+        sanitized_key = _sanitize_key(key)
+        scope_dir = self.init_storage(resolved_scope)
+
+        file_path = scope_dir / f"{sanitized_key}.json"
+        now = _utcnow_iso()
+        created_at = now
+
+        if not isinstance(value, Mapping):
+            raise ValueError("Memory value must be a mapping")
+
+        existing_entry = self._load_entry(file_path, resolved_scope)
+        if existing_entry:
+            created_at = existing_entry.created_at
+
+        entry = MemoryEntry(
+            key=key,
+            scope=resolved_scope,
+            data=dict(value),
+            created_at=created_at,
+            updated_at=now,
+            path=file_path,
+        )
+
+        file_path.write_text(json.dumps(entry.to_dict(), indent=2))
+        return entry
+
+    def retrieve(self, key: str, scope: str = "both") -> MemoryEntry | None:
+        """Retrieve entry by key honoring project→global lookup."""
+        scopes = (
+            ("project", "global") if scope == "both" else (self._validate_scope(scope),)
+        )
+
+        for current_scope in scopes:
+            file_path = self._scope_dir(current_scope) / f"{_sanitize_key(key)}.json"
+            entry = self._load_entry(file_path, current_scope)
+            if entry:
+                return entry
+
+        return None
+
+    def delete(self, key: str, scope: str = "project") -> bool:
+        """Delete entry for a specific scope."""
+        resolved_scope = self._validate_scope(scope)
+        file_path = self._scope_dir(resolved_scope) / f"{_sanitize_key(key)}.json"
+        if file_path.exists():
+            file_path.unlink()
+            return True
+        return False
+
+    def list_entries(self, scope: str = "both") -> list[MemoryEntry]:
+        """List all entries for the provided scope."""
+        entries: list[MemoryEntry] = []
+        scopes = (
+            ("project", "global") if scope == "both" else (self._validate_scope(scope),)
+        )
+
+        for current_scope in scopes:
+            scope_dir = self._scope_dir(current_scope)
+            if not scope_dir.exists():
+                continue
+            for file_path in scope_dir.glob("*.json"):
+                entry = self._load_entry(file_path, current_scope)
+                if entry:
+                    entries.append(entry)
+        return entries
+
+    def search(self, query: str, scope: str = "both") -> list[MemoryEntry]:
+        """Search entries by substring match."""
+        needle = query.lower()
+        results = []
+        for entry in self.list_entries(scope):
+            haystack = json.dumps(entry.data).lower()
+            if needle in entry.key.lower() or needle in haystack:
+                results.append(entry)
+        return results
+
+    def clean(self, older_than_days: int = 30, scope: str = "project") -> int:
+        """Remove entries older than provided days. Returns deleted count."""
+        resolved_scope = self._validate_scope(scope)
+        cutoff = datetime.now(UTC) - timedelta(days=older_than_days)
+        deleted = 0
+
+        for entry in self.list_entries(resolved_scope):
+            try:
+                created_time = datetime.fromisoformat(entry.created_at)
+            except ValueError:
+                created_time = datetime.utcfromtimestamp(entry.path.stat().st_mtime)
+
+            if created_time.tzinfo is None:
+                created_time = created_time.replace(tzinfo=UTC)
+
+            if created_time < cutoff and entry.path.exists():
+                entry.path.unlink()
+                deleted += 1
+
+        return deleted
+
+    def get_stats(self) -> dict[str, dict[str, Any]]:
+        """Return statistics for project and global scopes."""
+        stats = {}
+        for scope in ("project", "global"):
+            scope_dir = self._scope_dir(scope)
+            entry_files = list(scope_dir.glob("*.json")) if scope_dir.exists() else []
+            size_bytes = sum(f.stat().st_size for f in entry_files)
+
+            latest_updated = None
+            entry_count = 0
+            for entry in (self._load_entry(f, scope) for f in entry_files):
+                if not entry:
+                    continue
+                entry_count += 1
+                try:
+                    updated_time = datetime.fromisoformat(entry.updated_at)
+                except ValueError:
+                    updated_time = datetime.utcfromtimestamp(entry.path.stat().st_mtime)
+                if updated_time.tzinfo is None:
+                    updated_time = updated_time.replace(tzinfo=UTC)
+                if latest_updated is None or updated_time > latest_updated:
+                    latest_updated = updated_time
+
+            stats[scope] = {
+                "entries": entry_count,
+                "size_bytes": size_bytes,
+                "last_updated": latest_updated.isoformat() if latest_updated else None,
+                "path": str(scope_dir),
+            }
+
+        return stats
+
+    def _scope_dir(self, scope: str) -> Path:
+        """Return the directory for a scope (always within knowledge/)."""
+        base = self.project_root if scope == "project" else self.global_root
+        return base / "knowledge"
+
+    def _load_entry(self, file_path: Path, scope: str) -> MemoryEntry | None:
+        """Load entry from file; skip invalid JSON."""
+        if not file_path.exists():
+            return None
+        return MemoryEntry.from_file(file_path, scope)
+
+    def _validate_scope(self, scope: str) -> str:
+        """Ensure scope is recognized."""
+        if scope not in VALID_SCOPES:
+            allowed = ", ".join(sorted(VALID_SCOPES))
+            raise ValueError(f"Invalid scope: {scope}. Use one of: {allowed}")
+        return scope
+
+
+__all__ = ["MemoryEntry", "SimpleMemoryStore"]

uacs/packages/__init__.py

@@ -0,0 +1,26 @@
+"""Minimal local package manager for UACS.
+
+Provides simple package management (install, list, validate, remove) without
+remote discovery features. Inspired by GitHub CLI extensions pattern.
+"""
+
+from uacs.packages.manager import PackageManager
+from uacs.packages.models import InstalledPackage, PackageSource
+from uacs.packages.sources import (
+    GitCloneError,
+    InvalidSourceError,
+    LocalCopyError,
+    PackageSourceError,
+    PackageSourceHandler,
+)
+
+__all__ = [
+    "GitCloneError",
+    "InstalledPackage",
+    "InvalidSourceError",
+    "LocalCopyError",
+    "PackageManager",
+    "PackageSource",
+    "PackageSourceError",
+    "PackageSourceHandler",
+]