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

uacs/cli/context.py

@@ -0,0 +1,349 @@
+"""CLI commands for context management and visualization."""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+from uacs import UACS
+from uacs.visualization import ContextVisualizer
+from uacs.cli.utils import get_project_root
+
+app = typer.Typer(help="Manage shared context and compression")
+console = Console()
+
+
+def get_uacs() -> UACS:
+    """Get UACS instance for current project."""
+    return UACS(get_project_root())
+
+
+@app.command("stats")
+def show_stats():
+    """Show context and token usage statistics."""
+    uacs = get_uacs()
+
+    # Get stats from UACS
+    stats = uacs.get_stats()
+    token_stats = uacs.get_token_stats()
+    context_stats = stats.get("context", {})
+
+    # Render stats
+    console.print("\n[bold cyan]📊 Context Statistics[/bold cyan]\n")
+
+    console.print("[bold]Token Usage:[/bold]")
+    console.print(f"  AGENTS.md:      {token_stats['agents_md_tokens']:>6,} tokens")
+    console.print(f"  Agent Skills:   {token_stats['skills_tokens']:>6,} tokens")
+    console.print(
+        f"  Shared Context: {token_stats['shared_context_tokens']:>6,} tokens"
+    )
+    console.print(
+        f"  [dim]Total:          {token_stats['total_potential_tokens']:>6,} tokens[/dim]"
+    )
+
+    console.print("\n[bold]Compression:[/bold]")
+    console.print(f"  Tokens Saved:   {token_stats['tokens_saved_by_compression']:>6,}")
+    console.print(f"  Compression:    {context_stats['compression_ratio']:>6}")
+    console.print(f"  Storage:        {context_stats['storage_size_mb']:>6.2f} MB")
+
+    console.print("\n[bold]Entries:[/bold]")
+    console.print(f"  Context Entries: {context_stats['entry_count']:>3}")
+    console.print(f"  Summaries:       {context_stats['summary_count']:>3}")
+
+
+@app.command("visualize")
+def visualize_context(
+    update_interval: float = typer.Option(
+        2.0, "--interval", "-i", help="Update interval in seconds"
+    ),
+):
+    """Launch live context visualization dashboard."""
+    uacs = get_uacs()
+    viz = ContextVisualizer(console)
+
+    console.print("[cyan]Starting live dashboard...[/cyan]")
+    console.print("[dim]Press Ctrl+C to exit[/dim]\n")
+
+    try:
+        viz.live_dashboard(uacs.shared_context, update_interval)
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Dashboard closed[/yellow]")
+
+
+@app.command("graph")
+def show_graph():
+    """Show context relationship graph."""
+    uacs = get_uacs()
+    viz = ContextVisualizer(console)
+
+    graph = uacs.shared_context.get_context_graph()
+    console.print(viz.render_context_graph(graph))
+
+
+@app.command("compress")
+def compress_context(
+    force: bool = typer.Option(
+        False, "--force", help="Force compression even if not needed"
+    ),
+):
+    """Manually trigger context compression."""
+    uacs = get_uacs()
+
+    before_stats = uacs.shared_context.get_stats()
+    before_tokens = before_stats["total_tokens"]
+
+    console.print("🗜️  Compressing context...")
+
+    uacs.unified_context.optimize_context()
+
+    after_stats = uacs.shared_context.get_stats()
+    after_tokens = after_stats["total_tokens"]
+
+    viz = ContextVisualizer(console)
+    console.print(
+        viz.render_compression_viz(before_tokens, after_tokens, "auto-summary")
+    )
+
+    console.print("\n[green]✓[/green] Compression complete")
+    console.print(
+        f"  Created {after_stats['summary_count'] - before_stats['summary_count']} new summaries"
+    )
+
+
+@app.command("report")
+def compression_report():
+    """Show detailed compression report."""
+    uacs = get_uacs()
+    report = uacs.unified_context.get_compression_report()
+
+    md = Markdown(report)
+    console.print(Panel(md, title="Compression Report", border_style="cyan"))
+
+
+@app.command("export")
+def export_config(
+    output: Path = typer.Option(
+        Path("unified-context.json"), "--output", "-o", help="Output file path"
+    ),
+):
+    """Export unified context configuration."""
+    uacs = get_uacs()
+
+    uacs.unified_context.export_unified_config(output)
+
+    console.print(f"[green]✓[/green] Exported configuration to {output}")
+
+    # Show summary
+    caps = uacs.unified_context.get_unified_capabilities()
+    console.print(f"\n  Skills: {len(caps['available_skills'])}")
+    console.print(f"  AGENTS.md: {'✓' if caps['agents_md_loaded'] else '✗'}")
+    console.print(f"  Context entries: {caps['shared_context_stats']['entry_count']}")
+
+
+@app.command("snapshot")
+def create_snapshot(name: str = typer.Argument(..., help="Snapshot name")):
+    """Create snapshot of current context state."""
+    uacs = get_uacs()
+
+    snapshot = uacs.unified_context.create_snapshot(name)
+
+    console.print(f"[green]✓[/green] Created snapshot: [cyan]{name}[/cyan]")
+    console.print(f"\n  Timestamp: {snapshot['timestamp']}")
+    console.print(f"  Entries: {snapshot['context_entries']}")
+    console.print(f"  Summaries: {snapshot['summaries']}")
+
+
+@app.command("capabilities")
+def show_capabilities():
+    """Show all unified capabilities."""
+    uacs = get_uacs()
+    caps = uacs.get_capabilities()
+
+    console.print("\n[bold cyan]🎯 Unified Capabilities[/bold cyan]\n")
+
+    # AGENTS.md
+    if caps["agents_md_loaded"]:
+        console.print("[green]✓[/green] AGENTS.md loaded")
+        project_caps = caps["project_context"]
+        if project_caps.get("setup"):
+            console.print(f"  Setup commands: {len(project_caps['setup'])}")
+        if project_caps.get("code_style"):
+            console.print(f"  Style rules: {len(project_caps['code_style'])}")
+    else:
+        console.print("[dim]○ AGENTS.md not found[/dim]")
+
+    # Agent Skills
+    skills = caps["available_skills"]
+    if skills:
+        console.print(f"\n[green]✓[/green] Agent Skills loaded ({len(skills)} skills)")
+        for skill in skills[:5]:
+            console.print(f"  - {skill}")
+        if len(skills) > 5:
+            console.print(f"  [dim]... and {len(skills) - 5} more[/dim]")
+    else:
+        console.print("\n[dim]○ No skills loaded[/dim]")
+
+    # Shared Context
+    console.print("\n[green]✓[/green] Shared Context active")
+    context_stats = caps["shared_context_stats"]
+    console.print(f"  Entries: {context_stats['entry_count']}")
+    console.print(f"  Summaries: {context_stats['summary_count']}")
+    console.print(f"  Compression: {context_stats['compression_ratio']}")
+
+
+@app.command("clear")
+def clear_context(
+    confirm: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+):
+    """Clear all shared context (keeps Agent Skills and AGENTS.md)."""
+    if not confirm:
+        response = typer.confirm("Clear all shared context? This cannot be undone.")
+        if not response:
+            console.print("[yellow]Cancelled[/yellow]")
+            return
+
+    uacs = get_uacs()
+
+    # Clear context
+    uacs.shared_context.entries.clear()
+    uacs.shared_context.summaries.clear()
+    uacs.shared_context.dedup_index.clear()
+
+    # Clear storage
+    for file in uacs.shared_context.storage_path.glob("*"):
+        if file.is_file():
+            file.unlink()
+
+    console.print("[green]✓[/green] Cleared all shared context")
+
+
+@app.command("validate")
+def validate_project(
+    fix: bool = typer.Option(False, "--fix", help="Show fix suggestions"),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show all issues including suggestions"
+    ),
+):
+    """Validate AGENTS.md and agent skills configuration."""
+    # Note: ProjectValidator is not part of UACS core, so this command may need updates
+    # or be removed if the validator doesn't exist in UACS
+    console.print("[yellow]⚠ This command requires ProjectValidator which may not be available in UACS[/yellow]")
+    console.print("Use 'uacs skills validate' to validate individual SKILL.md files")
+
+
+@app.command("build")
+def build_focused_context(
+    query: str = typer.Argument(..., help="Query or task for context building"),
+    agent: str = typer.Option("claude", "--agent", "-a", help="Agent name"),
+    topics: str | None = typer.Option(
+        None, "--topics", "-t", help="Comma-separated topics to filter context"
+    ),
+    max_tokens: int = typer.Option(
+        4000, "--max-tokens", "-m", help="Maximum tokens to return"
+    ),
+):
+    """Build focused context filtered by topics."""
+    uacs = get_uacs()
+
+    # Parse topics if provided
+    topic_list = [t.strip() for t in topics.split(",")] if topics else None
+
+    console.print(f"\n[cyan]🔍 Building context for: {query}[/cyan]")
+    if topic_list:
+        console.print(f"[dim]Topics: {', '.join(topic_list)}[/dim]")
+    console.print()
+
+    # Build context
+    context = uacs.build_context(
+        query=query, agent=agent, max_tokens=max_tokens, topics=topic_list
+    )
+
+    # Display context
+    console.print(Panel(context, title=f"Context for {agent}", border_style="cyan"))
+
+    # Show token count
+    token_count = uacs.shared_context.count_tokens(context)
+    console.print(f"\n[dim]Token count: {token_count:,}[/dim]")
+
+
+@app.command("add")
+def add_context_entry(
+    content: str = typer.Argument(..., help="Content to add to context"),
+    agent: str = typer.Option("user", "--agent", "-a", help="Agent name"),
+    topics: str | None = typer.Option(
+        None, "--topics", "-t", help="Comma-separated topics for this entry"
+    ),
+):
+    """Add an entry to shared context with optional topics."""
+    uacs = get_uacs()
+
+    # Parse topics if provided
+    topic_list = [t.strip() for t in topics.split(",")] if topics else None
+
+    entry_id = uacs.shared_context.add_entry(
+        content=content, agent=agent, topics=topic_list
+    )
+
+    console.print(f"[green]✓[/green] Added context entry: [cyan]{entry_id}[/cyan]")
+    if topic_list:
+        console.print(f"[dim]Topics: {', '.join(topic_list)}[/dim]")
+
+
+@app.command("init")
+def init_agents_md():
+    """Initialize AGENTS.md file with template."""
+    target = get_project_root() / "AGENTS.md"
+
+    if target.exists():
+        console.print(f"[yellow]AGENTS.md already exists: {target}[/yellow]")
+        return
+
+    template = """# AGENTS.md
+
+## Project Overview
+Brief description of your project, its architecture, and key concepts.
+
+## Setup Commands
+- Install dependencies: `npm install` or `pip install -r requirements.txt`
+- Start dev server: `npm run dev` or `python app.py`
+
+## Dev Environment Tips
+- Use environment variables from .env.example
+- Database migrations: `npm run migrate`
+- Check logs: `tail -f logs/app.log`
+
+## Code Style
+- TypeScript strict mode enabled
+- Use single quotes for strings
+- 2-space indentation
+- No semicolons
+- Prefer functional patterns
+
+## Build Commands
+- Build: `npm run build`
+- Test: `npm test`
+- Lint: `npm run lint`
+
+## Testing Instructions
+- Run unit tests: `npm test`
+- Run integration tests: `npm run test:integration`
+- Coverage report: `npm run test:coverage`
+- All tests must pass before merging
+
+## PR Instructions
+- Title format: `[Component] Brief description`
+- Link related issues
+- Update tests for changed code
+- Run `npm run lint` before committing
+- Request review from @team
+"""
+
+    target.write_text(template)
+    console.print(f"[green]✓[/green] Created AGENTS.md at {target}")
+    console.print("\nEdit this file to customize for your project.")
+
+
+if __name__ == "__main__":
+    app()

