tokenguard-sdk 0.1.0__tar.gz

tokenguard_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: tokenguard-sdk
+Version: 0.1.0
+Summary: Monitor AI agents, track LLM costs, debug failures — TokenGuard Python SDK
+Author: TokenGuard
+License: MIT
+Project-URL: Homepage, https://github.com/acher112/TokenGuard
+Project-URL: Documentation, https://tokenguard-app-two.vercel.app/docs
+Keywords: ai,llm,monitoring,tracing,openai,anthropic,cost
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
+
+# tokenguard (Python SDK)
+
+**Monitor AI agents, track LLM costs, debug failures — in 2 lines of code.**
+
+## Install
+
+```bash
+pip install tokenguard
+```
+
+## Quick Start — Auto-wrap Groq (zero code change)
+
+```python
+from groq import Groq
+from tokenguard import TokenGuard
+
+aw = TokenGuard(
+    api_key="tg_live_...",           # from your dashboard Settings
+    base_url="http://localhost:3000", # your TokenGuard URL
+)
+
+# Wrap your existing Groq client — ONE LINE
+groq = aw.wrap_groq(Groq(api_key="..."), agent_name="DietAgent")
+
+# Use exactly as before — tracking happens automatically
+response = groq.chat.completions.create(
+    model="llama3-8b-8192",
+    messages=[{"role": "user", "content": "Give me a low-carb meal plan"}],
+)
+
+print(response.choices[0].message.content)
+# → Your dashboard now shows cost, tokens, latency for this call
+```
+
+## Quick Start — Auto-wrap OpenAI
+
+```python
+from openai import OpenAI
+from tokenguard import TokenGuard
+
+aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")
+
+# Wrap your OpenAI client
+openai = aw.wrap_openai(OpenAI(api_key="..."), agent_name="SupportBot")
+
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+## Manual Tracing (full control)
+
+```python
+from tokenguard import TokenGuard
+
+aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")
+
+def get_diet_plan(user_message):
+    with aw.trace("DietSuggestionAgent") as trace:
+
+        # Track the Groq call
+        llm = trace.llm(model="llama3-8b-8192", provider="groq")
+        response = groq_client.chat.completions.create(
+            model="llama3-8b-8192",
+            messages=[{"role": "user", "content": user_message}],
+        )
+        llm.end(
+            input_tokens=response.usage.prompt_tokens,
+            output_tokens=response.usage.completion_tokens,
+        )
+
+        # Track a tool call (optional)
+        tool = trace.tool("nutrition_database_lookup")
+        foods = lookup_foods(user_message)
+        tool.end(result=foods)
+
+        return response.choices[0].message.content
+```
+
+## What appears in your dashboard
+
+Every call shows:
+- 💰 **Cost** — exact cost per request
+- ⏱️ **Latency** — how long it took
+- 🔢 **Tokens** — input and output token counts
+- 🐛 **Errors** — full error details with stack traces
+- 📊 **Agent breakdown** — which agents cost the most
+
+## Supported providers
+
+| Provider | Method | Notes |
+|---|---|---|
+| **Groq** | `aw.wrap_groq(client)` | LLaMA, Mixtral, Gemma |
+| **OpenAI** | `aw.wrap_openai(client)` | GPT-4o, GPT-4o-mini |
+| **Any LLM** | Manual `trace.llm()` | Works with any provider |
+
+## Before you exit your script
+
+```python
+aw.flush()  # makes sure all traces are sent before process ends
+```

tokenguard_sdk-0.1.0/README.md

@@ -0,0 +1,102 @@
+# tokenguard (Python SDK)
+
+**Monitor AI agents, track LLM costs, debug failures — in 2 lines of code.**
+
+## Install
+
+```bash
+pip install tokenguard
+```
+
+## Quick Start — Auto-wrap Groq (zero code change)
+
+```python
+from groq import Groq
+from tokenguard import TokenGuard
+
+aw = TokenGuard(
+    api_key="tg_live_...",           # from your dashboard Settings
+    base_url="http://localhost:3000", # your TokenGuard URL
+)
+
+# Wrap your existing Groq client — ONE LINE
+groq = aw.wrap_groq(Groq(api_key="..."), agent_name="DietAgent")
+
+# Use exactly as before — tracking happens automatically
+response = groq.chat.completions.create(
+    model="llama3-8b-8192",
+    messages=[{"role": "user", "content": "Give me a low-carb meal plan"}],
+)
+
+print(response.choices[0].message.content)
+# → Your dashboard now shows cost, tokens, latency for this call
+```
+
+## Quick Start — Auto-wrap OpenAI
+
+```python
+from openai import OpenAI
+from tokenguard import TokenGuard
+
+aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")
+
+# Wrap your OpenAI client
+openai = aw.wrap_openai(OpenAI(api_key="..."), agent_name="SupportBot")
+
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+## Manual Tracing (full control)
+
+```python
+from tokenguard import TokenGuard
+
+aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")
+
+def get_diet_plan(user_message):
+    with aw.trace("DietSuggestionAgent") as trace:
+
+        # Track the Groq call
+        llm = trace.llm(model="llama3-8b-8192", provider="groq")
+        response = groq_client.chat.completions.create(
+            model="llama3-8b-8192",
+            messages=[{"role": "user", "content": user_message}],
+        )
+        llm.end(
+            input_tokens=response.usage.prompt_tokens,
+            output_tokens=response.usage.completion_tokens,
+        )
+
+        # Track a tool call (optional)
+        tool = trace.tool("nutrition_database_lookup")
+        foods = lookup_foods(user_message)
+        tool.end(result=foods)
+
+        return response.choices[0].message.content
+```
+
+## What appears in your dashboard
+
+Every call shows:
+- 💰 **Cost** — exact cost per request
+- ⏱️ **Latency** — how long it took
+- 🔢 **Tokens** — input and output token counts
+- 🐛 **Errors** — full error details with stack traces
+- 📊 **Agent breakdown** — which agents cost the most
+
+## Supported providers
+
+| Provider | Method | Notes |
+|---|---|---|
+| **Groq** | `aw.wrap_groq(client)` | LLaMA, Mixtral, Gemma |
+| **OpenAI** | `aw.wrap_openai(client)` | GPT-4o, GPT-4o-mini |
+| **Any LLM** | Manual `trace.llm()` | Works with any provider |
+
+## Before you exit your script
+
+```python
+aw.flush()  # makes sure all traces are sent before process ends
+```

