traceAI-openwebui 0.1.0__py3-none-any.whl

traceai_openwebui/__init__.py

@@ -0,0 +1,359 @@
+"""Maintained Open WebUI Pipe Function for real, individually timed model calls."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import json
+import logging
+import weakref
+from contextlib import nullcontext
+from importlib.metadata import version
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind, Status, StatusCode
+from packaging.version import Version
+from pydantic import BaseModel, Field, SecretStr, field_serializer
+from starlette.responses import Response, StreamingResponse
+
+from ._provider import Providers
+from ._response import Observation, is_chat_completion
+
+__version__ = "0.1.0"  # x-release-please-version
+log = logging.getLogger(__name__)
+
+
+def _check_host() -> None:
+    installed = Version(version("open-webui"))
+    if not Version("0.11.4") <= installed < Version("0.13"):
+        raise RuntimeError("traceAI-openwebui requires Open WebUI >=0.11.4,<0.13")
+
+
+def _secret() -> Any:
+    return Field(
+        default=SecretStr(""), json_schema_extra={"input": {"type": "password"}}
+    )
+
+
+async def _check_connection(request: Any, user: Any, model_id: str) -> None:
+    from open_webui.routers.openai import get_all_models, get_openai_connection
+
+    models = request.app.state.OPENAI_MODELS
+    if not models or model_id not in models:
+        await get_all_models(request, user=user)
+        models = request.app.state.OPENAI_MODELS
+    model = models.get(model_id)
+    if model is None:
+        raise ValueError(
+            "The target model's OpenAI-compatible connection is unavailable"
+        )
+    # Use the host's resolver, including index/legacy URL configuration lookup.
+    # Never cache this check: an administrator can change the connection's API.
+    _, _, config = await get_openai_connection(model["urlIdx"])
+    if config.get("api_type") == "responses":
+        # The host discards status/error/incomplete_details when a Responses
+        # endpoint returns JSON. Even stream=True can receive that lossy result.
+        # Reject before inference/span creation rather than inventing success.
+        raise ValueError(
+            "Responses API connections are not supported; choose a Chat Completions connection"
+        )
+
+
+class Pipe:
+    class Valves(BaseModel):
+        target_model: str = Field(
+            default="",
+            description="Native Chat Completions model ID; not Responses API, Ollama, another Pipe or Arena.",
+        )
+        api_key: SecretStr = _secret()
+        secret_key: SecretStr = _secret()
+        endpoint: str = "https://api.futureagi.com"
+        project: str = "open-webui"
+        capture_content: bool = False
+        max_chars: int = Field(default=32000, ge=1, le=131072)
+
+        @field_serializer("api_key", "secret_key")
+        def stored_secret(self, value: SecretStr) -> str:
+            # Open WebUI persists valves through model_dump(). Repr stays masked.
+            return value.get_secret_value()
+
+    def __init__(self) -> None:
+        self.valves = self.Valves()
+        self._providers = Providers()
+        weakref.finalize(self, self._providers.close)
+
+    async def pipe(
+        self,
+        body: dict[str, Any],
+        __request__: Any,
+        __user__: dict[str, Any],
+        __metadata__: dict[str, Any] | None = None,
+    ) -> Any:
+        _check_host()
+        from open_webui.models.users import Users
+        from open_webui.utils.chat import generate_chat_completion
+
+        valves = self.valves.model_copy(deep=True)
+        target = __request__.app.state.MODELS.get(valves.target_model)
+        # Recursive Pipes/Arena routes could produce nested spans for one request
+        # or recurse indefinitely. Delegate only to a native provider entry.
+        if (
+            not target
+            or target.get("pipe")
+            or target.get("owned_by") == "arena"
+            or target.get("info", {}).get("base_model_id")
+            or valves.target_model == body.get("model")
+        ):
+            raise ValueError(
+                "Choose a native provider model as target_model, not a workspace preset, Pipe or Arena"
+            )
+        # The native Ollama dispatcher discards in-band errors, invents [DONE]
+        # at EOF and (on the floor host) invents missing usage as zero. Reject it
+        # before dispatch instead of presenting converted data as real telemetry.
+        if target.get("owned_by") == "ollama":
+            raise ValueError(
+                "Native Ollama connections are not supported; choose an OpenAI-compatible connection"
+            )
+        user = await Users.get_user_by_id(__user__.get("id"))
+        if user is None:
+            raise ValueError("Open WebUI user is unavailable")
+        await _check_connection(__request__, user, valves.target_model)
+        payload = copy.deepcopy(body)
+        payload["model"] = valves.target_model
+        if __metadata__ is not None:
+            payload["metadata"] = dict(__metadata__)
+        metadata = __metadata__ or {}
+        temporary = str(metadata.get("chat_id", "")).startswith(
+            ("temporary:", "local:")
+        )
+        capture = valves.capture_content and not temporary
+        span = None
+        release = lambda: None
+        try:
+            if (
+                valves.api_key.get_secret_value()
+                and valves.secret_key.get_secret_value()
+            ):
+                provider, release = self._providers.acquire(
+                    (
+                        valves.endpoint,
+                        valves.project,
+                        valves.api_key.get_secret_value(),
+                        valves.secret_key.get_secret_value(),
+                    )
+                )
+                span = provider.get_tracer("traceai_openwebui", __version__).start_span(
+                    "openwebui.model",
+                    kind=SpanKind.CLIENT,
+                    attributes={
+                        "fi.span.kind": "LLM",
+                        "gen_ai.operation.name": "chat",
+                        "gen_ai.request.model": valves.target_model,
+                        "llm.model_name": valves.target_model,
+                        "openwebui.tracing.scope": "model_call",
+                    },
+                )
+        except Exception:  # noqa: BLE001 - telemetry fails open without logging private payloads
+            release()
+            release = lambda: None
+            log.warning("Open WebUI tracing unavailable; model execution continues")
+        # Native routing applies stored model defaults after this point, including
+        # custom n parameters. Only an explicit n has authoritative precedence;
+        # otherwise require [DONE] rather than guessing from the model cache.
+        observation = (
+            Observation(span, capture, valves.max_chars, payload.get("n"))
+            if span is not None
+            else None
+        )
+        if span is not None and capture:
+            messages = [
+                {"role": m.get("role"), "content": m.get("content")}
+                for m in payload.get("messages", [])
+                if isinstance(m, dict)
+            ]
+            span.set_attribute(
+                "input.value",
+                json.dumps(messages, ensure_ascii=False)[: valves.max_chars],
+            )
+            span.set_attribute("input.mime_type", "application/json")
+
+        def active():
+            return (
+                trace.use_span(
+                    span,
+                    end_on_exit=False,
+                    record_exception=False,
+                    set_status_on_exception=False,
+                )
+                if span is not None
+                else nullcontext()
+            )
+
+        watched_tasks: weakref.WeakSet[asyncio.Task] = weakref.WeakSet()
+
+        def observe(method: str, *args: Any) -> None:
+            if observation is not None:
+                try:
+                    getattr(observation, method)(*args)
+                except Exception:  # noqa: BLE001 - telemetry fails open without logging private payloads
+                    log.warning("Open WebUI response telemetry unavailable")
+
+        def finish(outcome: str) -> None:
+            nonlocal span
+            try:
+                if span is not None:
+                    # Host cleanup may abandon our stream under shield before the
+                    # cancelled consumer finishes. A pending cancel request is
+                    # already known; do not overwrite it with "incomplete" on GC.
+                    if outcome == "incomplete" and any(
+                        task.cancelling() or task.cancelled() for task in watched_tasks
+                    ):
+                        outcome = "cancelled"
+                    observe("finish")
+                    if observation is not None and observation.failed:
+                        outcome = "error"
+                    span.set_attribute("openwebui.outcome", outcome)
+                    if outcome != "completed":
+                        span.set_status(
+                            Status(
+                                StatusCode.ERROR,
+                                {
+                                    "error": "model request failed",
+                                    "cancelled": "model request cancelled",
+                                    "incomplete": "model stream ended without completion",
+                                }[outcome],
+                            )
+                        )
+                    span.end()
+                    span = None
+            finally:
+                for task in watched_tasks:
+                    task.remove_done_callback(task_done)
+                watched_tasks.clear()
+                release()
+
+        def task_done(task: asyncio.Task) -> None:
+            # A host may cancel while handling a chunk, outside our __anext__.
+            if task.cancelled():
+                finish("cancelled")
+
+        def watch_task() -> None:
+            task = asyncio.current_task()
+            if span is not None and task is not None and task not in watched_tasks:
+                watched_tasks.add(task)
+                task.add_done_callback(task_done)
+
+        watch_task()
+        try:
+            with active():
+                # Preserve upstream access checks. Never pass bypass_filter=True.
+                response = await generate_chat_completion(
+                    __request__,
+                    payload,
+                    user,
+                    bypass_system_prompt=getattr(
+                        __request__.state, "bypass_system_prompt", False
+                    ),
+                )
+        except asyncio.CancelledError:
+            finish("cancelled")
+            raise
+        except BaseException:
+            finish("error")
+            raise
+
+        if not isinstance(response, StreamingResponse):
+            data = response
+            if isinstance(response, Response):
+                try:
+                    data = json.loads(response.body)
+                except (ValueError, TypeError):
+                    data = None
+            invalid = not (
+                isinstance(data, dict)
+                and (data.get("error") or is_chat_completion(data))
+            )
+            http_error = isinstance(response, Response) and response.status_code >= 400
+            try:
+                observe("payload", data)
+            finally:
+                finish("error" if invalid or http_error else "completed")
+            # The native router normally returns decoded JSON, not a Response.
+            # Validate both forms even with tracing disabled: the Pipe dispatcher
+            # would otherwise fabricate an empty completion or treat a raw string
+            # as generated model content.
+            if http_error and (invalid or not data.get("error")):
+                return {
+                    "error": {
+                        "message": "model request failed",
+                        "code": response.status_code,
+                    }
+                }
+            if invalid:
+                return {"error": "model returned an invalid non-streaming response"}
+            return data
+
+        if observation is not None and response.status_code >= 400:
+            observation.failed = True
+
+        async def traced_stream():
+            watch_task()
+            outcome = "incomplete"
+            try:
+                iterator = response.body_iterator.__aiter__()
+                while True:
+                    try:
+                        # Do not leave the span attached across a yield: unrelated
+                        # tool/retrieval work must not become a child of this call.
+                        with active():
+                            chunk = await iterator.__anext__()
+                    except StopAsyncIteration:
+                        if observation is not None:
+                            observe("finish")
+                            outcome = (
+                                "completed" if observation.terminal else "incomplete"
+                            )
+                        else:
+                            outcome = "completed"
+                        break
+                    observe("chunk", chunk)
+                    yield chunk
+            except (asyncio.CancelledError, GeneratorExit):
+                outcome = "cancelled"
+                raise
+            except BaseException:
+                outcome = "error"
+                raise
+            finally:
+                try:
+                    close = getattr(response.body_iterator, "aclose", None)
+                    if close is not None:
+                        await close()
+                    # Open WebUI's Pipe dispatcher consumes only body_iterator;
+                    # it does not run the returned response's background task.
+                    if response.background is not None:
+                        await response.background()
+                finally:
+                    finish(outcome)
+
+        # Preserve the original stream exactly, including errors and [DONE].
+        stream = traced_stream()
+        # Includes a consumer that abandons the returned response before starting
+        # iteration. This is incomplete observation, never claimed as success.
+        weakref.finalize(stream, finish, "incomplete")
+        return StreamingResponse(
+            stream,
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            media_type=response.media_type,
+        )
+
+    def flush(self, timeout_millis: int = 10000) -> bool:
+        return self._providers.flush(timeout_millis)
+
+    def close(self) -> None:
+        self._providers.close()
+
+
+__all__ = ["Pipe"]

traceai_openwebui/_provider.py

@@ -0,0 +1,210 @@
+"""Private provider: never forward Open WebUI's HTTP, auth or database spans."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections.abc import Callable
+from concurrent.futures import Future, TimeoutError
+from urllib.parse import urlsplit
+
+import certifi
+import requests
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+    Compression,
+    OTLPSpanExporter,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import ALWAYS_ON
+
+
+def endpoint_url(value: str) -> str:
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme not in {"https", "http"}
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError("Use a collector URL without credentials, query or fragment")
+    if parsed.scheme == "http" and parsed.hostname not in {
+        "localhost",
+        "127.0.0.1",
+        "::1",
+    }:
+        raise ValueError("Use HTTPS for a non-loopback collector")
+    return value.rstrip("/") + (
+        ""
+        if parsed.path.rstrip("/").endswith("/tracer/v1/traces")
+        else "/tracer/v1/traces"
+    )
+
+
+class _ExportSession(requests.Session):
+    def __init__(self, auth_headers: dict[str, str]) -> None:
+        super().__init__()
+        self._auth_headers = auth_headers
+
+    def prepare_request(self, request):
+        prepared = super().prepare_request(request)
+        # Some SDK versions merge native OTEL_* headers even when headers were
+        # explicitly supplied. Allow only transport headers plus our own keys.
+        prepared.headers.clear()
+        prepared.headers.update(
+            {
+                "Content-Type": "application/x-protobuf",
+                "Content-Length": str(len(prepared.body or b"")),
+            }
+        )
+        prepared.headers.update(self._auth_headers)
+        return prepared
+
+    def request(self, method, url, **kwargs):
+        # The SDK's transport can pass mTLS from OTEL_* environment variables
+        # on each request. Override at the public requests boundary, not by
+        # temporarily mutating the process environment used by native telemetry.
+        kwargs["cert"] = None
+        kwargs["allow_redirects"] = False
+        return super().request(method, url, **kwargs)
+
+
+def make_provider(
+    endpoint: str, project: str, api_key: str, secret_key: str
+) -> TracerProvider:
+    session = _ExportSession({"X-Api-Key": api_key, "X-Secret-Key": secret_key})
+    # Never inherit proxy credentials or .netrc authentication from the host.
+    session.trust_env = False
+    exporter = OTLPSpanExporter(
+        endpoint=endpoint_url(endpoint),
+        headers={"X-Api-Key": api_key, "X-Secret-Key": secret_key},
+        timeout=10,
+        compression=Compression.NoCompression,
+        certificate_file=certifi.where(),
+        session=session,
+    )
+    # An unrelated native OTLP client certificate must not be sent to our endpoint.
+    session.cert = None
+    provider = TracerProvider(
+        resource=Resource(
+            {
+                "project_name": project,
+                "project_type": "observe",
+                "service.name": "open-webui",
+            }
+        ),
+        sampler=ALWAYS_ON,
+    )
+    provider.add_span_processor(
+        BatchSpanProcessor(
+            exporter,
+            max_queue_size=2048,
+            max_export_batch_size=512,
+            schedule_delay_millis=5000,
+            export_timeout_millis=10000,
+        )
+    )
+    return provider
+
+
+class _Generation:
+    def __init__(self, key: tuple[str, ...], provider: TracerProvider) -> None:
+        self.key = key
+        self.provider = provider
+        self.users = 0
+        self.retired = False
+
+
+class Providers:
+    """Keep in-flight calls on their original project when an admin edits valves."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._flush_lock = threading.Lock()
+        self._current: _Generation | None = None
+
+    @staticmethod
+    def _retire(generation: _Generation) -> None:
+        threading.Thread(
+            target=generation.provider.shutdown,
+            name="traceai-openwebui-close",
+            daemon=True,
+        ).start()
+
+    def acquire(
+        self, key: tuple[str, str, str, str]
+    ) -> tuple[TracerProvider, Callable[[], None]]:
+        with self._lock:
+            current = self._current
+            if current is None or current.key != key:
+                new = _Generation(key, make_provider(*key))
+                if current is not None:
+                    current.retired = True
+                    if current.users == 0:
+                        self._retire(current)
+                self._current = current = new
+            current.users += 1
+        released = False
+
+        def release() -> None:
+            nonlocal released
+            with self._lock:
+                if released:
+                    return
+                released = True
+                current.users -= 1
+                if current.retired and current.users == 0:
+                    self._retire(current)
+
+        return current.provider, release
+
+    def flush(self, timeout_millis: int = 10000) -> bool:
+        """Bound the caller's wait, even when the SDK ignores its flush timeout."""
+        deadline = time.monotonic() + max(0, timeout_millis) / 1000
+        with self._lock:
+            provider = self._current.provider if self._current else None
+        if provider is None:
+            return True
+        # One worker at a time, including after timeout. Do not create a thread
+        # per retry or return a previous flush's result for newly queued spans.
+        if not self._flush_lock.acquire(timeout=max(0, deadline - time.monotonic())):
+            return False
+        result: Future[bool] = Future()
+
+        def flush_provider() -> None:
+            try:
+                result.set_result(
+                    provider.force_flush(
+                        max(1, int((deadline - time.monotonic()) * 1000))
+                    )
+                )
+            except Exception:  # noqa: BLE001 - fixed diagnostic; never export private errors
+                logging.getLogger(__name__).warning("Open WebUI tracing flush failed")
+                result.set_result(False)
+            finally:
+                self._flush_lock.release()
+
+        try:
+            threading.Thread(
+                target=flush_provider, name="traceai-openwebui-flush", daemon=True
+            ).start()
+        except BaseException:
+            self._flush_lock.release()
+            raise
+        try:
+            return result.result(timeout=max(0, deadline - time.monotonic()))
+        except TimeoutError:
+            # Export can finish in the daemon worker; it cannot hold up shutdown.
+            return False
+
+    def close(self) -> None:
+        with self._lock:
+            current, self._current = self._current, None
+            if current is not None:
+                current.retired = True
+                if current.users == 0:
+                    self._retire(current)

