botzone-cost 0.1.0__py3-none-any.whl

botzone_cost/__init__.py

@@ -0,0 +1,6 @@
+"""Cost-tracking SDK for Anthropic, OpenAI, and Gemini clients."""
+
+from ._wrap import wrap, flush
+
+__all__ = ["wrap", "flush"]
+__version__ = "0.1.0"

botzone_cost/_wrap.py

@@ -0,0 +1,201 @@
+"""wrap() entry point. Auto-detects Anthropic / OpenAI / Gemini clients."""
+from __future__ import annotations
+
+import hashlib
+import os
+import time
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from .queue import IngestionQueue
+
+_queues: dict[str, IngestionQueue] = {}
+
+
+def _get_queue(api_key: Optional[str], endpoint: Optional[str], enabled: bool) -> Optional[IngestionQueue]:
+    if not enabled:
+        return None
+    api_key = api_key or os.environ.get("COST_API_KEY")
+    if not api_key:
+        return None
+    endpoint = endpoint or os.environ.get("COST_ENDPOINT", "https://cost.botzone.ai")
+    key = f"{api_key}|{endpoint}"
+    q = _queues.get(key)
+    if not q:
+        q = IngestionQueue(api_key=api_key, endpoint=endpoint)
+        _queues[key] = q
+    return q
+
+
+def _sha256(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def wrap(
+    client: Any,
+    *,
+    api_key: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    route: Optional[str] = None,
+    user_id: Optional[str] = None,
+    feature_tag: Optional[str] = None,
+    enabled: bool = True,
+    capture_bodies: bool = False,
+    provider: Optional[str] = None,
+) -> Any:
+    """Wrap an LLM client to capture cost-tracking events.
+
+    Returns the same client (mutated) for chaining. Raises ValueError if
+    the provider can't be detected.
+
+    The Python SDK is metadata-only today: it ships token counts, model,
+    route, latency, hashed user id, and feature tag. It does not send raw
+    request or response bodies. The ``capture_bodies`` keyword is reserved
+    for future parity with the TypeScript SDK and has no effect today.
+    """
+    queue = _get_queue(api_key, endpoint, enabled)
+    user_hash = _sha256(user_id) if user_id else None
+
+    detected = provider or _detect(client)
+    if detected == "anthropic":
+        return _wrap_anthropic(client, queue, route, user_hash, feature_tag, capture_bodies)
+    if detected == "openai":
+        return _wrap_openai(client, queue, route, user_hash, feature_tag, capture_bodies)
+    if detected == "gemini":
+        return _wrap_gemini(client, queue, route, user_hash, feature_tag, capture_bodies)
+    raise ValueError(
+        "[botzone-cost] could not detect provider: pass provider='anthropic'|'openai'|'gemini'"
+    )
+
+
+def _detect(client: Any) -> Optional[str]:
+    # Prefer module-path detection so auto-mocks don't all look like Anthropic.
+    module = getattr(type(client), "__module__", "") or ""
+    if module.startswith("anthropic"):
+        return "anthropic"
+    if module.startswith("openai"):
+        return "openai"
+    if module.startswith("google.generativeai") or module.startswith("google.genai"):
+        return "gemini"
+    # Fallback duck-typing for thin wrappers that don't carry the module name.
+    if hasattr(client, "messages") and hasattr(client.messages, "create"):
+        return "anthropic"
+    if hasattr(client, "chat") and hasattr(client.chat, "completions"):
+        return "openai"
+    if hasattr(client, "generate_content"):
+        return "gemini"
+    return None
+
+
+def _emit(queue: Optional[IngestionQueue], event: dict) -> None:
+    if queue is not None:
+        queue.enqueue(event)
+
+
+def _wrap_anthropic(client: Any, queue, route, user_hash, feature_tag, capture_bodies):
+    original = client.messages.create
+
+    def wrapped(*args, **kwargs):
+        start = time.time()
+        result = original(*args, **kwargs)
+        latency_ms = int((time.time() - start) * 1000)
+        if queue is not None:
+            usage = getattr(result, "usage", None)
+            input_tokens = getattr(usage, "input_tokens", 0) or 0
+            output_tokens = getattr(usage, "output_tokens", 0) or 0
+            cached = getattr(usage, "cache_read_input_tokens", 0) or 0
+            cache_creation = getattr(usage, "cache_creation_input_tokens", 0) or 0
+            _emit(queue, {
+                "provider": "anthropic",
+                "model": kwargs.get("model") or getattr(result, "model", "unknown"),
+                "promptTokens": input_tokens,
+                "completionTokens": output_tokens,
+                "cachedTokens": cached,
+                "cacheCreationTokens": cache_creation,
+                "latencyMs": latency_ms,
+                "route": route,
+                "userIdHash": user_hash,
+                "featureTag": feature_tag,
+                "occurredAt": _now(),
+            })
+        return result
+
+    client.messages.create = wrapped
+    return client
+
+
+def _wrap_openai(client: Any, queue, route, user_hash, feature_tag, capture_bodies):
+    original = client.chat.completions.create
+
+    def wrapped(*args, **kwargs):
+        start = time.time()
+        result = original(*args, **kwargs)
+        latency_ms = int((time.time() - start) * 1000)
+        if queue is not None:
+            usage = getattr(result, "usage", None)
+            prompt_tokens = getattr(usage, "prompt_tokens", 0) or 0
+            completion_tokens = getattr(usage, "completion_tokens", 0) or 0
+            details = getattr(usage, "prompt_tokens_details", None)
+            cached = getattr(details, "cached_tokens", 0) if details else 0
+            _emit(queue, {
+                "provider": "openai",
+                "model": kwargs.get("model") or getattr(result, "model", "unknown"),
+                "promptTokens": prompt_tokens,
+                "completionTokens": completion_tokens,
+                "cachedTokens": cached or 0,
+                "cacheCreationTokens": 0,
+                "latencyMs": latency_ms,
+                "route": route,
+                "userIdHash": user_hash,
+                "featureTag": feature_tag,
+                "occurredAt": _now(),
+            })
+        return result
+
+    client.chat.completions.create = wrapped
+    return client
+
+
+def _wrap_gemini(model: Any, queue, route, user_hash, feature_tag, capture_bodies):
+    """Wraps a `google.generativeai.GenerativeModel` instance directly."""
+    original = model.generate_content
+    model_name = getattr(model, "model_name", None) or getattr(model, "_model_name", "unknown")
+    if isinstance(model_name, str) and model_name.startswith("models/"):
+        model_name = model_name[len("models/"):]
+
+    def wrapped(*args, **kwargs):
+        start = time.time()
+        result = original(*args, **kwargs)
+        latency_ms = int((time.time() - start) * 1000)
+        if queue is not None:
+            usage = getattr(result, "usage_metadata", None)
+            prompt = getattr(usage, "prompt_token_count", 0) if usage else 0
+            completion = getattr(usage, "candidates_token_count", 0) if usage else 0
+            cached = getattr(usage, "cached_content_token_count", 0) if usage else 0
+            _emit(queue, {
+                "provider": "gemini",
+                "model": model_name,
+                "promptTokens": prompt or 0,
+                "completionTokens": completion or 0,
+                "cachedTokens": cached or 0,
+                "cacheCreationTokens": 0,
+                "latencyMs": latency_ms,
+                "route": route,
+                "userIdHash": user_hash,
+                "featureTag": feature_tag,
+                "occurredAt": _now(),
+            })
+        return result
+
+    model.generate_content = wrapped
+    return model
+
+
+def flush() -> None:
+    """Block until all pending events are sent. Useful in scripts before exit."""
+    for q in _queues.values():
+        q.flush()

botzone_cost/queue.py

@@ -0,0 +1,75 @@
+"""Background ingestion queue.
+
+Fire-and-forget: enqueue() returns immediately. A daemon thread flushes the
+buffer every 2 seconds (and on process exit). Drops events past a 1000-item
+cap rather than leak memory.
+"""
+from __future__ import annotations
+
+import atexit
+import json
+import threading
+import time
+from typing import Optional
+
+import httpx
+
+
+class IngestionQueue:
+    def __init__(self, api_key: str, endpoint: str, *, http: Optional[httpx.Client] = None):
+        self._api_key = api_key
+        self._endpoint = endpoint.rstrip("/")
+        self._buf: list[dict] = []
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._dropped = 0
+        self._http = http or httpx.Client(timeout=5.0)
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+        atexit.register(self._on_exit)
+
+    def enqueue(self, event: dict) -> None:
+        with self._lock:
+            if len(self._buf) >= 1000:
+                self._dropped += 1
+                return
+            self._buf.append(event)
+
+    def flush(self) -> None:
+        with self._lock:
+            batch, self._buf = self._buf, []
+        if not batch:
+            return
+        for chunk_start in range(0, len(batch), 50):
+            chunk = batch[chunk_start : chunk_start + 50]
+            self._send(chunk)
+
+    def dropped_count(self) -> int:
+        return self._dropped
+
+    def _send(self, batch: list[dict], attempt: int = 0) -> None:
+        try:
+            self._http.post(
+                f"{self._endpoint}/api/v1/events",
+                headers={"x-api-key": self._api_key, "content-type": "application/json"},
+                content=json.dumps({"events": batch}),
+            )
+        except Exception:
+            if attempt < 3:
+                time.sleep(0.2 * (2 ** attempt))
+                self._send(batch, attempt + 1)
+
+    def _loop(self) -> None:
+        while not self._stop.is_set():
+            self._stop.wait(2.0)
+            try:
+                self.flush()
+            except Exception:
+                pass
+
+    def _on_exit(self) -> None:
+        self._stop.set()
+        try:
+            self.flush()
+        except Exception:
+            pass

botzone_cost-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: botzone-cost
+Version: 0.1.0
+Summary: Cost-tracking SDK for Anthropic, OpenAI, and Gemini Python clients
+Author-email: Botzone <hello@botzone.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/botzone-ai/cost-sdk-py
+Project-URL: Repository, https://github.com/botzone-ai/cost-sdk-py
+Project-URL: Issues, https://github.com/botzone-ai/cost-sdk-py/issues
+Keywords: llm,cost-tracking,anthropic,openai,gemini
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.5; extra == "gemini"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Dynamic: license-file
+
+# botzone-cost
+
+Cost-tracking SDK for Anthropic, OpenAI, and Gemini Python clients. Wrap your
+existing client; per-call usage flows to your Cost dashboard. Adds zero
+measurable latency to the host call.
+
+## Install
+
+```
+pip install botzone-cost
+```
+
+## Usage
+
+```python
+from anthropic import Anthropic
+from botzone_cost import wrap
+
+client = wrap(Anthropic(), api_key="cost_sk_...", route="follow-up-draft")
+```
+
+Same surface for OpenAI and Gemini:
+
+```python
+from openai import OpenAI
+import google.generativeai as genai
+from botzone_cost import wrap
+
+openai_client = wrap(OpenAI(), route="summariser")
+gemini = wrap(genai.GenerativeModel("gemini-2.5-flash"), route="classifier")
+```
+
+## Options
+
+| arg              | default                                          |
+| ---------------- | ------------------------------------------------ |
+| `api_key`        | env `COST_API_KEY`                               |
+| `endpoint`       | env `COST_ENDPOINT` or `https://cost.botzone.ai` |
+| `route`          | (none: strongly recommended)                     |
+| `user_id`        | (sha256-hashed in the SDK before send)           |
+| `feature_tag`    | (none)                                           |
+| `enabled`        | `True`                                           |
+| `capture_bodies` | `False` (reserved, no effect today, see below)   |
+
+## What gets captured
+
+Token counts (including Anthropic prompt-cache reads / writes and OpenAI cached
+prompt tokens), latency, model, route, user id (hashed), feature tag. Computed
+USD cost is added server-side from the live pricing table. The Python SDK is
+**metadata-only today**: it does not send raw request or response bodies, and
+the `capture_bodies` parameter is reserved for future parity with the
+TypeScript SDK.
+
+End-user identifiers passed via `user_id` are SHA-256 hashed in the SDK before
+send; the plaintext never leaves your process.

botzone_cost-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+botzone_cost/__init__.py,sha256=KJ43Yxr-_P5fwJH8NNrjlkrCsRd8l23h4nizdQMTMOk,150
+botzone_cost/_wrap.py,sha256=MmgKGXo6SRM-cCXqK2C3pDkCIu-l6kpYj1UiwbPr950,7524
+botzone_cost/queue.py,sha256=vDE-uOnjrvm_W7DMh0_YUFla0VbO-Vp1snXMwteYKkU,2236
+botzone_cost-0.1.0.dist-info/licenses/LICENSE,sha256=niCot9KiAWe3mspxoLi9L9j72paHY492FgXLkmkcXJA,1064
+botzone_cost-0.1.0.dist-info/METADATA,sha256=Iiv8YbQsT6OcHRr6_G5F_P06T5H5lXj3wBuGQDAnQ6w,3093
+botzone_cost-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+botzone_cost-0.1.0.dist-info/top_level.txt,sha256=lXZoFY4ON_nsj2cmfAYylZ8bY77FsubrOhOggbhPITY,13
+botzone_cost-0.1.0.dist-info/RECORD,,

botzone_cost-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

botzone_cost-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Botzone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

botzone_cost-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+botzone_cost