eightstatecli 0.4.0__py3-none-any.whl

escli/commands/usage.py

@@ -0,0 +1,428 @@
+"""
+escli usage — view API usage and spend analytics from gate.
+
+Pulls aggregated usage data from the eightstate gate service. Authenticated
+via the CLI token from `escli auth login`.
+
+Usage:
+  escli usage                          Last 30 days summary
+  escli usage --days 7                 Last 7 days summary
+  escli usage --service parallel       Filter to one service
+  escli usage --pricing                Show current pricing rules
+  escli usage --daily                  Day-by-day breakdown
+  escli --json usage                   Structured JSON output
+"""
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+from ..services.credentials import get_cli_token
+
+GATE_URL = os.environ.get("ESCLI_GATE_URL", "https://internal.eightstate.co")
+
+# Box drawing — duplicated from __init__ to keep this module self-contained.
+BOX_H = "─"
+BULLET = "▸"
+DOT = "·"
+CHECK = "✓"
+CROSS = "✗"
+ARROW = "→"
+
+
+# ── HTTP ─────────────────────────────────────────────────────────
+
+def _require_token() -> str:
+    token = get_cli_token()
+    if not token:
+        print(f"  {CROSS} not authenticated", file=sys.stderr)
+        print(f"  {ARROW} run: escli auth login", file=sys.stderr)
+        sys.exit(1)
+    return token
+
+
+def _get(path: str, params: dict | None, token: str, timeout: int = 30) -> dict:
+    import httpx
+
+    try:
+        resp = httpx.get(
+            f"{GATE_URL}{path}",
+            params=params or None,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+    except Exception as e:
+        raise RuntimeError(f"network error: {e}") from e
+
+    if resp.status_code == 401:
+        raise RuntimeError("auth failed (401) — re-run: escli auth login")
+    if resp.status_code == 403:
+        raise RuntimeError("forbidden (403)")
+    if resp.status_code >= 400:
+        try:
+            body = resp.json()
+            msg = body.get("error") or body.get("message") or resp.text
+        except Exception:
+            msg = resp.text
+        raise RuntimeError(f"API error ({resp.status_code}): {msg}")
+
+    try:
+        return resp.json()
+    except Exception as e:
+        raise RuntimeError(f"invalid JSON response: {e}") from e
+
+
+# ── Date helpers ─────────────────────────────────────────────────
+
+def _date_range(days: int) -> tuple[str, str]:
+    end = datetime.now(timezone.utc)
+    start = end - timedelta(days=days)
+    return start.isoformat(), end.isoformat()
+
+
+# ── Formatting ───────────────────────────────────────────────────
+
+def _fmt_money(usd: float | int | None) -> str:
+    if usd is None:
+        return "—"
+    try:
+        v = float(usd)
+    except (TypeError, ValueError):
+        return "—"
+    if v == 0:
+        return "$0.00"
+    if abs(v) < 0.01:
+        return f"${v:.4f}"
+    return f"${v:,.2f}"
+
+
+def _fmt_int(n: int | float | None) -> str:
+    if n is None:
+        return "—"
+    try:
+        return f"{int(n):,}"
+    except (TypeError, ValueError):
+        return str(n)
+
+
+def _print_summary(data: dict, days: int, service: str | None):
+    """Render the summary box."""
+    total_requests = (
+        data.get("total_requests")
+        or data.get("requests")
+        or data.get("total_events")
+        or 0
+    )
+    total_cost = (
+        data.get("total_cost_usd")
+        or data.get("total_cost")
+        or data.get("estimated_cost_usd")
+        or 0.0
+    )
+    by_service = (
+        data.get("by_service")
+        or data.get("services")
+        or []
+    )
+
+    range_start = data.get("start") or data.get("range_start")
+    range_end = data.get("end") or data.get("range_end")
+
+    title = f"  Usage  {DOT}  last {days} day{'s' if days != 1 else ''}"
+    if service:
+        title += f"  {DOT}  service: {service}"
+
+    print()
+    print(title)
+    if range_start and range_end:
+        # Trim ISO microseconds for readability.
+        s = range_start.split(".")[0].replace("T", " ")
+        e = range_end.split(".")[0].replace("T", " ")
+        print(f"  {DOT} {s}  {ARROW}  {e}")
+    print(f"  {BOX_H * 60}")
+    print(f"  {'requests':<24} {_fmt_int(total_requests):>20}")
+    print(f"  {'estimated spend':<24} {_fmt_money(total_cost):>20}")
+
+    if by_service:
+        print()
+        print(f"  {'SERVICE':<16} {'REQUESTS':>12} {'SPEND':>14}")
+        print(f"  {BOX_H * 46}")
+        # by_service may be list[dict] or dict[name -> stats]
+        rows: list[tuple[str, int, float]] = []
+        if isinstance(by_service, dict):
+            for name, stats in by_service.items():
+                rows.append((
+                    name,
+                    int(stats.get("requests") or stats.get("count") or 0),
+                    float(stats.get("cost_usd") or stats.get("cost") or 0.0),
+                ))
+        else:
+            for entry in by_service:
+                name = entry.get("service") or entry.get("name") or "?"
+                rows.append((
+                    name,
+                    int(entry.get("requests") or entry.get("count") or 0),
+                    float(entry.get("cost_usd") or entry.get("cost") or 0.0),
+                ))
+        rows.sort(key=lambda r: r[2], reverse=True)
+        for name, requests, cost in rows:
+            print(f"  {name:<16} {_fmt_int(requests):>12} {_fmt_money(cost):>14}")
+
+    print()
+
+
+def _print_by_service(data: dict, days: int):
+    """Render the by-service breakdown."""
+    services = data.get("services") or data.get("by_service") or []
+
+    print()
+    print(f"  By service  {DOT}  last {days} day{'s' if days != 1 else ''}")
+    print(f"  {BOX_H * 70}")
+    print(f"  {'SERVICE':<14} {'REQUESTS':>10} {'TOKENS IN':>12} {'TOKENS OUT':>12} {'SPEND':>14}")
+    print(f"  {BOX_H * 70}")
+
+    rows = services if isinstance(services, list) else [
+        {"service": k, **(v if isinstance(v, dict) else {})} for k, v in services.items()
+    ]
+
+    for entry in rows:
+        name = entry.get("service") or entry.get("name") or "?"
+        requests = entry.get("requests") or entry.get("count") or 0
+        tokens_in = entry.get("tokens_in") or 0
+        tokens_out = entry.get("tokens_out") or 0
+        cost = entry.get("cost_usd") or entry.get("cost") or 0.0
+        print(
+            f"  {name:<14} {_fmt_int(requests):>10} {_fmt_int(tokens_in):>12} "
+            f"{_fmt_int(tokens_out):>12} {_fmt_money(cost):>14}"
+        )
+
+    print()
+
+
+def _print_by_day(data: dict, days: int, service: str | None):
+    """Render the day-by-day breakdown."""
+    rows = data.get("days") or data.get("by_day") or []
+
+    title = f"  Daily usage  {DOT}  last {days} day{'s' if days != 1 else ''}"
+    if service:
+        title += f"  {DOT}  service: {service}"
+
+    print()
+    print(title)
+    print(f"  {BOX_H * 50}")
+    print(f"  {'DATE':<12} {'REQUESTS':>12} {'SPEND':>14}")
+    print(f"  {BOX_H * 50}")
+
+    total_requests = 0
+    total_cost = 0.0
+    for entry in rows:
+        date = entry.get("date") or entry.get("day") or "?"
+        # Normalize date display
+        if isinstance(date, str) and "T" in date:
+            date = date.split("T")[0]
+        requests = int(entry.get("requests") or entry.get("count") or 0)
+        cost = float(entry.get("cost_usd") or entry.get("cost") or 0.0)
+        total_requests += requests
+        total_cost += cost
+        print(f"  {date:<12} {_fmt_int(requests):>12} {_fmt_money(cost):>14}")
+
+    if rows:
+        print(f"  {BOX_H * 50}")
+        print(f"  {'total':<12} {_fmt_int(total_requests):>12} {_fmt_money(total_cost):>14}")
+    else:
+        print("  (no events in range)")
+
+    print()
+
+
+def _print_pricing(data: dict):
+    """Render pricing rules."""
+    rules = data.get("rules") or data.get("pricing") or data.get("pricing_rules") or []
+
+    print()
+    print(f"  Pricing rules")
+    print(f"  {BOX_H * 70}")
+    print(f"  {'SERVICE':<14} {'SKU':<24} {'UNIT':<14} {'COST/UNIT':>14}")
+    print(f"  {BOX_H * 70}")
+
+    rows = rules if isinstance(rules, list) else []
+    rows.sort(key=lambda r: (r.get("service", ""), r.get("sku", "")))
+
+    for rule in rows:
+        if rule.get("enabled") == 0:
+            continue
+        service = rule.get("service", "?")
+        sku = rule.get("sku", "?")
+        unit = rule.get("unit_label") or rule.get("unit") or ""
+        cost = rule.get("cost_per_unit")
+        if cost is None:
+            cost_str = "—"
+        else:
+            try:
+                f = float(cost)
+                # Pricing often very small; show more decimals
+                cost_str = f"${f:.6f}" if f < 0.01 else f"${f:.4f}"
+            except (TypeError, ValueError):
+                cost_str = str(cost)
+        print(f"  {service:<14} {sku:<24} {unit:<14} {cost_str:>14}")
+
+    if not rows:
+        print("  (no pricing rules configured)")
+
+    print()
+
+
+# ── Commands ─────────────────────────────────────────────────────
+
+def cmd_usage(args):
+    """Show usage analytics."""
+    token = _require_token()
+    days = max(1, int(getattr(args, "days", 30) or 30))
+    service = getattr(args, "service", None)
+
+    # --pricing: fetch and show pricing rules, ignore date range.
+    if getattr(args, "pricing", False):
+        if not args.quiet and not args.json:
+            print(f"  {BULLET} fetching pricing rules...", file=sys.stderr)
+        try:
+            data = _get("/api/analytics/pricing", None, token)
+        except RuntimeError as e:
+            if args.json:
+                print(json.dumps({"success": False, "error": str(e)}))
+            else:
+                print(f"  {CROSS} {e}", file=sys.stderr)
+            return 1
+
+        if args.json:
+            print(json.dumps({"success": True, **data}))
+        else:
+            _print_pricing(data)
+        return 0
+
+    start, end = _date_range(days)
+    params = {"start": start, "end": end}
+    if service:
+        params["service"] = service
+
+    # --daily: day-by-day breakdown
+    if getattr(args, "daily", False):
+        if not args.quiet and not args.json:
+            print(f"  {BULLET} fetching daily breakdown ({days} days)...", file=sys.stderr)
+        try:
+            data = _get("/api/analytics/by-day", params, token)
+        except RuntimeError as e:
+            if args.json:
+                print(json.dumps({"success": False, "error": str(e)}))
+            else:
+                print(f"  {CROSS} {e}", file=sys.stderr)
+            return 1
+
+        if args.json:
+            print(json.dumps({
+                "success": True,
+                "days": days,
+                "service": service,
+                "start": start,
+                "end": end,
+                **data,
+            }))
+        else:
+            _print_by_day(data, days, service)
+        return 0
+
+    # --service (filter without --daily): show by-service detail
+    if service:
+        if not args.quiet and not args.json:
+            print(f"  {BULLET} fetching usage for {service} ({days} days)...", file=sys.stderr)
+        try:
+            data = _get("/api/analytics/by-service", params, token)
+        except RuntimeError as e:
+            if args.json:
+                print(json.dumps({"success": False, "error": str(e)}))
+            else:
+                print(f"  {CROSS} {e}", file=sys.stderr)
+            return 1
+
+        if args.json:
+            print(json.dumps({
+                "success": True,
+                "days": days,
+                "service": service,
+                "start": start,
+                "end": end,
+                **data,
+            }))
+        else:
+            _print_by_service(data, days)
+        return 0
+
+    # Default: summary across all services
+    if not args.quiet and not args.json:
+        print(f"  {BULLET} fetching usage summary ({days} days)...", file=sys.stderr)
+    try:
+        data = _get("/api/analytics/summary", params, token)
+    except RuntimeError as e:
+        if args.json:
+            print(json.dumps({"success": False, "error": str(e)}))
+        else:
+            print(f"  {CROSS} {e}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps({
+            "success": True,
+            "days": days,
+            "start": start,
+            "end": end,
+            **data,
+        }))
+    else:
+        _print_summary(data, days, service)
+    return 0
+
+
+# ── Parser ───────────────────────────────────────────────────────
+
+def register(subparsers):
+    """Register the usage subcommand."""
+    F = argparse.RawDescriptionHelpFormatter
+
+    p = subparsers.add_parser(
+        "usage", aliases=["u"], help="API usage and spend analytics",
+        formatter_class=F,
+        epilog=f"""examples:
+  escli usage                          {DOT} summary, last 30 days
+  escli usage --days 7                 {DOT} last 7 days
+  escli usage --service parallel       {DOT} per-service detail
+  escli usage --daily                  {DOT} day-by-day breakdown
+  escli usage --daily --days 14        {DOT} 14-day daily breakdown
+  escli usage --pricing                {DOT} current pricing rules
+  escli --json usage                   {DOT} structured JSON output
+
+modes (mutually informative):
+  (default)        summary across all services
+  --service NAME   filter to one service (uses /by-service endpoint)
+  --daily          day-by-day breakdown (uses /by-day endpoint)
+  --pricing        list pricing rules (ignores --days and --service)
+
+agent example:
+  escli --json --quiet usage --days 30
+  {ARROW} {{"success": true, "days": 30, "start": "...", "end": "...",
+       "total_requests": 1234, "total_cost_usd": 4.56,
+       "by_service": [...]}}
+
+auth: requires `escli auth login` (uses CLI token, not API key).
+""")
+    p.add_argument("--days", type=int, default=30, metavar="N",
+                   help="Window size in days (default: 30)")
+    p.add_argument("--service", default=None, metavar="NAME",
+                   help="Filter to a single service (e.g. parallel, openai, assemblyai)")
+    p.add_argument("--daily", action="store_true",
+                   help="Show day-by-day breakdown")
+    p.add_argument("--pricing", action="store_true",
+                   help="Show current pricing rules (ignores --days/--service)")
+    p.set_defaults(func=cmd_usage)
+
+    return p

