aegis-gateway-cli 2.0.0a0__py3-none-any.whl

aegis_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Aegis v2 — CLI package."""
+
+__version__ = "2.0.0a0"

aegis_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Aegis CLI command modules."""

aegis_cli/commands/chat.py

@@ -0,0 +1,65 @@
+"""CLI command: `aegis chat`."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from aegis_core.pipeline import PipelineAssembler, RunState
+from aegis_core.providers.models import Message
+from aegis_core.testing import FakeProvider
+
+_console = Console()
+_err_console = Console(stderr=True, style="bold red")
+
+
+def chat(
+    message: Annotated[str, typer.Argument(help="The message to send.")],
+    route: Annotated[
+        str,
+        typer.Option("--route", "-r", help="Route name to use."),
+    ] = "default",
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Emit JSON with the full event log."),
+    ] = False,
+) -> None:
+    """Send *message* through the pipeline and print the response."""
+    provider = FakeProvider(
+        name="fake",
+        complete_response=f"[fake] echo: {message}",
+    )
+
+    assembler = PipelineAssembler()
+    pipeline = assembler.compile(provider=provider, route=route)
+
+    initial_state = RunState(
+        run_id=str(uuid.uuid4()),
+        route=route,
+        messages=[Message(role="user", content=message)],
+    )
+
+    result = asyncio.run(pipeline.run(initial_state))
+
+    if json_output:
+        output = {
+            "run_id": result.run_id,
+            "route": result.route,
+            "status": result.status,
+            "response": result.response,
+            "events": [e.to_dict() for e in result.events],
+            "usage": {
+                "prompt_tokens": result.usage.prompt_tokens,
+                "completion_tokens": result.usage.completion_tokens,
+                "total_tokens": result.usage.total_tokens,
+                "cost": result.usage.cost,
+            },
+        }
+        _console.print(json.dumps(output, indent=2), markup=False)
+    else:
+        _console.print(result.response or "", markup=False)

aegis_cli/commands/config.py

@@ -0,0 +1,77 @@
+"""CLI commands: `aegis config validate` and `aegis config show`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.syntax import Syntax
+
+from aegis_core.config import load_config
+from aegis_core.errors import AegisConfigError
+
+app = typer.Typer(name="config", help="Validate and inspect Aegis configuration.")
+_console = Console()
+_err_console = Console(stderr=True, style="bold red")
+
+_DEFAULT_CONFIG = Path("aegis.yaml")
+
+
+@app.command("validate")
+def validate(
+    config_path: Annotated[
+        Path,
+        typer.Argument(help="Path to aegis.yaml to validate."),
+    ] = _DEFAULT_CONFIG,
+) -> None:
+    """Validate an aegis.yaml file and report any errors."""
+    try:
+        load_config(config_path)
+    except AegisConfigError as exc:
+        _err_console.print(str(exc))
+        raise typer.Exit(1) from exc
+    except Exception as exc:
+        _err_console.print(f"Unexpected error: {exc}")
+        raise typer.Exit(1) from exc
+
+    _console.print(f"[green]✓[/green] {config_path} is valid.")
+
+
+@app.command("show")
+def show(
+    config_path: Annotated[
+        Path,
+        typer.Argument(help="Path to aegis.yaml to display."),
+    ] = _DEFAULT_CONFIG,
+    output_format: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Output format: json or yaml."),
+    ] = "json",
+) -> None:
+    """Load and display the resolved configuration (secrets redacted)."""
+    try:
+        cfg = load_config(config_path)
+    except AegisConfigError as exc:
+        _err_console.print(str(exc))
+        raise typer.Exit(1) from exc
+    except Exception as exc:
+        _err_console.print(f"Unexpected error: {exc}")
+        raise typer.Exit(1) from exc
+
+    safe = cfg.safe_dict()
+
+    if output_format == "yaml":
+        try:
+            import yaml  # type: ignore[import-untyped]
+
+            text = yaml.dump(safe, default_flow_style=False, sort_keys=False)
+            _console.print(Syntax(text, "yaml", theme="monokai"))
+        except ImportError:
+            _err_console.print("PyYAML is required for YAML output.")
+            raise typer.Exit(1) from None
+    else:
+        text = json.dumps(safe, indent=2, default=str)
+        _console.print(Syntax(text, "json", theme="monokai"))

aegis_cli/commands/doctor.py

