Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
5936e09
test(harness): add shared OTLP harness for TH-8103 contract tests
nik13 Oct 4, 2026
32f5c9d
test(harness): accept the collector /tracer/v1/traces path
nik13 Oct 4, 2026
3eaadc8
fix(harness): decode chunked OTLP bodies and record request metadata
nik13 Oct 4, 2026
b559f69
test(examples): add loopback guard, OpenAI fake and probes for the Gr…
nik13 Oct 5, 2026
46c21dc
feat(examples): add a Gradio chat recipe traced by traceAI-openai
nik13 Oct 5, 2026
99ad5c5
docs(examples): add the Gradio recipe README
nik13 Oct 5, 2026
4eca448
test(examples): test the Gradio recipe in-process and through register()
nik13 Oct 5, 2026
f465604
docs(examples): state exactly how the published fi-instrumentation-ot…
nik13 Oct 5, 2026
ff7fed3
docs(examples): Gradio recipe runs on Python 3.10-3.13
nik13 Oct 5, 2026
c5b51f5
fix(examples): export a keyed digest of the Gradio session hash, not …
nik13 Oct 5, 2026
fca726b
test(examples): replay Gradio's startup re-run of the file in reload …
nik13 Oct 5, 2026
26ceb65
test(examples): a model error gives an exported ERROR span without co…
nik13 Oct 5, 2026
3f382ee
test(examples): opt-in run of requirements.txt from PyPI into the Rec…
nik13 Oct 5, 2026
3c2a1ac
docs(examples): say who can use a Gradio session hash when auth is set
nik13 Oct 5, 2026
47c30be
test(gradio): exercise the content-off init_tracing default
nik13 Oct 5, 2026
3ea677a
docs(gradio): record the live Gradio + Future AGI run in the cookbook
nik13 Oct 12, 2026
f78a19a
Merge dev into feat/th-8333-gradio
nik13 Oct 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
393 changes: 393 additions & 0 deletions python/examples/gradio/README.md

Large diffs are not rendered by default.

9 changes: 9 additions & 0 deletions python/examples/gradio/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Not a traceAI package: these are the example's own dependencies.
gradio==6.29.1
openai==3.24.0 # the version the tests ran with
# register() and the OpenAI instrumentor. The main tests run against this
# repository's python/fi_instrumentation and python/frameworks/openai at the
# same version numbers; an opt-in test installs this file from PyPI (see
# README.md, "Tests").
fi-instrumentation-otel==1.1.0
traceAI-openai==0.1.10
97 changes: 97 additions & 0 deletions python/examples/gradio/src/app.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
"""Trace a Gradio chat app with traceAI's OpenAI instrumentor.

Recipe example, not a package. Gradio emits no GenAI spans. The one span per
chat turn comes from ``traceai_openai`` instrumenting the OpenAI client that
``predict`` calls. This file calls ``register()`` once at startup, instruments
the OpenAI client with content capture off, and passes a keyed digest of
Gradio's session hash to ``using_session`` so the turns of one browser session
share a session id.

python src/app.py

FI_API_KEY, FI_SECRET_KEY, FI_PROJECT_NAME and (optionally) FI_BASE_URL are
read from the environment; so are OPENAI_API_KEY, OPENAI_BASE_URL and
OPENAI_MODEL. See README.md.
"""

from __future__ import annotations

import hashlib
import hmac
import os
import secrets
from contextlib import nullcontext

import gradio as gr
from fi_instrumentation import TraceConfig, register, using_session
from fi_instrumentation.fi_types import ProjectType
from openai import OpenAI
from traceai_openai import OpenAIInstrumentor

MODEL = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")


def init_tracing(trace_content: bool = False):
"""Register the Future AGI provider and instrument OpenAI. Call once, before the first turn."""
provider = register(
project_name=os.environ["FI_PROJECT_NAME"],
project_type=ProjectType.OBSERVE,
verbose=False,
)
# traceAI records prompts and answers unless told not to: TraceConfig's
# defaults are hide_inputs=False and hide_outputs=False.
if trace_content:
config = TraceConfig()
else:
config = TraceConfig(hide_inputs=True, hide_outputs=True)
OpenAIInstrumentor().instrument(tracer_provider=provider, config=config)
return provider


# OpenAI() reads OPENAI_API_KEY and OPENAI_BASE_URL.
client = OpenAI()


def _text(content) -> str:
# Gradio 6 passes each history message's content as a list of parts.
if isinstance(content, str):
return content
return "".join(part["text"] for part in content if part.get("type") == "text")