uacs/cli/main.py

@@ -0,0 +1,195 @@
+"""UACS CLI - Universal Agent Context System command-line interface."""
+
+import asyncio
+from pathlib import Path
+
+import typer
+
+from uacs.cli import context, memory, mcp, packages, skills
+
+app = typer.Typer(
+    name="uacs",
+    help="Universal Agent Context System - unified context for AI agents",
+    no_args_is_help=True,
+)
+
+# Register sub-apps
+app.add_typer(skills.app, name="skills")
+app.add_typer(context.app, name="context")
+app.add_typer(packages.app, name="packages")
+app.add_typer(memory.app, name="memory")
+app.add_typer(mcp.app, name="mcp")
+
+
+@app.command()
+def serve(
+    host: str = typer.Option("localhost", "--host", "-h", help="Server host"),
+    port: int = typer.Option(8080, "--port", "-p", help="Server port"),
+    with_ui: bool = typer.Option(False, "--with-ui", help="Start web UI visualization server"),
+    ui_port: int = typer.Option(8081, "--ui-port", help="Web UI port"),
+):
+    """Start UACS MCP server for tool integration.
+
+    The MCP server exposes all UACS capabilities as tools that can be
+    consumed by AI agents via the Model Context Protocol.
+
+    Use --with-ui to also start the web-based context visualization UI.
+
+    Examples:
+        uacs serve --host 0.0.0.0 --port 8080
+        uacs serve --with-ui --ui-port 8081
+    """
+    from uacs.protocols.mcp.skills_server import main as mcp_main
+
+    console = typer.get_text_stream("stdout")
+    typer.echo(f"Starting UACS MCP server on {host}:{port}...")
+    typer.echo("Exposing skills, context, and package management tools")
+
+    if with_ui:
+        typer.echo(f"Web UI will be available at http://{host}:{ui_port}")
+        typer.echo("Starting visualization server...")
+        _run_with_ui(host, port, ui_port)
+    else:
+        typer.echo("Press Ctrl+C to stop\n")
+        try:
+            asyncio.run(mcp_main())
+        except KeyboardInterrupt:
+            typer.echo("\n\nServer stopped")
+
+
+def _run_with_ui(host: str, port: int, ui_port: int):
+    """Run MCP server with web UI visualization.
+
+    Args:
+        host: Server host
+        port: MCP server port
+        ui_port: Web UI port
+    """
+    import uvicorn
+    from pathlib import Path
+    from uacs.context.shared_context import SharedContextManager
+    from uacs.visualization.web_server import VisualizationServer
+
+    # Initialize shared context manager
+    storage_path = Path.cwd() / ".state" / "context"
+    context_manager = SharedContextManager(storage_path=storage_path)
+
+    # Create visualization server
+    viz_server = VisualizationServer(context_manager, host, ui_port)
+
+    # Print startup message
+    typer.echo(f"\n✓ Web UI available at http://{host}:{ui_port}")
+    typer.echo("✓ MCP server running (stdio mode)")
+    typer.echo("Press Ctrl+C to stop\n")
+
+    # Run visualization server (MCP server runs in stdio mode alongside)
+    config = uvicorn.Config(
+        viz_server.app,
+        host=host,
+        port=ui_port,
+        log_level="info",
+    )
+    server = uvicorn.Server(config)
+
+    try:
+        asyncio.run(server.serve())
+    except KeyboardInterrupt:
+        typer.echo("\n\nServers stopped")
+
+
+@app.command()
+def version():
+    """Show UACS version information."""
+    try:
+        from importlib.metadata import version as get_version
+
+        uacs_version = get_version("universal-agent-context")
+        typer.echo(f"UACS version: {uacs_version}")
+    except Exception:
+        typer.echo("UACS version: development")
+
+
+@app.command()
+def init(
+    project_root: Path = typer.Argument(
+        Path.cwd(), help="Project root directory (default: current directory)"
+    ),
+):
+    """Initialize UACS for a project.
+
+    Creates necessary directories and example configuration files.
+    """
+    from rich.console import Console
+
+    console = Console()
+
+    # Create .agent directory structure
+    agent_dir = project_root / ".agent"
+    skills_dir = agent_dir / "skills"
+    state_dir = project_root / ".state"
+    context_dir = state_dir / "context"
+
+    dirs_to_create = [agent_dir, skills_dir, state_dir, context_dir]
+
+    for directory in dirs_to_create:
+        if not directory.exists():
+            directory.mkdir(parents=True, exist_ok=True)
+            console.print(f"[green]✓[/green] Created {directory}")
+        else:
+            console.print(f"[dim]○[/dim] Already exists: {directory}")
+
+    # Create example Agent Skill if .agent/skills/ is empty
+    skills_dir = project_root / ".agent" / "skills"
+    example_skill_dir = skills_dir / "example-skill"
+    if skills_dir.exists() and not any(skills_dir.iterdir()):
+        # Directory exists but is empty - create example
+        example_skill_dir.mkdir(parents=True, exist_ok=True)
+        example_skill = """---
+name: example-skill
+description: Example skill demonstrating the Agent Skills format
+---
+
+# Example Skill
+
+This is an example skill showing the Agent Skills format structure.
+
+## When to Use
+
+Use this skill when you need to demonstrate:
+- How to structure a skill with YAML frontmatter
+- How to organize instructions
+- How to trigger skill usage
+
+## Instructions
+
+1. **Understand the format**: Skills use YAML frontmatter + Markdown body
+2. **Define clear triggers**: Describe when this skill should be used
+3. **Provide actionable steps**: Break down the skill into clear instructions
+4. **Include examples**: Show concrete usage examples when relevant
+
+## Examples
+
+When a user asks "Show me how skills work", you can:
+1. Reference this example skill
+2. Explain the YAML frontmatter structure
+3. Show the markdown instruction format
+"""
+        skill_file = example_skill_dir / "SKILL.md"
+        skill_file.write_text(example_skill)
+        console.print(
+            f"[green]✓[/green] Created example skill {example_skill_dir.name}"
+        )
+
+    console.print("\n[bold cyan]UACS initialized successfully![/bold cyan]")
+    console.print("\nNext steps:")
+    console.print("  1. Run 'uacs skills list' to see available skills")
+    console.print("  2. Run 'uacs install owner/repo' to install packages from GitHub")
+    console.print("  3. Run 'uacs list' to see installed packages")
+    console.print("  4. Run 'uacs serve' to start the MCP server")
+
+
+__all__ = ["app"]
+
+
+if __name__ == "__main__":
+    app()

