seerlens 0.2.0__tar.gz

seerlens-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+bin/
+obj/
+*.user
+.vs/
+
+# dashboard
+node_modules/
+dashboard/dist/
+src/Seerlens.Collector/ui/
+
+# local data
+*.db
+*.db-shm
+*.db-wal
+
+# local provider keys
+.env.local
+
+# build artifacts
+nupkg/
+dist/
+
+# python
+__pycache__/
+*.pyc

seerlens-0.2.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: seerlens
+Version: 0.2.0
+Summary: Send your Python app's LLM calls to Seerlens, the local DevTools for AI calls.
+Project-URL: Homepage, https://github.com/eladser/seerlens
+Author: Elad Sertshuk
+License-Expression: MIT
+Keywords: ai,llm,observability,opentelemetry,tracing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# seerlens (Python)
+
+Send your Python app's LLM calls to [Seerlens](https://github.com/eladser/seerlens). Traces go out as OpenTelemetry GenAI spans, so they land in the same dashboard as the .NET ones.
+
+```python
+import seerlens
+
+seerlens.configure("http://localhost:5005")
+
+with seerlens.trace("answer ticket", model="gpt-4o") as span:
+    reply = my_llm(prompt)
+    span.complete(prompt=prompt, completion=reply, input_tokens=40, output_tokens=12)
+
+seerlens.flush()  # before a short script exits
+```
+
+Or record a call you already made:
+
+```python
+seerlens.record(model="gpt-4o", prompt="hi", completion="hello",
+                input_tokens=10, output_tokens=5, duration_ms=820)
+```
+
+Traces are sent on a background thread. If the collector is down the trace is dropped; it never blocks or throws into your app.
+
+No third-party dependencies. Run the example against a running collector:
+
+```bash
+python example.py
+```

seerlens-0.2.0/README.md

@@ -0,0 +1,30 @@
+# seerlens (Python)
+
+Send your Python app's LLM calls to [Seerlens](https://github.com/eladser/seerlens). Traces go out as OpenTelemetry GenAI spans, so they land in the same dashboard as the .NET ones.
+
+```python
+import seerlens
+
+seerlens.configure("http://localhost:5005")
+
+with seerlens.trace("answer ticket", model="gpt-4o") as span:
+    reply = my_llm(prompt)
+    span.complete(prompt=prompt, completion=reply, input_tokens=40, output_tokens=12)
+
+seerlens.flush()  # before a short script exits
+```
+
+Or record a call you already made:
+
+```python
+seerlens.record(model="gpt-4o", prompt="hi", completion="hello",
+                input_tokens=10, output_tokens=5, duration_ms=820)
+```
+
+Traces are sent on a background thread. If the collector is down the trace is dropped; it never blocks or throws into your app.
+
+No third-party dependencies. Run the example against a running collector:
+
+```bash
+python example.py
+```

seerlens-0.2.0/example.py

@@ -0,0 +1,18 @@
+import os
+
+import seerlens
+
+seerlens.configure(os.environ.get("SEERLENS_URL", "http://localhost:5005"))
+
+# Pretend these came back from your LLM client.
+with seerlens.trace("answer support ticket", model="gpt-4o") as span:
+    reply = "Your order shipped and arrives Thursday."
+    span.complete(prompt="Where is my order #5521?", completion=reply,
+                  input_tokens=40, output_tokens=12)
+
+seerlens.record(model="claude-3-5-sonnet", prompt="Summarize the update.",
+                completion="Numbers up, churn down.", input_tokens=120,
+                output_tokens=18, duration_ms=430)
+
+seerlens.flush()
+print("sent traces to Seerlens")

seerlens-0.2.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "seerlens"
+version = "0.2.0"
+description = "Send your Python app's LLM calls to Seerlens, the local DevTools for AI calls."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Elad Sertshuk" }]
+keywords = ["llm", "ai", "observability", "tracing", "opentelemetry"]
+
+[project.urls]
+Homepage = "https://github.com/eladser/seerlens"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

seerlens-0.2.0/seerlens/__init__.py