# Gradio's session hash identifies one browser session (one page load), not a
# user. It is also the key to that session's live state in the running app,
# so it is not exported. The span gets a digest keyed with a random
# per-process key that never leaves the process. Gradio's reload mode re-runs
# this file in the same namespace; keeping the key keeps the ids of open
# sessions.
_SESSION_KEY = globals().get("_SESSION_KEY") or secrets.token_bytes(32)


def _session_id(request: gr.Request | None) -> str | None:
if request is None or not request.session_hash:
return None
digest = hmac.new(_SESSION_KEY, request.session_hash.encode("utf-8"), hashlib.sha256)
return digest.hexdigest()[:32]


def predict(message: str, history: list, request: gr.Request = None) -> str:
messages = [{"role": m["role"], "content": _text(m["content"])} for m in history]
messages.append({"role": "user", "content": message})
# With a Gradio session, every turn of it carries the same session.id;
# without one, each turn is an unrelated trace.
session_id = _session_id(request)
with using_session(session_id) if session_id else nullcontext():
response = client.chat.completions.create(model=MODEL, messages=messages)
return response.choices[0].message.content or ""


# analytics_enabled=False turns off Gradio's own usage analytics, which
# otherwise contact api.gradio.app when the app is built. It is unrelated to
# tracing.
demo = gr.ChatInterface(predict, analytics_enabled=False)

if __name__ == "__main__":
init_tracing()
# register() flushes the batch on normal exit and on SIGINT/SIGTERM.
demo.launch()
15 changes: 15 additions & 0 deletions python/examples/gradio/tests/_analytics_probe.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
"""A test-only probe: build a Gradio app with Gradio's default analytics setting.

Run under ``_guarded_run.py`` with ``GRADIO_ANALYTICS_ENABLED`` unset, the
guard log shows whether building the app tries to reach Gradio's analytics
host. That is why ``src/app.py`` passes ``analytics_enabled=False``.
Not part of the recipe.
"""

from __future__ import annotations

import gradio as gr

gr.ChatInterface(lambda message, history: message)
# Gradio sends its analytics from background threads; the interpreter waits
# for them before exiting.
86 changes: 86 additions & 0 deletions python/examples/gradio/tests/_fake_openai.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
"""A loopback stand-in for the OpenAI Chat Completions API (non-streaming).

Every POST to /v1/chat/completions gets one assistant message whose text is
``answer_text``, with fixed token usage, so the instrumentor records model
and usage attributes. With ``status`` other than 200 it answers that status
and an OpenAI-style error body instead, with no message text in it. Each
request body and Authorization header is kept for assertions. Listens on
127.0.0.1 only.
"""

from __future__ import annotations

import json
import threading
from http import HTTPStatus
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from typing import Any

RESPONSE_MODEL = "gpt-4o-mini-2024-07-18"
USAGE = {"prompt_tokens": 11, "completion_tokens": 7, "total_tokens": 18}


class FakeOpenAI:
"""Serve /v1/chat/completions on 127.0.0.1 and record each request."""

def __init__(self, answer_text: str, status: int = HTTPStatus.OK) -> None:
self.requests: list[dict[str, Any]] = []
self.authorizations: list[str | None] = []
lock = threading.Lock()
owner = self

class Handler(BaseHTTPRequestHandler):
def do_POST(self) -> None: # noqa: N802 - BaseHTTPRequestHandler API
if self.path.rstrip("/") != "/v1/chat/completions":
self.send_error(HTTPStatus.NOT_FOUND)
return
length = int(self.headers.get("Content-Length", "0"))
request = json.loads(self.rfile.read(length).decode("utf-8"))
with lock:
owner.requests.append(request)
owner.authorizations.append(self.headers.get("Authorization"))
if status != HTTPStatus.OK:
error = {"message": "fixture failure", "type": "server_error", "code": None}
self._send_json(status, {"error": error})
return
self._send_json(
HTTPStatus.OK,
{
"id": "chatcmpl-fake",
"object": "chat.completion",
"created": 1_700_000_000,
"model": RESPONSE_MODEL,
"choices": [
{
"index": 0,
"message": {"role": "assistant", "content": answer_text},
"finish_reason": "stop",
}
],
"usage": USAGE,
},
)

def _send_json(self, code: int, payload: dict[str, Any]) -> None:
body = json.dumps(payload).encode("utf-8")
self.send_response(code)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)

def log_message(self, format: str, *args: Any) -> None: # noqa: A002
return

