tokenable 1.0.0__py3-none-any.whl

tokenable/__init__.py

@@ -0,0 +1,3 @@
+"""TokEnable — FinOps CLI for LLM API costs."""
+
+__version__ = "1.0.0"

tokenable/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m tokenable`."""
+
+from tokenable.cli import app
+
+app()

tokenable/calibration/__init__.py

@@ -0,0 +1,129 @@
+"""Calibration — fetch real usage data and compute correction factors."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from tokenable.models import CalibrationData, ModelCalibration, Provider
+
+CALIBRATION_DIR = ".tokenable"
+CALIBRATION_FILE = "calibration.json"
+
+
+def _calibration_path(project_root: str) -> Path:
+    return Path(project_root).resolve() / CALIBRATION_DIR / CALIBRATION_FILE
+
+
+def load_calibration(project_root: str | None = None) -> CalibrationData | None:
+    """Load calibration data from .tokenable/calibration.json."""
+    path = _calibration_path(project_root or os.getcwd())
+    if not path.exists():
+        return None
+    try:
+        raw = json.loads(path.read_text())
+        return CalibrationData.model_validate(raw)
+    except Exception:
+        return None
+
+
+def save_calibration(data: CalibrationData, project_root: str | None = None) -> str:
+    """Save calibration data. Returns file path."""
+    path = _calibration_path(project_root or os.getcwd())
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data.model_dump(), indent=2))
+    return str(path)
+
+
+def compute_confidence(sample_size: int) -> str:
+    """Derive confidence from sample size."""
+    if sample_size >= 1000:
+        return "high"
+    if sample_size >= 100:
+        return "medium"
+    return "low"
+
+
+def fetch_and_calibrate(
+    scan_path: str,
+    provider: str | None = None,
+    days: int = 30,
+    dry_run: bool = False,
+    config_path: str | None = None,
+) -> dict[str, Any]:
+    """Fetch usage data from provider APIs and compute calibration factors."""
+    from tokenable.calibration.providers import fetch_all_usage
+    from tokenable.config import load_config
+    from tokenable.estimator import buildEstimateRows, typical_input_tokens, typical_output_tokens
+    from tokenable.providers import get_model
+    from tokenable.scanner import scan_directory
+
+    cfg = load_config(config_path)
+    results = scan_directory(scan_path, cfg.ignore if cfg else [])
+
+    if not results:
+        return {"error": "No LLM API calls found to calibrate."}
+
+    # Get estimated averages per model
+    estimates: dict[str, dict[str, float]] = {}
+    for r in results:
+        if not r.model:
+            continue
+        key = f"{r.provider.value}/{r.model}"
+        if key in estimates:
+            continue
+        pricing = get_model(r.provider, r.model)
+        if pricing:
+            estimates[key] = {
+                "input": typical_input_tokens(pricing),
+                "output": typical_output_tokens(pricing),
+            }
+
+    # Fetch actual usage
+    usage_data = fetch_all_usage(provider=provider, days=days)
+    if not usage_data:
+        return {
+            "error": "No usage data returned. Check API keys (ANTHROPIC_ADMIN_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY)."
+        }
+
+    # Compute calibration
+    models: dict[str, ModelCalibration] = {}
+    for key, actual in usage_data.items():
+        est = estimates.get(key)
+        if not est:
+            continue
+        est_input = est["input"]
+        est_output = est["output"]
+        if est_input == 0 or est_output == 0:
+            continue
+
+        input_ratio = max(0.001, min(100, actual["avg_input"] / est_input))
+        output_ratio = max(0.001, min(100, actual["avg_output"] / est_output))
+
+        models[key] = ModelCalibration(
+            input_ratio=input_ratio,
+            output_ratio=output_ratio,
+            sample_size=actual["request_count"],
+            confidence=compute_confidence(actual["request_count"]),
+            actual_avg_input=actual["avg_input"],
+            actual_avg_output=actual["avg_output"],
+            estimated_avg_input=est_input,
+            estimated_avg_output=est_output,
+        )
+
+    if not models:
+        return {"error": "No matching models found between codebase and usage data."}
+
+    cal_data = CalibrationData(
+        version=1,
+        calibrated_at=datetime.now(UTC).isoformat(),
+        models=models,
+    )
+
+    if not dry_run:
+        save_calibration(cal_data, scan_path)
+
+    return cal_data.model_dump()

tokenable/calibration/providers.py

@@ -0,0 +1,202 @@
+"""Provider usage API clients for calibration."""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC
+from typing import Any
+
+import httpx
+
+
+def _fetch_anthropic_usage(days: int) -> dict[str, dict[str, Any]] | None:
+    """Fetch usage from Anthropic Admin API."""
+    api_key = os.environ.get("ANTHROPIC_ADMIN_API_KEY")
+    if not api_key:
+        return None
+
+    from datetime import datetime, timedelta
+
+    end = datetime.now(UTC)
+    start = end - timedelta(days=days)
+
+    url = "https://api.anthropic.com/v1/organizations/usage_report/messages"
+    params = {
+        "starting_at": start.isoformat(),
+        "ending_at": end.isoformat(),
+        "bucket_width": "1d",
+        "group_by[]": "model",
+    }
+    headers = {"x-api-key": api_key, "anthropic-version": "2023-06-01"}
+
+    results: dict[str, dict[str, Any]] = {}
+    try:
+        with httpx.Client(timeout=30) as client:
+            resp = client.get(url, params=params, headers=headers)
+            resp.raise_for_status()
+            data = resp.json()
+
+            by_model: dict[str, dict[str, int]] = {}
+            for bucket in data.get("data", []):
+                model = bucket.get("model", "unknown")
+                entry = by_model.setdefault(model, {"input": 0, "output": 0, "requests": 0})
+                entry["input"] += bucket.get("input_tokens", 0) + bucket.get(
+                    "cache_read_input_tokens", 0
+                )
+                entry["output"] += bucket.get("output_tokens", 0)
+                entry["requests"] += bucket.get("num_requests", 0)
+
+            for model, agg in by_model.items():
+                if agg["requests"] == 0:
+                    continue
+                results[f"anthropic/{model}"] = {
+                    "avg_input": agg["input"] / agg["requests"],
+                    "avg_output": agg["output"] / agg["requests"],
+                    "request_count": agg["requests"],
+                }
+    except Exception:
+        return None
+    return results or None
+
+
+def _fetch_openai_usage(days: int) -> dict[str, dict[str, Any]] | None:
+    """Fetch usage from OpenAI Organization Usage API."""
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        return None
+
+    import time
+
+    end_time = int(time.time())
+    start_time = end_time - days * 86400
+
+    url = "https://api.openai.com/v1/organization/usage/completions"
+    params = {
+        "start_time": str(start_time),
+        "end_time": str(end_time),
+        "bucket_width": "1d",
+        "group_by[]": "model",
+    }
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    results: dict[str, dict[str, Any]] = {}
+    try:
+        with httpx.Client(timeout=30) as client:
+            resp = client.get(url, params=params, headers=headers)
+            resp.raise_for_status()
+            data = resp.json()
+
+            by_model: dict[str, dict[str, int]] = {}
+            for bucket in data.get("data", []):
+                model = bucket.get("model", "unknown")
+                entry = by_model.setdefault(model, {"input": 0, "output": 0, "requests": 0})
+                entry["input"] += bucket.get("input_tokens", 0) + bucket.get(
+                    "cached_input_tokens", 0
+                )
+                entry["output"] += bucket.get("output_tokens", 0)
+                entry["requests"] += bucket.get("num_model_requests", 0)
+
+            for model, agg in by_model.items():
+                if agg["requests"] == 0:
+                    continue
+                results[f"openai/{model}"] = {
+                    "avg_input": agg["input"] / agg["requests"],
+                    "avg_output": agg["output"] / agg["requests"],
+                    "request_count": agg["requests"],
+                }
+    except Exception:
+        return None
+    return results or None
+
+
+def _fetch_openrouter_usage(days: int) -> dict[str, dict[str, Any]] | None:
+    """Fetch usage from OpenRouter Activity API."""
+    api_key = os.environ.get("OPENROUTER_API_KEY")
+    if not api_key:
+        return None
+
+    from datetime import datetime, timedelta
+
+    PROVIDER_MAP = {
+        "anthropic": "anthropic",
+        "openai": "openai",
+        "google": "google",
+        "google ai studio": "google",
+        "xai": "xai",
+        "perplexity": "perplexity",
+    }
+
+    results: dict[str, dict[str, int]] = {}
+    try:
+        with httpx.Client(timeout=30) as client:
+            now = datetime.now()
+            for i in range(min(days, 30)):
+                date = (now - timedelta(days=i)).strftime("%Y-%m-%d")
+                resp = client.get(
+                    f"https://openrouter.ai/api/v1/activity?date={date}",
+                    headers={"Authorization": f"Bearer {api_key}"},
+                )
+                if not resp.is_success:
+                    continue
+                for record in resp.json().get("data", []):
+                    if record.get("requests", 0) == 0:
+                        continue
+                    prov_name = record.get("provider_name", "").lower()
+                    provider = PROVIDER_MAP.get(prov_name)
+                    if not provider:
+                        continue
+                    raw_model = record.get("model", "")
+                    model = raw_model.split("/", 1)[-1] if "/" in raw_model else raw_model
+                    key = f"{provider}/{model}"
+                    entry = results.setdefault(key, {"input": 0, "output": 0, "requests": 0})
+                    entry["input"] += record.get("prompt_tokens", 0)
+                    entry["output"] += record.get("completion_tokens", 0) + record.get(
+                        "reasoning_tokens", 0
+                    )
+                    entry["requests"] += record.get("requests", 0)
+    except Exception:
+        return None
+
+    final: dict[str, dict[str, Any]] = {}
+    for key, agg in results.items():
+        if agg["requests"] == 0:
+            continue
+        final[key] = {
+            "avg_input": agg["input"] / agg["requests"],
+            "avg_output": agg["output"] / agg["requests"],
+            "request_count": agg["requests"],
+        }
+    return final or None
+
+
+def fetch_all_usage(
+    provider: str | None = None, days: int = 30
+) -> dict[str, dict[str, Any]] | None:
+    """Fetch usage from all available provider APIs. Returns merged results."""
+    all_results: dict[str, dict[str, Any]] = {}
+
+    fetchers = {
+        "anthropic": _fetch_anthropic_usage,
+        "openai": _fetch_openai_usage,
+        "openrouter": _fetch_openrouter_usage,
+    }
+
+    if provider:
+        fetcher = fetchers.get(provider)
+        if fetcher:
+            result = fetcher(days)
+            if result:
+                all_results.update(result)
+    else:
+        for name, fetcher in fetchers.items():
+            result = fetcher(days)
+            if result:
+                # Direct provider APIs take precedence over OpenRouter
+                if name == "openrouter":
+                    for k, v in result.items():
+                        if k not in all_results:
+                            all_results[k] = v
+                else:
+                    all_results.update(result)
+
+    return all_results or None