api-cost-tracker 0.2.0__tar.gz → 0.2.1__tar.gz

api_cost_tracker-0.2.1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: api-cost-tracker
+Version: 0.2.1
+Summary: Lightweight client for the Synth Insight Labs API cost tracker
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# api-cost-tracker
+
+The client for the Synth Insight Labs API cost tracker. It records what every API
+call costs to `https://api.synthinsightlabs.com` without ever breaking the call it
+measures. Standard library only; macOS and Linux.
+
+```python
+from api_cost_tracker import track, track_tokens, log_call
+
+response = client.messages.create(...)          # any provider SDK
+track(response, "anthropic", project="my-project", caller="summarizer")
+
+track_tokens("anthropic", "claude-haiku-4-5", 1200, 300, project="my-project")  # raw HTTP calls
+log_call("vercel", service="blob", project="my-project")                       # non-AI APIs
+```
+
+- **Providers:** `anthropic`, `openai`, `xai`, `google`, `openrouter` (records
+  OpenRouter's billed `usage.cost`).
+- **Never raises.** A record that can't be sent goes to an offline buffer at
+  `~/.local/share/api_trust_tracker/buffer.db`, and each later successful call
+  sends a few buffered rows too. A record that is lost anyway is logged at WARNING.
+- **Configuration:** `COST_TRACKER_API_KEY` (required by the server) and
+  `COST_TRACKER_URL` (default `https://api.synthinsightlabs.com`), from the
+  environment.
+
+Renamed from `api-trust-tracker` in 0.2.0. That package now only re-exports this
+one, and the buffer keeps its old directory so both versions share it.

api_cost_tracker-0.2.1/README.md

@@ -0,0 +1,27 @@
+# api-cost-tracker
+
+The client for the Synth Insight Labs API cost tracker. It records what every API
+call costs to `https://api.synthinsightlabs.com` without ever breaking the call it
+measures. Standard library only; macOS and Linux.
+
+```python
+from api_cost_tracker import track, track_tokens, log_call
+
+response = client.messages.create(...)          # any provider SDK
+track(response, "anthropic", project="my-project", caller="summarizer")
+
+track_tokens("anthropic", "claude-haiku-4-5", 1200, 300, project="my-project")  # raw HTTP calls
+log_call("vercel", service="blob", project="my-project")                       # non-AI APIs
+```
+
+- **Providers:** `anthropic`, `openai`, `xai`, `google`, `openrouter` (records
+  OpenRouter's billed `usage.cost`).
+- **Never raises.** A record that can't be sent goes to an offline buffer at
+  `~/.local/share/api_trust_tracker/buffer.db`, and each later successful call
+  sends a few buffered rows too. A record that is lost anyway is logged at WARNING.
+- **Configuration:** `COST_TRACKER_API_KEY` (required by the server) and
+  `COST_TRACKER_URL` (default `https://api.synthinsightlabs.com`), from the
+  environment.
+
+Renamed from `api-trust-tracker` in 0.2.0. That package now only re-exports this
+one, and the buffer keeps its old directory so both versions share it.

{api_cost_tracker-0.2.0 → api_cost_tracker-0.2.1}/pyproject.toml

@@ -4,8 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "api-cost-tracker"
-version = "0.2.0"
+version = "0.2.1"
 description = "Lightweight client for the Synth Insight Labs API cost tracker"
+readme = "README.md"
 requires-python = ">=3.11"
 dependencies = []
 

api_cost_tracker-0.2.1/src/api_cost_tracker/buffer.py

@@ -0,0 +1,227 @@
+"""
+Local SQLite buffer for offline usage tracking.
+
+When the hosted endpoint is unreachable, usage records are buffered here.
+flush_buffer() sends them once connectivity returns. The tracker calls it with a
+small batch after every successful POST, so a backlog drains on its own; run
+`report.py flush` (or call flush_buffer()) to send a large backlog at once.
+
+One buffer file is shared by every process on the machine. flush_buffer() holds
+an exclusive, non-blocking lock on a sibling `.flush.lock` file while it sends,
+so two flushes never send the same row twice; a flush that finds the lock taken
+returns at once with busy=True, without opening the database. Writers (buffer_record) never take that lock.
+The lock uses fcntl, so the client runs on macOS and Linux only.
+Flushes from clients older than 0.2.1 don't take it either, so run a manual
+flush only from 0.2.1 or later.
+"""
+
+import fcntl
+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, timeout: float = 5) -> sqlite3.Connection:
+    """Create a connection to the buffer database; `timeout` bounds each wait on a lock."""
+    path = db_path or BUFFER_DB_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path), timeout=timeout)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(f"PRAGMA busy_timeout={int(timeout * 1000)}")
+    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,
+    *,
+    stop_on_failure: bool = False,
+    timeout: float = 10,
+    db_timeout: float = 5,
+) -> dict:
+    """
+    Retry sending buffered records to the hosted endpoint.
+
+    Rows go oldest first among those with the fewest attempts, so one row the
+    server keeps rejecting can't hold back the rest. Before each POST the row's
+    attempt is recorded and committed; if the buffer is locked by another writer
+    for longer than db_timeout, that write raises sqlite3.OperationalError and
+    nothing more is sent. After a successful POST the row is deleted and
+    committed before the next one.
+
+    Delivery is at least once. A row is sent twice only if its POST succeeds and
+    its DELETE then fails: the process crashes in between, or another writer
+    holds the buffer longer than db_timeout in that moment. buffer_record()
+    holds it for milliseconds; a flush from a client older than 0.2.1 holds it
+    for its whole run, which is one reason to flush only from 0.2.1 or later.
+
+    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 send in this call.
+        stop_on_failure: Stop at the first failed POST instead of trying the
+            rest of the batch (the tracker's automatic flush uses this, so an
+            unreachable server costs the caller one timeout, not max_batch).
+        timeout: Seconds to wait for each POST.
+        db_timeout: Seconds to wait on the buffer's SQLite lock for each read
+            or write (the tracker's automatic flush uses a short one).
+
+    Returns:
+        Dict with keys: sent, failed, remaining, busy. When another process
+        holds the flush lock, busy is True, nothing was sent and remaining is
+        None (the buffer isn't opened, so this path never waits on SQLite).
+    """
+    path = db_path or BUFFER_DB_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path.with_name(path.name + ".flush.lock"), "a") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            return {"sent": 0, "failed": 0, "remaining": None, "busy": True}
+        try:
+            return _send_batch(path, base_url, api_key, max_batch, stop_on_failure, timeout, db_timeout)
+        finally:
+            fcntl.flock(lock, fcntl.LOCK_UN)
+
+
+def _send_batch(
+    path: Path,
+    base_url: str,
+    api_key: Optional[str],
+    max_batch: int,
+    stop_on_failure: bool,
+    timeout: float,
+    db_timeout: float,
+) -> dict:
+    """Send up to max_batch buffered rows; the caller holds the flush lock."""
+    conn = _get_buffer_connection(path, timeout=db_timeout)
+    sent = 0
+    failed = 0
+
+    try:
+        rows = conn.execute(
+            """SELECT id, endpoint, payload
+               FROM pending_records
+               ORDER BY attempts ASC, id ASC
+               LIMIT ?""",
+            (max_batch,),
+        ).fetchall()
+
+        headers = {"Content-Type": "application/json"}
+        if api_key:
+            headers["X-API-Key"] = api_key
+
+        for row in rows:
+            # Record the attempt before sending: if the buffer is locked this
+            # raises here, before anything goes out, instead of after a POST.
+            conn.execute(
+                """UPDATE pending_records
+                   SET attempts = attempts + 1, last_attempt = ?
+                   WHERE id = ?""",
+                (datetime.now().isoformat(), row["id"]),
+            )
+            conn.commit()
+
+            url = f"{base_url.rstrip('/')}{row['endpoint']}"
+            try:
+                req = Request(
+                    url,
+                    data=row["payload"].encode("utf-8"),
+                    headers=headers,
+                    method="POST",
+                )
+                ok = urlopen(req, timeout=timeout).status < 300
+            except (URLError, OSError, TimeoutError):  # governance: allow-silent SF002: a failed retry is counted in `failed`, the row stays buffered with its attempt already recorded, and the caller reports or logs the result
+                ok = False
+
+            if ok:
+                conn.execute("DELETE FROM pending_records WHERE id = ?", (row["id"],))
+                conn.commit()
+                sent += 1
+                continue
+
+            failed += 1
+            if stop_on_failure:
+                break
+
+        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, "busy": False}
+    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 → api_cost_tracker-0.2.1}/src/api_cost_tracker/tracker.py