self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
self.base_url = "http://127.0.0.1:{0}/v1".format(self._server.server_port)
self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
self._thread.start()

def __enter__(self) -> "FakeOpenAI":
return self

def __exit__(self, *_exc: Any) -> None:
self._server.shutdown()
self._server.server_close()
self._thread.join()
26 changes: 26 additions & 0 deletions python/examples/gradio/tests/_guard_probe.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
"""A test-only probe: try three non-loopback connections under the loopback guard.

The contract test runs this through ``_guarded_run.py`` to prove the guard
really refuses and logs a non-loopback attempt, so the ``guard_attempts == []``
assertions elsewhere cannot pass because the guard silently stopped working.
The targets are reserved and never reachable: TEST-NET-1 (RFC 5737), the IPv6
documentation prefix (RFC 3849) and the ``.invalid`` TLD (RFC 2606).
Not part of the recipe.
"""

from __future__ import annotations

import socket

refused = []
for label, attempt in (
("connect", lambda: socket.socket(socket.AF_INET, socket.SOCK_STREAM).connect(("192.0.2.1", 80))),
("connect_ex", lambda: socket.socket(socket.AF_INET6, socket.SOCK_STREAM).connect_ex(("2001:db8::1", 80, 0, 0))),
("getaddrinfo", lambda: socket.getaddrinfo("example.invalid", 443)),
):
try:
attempt()
except OSError as error:
if "blocked by loopback guard" in str(error):
refused.append(label)
print("refused:", ",".join(refused))
81 changes: 81 additions & 0 deletions python/examples/gradio/tests/_guarded_run.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
"""Run a script with every non-loopback network connection blocked and logged.

Usage: python _guarded_run.py <script.py> [args...]

Before the script starts, ``socket.socket.connect``/``connect_ex`` and
``socket.getaddrinfo`` refuse any host other than 127.0.0.1, ::1 or
localhost. Each refused attempt is appended as a JSON line to the file named
by ``LOOPBACK_GUARD_LOG``, so a test can assert that Gradio, traceAI and the
example tried to reach nothing else (no Gradio analytics host, no real
OpenAI, no Future AGI). Unix sockets are not affected.
"""

from __future__ import annotations

import json
import os
import runpy
import socket
import sys

_ALLOWED_HOSTS = {"127.0.0.1", "::1", "localhost"}
_LOG_PATH = os.environ.get("LOOPBACK_GUARD_LOG", "")


def _host(value: object) -> str:
if isinstance(value, bytes):
return value.decode("ascii", "replace")
return str(value)


def _refuse(kind: str, target: object) -> None:
if _LOG_PATH:
with open(_LOG_PATH, "a", encoding="utf-8") as log:
log.write(json.dumps({"kind": kind, "target": repr(target)}) + "\n")


_original_connect = socket.socket.connect
_original_connect_ex = socket.socket.connect_ex
_original_getaddrinfo = socket.getaddrinfo


def _is_blocked(sock: socket.socket, address: object) -> bool:
if sock.family not in (socket.AF_INET, socket.AF_INET6):
return False
host = address[0] if isinstance(address, tuple) else address
return _host(host) not in _ALLOWED_HOSTS


def _connect(self: socket.socket, address: object) -> None:
if _is_blocked(self, address):
_refuse("connect", address)
raise OSError("blocked by loopback guard: {0!r}".format(address))
return _original_connect(self, address)


def _connect_ex(self: socket.socket, address: object) -> int:
if _is_blocked(self, address):
_refuse("connect_ex", address)
raise OSError("blocked by loopback guard: {0!r}".format(address))
return _original_connect_ex(self, address)


def _getaddrinfo(host: object, *args: object, **kwargs: object): # type: ignore[no-untyped-def]
if host is not None and _host(host) not in _ALLOWED_HOSTS:
_refuse("getaddrinfo", host)
raise socket.gaierror("blocked by loopback guard: {0!r}".format(host))
return _original_getaddrinfo(host, *args, **kwargs)


def main() -> None:
socket.socket.connect = _connect # type: ignore[method-assign]
socket.socket.connect_ex = _connect_ex # type: ignore[method-assign]
socket.getaddrinfo = _getaddrinfo # type: ignore[assignment]
script = sys.argv[1]
sys.argv = sys.argv[1:]
sys.path.insert(0, os.path.dirname(os.path.abspath(script)))
runpy.run_path(script, run_name="__main__")


if __name__ == "__main__":
main()
Loading
Loading