@@ -0,0 +1,246 @@
+"""CLI command: `aegis doctor` — environment health checks."""
+
+from __future__ import annotations
+
+import importlib.util
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(name="doctor", invoke_without_command=True, help="Check Aegis environment health.")
+_console = Console()
+_err_console = Console(stderr=True)
+
+_DEFAULT_CONFIG = Path("aegis.yaml")
+_DEFAULT_PROVIDERS_STORE = Path.home() / ".aegis" / "providers.json"
+
+
+class CheckStatus(StrEnum):
+    OK = "ok"
+    WARN = "warn"
+    FAIL = "fail"
+
+
+@dataclass
+class HealthCheck:
+    name: str
+    status: CheckStatus
+    detail: str
+
+
+# ---------------------------------------------------------------------------
+# Individual checks
+# ---------------------------------------------------------------------------
+
+
+def check_config(config_path: Path) -> HealthCheck:
+    """AEG-CFG: aegis.yaml exists and is valid YAML."""
+    if not config_path.exists():
+        return HealthCheck(
+            name="config",
+            status=CheckStatus.FAIL,
+            detail=f"{config_path} not found. Run `aegis init` to create one.",
+        )
+    try:
+        import yaml
+
+        with open(config_path) as f:
+            raw = yaml.safe_load(f)
+        if not isinstance(raw, (dict, type(None))):
+            return HealthCheck(
+                name="config",
+                status=CheckStatus.FAIL,
+                detail=f"{config_path} does not contain a YAML mapping.",
+            )
+    except Exception as exc:
+        return HealthCheck(
+            name="config",
+            status=CheckStatus.FAIL,
+            detail=f"{config_path} could not be parsed: {exc}",
+        )
+    return HealthCheck(name="config", status=CheckStatus.OK, detail=str(config_path))
+
+
+def check_pii_extra() -> HealthCheck:
+    """AEG-POL: presidio-analyzer (PII extra) is installed."""
+    spec = None
+    try:
+        spec = importlib.util.find_spec("presidio_analyzer")
+    except ModuleNotFoundError:
+        pass
+    if spec is None:
+        return HealthCheck(
+            name="pii_extra",
+            status=CheckStatus.WARN,
+            detail=(
+                "presidio-analyzer not installed. "
+                "Install aegis-pack-pii[pii] to enable PII masking."
+            ),
+        )
+    return HealthCheck(name="pii_extra", status=CheckStatus.OK, detail="presidio-analyzer found.")
+
+
+def check_rag_extra() -> HealthCheck:
+    """AEG-RAG: chromadb (RAG extra) is installed."""
+    spec = None
+    try:
+        spec = importlib.util.find_spec("chromadb")
+    except ModuleNotFoundError:
+        pass
+    if spec is None:
+        return HealthCheck(
+            name="rag_extra",
+            status=CheckStatus.WARN,
+            detail=(
+                "chromadb not installed. "
+                "Install aegis-core[rag] to enable RAG retrieval."
+            ),
+        )
+    return HealthCheck(name="rag_extra", status=CheckStatus.OK, detail="chromadb found.")
+
+
+def check_provider_store(store_path: Path = _DEFAULT_PROVIDERS_STORE) -> HealthCheck:
+    """AEG-PRV: provider profile store file exists."""
+    if not store_path.exists():
+        return HealthCheck(
+            name="provider_store",
+            status=CheckStatus.WARN,
+            detail=(
+                f"{store_path} not found. "
+                "Run `aegis provider add` to create a provider profile."
+            ),
+        )
+    return HealthCheck(
+        name="provider_store",
+        status=CheckStatus.OK,
+        detail=str(store_path),
+    )
+
+
+def check_providers_reachable(store_path: Path = _DEFAULT_PROVIDERS_STORE) -> HealthCheck:
+    """AEG-PRV: ping each provider in the store (opt-in)."""
+    if not store_path.exists():
+        return HealthCheck(
+            name="providers_reachable",
+            status=CheckStatus.WARN,
+            detail="No provider store found; skipping reachability check.",
+        )
+    try:
+        import json
+
+        with open(store_path) as f:
+            data = json.load(f)
+        profiles = data if isinstance(data, list) else []
+        if not profiles:
+            return HealthCheck(
+                name="providers_reachable",
+                status=CheckStatus.WARN,
+                detail="No provider profiles configured.",
+            )
+        # Best-effort TCP reachability for each profile with a base_url
+        import socket
+        import urllib.parse
+
+        unreachable: list[str] = []
+        for profile in profiles:
+            base_url = profile.get("base_url")
+            if not base_url:
+                continue
+            parsed = urllib.parse.urlparse(base_url)
+            host = parsed.hostname or ""
+            port = parsed.port or (443 if parsed.scheme == "https" else 80)
+            try:
+                with socket.create_connection((host, port), timeout=3):
+                    pass
+            except OSError:
+                unreachable.append(profile.get("name", host))
+
+        if unreachable:
+            return HealthCheck(
+                name="providers_reachable",
+                status=CheckStatus.FAIL,
+                detail=f"Unreachable: {', '.join(unreachable)}",
+            )
+        return HealthCheck(
+            name="providers_reachable",
+            status=CheckStatus.OK,
+            detail=f"All {len(profiles)} provider(s) reachable.",
+        )
+    except Exception as exc:
+        return HealthCheck(
+            name="providers_reachable",
+            status=CheckStatus.FAIL,
+            detail=f"Check failed: {exc}",
+        )
+
+
+# ---------------------------------------------------------------------------
+# Public helper for tests
+# ---------------------------------------------------------------------------
+
+
+def run_checks(
+    config_path: Path = _DEFAULT_CONFIG,
+    store_path: Path = _DEFAULT_PROVIDERS_STORE,
+    check_providers: bool = False,
+) -> list[HealthCheck]:
+    """Run all health checks and return the results."""
+    checks: list[HealthCheck] = [
+        check_config(config_path),
+        check_pii_extra(),
+        check_rag_extra(),
+        check_provider_store(store_path),
+    ]
+    if check_providers:
+        checks.append(check_providers_reachable(store_path))
+    return checks
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+@app.callback(invoke_without_command=True)
+def doctor(
+    config_path: Annotated[
+        Path,
+        typer.Option("--config", "-c", help="Path to aegis.yaml to validate."),
+    ] = _DEFAULT_CONFIG,
+    store_path: Annotated[
+        Path,
+        typer.Option("--store", help="Path to provider profile store."),
+    ] = _DEFAULT_PROVIDERS_STORE,
+    check_providers: Annotated[
+        bool,
+        typer.Option("--check-providers", help="Ping each configured provider (opt-in)."),
+    ] = False,
+) -> None:
+    """Check Aegis environment health (config, extras, provider store)."""
+    checks = run_checks(config_path, store_path, check_providers)
+
+    table = Table(title="Aegis Doctor", show_header=True, header_style="bold cyan")
+    table.add_column("Check", style="bold")
+    table.add_column("Status")
+    table.add_column("Detail")
+
+    any_fail = False
+    for check in checks:
+        if check.status == CheckStatus.OK:
+            status_str = "[green]OK[/green]"
+        elif check.status == CheckStatus.WARN:
+            status_str = "[yellow]WARN[/yellow]"
+        else:
+            status_str = "[red]FAIL[/red]"
+            any_fail = True
+        table.add_row(check.name, status_str, check.detail)
+
+    _console.print(table)
+
+    if any_fail:
+        raise typer.Exit(1)

