keymeter 0.1.0__py3-none-any.whl

keymeter/__init__.py

@@ -0,0 +1,3 @@
+"""keymeter: live spend, budget and burn rate for one LiteLLM or OpenRouter API key."""
+
+__version__ = "0.1.0"

keymeter/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from keymeter.cli import main
+
+sys.exit(main())

keymeter/cli.py

@@ -0,0 +1,114 @@
+"""Command line: `keymeter web`, `keymeter tui` and `keymeter json`.
+
+Settings come from the environment, then from a .env file (the current directory's, or --env FILE):
+  KEYMETER_KEY      the API key to watch (required)
+  KEYMETER_URL      gateway base URL (default depends on the gateway)
+  KEYMETER_GATEWAY  auto, litellm or openrouter (default auto)
+"""
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from keymeter import __version__, gateways
+from keymeter.monitor import Monitor
+from keymeter.util import tidy
+
+
+def load_env(path, required):
+    """Minimal .env reader (KEY=VALUE lines); real environment variables win."""
+    if not path.is_file():
+        if required:
+            sys.exit(f"--env file not found: {path}")
+        return
+    raw = path.read_bytes()
+    try:
+        text = raw.decode("utf-16") if raw[:2] in (b"\xff\xfe", b"\xfe\xff") else raw.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        sys.exit(f"can't read {path}: save it as UTF-8")
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+
+
+def build_parser():
+    conn = argparse.ArgumentParser(add_help=False)
+    g = conn.add_argument_group("gateway")
+    g.add_argument("--gateway", choices=["auto", *gateways.GATEWAYS],
+                   help="gateway type (default: $KEYMETER_GATEWAY or auto: openrouter for openrouter.ai URLs "
+                        "and sk-or- keys, litellm otherwise)")
+    g.add_argument("--url", help="gateway base URL (default: $KEYMETER_URL, else http://localhost:4000 for "
+                                 "litellm or https://openrouter.ai/api for openrouter)")
+    g.add_argument("--env", metavar="FILE", help="read settings from this file (default: .env in the current directory)")
+
+    watch = argparse.ArgumentParser(add_help=False)
+    w = watch.add_argument_group("monitoring")
+    w.add_argument("-i", "--interval", type=float, default=15, help="seconds between polls (default 15)")
+    w.add_argument("--window", type=float, default=15, help="burn-rate window in minutes (default 15)")
+    w.add_argument("--warn", type=float, default=0.8, help="warn at this fraction of a budget (default 0.8)")
+    w.add_argument("--crit", type=float, default=0.95, help="critical at this fraction (default 0.95)")
+    w.add_argument("--log", metavar="CSV", help="also append every poll to this CSV file")
+
+    p = argparse.ArgumentParser(
+        prog="keymeter",
+        description="Live spend, budget and burn rate for one LiteLLM or OpenRouter API key.",
+        epilog="The key is read from KEYMETER_KEY (environment or .env). Run `keymeter COMMAND -h` for a command's options.")
+    p.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    web = sub.add_parser("web", parents=[conn, watch], help="browser dashboard",
+                         description="Serve a live dashboard for the key in the browser.")
+    web.add_argument("--host", default="127.0.0.1",
+                     help="address to listen on (default 127.0.0.1, this machine only; 0.0.0.0 = all interfaces, no login)")
+    web.add_argument("--port", type=int, default=8765, help="port (default 8765)")
+
+    tui = sub.add_parser("tui", parents=[conn, watch], help="terminal dashboard",
+                         description="Show a live dashboard for the key in the terminal.")
+    tui.add_argument("--once", action="store_true", help="print one snapshot and exit (exit 1 if not OK)")
+    tui.add_argument("--no-team", action="store_true", help="don't query the team (LiteLLM /team/info)")
+    tui.add_argument("--no-bell", action="store_true", help="don't beep on alerts")
+
+    js = sub.add_parser("json", parents=[conn], help="print one snapshot as JSON and exit",
+                        description="Poll once and print the summary as JSON. Exits 1 if the status is not OK.")
+    js.add_argument("--no-team", action="store_true", help="don't query the team (LiteLLM /team/info)")
+    js.set_defaults(interval=15, window=15, warn=0.8, crit=0.95, log=None)
+    return p
+
+
+def main(argv=None):
+    # write UTF-8 even when output goes to a pipe or file on Windows (Python's default from 3.15 on, PEP 686)
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    args = build_parser().parse_args(argv)
+    args.interval = max(args.interval, 1)
+    if args.env:
+        load_env(Path(args.env), required=True)
+    elif not os.environ.get("KEYMETER_KEY"):
+        # ./.env is only a fallback for the key itself: a .env in whatever directory you are in (a cloned
+        # repo, say) must not point a key from your environment at another server
+        load_env(Path(".env"), required=False)
+    key = os.environ.get("KEYMETER_KEY", "").strip().strip('"')
+    if not key:
+        sys.exit("KEYMETER_KEY is not set. Put it in a .env file in this directory, pass --env FILE, or export it.")
+    name = (args.gateway or os.environ.get("KEYMETER_GATEWAY") or "auto").strip().lower()
+    team = args.command != "web" and not args.no_team  # the web dashboard covers the key only
+    try:
+        gw = gateways.create(name, args.url or os.environ.get("KEYMETER_URL"), key, team=team)
+    except ValueError as e:
+        sys.exit(str(e))
+    mon = Monitor(gw, args)
+
+    if args.command == "json":
+        mon.poll()
+        print(json.dumps(tidy(mon.summary()), indent=2, ensure_ascii=False))
+        return 0 if mon.snap.status == "OK" else 1
+    if args.command == "web":
+        from keymeter import web
+        return web.serve(mon, args)
+    from keymeter import tui
+    return tui.run(mon, args)