@@ -5,22 +5,31 @@ 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.
+Each call POSTs one record, waiting at most a few seconds. 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.
+
+A record whose POST fails goes to the offline buffer (buffer.py). After every
+successful POST the server is known to be reachable, so the tracker also sends
+up to _DRAIN_BATCH buffered rows, stopping at the first failure. A backlog
+therefore drains a few rows per call with no scheduled job.
+
+Timestamps are UTC with an explicit offset. Clients before 0.2.1 sent naive
+local time, which the server stored as UTC (#8152).
 """
 
 import json
 import logging
 import os
 import platform
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Optional
 from urllib.error import URLError
 from urllib.request import Request, urlopen
 
-from .buffer import buffer_record
+from . import buffer as _buffer
+from .buffer import buffer_record, flush_buffer
 
 _log = logging.getLogger(__name__)
 
@@ -34,6 +43,12 @@ 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
 
+# Buffered rows sent after each successful POST
+_DRAIN_BATCH = 5
+
+# Seconds the automatic drain waits on the buffer's SQLite lock before giving up
+_DRAIN_DB_TIMEOUT = 0.5
+
 
 def _post_to_server(endpoint: str, payload: dict) -> bool:
     """
@@ -58,6 +73,37 @@ def _post_to_server(endpoint: str, payload: dict) -> bool:
         return False
 
 
+def _send(endpoint: str, payload: dict) -> None:
+    """POST one record; buffer it on failure, or drain the buffer a little on success."""
+    if _post_to_server(endpoint, payload):
+        _drain_buffer()
+    else:
+        buffer_record(endpoint, payload)
+
+
+def _drain_buffer() -> None:
+    """Send up to _DRAIN_BATCH buffered rows. Never raises; this call's record is already sent."""
+    try:
+        if not _buffer.BUFFER_DB_PATH.exists():  # don't create a buffer just to look in it
+            return
+        result = flush_buffer(
+            COST_TRACKER_URL,
+            api_key=COST_TRACKER_API_KEY,
+            max_batch=_DRAIN_BATCH,
+            stop_on_failure=True,
+            timeout=_POST_TIMEOUT,
+            db_timeout=_DRAIN_DB_TIMEOUT,
+        )
+        if result["failed"]:
+            _log.warning(
+                "Buffered cost rows were not sent this time (a retry POST failed after %d sent); "
+                "%d stay buffered",
+                result["sent"], result["remaining"],
+            )
+    except Exception:  # governance: allow-silent SF001: the caller's own record was already sent; buffered rows stay in the buffer for the next drain, and the failure is logged at WARNING
+        _log.warning("Buffered cost rows were not sent this time; they stay buffered", exc_info=True)
+
+
 def _extract_anthropic(response) -> dict:
     """Extract token usage from an Anthropic API response."""
     usage = response.usage
@@ -131,8 +177,17 @@ def _extract_openrouter(response) -> dict:
     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.
+
+    A response from the Anthropic SDK routed through OpenRouter has
+    Anthropic-shaped usage (``input_tokens``, ``cache_read_input_tokens``, ...)
+    and no ``prompt_tokens``; its cache tokens are read from those fields
+    instead of being dropped (#8053). A Responses-API shape has no Anthropic cache
+    fields, so it still records them as 0.
     """
     data = _extract_openai(response)
+    if not hasattr(response.usage, "prompt_tokens"):
+        data["cache_read_tokens"] = getattr(response.usage, "cache_read_input_tokens", 0) or 0
+        data["cache_creation_tokens"] = getattr(response.usage, "cache_creation_input_tokens", 0) or 0
     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
@@ -219,7 +274,7 @@ def track(
         total_tokens = prompt_tokens + completion_tokens + cache_read + cache_creation
 
         payload = {
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "provider": provider,
             "model": resolved_model,
             "service": service,
@@ -237,8 +292,7 @@ def track(
             "caller": caller,
         }
 
-        if not _post_to_server("/track", payload):
-            buffer_record("/track", payload)
+        _send("/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(
@@ -278,7 +332,7 @@ def track_tokens(
         total_tokens = prompt_tokens + completion_tokens + cache_read_tokens + cache_creation_tokens
 
         payload = {
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "provider": provider.lower(),
             "model": model,
             "service": service,
@@ -294,8 +348,7 @@ def track_tokens(
             "caller": caller,
         }
 
-        if not _post_to_server("/track", payload):
-            buffer_record("/track", payload)
+        _send("/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(
@@ -326,7 +379,7 @@ def log_call(
     """
     try:
         payload = {
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "provider": provider.lower(),
             "service": service,
             "project": project,
@@ -334,8 +387,7 @@ def log_call(
             "source_machine": platform.node(),
         }
 
-        if not _post_to_server("/log_call", payload):
-            buffer_record("/log_call", payload)
+        _send("/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_cost_tracker-0.2.1/tests/conftest.py

@@ -0,0 +1,99 @@
+"""Shared fixtures for the api_cost_tracker client tests."""
+
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+# The package under test, from source (client/src)
+_src_dir = str(Path(__file__).resolve().parent.parent / "src")
+if _src_dir not in sys.path:
+    sys.path.insert(0, _src_dir)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_buffer(monkeypatch, tmp_path):
+    """Keep every test away from the real offline buffer."""
+    import api_cost_tracker.buffer as client_buffer
+
+    monkeypatch.setattr(client_buffer, "BUFFER_DB_PATH", tmp_path / "buffer.db")
+
+
+@pytest.fixture
+def tmp_buffer_db(tmp_path):
+    """Provide a temporary buffer database path."""
+    return tmp_path / "test_buffer.db"
+
+
+@pytest.fixture
+def anthropic_response():
+    """Mock Anthropic API response."""
+    return SimpleNamespace(
+        model="claude-haiku-4-5",
+        usage=SimpleNamespace(
+            input_tokens=150,
+            output_tokens=50,
+            cache_read_input_tokens=20,
+            cache_creation_input_tokens=10,
+        ),
+        content=[SimpleNamespace(type="text", text="Hello world")],
+    )
+
+
+@pytest.fixture
+def openai_chat_response():
+    """Mock OpenAI Chat Completions API response."""
+    return SimpleNamespace(
+        model="gpt-4.1-mini",
+        usage=SimpleNamespace(
+            prompt_tokens=200,
+            completion_tokens=80,
+            total_tokens=280,
+        ),
+        choices=[SimpleNamespace(
+            message=SimpleNamespace(content="Hello world"),
+        )],
+    )
+
+
+@pytest.fixture
+def openai_responses_api():
+    """Mock OpenAI Responses API response."""
+    return SimpleNamespace(
+        model="gpt-4.1-mini",
+        usage=SimpleNamespace(
+            input_tokens=200,
+            output_tokens=80,
+        ),
+        output=[SimpleNamespace(type="message", content="Hello")],
+    )
+
+
+@pytest.fixture
+def google_response():
+    """Mock Google Gemini API response."""
+    return SimpleNamespace(
+        usage_metadata=SimpleNamespace(
+            prompt_token_count=300,
+            candidates_token_count=100,
+            total_token_count=400,
+        ),
+        model_version="gemini-2.5-flash",
+        text="Hello world",
+    )
+
+
+@pytest.fixture
+def mock_server_post():
+    """Patch _post_to_server to prevent real HTTP calls in tracker tests."""
+    with patch("api_cost_tracker.tracker._post_to_server", return_value=True) as mock:
+        yield mock
+
+
+@pytest.fixture
+def mock_server_post_fail():
+    """Patch _post_to_server to simulate server failure."""
+    with patch("api_cost_tracker.tracker._post_to_server", return_value=False) as mock:
+        yield mock