spanlens 0.1.0__tar.gz

spanlens-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+node_modules/
+.next/
+dist/
+build/
+.turbo/
+*.tsbuildinfo
+
+# env
+.env
+.env.local
+.env.production
+.env.*.local
+
+# supabase
+supabase/.branches/
+supabase/.temp/
+
+# pnpm
+.pnpm-store/
+
+# npm auth tokens (never commit)
+.npmrc
+
+# OS
+.DS_Store
+Thumbs.db
+
+# logs
+*.log
+npm-debug.log*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Vercel
+.vercel

spanlens-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+Initial release of the Spanlens Python SDK.
+
+* `SpanlensClient`, `TraceHandle`, `SpanHandle` — core tracing primitives
+* Context-manager support so `end()` is called automatically
+* `observe()`, `observe_openai()`, `observe_anthropic()`, `observe_gemini()`
+  — boilerplate-free helpers with auto-parsed usage
+* `create_openai()`, `create_anthropic()`, `create_gemini()`,
+  `configure_gemini()` — proxy-mode integrations
+* Background ingest with timeout + ordering guarantees so observability
+  never blocks user code or loses spans to race conditions
+* Sync **and** async callables supported by every `observe*()` helper

spanlens-0.1.0/LICENSE

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

spanlens-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: spanlens
+Version: 0.1.0
+Summary: Spanlens SDK — agent tracing, LLM usage capture, and cost observability for Python.
+Project-URL: Homepage, https://spanlens.io
+Project-URL: Documentation, https://spanlens.io/docs/sdk
+Project-URL: Repository, https://github.com/sunes26/Spanlens
+Project-URL: Issues, https://github.com/sunes26/Spanlens/issues
+Author-email: Spanlens <support@spanlens.io>
+License: MIT
+License-File: LICENSE
+Keywords: agent-tracing,ai-agents,anthropic,claude,cost-tracking,gemini,helicone-alternative,langchain,langfuse-alternative,langsmith-alternative,llamaindex,llm,llm-monitoring,llm-observability,llm-tracing,observability,openai,proxy,spanlens,token-tracking,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.18.0; extra == 'all'
+Requires-Dist: google-generativeai>=0.5.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.5.0; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Spanlens Python SDK
+
+LLM observability for Python. Trace agent runs, capture token usage and cost,
+and link calls back to your Spanlens dashboard with one line of code.
+
+[![PyPI](https://img.shields.io/pypi/v/spanlens.svg)](https://pypi.org/project/spanlens/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/pypi/pyversions/spanlens.svg)](https://pypi.org/project/spanlens/)
+
+> **Spanlens** is the open-source LLM observability platform. This is the
+> official Python SDK — for the dashboard, signup, and proxy docs, head to
+> [spanlens.io](https://spanlens.io).
+
+---
+
+## Install
+
+```bash
+pip install spanlens
+
+# Or with provider integrations:
+pip install "spanlens[openai]"
+pip install "spanlens[anthropic]"
+pip install "spanlens[gemini]"
+pip install "spanlens[all]"
+```
+
+## Two ways to use it
+
+| Mode | Best for | Setup |
+| --- | --- | --- |
+| **Proxy** | Single-call observability — drop-in for the OpenAI/Anthropic SDK | Replace `base_url` |
+| **SDK tracing** | Multi-step agents, RAG, tool calls, manual spans | `SpanlensClient(...)` |
+
+You can mix both. The proxy logs the raw request; the SDK groups multiple
+requests into a single trace with parent / child spans.
+
+---
+
+## Mode 1 — Proxy (zero-code)
+
+Get a Spanlens API key from your dashboard, then point your provider SDK at
+the Spanlens proxy:
+
+```python
+import os
+from spanlens.integrations.openai import create_openai
+
+# Reads SPANLENS_API_KEY from the environment
+client = create_openai()
+
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+Spanlens automatically logs the request, response, latency, token counts,
+and cost — viewable in the dashboard under **Requests**.
+
+### Tagging requests with a prompt version
+
+```python
+from spanlens.integrations.openai import create_openai, with_prompt_version
+
+client = create_openai()
+res = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[...],
+    **with_prompt_version("chatbot-system@3"),
+)
+```
+
+The same pattern works for Anthropic — see
+[`spanlens.integrations.anthropic`](./spanlens/integrations/anthropic.py).
+
+---
+
+## Mode 2 — SDK tracing (multi-step agents)
+
+Use the SDK when one user request spans multiple LLM calls, retrieval, tool
+use, etc. Spans appear nested under a single trace in the dashboard.
+
+```python
+from spanlens import SpanlensClient
+
+client = SpanlensClient(api_key="sl_live_...")
+
+with client.start_trace("rag_pipeline", metadata={"user_id": "u_42"}) as trace:
+    with trace.span("retrieve", span_type="retrieval") as span:
+        docs = vector_store.similarity_search(query, k=5)
+        span.end(output={"doc_count": len(docs)})
+
+    with trace.span("generate", span_type="llm") as span:
+        response = openai_client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=build_prompt(query, docs),
+            extra_headers=span.trace_headers(),  # links proxy log to this span
+        )
+        usage = response.usage
+        span.end(
+            output=response.choices[0].message.content,
+            prompt_tokens=usage.prompt_tokens,
+            completion_tokens=usage.completion_tokens,
+            total_tokens=usage.total_tokens,
+        )
+```
+
+When a span / trace context manager exits with an exception, the span is
+automatically marked `error` with the exception message.
+
+### Helper: `observe_openai`
+
+Boilerplate-free version of the LLM span — auto-injects trace headers,
+auto-parses `usage`, and auto-ends the span:
+
+```python
+from spanlens import observe_openai
+
+result = observe_openai(trace, "answer", lambda headers:
+    openai_client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=messages,
+        extra_headers=headers,
+    )
+)
+```
+
+The same shape exists for Anthropic (`observe_anthropic`) and Gemini
+(`observe_gemini`).
+
+### Async support
+
+`observe()` and `observe_*()` detect coroutines automatically. Pass an async
+callable and `await` the result:
+
+```python
+async def go():
+    result = await observe_openai(trace, "answer", lambda h:
+        async_openai.chat.completions.create(..., extra_headers=h),
+    )
+```
+
+---
+
+## Configuration reference
+
+```python
+SpanlensClient(
+    api_key="sl_live_...",        # required
+    base_url=None,                 # default: https://spanlens-server.vercel.app
+    timeout_ms=3000,               # ingest timeout per call
+    silent=True,                   # swallow errors so observability never crashes user code
+    on_error=None,                 # callback (err, context) for non-silent monitoring
+)
+```
+
+Environment variables:
+
+* `SPANLENS_API_KEY` — picked up by `create_openai()`, `create_anthropic()`,
+  `create_gemini()` when `api_key=` is omitted.
+
+---
+
+## Why the SDK is non-blocking
+
+Every `trace.end()` / `span.end()` call returns immediately. Network I/O
+runs on a background thread pool with a configurable timeout, so:
+
+* Your hot path (the LLM call itself) is never slowed down.
+* The Spanlens server being slow / down does not crash your app.
+* Order is still preserved: a span POST always waits for its parent trace
+  POST to finish — the server's ownership check would otherwise 404 and the
+  span would be silently lost.
+
+For short-lived scripts, call `client.close()` before exit (or use
+`with SpanlensClient(...) as client:`) to drain the queue.
+
+---
+
+## Compatibility
+
+* Python 3.9, 3.10, 3.11, 3.12, 3.13
+* `openai` >= 1.0
+* `anthropic` >= 0.18
+* `google-generativeai` >= 0.5
+
+---
+
+## Self-hosting
+
+Point the SDK and proxy helpers at your own deployment:
+
+```python
+client = SpanlensClient(
+    api_key="...",
+    base_url="https://spanlens.mycompany.com",
+)
+
+openai = create_openai(base_url="https://spanlens.mycompany.com/proxy/openai/v1")
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Links
+
+* [Spanlens dashboard](https://spanlens.io)
+* [Proxy docs](https://spanlens.io/docs/proxy)
+* [TypeScript SDK](https://www.npmjs.com/package/@spanlens/sdk)
+* [GitHub](https://github.com/sunes26/Spanlens)

spanlens-0.1.0/README.md

@@ -0,0 +1,214 @@
+# Spanlens Python SDK
+
+LLM observability for Python. Trace agent runs, capture token usage and cost,
+and link calls back to your Spanlens dashboard with one line of code.
+
+[![PyPI](https://img.shields.io/pypi/v/spanlens.svg)](https://pypi.org/project/spanlens/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/pypi/pyversions/spanlens.svg)](https://pypi.org/project/spanlens/)
+
+> **Spanlens** is the open-source LLM observability platform. This is the
+> official Python SDK — for the dashboard, signup, and proxy docs, head to
+> [spanlens.io](https://spanlens.io).
+
+---
+
+## Install
+
+```bash
+pip install spanlens
+
+# Or with provider integrations:
+pip install "spanlens[openai]"
+pip install "spanlens[anthropic]"
+pip install "spanlens[gemini]"
+pip install "spanlens[all]"
+```
+
+## Two ways to use it
+
+| Mode | Best for | Setup |
+| --- | --- | --- |
+| **Proxy** | Single-call observability — drop-in for the OpenAI/Anthropic SDK | Replace `base_url` |
+| **SDK tracing** | Multi-step agents, RAG, tool calls, manual spans | `SpanlensClient(...)` |
+
+You can mix both. The proxy logs the raw request; the SDK groups multiple
+requests into a single trace with parent / child spans.
+
+---
+
+## Mode 1 — Proxy (zero-code)
+
+Get a Spanlens API key from your dashboard, then point your provider SDK at
+the Spanlens proxy:
+
+```python
+import os
+from spanlens.integrations.openai import create_openai
+
+# Reads SPANLENS_API_KEY from the environment
+client = create_openai()
+
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+Spanlens automatically logs the request, response, latency, token counts,
+and cost — viewable in the dashboard under **Requests**.
+
+### Tagging requests with a prompt version
+
+```python
+from spanlens.integrations.openai import create_openai, with_prompt_version
+
+client = create_openai()
+res = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[...],
+    **with_prompt_version("chatbot-system@3"),
+)
+```
+
+The same pattern works for Anthropic — see
+[`spanlens.integrations.anthropic`](./spanlens/integrations/anthropic.py).
+
+---
+
+## Mode 2 — SDK tracing (multi-step agents)
+
+Use the SDK when one user request spans multiple LLM calls, retrieval, tool
+use, etc. Spans appear nested under a single trace in the dashboard.
+
+```python
+from spanlens import SpanlensClient
+
+client = SpanlensClient(api_key="sl_live_...")
+
+with client.start_trace("rag_pipeline", metadata={"user_id": "u_42"}) as trace:
+    with trace.span("retrieve", span_type="retrieval") as span:
+        docs = vector_store.similarity_search(query, k=5)
+        span.end(output={"doc_count": len(docs)})
+
+    with trace.span("generate", span_type="llm") as span:
+        response = openai_client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=build_prompt(query, docs),
+            extra_headers=span.trace_headers(),  # links proxy log to this span
+        )
+        usage = response.usage
+        span.end(
+            output=response.choices[0].message.content,
+            prompt_tokens=usage.prompt_tokens,
+            completion_tokens=usage.completion_tokens,
+            total_tokens=usage.total_tokens,
+        )
+```
+
+When a span / trace context manager exits with an exception, the span is
+automatically marked `error` with the exception message.
+
+### Helper: `observe_openai`
+
+Boilerplate-free version of the LLM span — auto-injects trace headers,
+auto-parses `usage`, and auto-ends the span:
+
+```python
+from spanlens import observe_openai
+
+result = observe_openai(trace, "answer", lambda headers:
+    openai_client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=messages,
+        extra_headers=headers,
+    )
+)
+```
+
+The same shape exists for Anthropic (`observe_anthropic`) and Gemini
+(`observe_gemini`).
+
+### Async support
+
+`observe()` and `observe_*()` detect coroutines automatically. Pass an async
+callable and `await` the result:
+
+```python
+async def go():
+    result = await observe_openai(trace, "answer", lambda h:
+        async_openai.chat.completions.create(..., extra_headers=h),
+    )
+```
+
+---
+
+## Configuration reference
+
+```python
+SpanlensClient(
+    api_key="sl_live_...",        # required
+    base_url=None,                 # default: https://spanlens-server.vercel.app
+    timeout_ms=3000,               # ingest timeout per call
+    silent=True,                   # swallow errors so observability never crashes user code
+    on_error=None,                 # callback (err, context) for non-silent monitoring
+)
+```
+
+Environment variables:
+
+* `SPANLENS_API_KEY` — picked up by `create_openai()`, `create_anthropic()`,
+  `create_gemini()` when `api_key=` is omitted.
+
+---
+
+## Why the SDK is non-blocking
+
+Every `trace.end()` / `span.end()` call returns immediately. Network I/O
+runs on a background thread pool with a configurable timeout, so:
+
+* Your hot path (the LLM call itself) is never slowed down.
+* The Spanlens server being slow / down does not crash your app.
+* Order is still preserved: a span POST always waits for its parent trace
+  POST to finish — the server's ownership check would otherwise 404 and the
+  span would be silently lost.
+
+For short-lived scripts, call `client.close()` before exit (or use
+`with SpanlensClient(...) as client:`) to drain the queue.
+
+---
+
+## Compatibility
+
+* Python 3.9, 3.10, 3.11, 3.12, 3.13
+* `openai` >= 1.0
+* `anthropic` >= 0.18
+* `google-generativeai` >= 0.5
+
+---
+
+## Self-hosting
+
+Point the SDK and proxy helpers at your own deployment:
+
+```python
+client = SpanlensClient(
+    api_key="...",
+    base_url="https://spanlens.mycompany.com",
+)
+
+openai = create_openai(base_url="https://spanlens.mycompany.com/proxy/openai/v1")
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Links
+
+* [Spanlens dashboard](https://spanlens.io)
+* [Proxy docs](https://spanlens.io/docs/proxy)
+* [TypeScript SDK](https://www.npmjs.com/package/@spanlens/sdk)
+* [GitHub](https://github.com/sunes26/Spanlens)

spanlens-0.1.0/pyproject.toml

@@ -0,0 +1,113 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spanlens"
+version = "0.1.0"
+description = "Spanlens SDK — agent tracing, LLM usage capture, and cost observability for Python."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Spanlens", email = "support@spanlens.io" }]
+keywords = [
+    "llm",
+    "llm-observability",
+    "llm-monitoring",
+    "llm-tracing",
+    "openai",
+    "anthropic",
+    "claude",
+    "gemini",
+    "observability",
+    "tracing",
+    "agent-tracing",
+    "ai-agents",
+    "cost-tracking",
+    "token-tracking",
+    "langchain",
+    "llamaindex",
+    "helicone-alternative",
+    "langfuse-alternative",
+    "langsmith-alternative",
+    "proxy",
+    "spanlens",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.18.0"]
+gemini = ["google-generativeai>=0.5.0"]
+all = [
+    "openai>=1.0.0",
+    "anthropic>=0.18.0",
+    "google-generativeai>=0.5.0",
+]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-mock>=3.12.0",
+    "respx>=0.20.0",
+    "ruff>=0.4.0",
+    "mypy>=1.8.0",
+]
+
+[project.urls]
+Homepage = "https://spanlens.io"
+Documentation = "https://spanlens.io/docs/sdk"
+Repository = "https://github.com/sunes26/Spanlens"
+Issues = "https://github.com/sunes26/Spanlens/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["spanlens"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "spanlens",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = ["error::DeprecationWarning"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N"]
+# UP006/UP007/UP035/UP045 push PEP 604 / PEP 585 syntax that we deliberately
+# avoid: while ``from __future__ import annotations`` makes ``list[int]`` and
+# ``X | None`` legal at parse time on Python 3.9, runtime introspection
+# (``typing.get_type_hints``) still breaks. Stick with ``Optional[X]`` /
+# ``List[X]`` until the minimum supported version is 3.10.
+ignore = ["E501", "UP006", "UP007", "UP035", "UP045"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true