traceai_openwebui/_response.py

@@ -0,0 +1,234 @@
+"""Observe provider responses, never reconstruct operations from a chat transcript."""
+
+from __future__ import annotations
+
+import codecs
+import json
+from typing import Any
+
+from opentelemetry.trace import Span
+
+_MAX_FRAME = 1_048_576
+
+
+def is_chat_completion(value: Any) -> bool:
+    """Require completed messages, not just a JSON object or streaming deltas.
+
+    Compatible providers can omit IDs, timestamps, usage, role and finish_reason.
+    Empty/filtered content, tool calls, refusals and audio are still completions.
+    """
+    if not isinstance(value, dict):
+        return False
+    choices = value.get("choices")
+    if not isinstance(choices, list) or not choices:
+        return False
+    for choice in choices:
+        if not isinstance(choice, dict):
+            return False
+        message = choice.get("message")
+        if not isinstance(message, dict):
+            return False
+        if "content" in message:
+            if message["content"] is not None and not isinstance(
+                message["content"], str
+            ):
+                return False
+        elif isinstance(message.get("refusal"), str):
+            continue
+        elif isinstance(message.get("tool_calls"), list) and message["tool_calls"]:
+            if not all(
+                isinstance(call, dict) and call for call in message["tool_calls"]
+            ):
+                return False
+        elif any(
+            isinstance(message.get(key), dict) and message[key]
+            for key in ("function_call", "audio")
+        ):
+            continue
+        else:
+            return False
+    return True
+
+
+class Observation:
+    def __init__(
+        self,
+        span: Span,
+        capture_content: bool,
+        max_chars: int,
+        choice_count: Any = None,
+    ) -> None:
+        self.span = span
+        self.capture_content = capture_content
+        self.max_chars = max_chars
+        self.usage: dict[str, int] = {}
+        self.output = ""
+        self._terminal = False
+        self._choice_count = (
+            choice_count if type(choice_count) is int and choice_count > 0 else 0
+        )
+        self._finished_choices: set[int] = set()
+        self._ambiguous_choices = self._choice_count == 0
+        self.failed = False
+        self._decoder = codecs.getincrementaldecoder("utf-8")("replace")
+        self._buffer = ""
+        self._data: list[str] = []
+        self._size = 0
+        self._dropping = False
+        self._observation_lost = False
+
+    @property
+    def terminal(self) -> bool:
+        # A discarded event may contain a provider error. Even [DONE] or fully
+        # finished choices cannot establish success after losing that evidence.
+        return not self._observation_lost and (
+            self._terminal
+            or (
+                not self._ambiguous_choices
+                and len(self._finished_choices) == self._choice_count
+            )
+        )
+
+    def payload(self, value: Any) -> None:
+        if not isinstance(value, dict):
+            return
+        if value.get("error") or value.get("type") in {"error", "response.failed"}:
+            self.failed = True
+        response = value.get("response")
+        if isinstance(response, dict):
+            if response.get("error") or response.get("status") in {
+                "failed",
+                "incomplete",
+                "cancelled",
+            }:
+                self.failed = True
+            self._usage(response.get("usage"))
+        self._usage(value.get("usage"))
+        if value.get("type") in {
+            "response.completed",
+            "response.failed",
+            "response.incomplete",
+        }:
+            self._terminal = True
+            if value["type"] != "response.completed":
+                self.failed = True
+        if value.get("type") == "response.output_text.delta":
+            self._text(value.get("delta"))
+        choices = value.get("choices")
+        if isinstance(choices, list):
+            for choice in choices:
+                if not isinstance(choice, dict):
+                    self._ambiguous_choices = True
+                    continue
+                # A choice finishing is not a request-level terminator. Account
+                # for n even when a missing choice never appears on the wire.
+                index = choice.get(
+                    "index",
+                    0 if self._choice_count == 1 and len(choices) == 1 else None,
+                )
+                if type(index) is not int or not 0 <= index < self._choice_count:
+                    # Cannot correlate ambiguous choices; require [DONE] instead.
+                    self._ambiguous_choices = True
+                elif (
+                    isinstance(choice.get("finish_reason"), str)
+                    and choice["finish_reason"]
+                ):
+                    self._finished_choices.add(index)
+                else:
+                    self._finished_choices.discard(index)
+                message = choice.get("delta") or choice.get("message")
+                if isinstance(message, dict):
+                    self._text(message.get("content"))
+        # Responses API non-streaming output. Streamed output is captured only
+        # from deltas, not again from response.completed's repeated output.
+        if isinstance(value.get("output"), list):
+            for item in value["output"]:
+                if (
+                    isinstance(item, dict)
+                    and item.get("type") == "message"
+                    and isinstance(item.get("content"), list)
+                ):
+                    for part in item["content"]:
+                        if isinstance(part, dict) and part.get("type") == "output_text":
+                            self._text(part.get("text"))
+
+    def _usage(self, usage: Any) -> None:
+        if not isinstance(usage, dict):
+            return
+        for key, aliases in (
+            ("input", ("prompt_tokens", "input_tokens")),
+            ("output", ("completion_tokens", "output_tokens")),
+        ):
+            for alias in aliases:
+                value = usage.get(alias)
+                if type(value) is int and 0 <= value < 2**63:
+                    # A provider's usage object is a snapshot, not a delta.
+                    self.usage[key] = value
+                    break
+
+    def _text(self, value: Any) -> None:
+        if self.capture_content and isinstance(value, str):
+            self.output += value[: max(0, self.max_chars - len(self.output))]
+
+    def chunk(self, chunk: str | bytes) -> None:
+        text = self._decoder.decode(chunk) if isinstance(chunk, bytes) else chunk
+        if not isinstance(text, str):
+            return
+        # Do not retain an oversized event or parse its suffix as a new event.
+        for piece in text.splitlines(keepends=True):
+            self._size += len(piece)
+            if self._size > _MAX_FRAME:
+                self._observation_lost = True
+                self._dropping = True
+                self._buffer = ""
+                self._data.clear()
+            if not self._dropping:
+                self._buffer += piece
+            if piece.endswith("\n"):
+                line = self._buffer.rstrip("\r\n")
+                if self._dropping:
+                    # A blank physical line terminates the dropped SSE frame.
+                    if piece in {"\n", "\r\n"}:
+                        self._reset()
+                elif not line:
+                    self._frame()
+                    self._reset()
+                elif line.startswith("data:"):
+                    self._data.append(line[5:].lstrip(" "))
+                self._buffer = ""
+
+    def _reset(self) -> None:
+        self._buffer = ""
+        self._data.clear()
+        self._size = 0
+        self._dropping = False
+
+    def _frame(self) -> None:
+        data = "\n".join(self._data).strip()
+        if data == "[DONE]":
+            self._terminal = True
+        elif data:
+            try:
+                self.payload(json.loads(data))
+            except (ValueError, TypeError):
+                pass
+
+    def finish(self) -> None:
+        if not self._dropping:
+            # Native Pipe wrappers can end with an unterminated [DONE] line.
+            if self._buffer.startswith("data:"):
+                self._data.append(self._buffer[5:].strip())
+            self._frame()
+        self._reset()
+        if self._observation_lost:
+            self.span.set_attribute("openwebui.observation_lost", True)
+        for key, count in self.usage.items():
+            self.span.set_attribute(f"gen_ai.usage.{key}_tokens", count)
+            legacy = "prompt" if key == "input" else "completion"
+            self.span.set_attribute(f"llm.token_count.{legacy}", count)
+        if len(self.usage) == 2 and sum(self.usage.values()) < 2**63:
+            self.span.set_attribute("llm.token_count.total", sum(self.usage.values()))
+        if not self.usage:
+            self.span.set_attribute("gen_ai.usage.unavailable", True)
+        if self.capture_content:
+            self.span.set_attribute("output.value", self.output)