uacs/cli/mcp.py

@@ -0,0 +1,115 @@
+"""CLI commands for MCP server management."""
+
+import json
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from uacs.protocols.mcp.manager import McpManager
+
+app = typer.Typer(help="Manage MCP servers")
+console = Console()
+
+
+@app.command("list")
+def list_servers():
+    """List all MCP servers in use in this project, regardless of installation source."""
+    manager = McpManager()
+    servers = manager.list_servers()
+
+    if not servers:
+        console.print("[yellow]No MCP servers configured.[/yellow]")
+        console.print("\nConfigure MCP servers in: ~/.uacs/mcp-config.json")
+        return
+
+    table = Table(title="MCP Servers in Use")
+    table.add_column("Name", style="cyan", width=20)
+    table.add_column("Command", style="green", width=40)
+    table.add_column("Args", style="white", width=30)
+    table.add_column("Status", style="magenta", width=10)
+
+    # Add configured servers
+    for server in servers:
+        status = "Enabled" if server.enabled else "Disabled"
+        args_str = " ".join(server.args[:2])
+        if len(server.args) > 2:
+            args_str += "..."
+
+        table.add_row(server.name, server.command, args_str, status)
+
+    console.print(table)
+    console.print(f"\n[dim]Total: {len(servers)} MCP server(s) configured[/dim]")
+
+
+@app.command("add")
+def add_server(
+    name: str = typer.Argument(..., help="Name of the MCP server"),
+    command: str = typer.Argument(..., help="Executable command"),
+    args: list[str] = typer.Argument(None, help="Arguments for the command"),
+    env: str = typer.Option(None, help="Environment variables as JSON string"),
+):
+    """Add a new MCP server."""
+    manager = McpManager()
+
+    env_dict = {}
+    if env:
+        try:
+            env_dict = json.loads(env)
+        except json.JSONDecodeError:
+            console.print("[red]Error: Invalid JSON for environment variables[/red]")
+            raise typer.Exit(1)
+
+    manager.add_server(name, command, args or [], env_dict)
+    console.print(f"[green]Added MCP server: {name}[/green]")
+
+
+@app.command("remove")
+def remove_server(name: str = typer.Argument(..., help="Name of the MCP server")):
+    """Remove an MCP server."""
+    manager = McpManager()
+    if manager.get_server(name):
+        manager.remove_server(name)
+        console.print(f"[green]Removed MCP server: {name}[/green]")
+    else:
+        console.print(f"[red]Server {name} not found[/red]")
+
+
+@app.command("install-filesystem")
+def install_filesystem(
+    path: str = typer.Argument(..., help="Root path for filesystem access"),
+):
+    """Helper to add the standard filesystem MCP server."""
+    manager = McpManager()
+    import shutil
+
+    # Detect available runner
+    command = None
+    args = []
+
+    if shutil.which("pnpm"):
+        command = "pnpm"
+        args = ["dlx", "@modelcontextprotocol/server-filesystem", path]
+    elif shutil.which("bun"):
+        command = "bun"
+        args = ["x", "@modelcontextprotocol/server-filesystem", path]
+    elif shutil.which("npx"):
+        command = "npx"
+        args = ["-y", "@modelcontextprotocol/server-filesystem", path]
+    else:
+        console.print(
+            "[red]Error: No suitable runner found (pnpm, bun, or npx required).[/red]"
+        )
+        raise typer.Exit(1)
+
+    manager.add_server(name="filesystem", command=command, args=args)
+    console.print(
+        f"[green]Added filesystem MCP server using {command} for path: {path}[/green]"
+    )
+
+
+__all__ = ["app"]
+
+
+if __name__ == "__main__":
+    app()