tracelens-sdk 1.0.0__tar.gz

tracelens_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: tracelens-sdk
+Version: 1.0.0
+Summary: Python client for TraceLens agent-run tracing
+Author-email: Vikas Budde <vikas.budde@hotmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pisigmac/tracelens
+Project-URL: Repository, https://github.com/pisigmac/tracelens
+Project-URL: Issues, https://github.com/pisigmac/tracelens/issues
+Keywords: tracing,observability,llm,agents,tracelens
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+
+# tracelens-sdk
+
+Python client for [TraceLens](https://github.com/pisigmac/tracelens), a local tracing stack for AI agent runs.
+
+The package name on PyPI is `tracelens-sdk`. The import name is `tracelens`. `tracelens` is already another project, and PyPI rejects `trace-lens` as too similar to it.
+
+```bash
+pip install tracelens-sdk
+```
+
+Requires Python 3.9+ and `httpx`.
+
+A `TraceLens` client turns a unit of work into a span, batches completed spans, and posts them to a TraceLens collector at `POST /v1/spans`. The collector stores the batch in ClickHouse. The dashboard reads it back.
+
+You bring the collector. This package does not start one. The repository `docker-compose.yml` runs ClickHouse, the collector on port `8080`, and the dashboard on port `43000`.
+
+## Authentication
+
+`api_key` is sent as `Authorization: Bearer <api_key>`. The collector treats that value as a JWT, not as an opaque string.
+
+For the Compose stack the signing secret is `dev-secret-change-in-production`. The token must use HS256 and include `iss=tracelens` and `aud=tracelens-api`.
+
+```python
+import base64, hashlib, hmac, json, time
+
+def dev_token(secret="dev-secret-change-in-production", ttl=86400):
+    def b64(raw: bytes) -> str:
+        return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+    header = b64(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode())
+    payload = b64(json.dumps({
+        "sub": "local-dev",
+        "api_key": "local-dev",
+        "tier": "dev",
+        "iss": "tracelens",
+        "aud": "tracelens-api",
+        "iat": int(time.time()),
+        "exp": int(time.time()) + ttl,
+    }, separators=(",", ":")).encode())
+    signing = f"{header}.{payload}".encode()
+    sig = b64(hmac.new(secret.encode(), signing, hashlib.sha256).digest())
+    return f"{header}.{payload}.{sig}"
+```
+
+Use your own secret outside local Compose. Do not ship the development secret.
+
+## Record spans
+
+```python
+import asyncio
+from tracelens import TraceLens
+
+tl = TraceLens(
+    endpoint="http://localhost:8080",
+    api_key=dev_token(),
+    service="support-agent",
+    buffer_ms=100,
+    max_batch_size=100,
+)
+
+async def main():
+    span = tl.start_span(
+        trace_id="trace-001",
+        agent="support-agent",
+        task="draft-reply",
+    )
+    span.set_attribute("llm.model", "claude-3-5-sonnet")
+    span.set_attribute("llm.input_tokens", 4200)
+    span.set_attribute("llm.output_tokens", 890)
+    span.set_attribute("cost.usd", 0.12)
+    span.set_attribute("prompt", "Summarise the ticket")
+    ended = span.end(status="ok")
+
+    follow_up = tl.start_span(
+        trace_id="trace-001",
+        agent="support-agent",
+        task="send-reply",
+        parent_id=ended.span_id,
+    )
+    follow_up.end(status="error", error_message="smtp timeout")
+    await tl.flush()
+
+asyncio.run(main())
+```
+
+`start_span` returns a `Span` immediately. `end(status="ok")` or `end(status="error", error_message=...)` freezes the span, sets `latency_ms` from the wall clock, and queues it. Calling `end()` twice raises `RuntimeError`.
+
+`await flush()` sends every queued batch and closes the HTTP client. Call it before the process exits. Spans left in the buffer are not delivered.
+
+`service` is accepted on the client and is not written onto the span. Identity in the stored trace comes from `trace_id`, `agent`, and `task`.
+
+`buffer_ms` is how long a batch waits before a flush when an event loop is already running. `max_batch_size` flushes early once that many spans are queued. The collector rejects a batch larger than 1000 spans.
+
+## Fields the collector indexes
+
+`end()` copies four attributes onto dedicated columns. Other attributes are stored on the span as JSON.
+
+| `set_attribute` key | Stored column | Default |
+|---|---|---|
+| `llm.model` | `llm_model` | `null` |
+| `llm.input_tokens` | `input_tokens` | `0` |
+| `llm.output_tokens` | `output_tokens` | `0` |
+| `cost.usd` | `cost_usd` | `0.0` |
+
+`agent` is stored as `agent_type`. `task` is stored as `tool_name`. `status` must be `ok` or `error`.
+
+Useful free-form attributes, if you want replay to show them, are `prompt`, `response`, `tool_output`, and `decision`. Replay reads those keys and ignores the rest.
+
+## Parent spans
+
+Pass the parent id yourself. The span id exists only after `end()`.
+
+```python
+parent = tl.start_span(trace_id="trace-001", agent="planner", task="plan")
+parent_data = parent.end(status="ok")
+child = tl.start_span(
+    trace_id="trace-001",
+    agent="planner",
+    task="search",
+    parent_id=parent_data.span_id,
+)
+```
+
+## LangChain callback
+
+`TraceLensLangChainHandler` implements the callback method names LangChain uses for chains, chat models, and tools: `on_chain_start`, `on_chain_end`, `on_chain_error`, `on_llm_start`, `on_llm_end`, `on_llm_error`, `on_tool_start`, `on_tool_end`, `on_tool_error`. It is not a subclass of LangChain's `BaseCallbackHandler`. Pass it where a callback object with those methods is accepted.
+
+```python
+from tracelens import TraceLens, TraceLensLangChainHandler
+
+tl = TraceLens(endpoint="http://localhost:8080", api_key=dev_token(), service="support-agent")
+handler = TraceLensLangChainHandler(tl, trace_id="trace-lc-001", agent_name="support-agent")
+```
+
+On `on_llm_end`, token counts are read from `response.llm_output["token_usage"]` (`prompt_tokens` and `completion_tokens`). Cost is then estimated as `$3 / 1M` input tokens and `$15 / 1M` output tokens. That estimate is not provider pricing. Prompts, outputs, and tool payloads are truncated to 1000 characters.
+
+One handler shares a single `trace_id`. Create a new handler per run if each run should be its own trace.
+
+## LlamaIndex helper
+
+`TraceLensLlamaIndexHandler` is a small helper you call yourself. It is not a LlamaIndex `CallbackHandler` and it does not register with a callback manager.
+
+```python
+from tracelens import TraceLens, TraceLensLlamaIndexHandler
+
+tl = TraceLens(endpoint="http://localhost:8080", api_key=dev_token(), service="rag")
+rag = TraceLensLlamaIndexHandler(tl, trace_id="trace-rag-001")
+
+rag.on_retrieve_start("quarterly revenue", event_id="ret-1")
+rag.on_retrieve_end(nodes, event_id="ret-1")
+
+rag.on_query_start("quarterly revenue", event_id="q-1")
+rag.on_query_end(response, event_id="q-1")
+await tl.flush()
+```
+
+`on_retrieve_end` records `retrieved_chunks_count`. `on_query_end` records `response`, truncated to 1000 characters.
+
+## What the client does not do
+
+- It does not create the collector, the database, or the dashboard.
+- It does not retry a failed post. A non-201 response or a connection error is printed and the batch is dropped.
+- It does not generate `trace_id`. You pass one per run.
+- It does not read traces back. Search, replay, and metrics are collector routes. See the repository README.
+
+## Development
+
+From `sdk/python`, with `pytest` installed:
+
+```bash
+python3 -m pip install -e .
+python3 -m pytest
+python3 -m build
+```
+
+The package metadata lives in `pyproject.toml`. Tests live in `tests/` and are not part of the installed package.
+
+## License
+
+MIT. Copyright (c) 2026 pisigmac.

tracelens_sdk-1.0.0/README.md

@@ -0,0 +1,180 @@
+# tracelens-sdk
+
+Python client for [TraceLens](https://github.com/pisigmac/tracelens), a local tracing stack for AI agent runs.
+
+The package name on PyPI is `tracelens-sdk`. The import name is `tracelens`. `tracelens` is already another project, and PyPI rejects `trace-lens` as too similar to it.
+
+```bash
+pip install tracelens-sdk
+```
+
+Requires Python 3.9+ and `httpx`.
+
+A `TraceLens` client turns a unit of work into a span, batches completed spans, and posts them to a TraceLens collector at `POST /v1/spans`. The collector stores the batch in ClickHouse. The dashboard reads it back.
+
+You bring the collector. This package does not start one. The repository `docker-compose.yml` runs ClickHouse, the collector on port `8080`, and the dashboard on port `43000`.
+
+## Authentication
+
+`api_key` is sent as `Authorization: Bearer <api_key>`. The collector treats that value as a JWT, not as an opaque string.
+
+For the Compose stack the signing secret is `dev-secret-change-in-production`. The token must use HS256 and include `iss=tracelens` and `aud=tracelens-api`.
+
+```python
+import base64, hashlib, hmac, json, time
+
+def dev_token(secret="dev-secret-change-in-production", ttl=86400):
+    def b64(raw: bytes) -> str:
+        return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+    header = b64(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode())
+    payload = b64(json.dumps({
+        "sub": "local-dev",
+        "api_key": "local-dev",
+        "tier": "dev",
+        "iss": "tracelens",
+        "aud": "tracelens-api",
+        "iat": int(time.time()),
+        "exp": int(time.time()) + ttl,
+    }, separators=(",", ":")).encode())
+    signing = f"{header}.{payload}".encode()
+    sig = b64(hmac.new(secret.encode(), signing, hashlib.sha256).digest())
+    return f"{header}.{payload}.{sig}"
+```
+
+Use your own secret outside local Compose. Do not ship the development secret.
+
+## Record spans
+
+```python
+import asyncio
+from tracelens import TraceLens
+
+tl = TraceLens(
+    endpoint="http://localhost:8080",
+    api_key=dev_token(),
+    service="support-agent",
+    buffer_ms=100,
+    max_batch_size=100,
+)
+
+async def main():
+    span = tl.start_span(
+        trace_id="trace-001",
+        agent="support-agent",
+        task="draft-reply",
+    )
+    span.set_attribute("llm.model", "claude-3-5-sonnet")
+    span.set_attribute("llm.input_tokens", 4200)
+    span.set_attribute("llm.output_tokens", 890)
+    span.set_attribute("cost.usd", 0.12)
+    span.set_attribute("prompt", "Summarise the ticket")
+    ended = span.end(status="ok")
+
+    follow_up = tl.start_span(
+        trace_id="trace-001",
+        agent="support-agent",
+        task="send-reply",
+        parent_id=ended.span_id,
+    )
+    follow_up.end(status="error", error_message="smtp timeout")
+    await tl.flush()
+
+asyncio.run(main())
+```
+
+`start_span` returns a `Span` immediately. `end(status="ok")` or `end(status="error", error_message=...)` freezes the span, sets `latency_ms` from the wall clock, and queues it. Calling `end()` twice raises `RuntimeError`.
+
+`await flush()` sends every queued batch and closes the HTTP client. Call it before the process exits. Spans left in the buffer are not delivered.
+
+`service` is accepted on the client and is not written onto the span. Identity in the stored trace comes from `trace_id`, `agent`, and `task`.
+
+`buffer_ms` is how long a batch waits before a flush when an event loop is already running. `max_batch_size` flushes early once that many spans are queued. The collector rejects a batch larger than 1000 spans.
+
+## Fields the collector indexes
+
+`end()` copies four attributes onto dedicated columns. Other attributes are stored on the span as JSON.
+
+| `set_attribute` key | Stored column | Default |
+|---|---|---|
+| `llm.model` | `llm_model` | `null` |
+| `llm.input_tokens` | `input_tokens` | `0` |
+| `llm.output_tokens` | `output_tokens` | `0` |
+| `cost.usd` | `cost_usd` | `0.0` |
+
+`agent` is stored as `agent_type`. `task` is stored as `tool_name`. `status` must be `ok` or `error`.
+
+Useful free-form attributes, if you want replay to show them, are `prompt`, `response`, `tool_output`, and `decision`. Replay reads those keys and ignores the rest.
+
+## Parent spans
+
+Pass the parent id yourself. The span id exists only after `end()`.
+
+```python
+parent = tl.start_span(trace_id="trace-001", agent="planner", task="plan")
+parent_data = parent.end(status="ok")
+child = tl.start_span(
+    trace_id="trace-001",
+    agent="planner",
+    task="search",
+    parent_id=parent_data.span_id,
+)
+```
+
+## LangChain callback
+
+`TraceLensLangChainHandler` implements the callback method names LangChain uses for chains, chat models, and tools: `on_chain_start`, `on_chain_end`, `on_chain_error`, `on_llm_start`, `on_llm_end`, `on_llm_error`, `on_tool_start`, `on_tool_end`, `on_tool_error`. It is not a subclass of LangChain's `BaseCallbackHandler`. Pass it where a callback object with those methods is accepted.
+
+```python
+from tracelens import TraceLens, TraceLensLangChainHandler
+
+tl = TraceLens(endpoint="http://localhost:8080", api_key=dev_token(), service="support-agent")
+handler = TraceLensLangChainHandler(tl, trace_id="trace-lc-001", agent_name="support-agent")
+```
+
+On `on_llm_end`, token counts are read from `response.llm_output["token_usage"]` (`prompt_tokens` and `completion_tokens`). Cost is then estimated as `$3 / 1M` input tokens and `$15 / 1M` output tokens. That estimate is not provider pricing. Prompts, outputs, and tool payloads are truncated to 1000 characters.
+
+One handler shares a single `trace_id`. Create a new handler per run if each run should be its own trace.
+
+## LlamaIndex helper
+
+`TraceLensLlamaIndexHandler` is a small helper you call yourself. It is not a LlamaIndex `CallbackHandler` and it does not register with a callback manager.
+
+```python
+from tracelens import TraceLens, TraceLensLlamaIndexHandler
+
+tl = TraceLens(endpoint="http://localhost:8080", api_key=dev_token(), service="rag")
+rag = TraceLensLlamaIndexHandler(tl, trace_id="trace-rag-001")
+
+rag.on_retrieve_start("quarterly revenue", event_id="ret-1")
+rag.on_retrieve_end(nodes, event_id="ret-1")
+
+rag.on_query_start("quarterly revenue", event_id="q-1")
+rag.on_query_end(response, event_id="q-1")
+await tl.flush()
+```
+
+`on_retrieve_end` records `retrieved_chunks_count`. `on_query_end` records `response`, truncated to 1000 characters.
+
+## What the client does not do
+
+- It does not create the collector, the database, or the dashboard.
+- It does not retry a failed post. A non-201 response or a connection error is printed and the batch is dropped.
+- It does not generate `trace_id`. You pass one per run.
+- It does not read traces back. Search, replay, and metrics are collector routes. See the repository README.
+
+## Development
+
+From `sdk/python`, with `pytest` installed:
+
+```bash
+python3 -m pip install -e .
+python3 -m pytest
+python3 -m build
+```
+
+The package metadata lives in `pyproject.toml`. Tests live in `tests/` and are not part of the installed package.
+
+## License
+
+MIT. Copyright (c) 2026 pisigmac.

tracelens_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tracelens-sdk"
+version = "1.0.0"
+description = "Python client for TraceLens agent-run tracing"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Vikas Budde", email = "vikas.budde@hotmail.com" },
+]
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.27.0",
+]
+keywords = ["tracing", "observability", "llm", "agents", "tracelens"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/pisigmac/tracelens"
+Repository = "https://github.com/pisigmac/tracelens"
+Issues = "https://github.com/pisigmac/tracelens/issues"
+
+[tool.setuptools.packages.find]
+include = ["tracelens*"]
+exclude = ["tests*"]

tracelens_sdk-1.0.0/setup.cfg

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

tracelens_sdk-1.0.0/tests/test_adapters.py

@@ -0,0 +1,58 @@
+import pytest
+from uuid import uuid4
+from unittest.mock import MagicMock
+from tracelens import TraceLens, TraceLensLangChainHandler, TraceLensLlamaIndexHandler
+
+
+@pytest.fixture
+def tl():
+    return TraceLens(
+        endpoint='http://localhost:8080',
+        api_key='test-key',
+        service='test-service',
+    )
+
+
+def test_langchain_handler_events(tl):
+    handler = TraceLensLangChainHandler(
+        tracer=tl,
+        trace_id="py-lc-001",
+        agent_name="python-langchain",
+    )
+
+    run_id_1 = uuid4()
+    run_id_2 = uuid4()
+
+    handler.on_chain_start({"name": "test_chain"}, {"input": "hello"}, run_id=run_id_1)
+    handler.on_llm_start({"name": "gpt-4o"}, ["Prompt text"], run_id=run_id_2, parent_run_id=run_id_1)
+
+    mock_llm_res = MagicMock()
+    mock_llm_res.llm_output = {"token_usage": {"prompt_tokens": 120, "completion_tokens": 45}}
+    mock_llm_res.generations = [[MagicMock(text="Completion response")]]
+
+    handler.on_llm_end(mock_llm_res, run_id=run_id_2)
+    handler.on_chain_end({"output": "success"}, run_id=run_id_1)
+
+
+def test_langchain_handler_errors(tl):
+    handler = TraceLensLangChainHandler(
+        tracer=tl,
+        trace_id="py-lc-err",
+    )
+    run_id = uuid4()
+
+    handler.on_tool_start({"name": "db_lookup"}, "select *", run_id=run_id)
+    handler.on_tool_error(RuntimeError("DB query failed"), run_id=run_id)
+
+
+def test_llamaindex_handler_events(tl):
+    handler = TraceLensLlamaIndexHandler(
+        tracer=tl,
+        trace_id="py-llama-001",
+    )
+
+    handler.on_retrieve_start("rag query", "ev-1")
+    handler.on_retrieve_end([{"node": 1}], "ev-1")
+
+    handler.on_query_start("full query", "ev-2")
+    handler.on_query_end("answer", "ev-2")

tracelens_sdk-1.0.0/tests/test_tracer.py

@@ -0,0 +1,44 @@
+import pytest
+import asyncio
+from tracelens import TraceLens
+
+
+@pytest.fixture
+def tl():
+    return TraceLens(
+        endpoint='http://localhost:8080',
+        api_key='test-key',
+        service='test-service',
+    )
+
+
+def test_create_and_end_span(tl):
+    span = tl.start_span(trace_id='trace-001', agent='cursor', task='refactor')
+    span.set_attribute('llm.model', 'claude-3-5-sonnet')
+    span.set_attribute('llm.input_tokens', 4200)
+    span.set_attribute('cost.usd', 0.12)
+    data = span.end(status='ok')
+
+    assert data.agent_type == 'cursor'
+    assert data.tool_name == 'refactor'
+    assert data.llm_model == 'claude-3-5-sonnet'
+    assert data.input_tokens == 4200
+    assert data.cost_usd == 0.12
+    assert data.status == 'ok'
+    assert data.latency_ms >= 0
+
+
+def test_span_cannot_end_twice(tl):
+    span = tl.start_span(trace_id='trace-002', agent='browser', task='verify')
+    span.end(status='ok')
+    with pytest.raises(RuntimeError, match='Span already ended'):
+        span.end(status='ok')
+
+
+def test_parent_id_propagation(tl):
+    parent = tl.start_span(trace_id='trace-003', agent='cursor', task='edit')
+    parent_data = parent.end(status='ok')
+
+    child = tl.start_span(trace_id='trace-003', agent='browser', task='verify', parent_id=parent_data.span_id)
+    child_data = child.end(status='ok')
+    assert child_data.parent_id == parent_data.span_id

tracelens_sdk-1.0.0/tracelens/__init__.py

@@ -0,0 +1,14 @@
+from .tracer import TraceLens
+from .span import Span
+from .types import SpanConfig, SDKConfig
+from .adapters import TraceLensLangChainHandler, TraceLensLlamaIndexHandler
+
+__all__ = [
+    'TraceLens',
+    'Span',
+    'SpanConfig',
+    'SDKConfig',
+    'TraceLensLangChainHandler',
+    'TraceLensLlamaIndexHandler',
+]
+__version__ = '1.0.0'

tracelens_sdk-1.0.0/tracelens/adapters/__init__.py

@@ -0,0 +1,7 @@
+from .langchain import TraceLensLangChainHandler
+from .llamaindex import TraceLensLlamaIndexHandler
+
+__all__ = [
+    "TraceLensLangChainHandler",
+    "TraceLensLlamaIndexHandler",
+]

tracelens_sdk-1.0.0/tracelens/adapters/langchain.py

@@ -0,0 +1,216 @@
+import time
+import json
+from typing import Any, Dict, List, Optional, Union
+from uuid import UUID
+from tracelens.tracer import TraceLens
+from tracelens.span import Span
+
+class TraceLensLangChainHandler:
+    """
+    LangChain & LangGraph Callback Handler for TraceLens.
+    Captures chains, LLM calls, and tool executions, measuring latencies, token burn, and errors.
+    """
+
+    def __init__(
+        self,
+        tracer: TraceLens,
+        trace_id: Optional[str] = None,
+        agent_name: str = "langchain-agent",
+    ):
+        self.tracer = tracer
+        self.default_trace_id = trace_id or f"langchain-{int(time.time() * 1000)}"
+        self.agent_name = agent_name
+        self.active_spans: Dict[str, Dict[str, Any]] = {}
+
+    def on_chain_start(
+        self,
+        serialized: Dict[str, Any],
+        inputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        parent_key = str(parent_run_id) if parent_run_id else None
+        parent_span_id = self.active_spans.get(parent_key, {}).get("span_id") if parent_key else None
+
+        task_name = serialized.get("name") or serialized.get("id", ["chain"])[-1] if serialized else "chain_execution"
+
+        span = self.tracer.start_span(
+            trace_id=self.default_trace_id,
+            agent=self.agent_name,
+            task=task_name,
+            parent_id=parent_span_id,
+        )
+
+        span.set_attribute("inputs", json.dumps(inputs)[:1000] if inputs else None)
+        span.set_attribute("framework", "langchain")
+
+        self.active_spans[run_key] = {"span": span, "span_id": getattr(span, "span_id", run_key)}
+
+    def on_chain_end(
+        self,
+        outputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        item = self.active_spans.pop(run_key, None)
+        if not item:
+            return
+
+        span: Span = item["span"]
+        span.set_attribute("outputs", json.dumps(outputs)[:1000] if outputs else None)
+        span.end(status="ok")
+
+    def on_chain_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        item = self.active_spans.pop(run_key, None)
+        if not item:
+            return
+
+        span: Span = item["span"]
+        span.end(status="error", error_message=str(error))
+
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        parent_key = str(parent_run_id) if parent_run_id else None
+        parent_span_id = self.active_spans.get(parent_key, {}).get("span_id") if parent_key else None
+
+        model_name = serialized.get("name") or "llm" if serialized else "llm"
+
+        span = self.tracer.start_span(
+            trace_id=self.default_trace_id,
+            agent=self.agent_name,
+            task=f"llm_inference:{model_name}",
+            parent_id=parent_span_id,
+        )
+
+        span.set_attribute("llm.model", model_name)
+        span.set_attribute("prompt", "\n".join(prompts)[:1000] if prompts else "")
+        span.set_attribute("framework", "langchain")
+
+        self.active_spans[run_key] = {"span": span, "span_id": getattr(span, "span_id", run_key)}
+
+    def on_llm_end(
+        self,
+        response: Any,
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        item = self.active_spans.pop(run_key, None)
+        if not item:
+            return
+
+        span: Span = item["span"]
+
+        llm_output = getattr(response, "llm_output", {}) or {}
+        token_usage = llm_output.get("token_usage") or llm_output.get("tokenUsage") or {}
+
+        if token_usage:
+            prompt_tokens = token_usage.get("prompt_tokens") or token_usage.get("promptTokens") or 0
+            completion_tokens = token_usage.get("completion_tokens") or token_usage.get("completionTokens") or 0
+
+            span.set_attribute("llm.input_tokens", prompt_tokens)
+            span.set_attribute("llm.output_tokens", completion_tokens)
+
+            cost = (prompt_tokens * 0.000003) + (completion_tokens * 0.000015)
+            span.set_attribute("cost.usd", round(cost, 6))
+
+        generations = getattr(response, "generations", [])
+        if generations and len(generations) > 0 and len(generations[0]) > 0:
+            gen_text = getattr(generations[0][0], "text", str(generations[0][0]))
+            span.set_attribute("response", gen_text[:1000])
+
+        span.end(status="ok")
+
+    def on_llm_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        item = self.active_spans.pop(run_key, None)
+        if not item:
+            return
+
+        span: Span = item["span"]
+        span.end(status="error", error_message=str(error))
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        parent_key = str(parent_run_id) if parent_run_id else None
+        parent_span_id = self.active_spans.get(parent_key, {}).get("span_id") if parent_key else None
+
+        tool_name = serialized.get("name") if serialized else "tool_execution"
+
+        span = self.tracer.start_span(
+            trace_id=self.default_trace_id,
+            agent=self.agent_name,
+            task=tool_name,
+            parent_id=parent_span_id,
+        )
+
+        span.set_attribute("tool_input", str(input_str)[:1000])
+        span.set_attribute("framework", "langchain")
+
+        self.active_spans[run_key] = {"span": span, "span_id": getattr(span, "span_id", run_key)}
+
+    def on_tool_end(
+        self,
+        output: str,
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        item = self.active_spans.pop(run_key, None)
+        if not item:
+            return
+
+        span: Span = item["span"]
+        span.set_attribute("tool_output", str(output)[:1000])
+        span.end(status="ok")
+
+    def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        run_key = str(run_id)
+        item = self.active_spans.pop(run_key, None)
+        if not item:
+            return
+
+        span: Span = item["span"]
+        span.end(status="error", error_message=str(error))

tracelens_sdk-1.0.0/tracelens/adapters/llamaindex.py

@@ -0,0 +1,51 @@
+import time
+from typing import Any, Dict, List, Optional
+from tracelens.tracer import TraceLens
+from tracelens.span import Span
+
+class TraceLensLlamaIndexHandler:
+    """
+    LlamaIndex Callback Handler for TraceLens.
+    Captures vector search, chunk retrieval, and RAG query execution.
+    """
+
+    def __init__(self, tracer: TraceLens, trace_id: Optional[str] = None):
+        self.tracer = tracer
+        self.default_trace_id = trace_id or f"llamaindex-{int(time.time() * 1000)}"
+        self.active_events: Dict[str, Span] = {}
+
+    def on_retrieve_start(self, query: str, event_id: str) -> None:
+        span = self.tracer.start_span(
+            trace_id=self.default_trace_id,
+            agent="llamaindex",
+            task="vector_retrieval",
+        )
+        span.set_attribute("query", query)
+        span.set_attribute("framework", "llamaindex")
+        self.active_events[event_id] = span
+
+    def on_retrieve_end(self, nodes: List[Any], event_id: str) -> None:
+        span = self.active_events.pop(event_id, None)
+        if not span:
+            return
+
+        span.set_attribute("retrieved_chunks_count", len(nodes) if nodes else 0)
+        span.end(status="ok")
+
+    def on_query_start(self, query: str, event_id: str) -> None:
+        span = self.tracer.start_span(
+            trace_id=self.default_trace_id,
+            agent="llamaindex",
+            task="rag_query_execution",
+        )
+        span.set_attribute("query", query)
+        span.set_attribute("framework", "llamaindex")
+        self.active_events[event_id] = span
+
+    def on_query_end(self, response: Any, event_id: str) -> None:
+        span = self.active_events.pop(event_id, None)
+        if not span:
+            return
+
+        span.set_attribute("response", str(response)[:1000])
+        span.end(status="ok")

tracelens_sdk-1.0.0/tracelens/batcher.py

@@ -0,0 +1,84 @@
+import asyncio
+import httpx
+from typing import List, Dict, Any
+from .types import SpanData
+
+
+class Batcher:
+    def __init__(self, endpoint: str, api_key: str, trace_id: str, buffer_ms: int = 100, max_batch_size: int = 100):
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.trace_id = trace_id
+        self.buffer_ms = buffer_ms
+        self.max_batch_size = max_batch_size
+        self._buffer: List[SpanData] = []
+        self._client = httpx.AsyncClient(timeout=10.0)
+        self._lock = asyncio.Lock()
+        try:
+            self._task = asyncio.create_task(self._loop())
+        except RuntimeError:
+            self._task = None
+
+    def add_sync(self, span: SpanData) -> None:
+        self._buffer.append(span)
+
+    async def add(self, span: SpanData) -> None:
+        async with self._lock:
+            self._buffer.append(span)
+            if len(self._buffer) >= self.max_batch_size:
+                await self._flush()
+
+    async def _loop(self) -> None:
+        while self._running:
+            await asyncio.sleep(self.buffer_ms / 1000)
+            async with self._lock:
+                await self._flush()
+
+    async def _flush(self) -> None:
+        if not self._buffer:
+            return
+        batch = self._buffer
+        self._buffer = []
+        payload = {
+            'trace_id': self.trace_id,
+            'spans': [
+                {
+                    'span_id': s.span_id,
+                    'parent_id': s.parent_id,
+                    'agent_type': s.agent_type,
+                    'tool_name': s.tool_name,
+                    'llm_model': s.llm_model,
+                    'input_tokens': s.input_tokens,
+                    'output_tokens': s.output_tokens,
+                    'latency_ms': s.latency_ms,
+                    'status': s.status,
+                    'error_message': s.error_message,
+                    'cost_usd': s.cost_usd,
+                    'timestamp': s.timestamp,
+                    'attributes': s.attributes,
+                }
+                for s in batch
+            ],
+        }
+        try:
+            resp = await self._client.post(
+                f'{self.endpoint}/v1/spans',
+                headers={'Authorization': f'Bearer {self.api_key}', 'Content-Type': 'application/json'},
+                json=payload,
+            )
+            if resp.status_code != 201:
+                print(f'TraceLens ingest failed: {resp.status_code}')
+        except Exception as e:
+            print(f'TraceLens flush error: {e}')
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        async with self._lock:
+            await self._flush()
+        await self._client.aclose()

tracelens_sdk-1.0.0/tracelens/span.py

@@ -0,0 +1,49 @@
+import time
+import uuid
+from typing import Optional, Dict, Any
+from .types import SpanConfig, SpanData
+
+
+class Span:
+    def __init__(self, config: SpanConfig):
+        self.config = config
+        self.attrs: Dict[str, Any] = {}
+        self.start_time = time.time()
+        self._ended = False
+        self.data: Optional[SpanData] = None
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        if self._ended:
+            return
+        self.attrs[key] = value
+
+    def set_attributes(self, attrs: Dict[str, Any]) -> None:
+        if self._ended:
+            return
+        self.attrs.update(attrs)
+
+    def end(self, status: str = 'ok', error_message: Optional[str] = None) -> SpanData:
+        if self._ended:
+            raise RuntimeError('Span already ended')
+        self._ended = True
+        latency = int((time.time() - self.start_time) * 1000)
+
+        self.data = SpanData(
+            span_id=str(uuid.uuid4()),
+            parent_id=self.config.parent_id,
+            agent_type=self.config.agent,
+            tool_name=self.config.task,
+            llm_model=self.attrs.get('llm.model'),
+            input_tokens=self.attrs.get('llm.input_tokens', 0),
+            output_tokens=self.attrs.get('llm.output_tokens', 0),
+            latency_ms=latency,
+            status=status,
+            error_message=error_message,
+            cost_usd=self.attrs.get('cost.usd', 0.0),
+            timestamp=time.strftime('%Y-%m-%dT%H:%M:%S.') + f'{int((time.time() % 1) * 1000):03d}Z',
+            attributes=self.attrs,
+        )
+        return self.data
+
+    def is_ended(self) -> bool:
+        return self._ended

tracelens_sdk-1.0.0/tracelens/tracer.py

@@ -0,0 +1,47 @@
+from .types import SDKConfig, SpanConfig
+from .span import Span
+from .batcher import Batcher
+import asyncio
+
+
+class TraceLens:
+    def __init__(self, endpoint: str, api_key: str, service: str, buffer_ms: int = 100, max_batch_size: int = 100):
+        self.config = SDKConfig(
+            endpoint=endpoint,
+            api_key=api_key,
+            service=service,
+            buffer_ms=buffer_ms,
+            max_batch_size=max_batch_size,
+        )
+        self._batchers: dict[str, Batcher] = {}
+
+    def start_span(self, trace_id: str, agent: str, task: str, parent_id: str | None = None) -> Span:
+        cfg = SpanConfig(trace_id=trace_id, agent=agent, task=task, parent_id=parent_id)
+        span = Span(cfg)
+
+        if trace_id not in self._batchers:
+            self._batchers[trace_id] = Batcher(
+                self.config.endpoint,
+                self.config.api_key,
+                trace_id,
+                self.config.buffer_ms,
+                self.config.max_batch_size,
+            )
+        batcher = self._batchers[trace_id]
+
+        original_end = span.end
+        def wrapped_end(status: str = 'ok', error_message: str | None = None):
+            data = original_end(status, error_message)
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(batcher.add(data))
+            except RuntimeError:
+                batcher.add_sync(data)
+            return data
+        span.end = wrapped_end
+
+        return span
+
+    async def flush(self) -> None:
+        await asyncio.gather(*(b.stop() for b in self._batchers.values()))
+        self._batchers.clear()

tracelens_sdk-1.0.0/tracelens/types.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any
+
+
+@dataclass
+class SpanConfig:
+    trace_id: str
+    agent: str
+    task: str
+    parent_id: Optional[str] = None
+
+
+@dataclass
+class SDKConfig:
+    endpoint: str
+    api_key: str
+    service: str
+    buffer_ms: int = 100
+    max_batch_size: int = 100
+
+
+@dataclass
+class SpanData:
+    span_id: str
+    parent_id: Optional[str]
+    agent_type: str
+    tool_name: str
+    llm_model: Optional[str]
+    input_tokens: int
+    output_tokens: int
+    latency_ms: int
+    status: str
+    error_message: Optional[str]
+    cost_usd: float
+    timestamp: str
+    attributes: Dict[str, Any] = field(default_factory=dict)

tracelens_sdk-1.0.0/tracelens_sdk.egg-info/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: tracelens-sdk
+Version: 1.0.0
+Summary: Python client for TraceLens agent-run tracing
+Author-email: Vikas Budde <vikas.budde@hotmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pisigmac/tracelens
+Project-URL: Repository, https://github.com/pisigmac/tracelens
+Project-URL: Issues, https://github.com/pisigmac/tracelens/issues
+Keywords: tracing,observability,llm,agents,tracelens
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+
+# tracelens-sdk
+
+Python client for [TraceLens](https://github.com/pisigmac/tracelens), a local tracing stack for AI agent runs.
+
+The package name on PyPI is `tracelens-sdk`. The import name is `tracelens`. `tracelens` is already another project, and PyPI rejects `trace-lens` as too similar to it.
+
+```bash
+pip install tracelens-sdk
+```
+
+Requires Python 3.9+ and `httpx`.
+
+A `TraceLens` client turns a unit of work into a span, batches completed spans, and posts them to a TraceLens collector at `POST /v1/spans`. The collector stores the batch in ClickHouse. The dashboard reads it back.
+
+You bring the collector. This package does not start one. The repository `docker-compose.yml` runs ClickHouse, the collector on port `8080`, and the dashboard on port `43000`.
+
+## Authentication
+
+`api_key` is sent as `Authorization: Bearer <api_key>`. The collector treats that value as a JWT, not as an opaque string.
+
+For the Compose stack the signing secret is `dev-secret-change-in-production`. The token must use HS256 and include `iss=tracelens` and `aud=tracelens-api`.
+
+```python
+import base64, hashlib, hmac, json, time
+
+def dev_token(secret="dev-secret-change-in-production", ttl=86400):
+    def b64(raw: bytes) -> str:
+        return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+    header = b64(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode())
+    payload = b64(json.dumps({
+        "sub": "local-dev",
+        "api_key": "local-dev",
+        "tier": "dev",
+        "iss": "tracelens",
+        "aud": "tracelens-api",
+        "iat": int(time.time()),
+        "exp": int(time.time()) + ttl,
+    }, separators=(",", ":")).encode())
+    signing = f"{header}.{payload}".encode()
+    sig = b64(hmac.new(secret.encode(), signing, hashlib.sha256).digest())
+    return f"{header}.{payload}.{sig}"
+```
+
+Use your own secret outside local Compose. Do not ship the development secret.
+
+## Record spans
+
+```python
+import asyncio
+from tracelens import TraceLens
+
+tl = TraceLens(
+    endpoint="http://localhost:8080",
+    api_key=dev_token(),
+    service="support-agent",
+    buffer_ms=100,
+    max_batch_size=100,
+)
+
+async def main():
+    span = tl.start_span(
+        trace_id="trace-001",
+        agent="support-agent",
+        task="draft-reply",
+    )
+    span.set_attribute("llm.model", "claude-3-5-sonnet")
+    span.set_attribute("llm.input_tokens", 4200)
+    span.set_attribute("llm.output_tokens", 890)
+    span.set_attribute("cost.usd", 0.12)
+    span.set_attribute("prompt", "Summarise the ticket")
+    ended = span.end(status="ok")
+
+    follow_up = tl.start_span(
+        trace_id="trace-001",
+        agent="support-agent",
+        task="send-reply",
+        parent_id=ended.span_id,
+    )
+    follow_up.end(status="error", error_message="smtp timeout")
+    await tl.flush()
+
+asyncio.run(main())
+```
+
+`start_span` returns a `Span` immediately. `end(status="ok")` or `end(status="error", error_message=...)` freezes the span, sets `latency_ms` from the wall clock, and queues it. Calling `end()` twice raises `RuntimeError`.
+
+`await flush()` sends every queued batch and closes the HTTP client. Call it before the process exits. Spans left in the buffer are not delivered.
+
+`service` is accepted on the client and is not written onto the span. Identity in the stored trace comes from `trace_id`, `agent`, and `task`.
+
+`buffer_ms` is how long a batch waits before a flush when an event loop is already running. `max_batch_size` flushes early once that many spans are queued. The collector rejects a batch larger than 1000 spans.
+
+## Fields the collector indexes
+
+`end()` copies four attributes onto dedicated columns. Other attributes are stored on the span as JSON.
+
+| `set_attribute` key | Stored column | Default |
+|---|---|---|
+| `llm.model` | `llm_model` | `null` |
+| `llm.input_tokens` | `input_tokens` | `0` |
+| `llm.output_tokens` | `output_tokens` | `0` |
+| `cost.usd` | `cost_usd` | `0.0` |
+
+`agent` is stored as `agent_type`. `task` is stored as `tool_name`. `status` must be `ok` or `error`.
+
+Useful free-form attributes, if you want replay to show them, are `prompt`, `response`, `tool_output`, and `decision`. Replay reads those keys and ignores the rest.
+
+## Parent spans
+
+Pass the parent id yourself. The span id exists only after `end()`.
+
+```python
+parent = tl.start_span(trace_id="trace-001", agent="planner", task="plan")
+parent_data = parent.end(status="ok")
+child = tl.start_span(
+    trace_id="trace-001",
+    agent="planner",
+    task="search",
+    parent_id=parent_data.span_id,
+)
+```
+
+## LangChain callback
+
+`TraceLensLangChainHandler` implements the callback method names LangChain uses for chains, chat models, and tools: `on_chain_start`, `on_chain_end`, `on_chain_error`, `on_llm_start`, `on_llm_end`, `on_llm_error`, `on_tool_start`, `on_tool_end`, `on_tool_error`. It is not a subclass of LangChain's `BaseCallbackHandler`. Pass it where a callback object with those methods is accepted.
+
+```python
+from tracelens import TraceLens, TraceLensLangChainHandler
+
+tl = TraceLens(endpoint="http://localhost:8080", api_key=dev_token(), service="support-agent")
+handler = TraceLensLangChainHandler(tl, trace_id="trace-lc-001", agent_name="support-agent")
+```
+
+On `on_llm_end`, token counts are read from `response.llm_output["token_usage"]` (`prompt_tokens` and `completion_tokens`). Cost is then estimated as `$3 / 1M` input tokens and `$15 / 1M` output tokens. That estimate is not provider pricing. Prompts, outputs, and tool payloads are truncated to 1000 characters.
+
+One handler shares a single `trace_id`. Create a new handler per run if each run should be its own trace.
+
+## LlamaIndex helper
+
+`TraceLensLlamaIndexHandler` is a small helper you call yourself. It is not a LlamaIndex `CallbackHandler` and it does not register with a callback manager.
+
+```python
+from tracelens import TraceLens, TraceLensLlamaIndexHandler
+
+tl = TraceLens(endpoint="http://localhost:8080", api_key=dev_token(), service="rag")
+rag = TraceLensLlamaIndexHandler(tl, trace_id="trace-rag-001")
+
+rag.on_retrieve_start("quarterly revenue", event_id="ret-1")
+rag.on_retrieve_end(nodes, event_id="ret-1")
+
+rag.on_query_start("quarterly revenue", event_id="q-1")
+rag.on_query_end(response, event_id="q-1")
+await tl.flush()
+```
+
+`on_retrieve_end` records `retrieved_chunks_count`. `on_query_end` records `response`, truncated to 1000 characters.
+
+## What the client does not do
+
+- It does not create the collector, the database, or the dashboard.
+- It does not retry a failed post. A non-201 response or a connection error is printed and the batch is dropped.
+- It does not generate `trace_id`. You pass one per run.
+- It does not read traces back. Search, replay, and metrics are collector routes. See the repository README.
+
+## Development
+
+From `sdk/python`, with `pytest` installed:
+
+```bash
+python3 -m pip install -e .
+python3 -m pytest
+python3 -m build
+```
+
+The package metadata lives in `pyproject.toml`. Tests live in `tests/` and are not part of the installed package.
+
+## License
+
+MIT. Copyright (c) 2026 pisigmac.

tracelens_sdk-1.0.0/tracelens_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+tests/test_adapters.py
+tests/test_tracer.py
+tracelens/__init__.py
+tracelens/batcher.py
+tracelens/span.py
+tracelens/tracer.py
+tracelens/types.py
+tracelens/adapters/__init__.py
+tracelens/adapters/langchain.py
+tracelens/adapters/llamaindex.py
+tracelens_sdk.egg-info/PKG-INFO
+tracelens_sdk.egg-info/SOURCES.txt
+tracelens_sdk.egg-info/dependency_links.txt
+tracelens_sdk.egg-info/requires.txt
+tracelens_sdk.egg-info/top_level.txt

tracelens_sdk-1.0.0/tracelens_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tracelens_sdk-1.0.0/tracelens_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27.0

tracelens_sdk-1.0.0/tracelens_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+tracelens