tokengrip 0.1.0__tar.gz

tokengrip-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+.next/
+out/
+.env
+.env.local
+*.db
+*.db-journal
+prisma/migrations/
+dist/
+.turbo
+coverage/

tokengrip-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: tokengrip
+Version: 0.1.0
+Summary: Track and optimize your AI spending with Tokengrip
+License-Expression: MIT
+Keywords: ai,anthropic,cost,llm,openai,tokengrip,tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tokengrip
+
+Track and optimize your AI spending with [Tokengrip](https://tokengrip.com).
+
+## Installation
+
+```bash
+pip install tokengrip
+```
+
+## Quick Start
+
+```python
+from tokengrip import Tokengrip, wrap_openai
+import openai
+
+tg = Tokengrip(api_key="tq_live_...")
+client = wrap_openai(openai.OpenAI(), tg)
+
+# Usage is automatically tracked
+response = client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+# Don't forget to flush on exit
+tg.shutdown()
+```
+
+## Wrappers
+
+### OpenAI
+
+```python
+from tokengrip import Tokengrip, wrap_openai
+import openai
+
+tg = Tokengrip(api_key="tq_live_...", project_id="my-project")
+client = wrap_openai(openai.OpenAI(), tg)
+
+# Chat Completions API
+response = client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+# Responses API
+response = client.responses.create(
+    model="gpt-4.1",
+    input="Hello!",
+)
+
+# Streaming works too
+stream = client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Hello!"}],
+    stream=True,
+)
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="")
+```
+
+### Anthropic
+
+```python
+from tokengrip import Tokengrip, wrap_anthropic
+import anthropic
+
+tg = Tokengrip(api_key="tq_live_...", project_id="my-project")
+client = wrap_anthropic(anthropic.Anthropic(), tg)
+
+response = client.messages.create(
+    model="claude-sonnet-4-5-20250929",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+### Async Clients
+
+Both sync and async clients are supported transparently:
+
+```python
+import openai
+from tokengrip import Tokengrip, wrap_openai
+
+tg = Tokengrip(api_key="tq_live_...")
+client = wrap_openai(openai.AsyncOpenAI(), tg)
+
+response = await client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+## Options
+
+```python
+tg = Tokengrip(
+    api_key="tq_live_...",       # Required
+    base_url="https://...",       # Default: https://tokengrip.com
+    project_id="my-project",      # Applied to all records
+    agent_name="my-agent",        # Applied to all records
+    debug=True,                   # Log tracking activity
+    batch_size=10,                # Records per batch
+    flush_interval_ms=5000,       # Auto-flush interval
+)
+
+# Wrapper-specific options
+client = wrap_openai(openai.OpenAI(), tg, {
+    "project_id": "override",     # Override per-wrapper
+    "agent_name": "override",
+    "task_type": "summarization",
+    "capture_content": True,      # Capture truncated prompt/response
+})
+```
+
+## Manual Tracking
+
+```python
+tg.track(
+    provider="openai",
+    model="gpt-4.1",
+    inputTokens=500,
+    outputTokens=150,
+    latencyMs=1200,
+    projectId="my-project",
+)
+```

tokengrip-0.1.0/README.md

@@ -0,0 +1,129 @@
+# tokengrip
+
+Track and optimize your AI spending with [Tokengrip](https://tokengrip.com).
+
+## Installation
+
+```bash
+pip install tokengrip
+```
+
+## Quick Start
+
+```python
+from tokengrip import Tokengrip, wrap_openai
+import openai
+
+tg = Tokengrip(api_key="tq_live_...")
+client = wrap_openai(openai.OpenAI(), tg)
+
+# Usage is automatically tracked
+response = client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+# Don't forget to flush on exit
+tg.shutdown()
+```
+
+## Wrappers
+
+### OpenAI
+
+```python
+from tokengrip import Tokengrip, wrap_openai
+import openai
+
+tg = Tokengrip(api_key="tq_live_...", project_id="my-project")
+client = wrap_openai(openai.OpenAI(), tg)
+
+# Chat Completions API
+response = client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+# Responses API
+response = client.responses.create(
+    model="gpt-4.1",
+    input="Hello!",
+)
+
+# Streaming works too
+stream = client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Hello!"}],
+    stream=True,
+)
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="")
+```
+
+### Anthropic
+
+```python
+from tokengrip import Tokengrip, wrap_anthropic
+import anthropic
+
+tg = Tokengrip(api_key="tq_live_...", project_id="my-project")
+client = wrap_anthropic(anthropic.Anthropic(), tg)
+
+response = client.messages.create(
+    model="claude-sonnet-4-5-20250929",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+### Async Clients
+
+Both sync and async clients are supported transparently:
+
+```python
+import openai
+from tokengrip import Tokengrip, wrap_openai
+
+tg = Tokengrip(api_key="tq_live_...")
+client = wrap_openai(openai.AsyncOpenAI(), tg)
+
+response = await client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+## Options
+
+```python
+tg = Tokengrip(
+    api_key="tq_live_...",       # Required
+    base_url="https://...",       # Default: https://tokengrip.com
+    project_id="my-project",      # Applied to all records
+    agent_name="my-agent",        # Applied to all records
+    debug=True,                   # Log tracking activity
+    batch_size=10,                # Records per batch
+    flush_interval_ms=5000,       # Auto-flush interval
+)
+
+# Wrapper-specific options
+client = wrap_openai(openai.OpenAI(), tg, {
+    "project_id": "override",     # Override per-wrapper
+    "agent_name": "override",
+    "task_type": "summarization",
+    "capture_content": True,      # Capture truncated prompt/response
+})
+```
+
+## Manual Tracking
+
+```python
+tg.track(
+    provider="openai",
+    model="gpt-4.1",
+    inputTokens=500,
+    outputTokens=150,
+    latencyMs=1200,
+    projectId="my-project",
+)
+```

tokengrip-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tokengrip"
+version = "0.1.0"
+description = "Track and optimize your AI spending with Tokengrip"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["ai", "llm", "cost", "tracking", "openai", "anthropic", "tokengrip"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tokengrip"]

tokengrip-0.1.0/src/tokengrip/__init__.py

@@ -0,0 +1,26 @@
+"""tokengrip - Track and optimize your AI spending."""
+
+from tokengrip.client import Tokengrip
+from tokengrip.types import TrackUsagePayload, WrapOptions
+
+__all__ = [
+    "Tokengrip",
+    "wrap_openai",
+    "wrap_anthropic",
+    "TrackUsagePayload",
+    "WrapOptions",
+]
+
+
+def wrap_openai(client, tg, opts=None):  # type: ignore[no-untyped-def]
+    """Wrap an OpenAI client to automatically track token usage."""
+    from tokengrip.wrappers.openai import wrap_openai as _wrap
+
+    return _wrap(client, tg, opts)
+
+
+def wrap_anthropic(client, tg, opts=None):  # type: ignore[no-untyped-def]
+    """Wrap an Anthropic client to automatically track token usage."""
+    from tokengrip.wrappers.anthropic import wrap_anthropic as _wrap
+
+    return _wrap(client, tg, opts)

tokengrip-0.1.0/src/tokengrip/client.py

@@ -0,0 +1,204 @@
+"""Core Tokengrip client with batching and auto-flush."""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import threading
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from tokengrip.types import TrackUsagePayload
+
+logger = logging.getLogger("tokengrip")
+
+_SDK_VERSION = "0.1.0"
+
+
+class Tokengrip:
+    """Buffer usage records and send them in batches to the Tokengrip API.
+
+    Example::
+
+        tg = Tokengrip(api_key="tq_live_abc123", project_id="my-project")
+        tg.track(provider="openai", model="gpt-4.1",
+                 inputTokens=500, outputTokens=150)
+        tg.shutdown()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://tokengrip.com",
+        project_id: str = "",
+        agent_name: str = "",
+        debug: bool = False,
+        batch_size: int = 10,
+        flush_interval_ms: int = 5000,
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "Tokengrip: api_key is required. "
+                "Get yours at https://tokengrip.com/settings/api-keys"
+            )
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._project_id = project_id
+        self._agent_name = agent_name
+        self._debug = debug
+        self._batch_size = batch_size
+        self._flush_interval_s = flush_interval_ms / 1000.0
+
+        self._buffer: List[Dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._is_flushing = False
+        self._is_shutdown = False
+
+        self._timer: Optional[threading.Timer] = None
+        if self._flush_interval_s > 0:
+            self._schedule_flush()
+
+        atexit.register(self.shutdown)
+
+    def _schedule_flush(self) -> None:
+        if self._is_shutdown:
+            return
+        self._timer = threading.Timer(self._flush_interval_s, self._periodic_flush)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _periodic_flush(self) -> None:
+        self.flush()
+        self._schedule_flush()
+
+    def track(
+        self,
+        payload: Optional[TrackUsagePayload] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Buffer a single usage record.
+
+        Accepts a ``TrackUsagePayload`` dict, keyword arguments, or both.
+        Never raises — errors are logged at debug level when ``debug=True``.
+        """
+        if self._is_shutdown:
+            self._log("warn", "track() called after shutdown — record dropped")
+            return
+
+        try:
+            record: Dict[str, Any] = dict(payload) if payload else {}
+            record.update(kwargs)
+
+            # Compute totalTokens if absent
+            input_t = record.get("inputTokens", 0)
+            output_t = record.get("outputTokens", 0)
+            if "totalTokens" not in record:
+                record["totalTokens"] = input_t + output_t
+
+            # Apply defaults from config
+            if not record.get("projectId") and self._project_id:
+                record["projectId"] = self._project_id
+            if not record.get("agentName") and self._agent_name:
+                record["agentName"] = self._agent_name
+
+            # Strip falsy optional fields for a clean payload
+            for key in ("projectId", "agentName", "taskType", "metadata"):
+                if key in record and not record[key]:
+                    del record[key]
+            if "latencyMs" in record and record["latencyMs"] is None:
+                del record["latencyMs"]
+
+            with self._lock:
+                self._buffer.append(record)
+                buffer_len = len(self._buffer)
+
+            self._log(
+                "debug",
+                f"Buffered: {record.get('provider')}/{record.get('model')} "
+                f"({input_t}+{output_t} tokens)",
+            )
+
+            if buffer_len >= self._batch_size:
+                self.flush()
+
+        except Exception as e:
+            self._log("warn", f"Failed to buffer record: {e}")
+
+    def flush(self) -> None:
+        """Force-flush all buffered records to the API. Thread-safe."""
+        with self._lock:
+            if not self._buffer or self._is_flushing:
+                return
+            self._is_flushing = True
+            records = self._buffer[:]
+            self._buffer.clear()
+
+        try:
+            self._send_batch(records)
+        except Exception as e:
+            self._log("warn", f"Flush failed: {e}")
+        finally:
+            with self._lock:
+                self._is_flushing = False
+
+    def shutdown(self) -> None:
+        """Flush remaining records and stop the auto-flush timer."""
+        if self._is_shutdown:
+            return
+        self._is_shutdown = True
+
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+        with self._lock:
+            self._is_flushing = False
+
+        self.flush()
+        self._log("debug", "Tokengrip client shut down")
+
+    def _send_batch(self, records: List[Dict[str, Any]]) -> None:
+        if not records:
+            return
+
+        url = f"{self._base_url}/api/v1/track"
+        self._log("debug", f"Sending {len(records)} record(s) to {url}")
+
+        data = json.dumps(records).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self._api_key}",
+                "User-Agent": f"tokengrip-python/{_SDK_VERSION}",
+            },
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                self._log(
+                    "debug", f"Sent {len(records)} record(s), status {resp.status}"
+                )
+        except urllib.error.HTTPError as e:
+            body = ""
+            try:
+                body = e.read().decode("utf-8", errors="replace")
+            except Exception:
+                pass
+            self._log("warn", f"API returned {e.code}: {body}")
+        except Exception as e:
+            self._log("warn", f"Failed to send batch: {e}")
+
+    def _log(self, level: str, message: str) -> None:
+        if not self._debug:
+            return
+        prefix = "[tokengrip]"
+        if level == "warn":
+            logger.warning("%s %s", prefix, message)
+        else:
+            logger.debug("%s %s", prefix, message)

tokengrip-0.1.0/src/tokengrip/types.py

@@ -0,0 +1,39 @@
+"""Type definitions for the Tokengrip SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+try:
+    from typing import TypedDict
+except ImportError:
+    from typing_extensions import TypedDict  # type: ignore[assignment]
+
+
+class TrackUsagePayload(TypedDict, total=False):
+    """Payload sent to the Tokengrip tracking API.
+
+    Field names use camelCase to match the server's Zod schema.
+    """
+
+    provider: str
+    model: str
+    inputTokens: int
+    outputTokens: int
+    totalTokens: int
+    latencyMs: int
+    projectId: str
+    agentName: str
+    taskType: str
+    metadata: Dict[str, Any]
+    promptContent: str
+    responseContent: str
+
+
+class WrapOptions(TypedDict, total=False):
+    """Options for AI client wrappers."""
+
+    project_id: str
+    agent_name: str
+    task_type: str
+    capture_content: bool

tokengrip-0.1.0/src/tokengrip/wrappers/__init__.py

@@ -0,0 +1 @@
+"""AI client wrappers for automatic usage tracking."""