tokenguard_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokenguard-sdk"
+version = "0.1.0"
+description = "Monitor AI agents, track LLM costs, debug failures — TokenGuard Python SDK"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "TokenGuard" }]
+requires-python = ">=3.8"
+keywords = ["ai", "llm", "monitoring", "tracing", "openai", "anthropic", "cost"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.18.0"]
+
+[project.urls]
+Homepage = "https://github.com/acher112/TokenGuard"
+Documentation = "https://tokenguard-app-two.vercel.app/docs"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tokenguard*"]

tokenguard_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokenguard_sdk-0.1.0/tokenguard/__init__.py

@@ -0,0 +1,11 @@
+"""
+TokenGuard Python SDK
+Monitor AI agents, track LLM costs, debug failures.
+"""
+
+from .client import TokenGuard, wrap_openai, wrap_groq
+from .trace import TraceContext
+
+__version__ = "0.1.0"
+__all__ = ["TokenGuard", "TraceContext", "wrap_openai", "wrap_groq"]
+

tokenguard_sdk-0.1.0/tokenguard/client.py

@@ -0,0 +1,303 @@
+"""
+TokenGuard Python Client — main entry point.
+
+Usage:
+    from tokenguard import TokenGuard
+
+    aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")
+
+    # Option 1: Auto-wrap OpenAI
+    client = aw.wrap_openai(OpenAI())
+
+    # Option 2: Auto-wrap Groq
+    client = aw.wrap_groq(Groq())
+
+    # Option 3: Manual tracing
+    with aw.trace("my-agent") as trace:
+        llm = trace.llm(model="gpt-4o", provider="openai")
+        response = openai_client.chat.completions.create(...)
+        llm.end(
+            input_tokens=response.usage.prompt_tokens,
+            output_tokens=response.usage.completion_tokens,
+        )
+"""
+from __future__ import annotations
+
+import json
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Generator, Optional
+
+from .transport import Transport
+from .trace import TraceContext
+
+
+def _now_iso() -> str:
+    """Return UTC datetime in Zod-compatible format: 2026-09-15T12:03:19.123Z"""
+    return datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+import os
+
+DEFAULT_BASE_URL = os.environ.get("TOKENGUARD_BASE_URL", "https://tokenguard-app-two.vercel.app")
+
+
+class TokenGuard:
+    """
+    TokenGuard Python SDK client.
+
+    Args:
+        api_key: Your TokenGuard API key (from dashboard or TOKENGUARD_API_KEY env var)
+        base_url: URL of your TokenGuard deployment (default: https://tokenguard-app-two.vercel.app)
+        debug: Print debug logs (default: False)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        debug: bool = False,
+    ):
+        resolved_key = api_key or os.environ.get("TOKENGUARD_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "TokenGuard: api_key is required. Pass api_key='tg_live_...' or set TOKENGUARD_API_KEY in your environment."
+            )
+
+        self._api_key = resolved_key
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._debug = debug
+        self._transport = Transport(
+            api_key=self._api_key,
+            base_url=self._base_url,
+            debug=debug,
+        )
+
+    # ─── Context manager trace ────────────────────────────────────────────────
+
+    @contextmanager
+    def trace(
+        self,
+        agent_name: str,
+        user_id: Optional[str] = None,
+        tags: Optional[list] = None,
+        session_id: Optional[str] = None,
+    ) -> Generator[TraceContext, None, None]:
+        """
+        Context manager that wraps an agent execution in a trace.
+
+        Usage:
+            with aw.trace("diet-agent", session_id="session-abc123") as trace:
+                llm = trace.llm(model="llama3-8b-8192", provider="groq")
+                response = groq.chat.completions.create(...)
+                llm.end(
+                    input_tokens=response.usage.prompt_tokens,
+                    output_tokens=response.usage.completion_tokens,
+                )
+        """
+        ctx = TraceContext()
+        started_at = _now_iso()
+        start_time = time.time()
+
+        try:
+            yield ctx
+        except Exception as e:
+            ctx.error(e)
+            ctx.status = "failed"
+            raise
+        finally:
+            ended_at = _now_iso()
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            payload = {
+                "agentName": agent_name,
+                "status": ctx.status,
+                "startedAt": started_at,
+                "endedAt": ended_at,
+                "durationMs": duration_ms,
+                "steps": ctx.steps,
+            }
+
+            if user_id:
+                payload["userId"] = user_id
+            if tags:
+                payload["tags"] = tags
+            if session_id:
+                payload["sessionId"] = session_id
+
+            self._transport.enqueue(payload)
+
+
+    # ─── OpenAI auto-instrumentation ─────────────────────────────────────────
+
+    def wrap_openai(self, client: Any, agent_name: str = "OpenAIAgent", session_id: Optional[str] = None) -> Any:
+        """
+        Wrap an OpenAI client to automatically track all chat.completions.create calls.
+
+        Usage:
+            from openai import OpenAI
+            client = aw.wrap_openai(OpenAI(), session_id="my-session-123")
+            # All calls now tracked automatically
+            response = client.chat.completions.create(model="gpt-4o", messages=[...])
+        """
+        return _wrap_client(client, self._transport, agent_name, provider="openai", session_id=session_id)
+
+    # ─── Groq auto-instrumentation ────────────────────────────────────────────
+
+    def wrap_groq(self, client: Any, agent_name: str = "GroqAgent", session_id: Optional[str] = None) -> Any:
+        """
+        Wrap a Groq client to automatically track all chat.completions.create calls.
+
+        Usage:
+            from groq import Groq
+            client = aw.wrap_groq(Groq(), session_id="my-session-123")
+            # All calls now tracked automatically
+            response = client.chat.completions.create(model="llama3-8b-8192", messages=[...])
+        """
+        return _wrap_client(client, self._transport, agent_name, provider="groq", session_id=session_id)
+
+
+    # ─── Flush ────────────────────────────────────────────────────────────────
+
+    def flush(self) -> None:
+        """Wait for all pending traces to be sent. Call before your process exits."""
+        self._transport.flush()
+
+
+# ─── Client wrapper (works for both OpenAI and Groq) ─────────────────────────
+
+class _WrappedCompletions:
+    """Wraps the chat.completions object to intercept .create() calls."""
+
+    def __init__(self, original_completions: Any, transport: Transport, agent_name: str, provider: str, session_id: Optional[str] = None):
+        self._completions = original_completions
+        self._transport = transport
+        self._agent_name = agent_name
+        self._provider = provider
+        self._session_id = session_id
+
+    def create(self, **kwargs: Any) -> Any:
+        started_at = _now_iso()
+        start_time = time.time()
+        model = kwargs.get("model", "unknown")
+
+        try:
+            response = self._completions.create(**kwargs)
+            ended_at = _now_iso()
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            # Extract token usage
+            input_tokens = 0
+            output_tokens = 0
+            if hasattr(response, "usage") and response.usage:
+                input_tokens = getattr(response.usage, "prompt_tokens", 0) or 0
+                output_tokens = getattr(response.usage, "completion_tokens", 0) or 0
+
+            # Extract request / response content
+            request_json = None
+            response_json = None
+            try:
+                if "messages" in kwargs:
+                    request_json = json.dumps(kwargs.get("messages", []))
+                if hasattr(response, "choices") and response.choices:
+                    first_choice = response.choices[0]
+                    if hasattr(first_choice, "message") and hasattr(first_choice.message, "content"):
+                        response_json = first_choice.message.content
+            except Exception:
+                pass
+
+            payload = {
+                "agentName": self._agent_name,
+                "status": "success",
+                "startedAt": started_at,
+                "endedAt": ended_at,
+                "durationMs": duration_ms,
+                "steps": [{
+                    "stepType": "llm",
+                    "sequence": 1,
+                    "name": f"{self._provider}/{model}",
+                    "startedAt": started_at,
+                    "endedAt": ended_at,
+                    "durationMs": duration_ms,
+                    "llmCall": {
+                        "modelName": model,
+                        "provider": self._provider,
+                        "inputTokens": input_tokens,
+                        "outputTokens": output_tokens,
+                        "requestJson": request_json,
+                        "responseJson": response_json,
+                    },
+                }],
+            }
+
+            if self._session_id:
+                payload["sessionId"] = self._session_id
+
+            self._transport.enqueue(payload)
+            return response
+
+        except Exception as e:
+            ended_at = _now_iso()
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            payload = {
+                "agentName": self._agent_name,
+                "status": "failed",
+                "startedAt": started_at,
+                "endedAt": ended_at,
+                "durationMs": duration_ms,
+                "steps": [{
+                    "stepType": "error",
+                    "sequence": 1,
+                    "name": "LLM call failed",
+                    "startedAt": started_at,
+                    "endedAt": ended_at,
+                    "durationMs": duration_ms,
+                    "error": {
+                        "errorType": type(e).__name__,
+                        "message": str(e),
+                    },
+                }],
+            }
+
+            if self._session_id:
+                payload["sessionId"] = self._session_id
+
+            self._transport.enqueue(payload)
+            raise
+
+
+class _WrappedChat:
+    def __init__(self, original_chat: Any, transport: Transport, agent_name: str, provider: str, session_id: Optional[str] = None):
+        self.completions = _WrappedCompletions(
+            original_chat.completions, transport, agent_name, provider, session_id=session_id
+        )
+
+
+class _WrappedClient:
+    """Proxy client that intercepts chat.completions.create calls."""
+
+    def __init__(self, original_client: Any, transport: Transport, agent_name: str, provider: str, session_id: Optional[str] = None):
+        self._original = original_client
+        self.chat = _WrappedChat(original_client.chat, transport, agent_name, provider, session_id=session_id)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._original, name)
+
+
+def _wrap_client(client: Any, transport: Transport, agent_name: str, provider: str, session_id: Optional[str] = None) -> Any:
+    return _WrappedClient(client, transport, agent_name, provider, session_id=session_id)
+
+
+def wrap_openai(client: Any, tg: Optional[TokenGuard] = None, agent_name: str = "OpenAIAgent", session_id: Optional[str] = None) -> Any:
+    """Convenience function to wrap an OpenAI client."""
+    guard = tg if tg is not None else TokenGuard()
+    return guard.wrap_openai(client, agent_name=agent_name, session_id=session_id)
+
+
+def wrap_groq(client: Any, tg: Optional[TokenGuard] = None, agent_name: str = "GroqAgent", session_id: Optional[str] = None) -> Any:
+    """Convenience function to wrap a Groq client."""
+    guard = tg if tg is not None else TokenGuard()
+    return guard.wrap_groq(client, agent_name=agent_name, session_id=session_id)
+

tokenguard_sdk-0.1.0/tokenguard/trace.py

@@ -0,0 +1,155 @@
+"""
+TraceContext — holds steps for a single agent trace execution.
+Used as a context manager or directly.
+"""
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+def _now_iso() -> str:
+    """Return UTC datetime in Zod-compatible format: 2026-09-15T12:03:19.123Z"""
+    return datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+class LlmSpan:
+    """Tracks a single LLM call within a trace."""
+
+    def __init__(self, model: str, provider: str, steps: List[Dict], sequence: int):
+        self._model = model
+        self._provider = provider
+        self._steps = steps
+        self._sequence = sequence
+        self._started_at = _now_iso()
+        self._start_time = time.time()
+
+    def end(
+        self,
+        input_tokens: int,
+        output_tokens: int,
+        response: Any = None,
+    ) -> None:
+        duration_ms = int((time.time() - self._start_time) * 1000)
+        self._steps.append({
+            "stepType": "llm",
+            "sequence": self._sequence,
+            "name": f"{self._provider}/{self._model}",
+            "startedAt": self._started_at,
+            "endedAt": _now_iso(),
+            "durationMs": duration_ms,
+            "llmCall": {
+                "modelName": self._model,
+                "provider": self._provider,
+                "inputTokens": input_tokens,
+                "outputTokens": output_tokens,
+            },
+        })
+
+    def fail(self, error: Exception) -> None:
+        duration_ms = int((time.time() - self._start_time) * 1000)
+        self._steps.append({
+            "stepType": "error",
+            "sequence": self._sequence,
+            "name": "LLM call failed",
+            "startedAt": self._started_at,
+            "endedAt": _now_iso(),
+            "durationMs": duration_ms,
+            "error": {
+                "errorType": type(error).__name__,
+                "message": str(error),
+            },
+        })
+
+
+class ToolSpan:
+    """Tracks a single tool/function call within a trace."""
+
+    def __init__(self, name: str, steps: List[Dict], sequence: int):
+        self._name = name
+        self._steps = steps
+        self._sequence = sequence
+        self._started_at = _now_iso()
+        self._start_time = time.time()
+
+    def end(self, result: Any = None) -> None:
+        duration_ms = int((time.time() - self._start_time) * 1000)
+        self._steps.append({
+            "stepType": "tool",
+            "sequence": self._sequence,
+            "name": self._name,
+            "startedAt": self._started_at,
+            "endedAt": _now_iso(),
+            "durationMs": duration_ms,
+            "toolCall": {
+                "toolName": self._name,
+                "status": "success",
+                "resultJson": str(result) if result is not None else None,
+            },
+        })
+
+    def fail(self, error: Exception) -> None:
+        duration_ms = int((time.time() - self._start_time) * 1000)
+        self._steps.append({
+            "stepType": "error",
+            "sequence": self._sequence,
+            "name": f"Tool failed: {self._name}",
+            "startedAt": self._started_at,
+            "endedAt": _now_iso(),
+            "durationMs": duration_ms,
+            "error": {
+                "errorType": type(error).__name__,
+                "message": str(error),
+            },
+        })
+
+
+class TraceContext:
+    """
+    Active trace context. Add LLM calls, tool calls, and errors to it.
+
+    Usage:
+        with aw.trace("my-agent") as trace:
+            llm = trace.llm(model="gpt-4o", provider="openai")
+            response = client.chat.completions.create(...)
+            llm.end(input_tokens=100, output_tokens=50)
+    """
+
+    def __init__(self):
+        self._steps: List[Dict] = []
+        self._sequence = 0
+        self.status = "success"
+
+    def llm(self, model: str, provider: str = "openai") -> LlmSpan:
+        """Start tracking an LLM call."""
+        self._sequence += 1
+        return LlmSpan(model=model, provider=provider, steps=self._steps, sequence=self._sequence)
+
+    def tool(self, name: str) -> ToolSpan:
+        """Start tracking a tool/function call."""
+        self._sequence += 1
+        return ToolSpan(name=name, steps=self._steps, sequence=self._sequence)
+
+    def error(self, error: Exception, wasted_cost_usd: float = 0.0) -> None:
+        """Record an error that occurred during the trace."""
+        self._sequence += 1
+        self._steps.append({
+            "stepType": "error",
+            "sequence": self._sequence,
+            "name": type(error).__name__,
+            "startedAt": _now_iso(),
+            "endedAt": _now_iso(),
+            "durationMs": 0,
+            "error": {
+                "errorType": type(error).__name__,
+                "message": str(error),
+                "wastedCostUsd": str(wasted_cost_usd),
+            },
+        })
+        self.status = "failed"
+
+    @property
+    def steps(self) -> List[Dict]:
+        return self._steps

tokenguard_sdk-0.1.0/tokenguard/transport.py

@@ -0,0 +1,89 @@
+"""
+Transport — sends trace payloads to the TokenGuard ingest API.
+Handles retries, timeouts, and never crashes the host application.
+"""
+from __future__ import annotations
+
+import json
+import time
+import threading
+from typing import Any, Dict, List, Optional
+import requests
+
+
+class Transport:
+    """
+    Thread-safe HTTP transport with buffered queue and retry logic.
+    Sends traces in a background thread so it never blocks the app.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        max_retries: int = 3,
+        retry_delay: float = 0.5,
+        timeout: float = 10.0,
+        debug: bool = False,
+    ):
+        self.api_key = api_key
+        self.ingest_url = base_url.rstrip("/") + "/api/v1/ingest"
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.timeout = timeout
+        self.debug = debug
+
+        self._queue: List[Dict[str, Any]] = []
+        self._lock = threading.Lock()
+
+    def enqueue(self, payload: Dict[str, Any]) -> None:
+        """Add a trace payload to the send queue and dispatch immediately."""
+        with self._lock:
+            self._queue.append(payload)
+
+        # Send in background thread so it never blocks the caller
+        thread = threading.Thread(target=self._send, args=(payload,), daemon=True)
+        thread.start()
+
+    def _send(self, payload: Dict[str, Any]) -> None:
+        """Send a single payload with retries."""
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        for attempt in range(self.max_retries):
+            try:
+                response = requests.post(
+                    self.ingest_url,
+                    json=payload,
+                    headers=headers,
+                    timeout=self.timeout,
+                )
+
+                if response.status_code == 201:
+                    if self.debug:
+                        print(f"[TokenGuard] Trace sent: {response.json().get('traceId')}")
+                    return
+
+                # 4xx errors — don't retry
+                if 400 <= response.status_code < 500:
+                    if self.debug:
+                        print(f"[TokenGuard] Client error {response.status_code}: {response.text}")
+                    return
+
+                # 5xx — retry
+                if self.debug:
+                    print(f"[TokenGuard] Server error {response.status_code}, retrying ({attempt + 1}/{self.max_retries})")
+
+            except requests.exceptions.RequestException as e:
+                if self.debug:
+                    print(f"[TokenGuard] Request failed: {e}, retrying ({attempt + 1}/{self.max_retries})")
+
+            if attempt < self.max_retries - 1:
+                time.sleep(self.retry_delay * (2 ** attempt))
+
+    def flush(self) -> None:
+        """Wait for all background threads to complete (best-effort)."""
+        # Give background threads up to 5 seconds to finish
+        time.sleep(0.5)

