kctl-litellm 0.2.0__tar.gz

kctl_litellm-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_litellm-0.2.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: kctl-litellm
+Version: 0.2.0
+Summary: Kodemeio LiteLLM CLI — manage LiteLLM proxy instances
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: kctl-lib>=0.4.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_litellm-0.2.0/README.md

@@ -0,0 +1,78 @@
+# kctl-litellm
+
+Kodemeio CLI for managing [LiteLLM](https://github.com/BerriAI/litellm) proxy instances. Part of the [kodemeio-platform](https://github.com/tgunawandev/kodemeio-platform) monorepo.
+
+## Installation
+
+```bash
+uv pip install -e packages/kctl-litellm
+```
+
+## Configuration
+
+Add a profile to `~/.config/kodemeio/config.yaml`:
+
+```yaml
+profiles:
+  production:
+    litellm:
+      url: https://llm.terakidz.com
+      master_key: ${KCTL_LITELLM_MASTER_KEY}
+      container_name: litellm
+```
+
+Or use the CLI:
+
+```bash
+kctl-litellm config add production --url https://llm.terakidz.com --master-key sk-...
+```
+
+## Usage
+
+```bash
+# Health
+kctl-litellm health check         # Full health check with model status
+kctl-litellm health ping          # Quick connectivity check
+kctl-litellm health liveliness    # Liveness probe (no auth)
+
+# Models
+kctl-litellm models list          # List available models
+kctl-litellm models info          # Detailed model info with pricing
+
+# Key Management
+kctl-litellm keys generate --key-alias my-app --max-budget 100
+kctl-litellm keys list
+kctl-litellm keys info <token>
+kctl-litellm keys delete <token>
+
+# Teams & Budgets
+kctl-litellm teams create --team-alias engineering --max-budget 500
+kctl-litellm teams list
+kctl-litellm budgets create --budget-id dev-tier --max-budget 200
+kctl-litellm budgets list
+
+# Spend & Logs
+kctl-litellm spend summary        # Total spend by model
+kctl-litellm spend daily          # Daily activity (last 7 days)
+kctl-litellm logs list --limit 50 # Recent request logs
+
+# Config
+kctl-litellm config profiles      # List profiles
+kctl-litellm config show          # Show current config (secrets masked)
+kctl-litellm config use staging   # Switch default profile
+```
+
+## Global Options
+
+```
+--json         Output as JSON
+--quiet, -q    Suppress info messages
+--profile, -p  Config profile name
+--url          LiteLLM URL override
+--version, -V  Show version
+```
+
+## Dependencies
+
+- Python >= 3.12
+- [kctl-lib](../kctl-lib) >= 0.4.0

kctl_litellm-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-litellm"
+version = "0.2.0"
+description = "Kodemeio LiteLLM CLI — manage LiteLLM proxy instances"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.4.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-litellm = "kctl_litellm.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_litellm"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_litellm-0.2.0/skills/litellm-admin/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: litellm-admin
+description: >
+  LiteLLM proxy administration via kctl-litellm CLI (7 groups, ~20 commands).
+  MUST use for ANY kctl-litellm operation.
+  Triggers on: "budget", "config", "health", "kctl-litellm", "keys", "litellm", "llm",
+  "logs", "models", "profile", "proxy", "spend", "teams", "tokens", "virtual-key".
+  Auto-generated: 2026-05-03
+---
+
+# litellm-admin -- kctl-litellm CLI Reference
+
+> Auto-generated from `kctl-litellm` command registry. Do not edit manually.
+> To regenerate: `kctl-litellm skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-litellm`
+**Command groups:** 7
+**Total commands:** ~20
+**Install:** `cd packages/kctl-litellm && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON |
+| `--quiet`, `-q` | Suppress info messages |
+| `--profile`, `-p` | Config profile name |
+| `--url` | LiteLLM URL override |
+| `--version`, `-V` | Show version |
+
+## Command Reference
+
+### `kctl-litellm health` (Services)
+
+Check LiteLLM proxy service health.
+
+| Command | Description |
+|---------|-------------|
+| `health check` | Full health check via /health endpoint. Shows healthy and unhealthy models. |
+| `health ping` | Quick connectivity check (GET /, status code and response time). |
+| `health liveliness` | Quick liveness check via /health/liveliness (no auth required). |
+
+### `kctl-litellm models` (Services)
+
+Manage and inspect LiteLLM models.
+
+| Command | Description |
+|---------|-------------|
+| `models list` | List available models via /v1/models. |
+| `models info [<model>]` | Show detailed model info with pricing via /model/info. |
+
+### `kctl-litellm keys` (Key Management)
+
+Manage LiteLLM virtual keys.
+
+| Command | Description |
+|---------|-------------|
+| `keys generate [--team-id] [--max-budget] [--duration] [--models] [--key-alias]` | Generate a new virtual key. |
+| `keys list` | List all virtual keys. |
+| `keys info <key>` | Show detailed key information (key value masked). |
+| `keys update <key> [--max-budget] [--models] [--key-alias] [--duration]` | Update a virtual key's settings. |
+| `keys delete <key> [--force]` | Delete a virtual key. |
+
+### `kctl-litellm teams` (Teams & Budgets)
+
+Manage LiteLLM teams.
+
+| Command | Description |
+|---------|-------------|
+| `teams create --team-alias <alias> [--max-budget] [--models]` | Create a new team. |
+| `teams list` | List all teams. |
+| `teams update <team_id> [--team-alias] [--max-budget] [--models]` | Update a team's settings. |
+| `teams delete <team_id> [--force]` | Delete a team. |
+
+### `kctl-litellm budgets` (Teams & Budgets)
+
+Manage LiteLLM budgets.
+
+| Command | Description |
+|---------|-------------|
+| `budgets create [--budget-id] [--max-budget] [--soft-budget] [--tpm-limit] [--rpm-limit]` | Create a new budget with rate limits. |
+| `budgets list` | List all budgets. |
+
+### `kctl-litellm spend` (Usage & Spend)
+
+Track LiteLLM spend and usage.
+
+| Command | Description |
+|---------|-------------|
+| `spend summary` | Show total spend summary aggregated by model. |
+| `spend daily [--start-date] [--end-date]` | Show daily activity (requests, spend, tokens). |
+
+### `kctl-litellm logs` (Usage & Spend)
+
+View LiteLLM request spend logs.
+
+| Command | Description |
+|---------|-------------|
+| `logs list [--limit] [--start-date] [--end-date] [--api-key]` | List spend logs from /global/spend/logs. |
+
+### `kctl-litellm config` (Admin & Config)
+
+Manage CLI configuration and profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config init` | Initialize CLI configuration. |
+| `config show` | Show configuration (keys masked). |
+| `config add` | Add a new profile. |
+| `config use` | Switch default profile. |
+| `config remove` | Remove a profile. |
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-litellm config init       # Interactive setup
+kctl-litellm config show       # Show current config
+kctl-litellm self-update       # Check for updates
+kctl-litellm completions zsh --install  # Install shell completions
+```
+
+**Examples:**
+```bash
+# Check proxy health
+kctl-litellm health check -p kodemeio
+
+# List all available models with pricing
+kctl-litellm models info -p kodemeio
+
+# Generate a virtual key for an app
+kctl-litellm keys generate --key-alias my-app --max-budget 100 --duration 30d -p kodemeio
+
+# Create a team with a budget
+kctl-litellm teams create --team-alias engineering --max-budget 500 -p kodemeio
+
+# View spend breakdown by model
+kctl-litellm spend summary -p kodemeio
+
+# View daily activity for the last 7 days
+kctl-litellm spend daily -p kodemeio
+
+# Browse recent request logs
+kctl-litellm logs list --limit 50 -p kodemeio
+```

kctl_litellm-0.2.0/src/kctl_litellm/__init__.py

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

kctl_litellm-0.2.0/src/kctl_litellm/__main__.py

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

kctl_litellm-0.2.0/src/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-0.2.0/src/kctl_litellm/commands/__init__.py

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

kctl_litellm-0.2.0/src/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)}")