spendline 0.1.0__tar.gz

spendline-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spendline
+
+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.

spendline-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: spendline
+Version: 0.1.0
+Summary: Track LLM tokens, cost, latency, and model usage in production.
+License: MIT
+License-File: LICENSE
+Keywords: llm,ai,openai,anthropic,bedrock,observability,cost-tracking
+Author: Spendline
+Author-email: hello@spendline.dev
+Requires-Python: >=3.8
+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.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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: httpx (>=0.24)
+Requires-Dist: requests (>=2.28)
+Project-URL: Documentation, https://github.com/emartai/spendline/tree/main/doc
+Project-URL: Homepage, https://github.com/emartai/spendline
+Project-URL: Issues, https://github.com/emartai/spendline/issues
+Project-URL: Repository, https://github.com/emartai/spendline
+Description-Content-Type: text/markdown
+
+# Spendline Python SDK
+
+Spendline tracks LLM usage in production with one line of code. The SDK captures tokens, model, latency, cost, timestamp, workflow ID, and request metadata without collecting prompt or completion text.
+
+## Install
+
+```bash
+pip install spendline
+```
+
+## Quick Start
+
+```python
+from openai import OpenAI
+from spendline import track
+
+client = OpenAI()
+
+response = track(
+    client.chat.completions.create(
+        model="gpt-5-mini",
+        messages=[{"role": "user", "content": "Say hello"}],
+    ),
+    workflow_id="support-bot",
+    session_id="session-123",
+    metadata={"feature": "chat", "environment": "production"},
+)
+
+print(response.choices[0].message.content)
+```
+
+## Auto-Patch Supported Clients
+
+```python
+from spendline import patch
+
+patch()
+```
+
+## LangChain
+
+```python
+from spendline.langchain import SpendlineCallbackHandler
+
+handler = SpendlineCallbackHandler(workflow_id="chatbot")
+```
+
+## Supported Providers
+
+| Provider | Support |
+| --- | --- |
+| OpenAI | `track()` and `patch()` |
+| Anthropic | `track()` and `patch()` |
+| Google Gemini | `track()` |
+| DeepSeek | `track()` |
+| Bedrock | `track()` |
+
+## Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `SPENDLINE_API_KEY` | Default ingest key |
+| `SPENDLINE_API_URL` | Override API base URL |
+| `SPENDLINE_DISABLE` | Disable tracking when `true` |
+| `SPENDLINE_LOG` | Print tracked events locally |
+
+## Privacy
+
+Spendline does not collect:
+
+- Prompt text
+- Completion text
+- Raw request bodies
+- Secrets from your application context
+

spendline-0.1.0/README.md

@@ -0,0 +1,74 @@
+# Spendline Python SDK
+
+Spendline tracks LLM usage in production with one line of code. The SDK captures tokens, model, latency, cost, timestamp, workflow ID, and request metadata without collecting prompt or completion text.
+
+## Install
+
+```bash
+pip install spendline
+```
+
+## Quick Start
+
+```python
+from openai import OpenAI
+from spendline import track
+
+client = OpenAI()
+
+response = track(
+    client.chat.completions.create(
+        model="gpt-5-mini",
+        messages=[{"role": "user", "content": "Say hello"}],
+    ),
+    workflow_id="support-bot",
+    session_id="session-123",
+    metadata={"feature": "chat", "environment": "production"},
+)
+
+print(response.choices[0].message.content)
+```
+
+## Auto-Patch Supported Clients
+
+```python
+from spendline import patch
+
+patch()
+```
+
+## LangChain
+
+```python
+from spendline.langchain import SpendlineCallbackHandler
+
+handler = SpendlineCallbackHandler(workflow_id="chatbot")
+```
+
+## Supported Providers
+
+| Provider | Support |
+| --- | --- |
+| OpenAI | `track()` and `patch()` |
+| Anthropic | `track()` and `patch()` |
+| Google Gemini | `track()` |
+| DeepSeek | `track()` |
+| Bedrock | `track()` |
+
+## Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `SPENDLINE_API_KEY` | Default ingest key |
+| `SPENDLINE_API_URL` | Override API base URL |
+| `SPENDLINE_DISABLE` | Disable tracking when `true` |
+| `SPENDLINE_LOG` | Print tracked events locally |
+
+## Privacy
+
+Spendline does not collect:
+
+- Prompt text
+- Completion text
+- Raw request bodies
+- Secrets from your application context