escli/services/credentials.py

@@ -0,0 +1,117 @@
+"""
+Credential service — vends API keys from gate (internal.eightstate.co).
+
+If the user is authenticated via `escli auth login`, keys are fetched from
+the gate service with headroom-aware rotation. Otherwise falls back to
+local env vars or config.
+"""
+
+import json
+import os
+import pathlib
+import sys
+import time
+
+GATE_URL = os.environ.get("ESCLI_GATE_URL", "https://internal.eightstate.co")
+CONFIG_DIR = pathlib.Path(os.environ.get("ESCLI_CONFIG_DIR", pathlib.Path.home() / ".escli"))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def _load_config() -> dict:
+    if CONFIG_FILE.exists():
+        try:
+            return json.loads(CONFIG_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            return {}
+    return {}
+
+
+def get_cli_token() -> str | None:
+    """Get the stored CLI token from config."""
+    cfg = _load_config()
+    profile = cfg.get("active_profile", "default")
+    return cfg.get("profiles", {}).get(profile, {}).get("cli_token")
+
+
+def vend_key(service: str) -> dict | None:
+    """
+    Fetch an API key for a service from gate.
+    Returns {"api_key": str, "fingerprint": str} or None.
+    """
+    token = get_cli_token()
+    if not token:
+        return None
+
+    try:
+        import httpx
+        resp = httpx.post(
+            f"{GATE_URL}/api/keys/vend",
+            json={"service": service},
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            if data.get("success"):
+                return {"api_key": data["api_key"], "fingerprint": data["fingerprint"]}
+    except Exception:
+        pass
+
+    return None
+
+
+def report_key(service: str, fingerprint: str, status: int,
+               remaining: int | None = None, limit: int | None = None,
+               reset: str | None = None, retry_after: int | None = None,
+               tier: str | None = None,
+               tokens_in: int | None = None, tokens_out: int | None = None,
+               audio_seconds: float | None = None,
+               usage_units: float | None = None, usage_sku: str | None = None):
+    """Report rate limit state and usage metadata back to gate."""
+    token = get_cli_token()
+    if not token:
+        return
+
+    try:
+        import httpx
+        httpx.post(
+            f"{GATE_URL}/api/keys/report",
+            json={
+                "service": service,
+                "fingerprint": fingerprint,
+                "status": status,
+                "remaining": remaining,
+                "limit": limit,
+                "reset": reset,
+                "retry_after": retry_after,
+                "tier": tier,
+                "tokens_in": tokens_in,
+                "tokens_out": tokens_out,
+                "audio_seconds": audio_seconds,
+                "usage_units": usage_units,
+                "usage_sku": usage_sku,
+            },
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=5,
+        )
+    except Exception:
+        pass
+
+
+def get_key_for_service(service: str, env_var: str | None = None) -> str | None:
+    """
+    Get an API key for a service. Priority:
+    1. Environment variable (if specified)
+    2. Gate credential vending
+    3. None
+    """
+    if env_var:
+        key = os.environ.get(env_var)
+        if key:
+            return key
+
+    result = vend_key(service)
+    if result:
+        return result["api_key"]
+
+    return None