traceai_openwebui/cli.py

@@ -0,0 +1,42 @@
+"""Generate Open WebUI's supported Function import file from the installed package."""
+
+import argparse
+import json
+from pathlib import Path
+
+from . import __version__
+
+
+def function_document() -> dict:
+    source = f'''"""
+title: Traced model
+version: {__version__}
+license: Apache-2.0
+required_open_webui_version: 0.11.4
+requirements: traceAI-openwebui=={__version__}
+"""
+from traceai_openwebui import Pipe as _Pipe
+
+class Pipe(_Pipe):
+    pass
+'''
+    return {
+        "id": "traceai_openwebui",
+        "name": "Traced model",
+        "type": "pipe",
+        "content": source,
+        "meta": {"description": "Trace individual native model calls in Future AGI"},
+        "is_active": False,
+        "is_global": False,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("command", choices=["export-function"])
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    # Never overwrite a user's existing Function export or configuration.
+    with args.output.open("x", encoding="utf-8") as handle:
+        json.dump([function_document()], handle, indent=2)
+        handle.write("\n")

traceai_openwebui-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: traceAI-openwebui
+Version: 0.1.0
+Summary: Trace real Open WebUI model calls with a maintained Pipe Function
+Project-URL: Repository, https://github.com/future-agi/traceAI
+Project-URL: Documentation, https://docs.futureagi.com/docs/integrations/no-code/open-webui
+Author-email: Future AGI <no-reply@futureagi.com>
+License-Expression: Apache-2.0
+Requires-Python: <3.13,>=3.11
+Requires-Dist: certifi>=2024.7.4
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27
+Requires-Dist: opentelemetry-sdk<2,>=1.27
+Requires-Dist: packaging<27,>=24
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: starlette<1,>=0.40
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.18; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.14; extra == 'dev'
+Requires-Dist: types-requests>=2.32; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# traceAI-openwebui
+
+Trace each model call made through an Open WebUI Pipe Function in Future AGI, with streaming duration, provider-reported usage, and failure or cancellation status.
+
+## Install
+
+Use Python 3.11 or 3.12 and Open WebUI 0.11.4–0.12.x. Configure an OpenAI-compatible **Chat Completions** connection model in Open WebUI first.
+
+Native Ollama and **Responses API** connections are not supported. Open WebUI's conversions can hide failures or incomplete responses, so the Pipe rejects these connections before making a model request or recording a span. Responses API connections are rejected even with streaming enabled: a provider can return a non-streaming response to a streaming request. Choose a connection configured for Chat Completions instead.
+
+Install the package in the same Python environment as Open WebUI, then generate its Function import file:
+
+```bash
+pip install traceAI-openwebui
+traceai-openwebui export-function --output traceai-openwebui.json
+```
+
+For a container deployment, install the package in your image and run the export command in that image. Make the generated JSON file available to your browser. The file contains a small package loader, not instrumentation source to maintain.
+
+## Configure the Function
+
+1. In **Admin Panel → Functions**, import `traceai-openwebui.json`.
+2. Open the **Traced model** Function's valves. Set `target_model` to the exact model ID from your existing Chat Completions connection. Responses API connections, native Ollama models, workspace model presets, other Pipes, and Arena models cannot be targets.
+3. Set `api_key`, `secret_key`, and `project` to your Future AGI credentials and project name. The default endpoint is `https://api.futureagi.com`. For self-hosted Future AGI, set its HTTPS origin; `/tracer/v1/traces` is added automatically.
+4. Enable the Function, and select **Traced model** in a new chat. Access to the target model is still checked using the signed-in Open WebUI user.
+
+Set `ENABLE_VALVE_ENCRYPTION=true` in Open WebUI before storing production credentials so its database encrypts the valves.
+
+Use the wrapper model's settings for tools and knowledge. Target-model workspace presets are not inherited. Enable **Usage** in the wrapper model's capabilities when your provider supports streamed token counts. Missing usage stays missing; the integration does not estimate it.
+
+Send a message such as “Explain how a cache works in two sentences.” In Future AGI, open **Observe**, choose your project, and inspect an `openwebui.model` span. Native tool loops that invoke this Pipe again produce a separate span for each actual model call, not one span for the whole conversation.
+
+## What is captured
+
+- One `LLM` span per delegated model request, from dispatch through response consumption.
+- Provider-reported input and output token counts on that call only. Repeated usage snapshots replace previous values; turn totals are never added again.
+- Fixed error messages for failures, cancellation, or an incomplete stream. Provider exception text and stack traces are not exported.
+- The active OpenTelemetry span as parent, when one exists. The package does not export Open WebUI's native HTTP, database, Redis, or authentication spans.
+
+This is **model-call tracing**, not a trace of the entire chat workflow. Retrieval, tool execution, approval pauses, and calls to unwrapped models are outside the Pipe boundary. The integration does not fabricate spans for them or reconstruct model calls from the final transcript. If you also instrument the target gateway, avoid counting both its LLM spans and this Pipe's spans as separate model usage.
+
+Prompts, responses, user identifiers, raw email, headers, URLs, tool arguments, and retrieval content are excluded by default. To include message content, enable `capture_content`; `max_chars` bounds each captured input/output to 32,000 characters by default. Temporary and local chats always exclude content. Model IDs and your configured project name are exported.
+
+Open WebUI's own telemetry is independent. Enabling it can export additional personal data through its separately configured exporter; this package does not sanitize that exporter.
+
+## Replace the old Filter
+
+Disable and delete the old Future AGI Filter Function before enabling this Pipe. The old filter recorded whole-turn summaries as an LLM child and could not observe failed or cancelled turns reliably. The Pipe is not a drop-in filter: choose **Traced model** for the calls you want to trace. Remove any separate tracing filter or gateway integration that would duplicate usage.
+
+Existing Function copies in Open WebUI's database do not change when this repository changes. Import the generated Function after each package upgrade, then restart Open WebUI to load the new Python package.
+
+## Troubleshooting
+
+**No spans:** Confirm you selected **Traced model**, supplied both Future AGI keys, and enabled the Function. Tracing configuration/export failures do not block the model response. Allow a few seconds for the batch exporter.
+
+**Target model rejected:** Use an OpenAI-compatible Chat Completions connection model ID, not a Responses API connection, native Ollama model, workspace preset, Arena model, or another Pipe. The signed-in user must also have permission to use that target.
+
+**Invalid non-streaming response:** The provider returned a scalar, array, or undecodable body instead of a completion object. Check the connection URL and API type; the Pipe returns an explicit error rather than presenting that body as generated text.
+
+**No token counts:** Enable Usage on the wrapper model and check that the provider returns usage. Cancelled calls may never receive a final usage snapshot.
+
+**Incomplete stream:** The provider ended its stream without confirmed completion, or the consumer closed it early. The span is not marked successful. When the request explicitly supplies a positive integer `n`, every requested choice must finish unless the provider sends `[DONE]`. Without explicit `n`, the Pipe requires `[DONE]`: native model defaults can change the choice count after dispatch, so a single finished choice does not prove the request completed. If your provider omits `[DONE]`, supply the intended `n` in the wrapper request rather than relying on target-model defaults. This does not change the response sent to your chat. An abrupt process kill cannot export pending spans.
+
+**Oversized streaming event:** The Pipe inspects up to 1,048,576 decoded characters per SSE event, including framing and line endings. Larger events still reach your chat unchanged, but the Pipe discards them from telemetry parsing to bound its buffer. The span records `openwebui.observation_lost=true` and an `incomplete` outcome with error status, even if `[DONE]` or finished choices are observed; a separately observed failure or cancellation retains its own outcome. This indicates incomplete observation, not proof that the provider failed. Content and usage from discarded events are unavailable; token counts reflect only observed snapshots. Configure your provider to send smaller streaming events if you need complete telemetry. The `max_chars` content-capture setting does not change this inspection limit.
+
+**Self-hosted collector:** Remote endpoints must use HTTPS; HTTP is accepted only for loopback testing. Redirects, host proxy settings, `.netrc`, and unrelated native OTLP client certificates are not used. Use a directly reachable collector endpoint.
+
+## Embedding lifecycle
+
+If you manage the Pipe lifecycle in Python, `pipe.flush(timeout_millis=10000)` bounds the caller's wait and returns `False` when the flush does not complete within that budget. An in-progress export can continue in the background; retrying does not create concurrent flush workers. Call `pipe.close()` to retire the exporter after active model calls finish.

traceai_openwebui-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+traceai_openwebui/__init__.py,sha256=wNI4yC38fRD0uMOnMs-fk6nsZ6r55hRe2cabdfJa46g,14690
+traceai_openwebui/_provider.py,sha256=qWwnfMBzdLqFRIb3551g2-QRw6WXt3WDO33g1q_t1nM,7254
+traceai_openwebui/_response.py,sha256=lm6c1jmKDlbwf5rnq7l__h5sw4VwQ0BPvXKa7fm9khw,9068
+traceai_openwebui/cli.py,sha256=eESHASz89dn69pt2ozuCH7O9vIiOmkvKpnz6jwp1Mc0,1187
+traceai_openwebui-0.1.0.dist-info/METADATA,sha256=lAbL_Z2BZIFk2uTpucWxBO_syz2eh8Z1mUXRB7BDXXU,8867
+traceai_openwebui-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+traceai_openwebui-0.1.0.dist-info/entry_points.txt,sha256=jRV9AS90PhkYRPJ6nATcURjIugXksswLtgNVS2hEhCE,65
+traceai_openwebui-0.1.0.dist-info/RECORD,,

traceai_openwebui-0.1.0.dist-info/WHEEL

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

traceai_openwebui-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+traceai-openwebui = traceai_openwebui.cli:main