agent-catalog-new 0.2.0__py3-none-any.whl

agent_catalog/__init__.py

@@ -0,0 +1,33 @@
+"""Agent Catalog — Declarative agent registry.
+
+Discover, diff, and manage agent capabilities across environments.
+
+Decorator API (new in 0.2.0):
+
+    from agent_catalog import agent, capability, tool, interface, dependency
+    from agent_catalog.decorators import build_manifest
+"""
+
+from __future__ import annotations
+
+from agent_catalog.decorators import (
+    agent,
+    build_manifest,
+    capability,
+    dependency,
+    interface,
+    prompt_ref,
+    tool,
+)
+
+__all__ = [
+    "agent",
+    "build_manifest",
+    "capability",
+    "dependency",
+    "interface",
+    "prompt_ref",
+    "tool",
+]
+
+__version__ = "0.2.0"

agent_catalog/cli/__init__.py

@@ -0,0 +1,108 @@
+"""Agent Catalog CLI — declarative agent registry.
+
+Usage:
+    agent-catalog register ./agent.yaml
+    agent-catalog list
+    agent-catalog get agentic-inbox
+    agent-catalog search --capability send_email
+    agent-catalog diff agentic-inbox --right staging
+"""
+
+from __future__ import annotations
+
+import os
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from agent_catalog import __version__
+from agent_catalog.storage import CatalogStore
+
+# ── App ────────────────────────────────────────────────────────────────────────
+
+app = typer.Typer(
+    name="agent-catalog",
+    help="Declarative agent registry — catalog, discover, and diff agent capabilities.",
+    no_args_is_help=True,
+)
+
+# Typer adds --install-completion and --show-completion automatically.
+
+console = Console()
+
+
+# ── Version flag ────────────────────────────────────────────────────────────────
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"agent-catalog {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main_options(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Agent Catalog — declarative agent registry."""
+
+
+# ── Shared helpers ─────────────────────────────────────────────────────────────
+
+
+def _get_store() -> CatalogStore:
+    """Resolve the catalog store, respecting AGENT_CATALOG_DIR env var."""
+    root = os.environ.get("AGENT_CATALOG_DIR")
+    return CatalogStore(root=root) if root else CatalogStore()
+
+
+def _render_manifest(m) -> Panel:
+    """Pretty-print an agent manifest as a Rich Panel."""
+    rows: list[str] = []
+    rows.append(f"[bold]Name:[/]         {m.name}")
+    rows.append(f"[bold]Slug:[/]         {m.slug}")
+    rows.append(f"[bold]Version:[/]      {m.version}")
+    rows.append(f"[bold]Environment:[/]  {m.environment}")
+    rows.append(f"[bold]Status:[/]       {m.status}")
+    rows.append(f"[bold]Description:[/]  {m.description}")
+    if m.model:
+        rows.append(f"[bold]Model:[/]        {m.model.provider}/{m.model.name}")
+    if m.capabilities:
+        rows.append(f"[bold]Capabilities:[/] {', '.join(c.id for c in m.capabilities)}")
+    if m.tools:
+        rows.append(f"[bold]Tools:[/]        {', '.join(t.name for t in m.tools)}")
+    if m.prompt:
+        versions = ", ".join(p.version for p in m.prompt)
+        rows.append(f"[bold]Prompts:[/]      {versions}")
+    if m.dependencies:
+        deps = ", ".join(d.name for d in m.dependencies)
+        rows.append(f"[bold]Dependencies:[/] {deps}")
+    if m.eval_contract:
+        suites = ", ".join(m.eval_contract.suites)
+        rows.append(f"[bold]Eval Suites:[/]  {suites}")
+    text = "\n".join(rows)
+    return Panel(Text.from_markup(text), title=m.environment_tag())
+
+
+# ── Entry point ────────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    """Entry point for the 'agent-catalog' command."""
+    app()
+
+
+if __name__ == "__main__":
+    main()
+
+# ── Register subcommand modules ────────────────────────────────────────────────
+
+from . import aux_commands, crud, diff_commands, discover_commands  # noqa: E402,F401

agent_catalog/cli/__main__.py