aegis_cli/commands/init.py

@@ -0,0 +1,122 @@
+"""CLI command: `aegis init` — generate a starter aegis.yaml."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(name="init", invoke_without_command=True, help="Generate a starter aegis.yaml.")
+_console = Console()
+_err_console = Console(stderr=True, style="bold red")
+
+_DEFAULT_OUTPUT = Path("aegis.yaml")
+
+# ---------------------------------------------------------------------------
+# Template
+# ---------------------------------------------------------------------------
+
+_TEMPLATE = """\
+# aegis.yaml — generated by `aegis init`
+# Run `aegis config validate aegis.yaml` to validate this file.
+# Run `aegis policy lint aegis.yaml` to check policy references.
+
+# ── Providers ─────────────────────────────────────────────────────────────
+# Uncomment and configure at least one provider before serving requests.
+#
+# providers:
+#   my_provider:
+#     type: openai_compatible
+#     base_url: http://localhost:11434/v1
+#     model: llama3
+#     api_key: secret://env/MY_API_KEY#value
+
+# ── Guardrails ────────────────────────────────────────────────────────────
+# The PII guard is enabled by default (requires aegis-pack-pii[pii]).
+# Add more guards from available packs below.
+
+guardrails:
+  pii:
+    pack: aegis_pack_pii
+    mode: mask
+
+  # llm_guard:
+  #   pack: aegis_pack_llm_guard
+  #   scanners: [PromptInjection]
+  #   threshold: 0.8
+
+  # residency:
+  #   pack: aegis_pack_residency
+  #   region: us
+
+# ── Pipeline ──────────────────────────────────────────────────────────────
+# Guardrail names listed here must match keys in the guardrails section above.
+
+pipeline:
+  ingress: [pii]
+  # tool_result: [pii]
+  # egress: []   # note: non-incremental egress guards disable true-streaming
+
+# ── Routes ────────────────────────────────────────────────────────────────
+# Uncomment and configure after adding a provider above.
+#
+# routes:
+#   default:
+#     provider: my_provider
+#     model: llama3
+
+# ── Auth ──────────────────────────────────────────────────────────────────
+# Change to `type: api_key` and use `aegis keys create` for production.
+
+auth:
+  type: none
+"""
+
+
+# ---------------------------------------------------------------------------
+# Public helper for tests
+# ---------------------------------------------------------------------------
+
+
+def write_init_yaml(output: Path, force: bool = False) -> None:
+    """Write the starter aegis.yaml to *output*.
+
+    Raises:
+        FileExistsError: If *output* exists and *force* is False.
+    """
+    if output.exists() and not force:
+        raise FileExistsError(
+            f"{output} already exists. Use --force to overwrite."
+        )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(_TEMPLATE)
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+@app.callback(invoke_without_command=True)
+def init(
+    output: Annotated[
+        Path,
+        typer.Option("--output", "-o", help="Output path for aegis.yaml."),
+    ] = _DEFAULT_OUTPUT,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Overwrite existing file."),
+    ] = False,
+) -> None:
+    """Generate a starter aegis.yaml with PII guarding enabled."""
+    try:
+        write_init_yaml(output, force=force)
+    except FileExistsError as exc:
+        _err_console.print(str(exc))
+        raise typer.Exit(1) from exc
+
+    _console.print(f"[green]Created[/green] {output}")
+    _console.print("  Validate: [cyan]aegis config validate aegis.yaml[/cyan]")
+    _console.print("  Lint:     [cyan]aegis policy lint aegis.yaml[/cyan]")

aegis_cli/commands/keys.py

@@ -0,0 +1,87 @@
+"""CLI commands: `aegis keys create|list|revoke` (PROJECT_SPEC D17)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(help="Manage Aegis virtual API keys.", no_args_is_help=True)
+_console = Console()
+_DEFAULT_KEYS_PATH = Path.home() / ".aegis" / "keys.json"
+
+
+def _load_store(keys_path: Path) -> object:
+    from aegis_server.keys import KeyStore
+
+    return KeyStore(path=keys_path)
+
+
+@app.command("create")
+def create(
+    principal_id: Annotated[str, typer.Argument(help="Principal ID for this key.")],
+    team: Annotated[str, typer.Option("--team", "-t", help="Team name.")] = "",
+    keys_path: Annotated[
+        Path,
+        typer.Option("--keys-file", help="Path to keys JSON file."),
+    ] = _DEFAULT_KEYS_PATH,
+) -> None:
+    """Generate a new API key and print it once."""
+    from aegis_server.keys import KeyStore
+
+    store = KeyStore(path=keys_path)
+    key = store.create(principal_id=principal_id, team=team)
+    _console.print("[bold green]Key created.[/bold green] Store this — it will not be shown again.\n")
+    _console.print(key, markup=False)
+
+
+@app.command("list")
+def list_keys(
+    keys_path: Annotated[
+        Path,
+        typer.Option("--keys-file", help="Path to keys JSON file."),
+    ] = _DEFAULT_KEYS_PATH,
+) -> None:
+    """List all API keys (no plaintext shown)."""
+    from aegis_server.keys import KeyStore
+
+    store = KeyStore(path=keys_path)
+    entries = store.list()
+    if not entries:
+        _console.print("No keys found.")
+        return
+    table = Table(title="API Keys")
+    table.add_column("key_id")
+    table.add_column("principal_id")
+    table.add_column("team")
+    table.add_column("created_at")
+    for entry in entries:
+        table.add_row(
+            str(entry["key_id"]),
+            str(entry["principal_id"]),
+            str(entry["team"]),
+            str(entry["created_at"]),
+        )
+    _console.print(table)
+
+
+@app.command("revoke")
+def revoke(
+    key_id: Annotated[str, typer.Argument(help="The key_id to revoke.")],
+    keys_path: Annotated[
+        Path,
+        typer.Option("--keys-file", help="Path to keys JSON file."),
+    ] = _DEFAULT_KEYS_PATH,
+) -> None:
+    """Revoke an API key by its key_id."""
+    from aegis_server.keys import KeyStore
+
+    store = KeyStore(path=keys_path)
+    if store.revoke(key_id):
+        _console.print(f"[green]Revoked {key_id}.[/green]")
+    else:
+        _console.print(f"[red]Key '{key_id}' not found.[/red]")
+        raise typer.Exit(code=1)