@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/cli/benchmark.py

@@ -0,0 +1,360 @@
+"""Benchmark LLM response time across all available backends.
+
+Sends a configurable prompt to each detected backend, measures wall-clock
+latency, and renders a Rich table (or JSON) with results.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Optional
+
+import click
+from rich.table import Table
+
+from ._common import AGENT_HOME, console
+
+# Ordered list of all known backends (matches consciousness_loop.py fallback_chain)
+BACKENDS: list[str] = ["ollama", "grok", "kimi", "nvidia", "anthropic", "openai", "passthrough"]
+
+
+# ---------------------------------------------------------------------------
+# BenchmarkRunner
+# ---------------------------------------------------------------------------
+
+
+class BenchmarkRunner:
+    """Run latency benchmarks against LLM backends.
+
+    Each backend is called with a simple prompt and the round-trip wall-clock
+    time is recorded.  Cloud backends (anthropic, openai, grok, kimi, nvidia)
+    require both an API key *and* the respective SDK to be installed.
+
+    Args:
+        prompt: The prompt string to send to every backend.
+        timeout: Per-backend HTTP/API timeout in seconds.
+    """
+
+    def __init__(self, prompt: str = "Hello", timeout: float = 30.0) -> None:
+        self.prompt = prompt
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Detection
+    # ------------------------------------------------------------------
+
+    def detect_backends(self) -> dict[str, bool]:
+        """Return a mapping of backend name → availability.
+
+        Ollama is probed via HTTP; cloud providers are available when the
+        corresponding API key env-var is set; passthrough is always True.
+        """
+        return {
+            "ollama": self._probe_ollama(),
+            "grok": bool(os.environ.get("XAI_API_KEY")),
+            "kimi": bool(os.environ.get("MOONSHOT_API_KEY")),
+            "nvidia": bool(os.environ.get("NVIDIA_API_KEY")),
+            "anthropic": bool(os.environ.get("ANTHROPIC_API_KEY")),
+            "openai": bool(os.environ.get("OPENAI_API_KEY")),
+            "passthrough": True,
+        }
+
+    def _probe_ollama(self) -> bool:
+        """Return True if the Ollama API is reachable."""
+        import urllib.request
+
+        host = os.environ.get("OLLAMA_HOST", "http://localhost:11434")
+        try:
+            with urllib.request.urlopen(f"{host}/api/tags", timeout=2):
+                return True
+        except Exception:
+            return False
+
+    # ------------------------------------------------------------------
+    # Runner
+    # ------------------------------------------------------------------
+
+    def run_all(self, skip_unavailable: bool = True) -> list[dict]:
+        """Benchmark all backends and return a list of result dicts.
+
+        Result dict keys: ``backend``, ``status``, ``ms``, ``model``, ``error``.
+
+        Args:
+            skip_unavailable: When True, unavailable backends are included in
+                the result list with ``status="unavailable"`` but are not
+                actually called.
+        """
+        available = self.detect_backends()
+        results: list[dict] = []
+        for name in BACKENDS:
+            if not available.get(name, False):
+                results.append(
+                    {"backend": name, "status": "unavailable", "ms": None, "model": None, "error": None}
+                )
+                continue
+            results.append(self.run_backend(name))
+        return results
+
+    def run_backend(self, name: str) -> dict:
+        """Benchmark a single backend by name.
+
+        Returns a result dict with keys: ``backend``, ``status``, ``ms``,
+        ``model``, ``error``.
+        """
+        method = getattr(self, f"_bench_{name}", None)
+        if method is None:
+            return {
+                "backend": name,
+                "status": "unsupported",
+                "ms": None,
+                "model": None,
+                "error": f"No benchmark method for backend '{name}'",
+            }
+        try:
+            return method()
+        except Exception as exc:
+            return {
+                "backend": name,
+                "status": "error",
+                "ms": None,
+                "model": None,
+                "error": str(exc)[:120],
+            }
+
+    # ------------------------------------------------------------------
+    # Per-backend implementations
+    # ------------------------------------------------------------------
+
+    def _bench_passthrough(self) -> dict:
+        """Passthrough — instant in-process mock (always succeeds)."""
+        t0 = time.perf_counter()
+        _ = f"[passthrough] {self.prompt}"
+        ms = round((time.perf_counter() - t0) * 1000, 3)
+        return {"backend": "passthrough", "status": "ok", "ms": ms, "model": "mock", "error": None}
+
+    def _bench_ollama(self) -> dict:
+        """Ollama — local HTTP POST to /api/generate."""
+        import urllib.request
+
+        host = os.environ.get("OLLAMA_HOST", "http://localhost:11434")
+        model = os.environ.get("OLLAMA_MODEL", "llama3.2")
+        payload = json.dumps(
+            {"model": model, "prompt": self.prompt, "stream": False}
+        ).encode()
+        req = urllib.request.Request(
+            f"{host}/api/generate",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+        )
+        t0 = time.perf_counter()
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            data = json.loads(resp.read())
+        ms = round((time.perf_counter() - t0) * 1000, 1)
+        return {
+            "backend": "ollama",
+            "status": "ok",
+            "ms": ms,
+            "model": data.get("model", model),
+            "error": None,
+        }
+
+    def _bench_anthropic(self) -> dict:
+        """Anthropic Claude — requires ``anthropic`` SDK + ANTHROPIC_API_KEY."""
+        try:
+            import anthropic as _anthropic
+        except ImportError:
+            raise RuntimeError("anthropic SDK not installed — run: pip install anthropic")
+
+        model = "claude-haiku-4-5-20251001"
+        client = _anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+        t0 = time.perf_counter()
+        client.messages.create(
+            model=model,
+            max_tokens=64,
+            messages=[{"role": "user", "content": self.prompt}],
+        )
+        ms = round((time.perf_counter() - t0) * 1000, 1)
+        return {"backend": "anthropic", "status": "ok", "ms": ms, "model": model, "error": None}
+
+    def _bench_openai(self) -> dict:
+        """OpenAI — requires ``openai`` SDK + OPENAI_API_KEY."""
+        try:
+            import openai as _openai
+        except ImportError:
+            raise RuntimeError("openai SDK not installed — run: pip install openai")
+
+        model = "gpt-3.5-turbo"
+        client = _openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"])
+        t0 = time.perf_counter()
+        client.chat.completions.create(
+            model=model,
+            max_tokens=64,
+            messages=[{"role": "user", "content": self.prompt}],
+        )
+        ms = round((time.perf_counter() - t0) * 1000, 1)
+        return {"backend": "openai", "status": "ok", "ms": ms, "model": model, "error": None}
+
+    def _bench_grok(self) -> dict:
+        """xAI Grok — OpenAI-compatible API, requires ``openai`` SDK + XAI_API_KEY."""
+        try:
+            import openai as _openai
+        except ImportError:
+            raise RuntimeError("openai SDK not installed — run: pip install openai")
+
+        model = "grok-3-mini"
+        client = _openai.OpenAI(
+            api_key=os.environ["XAI_API_KEY"],
+            base_url="https://api.x.ai/v1",
+        )
+        t0 = time.perf_counter()
+        client.chat.completions.create(
+            model=model,
+            max_tokens=64,
+            messages=[{"role": "user", "content": self.prompt}],
+        )
+        ms = round((time.perf_counter() - t0) * 1000, 1)
+        return {"backend": "grok", "status": "ok", "ms": ms, "model": model, "error": None}
+
+    def _bench_kimi(self) -> dict:
+        """Moonshot Kimi — OpenAI-compatible API, requires ``openai`` SDK + MOONSHOT_API_KEY."""
+        try:
+            import openai as _openai
+        except ImportError:
+            raise RuntimeError("openai SDK not installed — run: pip install openai")
+
+        model = "moonshot-v1-8k"
+        client = _openai.OpenAI(
+            api_key=os.environ["MOONSHOT_API_KEY"],
+            base_url="https://api.moonshot.cn/v1",
+        )
+        t0 = time.perf_counter()
+        client.chat.completions.create(
+            model=model,
+            max_tokens=64,
+            messages=[{"role": "user", "content": self.prompt}],
+        )
+        ms = round((time.perf_counter() - t0) * 1000, 1)
+        return {"backend": "kimi", "status": "ok", "ms": ms, "model": model, "error": None}
+
+    def _bench_nvidia(self) -> dict:
+        """NVIDIA NIM — OpenAI-compatible API, requires ``openai`` SDK + NVIDIA_API_KEY."""
+        try:
+            import openai as _openai
+        except ImportError:
+            raise RuntimeError("openai SDK not installed — run: pip install openai")
+
+        model = "meta/llama-3.1-8b-instruct"
+        client = _openai.OpenAI(
+            api_key=os.environ["NVIDIA_API_KEY"],
+            base_url="https://integrate.api.nvidia.com/v1",
+        )
+        t0 = time.perf_counter()
+        client.chat.completions.create(
+            model=model,
+            max_tokens=64,
+            messages=[{"role": "user", "content": self.prompt}],
+        )
+        ms = round((time.perf_counter() - t0) * 1000, 1)
+        return {"backend": "nvidia", "status": "ok", "ms": ms, "model": model, "error": None}
+
+
+# ---------------------------------------------------------------------------
+# Rich table renderer
+# ---------------------------------------------------------------------------
+
+
+def _render_table(results: list[dict]) -> None:
+    """Render benchmark results as a Rich table with a fastest-backend summary."""
+    table = Table(title="LLM Backend Benchmark", show_header=True, header_style="bold magenta")
+    table.add_column("Backend", style="cyan", no_wrap=True)
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Model", style="dim")
+    table.add_column("Latency (ms)", justify="right")
+    table.add_column("Note")
+
+    for r in results:
+        status = r["status"]
+        if status == "ok":
+            status_str = "[green]ok[/]"
+            ms_str = f"[green]{r['ms']}[/]"
+        elif status == "unavailable":
+            status_str = "[dim]unavailable[/]"
+            ms_str = "[dim]—[/]"
+        else:
+            status_str = "[red]error[/]"
+            ms_str = "[red]—[/]"
+
+        table.add_row(
+            r["backend"],
+            status_str,
+            r.get("model") or "—",
+            ms_str,
+            r.get("error") or "",
+        )
+
+    console.print(table)
+
+    ok_results = [r for r in results if r["status"] == "ok"]
+    if ok_results:
+        fastest = min(ok_results, key=lambda r: r["ms"])
+        console.print(
+            f"\n[bold]Fastest:[/] [green]{fastest['backend']}[/] — {fastest['ms']} ms"
+            f"  ([dim]{fastest['model']}[/])"
+        )
+    elif all(r["status"] == "unavailable" for r in results):
+        console.print("[yellow]No backends available. Set API keys or start Ollama.[/]")
+
+
+# ---------------------------------------------------------------------------
+# CLI registration
+# ---------------------------------------------------------------------------
+
+
+def register_benchmark_commands(main: click.Group) -> None:
+    """Register the ``skcapstone benchmark`` command."""
+
+    @main.command("benchmark")
+    @click.option(
+        "--prompt", default="Hello", show_default=True,
+        help="Prompt to send to each backend.",
+    )
+    @click.option(
+        "--timeout", default=30.0, show_default=True, type=float,
+        help="Per-backend timeout in seconds.",
+    )
+    @click.option(
+        "--include-unavailable", is_flag=True,
+        help="Include unavailable backends in output (they will show as 'unavailable').",
+    )
+    @click.option("--json-out", is_flag=True, help="Output raw JSON instead of a table.")
+    def benchmark_cmd(
+        prompt: str,
+        timeout: float,
+        include_unavailable: bool,
+        json_out: bool,
+    ) -> None:
+        """Benchmark LLM response time across all available backends.
+
+        Sends PROMPT to each detected backend, measures latency, and
+        reports results in a table.  Cloud backends require API key env vars
+        (ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY,
+        NVIDIA_API_KEY).  Ollama is probed via HTTP on OLLAMA_HOST.
+        """
+        runner = BenchmarkRunner(prompt=prompt, timeout=timeout)
+
+        if not json_out:
+            console.print(
+                f"[bold]Benchmarking LLM backends[/] — "
+                f"prompt: [cyan]{prompt!r}[/]  timeout: {timeout}s"
+            )
+            console.print()
+
+        results = runner.run_all(skip_unavailable=not include_unavailable)
+
+        if json_out:
+            click.echo(json.dumps(results, indent=2))
+            return
+
+        _render_table(results)

package/src/skcapstone/cli/capabilities_cmd.py

@@ -0,0 +1,171 @@
+"""Capabilities commands: list, add, remove."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+import yaml
+
+from ._common import AGENT_HOME, console
+
+from rich.panel import Panel
+from rich.table import Table
+
+
+def _load_config_data(config_path: Path) -> dict:
+    """Load raw config dict from YAML, or return empty dict."""
+    if config_path.exists():
+        try:
+            return yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            return {}
+    return {}
+
+
+def _save_config_data(config_path: Path, data: dict) -> None:
+    """Write config dict back to YAML, creating parent dirs as needed."""
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(yaml.dump(data, default_flow_style=False), encoding="utf-8")
+
+
+def _current_capabilities(config_path: Path) -> list[str]:
+    """Return the current capabilities list from config (or defaults)."""
+    data = _load_config_data(config_path)
+    caps = data.get("capabilities")
+    if isinstance(caps, list):
+        return [str(c) for c in caps if c]
+    from ..models import AgentConfig
+    return list(AgentConfig().capabilities)
+
+
+def register_capabilities_commands(main: click.Group) -> None:
+    """Register the capabilities command group."""
+
+    @main.group(invoke_without_command=True)
+    @click.option("--home", "sk_home", default=AGENT_HOME, type=click.Path())
+    @click.option("--json", "json_out", is_flag=True, help="Output as JSON.")
+    @click.pass_context
+    def capabilities(ctx, sk_home, json_out):
+        """Agent capability advertisement — what this agent can do.
+
+        Capabilities are included in every heartbeat beacon so peers
+        know what services this agent offers.
+
+        Defaults: consciousness, code, chat, memory
+        """
+        if ctx.invoked_subcommand is None:
+            sk_path = Path(sk_home).expanduser()
+            config_path = sk_path / "config" / "config.yaml"
+            caps = _current_capabilities(config_path)
+
+            if json_out:
+                click.echo(json.dumps(caps, indent=2))
+                return
+
+            console.print()
+            if not caps:
+                console.print("  [dim]No capabilities configured.[/]")
+                console.print()
+                return
+
+            table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+            table.add_column("#", style="dim", width=4)
+            table.add_column("Capability", style="cyan")
+
+            for i, name in enumerate(caps, 1):
+                table.add_row(str(i), name)
+
+            source = "[dim](from config)[/]" if (config_path.exists() and
+                _load_config_data(config_path).get("capabilities")) else "[dim](defaults)[/]"
+            console.print(Panel(
+                f"[bold]{len(caps)}[/] capability(s) advertised  {source}",
+                title="Agent Capabilities",
+                border_style="bright_blue",
+            ))
+            console.print(table)
+            console.print()
+
+    @capabilities.command("list")
+    @click.option("--home", "sk_home", default=AGENT_HOME, type=click.Path())
+    @click.option("--json", "json_out", is_flag=True, help="Output as JSON.")
+    def capabilities_list(sk_home, json_out):
+        """List capabilities advertised in heartbeat beacons."""
+        sk_path = Path(sk_home).expanduser()
+        config_path = sk_path / "config" / "config.yaml"
+        caps = _current_capabilities(config_path)
+
+        if json_out:
+            click.echo(json.dumps(caps, indent=2))
+            return
+
+        console.print()
+        if not caps:
+            console.print("  [dim]No capabilities configured.[/]")
+            console.print()
+            return
+
+        for name in caps:
+            console.print(f"  [cyan]{name}[/]")
+        console.print()
+
+    @capabilities.command("add")
+    @click.argument("name")
+    @click.option("--home", "sk_home", default=AGENT_HOME, type=click.Path())
+    def capabilities_add(name, sk_home):
+        """Add a capability to the advertised list.
+
+        Example: skcapstone capabilities add vector-search
+        """
+        name = name.strip()
+        if not name:
+            console.print("\n  [red]Capability name cannot be empty.[/]\n")
+            sys.exit(1)
+
+        sk_path = Path(sk_home).expanduser()
+        config_path = sk_path / "config" / "config.yaml"
+        data = _load_config_data(config_path)
+
+        # Seed from defaults if no key yet
+        if "capabilities" not in data:
+            from ..models import AgentConfig
+            data["capabilities"] = list(AgentConfig().capabilities)
+
+        caps: list[str] = data["capabilities"]
+        if name in caps:
+            console.print(f"\n  [yellow]'{name}' is already in the capabilities list.[/]\n")
+            return
+
+        caps.append(name)
+        data["capabilities"] = caps
+        _save_config_data(config_path, data)
+        console.print(f"\n  [green]Added capability:[/] [cyan]{name}[/]\n")
+
+    @capabilities.command("remove")
+    @click.argument("name")
+    @click.option("--home", "sk_home", default=AGENT_HOME, type=click.Path())
+    def capabilities_remove(name, sk_home):
+        """Remove a capability from the advertised list.
+
+        Example: skcapstone capabilities remove chat
+        """
+        name = name.strip()
+        sk_path = Path(sk_home).expanduser()
+        config_path = sk_path / "config" / "config.yaml"
+        data = _load_config_data(config_path)
+
+        if "capabilities" not in data:
+            from ..models import AgentConfig
+            data["capabilities"] = list(AgentConfig().capabilities)
+
+        caps: list[str] = data["capabilities"]
+        if name not in caps:
+            console.print(f"\n  [yellow]'{name}' not found in capabilities list.[/]\n")
+            return
+
+        caps.remove(name)
+        data["capabilities"] = caps
+        _save_config_data(config_path, data)
+        console.print(f"\n  [green]Removed capability:[/] [cyan]{name}[/]\n")

