api-cost-tracker 0.2.0__tar.gz

api_cost_tracker-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+# Dependencies
+node_modules/
+yarn.lock
+package-lock.json
+
+# Build output
+website/dist/
+website/.vercel/
+
+# Scaffolding
+.agent/
+.agentsync/
+.scaffolding-version
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.pyc
+*.db
+*.db-shm
+*.db-wal
+
+# Generated indexes
+00_Index_*.md
+
+# Auto-generated session stub (recreated by /cleanup as needed)
+PROGRESS.md
+
+# uv
+uv.lock
+
+# OS
+.DS_Store
+Thumbs.db
+.vercel
+.env*.local
+.scratch/
+/.claude/

api_cost_tracker-0.2.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.5
+Name: api-cost-tracker
+Version: 0.2.0
+Summary: Lightweight client for the Synth Insight Labs API cost tracker
+Requires-Python: >=3.11

api_cost_tracker-0.2.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "api-cost-tracker"
+version = "0.2.0"
+description = "Lightweight client for the Synth Insight Labs API cost tracker"
+requires-python = ">=3.11"
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/api_cost_tracker"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

api_cost_tracker-0.2.0/src/api_cost_tracker/__init__.py

@@ -0,0 +1,18 @@
+"""
+API Cost Tracker Client — track API spend across all providers and services.
+
+Usage:
+    from api_cost_tracker import track, log_call
+
+    # AI API response tracking
+    resp = client.messages.create(model="claude-haiku-4-5", ...)
+    track(resp, "anthropic", project="ai-memory", caller="classifier")
+
+    # Non-AI API call logging
+    log_call("vercel", service="blob", project="muffinpanrecipes")
+"""
+
+from .tracker import track, track_tokens, log_call
+from .buffer import flush_buffer, pending_count
+
+__all__ = ["track", "track_tokens", "log_call", "flush_buffer", "pending_count"]

api_cost_tracker-0.2.0/src/api_cost_tracker/buffer.py

