kctl-litellm 0.2.0__py3-none-any.whl

kctl_litellm/__init__.py

@@ -0,0 +1,3 @@
+"""Kodemeio LiteLLM CLI."""
+
+__version__ = "0.2.0"

kctl_litellm/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m kctl_litellm."""
+
+from kctl_litellm.cli import _run
+
+_run()

kctl_litellm/cli.py

@@ -0,0 +1,126 @@
+"""Main CLI entry point for kctl-litellm."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import handle_cli_error
+
+from kctl_litellm import __version__
+from kctl_litellm.commands.budgets_cmd import app as budgets_app
+from kctl_litellm.commands.config_cmd import app as config_app
+from kctl_litellm.commands.health_cmd import app as health_app
+from kctl_litellm.commands.keys_cmd import app as keys_app
+from kctl_litellm.commands.logs_cmd import app as logs_app
+from kctl_litellm.commands.models_cmd import app as models_app
+from kctl_litellm.commands.spend_cmd import app as spend_app
+from kctl_litellm.commands.teams_cmd import app as teams_app
+from kctl_litellm.core.callbacks import AppContext
+from kctl_litellm.core.exceptions import LiteLLMError
+from kctl_lib.self_update import notify_if_outdated
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-litellm {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-litellm",
+    help="Kodemeio LiteLLM CLI - manage LiteLLM proxy instances.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    url: Annotated[str | None, typer.Option("--url", help="LiteLLM URL override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio LiteLLM CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        url_override=url,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-litellm", __version__)
+
+
+_P_ADMIN = "Admin & Config"
+app.add_typer(config_app, name="config", rich_help_panel=_P_ADMIN)
+
+_P_SERVICES = "Services"
+app.add_typer(health_app, name="health", rich_help_panel=_P_SERVICES)
+app.add_typer(models_app, name="models", rich_help_panel=_P_SERVICES)
+
+_P_KEYS = "Key Management"
+app.add_typer(keys_app, name="keys", rich_help_panel=_P_KEYS)
+
+_P_TEAMS = "Teams & Budgets"
+app.add_typer(teams_app, name="teams", rich_help_panel=_P_TEAMS)
+app.add_typer(budgets_app, name="budgets", rich_help_panel=_P_TEAMS)
+
+_P_USAGE = "Usage & Spend"
+app.add_typer(spend_app, name="spend", rich_help_panel=_P_USAGE)
+app.add_typer(logs_app, name="logs", rich_help_panel=_P_USAGE)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-litellm."""
+    actx = ctx.obj
+    out = actx.output
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-litellm", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-litellm")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-litellm", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-litellm", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except LiteLLMError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_litellm/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules for kctl-litellm."""

kctl_litellm/commands/budgets_cmd.py

@@ -0,0 +1,116 @@
+"""Budget management commands for kctl-litellm.
+
+Create and list LiteLLM budgets.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich import print as rprint
+from rich.table import Table
+
+from kctl_litellm.core.callbacks import AppContext
+from kctl_litellm.core.client import LiteLLMClient
+from kctl_litellm.core.exceptions import LiteLLMError
+
+app = typer.Typer(help="Manage LiteLLM budgets.")
+
+
+def _get_client(actx: AppContext) -> LiteLLMClient:
+    cfg = actx.config
+    return LiteLLMClient(base_url=cfg.url, master_key=cfg.master_key)
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    budget_id: Annotated[str | None, typer.Option("--budget-id", help="Budget identifier.")] = None,
+    max_budget: Annotated[float, typer.Option("--max-budget", help="Maximum budget in USD.")] = 100.0,
+    soft_budget: Annotated[
+        float | None, typer.Option("--soft-budget", help="Soft budget limit (warning threshold).")
+    ] = None,
+    max_parallel_requests: Annotated[
+        int | None, typer.Option("--max-parallel-requests", help="Max parallel requests.")
+    ] = None,
+    tpm_limit: Annotated[int | None, typer.Option("--tpm-limit", help="Tokens per minute limit.")] = None,
+    rpm_limit: Annotated[int | None, typer.Option("--rpm-limit", help="Requests per minute limit.")] = None,
+) -> None:
+    """Create a new budget.
+
+    Example: kctl-litellm budgets create --budget-id dev-budget --max-budget 200
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    kwargs: dict = {"max_budget": max_budget}
+    if budget_id:
+        kwargs["budget_id"] = budget_id
+    if soft_budget is not None:
+        kwargs["soft_budget"] = soft_budget
+    if max_parallel_requests is not None:
+        kwargs["max_parallel_requests"] = max_parallel_requests
+    if tpm_limit is not None:
+        kwargs["tpm_limit"] = tpm_limit
+    if rpm_limit is not None:
+        kwargs["rpm_limit"] = rpm_limit
+
+    try:
+        client = _get_client(actx)
+        result = client.create_budget(**kwargs)
+        client.close()
+    except LiteLLMError as exc:
+        out.error(str(exc))
+        raise typer.Exit(1) from exc
+
+    out.success("Budget created")
+    out.kv("Budget ID", result.get("budget_id", "[dim]auto-generated[/dim]"))
+    out.kv("Max Budget", f"${result.get('max_budget', max_budget)}")
+    if result.get("soft_budget") is not None:
+        out.kv("Soft Budget", f"${result['soft_budget']}")
+    if result.get("tpm_limit"):
+        out.kv("TPM Limit", str(result["tpm_limit"]))
+    if result.get("rpm_limit"):
+        out.kv("RPM Limit", str(result["rpm_limit"]))
+
+
+@app.command("list")
+def list_(ctx: typer.Context) -> None:
+    """List all budgets."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        client = _get_client(actx)
+        budgets = client.list_budgets()
+        client.close()
+    except LiteLLMError as exc:
+        out.error(str(exc))
+        raise typer.Exit(1) from exc
+
+    if not budgets:
+        out.warn("No budgets found.")
+        return
+
+    table = Table(title="Budgets", show_header=True, header_style="bold cyan")
+    table.add_column("Budget ID", style="cyan")
+    table.add_column("Max Budget", justify="right")
+    table.add_column("Soft Budget", justify="right")
+    table.add_column("TPM Limit", justify="right")
+    table.add_column("RPM Limit", justify="right")
+    table.add_column("Max Parallel", justify="right")
+
+    for b in budgets:
+        if not isinstance(b, dict):
+            continue
+        budget_id = b.get("budget_id", "unknown")
+        max_b = f"${b['max_budget']:.2f}" if b.get("max_budget") is not None else "[dim]-[/dim]"
+        soft_b = f"${b['soft_budget']:.2f}" if b.get("soft_budget") is not None else "[dim]-[/dim]"
+        tpm = str(b.get("tpm_limit", "")) or "[dim]-[/dim]"
+        rpm = str(b.get("rpm_limit", "")) or "[dim]-[/dim]"
+        max_par = str(b.get("max_parallel_requests", "")) or "[dim]-[/dim]"
+        table.add_row(budget_id, max_b, soft_b, tpm, rpm, max_par)
+
+    rprint(table)
+    out.info(f"Total budgets: {len(budgets)}")

kctl_litellm/commands/config_cmd.py

@@ -0,0 +1,225 @@
+"""Configuration management commands for kctl-litellm.
+
+Manage profiles and LiteLLM connection settings.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated
+
+import typer
+from rich import print as rprint
+from rich.table import Table
+
+from kctl_litellm.core.callbacks import AppContext
+from kctl_litellm.core.config import (
+    SERVICE_KEY,
+    ServiceConfig,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    get_service_config,
+    remove_profile,
+    resolve_active_profile_name,
+    set_default_profile,
+    set_service_config,
+)
+
+app = typer.Typer(help="Manage CLI configuration and profiles.")
+
+
+def _mask_secret(secret: str) -> str:
+    """Mask a secret, showing only last 8 chars."""
+    if not secret:
+        return "[dim]not set[/dim]"
+    if len(secret) <= 8:
+        return "****"
+    return f"{'*' * (len(secret) - 8)}{secret[-8:]}"
+
+
+@app.command()
+def profiles(ctx: typer.Context) -> None:
+    """List all profiles with their LiteLLM configuration."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    profile_names = get_profile_names()
+    if not profile_names:
+        out.warn("No profiles configured.")
+        return
+
+    default = get_default_profile()
+    active = resolve_active_profile_name(actx.profile)
+
+    table = Table(title="Profiles", show_header=True, header_style="bold cyan")
+    table.add_column("Name", style="cyan")
+    table.add_column("URL")
+    table.add_column("Default")
+
+    for pname in profile_names:
+        svc = get_service_config(pname)
+        is_default = pname == default
+        is_active = pname == active
+        default_marker = "[green]yes[/green]" if is_default else ""
+        if is_active and not is_default:
+            default_marker = "[yellow]active[/yellow]"
+        elif is_active and is_default:
+            default_marker = "[green]yes (active)[/green]"
+        table.add_row(pname, svc.url or "[dim]-[/dim]", default_marker)
+
+    rprint(table)
+
+
+@app.command()
+def show(
+    ctx: typer.Context,
+    name: Annotated[str | None, typer.Argument(help="Profile name (default: active profile)")] = None,
+) -> None:
+    """Show current profile config (secrets masked)."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    profile_name = name or resolve_active_profile_name(actx.profile)
+    svc = get_service_config(profile_name)
+
+    out.kv("Profile", profile_name)
+    out.kv("Service", SERVICE_KEY)
+    out.kv("URL", svc.url or "[dim]not set[/dim]")
+    out.kv("Master Key", _mask_secret(svc.master_key))
+    out.kv("Salt Key", _mask_secret(svc.salt_key))
+    out.kv("DB URL", _mask_secret(svc.db_url))
+    out.kv("SSH Host", svc.ssh_host or "[dim]not set[/dim]")
+    out.kv("SSH Port", str(svc.ssh_port))
+    out.kv("SSH User", svc.ssh_user)
+    out.kv("SSH Key", svc.ssh_key)
+    out.kv("Container Name", svc.container_name or "[dim]not set[/dim]")
+
+
+@app.command()
+def current(ctx: typer.Context) -> None:
+    """Show the active profile name."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    active = resolve_active_profile_name(actx.profile)
+    default = get_default_profile()
+
+    source = "config default"
+    if actx.profile:
+        source = "--profile flag"
+    elif os.environ.get("KCTL_LITELLM_PROFILE"):
+        source = "KCTL_LITELLM_PROFILE env var"
+
+    out.kv("Active Profile", active)
+    out.kv("Default Profile", default)
+    out.kv("Source", source)
+
+
+@app.command()
+def add(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Profile name (e.g. production, staging)")],
+    url: Annotated[str | None, typer.Option("--url", help="LiteLLM proxy URL.")] = None,
+    master_key: Annotated[str | None, typer.Option("--master-key", help="Master key for API access.")] = None,
+    salt_key: Annotated[str | None, typer.Option("--salt-key", help="Salt key for hashing.")] = None,
+    db_url: Annotated[str | None, typer.Option("--db-url", help="Database connection URL.")] = None,
+    ssh_host: Annotated[str | None, typer.Option("--ssh-host", help="SSH host (public IP).")] = None,
+    ssh_user: Annotated[str, typer.Option("--ssh-user", help="SSH username.")] = "root",
+    container_name: Annotated[str | None, typer.Option("--container-name", help="Docker container name.")] = None,
+    set_default: Annotated[bool, typer.Option("--default", help="Set as default profile.")] = False,
+) -> None:
+    """Add or update a LiteLLM profile.
+
+    Example: kctl-litellm config add production --url https://litellm.kodeme.io --master-key sk-...
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    existing = get_service_config(name)
+    if existing.url:
+        if not typer.confirm(f"Profile '{name}' already has {SERVICE_KEY} config ({existing.url}). Overwrite?"):
+            raise typer.Exit(0)
+
+    svc = ServiceConfig(
+        url=url or "",
+        master_key=master_key or "",
+        salt_key=salt_key or "",
+        db_url=db_url or "",
+        ssh_host=ssh_host or "",
+        ssh_user=ssh_user,
+        container_name=container_name or "",
+    )
+
+    set_service_config(name, svc)
+
+    if set_default or len(get_profile_names()) == 1:
+        set_default_profile(name)
+
+    out.success(f"Profile '{name}' -> {SERVICE_KEY} configured")
+    out.kv("URL", svc.url or "[dim]not set[/dim]")
+    if svc.ssh_host:
+        out.kv("SSH", f"{ssh_user}@{svc.ssh_host}")
+    if get_default_profile() == name:
+        out.info("Set as default profile")
+
+
+@app.command("remove")
+def remove_(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Profile name to remove")],
+    force: Annotated[bool, typer.Option("--force", help="Skip confirmation")] = False,
+) -> None:
+    """Remove a profile."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    profile_names = get_profile_names()
+    if name not in profile_names:
+        out.error(f"Profile '{name}' not found")
+        out.info(f"Available: {', '.join(profile_names)}")
+        raise typer.Exit(1)
+
+    if not force:
+        services = get_all_services_in_profile(name)
+        svc_list = ", ".join(services.keys()) if services else "empty"
+        if not typer.confirm(f"Remove entire profile '{name}' (services: {svc_list})?"):
+            raise typer.Exit(0)
+
+    remove_profile(name)
+    out.success(f"Profile '{name}' removed")
+
+    new_default = get_default_profile()
+    if new_default and new_default != name:
+        out.info(f"Default is now: {new_default}")
+
+
+@app.command()
+def use(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Profile name to switch to")],
+) -> None:
+    """Set the default profile.
+
+    Example: kctl-litellm config use production
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    profile_names = get_profile_names()
+    if name not in profile_names:
+        out.error(f"Profile '{name}' not found")
+        out.info(f"Available: {', '.join(profile_names)}")
+        raise typer.Exit(1)
+
+    old_default = get_default_profile()
+    set_default_profile(name)
+
+    svc = get_service_config(name)
+    if svc.url:
+        out.success(f"Switched to '{name}' ({svc.url})")
+    else:
+        out.warn(f"Switched to '{name}' -- no {SERVICE_KEY} config in this profile")
+
+    if old_default and old_default != name:
+        out.info(f"Previous default: {old_default}")

kctl_litellm/commands/health_cmd.py

@@ -0,0 +1,135 @@
+"""Health check commands for kctl-litellm.
+
+Check LiteLLM proxy service health via HTTP.
+"""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+import typer
+from rich import print as rprint
+from rich.table import Table
+
+from kctl_litellm.core.callbacks import AppContext
+from kctl_litellm.core.client import LiteLLMClient
+from kctl_litellm.core.exceptions import LiteLLMError
+
+app = typer.Typer(help="Check LiteLLM proxy service health.")
+
+
+def _get_client(actx: AppContext) -> LiteLLMClient:
+    cfg = actx.config
+    return LiteLLMClient(base_url=cfg.url, master_key=cfg.master_key)
+
+
+@app.command()
+def check(ctx: typer.Context) -> None:
+    """Full health check via /health endpoint.
+
+    Shows healthy and unhealthy models in a table.
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        client = _get_client(actx)
+        result = client.health_check()
+        client.close()
+    except LiteLLMError as exc:
+        out.error(str(exc))
+        raise typer.Exit(1) from exc
+
+    # Parse healthy/unhealthy models from the response
+    healthy = result.get("healthy_endpoints", [])
+    unhealthy = result.get("unhealthy_endpoints", [])
+
+    table = Table(title="LiteLLM Health Check", show_header=True, header_style="bold cyan")
+    table.add_column("Model", style="cyan")
+    table.add_column("Status")
+    table.add_column("Details")
+
+    for endpoint in healthy:
+        model = endpoint.get("model", "unknown") if isinstance(endpoint, dict) else str(endpoint)
+        details = endpoint.get("api_base", "") if isinstance(endpoint, dict) else ""
+        table.add_row(model, "[green]healthy[/green]", details)
+
+    for endpoint in unhealthy:
+        model = endpoint.get("model", "unknown") if isinstance(endpoint, dict) else str(endpoint)
+        error = endpoint.get("error", "") if isinstance(endpoint, dict) else ""
+        table.add_row(model, "[red]unhealthy[/red]", str(error)[:80])
+
+    if not healthy and not unhealthy:
+        # Simple status display if no model-level data
+        status = result.get("status", "unknown")
+        if status == "healthy":
+            out.success("LiteLLM proxy is healthy")
+        else:
+            out.warn(f"LiteLLM proxy status: {status}")
+        return
+
+    rprint(table)
+    out.info(f"Healthy: {len(healthy)}, Unhealthy: {len(unhealthy)}")
+
+
+@app.command()
+def ping(ctx: typer.Context) -> None:
+    """Quick connectivity check (GET /, show status code and response time)."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    cfg = actx.config
+    if not cfg.url:
+        out.error("No LiteLLM URL configured. Run: kctl-litellm config add <name> --url <url>")
+        raise typer.Exit(1)
+
+    base_url = cfg.url.rstrip("/")
+    start = time.monotonic()
+    try:
+        response = httpx.get(f"{base_url}/", timeout=10.0)
+        elapsed = (time.monotonic() - start) * 1000
+        out.kv("URL", base_url)
+        out.kv("Status", str(response.status_code))
+        out.kv("Response time", f"{elapsed:.1f}ms")
+    except httpx.ConnectError as exc:
+        out.error(f"Connection failed: {exc}")
+        raise typer.Exit(1) from exc
+    except httpx.TimeoutException as exc:
+        out.error(f"Timeout: {exc}")
+        raise typer.Exit(1) from exc
+
+
+@app.command()
+def liveliness(ctx: typer.Context) -> None:
+    """Quick liveness check via /health/liveliness (no auth required)."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    cfg = actx.config
+    if not cfg.url:
+        out.error("No LiteLLM URL configured. Run: kctl-litellm config add <name> --url <url>")
+        raise typer.Exit(1)
+
+    base_url = cfg.url.rstrip("/")
+    start = time.monotonic()
+    try:
+        response = httpx.get(f"{base_url}/health/liveliness", timeout=10.0)
+        result = response.json()
+        elapsed = (time.monotonic() - start) * 1000
+    except httpx.ConnectError as exc:
+        out.error(f"Connection failed: {exc}")
+        raise typer.Exit(1) from exc
+    except httpx.TimeoutException as exc:
+        out.error(f"Timeout: {exc}")
+        raise typer.Exit(1) from exc
+
+    status = result.get("status", "unknown") if isinstance(result, dict) else str(result)
+    out.kv("URL", cfg.url)
+    out.kv("Status", status)
+    out.kv("Response time", f"{elapsed:.1f}ms")
+
+    if status == "alive":
+        out.success("LiteLLM proxy is alive")
+    else:
+        out.warn(f"Unexpected status: {status}")