@@ -0,0 +1,129 @@
+"""Send your Python app's LLM calls to Seerlens.
+
+    import seerlens
+    seerlens.configure("http://localhost:5005")
+
+    with seerlens.trace("answer ticket", model="gpt-4o") as span:
+        reply = my_llm(prompt)
+        span.complete(prompt=prompt, completion=reply, input_tokens=40, output_tokens=12)
+
+    seerlens.flush()  # before a short script exits
+
+Traces are sent as OpenTelemetry GenAI spans, on a background thread. If the
+collector is down the trace is dropped; it never blocks or breaks your app.
+"""
+
+import json
+import os
+import threading
+import time
+import urllib.request
+
+__all__ = ["configure", "record", "trace", "flush"]
+
+_endpoint = None
+_threads = []
+
+
+def configure(collector_url):
+    global _endpoint
+    _endpoint = collector_url.rstrip("/") + "/v1/traces"
+
+
+def record(model, prompt="", completion="", input_tokens=None, output_tokens=None,
+           duration_ms=0.0, system=None, name=None):
+    """Record one finished LLM call."""
+    end = time.time_ns()
+    start = end - int(duration_ms * 1_000_000)
+    span = {
+        "traceId": _hexid(16),
+        "spanId": _hexid(8),
+        "parentSpanId": "",
+        "name": name or f"chat: {model}",
+        "startTimeUnixNano": str(start),
+        "endTimeUnixNano": str(end),
+        "attributes": _attrs(model, prompt, completion, input_tokens, output_tokens, system),
+        "status": {"code": 1},
+    }
+    _send({"resourceSpans": [{"scopeSpans": [{"spans": [span]}]}]})
+
+
+class trace:
+    """Context manager that times a call and records it on exit."""
+
+    def __init__(self, name, model, system=None):
+        self._name = name
+        self._model = model
+        self._system = system
+        self._prompt = ""
+        self._completion = ""
+        self._in = None
+        self._out = None
+
+    def __enter__(self):
+        self._t0 = time.perf_counter()
+        return self
+
+    def complete(self, prompt="", completion="", input_tokens=None, output_tokens=None):
+        self._prompt = prompt
+        self._completion = completion
+        self._in = input_tokens
+        self._out = output_tokens
+
+    def __exit__(self, *exc):
+        ms = (time.perf_counter() - self._t0) * 1000
+        record(self._model, self._prompt, self._completion, self._in, self._out,
+               ms, self._system, self._name)
+        return False
+
+
+def flush(timeout=3.0):
+    """Wait for any in-flight traces to finish sending. Call before a short script exits."""
+    for t in list(_threads):
+        t.join(timeout)
+
+
+def _send(payload):
+    if not _endpoint:
+        return
+    t = threading.Thread(target=_post, args=(payload,), daemon=True)
+    _threads.append(t)
+    t.start()
+
+
+def _post(payload):
+    try:
+        data = json.dumps(payload).encode()
+        req = urllib.request.Request(_endpoint, data=data, headers={"Content-Type": "application/json"})
+        urllib.request.urlopen(req, timeout=5).close()
+    except Exception:
+        pass  # never break the host app
+
+
+def _attrs(model, prompt, completion, in_tokens, out_tokens, system):
+    pairs = [
+        ("gen_ai.system", system or _provider(model)),
+        ("gen_ai.request.model", model),
+        ("gen_ai.prompt", prompt),
+        ("gen_ai.completion", completion),
+    ]
+    out = [{"key": k, "value": {"stringValue": str(v)}} for k, v in pairs if v]
+    for k, v in (("gen_ai.usage.input_tokens", in_tokens), ("gen_ai.usage.output_tokens", out_tokens)):
+        if v is not None:
+            out.append({"key": k, "value": {"intValue": str(v)}})
+    return out
+
+
+def _provider(model):
+    m = (model or "").lower()
+    if m.startswith(("gpt", "o1", "o3")):
+        return "openai"
+    if "claude" in m:
+        return "anthropic"
+    if "gemini" in m:
+        return "google"
+    return None
+
+
+def _hexid(n):
+    return os.urandom(n).hex()

seerlens-0.2.0/test_seerlens.py

@@ -0,0 +1,42 @@
+import unittest
+
+import seerlens
+
+
+class SeerlensTests(unittest.TestCase):
+    def setUp(self):
+        self.sent = []
+        seerlens._send = lambda payload: self.sent.append(payload)  # bypass the network
+
+    def _span(self):
+        return self.sent[-1]["resourceSpans"][0]["scopeSpans"][0]["spans"][0]
+
+    def _attrs(self):
+        return {a["key"]: a["value"] for a in self._span()["attributes"]}
+
+    def test_record_builds_a_genai_span(self):
+        seerlens.record(model="gpt-4o", prompt="hi", completion="hello",
+                        input_tokens=10, output_tokens=5, duration_ms=200)
+
+        attrs = self._attrs()
+        self.assertEqual(attrs["gen_ai.request.model"]["stringValue"], "gpt-4o")
+        self.assertEqual(attrs["gen_ai.system"]["stringValue"], "openai")
+        self.assertEqual(attrs["gen_ai.usage.input_tokens"]["intValue"], "10")
+        self.assertEqual(attrs["gen_ai.prompt"]["stringValue"], "hi")
+
+    def test_duration_is_reflected_in_span_times(self):
+        seerlens.record(model="gpt-4o", duration_ms=200)
+        span = self._span()
+        elapsed_ns = int(span["endTimeUnixNano"]) - int(span["startTimeUnixNano"])
+        self.assertEqual(elapsed_ns, 200 * 1_000_000)
+
+    def test_trace_context_manager_records_with_inferred_provider(self):
+        with seerlens.trace("ticket", model="claude-3-5-sonnet") as span:
+            span.complete(prompt="q", completion="a", input_tokens=3, output_tokens=2)
+
+        self.assertEqual(self._span()["name"], "ticket")
+        self.assertEqual(self._attrs()["gen_ai.system"]["stringValue"], "anthropic")
+
+
+if __name__ == "__main__":
+    unittest.main()