provekit 0.1.0__py3-none-any.whl

provekit/services/flow.py

@@ -0,0 +1,299 @@
+"""Generic visual-flow engine. Walks a graph of nodes (input · prompt · tool · agent ·
+condition · output), threading a shared context, and streams rich per-node events so the
+canvas can animate + inspect execution. Nodes reuse the providers via dispatch.run_collect.
+Supports breakpoints + single-step (like a debugger).
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+import uuid
+
+from . import dispatch
+from .runstore import drop_ctx as _drop_run
+from .runstore import pop_ctx
+from .runstore import store_ctx as _store_run
+
+MAX_STEPS = 100
+_REF = re.compile(r"\{\{\s*([\w.\-]+)\s*\}\}")
+
+
+def _skey(run_id: str, workspace_id) -> str:
+    """Namespace a stored run context by workspace so /continue can only resume runs from
+    the caller's own workspace — a foreign run_id misses the store instead of popping (and
+    deleting) another tenant's paused context."""
+    return f"{workspace_id if workspace_id is not None else 0}:{run_id}"
+
+
+def pop_run(run_id: str, workspace_id=None) -> dict | None:
+    """Atomically remove and return a paused run context for a workspace (None if absent)."""
+    return pop_ctx(_skey(run_id, workspace_id))
+
+# Catalog served to the frontend palette + inspector.
+NODE_TYPES = {
+    "input": {"label": "Input", "category": "trigger", "color": "muted"},
+    "prompt": {"label": "Prompt", "category": "ai", "color": "prompt"},
+    "tool": {"label": "Tool", "category": "tool", "color": "tool"},
+    "agent": {"label": "Agent", "category": "agent", "color": "agent"},
+    "condition": {"label": "Condition", "category": "logic", "color": "purple", "branches": ["true", "false"]},
+    "output": {"label": "Output", "category": "output", "color": "ok"},
+}
+
+
+def _resolve(ref: str, ctx: dict):
+    parts = [p for p in ref.split(".") if p]
+    if not parts:
+        return None
+    root = parts[0]
+    cur = ctx.get("input") if root == "input" else (ctx.get("nodes") or {}).get(root)
+    for p in parts[1:]:
+        if isinstance(cur, dict):
+            cur = cur.get(p)
+        elif isinstance(cur, list):
+            try:
+                cur = cur[int(p)]
+            except (ValueError, IndexError):
+                return None
+        else:
+            return None
+    return cur
+
+
+def _interp(text, ctx):
+    if not isinstance(text, str):
+        return text
+
+    def sub(m):
+        v = _resolve(m.group(1), ctx)
+        if v is None:
+            return m.group(0)
+        return v if isinstance(v, str) else json.dumps(v)
+    return _REF.sub(sub, text)
+
+
+def _interp_obj(obj, ctx):
+    if isinstance(obj, str):
+        return _interp(obj, ctx)
+    if isinstance(obj, list):
+        return [_interp_obj(x, ctx) for x in obj]
+    if isinstance(obj, dict):
+        return {k: _interp_obj(v, ctx) for k, v in obj.items()}
+    return obj
+
+
+def _mask_config(cfg):
+    """Mask secrets in a node's config before it's streamed to the canvas — an agent node's
+    inline `headers` or `body` can carry a credential that must not leak into run events."""
+    from .masking import mask_body, mask_headers
+    if not isinstance(cfg, dict):
+        return cfg
+    hdrs = cfg.get("headers")
+    out = mask_body({k: v for k, v in cfg.items() if k != "headers"})
+    if isinstance(hdrs, dict):
+        out["headers"] = mask_headers(hdrs)
+    return out
+
+
+def _trim(v, _d=0):
+    if _d > 6:
+        return "…"
+    if isinstance(v, str):
+        return v if len(v) <= 2000 else v[:2000] + "…"
+    if isinstance(v, dict):
+        return {k: _trim(x, _d + 1) for k, x in list(v.items())[:50]}
+    if isinstance(v, list):
+        return [_trim(x, _d + 1) for x in v[:40]]
+    return v
+
+
+def _adjacency(edges):
+    adj = {}
+    for e in edges:
+        adj.setdefault(e["source"], []).append(e)
+    return adj
+
+
+def _next(adj, cur, branch):
+    outs = adj.get(cur, [])
+    if branch is not None:
+        for e in outs:
+            if (e.get("condition") or {}).get("branch") == branch:
+                return e["target"]
+        return None
+    uncond = [e for e in outs if not (e.get("condition") or {}).get("branch")]
+    return (uncond[0]["target"] if uncond else (outs[0]["target"] if outs else None))
+
+
+def _find_trigger(graph):
+    indeg = {n["id"]: 0 for n in graph["nodes"]}
+    for e in graph["edges"]:
+        if e["target"] in indeg:
+            indeg[e["target"]] += 1
+    for n in graph["nodes"]:
+        if n["type"] == "input" and indeg.get(n["id"], 0) == 0:
+            return n["id"]
+    for n in graph["nodes"]:
+        if indeg.get(n["id"], 0) == 0:
+            return n["id"]
+    return graph["nodes"][0]["id"] if graph["nodes"] else None
+
+
+async def _exec_node(db, node, ctx, variables=None, workspace_id=None):
+    """Execute one node; return (output, branch). `variables` (the active environment)
+    fill any {{name}} refs the flow context didn't resolve, matching console behavior."""
+    t = node["type"]
+    cfg = node.get("config") or {}
+    if t == "input":
+        return ctx.get("input") or {}, None
+    if t == "prompt":
+        system = cfg.get("system")
+        if cfg.get("prompt_key"):  # pull the shared prompt from the registry (single source of truth)
+            reg = _registry_prompt(db, cfg["prompt_key"], workspace_id)
+            if reg is not None:
+                system = reg
+        req = {"type": "prompt", "connection_id": cfg.get("connection_id"), "model": cfg.get("model"),
+               "system": _interp(system, ctx), "user": _interp(cfg.get("user", ""), ctx),
+               "temperature": cfg.get("temperature", 0.7), "max_tokens": cfg.get("max_tokens", 1024)}
+        if cfg.get("tools"):  # MCP servers this node's model may call
+            req["tools"] = cfg["tools"]
+            req["max_tool_rounds"] = cfg.get("max_tool_rounds", 5)
+        r = await dispatch.run_collect(db, req, variables, workspace_id)
+        if r["status"] == "failed":
+            raise RuntimeError(r["error"] or "prompt failed")
+        # Surface tool calls downstream only when there were some — a tool-free prompt node
+        # keeps its existing {"text": ...} output shape.
+        out = {"text": r["text"]}
+        if r.get("events"):
+            out["events"] = r["events"]
+        return out, None
+    if t == "tool":
+        req = {"type": "tool", "connection_id": cfg.get("connection_id"), "tool": cfg.get("tool"),
+               "args": _interp_obj(cfg.get("args") or {}, ctx)}
+        r = await dispatch.run_collect(db, req, variables, workspace_id)
+        if r["status"] == "failed":
+            raise RuntimeError(r["error"] or "tool failed")
+        return r["output"], None
+    if t == "agent":
+        req = {"type": "agent", "connection_id": cfg.get("connection_id"), "method": cfg.get("method", "POST"),
+               "path": _interp(cfg.get("path", ""), ctx), "headers": cfg.get("headers") or {},
+               "body": _interp_obj(cfg.get("body"), ctx)}
+        r = await dispatch.run_collect(db, req, variables, workspace_id)
+        if r["status"] == "failed":
+            raise RuntimeError(r["error"] or "agent failed")
+        return r["output"], None
+    if t == "condition":
+        # Unresolved refs become "" (not the literal "{{ref}}") so `exists`/comparisons are correct.
+        left = _interp_blank(cfg.get("left", ""), ctx)
+        right = _interp_blank(cfg.get("right", ""), ctx)
+        op = cfg.get("op", "==")
+        ok = _compare(left, right, op)
+        return {"result": ok, "left": left, "right": right, "op": op}, ("true" if ok else "false")
+    if t == "output":
+        val = _interp_obj(cfg.get("value", ""), ctx)
+        return {"value": val}, None
+    return {}, None
+
+
+def _registry_prompt(db, key: str, workspace_id=None):
+    """Resolve a Prompt Registry entry's content by key within the workspace (None if missing)."""
+    from ..models import Prompt
+    q = db.query(Prompt).filter(Prompt.key == key)
+    if workspace_id is not None:
+        q = q.filter(Prompt.workspace_id == workspace_id)
+    row = q.first()
+    return row.content if row else None
+
+
+def _interp_blank(text, ctx):
+    """Like _interp but resolves unknown refs to "" instead of echoing the literal template —
+    correct for condition comparisons / exists checks."""
+    if not isinstance(text, str):
+        return text
+
+    def sub(m):
+        v = _resolve(m.group(1), ctx)
+        if v is None:
+            return ""
+        return v if isinstance(v, str) else json.dumps(v)
+    return _REF.sub(sub, text)
+
+
+def _compare(left, right, op):
+    if op == "exists":
+        return left not in (None, "", "null")
+    if op == "contains":
+        return str(right) in str(left)
+    if op in ("==", "equals"):
+        return str(left) == str(right)
+    if op == "!=":
+        return str(left) != str(right)
+    try:
+        lf, rf = float(left), float(right)
+        return lf > rf if op == ">" else lf < rf if op == "<" else False
+    except (ValueError, TypeError):
+        return False
+
+
+async def run_stream(db, flow: dict, flow_input: dict, breakpoints=None, single_step=False,
+               start_at=None, ctx=None, run_id=None, variables=None, workspace_id=None):
+    breakpoints = set(breakpoints or [])
+    graph = {"nodes": flow["nodes"], "edges": flow["edges"]}
+    nodes = {n["id"]: n for n in graph["nodes"]}
+    adj = _adjacency(graph["edges"])
+    ctx = ctx or {"input": flow_input or {}, "nodes": {}}
+    rid = run_id or uuid.uuid4().hex[:12]
+    yield {"type": "start", "run_id": rid}
+
+    skey = _skey(rid, workspace_id)
+    node_id = start_at or _find_trigger(graph)
+    steps, first = ctx.get("_steps", 0), True  # cumulative across pause/continue so cycles stay bounded
+    while node_id:
+        # Skip the breakpoint check only for the node we're resuming ONTO.
+        if node_id in breakpoints and not (first and start_at):
+            ctx["_steps"] = steps
+            _store_run(skey, ctx)
+            yield {"type": "pause", "node_id": node_id, "run_id": rid, "reason": "breakpoint"}
+            return
+        steps += 1
+        if steps > MAX_STEPS:
+            _drop_run(skey)
+            yield {"type": "error", "error": "step budget exceeded (cycle?)"}
+            yield {"type": "done", "status": "failed"}
+            return
+        node = nodes.get(node_id)
+        if not node:
+            break
+        ntype = node["type"]
+        title = (node.get("data") or {}).get("title") or NODE_TYPES.get(ntype, {}).get("label", ntype)
+        yield {"type": "node", "node_id": node_id, "node_type": ntype, "title": title, "status": "running"}
+        t0 = time.monotonic()
+        try:
+            output, branch = await _exec_node(db, node, ctx, variables, workspace_id)
+        except Exception as exc:
+            _drop_run(skey)
+            yield {"type": "node", "node_id": node_id, "node_type": ntype, "title": title,
+                   "status": "error", "error": str(exc)[:400], "duration_ms": round((time.monotonic() - t0) * 1000)}
+            yield {"type": "done", "status": "failed"}
+            return
+        dur = round((time.monotonic() - t0) * 1000)
+        ctx["nodes"][node_id] = output
+        yield {"type": "node", "node_id": node_id, "node_type": ntype, "title": title, "status": "ok",
+               "branch": branch, "duration_ms": dur, "input": _trim(_mask_config(node.get("config") or {})),
+               "output": _trim(output)}
+        nxt = _next(adj, node_id, branch)
+        if single_step and nxt:
+            ctx["_steps"] = steps
+            _store_run(skey, ctx)
+            yield {"type": "pause", "node_id": nxt, "run_id": rid, "reason": "step"}
+            return
+        node_id = nxt
+        first = False
+
+    _drop_run(skey)
+    yield {"type": "done", "status": "completed", "output": _trim({k: v for k, v in (ctx.get("nodes") or {}).items()})}
+
+
+# pop_run wraps the runstore's GETDEL-atomic pop with per-workspace key namespacing so a
+# concurrent /continue can't resume twice and a foreign run_id can't touch another tenant.
+__all__ = ["run_stream", "pop_run", "NODE_TYPES"]