@@ -0,0 +1,3 @@
+from agent_catalog.cli import app
+
+app()

agent_catalog/cli/aux_commands.py

@@ -0,0 +1,139 @@
+"""Auxiliary commands: security-audit, graph, serve, run, doctor."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from agent_catalog.cli import _get_store, app, console
+
+
+@app.command()
+def security_audit(
+    output_format: str = typer.Option("table", "--format", "-f", help="Output: table, json"),
+):
+    """Audit all registered agents for security gaps."""
+    from agent_catalog.security import audit_catalog
+
+    findings = audit_catalog(_get_store())
+    if not findings:
+        console.print("[green]No security issues found[/]")
+        return
+
+    if output_format == "json":
+        console.print(
+            json.dumps(
+                [
+                    {"severity": f.severity, "agent": f.agent, "title": f.title, "detail": f.detail}
+                    for f in findings
+                ],
+                indent=2,
+            )
+        )
+        return
+
+    from rich.table import Table
+
+    table = Table(title="Security Audit")
+    table.add_column("Severity", style="bold")
+    table.add_column("Agent")
+    table.add_column("Issue")
+    table.add_column("Detail", style="dim")
+
+    for f in findings:
+        color = {"critical": "red", "high": "yellow", "medium": "dim", "low": "dim"}[f.severity]
+        table.add_row(f"[{color}]{f.severity}[/]", f.agent, f.title, f.detail)
+
+    console.print(table)
+    crit = sum(1 for f in findings if f.severity == "critical")
+    high = sum(1 for f in findings if f.severity == "high")
+    console.print(f"[bold]Summary:[/] {len(findings)} findings ({crit} critical, {high} high)")
+
+
+@app.command()
+def graph(
+    output_format: str = typer.Option("mermaid", "--format", "-f", help="Output: mermaid, json"),
+):
+    """Show agent dependency graph."""
+    from agent_catalog.graph import build_graph, to_mermaid
+
+    store = _get_store()
+    if output_format == "json":
+        console.print_json(json.dumps(build_graph(store), default=str))
+    else:
+        console.print(to_mermaid(store))
+
+
+@app.command()
+def serve(
+    port: int = typer.Option(8420, "--port", "-p", help="HTTP port"),
+    mcp: bool = typer.Option(False, "--mcp", help="Run MCP server instead of HTTP (stdio transport)"),
+):
+    """Start the Agent Marketplace web dashboard.
+
+    By default starts an HTTP server.  Pass --mcp to run as an MCP
+    server over stdio (for use with MCP clients like Claude Code).
+    """
+    if mcp:
+        from agent_catalog.mcp_server import run_server
+
+        run_server(store=_get_store())
+    else:
+        from agent_catalog.serve import serve as run_serve
+
+        run_serve(port=port, store=_get_store())
+
+
+@app.command()
+def run(
+    slug: str = typer.Argument(..., help="Agent slug"),
+    capability: str = typer.Argument(..., help="Capability ID to invoke"),
+    params: str | None = typer.Option(None, "--params", "-p", help="JSON string of parameters"),
+):
+    """Load an agent and invoke a capability at runtime.
+
+    Uses metadata.python_module / metadata.python_class to find and
+    import the agent class, then calls the capability method.
+
+    Examples:
+        agent-catalog run my-agent greet
+        agent-catalog run my-agent greet --params '{"name": "World"}'
+    """
+    from agent_catalog.loader import invoke_capability
+
+    kwargs: dict = {}
+    if params:
+        try:
+            kwargs = json.loads(params)
+        except json.JSONDecodeError as e:
+            console.print(f"[red]\u2717[/] Invalid JSON in --params: {e}")
+            raise typer.Exit(1) from e
+
+    try:
+        result = invoke_capability(slug, capability, store=_get_store(), **kwargs)
+        console.print(result)
+    except Exception as e:
+        console.print(f"[red]\u2717[/] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def doctor():
+    """Check catalog consistency (orphaned files, missing manifests).
+
+    Scans the catalog directory and verifies every indexed agent
+    has a manifest file on disk, and every YAML file is indexed.
+    """
+    store = _get_store()
+    issues = store.check_consistency()
+
+    if not issues:
+        console.print("[green]\u2713[/] Catalog is consistent")
+        return
+
+    console.print(f"[yellow]Found {len(issues)} issue(s):[/]")
+    for issue in issues:
+        prefix = "[red]MISSING[/]" if issue.startswith("MISSING") else "[yellow]ORPHAN[/]"
+        console.print(f"  {prefix} {issue}")
+    raise typer.Exit(1)

agent_catalog/cli/crud.py

@@ -0,0 +1,192 @@
+"""CRUD commands: register, list, get, search, validate, unregister, update."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+import yaml
+from rich.table import Table
+
+from agent_catalog.cli import _get_store, _render_manifest, app, console
+from agent_catalog.schema import AgentManifest
+
+
+@app.command()
+def register(
+    manifest: str = typer.Argument(..., help="Path to agent manifest YAML file"),
+):
+    """Register an agent from a manifest file."""
+    try:
+        agent = _get_store().register(Path(manifest))
+        console.print(f"[green]\u2713[/] Registered [bold]{agent.slug}[/] @ {agent.environment}")
+        console.print(_render_manifest(agent))
+    except Exception as e:
+        console.print(f"[red]\u2717[/] Failed to register: {e}")
+        raise typer.Exit(code=1) from e
+
+
+@app.command()
+def list(
+    environment: str | None = typer.Option(None, "--env", "-e", help="Filter by environment"),
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table, json"),
+):
+    """List all registered agents."""
+    import json as _json
+
+    agents = _get_store().list_all()
+    if environment:
+        agents = [a for a in agents if a.environment == environment]
+
+    if not agents:
+        if output == "json":
+            console.print(_json.dumps({"agents": []}))
+        else:
+            console.print("[yellow]No agents registered.[/]")
+        return
+
+    if output == "json":
+        data = [
+            {
+                "slug": a.slug,
+                "name": a.name,
+                "version": a.version,
+                "environment": a.environment,
+                "status": a.status,
+                "capabilities": [c.id for c in a.capabilities],
+            }
+            for a in sorted(agents, key=lambda x: x.slug)
+        ]
+        console.print(_json.dumps({"agents": data}, indent=2))
+        return
+
+    table = Table(title="Agent Catalog")
+    table.add_column("Slug", style="cyan")
+    table.add_column("Name", style="bold")
+    table.add_column("Version")
+    table.add_column("Environment")
+    table.add_column("Capabilities")
+    table.add_column("Status")
+
+    for a in sorted(agents, key=lambda x: x.slug):
+        table.add_row(
+            a.slug,
+            a.name,
+            a.version,
+            a.environment,
+            ", ".join(c.id for c in a.capabilities[:3])
+            + ("..." if len(a.capabilities) > 3 else ""),
+            a.status,
+        )
+
+    console.print(table)
+    console.print(f"[dim]{len(agents)} agent(s)[/]")
+
+
+@app.command()
+def get(
+    slug: str = typer.Argument(..., help="Agent slug to retrieve"),
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table, json"),
+):
+    """Show full details for an agent."""
+    import json as _json
+
+    try:
+        agent = _get_store().get(slug)
+        if output == "json":
+            console.print(_json.dumps(agent.model_dump(mode="json", exclude_none=True), indent=2))
+        else:
+            console.print(_render_manifest(agent))
+    except (KeyError, FileNotFoundError) as e:
+        console.print(f"[red]\u2717[/] {e}")
+        raise typer.Exit(code=1) from e
+
+
+@app.command()
+def search(
+    capability: str | None = typer.Option(
+        None, "--capability", "-c", help="Search by capability ID"
+    ),
+    tool: str | None = typer.Option(None, "--tool", "-t", help="Search by tool name"),
+    surface: str | None = typer.Option(None, "--surface", "-s", help="Search by interface surface"),
+    environment: str | None = typer.Option(None, "--env", "-e", help="Filter by environment"),
+):
+    """Search agents by capability, tool, surface, or environment."""
+    results = _get_store().search(
+        capability=capability,
+        tool=tool,
+        surface=surface,
+        environment=environment,
+    )
+
+    if not results:
+        console.print("[yellow]No matching agents.[/]")
+        return
+
+    table = Table(title=f"Search Results ({len(results)})")
+    table.add_column("Slug", style="cyan")
+    table.add_column("Name")
+    table.add_column("Environment")
+    table.add_column("Capabilities")
+    table.add_column("Tools")
+    table.add_column("Surfaces")
+
+    for a in sorted(results, key=lambda x: x.slug):
+        table.add_row(
+            a.slug,
+            a.name,
+            a.environment,
+            ", ".join(c.id for c in a.capabilities),
+            ", ".join(t.name for t in a.tools),
+            ", ".join(s.type.value for s in a.interfaces),
+        )
+
+    console.print(table)
+
+
+@app.command()
+def validate(
+    manifest: str = typer.Argument(..., help="Path to manifest YAML to validate"),
+):
+    """Validate a manifest file without registering it."""
+    try:
+        raw = yaml.safe_load(Path(manifest).read_text())
+        if raw is None:
+            console.print("[red]\u2717[/] Empty or invalid YAML.")
+            raise typer.Exit(1)
+        m = AgentManifest.model_validate(raw)
+        console.print(f"[green]\u2713[/] Valid: [bold]{m.slug}[/] ({m.name})")
+    except Exception as e:
+        console.print(f"[red]\u2717[/] Validation failed: {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def unregister(
+    slug: str = typer.Argument(..., help="Agent slug to remove"),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation"),
+):
+    """Remove an agent from the catalog."""
+    if not force:
+        typer.confirm(f"Remove '{slug}' from the catalog?", abort=True)
+    if _get_store().unregister(slug):
+        console.print(f"[green]\u2713[/] Unregistered [bold]{slug}[/]")
+    else:
+        console.print(f"[yellow]Agent '{slug}' not found.[/]")
+
+
+@app.command()
+def update(
+    slug: str = typer.Argument(..., help="Agent slug to update"),
+    manifest: str = typer.Argument(..., help="Path to updated manifest YAML"),
+):
+    """Update an existing agent's manifest."""
+    try:
+        raw = yaml.safe_load(Path(manifest).read_text())
+        updated = AgentManifest.model_validate(raw)
+        result = _get_store().update(slug, updated)
+        console.print(f"[green]\u2713[/] Updated [bold]{result.slug}[/]")
+        console.print(_render_manifest(result))
+    except Exception as e:
+        console.print(f"[red]\u2717[/] Update failed: {e}")
+        raise typer.Exit(1) from e