package/src/skcapstone/cli/card.py

@@ -0,0 +1,151 @@
+"""Agent card commands: generate, show, verify, export."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from ._common import AGENT_HOME, console
+from ..runtime import get_runtime
+
+from rich.panel import Panel
+
+
+def register_card_commands(main: click.Group) -> None:
+    """Register the card command group."""
+
+    @main.group()
+    def card():
+        """Agent card — shareable sovereign identity for P2P discovery.
+
+        Generate, view, export, and verify sovereign agent identity cards.
+        Cards contain your CapAuth identity, contact transports, and capabilities.
+        """
+
+    @card.command("generate")
+    @click.option("--home", default=AGENT_HOME, type=click.Path(), help="Agent home directory.")
+    @click.option("--capauth-home", default="~/.capauth", type=click.Path(), help="CapAuth home.")
+    @click.option("--motto", default=None, help="Short tagline for the card.")
+    @click.option("--output", "-o", default=None, type=click.Path(), help="Output file path.")
+    @click.option("--sign", "do_sign", is_flag=True, default=False, help="Sign the card with your PGP key.")
+    @click.option("--passphrase", "-p", default=None, hide_input=True, help="PGP passphrase for signing.")
+    def card_generate(home, capauth_home, motto, output, do_sign, passphrase):
+        """Generate an agent card from your CapAuth profile."""
+        from ..agent_card import AgentCapability, AgentCard
+
+        home_path = Path(home).expanduser()
+
+        try:
+            agent_card = AgentCard.from_capauth_profile(
+                profile_dir=capauth_home,
+                capabilities=[
+                    AgentCapability(name="chat", description="SKChat encrypted messaging"),
+                    AgentCapability(name="memory", description="SKMemory persistent context"),
+                ],
+            )
+        except FileNotFoundError:
+            runtime = get_runtime(home_path)
+            m = runtime.manifest
+            agent_card = AgentCard.generate(
+                name=m.name, fingerprint=m.identity.fingerprint or "unknown",
+                public_key="", entity_type="ai",
+            )
+
+        if motto:
+            agent_card.motto = motto
+
+        if do_sign:
+            if not passphrase:
+                passphrase = click.prompt("PGP passphrase", hide_input=True)
+            capauth_path = Path(capauth_home).expanduser()
+            priv_path = capauth_path / "identity" / "private.asc"
+            if priv_path.exists():
+                agent_card.sign(priv_path.read_text(encoding="utf-8"), passphrase)
+                console.print("[green]Card signed.[/]")
+            else:
+                console.print("[yellow]Private key not found, card unsigned.[/]")
+
+        out_path = output or str(home_path / "agent-card.json")
+        agent_card.save(out_path)
+
+        console.print(Panel(agent_card.summary(), title="Agent Card Generated", border_style="cyan"))
+        console.print(f"  [dim]Saved to: {out_path}[/]\n")
+
+    @card.command("show")
+    @click.argument("filepath", default="~/.skcapstone/agent-card.json")
+    def card_show(filepath):
+        """Display an agent card."""
+        from ..agent_card import AgentCard
+
+        try:
+            agent_card = AgentCard.load(filepath)
+        except FileNotFoundError:
+            console.print(f"[red]Card not found: {filepath}[/]")
+            raise SystemExit(1)
+
+        verified = AgentCard.verify_signature(agent_card)
+        sig_str = "[green]VALID[/]" if verified else (
+            "[yellow]unsigned[/]" if not agent_card.signature else "[red]INVALID[/]"
+        )
+
+        console.print(Panel(
+            f"[bold]{agent_card.name}[/] ({agent_card.entity_type})\n"
+            f"Fingerprint: [cyan]{agent_card.fingerprint[:16]}...[/]\n"
+            f"Trust: depth={agent_card.trust_depth} entangled={agent_card.entangled}\n"
+            f"Signature: {sig_str}\n"
+            f"Transports: {len(agent_card.transports)}\n"
+            f"Capabilities: {', '.join(c.name for c in agent_card.capabilities) or 'none'}\n"
+            + (f'Motto: "{agent_card.motto}"' if agent_card.motto else ""),
+            title=f"Agent Card: {agent_card.name}",
+            border_style="cyan",
+        ))
+
+    @card.command("verify")
+    @click.argument("filepath")
+    def card_verify(filepath):
+        """Verify the PGP signature on an agent card."""
+        from ..agent_card import AgentCard
+
+        try:
+            agent_card = AgentCard.load(filepath)
+        except FileNotFoundError:
+            console.print(f"[red]Card not found: {filepath}[/]")
+            raise SystemExit(1)
+
+        if not agent_card.signature:
+            console.print("[yellow]Card is not signed.[/]")
+            raise SystemExit(1)
+
+        if AgentCard.verify_signature(agent_card):
+            console.print(Panel(
+                f"[bold green]VERIFIED[/]\nAgent: {agent_card.name}\n"
+                f"Fingerprint: {agent_card.fingerprint[:16]}...",
+                title="Signature Valid", border_style="green",
+            ))
+        else:
+            console.print(Panel(
+                f"[bold red]SIGNATURE INVALID[/]\nAgent: {agent_card.name}\n"
+                "The card may have been tampered with.",
+                title="Verification Failed", border_style="red",
+            ))
+            raise SystemExit(1)
+
+    @card.command("export")
+    @click.argument("filepath", default="~/.skcapstone/agent-card.json")
+    @click.option("--compact", is_flag=True, help="Export compact format (no public key).")
+    def card_export(filepath, compact):
+        """Export an agent card to stdout (for sharing)."""
+        from ..agent_card import AgentCard
+
+        try:
+            agent_card = AgentCard.load(filepath)
+        except FileNotFoundError:
+            console.print(f"[red]Card not found: {filepath}[/]")
+            raise SystemExit(1)
+
+        if compact:
+            click.echo(json.dumps(agent_card.to_compact(), indent=2))
+        else:
+            click.echo(agent_card.model_dump_json(indent=2))