spendline-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["poetry-core>=1.8.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "spendline"
+version = "0.1.0"
+description = "Track LLM tokens, cost, latency, and model usage in production."
+authors = ["Spendline <hello@spendline.dev>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "spendline" }]
+keywords = ["llm", "ai", "openai", "anthropic", "bedrock", "observability", "cost-tracking"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "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 :: Python Modules",
+]
+include = ["LICENSE"]
+
+[tool.poetry.dependencies]
+python = ">=3.8"
+requests = ">=2.28"
+httpx = ">=0.24"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+pytest-mock = ">=3.0"
+responses = ">=0.25"
+pytest-asyncio = ">=0.23"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.poetry.urls]
+Homepage = "https://github.com/emartai/spendline"
+Repository = "https://github.com/emartai/spendline"
+Documentation = "https://github.com/emartai/spendline/tree/main/doc"
+Issues = "https://github.com/emartai/spendline/issues"

spendline-0.1.0/spendline/__init__.py

@@ -0,0 +1,7 @@
+"""Spendline Python SDK."""
+
+from .autopatch import patch
+from .client import Spendline
+from .track import track
+
+__all__ = ["Spendline", "patch", "track"]

spendline-0.1.0/spendline/autopatch.py

@@ -0,0 +1,107 @@
+"""Automatic provider patching for Spendline."""
+
+import os
+import time
+import warnings
+from functools import wraps
+
+from .track import _record_response
+
+_MARKER_ATTR = "__spendline_patched__"
+
+
+def _tracking_disabled() -> bool:
+    return os.getenv("SPENDLINE_DISABLE", "").lower() == "true"
+
+
+def _warn_missing_api_key():
+    if not os.getenv("SPENDLINE_API_KEY"):
+        warnings.warn(
+            "SPENDLINE_API_KEY is not set; spendline.patch() will not send tracking data.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
+
+def _patch_sync_method(target, attr_name):
+    original = getattr(target, attr_name, None)
+    if original is None or getattr(original, _MARKER_ATTR, False):
+        return False
+
+    @wraps(original)
+    def wrapped(*args, **kwargs):
+        started_at = time.perf_counter()
+        response = original(*args, **kwargs)
+        try:
+            _record_response(response, started_at=started_at)
+        except Exception:
+            pass
+        return response
+
+    setattr(wrapped, _MARKER_ATTR, True)
+    setattr(target, attr_name, wrapped)
+    return True
+
+
+def _patch_async_method(target, attr_name):
+    original = getattr(target, attr_name, None)
+    if original is None or getattr(original, _MARKER_ATTR, False):
+        return False
+
+    @wraps(original)
+    async def wrapped(*args, **kwargs):
+        started_at = time.perf_counter()
+        response = await original(*args, **kwargs)
+        try:
+            _record_response(response, started_at=started_at)
+        except Exception:
+            pass
+        return response
+
+    setattr(wrapped, _MARKER_ATTR, True)
+    setattr(target, attr_name, wrapped)
+    return True
+
+
+def _patch_openai():
+    try:
+        import openai
+    except ImportError:
+        return False
+
+    patched = False
+
+    chat = getattr(openai, "chat", None)
+    completions = getattr(chat, "completions", None) if chat is not None else None
+    if completions is not None:
+        patched = _patch_sync_method(completions, "create") or patched
+        patched = _patch_async_method(completions, "acreate") or patched
+
+    return patched
+
+
+def _patch_anthropic():
+    try:
+        import anthropic
+    except ImportError:
+        return False
+
+    patched = False
+    messages = getattr(anthropic, "messages", None)
+    if messages is not None:
+        patched = _patch_sync_method(messages, "create") or patched
+        patched = _patch_sync_method(messages, "stream") or patched
+
+    return patched
+
+
+def patch():
+    """Patches supported provider SDK entrypoints in place."""
+
+    if _tracking_disabled():
+        return None
+
+    _warn_missing_api_key()
+    _patch_openai()
+    _patch_anthropic()
+    return None

spendline-0.1.0/spendline/batch.py

@@ -0,0 +1,53 @@
+"""Batch sending for Spendline ingest events."""
+
+import threading
+
+
+class BatchBuffer:
+    """Buffers ingest events and flushes them asynchronously."""
+
+    def __init__(self, api_key: str, api_url: str, max_size=100, flush_interval=2.0):
+        self.api_key = api_key
+        self.api_url = api_url.rstrip("/")
+        self.max_size = max_size
+        self.flush_interval = flush_interval
+        self._buffer = []
+        self._lock = threading.Lock()
+        self._timer = None
+        self._start_timer()
+
+    def add(self, event: dict):
+        with self._lock:
+            self._buffer.append(event)
+            if len(self._buffer) >= self.max_size:
+                self._flush_locked()
+
+    def _start_timer(self):
+        self._timer = threading.Timer(self.flush_interval, self._flush_and_restart)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _flush_and_restart(self):
+        with self._lock:
+            self._flush_locked()
+        self._start_timer()
+
+    def _flush_locked(self):
+        if not self._buffer:
+            return
+        events = self._buffer[:]
+        self._buffer = []
+        threading.Thread(target=self._send, args=(events,), daemon=True).start()
+
+    def _send(self, events: list):
+        try:
+            import requests as http
+
+            http.post(
+                f"{self.api_url}/v1/ingest",
+                json=events,
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=5,
+            )
+        except Exception:
+            pass

spendline-0.1.0/spendline/client.py

@@ -0,0 +1,50 @@
+"""Client helpers for the Spendline SDK."""
+
+import os
+import threading
+
+from .batch import BatchBuffer
+
+DEFAULT_API_URL = os.getenv("SPENDLINE_API_URL", "https://api.spendline.dev")
+
+_clients = {}
+_clients_lock = threading.Lock()
+
+
+class Spendline:
+    """Small SDK client that owns a shared batch buffer."""
+
+    def __init__(self, api_key=None, api_url=None):
+        self.api_key = api_key or os.getenv("SPENDLINE_API_KEY")
+        self.api_url = (api_url or os.getenv("SPENDLINE_API_URL") or DEFAULT_API_URL).rstrip("/")
+        self.batch = BatchBuffer(self.api_key, self.api_url) if self.api_key else None
+
+    def track(self, response_or_fn, workflow_id=None, session_id=None, metadata=None):
+        from .track import track
+
+        return track(
+            response_or_fn,
+            api_key=self.api_key,
+            workflow_id=workflow_id,
+            session_id=session_id,
+            metadata=metadata,
+            api_url=self.api_url,
+        )
+
+
+def get_client(api_key=None, api_url=None):
+    """Returns a shared Spendline client per api key and URL."""
+
+    resolved_api_key = api_key or os.getenv("SPENDLINE_API_KEY")
+    resolved_api_url = (api_url or os.getenv("SPENDLINE_API_URL") or DEFAULT_API_URL).rstrip("/")
+
+    if not resolved_api_key:
+        return Spendline(api_key=None, api_url=resolved_api_url)
+
+    cache_key = (resolved_api_key, resolved_api_url)
+    with _clients_lock:
+        client = _clients.get(cache_key)
+        if client is None:
+            client = Spendline(api_key=resolved_api_key, api_url=resolved_api_url)
+            _clients[cache_key] = client
+        return client

spendline-0.1.0/spendline/costs.py

@@ -0,0 +1,95 @@
+"""Pricing lookup and response usage extraction."""
+
+import os
+import threading
+import time
+
+import requests as http
+
+CACHE_TTL = 86400
+API_URL = os.getenv("SPENDLINE_API_URL", "https://api.spendline.dev")
+
+_lock = threading.Lock()
+_model_cache = {}
+_cache_fetched_at = 0.0
+
+FALLBACK_BASELINE = {
+    "claude-sonnet-4-6": {"input": 3.00, "output": 15.00},
+    "claude-haiku-4-5": {"input": 1.00, "output": 5.00},
+    "gpt-5.2": {"input": 1.75, "output": 14.00},
+    "gpt-5-mini": {"input": 0.25, "output": 2.00},
+    "gemini-2-5-flash": {"input": 0.30, "output": 2.50},
+}
+
+
+def getCostMap(api_url=None) -> dict:
+    """Returns the pricing map, refreshing at most once per TTL."""
+
+    global _cache_fetched_at, _model_cache
+
+    now = time.time()
+    with _lock:
+        if _cache_fetched_at and (now - _cache_fetched_at) < CACHE_TTL:
+            return _model_cache
+
+        base_url = (api_url or os.getenv("SPENDLINE_API_URL") or API_URL).rstrip("/")
+        try:
+            response = http.get(f"{base_url}/v1/models", timeout=3)
+            data = response.json()
+            _model_cache = {
+                model["model_id"]: {
+                    "input": model["input_cost_per_1m"],
+                    "output": model["output_cost_per_1m"],
+                }
+                for model in data["models"]
+            }
+            _cache_fetched_at = now
+        except Exception:
+            if not _model_cache:
+                _model_cache = FALLBACK_BASELINE.copy()
+
+        return _model_cache
+
+
+def calculate_cost(model: str, tokens_in: int, tokens_out: int, api_url=None) -> tuple:
+    """Returns (cost_usd, unknown_model)."""
+
+    cost_map = getCostMap(api_url=api_url)
+    if model not in cost_map:
+        return 0.0, True
+
+    prices = cost_map[model]
+    cost = (tokens_in / 1_000_000 * prices["input"]) + (
+        tokens_out / 1_000_000 * prices["output"]
+    )
+    return round(cost, 8), False
+
+
+def extract_usage(response) -> dict:
+    """Handles OpenAI, Anthropic, and Bedrock response shapes."""
+
+    usage = getattr(response, "usage", None)
+
+    if usage is not None and hasattr(usage, "prompt_tokens"):
+        return {
+            "tokens_in": getattr(usage, "prompt_tokens", 0) or 0,
+            "tokens_out": getattr(usage, "completion_tokens", 0) or 0,
+            "model": getattr(response, "model", "unknown"),
+        }
+
+    if usage is not None and hasattr(usage, "input_tokens"):
+        return {
+            "tokens_in": getattr(usage, "input_tokens", 0) or 0,
+            "tokens_out": getattr(usage, "output_tokens", 0) or 0,
+            "model": getattr(response, "model", "unknown"),
+        }
+
+    if isinstance(response, dict) and "usage" in response:
+        usage_dict = response.get("usage") or {}
+        return {
+            "tokens_in": usage_dict.get("inputTokens", 0) or 0,
+            "tokens_out": usage_dict.get("outputTokens", 0) or 0,
+            "model": response.get("modelId", "unknown"),
+        }
+
+    return {"tokens_in": 0, "tokens_out": 0, "model": "unknown"}

spendline-0.1.0/spendline/langchain.py

@@ -0,0 +1,148 @@
+"""LangChain callback handler for Spendline."""
+
+import os
+import time
+import uuid
+from datetime import datetime, timezone
+
+from .client import get_client
+from .costs import calculate_cost, getCostMap
+from .track import _tracking_disabled, _truncate_metadata, detect_provider
+
+try:
+    from langchain.callbacks.base import BaseCallbackHandler as _BaseCallbackHandler
+
+    _LANGCHAIN_IMPORT_ERROR = None
+except ImportError as exc:
+    _BaseCallbackHandler = object
+    _LANGCHAIN_IMPORT_ERROR = exc
+
+
+class SpendlineCallbackHandler(_BaseCallbackHandler):
+    """LangChain callback that tracks LLM usage to Spendline."""
+
+    def __init__(self, workflow_id=None, session_id=None, api_key=None):
+        if _LANGCHAIN_IMPORT_ERROR is not None:
+            raise ImportError(
+                "langchain is required to use SpendlineCallbackHandler. "
+                "Install langchain to enable this integration."
+            ) from _LANGCHAIN_IMPORT_ERROR
+
+        self.workflow_id = workflow_id
+        self.session_id = session_id
+        self.api_key = api_key or os.getenv("SPENDLINE_API_KEY")
+        self._start_times = {}
+        self._models = {}
+
+    def on_llm_start(self, serialized, prompts, **kwargs):
+        try:
+            if _tracking_disabled():
+                return
+
+            run_id = kwargs.get("run_id")
+            if run_id is None:
+                return
+
+            self._start_times[str(run_id)] = time.perf_counter()
+
+            model = (
+                (serialized or {}).get("kwargs", {}).get("model_name")
+                or (serialized or {}).get("kwargs", {}).get("model")
+                or (serialized or {}).get("name")
+                or "unknown"
+            )
+            self._models[str(run_id)] = model
+
+            if os.getenv("SPENDLINE_LOG", "").lower() == "true" and model != "unknown":
+                print({"spendline_langchain_model": model})
+        except Exception:
+            pass
+
+    def on_llm_end(self, response, **kwargs):
+        try:
+            if _tracking_disabled():
+                return
+
+            run_id = str(kwargs.get("run_id"))
+            started_at = self._start_times.pop(run_id, time.perf_counter())
+            model = self._models.pop(run_id, "unknown")
+
+            llm_output = getattr(response, "llm_output", None) or {}
+            usage = llm_output.get("token_usage") or llm_output.get("usage") or {}
+
+            tokens_in = int(
+                usage.get("prompt_tokens")
+                or usage.get("input_tokens")
+                or usage.get("inputTokens")
+                or 0
+            )
+            tokens_out = int(
+                usage.get("completion_tokens")
+                or usage.get("output_tokens")
+                or usage.get("outputTokens")
+                or 0
+            )
+
+            model = llm_output.get("model_name") or llm_output.get("model") or model
+            provider = detect_provider(model)
+            getCostMap()
+            cost_usd, unknown_model = calculate_cost(model, tokens_in, tokens_out)
+            latency_ms = int((time.perf_counter() - started_at) * 1000)
+
+            event = {
+                "model": model,
+                "provider": provider,
+                "tokens_in": tokens_in,
+                "tokens_out": tokens_out,
+                "latency_ms": latency_ms,
+                "cost_usd": cost_usd,
+                "unknown_model": unknown_model,
+                "workflow_id": self.workflow_id,
+                "session_id": self.session_id,
+                "request_id": str(uuid.uuid4()),
+                "metadata": None,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+
+            if os.getenv("SPENDLINE_LOG", "").lower() == "true":
+                print(event)
+
+            client = get_client(self.api_key)
+            if client.batch is not None:
+                client.batch.add(event)
+        except Exception:
+            pass
+
+    def on_llm_error(self, error, **kwargs):
+        try:
+            if _tracking_disabled():
+                return
+
+            run_id = str(kwargs.get("run_id"))
+            started_at = self._start_times.pop(run_id, time.perf_counter())
+            model = self._models.pop(run_id, "unknown")
+            latency_ms = int((time.perf_counter() - started_at) * 1000)
+
+            event = {
+                "model": model,
+                "provider": detect_provider(model),
+                "tokens_in": 0,
+                "tokens_out": 0,
+                "latency_ms": latency_ms,
+                "cost_usd": 0.0,
+                "unknown_model": model == "unknown",
+                "workflow_id": self.workflow_id,
+                "session_id": self.session_id,
+                "request_id": str(uuid.uuid4()),
+                "metadata": _truncate_metadata({"error": True}),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+
+            if os.getenv("SPENDLINE_LOG", "").lower() == "true":
+                print(event)
+
+            client = get_client(self.api_key)
+            if client.batch is not None:
+                client.batch.add(event)
+        except Exception:
+            pass

spendline-0.1.0/spendline/track.py

@@ -0,0 +1,132 @@
+"""Core Spendline tracking helpers."""
+
+import os
+import time
+import uuid
+from datetime import datetime, timezone
+
+from .client import get_client
+from .costs import calculate_cost, extract_usage
+
+
+def detect_provider(model: str) -> str:
+    """Best-effort provider detection from model naming."""
+
+    if model.startswith("claude-"):
+        return "anthropic"
+    if model.startswith("gpt-"):
+        return "openai"
+    if model.startswith("o1") or model.startswith("o3") or model.startswith("o4"):
+        return "openai"
+    if model.startswith("gemini-"):
+        return "google"
+    if model.startswith("deepseek-"):
+        return "deepseek"
+    if model.startswith("anthropic."):
+        return "bedrock"
+    if model.startswith("amazon."):
+        return "bedrock"
+    return "unknown"
+
+
+def _tracking_disabled() -> bool:
+    return os.getenv("SPENDLINE_DISABLE", "").lower() == "true"
+
+
+def _truncate_metadata(metadata):
+    if not isinstance(metadata, dict):
+        return None
+
+    clean = {}
+    for key, value in metadata.items():
+        if isinstance(value, str):
+            clean[key] = value[:500]
+        elif isinstance(value, (int, float, bool)) or value is None:
+            clean[key] = value
+        else:
+            clean[key] = str(value)[:500]
+    return clean
+
+
+def _record_response(
+    response,
+    *,
+    started_at,
+    api_key=None,
+    workflow_id=None,
+    session_id=None,
+    metadata=None,
+    api_url=None,
+):
+    """Builds and buffers a single event for a completed response."""
+
+    resolved_api_key = api_key or os.getenv("SPENDLINE_API_KEY")
+    if not resolved_api_key:
+        return
+
+    usage = extract_usage(response)
+    model = usage["model"]
+    tokens_in = int(usage["tokens_in"])
+    tokens_out = int(usage["tokens_out"])
+    provider = detect_provider(model)
+
+    if api_url:
+        cost_usd, unknown_model = calculate_cost(
+            model, tokens_in, tokens_out, api_url=api_url
+        )
+    else:
+        cost_usd, unknown_model = calculate_cost(model, tokens_in, tokens_out)
+    latency_ms = int((time.perf_counter() - started_at) * 1000)
+
+    event = {
+        "model": model,
+        "provider": provider,
+        "tokens_in": tokens_in,
+        "tokens_out": tokens_out,
+        "latency_ms": latency_ms,
+        "cost_usd": cost_usd,
+        "unknown_model": unknown_model,
+        "workflow_id": workflow_id,
+        "session_id": session_id,
+        "request_id": str(uuid.uuid4()),
+        "metadata": _truncate_metadata(metadata),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+    if os.getenv("SPENDLINE_LOG", "").lower() == "true":
+        print(event)
+
+    client = get_client(resolved_api_key, api_url=api_url)
+    if client.batch is not None:
+        client.batch.add(event)
+
+
+def track(response_or_fn, api_key=None, workflow_id=None, session_id=None, metadata=None, api_url=None):
+    """Tracks a response or wrapped function and always returns the original response."""
+
+    if _tracking_disabled():
+        return response_or_fn() if callable(response_or_fn) else response_or_fn
+
+    response = None
+    has_response = False
+
+    try:
+        started_at = time.perf_counter()
+        response = response_or_fn() if callable(response_or_fn) else response_or_fn
+        has_response = True
+
+        _record_response(
+            response,
+            started_at=started_at,
+            api_key=api_key,
+            workflow_id=workflow_id,
+            session_id=session_id,
+            metadata=metadata,
+            api_url=api_url,
+        )
+
+        return response
+    except Exception:
+        if has_response:
+            return response
+        raise