agent_catalog/cli/diff_commands.py

@@ -0,0 +1,165 @@
+"""Diff commands: diff, export_contract."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+import yaml
+
+from agent_catalog.cli import _get_store, app, console
+from agent_catalog.diff import diff_manifests
+from agent_catalog.schema import AgentManifest
+
+
+@app.command()
+def diff(
+    slug: str = typer.Argument(..., help="Slug of the primary agent"),
+    right: str | None = typer.Option(
+        None,
+        "--right",
+        "-r",
+        help="Path to another manifest YAML to diff against",
+    ),
+    left_env: str | None = typer.Option(
+        None,
+        "--left-env",
+        help="Environment for the left side (from metadata.environments snapshots)",
+    ),
+    right_env: str | None = typer.Option(
+        None,
+        "--right-env",
+        help="Environment for the right side. Use with a second slug via --slug2 for cross-agent env diff",
+    ),
+    slug2: str | None = typer.Option(
+        None,
+        "--slug2",
+        help="Second agent slug to diff against (for cross-agent comparison)",
+    ),
+):
+    """Show structured diff between two manifests, environments, or agents.
+
+    Modes:
+      agent-catalog diff agentic-inbox --right-env staging
+        Compare agentic-inbox's production manifest against its staging snapshot
+
+      agent-catalog diff agentic-inbox --left-env staging --right-env production
+        Compare staging and production snapshots from metadata.environments
+
+      agent-catalog diff agentic-inbox --slug2 nexusgate
+        Cross-agent comparison: agentic-inbox vs nexusgate
+
+      agent-catalog diff agentic-inbox --right ./external.yaml
+        Compare registered agent against an external manifest file
+    """
+    try:
+        left = _get_store().get(slug)
+    except KeyError:
+        console.print(f"[red]\u2717[/] Agent '{slug}' not registered.")
+        raise typer.Exit(1) from None
+
+    # Resolve left manifest (with optional env overlay)
+    left_manifest = left
+    if left_env:
+        envs = left.metadata.get("environments", {})
+        if left_env not in envs:
+            console.print(f"[red]\u2717[/] No '{left_env}' snapshot in {slug} metadata.")
+            raise typer.Exit(1)
+        left_data = envs[left_env]
+        left_manifest = left.model_copy(update=left_data)
+        left_manifest.environment = left_env
+
+    # Resolve right manifest
+    if right:
+        # External file
+        right_manifest = AgentManifest.model_validate(
+            yaml.safe_load(Path(right).read_text())
+        )
+        right_manifest.environment = right_manifest.environment or "external"
+    elif slug2:
+        # Cross-agent comparison
+        try:
+            right_manifest = _get_store().get(slug2)
+        except KeyError:
+            console.print(f"[red]\u2717[/] Agent '{slug2}' not registered.")
+            raise typer.Exit(1) from None
+        if right_env:
+            envs = right_manifest.metadata.get("environments", {})
+            if right_env not in envs:
+                console.print(f"[red]\u2717[/] No '{right_env}' snapshot in {slug2} metadata.")
+                raise typer.Exit(1)
+            right_data = envs[right_env]
+            right_manifest = right_manifest.model_copy(update=right_data)
+            right_manifest.environment = right_env
+    elif right_env:
+        # Same agent, env snapshot from metadata
+        envs = left.metadata.get("environments", {})
+        if right_env not in envs:
+            console.print(f"[red]\u2717[/] No '{right_env}' snapshot in {slug} metadata.")
+            raise typer.Exit(1)
+        right_data = envs[right_env]
+        right_manifest = left.model_copy(update=right_data)
+        right_manifest.environment = right_env
+    else:
+        # Auto-find: try staging environment, then fall back to any second registered agent
+        second = _get_store().search(environment="staging")
+        if second:
+            right_manifest = second[0]
+        else:
+            all_agents = _get_store().list_all()
+            others = [a for a in all_agents if a.slug != slug]
+            if others:
+                right_manifest = others[0]
+                console.print(
+                    f"[dim]Comparing against '{right_manifest.slug}' (no staging found)[/]"
+                )
+            else:
+                console.print(
+                    "[yellow]No second manifest to diff against. "
+                    "Try --right, --slug2, or --right-env.[/]"
+                )
+                raise typer.Exit(0)
+
+    report = diff_manifests(left_manifest, right_manifest)
+    console.print(report.summary)
+
+
+@app.command()
+def export_contract(
+    slug: str = typer.Argument(..., help="Agent slug to export contract for"),
+    output: str | None = typer.Option(
+        None, "--output", "-o", help="Output file path (default: stdout)"
+    ),
+):
+    """Export a manifest's eval contract as eval-harness compatible YAML."""
+    try:
+        agent = _get_store().get(slug)
+    except KeyError:
+        console.print(f"[red]\u2717[/] Agent '{slug}' not registered.")
+        raise typer.Exit(1) from None
+
+    ec = agent.eval_contract
+    if not ec or not ec.suites:
+        console.print(f"[yellow]No eval contract defined for '{slug}'.[/]")
+        raise typer.Exit(1)
+
+    contract_yaml = {
+        "project": ec.project or agent.slug,
+        "coverage_required": ec.coverage_required,
+        "suites": ec.suites,
+        "agent": {
+            "slug": agent.slug,
+            "version": agent.version,
+            "environment": agent.environment,
+            "capabilities": [c.id for c in agent.capabilities],
+            "model": f"{agent.model.provider}/{agent.model.name}" if agent.model else None,
+        },
+    }
+
+    yaml_text = yaml.dump(contract_yaml, sort_keys=False, default_flow_style=False)
+
+    if output:
+        Path(output).write_text(yaml_text)
+        console.print(f"[green]\u2713[/] Contract exported to [bold]{output}[/]")
+    else:
+        console.print(yaml_text)