keymeter/gateways/__init__.py

@@ -0,0 +1,37 @@
+"""Gateway adapters.
+
+An adapter polls one gateway with the key and returns a Snapshot whose `key` dict uses LiteLLM's
+/key/info field names, so the monitor and both dashboards treat every gateway the same way. Each
+adapter has `name`, `default_url`, `url`, `key`, `fetch() -> Snapshot`, and `features`: the optional
+parts of the dashboard it can fill ("models" = spend per model, "limits" = rate limits and allowed
+models, "team" = team budget and keys).
+"""
+from urllib.parse import urlparse
+
+from keymeter.gateways.base import Snapshot, base_url
+from keymeter.gateways.litellm import LiteLLM
+from keymeter.gateways.openrouter import OpenRouter
+
+GATEWAYS = {"litellm": LiteLLM, "openrouter": OpenRouter}
+
+__all__ = ["GATEWAYS", "LiteLLM", "OpenRouter", "Snapshot", "create", "detect"]
+
+
+def detect(url, key):
+    """Pick a gateway from the URL's host, or from the key's prefix when no URL is set."""
+    if url:
+        host = urlparse(url).hostname or ""
+        return "openrouter" if host == "openrouter.ai" or host.endswith(".openrouter.ai") else "litellm"
+    return "openrouter" if key.startswith("sk-or-") else "litellm"
+
+
+def create(name, url, key, team=True):
+    """Adapter for gateway `name` ("auto", "litellm" or "openrouter"); `url` falls back to its default."""
+    if name == "auto":
+        name = detect(url, key)
+    if name not in GATEWAYS:
+        raise ValueError(f"unknown gateway {name!r}: use auto, {' or '.join(GATEWAYS)}")
+    url = base_url(url or GATEWAYS[name].default_url)
+    if urlparse(url).scheme not in ("http", "https") or not urlparse(url).netloc:
+        raise ValueError(f"the gateway URL must start with http:// or https:// (got {url!r})")
+    return LiteLLM(url, key, team=team) if name == "litellm" else OpenRouter(url, key)

