loopview-sdk 0.2.0__py3-none-any.whl

loopview_sdk/__init__.py

@@ -0,0 +1,19 @@
+"""loopview-sdk: connect an agent to loopview.
+
+    import loopview_sdk
+    loopview_sdk.connect()          # exporter, instrumentation, content, flush at exit
+
+    with loopview_sdk.agent("name"):  # only for hand-written loops with no agent span
+        ...
+
+    @loopview_sdk.tool                # optional: exact timing and errors for your tools
+    def get_weather(city): ...
+
+LiveStartProcessor, the start reporter connect() adds, can also be used on its own.
+"""
+
+from loopview_sdk._live import LiveStartProcessor
+from loopview_sdk.connect import agent, rank_instrumentors, connect, tool
+
+__all__ = ["LiveStartProcessor", "agent", "rank_instrumentors", "connect", "tool"]
+__version__ = "0.2.0"

loopview_sdk/_live.py

@@ -0,0 +1,136 @@
+"""loopview-sdk: tell loopview when spans *start*, for true real-time views.
+
+Standard OpenTelemetry exporters send a span only when it ends, so on its own
+loopview sees a step only after it finished (it infers running parents from
+their finished children). Add this processor next to your normal exporter and
+loopview also hears about every span the moment it starts:
+
+    from loopview_sdk import LiveStartProcessor
+    provider.add_span_processor(LiveStartProcessor())
+
+It only reports starts; your normal exporter still sends the finished spans.
+Reports are batched every 50 ms and sent from a background thread, so the
+agent never waits on loopview. If loopview isn't running, reports are dropped.
+
+Dependencies: opentelemetry-sdk only (HTTP is done with the standard library).
+"""
+
+import json
+import os
+import queue
+import threading
+import urllib.request
+from typing import Any
+
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+
+DEFAULT_ENDPOINT = "http://127.0.0.1:4318/v1/loopview/span-starts"
+_KIND = {"INTERNAL": 1, "SERVER": 2, "CLIENT": 3, "PRODUCER": 4, "CONSUMER": 5}
+
+
+class LiveStartProcessor(SpanProcessor):
+    def __init__(self, endpoint: str | None = None, interval_s: float = 0.05) -> None:
+        self.endpoint = endpoint or os.environ.get("LOOPVIEW_STARTS_ENDPOINT", DEFAULT_ENDPOINT)
+        self.interval_s = interval_s
+        self._queue: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=10_000)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, name="loopview-starts", daemon=True)
+        self._thread.start()
+
+    # --- SpanProcessor -----------------------------------------------------------------
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        try:
+            self._queue.put_nowait(_encode(span))
+        except queue.Full:
+            pass  # never slow the agent down
+
+    def on_end(self, span: ReadableSpan) -> None:
+        pass  # finished spans go through the user's normal exporter
+
+    def shutdown(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=2)
+        self._flush()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        self._flush()
+        return True
+
+    # --- background sending --------------------------------------------------------------
+
+    def _run(self) -> None:
+        while not self._stop.wait(self.interval_s):
+            self._flush()
+
+    def _flush(self) -> None:
+        batch: list[dict[str, Any]] = []
+        while True:
+            try:
+                batch.append(self._queue.get_nowait())
+            except queue.Empty:
+                break
+        if not batch:
+            return
+        body = json.dumps(_request(batch)).encode()
+        request = urllib.request.Request(
+            self.endpoint, data=body, headers={"Content-Type": "application/json"}
+        )
+        try:
+            urllib.request.urlopen(request, timeout=2).close()
+        except OSError:
+            pass  # loopview not running: drop, like a best-effort exporter
+
+
+# --- OTLP/JSON encoding of a just-started span ---------------------------------------------
+
+
+def _encode(span: Span) -> dict[str, Any]:
+    ctx = span.get_span_context()
+    encoded: dict[str, Any] = {
+        "traceId": format(ctx.trace_id, "032x"),
+        "spanId": format(ctx.span_id, "016x"),
+        "name": span.name,
+        "kind": _KIND.get(span.kind.name, 0),
+        "startTimeUnixNano": str(span.start_time or 0),
+        "attributes": _kv(dict(span.attributes or {})),
+    }
+    if span.parent is not None:
+        encoded["parentSpanId"] = format(span.parent.span_id, "016x")
+    scope = span.instrumentation_scope
+    return {
+        "span": encoded,
+        "resource": dict(span.resource.attributes) if span.resource else {},
+        "scope": (scope.name, scope.version or "") if scope else ("", ""),
+    }
+
+
+def _request(batch: list[dict[str, Any]]) -> dict[str, Any]:
+    """Group encoded spans by resource and scope into one ExportTraceServiceRequest."""
+    groups: dict[str, dict[str, Any]] = {}
+    for item in batch:
+        key = json.dumps([item["resource"], item["scope"]], sort_keys=True, default=str)
+        group = groups.setdefault(key, {
+            "resource": {"attributes": _kv(item["resource"])},
+            "scopeSpans": [{"scope": {"name": item["scope"][0], "version": item["scope"][1]},
+                            "spans": []}],
+        })
+        group["scopeSpans"][0]["spans"].append(item["span"])
+    return {"resourceSpans": list(groups.values())}
+
+
+def _kv(attributes: dict[str, Any]) -> list[dict[str, Any]]:
+    return [{"key": k, "value": _value(v)} for k, v in attributes.items()]
+
+
+def _value(v: Any) -> dict[str, Any]:
+    if isinstance(v, bool):
+        return {"boolValue": v}
+    if isinstance(v, int):
+        return {"intValue": str(v)}
+    if isinstance(v, float):
+        return {"doubleValue": v}
+    if isinstance(v, (list, tuple)):
+        return {"arrayValue": {"values": [_value(x) for x in v]}}
+    return {"stringValue": str(v)}