@@ -0,0 +1,174 @@
+"""
+Local SQLite buffer for offline usage tracking.
+
+When the hosted endpoint is unreachable, usage records are buffered here.
+Call flush_buffer() to retry sending buffered records when connectivity returns.
+"""
+
+import json
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+# Deliberately still the pre-#7830 name: 0.1.x clients that are not upgraded yet
+# keep writing this file, and sharing it is the only way neither version strands
+# rows the other wrote. The schema is unchanged.
+BUFFER_DB_PATH = Path.home() / ".local" / "share" / "api_trust_tracker" / "buffer.db"
+
+
+def _get_buffer_connection(db_path: Optional[Path] = None) -> sqlite3.Connection:
+    """Create a connection to the buffer database."""
+    path = db_path or BUFFER_DB_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path), timeout=5)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=5000")
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS pending_records (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            endpoint TEXT NOT NULL,
+            payload TEXT NOT NULL,
+            created_at TEXT NOT NULL,
+            attempts INTEGER DEFAULT 0,
+            last_attempt TEXT
+        );
+    """)
+    return conn
+
+
+def buffer_record(
+    endpoint: str,
+    payload: dict,
+    db_path: Optional[Path] = None,
+) -> int:
+    """
+    Store a failed POST payload for later retry.
+
+    Args:
+        endpoint: The relative endpoint path (e.g., "/track" or "/log_call").
+        payload: The JSON payload that failed to send.
+        db_path: Override buffer DB path for testing.
+
+    Returns:
+        The buffered record's ID.
+    """
+    conn = _get_buffer_connection(db_path)
+    try:
+        cursor = conn.execute(
+            """INSERT INTO pending_records (endpoint, payload, created_at)
+               VALUES (?, ?, ?)""",
+            (endpoint, json.dumps(payload), datetime.now().isoformat()),
+        )
+        conn.commit()
+        return cursor.lastrowid
+    finally:
+        conn.close()
+
+
+def flush_buffer(
+    base_url: str,
+    api_key: Optional[str] = None,
+    db_path: Optional[Path] = None,
+    max_batch: int = 100,
+) -> dict:
+    """
+    Retry sending buffered records to the hosted endpoint.
+
+    Args:
+        base_url: The base URL (e.g., "https://api.synthinsightlabs.com").
+        api_key: API key for authentication.
+        db_path: Override buffer DB path for testing.
+        max_batch: Maximum records to flush per call.
+
+    Returns:
+        Dict with keys: sent, failed, remaining.
+    """
+    conn = _get_buffer_connection(db_path)
+    sent = 0
+    failed = 0
+
+    try:
+        rows = conn.execute(
+            """SELECT id, endpoint, payload, attempts
+               FROM pending_records
+               ORDER BY created_at ASC
+               LIMIT ?""",
+            (max_batch,),
+        ).fetchall()
+
+        for row in rows:
+            record_id = row["id"]
+            endpoint = row["endpoint"]
+            payload = row["payload"]
+
+            url = f"{base_url.rstrip('/')}{endpoint}"
+            headers = {"Content-Type": "application/json"}
+            if api_key:
+                headers["X-API-Key"] = api_key
+
+            try:
+                req = Request(
+                    url,
+                    data=payload.encode("utf-8"),
+                    headers=headers,
+                    method="POST",
+                )
+                resp = urlopen(req, timeout=10)
+                if resp.status < 300:
+                    conn.execute(
+                        "DELETE FROM pending_records WHERE id = ?",
+                        (record_id,),
+                    )
+                    sent += 1
+                else:
+                    conn.execute(
+                        """UPDATE pending_records
+                           SET attempts = attempts + 1, last_attempt = ?
+                           WHERE id = ?""",
+                        (datetime.now().isoformat(), record_id),
+                    )
+                    failed += 1
+            except (URLError, OSError, TimeoutError):
+                conn.execute(
+                    """UPDATE pending_records
+                       SET attempts = attempts + 1, last_attempt = ?
+                       WHERE id = ?""",
+                    (datetime.now().isoformat(), record_id),
+                )
+                failed += 1
+
+        conn.commit()
+
+        remaining_row = conn.execute(
+            "SELECT COUNT(*) AS cnt FROM pending_records"
+        ).fetchone()
+        remaining = remaining_row["cnt"] if remaining_row else 0
+
+        return {"sent": sent, "failed": failed, "remaining": remaining}
+    finally:
+        conn.close()
+
+
+def pending_count(db_path: Optional[Path] = None) -> int:
+    """Return the number of pending buffered records."""
+    conn = _get_buffer_connection(db_path)
+    try:
+        row = conn.execute("SELECT COUNT(*) AS cnt FROM pending_records").fetchone()
+        return row["cnt"] if row else 0
+    finally:
+        conn.close()
+
+
+def clear_buffer(db_path: Optional[Path] = None) -> int:
+    """Clear all buffered records. Returns count deleted."""
+    conn = _get_buffer_connection(db_path)
+    try:
+        cursor = conn.execute("DELETE FROM pending_records")
+        conn.commit()
+        return cursor.rowcount
+    finally:
+        conn.close()

api_cost_tracker-0.2.0/src/api_cost_tracker/tracker.py

@@ -0,0 +1,345 @@
+"""
+Client-side API cost tracker.
+
+Two public functions:
+    track(response, provider, ...) -- for AI API responses. Extracts tokens, POSTs to server.
+    log_call(provider, service, ...) -- for non-AI API calls. Logs that the call happened.
+
+Both return immediately. Neither raises exceptions -- a tracking failure (or an
+unknown provider) is logged at WARNING with the call's identity, because that
+call's spend was not recorded.
+The API call must always succeed even if tracking fails.
+"""
+
+import json
+import logging
+import os
+import platform
+from datetime import datetime
+from typing import Optional
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from .buffer import buffer_record
+
+_log = logging.getLogger(__name__)
+
+
+# Configurable endpoint
+COST_TRACKER_URL = os.environ.get(
+    "COST_TRACKER_URL", "https://api.synthinsightlabs.com"
+)
+COST_TRACKER_API_KEY = os.environ.get("COST_TRACKER_API_KEY")
+
+# Timeout for POSTs (seconds) -- keep short so tracking doesn't slow down the caller
+_POST_TIMEOUT = 5
+
+
+def _post_to_server(endpoint: str, payload: dict) -> bool:
+    """
+    POST payload to the hosted endpoint.
+    Returns True if successful, False if failed (payload gets buffered).
+    """
+    url = f"{COST_TRACKER_URL.rstrip('/')}{endpoint}"
+    headers = {"Content-Type": "application/json"}
+    if COST_TRACKER_API_KEY:
+        headers["X-API-Key"] = COST_TRACKER_API_KEY
+
+    try:
+        req = Request(
+            url,
+            data=json.dumps(payload).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        resp = urlopen(req, timeout=_POST_TIMEOUT)
+        return resp.status < 300
+    except (URLError, OSError, TimeoutError):  # governance: allow-silent SF002: False is the documented POST-failed result; every caller then writes the payload to the offline buffer via buffer_record for later flush
+        return False
+
+
+def _extract_anthropic(response) -> dict:
+    """Extract token usage from an Anthropic API response."""
+    usage = response.usage
+    return {
+        "model": response.model,
+        "prompt_tokens": usage.input_tokens,
+        "completion_tokens": usage.output_tokens,
+        "cache_read_tokens": getattr(usage, "cache_read_input_tokens", 0) or 0,
+        "cache_creation_tokens": getattr(usage, "cache_creation_input_tokens", 0) or 0,
+    }
+
+
+def _extract_openai(response) -> dict:
+    """
+    Extract token usage from an OpenAI API response.
+    Handles both Chat Completions and Responses API formats.
+    """
+    usage = response.usage
+    model = response.model
+
+    # Chat Completions API
+    if hasattr(usage, "prompt_tokens"):
+        return {
+            "model": model,
+            "prompt_tokens": usage.prompt_tokens,
+            "completion_tokens": usage.completion_tokens,
+            "cache_read_tokens": 0,
+            "cache_creation_tokens": 0,
+        }
+
+    # Responses API
+    return {
+        "model": model,
+        "prompt_tokens": getattr(usage, "input_tokens", 0) or 0,
+        "completion_tokens": getattr(usage, "output_tokens", 0) or 0,
+        "cache_read_tokens": 0,
+        "cache_creation_tokens": 0,
+    }
+
+
+def _extract_google(response, model: Optional[str] = None) -> dict:
+    """Extract token usage from a Google Gemini API response."""
+    meta = response.usage_metadata
+
+    prompt = getattr(meta, "prompt_token_count", 0) or 0
+    completion = getattr(meta, "candidates_token_count", 0) or 0
+
+    resolved_model = model
+    if resolved_model is None:
+        resolved_model = getattr(response, "model_version", None)
+        if resolved_model is None:
+            resolved_model = getattr(response, "model", "unknown")
+
+    return {
+        "model": resolved_model,
+        "prompt_tokens": prompt,
+        "completion_tokens": completion,
+        "cache_read_tokens": 0,
+        "cache_creation_tokens": 0,
+    }
+
+
+def _extract_openrouter(response) -> dict:
+    """
+    Extract token usage and the billed cost from an OpenRouter response.
+
+    OpenRouter's usage object is OpenAI-compatible and also carries ``cost``,
+    "the total amount charged to your account" in USD-denominated credits,
+    returned on every response
+    (https://openrouter.ai/docs/use-cases/usage-accounting). That reported
+    cost is kept as ``reported_cost_usd`` so no registry price is needed for
+    OpenRouter model ids such as ``x-ai/grok-4.3``. A missing or invalid
+    cost yields None.
+    """
+    data = _extract_openai(response)
+    cost = getattr(response.usage, "cost", None)
+    valid = isinstance(cost, (int, float)) and not isinstance(cost, bool) and cost >= 0
+    data["reported_cost_usd"] = float(cost) if valid else None
+    return data
+
+
+_EXTRACTORS = {
+    "anthropic": _extract_anthropic,
+    "openai": _extract_openai,
+    "xai": _extract_openai,  # xAI uses OpenAI-compatible format
+    "openrouter": _extract_openrouter,  # OpenAI-compatible + billed cost
+    "google": _extract_google,
+}
+
+
+def _model_for_warning(response, model: Optional[str]):
+    """Identity for an 'API cost NOT recorded' warning: the explicit model, else response.model."""
+    if model:
+        return model
+    try:
+        return getattr(response, "model", None)
+    except Exception:  # governance: allow-silent SF002: feeds a warning line only; None logs as an unknown model and must never make track() raise
+        return None
+
+
+def track(
+    response,
+    provider: str,
+    *,
+    model: Optional[str] = None,
+    project: Optional[str] = None,
+    caller: Optional[str] = None,
+    service: str = "chat",
+):
+    """
+    Track an AI API response. Extracts tokens, sends to server.
+
+    The response object passes through unchanged -- call this after every API call.
+
+    Usage:
+        resp = client.messages.create(model="claude-haiku-4-5", ...)
+        track(resp, "anthropic", project="ai-memory", caller="classifier")
+
+        resp = openai_client.chat.completions.create(model="gpt-4.1-mini", ...)
+        track(resp, "openai", project="flowfi")
+
+    Args:
+        response: The raw SDK response object.
+        provider: Provider name ("anthropic", "openai", "xai", "openrouter", "google").
+        model: Override model name (extracted from response if not provided).
+        project: Project name for attribution.
+        caller: Identifies the calling code path.
+        service: Service type (default "chat").
+
+    Returns:
+        The original response object, unchanged.
+    """
+    try:
+        provider = provider.lower()
+        extractor = _EXTRACTORS.get(provider)
+        if extractor is None:
+            # Unknown provider: pass the response through, but the spend is not recorded.
+            _log.warning(
+                "API cost NOT recorded: unknown provider %r (model=%r, project=%r, caller=%r)",
+                provider, _model_for_warning(response, model), project, caller,
+            )
+            return response
+
+        # Google extractor needs model hint
+        if provider == "google":
+            usage_data = extractor(response, model=model)
+        else:
+            usage_data = extractor(response)
+
+        # Allow model override
+        if model:
+            usage_data["model"] = model
+
+        resolved_model = usage_data.get("model", "unknown")
+        prompt_tokens = usage_data.get("prompt_tokens", 0)
+        completion_tokens = usage_data.get("completion_tokens", 0)
+        cache_read = usage_data.get("cache_read_tokens", 0)
+        cache_creation = usage_data.get("cache_creation_tokens", 0)
+        total_tokens = prompt_tokens + completion_tokens + cache_read + cache_creation
+
+        payload = {
+            "timestamp": datetime.now().isoformat(),
+            "provider": provider,
+            "model": resolved_model,
+            "service": service,
+            "api_type": "ai",
+            "project": project,
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "cache_read_tokens": cache_read,
+            "cache_creation_tokens": cache_creation,
+            "total_tokens": total_tokens,
+            # Provider-billed cost when reported (OpenRouter usage.cost);
+            # otherwise None and the server calculates it.
+            "estimated_cost_usd": usage_data.get("reported_cost_usd"),
+            "source_machine": platform.node(),
+            "caller": caller,
+        }
+
+        if not _post_to_server("/track", payload):
+            buffer_record("/track", payload)
+
+    except Exception:  # governance: allow-silent SF001: documented never-raise contract (the caller's API call already succeeded and must not fail or be retried); the uncounted call is logged at WARNING with its identity
+        _log.warning(
+            "API cost NOT recorded: track() failed for provider=%r model=%r project=%r caller=%r",
+            provider, _model_for_warning(response, model), project, caller,
+            exc_info=True,
+        )
+
+    return response
+
+
+def track_tokens(
+    provider: str,
+    model: str,
+    prompt_tokens: int,
+    completion_tokens: int,
+    *,
+    cache_read_tokens: int = 0,
+    cache_creation_tokens: int = 0,
+    project: Optional[str] = None,
+    caller: Optional[str] = None,
+    service: str = "chat",
+) -> None:
+    """
+    Track AI API usage by token counts directly (no SDK response object needed).
+
+    Use this when calling provider APIs via raw HTTP instead of their SDK.
+
+    Usage:
+        result = json.loads(resp.read())
+        usage = result["usage"]
+        track_tokens("anthropic", result["model"],
+                     usage["input_tokens"], usage["output_tokens"],
+                     project="ai-memory", caller="brain.classify_scope")
+    """
+    try:
+        total_tokens = prompt_tokens + completion_tokens + cache_read_tokens + cache_creation_tokens
+
+        payload = {
+            "timestamp": datetime.now().isoformat(),
+            "provider": provider.lower(),
+            "model": model,
+            "service": service,
+            "api_type": "ai",
+            "project": project,
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "cache_read_tokens": cache_read_tokens,
+            "cache_creation_tokens": cache_creation_tokens,
+            "total_tokens": total_tokens,
+            "estimated_cost_usd": None,  # Server calculates cost
+            "source_machine": platform.node(),
+            "caller": caller,
+        }
+
+        if not _post_to_server("/track", payload):
+            buffer_record("/track", payload)
+
+    except Exception:  # governance: allow-silent SF001: documented never-raise contract (the caller's API call already succeeded and must not fail or be retried); the uncounted call is logged at WARNING with its identity
+        _log.warning(
+            "API cost NOT recorded: track_tokens() failed for provider=%r model=%r project=%r caller=%r",
+            provider, model, project, caller,
+            exc_info=True,
+        )
+
+
+def log_call(
+    provider: str,
+    *,
+    service: str = "api",
+    project: Optional[str] = None,
+    caller: Optional[str] = None,
+) -> None:
+    """
+    Log a non-AI API call (Vercel, Doppler, RunPod, etc.).
+
+    Usage:
+        log_call("vercel", service="blob", project="muffinpanrecipes", caller="storage.upload")
+
+    Args:
+        provider: Service provider name.
+        service: Specific service/endpoint being called.
+        project: Project name for attribution.
+        caller: Identifies the calling code path.
+    """
+    try:
+        payload = {
+            "timestamp": datetime.now().isoformat(),
+            "provider": provider.lower(),
+            "service": service,
+            "project": project,
+            "caller": caller,
+            "source_machine": platform.node(),
+        }
+
+        if not _post_to_server("/log_call", payload):
+            buffer_record("/log_call", payload)
+
+    except Exception:  # governance: allow-silent SF001: documented never-raise contract (the caller's API call already succeeded and must not fail or be retried); the uncounted call is logged at WARNING with its identity
+        _log.warning(
+            "API call NOT recorded: log_call() failed for provider=%r service=%r project=%r caller=%r",
+            provider, service, project, caller,
+            exc_info=True,
+        )