logspine 0.1.0__tar.gz

logspine-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# dependencies
+node_modules/
+.pnpm-store/
+
+# build outputs
+dist/
+.next/
+.turbo/
+out/
+build/
+
+# env
+.env
+.env.local
+.env.*.local
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# editor
+.vscode/
+.idea/
+*.swp
+
+# wrangler / CF
+.wrangler/
+.dev.vars
+
+# tsbuildinfo
+*.tsbuildinfo
+
+# coverage
+coverage/
+
+# Tinybird CLI local state (contains admin token!)
+.tinyb
+.tinyenv
+
+# pnpm temp files from interrupted installs
+_tmp_*
+
+# outreach tool outputs (may contain PII, large files)
+tools/helicone-stargazers-raw.json
+tools/helicone-stargazers-filtered.json
+tools/helicone-stargazers-filtered.csv

logspine-0.1.0/LICENSE

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

logspine-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include logspine *.py

logspine-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: logspine
+Version: 0.1.0
+Summary: Drop-in observability for AI agents — Python SDK
+Project-URL: Homepage, https://www.logspine.dev
+Project-URL: Documentation, https://www.logspine.dev/docs
+Project-URL: Repository, https://github.com/logspine-dev/logspine
+Author-email: Adam Kallen <hello@logspine.dev>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# logspine · Python SDK
+
+Drop-in observability for AI agents. Track every OpenAI and Anthropic call
+with cost, tokens, and latency — no code changes to your prompts.
+
+Full docs: [logspine.dev/docs](https://www.logspine.dev/docs)
+
+---
+
+## Install
+
+```bash
+pip install logspine
+
+# with OpenAI support
+pip install "logspine[openai]"
+
+# with Anthropic support
+pip install "logspine[anthropic]"
+
+# both
+pip install "logspine[openai,anthropic]"
+```
+
+---
+
+## Quick start — OpenAI
+
+```python
+import openai
+from logspine import LogspineClient
+
+logspine = LogspineClient(api_key="lsk_live_...")
+client = logspine.instrument_openai(openai.OpenAI())
+
+# Every call is now tracked automatically
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Say hello in five words."}],
+)
+print(response.choices[0].message.content)
+
+logspine.flush()  # call before process exit
+```
+
+---
+
+## Quick start — Anthropic
+
+```python
+import anthropic
+from logspine import LogspineClient
+
+logspine = LogspineClient(api_key="lsk_live_...")
+client = logspine.instrument_anthropic(anthropic.Anthropic())
+
+response = client.messages.create(
+    model="claude-sonnet-4-5",
+    max_tokens=256,
+    messages=[{"role": "user", "content": "Say hello in five words."}],
+)
+print(response.content[0].text)
+
+logspine.flush()
+```
+
+---
+
+## Optional span metadata
+
+Pass a `logspine` dict as an extra kwarg to tag individual calls:
+
+```python
+client.chat.completions.create(
+    model="gpt-4o",
+    messages=[...],
+    logspine={
+        "trace_id": "my-session-abc123",
+        "name": "summarise_document",
+        "user_id": "usr_42",
+    },
+)
+```
+
+---
+
+## Links
+
+- [Docs](https://www.logspine.dev/docs)
+- [Dashboard](https://www.logspine.dev/dashboard)
+- [Pricing](https://www.logspine.dev/pricing)
+- [GitHub](https://github.com/logspine-dev/logspine)

logspine-0.1.0/README.md

@@ -0,0 +1,92 @@
+# logspine · Python SDK
+
+Drop-in observability for AI agents. Track every OpenAI and Anthropic call
+with cost, tokens, and latency — no code changes to your prompts.
+
+Full docs: [logspine.dev/docs](https://www.logspine.dev/docs)
+
+---
+
+## Install
+
+```bash
+pip install logspine
+
+# with OpenAI support
+pip install "logspine[openai]"
+
+# with Anthropic support
+pip install "logspine[anthropic]"
+
+# both
+pip install "logspine[openai,anthropic]"
+```
+
+---
+
+## Quick start — OpenAI
+
+```python
+import openai
+from logspine import LogspineClient
+
+logspine = LogspineClient(api_key="lsk_live_...")
+client = logspine.instrument_openai(openai.OpenAI())
+
+# Every call is now tracked automatically
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Say hello in five words."}],
+)
+print(response.choices[0].message.content)
+
+logspine.flush()  # call before process exit
+```
+
+---
+
+## Quick start — Anthropic
+
+```python
+import anthropic
+from logspine import LogspineClient
+
+logspine = LogspineClient(api_key="lsk_live_...")
+client = logspine.instrument_anthropic(anthropic.Anthropic())
+
+response = client.messages.create(
+    model="claude-sonnet-4-5",
+    max_tokens=256,
+    messages=[{"role": "user", "content": "Say hello in five words."}],
+)
+print(response.content[0].text)
+
+logspine.flush()
+```
+
+---
+
+## Optional span metadata
+
+Pass a `logspine` dict as an extra kwarg to tag individual calls:
+
+```python
+client.chat.completions.create(
+    model="gpt-4o",
+    messages=[...],
+    logspine={
+        "trace_id": "my-session-abc123",
+        "name": "summarise_document",
+        "user_id": "usr_42",
+    },
+)
+```
+
+---
+
+## Links
+
+- [Docs](https://www.logspine.dev/docs)
+- [Dashboard](https://www.logspine.dev/dashboard)
+- [Pricing](https://www.logspine.dev/pricing)
+- [GitHub](https://github.com/logspine-dev/logspine)

logspine-0.1.0/logspine/__init__.py

@@ -0,0 +1,4 @@
+from .client import LogspineClient
+from ._version import __version__
+
+__all__ = ["LogspineClient", "__version__"]

logspine-0.1.0/logspine/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

logspine-0.1.0/logspine/client.py

@@ -0,0 +1,117 @@
+"""
+Logspine Python SDK — AI agent observability.
+https://www.logspine.dev
+"""
+
+from __future__ import annotations
+
+import time
+import json
+import threading
+from typing import Any, Optional
+from ._version import __version__
+
+DEFAULT_ENDPOINT = "https://ingest.logspine.dev"
+FLUSH_INTERVAL = 2.0  # seconds
+MAX_BATCH_SIZE = 100
+
+
+class LogspineClient:
+    """
+    Drop-in observability client for AI agents.
+
+    Usage::
+
+        from logspine import LogspineClient
+        import openai
+
+        logspine = LogspineClient(api_key="lsk_live_...")
+        client = logspine.instrument_openai(openai.OpenAI())
+
+        # Every call is now tracked
+        response = client.chat.completions.create(...)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: str = DEFAULT_ENDPOINT,
+        flush_interval: float = FLUSH_INTERVAL,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._endpoint = endpoint.rstrip("/")
+        self._queue: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._flush_interval = flush_interval
+        self._timer: Optional[threading.Timer] = None
+        self._schedule_flush()
+
+    # ── Instrumentation ──────────────────────────────────────────────
+
+    def instrument_openai(self, client: Any) -> Any:
+        """Wrap an OpenAI client to track every call automatically."""
+        from .instrumentation.openai import instrument
+        return instrument(client, self)
+
+    def instrument_anthropic(self, client: Any) -> Any:
+        """Wrap an Anthropic client to track every call automatically."""
+        from .instrumentation.anthropic import instrument
+        return instrument(client, self)
+
+    # ── Span tracking ────────────────────────────────────────────────
+
+    def _record_span(self, span: dict[str, Any]) -> None:
+        with self._lock:
+            self._queue.append(span)
+            if len(self._queue) >= MAX_BATCH_SIZE:
+                self._flush_locked()
+
+    def flush(self) -> None:
+        """Send all buffered spans immediately. Call before process exit."""
+        with self._lock:
+            self._flush_locked()
+
+    def _flush_locked(self) -> None:
+        if not self._queue:
+            return
+        batch = self._queue[:]
+        self._queue.clear()
+        # Fire and forget in a thread to not block the caller
+        threading.Thread(target=self._send, args=(batch,), daemon=True).start()
+
+    def _schedule_flush(self) -> None:
+        self._timer = threading.Timer(self._flush_interval, self._auto_flush)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _auto_flush(self) -> None:
+        self.flush()
+        self._schedule_flush()
+
+    def _send(self, spans: list[dict[str, Any]]) -> None:
+        import urllib.request
+        import urllib.error
+
+        payload = json.dumps({"spans": spans}).encode()
+        req = urllib.request.Request(
+            f"{self._endpoint}/v1/ingest",
+            data=payload,
+            headers={
+                "Content-Type": "application/json",
+                "x-logspine-key": self._api_key,
+                "x-logspine-sdk": f"python/{__version__}",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=5):
+                pass
+        except Exception:
+            pass  # Never raise — observability must never break the app
+
+    def __del__(self) -> None:
+        if self._timer:
+            self._timer.cancel()
+        self.flush()

logspine-0.1.0/logspine/instrumentation/anthropic.py

@@ -0,0 +1,109 @@
+"""Anthropic instrumentation for Logspine."""
+
+from __future__ import annotations
+
+import time
+import json
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import LogspineClient
+
+# Cost per 1M tokens in USD (as of mid-2026)
+PRICING: dict[str, dict[str, float]] = {
+    "claude-opus-4":      {"input": 15.00, "output": 75.00},
+    "claude-sonnet-4":    {"input": 3.00,  "output": 15.00},
+    "claude-3-5-sonnet":  {"input": 3.00,  "output": 15.00},
+    "claude-3-5-haiku":   {"input": 0.80,  "output": 4.00},
+    "claude-3-haiku":     {"input": 0.25,  "output": 1.25},
+}
+
+
+def _cost(model: str, input_tokens: int, output_tokens: int) -> float:
+    key = next((k for k in PRICING if model.startswith(k)), None)
+    if not key:
+        return 0.0
+    p = PRICING[key]
+    return (input_tokens * p["input"] + output_tokens * p["output"]) / 1_000_000
+
+
+def instrument(anthropic_client: Any, logspine: "LogspineClient") -> Any:
+    """Wrap an anthropic.Anthropic() instance to track every LLM call."""
+    original_create = anthropic_client.messages.create
+
+    def tracked_create(*args: Any, **kwargs: Any) -> Any:
+        meta: dict[str, Any] = kwargs.pop("logspine", {}) or {}
+        start = time.time()
+        error_msg = ""
+        response = None
+
+        try:
+            response = original_create(*args, **kwargs)
+        except Exception as exc:
+            error_msg = str(exc)
+            raise
+        finally:
+            end = time.time()
+
+            model = kwargs.get("model", "")
+            messages = kwargs.get("messages", [])
+            system = kwargs.get("system", "")
+
+            input_tokens = 0
+            output_tokens = 0
+            output_text = ""
+
+            if response is not None:
+                usage = getattr(response, "usage", None)
+                if usage:
+                    input_tokens = getattr(usage, "input_tokens", 0) or 0
+                    output_tokens = getattr(usage, "output_tokens", 0) or 0
+                content = getattr(response, "content", [])
+                if content:
+                    first = content[0]
+                    output_text = getattr(first, "text", "") or ""
+
+            cost = _cost(model, input_tokens, output_tokens)
+
+            # Build input representation — include system prompt if present
+            input_payload: dict[str, Any] = {"messages": messages}
+            if system:
+                input_payload["system"] = system
+
+            span: dict[str, Any] = {
+                "trace_id": meta.get("trace_id", _new_id()),
+                "span_id": _new_id(),
+                "parent_id": meta.get("parent_id", ""),
+                "name": meta.get("name", f"messages/{model}"),
+                "start_ts": _iso(start),
+                "end_ts": _iso(end),
+                "provider": "anthropic",
+                "model": model,
+                "prompt_tokens": input_tokens,
+                "completion_tokens": output_tokens,
+                "cost_usd": cost,
+                "status": "error" if error_msg else "ok",
+                "error": error_msg,
+                "input": json.dumps(input_payload)[:65536],
+                "output": output_text[:65536],
+                "metadata": json.dumps({
+                    k: v for k, v in meta.items()
+                    if k not in ("trace_id", "span_id", "parent_id", "name")
+                }),
+            }
+            logspine._record_span(span)
+
+        return response
+
+    anthropic_client.messages.create = tracked_create
+    return anthropic_client
+
+
+def _new_id() -> str:
+    import uuid
+    return str(uuid.uuid4())
+
+
+def _iso(ts: float) -> str:
+    from datetime import datetime, timezone
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()

logspine-0.1.0/logspine/instrumentation/openai.py

@@ -0,0 +1,106 @@
+"""OpenAI instrumentation for Logspine."""
+
+from __future__ import annotations
+
+import time
+import json
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import LogspineClient
+
+# Cost per 1M tokens in USD (as of mid-2026)
+PRICING: dict[str, dict[str, float]] = {
+    "gpt-4o":           {"input": 2.50,  "output": 10.00},
+    "gpt-4o-mini":      {"input": 0.15,  "output": 0.60},
+    "gpt-4-turbo":      {"input": 10.00, "output": 30.00},
+    "gpt-3.5-turbo":    {"input": 0.50,  "output": 1.50},
+    "o1":               {"input": 15.00, "output": 60.00},
+    "o1-mini":          {"input": 3.00,  "output": 12.00},
+}
+
+
+def _cost(model: str, prompt: int, completion: int) -> float:
+    key = next((k for k in PRICING if model.startswith(k)), None)
+    if not key:
+        return 0.0
+    p = PRICING[key]
+    return (prompt * p["input"] + completion * p["output"]) / 1_000_000
+
+
+def instrument(openai_client: Any, logspine: "LogspineClient") -> Any:
+    """Wrap an openai.OpenAI() instance to track every LLM call."""
+    original_create = openai_client.chat.completions.create
+
+    def tracked_create(*args: Any, **kwargs: Any) -> Any:
+        meta: dict[str, Any] = kwargs.pop("logspine", {}) or {}
+        start = time.time()
+        error_msg = ""
+        response = None
+
+        try:
+            response = original_create(*args, **kwargs)
+        except Exception as exc:
+            error_msg = str(exc)
+            raise
+        finally:
+            end = time.time()
+            duration_ms = int((end - start) * 1000)
+
+            model = kwargs.get("model", "")
+            messages = kwargs.get("messages", [])
+
+            prompt_tokens = 0
+            completion_tokens = 0
+            output_text = ""
+
+            if response is not None:
+                usage = getattr(response, "usage", None)
+                if usage:
+                    prompt_tokens = getattr(usage, "prompt_tokens", 0) or 0
+                    completion_tokens = getattr(usage, "completion_tokens", 0) or 0
+                choices = getattr(response, "choices", [])
+                if choices:
+                    msg = getattr(choices[0], "message", None)
+                    if msg:
+                        output_text = getattr(msg, "content", "") or ""
+
+            cost = _cost(model, prompt_tokens, completion_tokens)
+
+            span: dict[str, Any] = {
+                "trace_id": meta.get("trace_id", _new_id()),
+                "span_id": _new_id(),
+                "parent_id": meta.get("parent_id", ""),
+                "name": meta.get("name", f"chat/{model}"),
+                "start_ts": _iso(start),
+                "end_ts": _iso(end),
+                "provider": "openai",
+                "model": model,
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens,
+                "cost_usd": cost,
+                "status": "error" if error_msg else "ok",
+                "error": error_msg,
+                "input": json.dumps(messages)[:65536],
+                "output": output_text[:65536],
+                "metadata": json.dumps({
+                    k: v for k, v in meta.items()
+                    if k not in ("trace_id", "span_id", "parent_id", "name")
+                }),
+            }
+            logspine._record_span(span)
+
+        return response
+
+    openai_client.chat.completions.create = tracked_create
+    return openai_client
+
+
+def _new_id() -> str:
+    import uuid
+    return str(uuid.uuid4())
+
+
+def _iso(ts: float) -> str:
+    from datetime import datetime, timezone
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()

logspine-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "logspine"
+version = "0.1.0"
+description = "Drop-in observability for AI agents — Python SDK"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Adam Kallen", email = "hello@logspine.dev" }]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.25.0"]
+
+[project.urls]
+Homepage = "https://www.logspine.dev"
+Documentation = "https://www.logspine.dev/docs"
+Repository = "https://github.com/logspine-dev/logspine"