loopview_sdk/connect.py

@@ -0,0 +1,285 @@
+"""Send an agent's traces to loopview with one call, whatever it is built with.
+
+    import loopview_sdk
+    loopview_sdk.connect()
+
+It does what every agent needs, so nothing else is required in most cases:
+- an OTLP/HTTP exporter to loopview, sending every 100 ms, and LiveStartProcessor
+  so steps light up when they start;
+- the instrumentation of every agent framework or model SDK that is installed:
+  each OpenTelemetry instrumentor package registers itself (the
+  `opentelemetry_instrumentor` entry point), so they are found, not listed here.
+  When several cover the same library (OpenInference's and OpenTelemetry's for
+  the OpenAI SDK), OpenInference's is tried first: it records message content and
+  tool definitions. If it doesn't support the installed version of the library,
+  the next one is used, and a library none fits is reported. Pydantic AI
+  instruments itself and is turned on directly;
+- message content capture, which some instrumentations leave off by default;
+- a flush at exit, so a short script doesn't lose its last spans.
+
+A hand-written loop on a model SDK has no span around it: each model call would be
+a run of its own. Wrap the loop in `loopview_sdk.agent("name")` to make it one run.
+Its tool calls are rebuilt from the conversation by loopview; decorate the tools
+with `@loopview_sdk.tool` for exact timing and errors (all of them, or none).
+"""
+
+import atexit
+import functools
+import inspect
+import json
+import os
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from importlib.metadata import EntryPoint, entry_points
+from typing import Any, TypeVar, overload
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from loopview_sdk._live import LiveStartProcessor
+
+DEFAULT_URL = "http://127.0.0.1:4318"
+
+# Instrumentors for agent frameworks and model SDKs, besides every OpenInference
+# package: OpenTelemetry's own GenAI instrumentations and OpenLLMetry's register
+# under these names. Other instrumentors (HTTP clients, databases) are left alone.
+GENAI_NAMES = frozenset({
+    "openai", "anthropic", "langchain", "llama_index", "bedrock", "vertexai",
+    "google_genai", "mistralai", "groq", "cohere", "ollama", "crewai", "litellm",
+    "openai_agents", "haystack", "dspy", "smolagents", "autogen", "agno", "mcp",
+})
+
+# Content capture, for instrumentations that leave it off by default. Only set
+# when the variable isn't set already: a user's choice always wins.
+CONTENT_DEFAULTS = {
+    # OpenTelemetry's GenAI instrumentations (openai-v2, ...): content on spans,
+    # where loopview reads it, rather than as log events.
+    "OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental",
+    "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "SPAN_ONLY",
+    # OpenLLMetry
+    "TRACELOOP_TRACE_CONTENT": "true",
+}
+
+
+def connect(
+    service_name: str | None = None,
+    url: str | None = None,
+    instrument: bool | Sequence[str] = True,
+    capture_content: bool = True,
+    live: bool = True,
+    provider: TracerProvider | None = None,
+    quiet: bool = False,
+) -> TracerProvider:
+    """Send this process's traces to loopview. Returns the TracerProvider used.
+
+    service_name: shown under each run (default: the script's name).
+    url:          loopview's address. Default: LOOPVIEW_URL, else the standard
+                  OTEL_EXPORTER_OTLP_TRACES_ENDPOINT if set, else http://127.0.0.1:4318.
+    instrument:   True for every installed framework, False for none, or names
+                  such as ["openai", "langchain"].
+    provider:     a TracerProvider of your own to add loopview's processors to.
+                  By default the global one is used if it is already an SDK
+                  provider, otherwise one is created and made global.
+    """
+    standard = os.environ.get("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "").removesuffix("/v1/traces")
+    base = (url or os.environ.get("LOOPVIEW_URL") or standard or DEFAULT_URL).rstrip("/")
+    if capture_content:
+        for key, value in CONTENT_DEFAULTS.items():
+            os.environ.setdefault(key, value)
+
+    provider, owned = _provider(provider, service_name)
+    provider.add_span_processor(
+        BatchSpanProcessor(OTLPSpanExporter(endpoint=f"{base}/v1/traces"), schedule_delay_millis=100)
+    )
+    if live:
+        provider.add_span_processor(LiveStartProcessor(endpoint=f"{base}/v1/loopview/span-starts"))
+    # Short scripts can end before the exporter's next batch: flush at exit.
+    atexit.register(provider.shutdown if owned else provider.force_flush)
+
+    instrumented, skipped = _instrument(provider, instrument) if instrument else ([], [])
+    if not quiet:
+        found = ", ".join(instrumented) or "nothing (no supported framework installed)"
+        print(f"loopview: sending traces to {base}; instrumented {found}")
+        for item in skipped:
+            print(f"loopview: could not instrument {item}")
+    return provider
+
+
+@contextmanager
+def agent(name: str, **attributes: Any) -> Iterator[trace.Span]:
+    """A span around an agent's work, for loops that have none of their own.
+
+        with loopview_sdk.agent("weather_assistant"):
+            ...  # your loop: model calls, tool calls
+
+    Everything inside becomes one run, drawn as this agent. Works in async code too.
+    """
+    tracer = trace.get_tracer("loopview_sdk")
+    with tracer.start_as_current_span(
+        f"invoke_agent {name}",
+        attributes={"gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": name, **attributes},
+    ) as span:
+        yield span
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@overload
+def tool(fn: F) -> F: ...
+@overload
+def tool(*, name: str | None = None) -> Callable[[F], F]: ...
+
+
+def tool(fn: Callable[..., Any] | None = None, *, name: str | None = None) -> Any:
+    """Record each call of a tool function: arguments, result, and errors.
+
+        @loopview_sdk.tool
+        def get_weather(city: str) -> dict: ...
+
+    Works on async functions too. An exception marks the call as failed and is
+    raised again unchanged. Optional: without it, loopview rebuilds tool calls
+    from the conversation, with approximate timing and fewer errors.
+    """
+
+    def decorate(f: Callable[..., Any]) -> Callable[..., Any]:
+        tool_name = name or f.__name__
+        signature = inspect.signature(f)
+
+        def start(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+            try:
+                bound = signature.bind(*args, **kwargs)
+                arguments = _json(dict(bound.arguments))
+            except TypeError:
+                arguments = _json({"args": list(args), **kwargs})
+            return trace.get_tracer("loopview_sdk").start_as_current_span(
+                f"execute_tool {tool_name}",
+                attributes={
+                    "gen_ai.operation.name": "execute_tool",
+                    "gen_ai.tool.name": tool_name,
+                    "gen_ai.tool.type": "function",
+                    "gen_ai.tool.call.arguments": arguments,
+                },
+                record_exception=True,
+                set_status_on_exception=True,
+            )
+
+        if inspect.iscoroutinefunction(f):
+
+            @functools.wraps(f)
+            async def run_async(*args: Any, **kwargs: Any) -> Any:
+                with start(args, kwargs) as span:
+                    result = await f(*args, **kwargs)
+                    span.set_attribute("gen_ai.tool.call.result", _json(result))
+                    return result
+
+            return run_async
+
+        @functools.wraps(f)
+        def run(*args: Any, **kwargs: Any) -> Any:
+            with start(args, kwargs) as span:
+                result = f(*args, **kwargs)
+                span.set_attribute("gen_ai.tool.call.result", _json(result))
+                return result
+
+        return run
+
+    return decorate(fn) if fn is not None else decorate
+
+
+def _json(value: Any) -> str:
+    try:
+        return json.dumps(value, default=str)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+# --- helpers -------------------------------------------------------------------------------
+
+
+def _provider(given: TracerProvider | None, service_name: str | None) -> tuple[TracerProvider, bool]:
+    """The provider to use, and whether connect() created it."""
+    if given is not None:
+        return given, False
+    current = trace.get_tracer_provider()
+    if isinstance(current, TracerProvider):
+        return current, False
+    name = service_name or os.environ.get("OTEL_SERVICE_NAME") or _script_name()
+    provider = TracerProvider(resource=Resource.create({"service.name": name}))
+    trace.set_tracer_provider(provider)
+    return provider, True
+
+
+def _script_name() -> str:
+    import __main__
+
+    path = getattr(__main__, "__file__", None)
+    return os.path.splitext(os.path.basename(path))[0] if path else "agent"
+
+
+def rank_instrumentors(
+    points: Sequence[EntryPoint], only: Sequence[str] | None = None
+) -> dict[str, list[EntryPoint]]:
+    """The instrumentors for each GenAI library, best first: OpenInference's (it
+    records content and tool definitions), then the others in the order found."""
+    ranked: dict[str, list[EntryPoint]] = {}
+    for ep in points:
+        if not _is_genai(ep) or (only is not None and ep.name not in only):
+            continue
+        ranked.setdefault(ep.name, []).append(ep)
+    for candidates in ranked.values():
+        candidates.sort(key=lambda ep: not _is_openinference(ep))  # stable
+    return ranked
+
+
+def _is_openinference(ep: EntryPoint) -> bool:
+    return bool(ep.dist and ep.dist.name.startswith("openinference-instrumentation-"))
+
+
+def _is_genai(ep: EntryPoint) -> bool:
+    return _is_openinference(ep) or ep.name in GENAI_NAMES
+
+
+def _instrument(provider: TracerProvider, which: bool | Sequence[str]) -> tuple[list[str], list[str]]:
+    """Instrument every installed GenAI library. Returns (instrumented, skipped), the
+    skipped ones with the reason: no instrumentor fits the installed version."""
+    only = None if which is True else list(which)  # type: ignore[arg-type]
+    done: list[str] = []
+    skipped: list[str] = []
+    ranked = rank_instrumentors(list(entry_points(group="opentelemetry_instrumentor")), only)
+    for library, candidates in ranked.items():
+        reasons = []
+        for ep in candidates:
+            try:
+                instrumentor = ep.load()()
+                # The instrumentor's own check: is a version it supports installed?
+                conflict = instrumentor._check_dependency_conflicts()
+                if conflict is not None:
+                    if getattr(conflict, "found", None):  # installed, wrong version
+                        reasons.append(f"{ep.dist.name if ep.dist else ep.name}: {conflict}")
+                    continue
+                if not getattr(instrumentor, "is_instrumented_by_opentelemetry", False):
+                    instrumentor.instrument(tracer_provider=provider)
+                done.append(library if _is_openinference(ep) else f"{library} ({ep.dist.name if ep.dist else ep.value})")
+                break
+            except Exception as exc:  # a broken instrumentor must never stop the agent
+                reasons.append(f"{ep.dist.name if ep.dist else ep.name}: {exc}")
+        else:
+            if reasons:
+                skipped.append(f"{library} ({'; '.join(reasons)})")
+    if (only is None or "pydantic_ai" in only) and _instrument_pydantic_ai(provider):
+        done.append("pydantic_ai")
+    return done, skipped
+
+
+def _instrument_pydantic_ai(provider: TracerProvider) -> bool:
+    try:
+        from pydantic_ai import Agent
+        from pydantic_ai.models.instrumented import InstrumentationSettings
+    except ImportError:
+        return False
+    Agent.instrument_all(InstrumentationSettings(tracer_provider=provider))
+    return True

loopview_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: loopview-sdk
+Version: 0.2.0
+Summary: Connect any agent to loopview in one call, and see steps the moment they start.
+Keywords: ai-agents,llm,opentelemetry,observability,debugging,tracing
+Author: YasmineZerai
+Author-email: YasmineZerai <zeraiyasmine7@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Dist: opentelemetry-sdk>=1.20
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/YasmineZerai/loopview
+Project-URL: Documentation, https://github.com/YasmineZerai/loopview#connect-your-agent
+Project-URL: Issues, https://github.com/YasmineZerai/loopview/issues
+Description-Content-Type: text/markdown
+
+# loopview-sdk
+
+Connect any Python agent to [loopview](https://github.com/YasmineZerai/loopview) in one call.
+
+```python
+import loopview_sdk
+loopview_sdk.connect()
+```
+
+`connect()` does what every agent needs:
+
+- sends traces to loopview (`LOOPVIEW_URL`, else `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`,
+  else `http://127.0.0.1:4318`), every 100 ms;
+- switches on the OpenTelemetry instrumentation of every installed agent framework or
+  model SDK. Instrumentor packages register themselves, so any OpenInference package,
+  OpenTelemetry's GenAI instrumentations and OpenLLMetry are found; when two cover the
+  same library, OpenInference's is used. Pydantic AI is switched on directly;
+- turns on message content capture where an instrumentation leaves it off;
+- reports span starts, so steps light up the moment they begin;
+- flushes at exit, so short scripts don't lose their last spans.
+
+Options: `connect(service_name=..., url=..., instrument=["openai"] or False,
+capture_content=False, live=False, provider=my_provider, quiet=True)`.
+
+## A loop you wrote yourself
+
+Model SDK instrumentation records model calls only. Wrap your loop so it is one run,
+drawn as an agent:
+
+```python
+with loopview_sdk.agent("weather_assistant"):
+    ...  # your loop
+```
+
+## Only the live start reports
+
+`LiveStartProcessor` is the start reporter `connect()` adds, usable on its own next to
+your own exporter:
+
+```python
+from loopview_sdk import LiveStartProcessor
+provider.add_span_processor(LiveStartProcessor())
+```

loopview_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+loopview_sdk/__init__.py,sha256=dBJSePEGS8l7-YcOi4X40zrhjO7bTTYXz0_SyzXbrZI,701
+loopview_sdk/_live.py,sha256=A3ZX9IdUidLupQr37tXBT3u6KpFmvkXjkHvM5242odY,5133
+loopview_sdk/connect.py,sha256=6syDJyDDZ0QoMWFTz-OMI-dnYEhvh_z_TfxEFnk77ms,12036
+loopview_sdk-0.2.0.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
+loopview_sdk-0.2.0.dist-info/METADATA,sha256=M8pIo0A3jUwFjSKzbTl17BY2DC3jarbps2LvW1sv0K0,2591
+loopview_sdk-0.2.0.dist-info/RECORD,,

loopview_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.23
+Root-Is-Purelib: true
+Tag: py3-none-any