tokenjam 0.2.1__tar.gz → 0.2.2__tar.gz

{tokenjam-0.2.1 → tokenjam-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenjam
-Version: 0.2.1
+Version: 0.2.2
 Summary: TokenJam — local-first OTel-native observability for Autonomous AI agents
 Project-URL: Homepage, https://opencla.watch
 Project-URL: Repository, https://github.com/Metabuilder-Labs/openclawwatch

{tokenjam-0.2.1 → tokenjam-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tokenjam"
-version = "0.2.1"
+version = "0.2.2"
 description = "TokenJam — local-first OTel-native observability for Autonomous AI agents"
 readme = "README.md"
 requires-python = ">=3.10"

{tokenjam-0.2.1 → tokenjam-0.2.2}/sdk-ts/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@tokenjam/sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@tokenjam/sdk",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "license": "MIT",
       "devDependencies": {
         "@types/node": "^25.5.0",

{tokenjam-0.2.1 → tokenjam-0.2.2}/sdk-ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenjam/sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "TypeScript SDK for TokenJam — local-first observability for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

tokenjam-0.2.2/tests/unit/test_litellm_client.py

@@ -0,0 +1,214 @@
+"""Unit tests for TokenJamClient.emit_litellm_span (LiteLLM named-callback path)."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+from tokenjam.otel.semconv import GenAIAttributes, TjAttributes
+from tokenjam.sdk.client import TokenJamClient, _build_litellm_span
+
+
+def _attrs_to_dict(otlp_attrs: list[dict]) -> dict[str, object]:
+    out: dict[str, object] = {}
+    for a in otlp_attrs:
+        v = a["value"]
+        if "stringValue" in v:
+            out[a["key"]] = v["stringValue"]
+        elif "intValue" in v:
+            out[a["key"]] = int(v["intValue"])
+        elif "doubleValue" in v:
+            out[a["key"]] = float(v["doubleValue"])
+        elif "boolValue" in v:
+            out[a["key"]] = v["boolValue"]
+    return out
+
+
+def _basic_response(provider: str = "openai", prompt: int = 10, completion: int = 5) -> object:
+    return SimpleNamespace(
+        usage=SimpleNamespace(prompt_tokens=prompt, completion_tokens=completion),
+        _hidden_params={"custom_llm_provider": provider, "response_cost": 0.00042},
+    )
+
+
+# --- _build_litellm_span ---------------------------------------------------
+
+
+def test_build_span_success_with_usage_and_cost():
+    kwargs = {
+        "model": "openai/gpt-4o-mini",
+        "metadata": {"tj_agent_id": "agent-a", "tj_session_id": "sess-1"},
+    }
+    response = _basic_response()
+    start = datetime(2026, 5, 12, tzinfo=timezone.utc)
+    end = datetime(2026, 5, 12, 0, 0, 1, tzinfo=timezone.utc)
+
+    span = _build_litellm_span(kwargs, response, start, end, success=True)
+
+    assert span["name"] == GenAIAttributes.SPAN_LLM_CALL
+    assert span["status"] == {"code": 1}
+    assert len(span["traceId"]) == 32
+    assert len(span["spanId"]) == 16
+
+    attrs = _attrs_to_dict(span["attributes"])
+    assert attrs[GenAIAttributes.REQUEST_MODEL] == "gpt-4o-mini"  # prefix stripped
+    assert attrs[GenAIAttributes.PROVIDER_NAME] == "openai"
+    assert attrs[GenAIAttributes.INPUT_TOKENS] == 10
+    assert attrs[GenAIAttributes.OUTPUT_TOKENS] == 5
+    assert attrs[TjAttributes.COST_USD] == pytest.approx(0.00042)
+    assert attrs[GenAIAttributes.AGENT_ID] == "agent-a"
+    assert attrs[GenAIAttributes.CONVERSATION_ID] == "sess-1"
+
+
+def test_build_span_failure_records_error_status():
+    kwargs = {"model": "anthropic/claude-3-5-sonnet"}
+    err = RuntimeError("rate limited")
+    start = datetime.now(timezone.utc)
+    end = datetime.now(timezone.utc)
+
+    span = _build_litellm_span(kwargs, err, start, end, success=False)
+    assert span["status"]["code"] == 2
+    assert span["status"]["message"] == "rate limited"
+
+
+def test_build_span_falls_back_to_model_prefix_for_provider():
+    # No _hidden_params on response — provider inferred from model prefix.
+    kwargs = {"model": "anthropic/claude-3-5-sonnet"}
+    response = SimpleNamespace(usage=None)
+    span = _build_litellm_span(
+        kwargs, response,
+        datetime.now(timezone.utc), datetime.now(timezone.utc),
+        success=True,
+    )
+    attrs = _attrs_to_dict(span["attributes"])
+    assert attrs[GenAIAttributes.PROVIDER_NAME] == "anthropic"
+    assert attrs[GenAIAttributes.REQUEST_MODEL] == "claude-3-5-sonnet"
+
+
+def test_build_span_handles_dict_usage():
+    kwargs = {"model": "gpt-4o"}
+    response = {
+        "usage": {
+            "prompt_tokens": 7,
+            "completion_tokens": 3,
+            "cache_read_input_tokens": 100,
+            "cache_creation_input_tokens": 50,
+        },
+        "_hidden_params": {"custom_llm_provider": "openai"},
+    }
+    span = _build_litellm_span(
+        kwargs, response,
+        datetime.now(timezone.utc), datetime.now(timezone.utc),
+        success=True,
+    )
+    attrs = _attrs_to_dict(span["attributes"])
+    assert attrs[GenAIAttributes.INPUT_TOKENS] == 7
+    assert attrs[GenAIAttributes.OUTPUT_TOKENS] == 3
+    assert attrs[GenAIAttributes.CACHE_READ_TOKENS] == 100
+    assert attrs[GenAIAttributes.CACHE_CREATE_TOKENS] == 50
+
+
+def test_build_span_missing_model_defaults_to_unknown():
+    span = _build_litellm_span(
+        {}, SimpleNamespace(usage=None),
+        datetime.now(timezone.utc), datetime.now(timezone.utc),
+        success=True,
+    )
+    attrs = _attrs_to_dict(span["attributes"])
+    assert attrs[GenAIAttributes.REQUEST_MODEL] == "unknown"
+    assert attrs[GenAIAttributes.PROVIDER_NAME] == "litellm"
+
+
+# --- TokenJamClient HTTP behavior ------------------------------------------
+
+
+def test_client_appends_api_v1_spans_to_base_endpoint():
+    c = TokenJamClient(endpoint="http://localhost:7391")
+    assert c._endpoint == "http://localhost:7391/api/v1/spans"
+
+    c2 = TokenJamClient(endpoint="http://localhost:7391/api/v1/spans")
+    assert c2._endpoint == "http://localhost:7391/api/v1/spans"
+
+    c3 = TokenJamClient(endpoint="http://localhost:7391/")
+    assert c3._endpoint == "http://localhost:7391/api/v1/spans"
+
+
+def test_client_posts_otlp_payload_with_bearer_when_secret_set():
+    c = TokenJamClient(endpoint="http://localhost:7391", ingest_secret="s3cret")
+
+    captured: dict[str, object] = {}
+
+    def fake_post(url, json, headers, timeout):
+        captured["url"] = url
+        captured["json"] = json
+        captured["headers"] = headers
+        return httpx.Response(200)
+
+    with patch("tokenjam.sdk.client.httpx.post", side_effect=fake_post):
+        c.emit_litellm_span(
+            kwargs={"model": "openai/gpt-4o-mini"},
+            response_obj=_basic_response(),
+            start_time=datetime.now(timezone.utc),
+            end_time=datetime.now(timezone.utc),
+            success=True,
+        )
+
+    assert captured["url"] == "http://localhost:7391/api/v1/spans"
+    assert captured["headers"]["Authorization"] == "Bearer s3cret"
+    body = captured["json"]
+    assert "resourceSpans" in body
+    assert body["resourceSpans"][0]["scopeSpans"][0]["spans"][0]["name"] == GenAIAttributes.SPAN_LLM_CALL
+
+
+def test_client_omits_authorization_when_no_secret():
+    c = TokenJamClient(endpoint="http://localhost:7391")
+    captured: dict[str, object] = {}
+
+    def fake_post(url, json, headers, timeout):
+        captured["headers"] = headers
+        return httpx.Response(200)
+
+    with patch("tokenjam.sdk.client.httpx.post", side_effect=fake_post):
+        c.emit_litellm_span(
+            kwargs={"model": "gpt-4o-mini"},
+            response_obj=_basic_response(),
+            start_time=datetime.now(timezone.utc),
+            end_time=datetime.now(timezone.utc),
+            success=True,
+        )
+
+    assert "Authorization" not in captured["headers"]
+
+
+def test_client_swallows_connection_errors():
+    c = TokenJamClient(endpoint="http://localhost:7391")
+    with patch(
+        "tokenjam.sdk.client.httpx.post",
+        side_effect=httpx.ConnectError("boom"),
+    ):
+        # Must not raise.
+        c.emit_litellm_span(
+            kwargs={"model": "gpt-4o-mini"},
+            response_obj=_basic_response(),
+            start_time=datetime.now(timezone.utc),
+            end_time=datetime.now(timezone.utc),
+            success=True,
+        )
+
+
+def test_client_swallows_build_errors():
+    """A malformed response should not propagate; the event is dropped."""
+    c = TokenJamClient(endpoint="http://localhost:7391")
+    with patch(
+        "tokenjam.sdk.client._build_litellm_span",
+        side_effect=ValueError("bad payload"),
+    ):
+        c.emit_litellm_span(
+            kwargs={}, response_obj=None,
+            start_time=datetime.now(timezone.utc),
+            end_time=datetime.now(timezone.utc),
+            success=True,
+        )

{tokenjam-0.2.1 → tokenjam-0.2.2}/tokenjam/sdk/__init__.py

@@ -1,4 +1,5 @@
 from tokenjam.sdk.agent import watch, AgentSession, record_llm_call, record_tool_call
+from tokenjam.sdk.client import TokenJamClient
 from tokenjam.sdk.integrations.anthropic import patch_anthropic
 from tokenjam.sdk.integrations.openai import patch_openai
 from tokenjam.sdk.integrations.gemini import patch_gemini
@@ -14,6 +15,7 @@ from tokenjam.sdk.integrations.nemoclaw import watch_nemoclaw
 
 __all__ = [
     "watch", "AgentSession", "record_llm_call", "record_tool_call",
+    "TokenJamClient",
     "patch_anthropic", "patch_openai", "patch_gemini", "patch_bedrock",
     "patch_langchain", "patch_langgraph", "patch_crewai", "patch_autogen",
     "patch_litellm", "patch_llamaindex", "patch_openai_agents",

tokenjam-0.2.2/tokenjam/sdk/client.py

@@ -0,0 +1,267 @@
+"""Public HTTP client for shipping spans into a running ``tj serve``.
+
+This is the entry point used by external integrations that cannot rely on the
+in-process OTel TracerProvider — most notably, the upstream LiteLLM named
+callback (``litellm.success_callback = ["tokenjam"]``) which lives in the
+LiteLLM repo and only depends on this public surface.
+
+For in-process use inside a tokenjam-aware app, prefer ``patch_litellm()`` —
+it produces the same spans via the OTel pipeline.
+"""
+from __future__ import annotations
+
+import logging
+import secrets
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import httpx
+
+from tokenjam.otel.semconv import GenAIAttributes, TjAttributes
+
+logger = logging.getLogger("tokenjam.sdk")
+
+_TIMEOUT_SECS = 5.0
+
+
+class TokenJamClient:
+    """Thin HTTP client that POSTs a single LiteLLM call as an OTLP span.
+
+    Designed to be embedded in foreign codebases (e.g. LiteLLM's named-callback
+    machinery), so it has no dependency on the rest of the tokenjam SDK at
+    construction time and never raises from its public methods — failures are
+    logged at ``debug`` and the event is dropped.
+    """
+
+    def __init__(
+        self,
+        endpoint: str = "http://localhost:7391",
+        ingest_secret: Optional[str] = None,
+    ) -> None:
+        # Accept either the server base URL or the full /api/v1/spans path.
+        endpoint = endpoint.rstrip("/")
+        if not endpoint.endswith("/api/v1/spans"):
+            endpoint = f"{endpoint}/api/v1/spans"
+        self._endpoint = endpoint
+        self._secret = ingest_secret
+
+    def emit_litellm_span(
+        self,
+        kwargs: dict[str, Any],
+        response_obj: Any,
+        start_time: datetime,
+        end_time: datetime,
+        success: bool,
+    ) -> None:
+        """Translate a LiteLLM success/failure callback payload into an OTLP
+        span and POST it to ``tj serve``.
+
+        Non-blocking: all errors are swallowed and logged at debug.
+        """
+        try:
+            span = _build_litellm_span(
+                kwargs=kwargs,
+                response_obj=response_obj,
+                start_time=start_time,
+                end_time=end_time,
+                success=success,
+            )
+            payload = {
+                "resourceSpans": [{
+                    "resource": {"attributes": [
+                        {"key": "service.name",
+                         "value": {"stringValue": "litellm"}},
+                    ]},
+                    "scopeSpans": [{"spans": [span]}],
+                }],
+            }
+            headers = {"Content-Type": "application/json"}
+            if self._secret:
+                headers["Authorization"] = f"Bearer {self._secret}"
+            resp = httpx.post(
+                self._endpoint,
+                json=payload,
+                headers=headers,
+                timeout=_TIMEOUT_SECS,
+            )
+            if resp.status_code >= 300:
+                logger.debug(
+                    "tj serve returned %d on emit_litellm_span",
+                    resp.status_code,
+                )
+        except Exception as exc:  # noqa: BLE001 — non-blocking by design
+            logger.debug("emit_litellm_span failed: %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# Payload construction (pure functions, exposed for unit testing)
+# ---------------------------------------------------------------------------
+
+
+def _build_litellm_span(
+    kwargs: dict[str, Any],
+    response_obj: Any,
+    start_time: datetime,
+    end_time: datetime,
+    success: bool,
+) -> dict[str, Any]:
+    """Build an OTLP JSON span dict from a LiteLLM callback payload."""
+    raw_model = str(kwargs.get("model") or "unknown")
+    model = _strip_provider_prefix(raw_model)
+    provider = _parse_provider(raw_model, response_obj)
+    metadata = kwargs.get("metadata") or {}
+
+    attrs: dict[str, Any] = {
+        GenAIAttributes.REQUEST_MODEL: model,
+        GenAIAttributes.PROVIDER_NAME: provider,
+    }
+
+    # Token usage from response.usage (OpenAI-style dict or pydantic model)
+    usage = _get_usage(response_obj)
+    if usage:
+        prompt_tokens = _coerce_int(usage.get("prompt_tokens"))
+        completion_tokens = _coerce_int(usage.get("completion_tokens"))
+        if prompt_tokens is not None:
+            attrs[GenAIAttributes.INPUT_TOKENS] = prompt_tokens
+        if completion_tokens is not None:
+            attrs[GenAIAttributes.OUTPUT_TOKENS] = completion_tokens
+        # Anthropic-style cache token fields, if present
+        cache_read = _coerce_int(usage.get("cache_read_input_tokens"))
+        cache_create = _coerce_int(usage.get("cache_creation_input_tokens"))
+        if cache_read is not None:
+            attrs[GenAIAttributes.CACHE_READ_TOKENS] = cache_read
+        if cache_create is not None:
+            attrs[GenAIAttributes.CACHE_CREATE_TOKENS] = cache_create
+
+    # LiteLLM puts a precomputed cost on kwargs / response.hidden_params
+    cost = _get_response_cost(kwargs, response_obj)
+    if cost is not None:
+        attrs[TjAttributes.COST_USD] = cost
+
+    # Per-call agent + session tags supplied via metadata
+    if isinstance(metadata, dict):
+        agent_id = metadata.get("tj_agent_id")
+        if agent_id:
+            attrs[GenAIAttributes.AGENT_ID] = str(agent_id)
+        session_id = metadata.get("tj_session_id")
+        if session_id:
+            attrs[GenAIAttributes.CONVERSATION_ID] = str(session_id)
+
+    span: dict[str, Any] = {
+        "traceId": _new_trace_id(),
+        "spanId": _new_span_id(),
+        "name": GenAIAttributes.SPAN_LLM_CALL,
+        "kind": 3,  # CLIENT
+        "startTimeUnixNano": str(_to_unix_nanos(start_time)),
+        "endTimeUnixNano": str(_to_unix_nanos(end_time)),
+        "attributes": [
+            {"key": k, "value": _to_otlp_value(v)} for k, v in attrs.items()
+        ],
+        "status": {"code": 1 if success else 2},
+        "events": [],
+    }
+    if not success:
+        msg = _extract_error_message(response_obj)
+        if msg:
+            span["status"]["message"] = msg
+    return span
+
+
+def _strip_provider_prefix(model: str) -> str:
+    if "/" in model:
+        return model.split("/", 1)[1]
+    return model
+
+
+def _parse_provider(model: str, response: Any) -> str:
+    hidden = getattr(response, "_hidden_params", None)
+    if isinstance(hidden, dict):
+        p = hidden.get("custom_llm_provider")
+        if p:
+            return str(p)
+    if isinstance(response, dict):
+        hidden = response.get("_hidden_params")
+        if isinstance(hidden, dict) and hidden.get("custom_llm_provider"):
+            return str(hidden["custom_llm_provider"])
+    if "/" in model:
+        return model.split("/", 1)[0]
+    return "litellm"
+
+
+def _get_usage(response: Any) -> Optional[dict[str, Any]]:
+    """Normalize response.usage to a dict, regardless of pydantic/dict shape."""
+    usage = getattr(response, "usage", None)
+    if usage is None and isinstance(response, dict):
+        usage = response.get("usage")
+    if usage is None:
+        return None
+    if isinstance(usage, dict):
+        return usage
+    # pydantic v2 model or plain object with attributes
+    out: dict[str, Any] = {}
+    for k in (
+        "prompt_tokens", "completion_tokens",
+        "cache_read_input_tokens", "cache_creation_input_tokens",
+    ):
+        v = getattr(usage, k, None)
+        if v is not None:
+            out[k] = v
+    return out or None
+
+
+def _get_response_cost(kwargs: dict[str, Any], response: Any) -> Optional[float]:
+    # LiteLLM exposes response_cost on the callback kwargs
+    cost = kwargs.get("response_cost")
+    if cost is None:
+        hidden = getattr(response, "_hidden_params", None)
+        if isinstance(hidden, dict):
+            cost = hidden.get("response_cost")
+    if cost is None:
+        return None
+    try:
+        return float(cost)
+    except (TypeError, ValueError):
+        return None
+
+
+def _extract_error_message(response: Any) -> Optional[str]:
+    if isinstance(response, Exception):
+        return str(response)
+    if isinstance(response, dict):
+        err = response.get("error") or response.get("message")
+        if err:
+            return str(err)
+    return None
+
+
+def _coerce_int(v: Any) -> Optional[int]:
+    if v is None:
+        return None
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_unix_nanos(dt: datetime) -> int:
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return int(dt.timestamp() * 1_000_000_000)
+
+
+def _new_trace_id() -> str:
+    return secrets.token_hex(16)
+
+
+def _new_span_id() -> str:
+    return secrets.token_hex(8)
+
+
+def _to_otlp_value(v: Any) -> dict[str, Any]:
+    if isinstance(v, bool):
+        return {"boolValue": v}
+    if isinstance(v, int):
+        return {"intValue": str(v)}
+    if isinstance(v, float):
+        return {"doubleValue": v}
+    return {"stringValue": str(v)}