api-trust-tracker 0.1.0__tar.gz

api_trust_tracker-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# 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
+
+# Generated indexes
+00_Index_*.md
+
+# uv
+uv.lock
+
+# OS
+.DS_Store
+Thumbs.db
+.vercel
+.env*.local

api_trust_tracker-0.1.0/PKG-INFO

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

api_trust_tracker-0.1.0/pyproject.toml

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

api_trust_tracker-0.1.0/src/api_trust_tracker/__init__.py

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

api_trust_tracker-0.1.0/src/api_trust_tracker/buffer.py

@@ -0,0 +1,171 @@
+"""
+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
+
+BUFFER_DB_PATH = Path.home() / ".local" / "share" / "ai_cost_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/costs").
+        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_trust_tracker-0.1.0/src/api_trust_tracker/tracker.py

@@ -0,0 +1,242 @@
+"""
+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 -- tracking failures are silent.
+The API call must always succeed even if tracking fails.
+"""
+
+import json
+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
+
+
+# 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):
+        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,
+    }
+
+
+_EXTRACTORS = {
+    "anthropic": _extract_anthropic,
+    "openai": _extract_openai,
+    "xai": _extract_openai,  # xAI uses OpenAI-compatible format
+    "google": _extract_google,
+}
+
+
+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="open-brain", 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", "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:
+            return response  # Unknown provider, pass through silently
+
+        # 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,
+            "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:
+        # Never let tracking break the caller
+        pass
+
+    return response
+
+
+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:
+        # Never let tracking break the caller
+        pass