keymeter/gateways/base.py

@@ -0,0 +1,95 @@
+"""What every gateway adapter shares: the snapshot it returns and a small read-only HTTP client."""
+import http.client
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+
+from keymeter import __version__
+
+USER_AGENT = f"keymeter/{__version__}"
+
+
+@dataclass
+class Snapshot:
+    """One poll. `key` and `team` use LiteLLM's /key/info and /team/info field names; other adapters translate into them."""
+    ts: float
+    status: str
+    message: str = ""
+    latency_ms: float = 0.0
+    key: dict = field(default_factory=dict)        # spend, max_budget, budget_reset_at, expires, ...
+    team: dict = field(default_factory=dict)
+    team_keys: list = field(default_factory=list)
+    team_error: str = ""
+    notices: list = field(default_factory=list)    # info lines for the monitor's event log
+
+
+def base_url(url):
+    """Trim a trailing slash and a trailing /v1, so an OpenAI-style base URL works too."""
+    return url.rstrip("/").removesuffix("/v1")
+
+
+def http_get(base, key, path, params=None, timeout=15):
+    """GET a gateway endpoint -> (status, body, latency_ms); status 0 means a network error."""
+    url = base.rstrip("/") + path
+    if params:
+        url += "?" + urllib.parse.urlencode(params)
+    t0 = time.monotonic()
+    try:
+        req = urllib.request.Request(url, headers={
+            "Authorization": f"Bearer {key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        })
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            status, raw = resp.status, resp.read()
+    except urllib.error.HTTPError as e:
+        status, raw = e.code, e.read()
+    except (urllib.error.URLError, http.client.HTTPException, OSError, ValueError) as e:
+        return 0, str(getattr(e, "reason", e)), (time.monotonic() - t0) * 1000
+    latency = (time.monotonic() - t0) * 1000
+    try:
+        return status, json.loads(raw), latency
+    except ValueError:
+        return status, raw.decode("utf-8", "replace").strip()[:300], latency
+
+
+def unwrap(body, inner):
+    """LiteLLM wraps some responses ({"info": {...}}, {"team_info": {...}}); accept both."""
+    if isinstance(body, dict) and isinstance(body.get(inner), dict):
+        return body[inner]
+    return body if isinstance(body, dict) else {}
+
+
+def error_text(body):
+    if isinstance(body, dict):
+        err = body.get("error", body.get("detail", body))
+        if isinstance(err, dict):
+            return str(err.get("message", err))
+        return str(err)
+    return str(body)
+
+
+def classify(status, msg):
+    m = msg.lower()
+    if status == 0:
+        return "OFFLINE"
+    if "blocked" in m:
+        return "BLOCKED"
+    if "budget" in m:
+        return "OVER BUDGET"
+    if "expired" in m:
+        return "EXPIRED"
+    if status == 429:
+        return "RATE LIMITED"
+    if status in (401, 403):
+        return "AUTH ERROR"
+    return f"HTTP {status}"
+
+
+def error_snapshot(status, body, latency_ms):
+    """Snapshot for a poll that returned no key data."""
+    msg = error_text(body) if status else f"network error: {body}"
+    return Snapshot(time.time(), classify(status, msg), msg, latency_ms)

keymeter/gateways/litellm.py

@@ -0,0 +1,42 @@
+"""LiteLLM proxy: GET /key/info for the calling key, plus /team/info when the key is allowed to read it.
+
+Both endpoints are read-only and cost no tokens.
+"""
+import time
+
+from keymeter.gateways.base import Snapshot, error_snapshot, error_text, http_get, unwrap
+
+
+class LiteLLM:
+    name = "litellm"
+    default_url = "http://localhost:4000"
+    features = frozenset({"models", "limits", "team"})
+
+    def __init__(self, url, key, team=True):
+        self.url, self.key = url, key
+        self.team_allowed = team
+        self.key_param = False  # older LiteLLM versions need /key/info?key=...
+
+    def fetch(self):
+        params = {"key": self.key} if self.key_param else None
+        status, body, ms = http_get(self.url, self.key, "/key/info", params)
+        # the key goes into the URL (and so into access logs) only when LiteLLM asks for the parameter
+        if not self.key_param and (status == 422 or (status == 200 and "spend" not in unwrap(body, "info"))):
+            self.key_param = True
+            status, body, ms = http_get(self.url, self.key, "/key/info", {"key": self.key})
+        if status != 200 or not isinstance(body, dict):
+            return error_snapshot(status, body, ms)
+
+        snap = Snapshot(time.time(), "OK", latency_ms=ms, key=unwrap(body, "info"))
+        team_id = snap.key.get("team_id")
+        if team_id and self.team_allowed:
+            ts, tbody, _ = http_get(self.url, self.key, "/team/info", {"team_id": team_id})
+            if ts == 200 and isinstance(tbody, dict):
+                snap.team = unwrap(tbody, "team_info")
+                snap.team_keys = tbody.get("keys") or []
+            else:
+                snap.team_error = f"HTTP {ts}: {error_text(tbody)}"[:160]
+                if ts in (401, 403):
+                    self.team_allowed = False
+                    snap.notices.append("this key can't read /team/info — showing key data only")
+        return snap

keymeter/gateways/openrouter.py

@@ -0,0 +1,57 @@
+"""OpenRouter: GET /api/v1/key, translated into the LiteLLM field names the monitor works with.
+
+OpenRouter reports the key's credit limit, what is left of it and how often it resets (daily, weekly
+or monthly, on UTC boundaries). It has no per-model spend, rate limits or teams.
+"""
+import time
+from datetime import datetime, timedelta, timezone
+
+from keymeter.gateways.base import Snapshot, error_snapshot, http_get
+from keymeter.util import num
+
+PERIODS = {"daily": "day", "weekly": "week", "monthly": "month"}
+
+
+def next_reset(period, now):
+    """Start of the next UTC day, week (Monday) or month after `now`, or None if the limit never resets."""
+    d = datetime.fromtimestamp(now, timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0)
+    if period == "daily":
+        return d + timedelta(days=1)
+    if period == "weekly":
+        return d + timedelta(days=7 - d.weekday())
+    if period == "monthly":
+        return d.replace(year=d.year + d.month // 12, month=d.month % 12 + 1, day=1)
+    return None
+
+
+def translate(d, now):
+    """/api/v1/key "data" -> the key fields the monitor reads."""
+    limit, remaining = num(d.get("limit")), num(d.get("limit_remaining"))
+    reset = next_reset(d.get("limit_reset"), now) if limit is not None else None
+    label = d.get("label") or ""
+    return {
+        # the default label is just the masked key, which the header already shows
+        "key_alias": None if label.startswith("sk-or-") else label or None,
+        # spend that counts against the limit (this period's when the limit resets)
+        "spend": max(limit - remaining, 0.0) if limit is not None and remaining is not None else num(d.get("usage")) or 0.0,
+        "max_budget": limit,
+        "budget_duration": PERIODS.get(d.get("limit_reset")) if limit is not None else None,
+        "budget_reset_at": reset.isoformat() if reset else None,
+        "expires": d.get("expires_at"),
+    }
+
+
+class OpenRouter:
+    name = "openrouter"
+    default_url = "https://openrouter.ai/api"
+    features = frozenset()
+
+    def __init__(self, url, key):
+        self.url, self.key = url, key
+
+    def fetch(self):
+        status, body, ms = http_get(self.url, self.key, "/v1/key")
+        if status != 200 or not isinstance(body, dict) or not isinstance(body.get("data"), dict):
+            return error_snapshot(status, body, ms)
+        now = time.time()
+        return Snapshot(now, "OK", latency_ms=ms, key=translate(body["data"], now))