provekit/services/limits.py

@@ -0,0 +1,109 @@
+"""Rate limiting + quotas, so one workspace can't exhaust shared infrastructure.
+
+Fixed-window per-workspace counter. Redis-backed when REDIS_URL is set (correct across
+workers), else in-memory. A dependency raises 429 with Retry-After when the window is full.
+Local mode (no hosting) leaves the limit generous; tune via RATE_LIMIT_PER_MIN.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+from functools import lru_cache
+
+from fastapi import Depends, HTTPException
+
+from ..config import get_settings
+from ..models import Workspace
+from .workspace import current_workspace
+
+
+class _MemoryWindow:
+    def __init__(self):
+        # LRU-ordered so eviction drops the oldest bucket, never the one being counted.
+        self._c: OrderedDict[str, int] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def hit(self, key: str, ttl: int) -> int:
+        # Streams run concurrently in the threadpool, so the read-modify-write must be atomic
+        # or concurrent hits under-count and admit more than the limit.
+        with self._lock:
+            count = self._c.get(key, 0) + 1
+            self._c[key] = count
+            self._c.move_to_end(key)  # mark as most-recently-used
+            while len(self._c) > 10_000:
+                self._c.popitem(last=False)  # evict least-recently-used, keeping live buckets
+            return count
+
+
+class _RedisWindow:
+    def __init__(self, url: str):
+        import redis
+        self._r = redis.Redis.from_url(url, decode_responses=True)
+
+    def hit(self, key: str, ttl: int) -> int:
+        pipe = self._r.pipeline()
+        pipe.incr(key)
+        pipe.expire(key, ttl)
+        return pipe.execute()[0]
+
+
+@lru_cache
+def _window():
+    url = get_settings().redis_url
+    return _RedisWindow(url) if url else _MemoryWindow()
+
+
+def _now() -> int:
+    # time.time() is fine here (not a resumable workflow); windows are wall-clock minutes.
+    return int(time.time())
+
+
+def check_rate(ws: Workspace = Depends(current_workspace)) -> Workspace:
+    """Dependency: enforce the per-workspace request rate on run endpoints."""
+    limit = get_settings().rate_limit_per_min
+    if limit <= 0:
+        return ws
+    window = _now() // 60
+    key = f"rl:{ws.id}:{window}"
+    count = _window().hit(key, 60)
+    if count > limit:
+        raise HTTPException(429, "Rate limit exceeded — slow down.",
+                            headers={"Retry-After": str(60 - (_now() % 60))})
+    return ws
+
+
+def check_login_rate(ident: str) -> None:
+    """Throttle login attempts per identifier (email+IP) to blunt brute force."""
+    limit = get_settings().login_attempts_per_min
+    if limit <= 0:
+        return
+    key = f"login:{ident}:{_now() // 60}"
+    if _window().hit(key, 60) > limit:
+        raise HTTPException(429, "Too many login attempts — wait a minute.",
+                            headers={"Retry-After": str(60 - (_now() % 60))})
+
+
+def enforce_dataset_size(n_rows: int) -> None:
+    cap = get_settings().dataset_max_rows
+    if cap and n_rows > cap:
+        raise HTTPException(400, f"Dataset too large: {n_rows} rows (max {cap}).")
+
+
+def clamp_max_tokens(req: dict) -> None:
+    cap = get_settings().max_tokens_cap
+    if cap and isinstance(req.get("max_tokens"), int) and req["max_tokens"] > cap:
+        req["max_tokens"] = cap
+
+
+def prune_runs(db, workspace_id: int) -> None:
+    """Keep only the most recent N runs per workspace (called after an insert)."""
+    keep = get_settings().runs_retention
+    if not keep:
+        return
+    from ..models import Run
+    ids = [r.id for r in db.query(Run.id).filter(Run.workspace_id == workspace_id)
+           .order_by(Run.id.desc()).offset(keep).all()]
+    if ids:
+        db.query(Run).filter(Run.id.in_(ids)).delete(synchronize_session=False)
+        db.commit()

provekit/services/masking.py

@@ -0,0 +1,45 @@
+"""Masking helpers for secret values in API responses and persisted records."""
+from __future__ import annotations
+
+import re
+
+MASK = "••••••"
+
+# Header keys whose values are secrets — masked in API responses and run history.
+SECRET_HEADERS = {"authorization", "x-api-key", "api-key", "cookie", "x-auth-token", "proxy-authorization"}
+# Also treat any header whose name looks credential-bearing as secret (e.g. X-Custom-Token),
+# so masking isn't limited to the fixed set above.
+_SECRET_HEADER_RE = re.compile(r"(authorization|api[-_]?key|secret|token|password|passwd|cookie|credential|session)", re.I)
+
+
+def is_secret_header(name: str) -> bool:
+    n = str(name).lower()
+    return n in SECRET_HEADERS or bool(_SECRET_HEADER_RE.search(n))
+
+
+def mask_value(v) -> str:
+    s = str(v)
+    return MASK + s[-4:] if len(s) > 4 else MASK
+
+
+def mask_headers(headers: dict) -> dict:
+    return {k: (mask_value(v) if is_secret_header(k) and v else v) for k, v in headers.items()}
+
+
+def is_masked(v) -> bool:
+    return isinstance(v, str) and v.startswith(MASK)
+
+
+# Body fields whose values look like secrets — masked before persisting to history.
+_SECRET_FIELDS = {"api_key", "apikey", "token", "access_token", "refresh_token", "password",
+                  "secret", "client_secret", "authorization"}
+
+
+def mask_body(obj):
+    """Recursively mask secret-looking fields in a request/response body for storage."""
+    if isinstance(obj, dict):
+        return {k: (mask_value(v) if k.lower() in _SECRET_FIELDS and v and isinstance(v, str)
+                    else mask_body(v)) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [mask_body(x) for x in obj]
+    return obj

provekit/services/netguard.py

@@ -0,0 +1,69 @@
+"""Outbound URL guard (SSRF protection), enforced at every provider entry point.
+
+Local mode (default): this is a dev tool that legitimately targets localhost and
+private IPs, so those stay allowed — only the link-local block (incl. the
+169.254.169.254 cloud-metadata endpoint) is refused.
+
+Hosted mode (HOSTED=true): all private/reserved ranges are blocked, and hostnames
+are DNS-resolved so a name pointing at an internal IP is caught too. A rebinding
+server could still answer differently on the actual connect — pinning connections
+through an egress proxy is the complete fix; accepted residual risk pre-GA.
+"""
+from __future__ import annotations
+
+import ipaddress
+import socket
+from urllib.parse import urlparse
+
+from ..config import get_settings
+
+_BLOCKED_HOSTS = {"metadata", "metadata.google.internal"}
+
+
+class BlockedURL(ValueError):
+    """Raised when an outbound URL targets a forbidden address."""
+
+
+def guard_stdio() -> None:
+    """Refuse to spawn a local MCP server process in hosted mode.
+
+    stdio MCP connections run an arbitrary `command` on the server (subprocess.Popen).
+    That is fine for a single-user local install, but on shared/hosted infrastructure it
+    is remote code execution: any authenticated tenant could run arbitrary programs. URLs
+    are policed by guard_url; this is the equivalent gate for the process transport.
+    """
+    if get_settings().hosted:
+        raise BlockedURL("Local process (stdio) MCP connections are disabled in hosted mode")
+
+
+def _check_ip(ip, hosted: bool) -> None:
+    if ip.is_link_local:
+        raise BlockedURL("Link-local / metadata addresses are not allowed")
+    if hosted and not ip.is_global:
+        raise BlockedURL("Private / internal addresses are not allowed in hosted mode")
+
+
+def guard_url(url: str) -> None:
+    hosted = get_settings().hosted
+    host = (urlparse(str(url)).hostname or "").lower()
+    if not host:
+        raise BlockedURL("URL has no host")
+    if host in _BLOCKED_HOSTS:
+        raise BlockedURL("Target host is not allowed")
+
+    ip = None
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        pass  # not a literal IP — a hostname
+    if ip is not None:
+        _check_ip(ip, hosted)
+        return
+
+    if hosted:
+        try:
+            infos = socket.getaddrinfo(host, None)
+        except OSError:
+            raise BlockedURL(f"Cannot resolve host '{host}'")
+        for info in infos:
+            _check_ip(ipaddress.ip_address(info[4][0]), hosted)

provekit/services/otel.py

@@ -0,0 +1,146 @@
+"""OpenTelemetry GenAI ingest + emit.
+
+Ingest: accept OTLP/HTTP-JSON trace exports and map gen_ai.* spans into ProveKit runs,
+so a user SEES traces from an agent built in ANY framework (ADK, Strands, Pydantic AI,
+CrewAI, Semantic Kernel, OpenAI Agents SDK…) without swapping in our SDK.
+
+The gen_ai semantic conventions are still churning, so the mapping is deliberately thin
+and accepts three dialects:
+  - current  gen_ai.* v1.37+  (gen_ai.input.messages / gen_ai.output.messages,
+             gen_ai.provider.name, gen_ai.request.model, gen_ai.usage.*)
+  - legacy   gen_ai.prompt / gen_ai.completion / gen_ai.system
+  - OpenInference  llm.* / input.value / output.value
+
+Emit: optionally export ProveKit's own runs as gen_ai spans to an OTLP collector, the
+dual-export escape hatch buyers now expect.
+"""
+from __future__ import annotations
+
+import json
+import logging
+
+log = logging.getLogger("provekit.otel")
+
+
+def _attr_value(v: dict):
+    if "stringValue" in v:
+        return v["stringValue"]
+    if "intValue" in v:
+        return int(v["intValue"])
+    if "doubleValue" in v:
+        return v["doubleValue"]
+    if "boolValue" in v:
+        return v["boolValue"]
+    if "arrayValue" in v:
+        return [_attr_value(x) for x in v["arrayValue"].get("values", [])]
+    if "kvlistValue" in v:
+        return {kv["key"]: _attr_value(kv["value"]) for kv in v["kvlistValue"].get("values", [])}
+    return None
+
+
+def flatten_attrs(attributes: list) -> dict:
+    return {a["key"]: _attr_value(a.get("value") or {}) for a in attributes or []}
+
+
+def _first(attrs: dict, *keys):
+    for k in keys:
+        if k in attrs and attrs[k] not in (None, ""):
+            return attrs[k]
+    return None
+
+
+def _as_text(v) -> str:
+    if v is None:
+        return ""
+    if isinstance(v, str):
+        return v
+    try:
+        return json.dumps(v)
+    except (TypeError, ValueError):
+        return str(v)
+
+
+def map_span(span: dict) -> dict | None:
+    """Map one OTLP span to Run kwargs, or None if it isn't a gen_ai/LLM span."""
+    attrs = flatten_attrs(span.get("attributes"))
+    model = _first(attrs, "gen_ai.request.model", "gen_ai.response.model", "llm.model_name", "gen_ai.model")
+    provider = _first(attrs, "gen_ai.provider.name", "gen_ai.system", "llm.provider")
+    operation = _first(attrs, "gen_ai.operation.name")
+    tool = _first(attrs, "gen_ai.tool.name")
+    is_genai = bool(model or provider or operation or tool
+                    or any(k.startswith(("gen_ai.", "llm.")) for k in attrs))
+    if not is_genai:
+        return None
+
+    prompt = _first(attrs, "gen_ai.input.messages", "gen_ai.prompt", "input.value", "llm.input_messages")
+    completion = _first(attrs, "gen_ai.output.messages", "gen_ai.completion", "output.value", "llm.output_messages")
+    usage = {}
+    it = _first(attrs, "gen_ai.usage.input_tokens", "gen_ai.usage.prompt_tokens", "llm.token_count.prompt")
+    ot = _first(attrs, "gen_ai.usage.output_tokens", "gen_ai.usage.completion_tokens", "llm.token_count.completion")
+    if it is not None:
+        usage["input_tokens"] = it
+    if ot is not None:
+        usage["output_tokens"] = ot
+
+    start = int(span.get("startTimeUnixNano") or 0)
+    end = int(span.get("endTimeUnixNano") or 0)
+    dur_ms = round((end - start) / 1e6) if end > start else 0
+    status = "failed" if (span.get("status") or {}).get("code") == 2 else "completed"
+
+    op = operation or ("execute_tool" if tool else "chat")
+    label = f"{op} {model}" if model else (span.get("name") or op)
+    meta = {"provider": provider, "model": model, "usage": usage, "source": "otel"}
+    if tool:
+        meta["tool"] = tool
+    return {
+        "type": "trace",
+        "label": label[:200],
+        "request": {"type": "trace", "provider": provider, "model": model,
+                    "operation": op, "input": _as_text(prompt)[:8000]},
+        "result": {"text": _as_text(completion) or None, "output": None, "meta": meta},
+        "status": status,
+        "duration_ms": dur_ms,
+        "error": (span.get("status") or {}).get("message", "") if status == "failed" else "",
+    }
+
+
+def ingest(payload: dict) -> list[dict]:
+    """Turn an OTLP ExportTraceServiceRequest into a list of Run kwargs (gen_ai spans only)."""
+    runs = []
+    for rs in payload.get("resourceSpans", []):
+        for ss in rs.get("scopeSpans", []) + rs.get("instrumentationLibrarySpans", []):
+            for span in ss.get("spans", []):
+                mapped = map_span(span)
+                if mapped:
+                    runs.append(mapped)
+    return runs
+
+
+# ---- emit (best-effort) ----
+def emit_run(run_row) -> None:
+    """Export one ProveKit run as a gen_ai span to an OTLP collector, if configured."""
+    from ..config import get_settings
+    url = get_settings().otel_export_url
+    if not url:
+        return
+    import httpx
+
+    from .netguard import guard_url
+    meta = (run_row.result or {}).get("meta") or {}
+    attrs = [{"key": "gen_ai.operation.name", "value": {"stringValue": run_row.type}}]
+    if meta.get("provider"):
+        attrs.append({"key": "gen_ai.provider.name", "value": {"stringValue": str(meta["provider"])}})
+    if meta.get("model"):
+        attrs.append({"key": "gen_ai.request.model", "value": {"stringValue": str(meta["model"])}})
+    usage = meta.get("usage") or {}
+    for src, dst in (("input_tokens", "gen_ai.usage.input_tokens"), ("output_tokens", "gen_ai.usage.output_tokens")):
+        if usage.get(src) is not None:
+            attrs.append({"key": dst, "value": {"intValue": int(usage[src])}})
+    body = {"resourceSpans": [{"scopeSpans": [{"spans": [{
+        "name": run_row.label or run_row.type, "attributes": attrs,
+        "status": {"code": 2 if run_row.status == "failed" else 1}}]}]}]}
+    try:
+        guard_url(url)
+        httpx.post(url, json=body, timeout=5, follow_redirects=False)
+    except Exception as exc:  # best-effort; never break a run on export failure
+        log.debug("otel emit failed: %s", exc)