tokenguard_sdk-0.1.0/tokenguard_sdk.egg-info/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: tokenguard-sdk
+Version: 0.1.0
+Summary: Monitor AI agents, track LLM costs, debug failures — TokenGuard Python SDK
+Author: TokenGuard
+License: MIT
+Project-URL: Homepage, https://github.com/acher112/TokenGuard
+Project-URL: Documentation, https://tokenguard-app-two.vercel.app/docs
+Keywords: ai,llm,monitoring,tracing,openai,anthropic,cost
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
+
+# tokenguard (Python SDK)
+
+**Monitor AI agents, track LLM costs, debug failures — in 2 lines of code.**
+
+## Install
+
+```bash
+pip install tokenguard
+```
+
+## Quick Start — Auto-wrap Groq (zero code change)
+
+```python
+from groq import Groq
+from tokenguard import TokenGuard
+
+aw = TokenGuard(
+    api_key="tg_live_...",           # from your dashboard Settings
+    base_url="http://localhost:3000", # your TokenGuard URL
+)
+
+# Wrap your existing Groq client — ONE LINE
+groq = aw.wrap_groq(Groq(api_key="..."), agent_name="DietAgent")
+
+# Use exactly as before — tracking happens automatically
+response = groq.chat.completions.create(
+    model="llama3-8b-8192",
+    messages=[{"role": "user", "content": "Give me a low-carb meal plan"}],
+)
+
+print(response.choices[0].message.content)
+# → Your dashboard now shows cost, tokens, latency for this call
+```
+
+## Quick Start — Auto-wrap OpenAI
+
+```python
+from openai import OpenAI
+from tokenguard import TokenGuard
+
+aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")
+
+# Wrap your OpenAI client
+openai = aw.wrap_openai(OpenAI(api_key="..."), agent_name="SupportBot")
+
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+## Manual Tracing (full control)
+
+```python
+from tokenguard import TokenGuard
+
+aw = TokenGuard(api_key="tg_live_...", base_url="http://localhost:3000")
+
+def get_diet_plan(user_message):
+    with aw.trace("DietSuggestionAgent") as trace:
+
+        # Track the Groq call
+        llm = trace.llm(model="llama3-8b-8192", provider="groq")
+        response = groq_client.chat.completions.create(
+            model="llama3-8b-8192",
+            messages=[{"role": "user", "content": user_message}],
+        )
+        llm.end(
+            input_tokens=response.usage.prompt_tokens,
+            output_tokens=response.usage.completion_tokens,
+        )
+
+        # Track a tool call (optional)
+        tool = trace.tool("nutrition_database_lookup")
+        foods = lookup_foods(user_message)
+        tool.end(result=foods)
+
+        return response.choices[0].message.content
+```
+
+## What appears in your dashboard
+
+Every call shows:
+- 💰 **Cost** — exact cost per request
+- ⏱️ **Latency** — how long it took
+- 🔢 **Tokens** — input and output token counts
+- 🐛 **Errors** — full error details with stack traces
+- 📊 **Agent breakdown** — which agents cost the most
+
+## Supported providers
+
+| Provider | Method | Notes |
+|---|---|---|
+| **Groq** | `aw.wrap_groq(client)` | LLaMA, Mixtral, Gemma |
+| **OpenAI** | `aw.wrap_openai(client)` | GPT-4o, GPT-4o-mini |
+| **Any LLM** | Manual `trace.llm()` | Works with any provider |
+
+## Before you exit your script
+
+```python
+aw.flush()  # makes sure all traces are sent before process ends
+```

tokenguard_sdk-0.1.0/tokenguard_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+tokenguard/__init__.py
+tokenguard/client.py
+tokenguard/trace.py
+tokenguard/transport.py
+tokenguard_sdk.egg-info/PKG-INFO
+tokenguard_sdk.egg-info/SOURCES.txt
+tokenguard_sdk.egg-info/dependency_links.txt
+tokenguard_sdk.egg-info/requires.txt
+tokenguard_sdk.egg-info/top_level.txt

tokenguard_sdk-0.1.0/tokenguard_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tokenguard_sdk-0.1.0/tokenguard_sdk.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests>=2.28.0
+
+[anthropic]
+anthropic>=0.18.0
+
+[openai]
+openai>=1.0.0

tokenguard_sdk-0.1.0/tokenguard_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+tokenguard