evalrx 0.1.2__py3-none-any.whl

evalrx/models/tools/visual.py

@@ -0,0 +1,174 @@
+"""Visual perception tools — the T0 tier of the default visual-reasoning kit.
+
+``zoom_in`` is the single highest-value visual tool (the o3 / DeepEyes /
+Qwen3-VL-demo mechanism): crop a region, upscale it, and hand it back as a new
+image so the model can inspect fine detail.  Torch-free; PIL imported lazily.
+"""
+
+from __future__ import annotations
+
+import itertools
+import os
+from typing import Any
+
+from evalrx.core.tool import Tool, ToolResult
+
+_MIN_SIDE_FRAC = 0.05        # never zoom into a sliver thinner than 5% of a side
+_TARGET_SHORT_SIDE = 672     # upscale the crop so detail is actually visible
+_MAX_UPSCALE = 4.0           # ... but never blow pixels up more than 4x
+
+ZOOM_IN_DESCRIPTION = (
+    "Zoom into a rectangular region of the CURRENT image to inspect fine detail. "
+    "Pass bbox=[x0, y0, x1, y1] as FRACTIONS of the image width/height, each in "
+    "[0, 1], with (x0, y0) the top-left and (x1, y1) the bottom-right corner "
+    "(e.g. the right half is [0.5, 0.0, 1.0, 1.0]). The cropped, enlarged view "
+    "comes back as a new image. Zoom before answering questions about small "
+    "objects, text, or fine attributes."
+)
+
+ZOOM_IN_PARAMETERS = {
+    "type": "object",
+    "properties": {
+        "bbox": {
+            "type": "array",
+            "items": {"type": "number"},
+            "minItems": 4,
+            "maxItems": 4,
+            "description": "[x0, y0, x1, y1], fractions of width/height in [0, 1].",
+        },
+        "target": {
+            "type": "string",
+            "description": "What you are trying to see in this region (short phrase).",
+        },
+    },
+    "required": ["bbox"],
+}
+
+
+def _to_pil(image: Any):
+    """Return *image* as a PIL image (paths are opened and converted to RGB)."""
+    if hasattr(image, "size") and hasattr(image, "mode"):
+        return image
+    from PIL import Image
+
+    return Image.open(image).convert("RGB")
+
+
+def _sanitize_bbox(bbox: Any, width: int, height: int) -> "tuple[list[float], str]":
+    """Normalize *bbox* to fractional [x0, y0, x1, y1] and report the coord mode.
+
+    Models that ground in pixel coordinates are auto-detected (any value > 1.5)
+    and converted — the mode is recorded so the trajectory keeps evidence of
+    which convention the model actually used.
+    """
+    try:
+        vals = [float(v) for v in bbox]
+    except (TypeError, ValueError):
+        raise ValueError(f"bbox must be four numbers [x0, y0, x1, y1], got {bbox!r}")
+    if len(vals) != 4:
+        raise ValueError(f"bbox must have exactly 4 values [x0, y0, x1, y1], got {len(vals)}")
+
+    mode = "normalized"
+    if max(vals) > 1.5:  # not fractions: pixel coordinates or a Qwen-style 0-1000 grid
+        fits_pixels = (
+            max(vals[0], vals[2]) <= width * 1.05
+            and max(vals[1], vals[3]) <= height * 1.05
+        )
+        if fits_pixels:
+            mode = "pixel"
+            scale = (width, height, width, height)
+        else:  # out of pixel bounds -> 0-1000 normalized grid
+            mode = "grid_1000"
+            scale = (1000.0, 1000.0, 1000.0, 1000.0)
+        vals = [v / s for v, s in zip(vals, scale)]
+
+    x0, y0, x1, y1 = vals
+    if x1 < x0:
+        x0, x1 = x1, x0
+    if y1 < y0:
+        y0, y1 = y1, y0
+    x0, y0 = max(0.0, x0), max(0.0, y0)
+    x1, y1 = min(1.0, x1), min(1.0, y1)
+
+    # expand degenerate/sliver boxes around their center to a usable minimum
+    for lo, hi in ((0, 2), (1, 3)):
+        box = [x0, y0, x1, y1]
+        if box[hi] - box[lo] < _MIN_SIDE_FRAC:
+            center = (box[lo] + box[hi]) / 2
+            lo_v = min(max(0.0, center - _MIN_SIDE_FRAC / 2), 1.0 - _MIN_SIDE_FRAC)
+            if lo == 0:
+                x0, x1 = lo_v, lo_v + _MIN_SIDE_FRAC
+            else:
+                y0, y1 = lo_v, lo_v + _MIN_SIDE_FRAC
+    return [x0, y0, x1, y1], mode
+
+
+def zoom_in_tool(
+    image: Any,
+    *,
+    save_dir: "str | None" = None,
+    target_short_side: int = _TARGET_SHORT_SIDE,
+    max_upscale: float = _MAX_UPSCALE,
+) -> Tool:
+    """Build the ``image_zoom_in`` tool bound to *image* (PIL or path).
+
+    The returned crop is upscaled (LANCZOS) so its short side reaches
+    *target_short_side* (capped at *max_upscale*), and re-injected into the
+    conversation by the agent loop.  When *save_dir* is given every crop is
+    also written there (``zoom_00.png``, ...) and the path recorded in
+    ``ToolResult.meta`` — trajectories reference media rather than embed it.
+    """
+    base = _to_pil(image)
+    width, height = base.size
+    counter = itertools.count()
+
+    def _zoom(bbox, target: str = "") -> ToolResult:
+        frac, mode = _sanitize_bbox(bbox, width, height)
+        px = (
+            int(round(frac[0] * width)),
+            int(round(frac[1] * height)),
+            int(round(frac[2] * width)),
+            int(round(frac[3] * height)),
+        )
+        crop = base.crop(px)
+        short = min(crop.size)
+        if short > 0 and short < target_short_side:
+            factor = min(target_short_side / short, max_upscale)
+            if factor > 1.0:
+                from PIL import Image
+
+                crop = crop.resize(
+                    (int(round(crop.size[0] * factor)), int(round(crop.size[1] * factor))),
+                    Image.LANCZOS,
+                )
+
+        meta: dict = {
+            "bbox_frac": [round(v, 4) for v in frac],
+            "crop_px": list(px),
+            "coord_mode": mode,
+        }
+        if target:
+            meta["target"] = target
+        if save_dir:
+            os.makedirs(save_dir, exist_ok=True)
+            path = os.path.join(save_dir, f"zoom_{next(counter):02d}.png")
+            crop.save(path)
+            meta["saved_path"] = path
+
+        note = "" if mode == "normalized" else f" (coordinates interpreted as {mode})"
+        return ToolResult(
+            text=(
+                f"Zoomed into region x:[{frac[0]:.2f}, {frac[2]:.2f}] "
+                f"y:[{frac[1]:.2f}, {frac[3]:.2f}] of the {width}x{height} image{note}. "
+                f"The enlarged {crop.size[0]}x{crop.size[1]} view is attached as a new image."
+            ),
+            images=[crop],
+            meta=meta,
+        )
+
+    return Tool(
+        name="image_zoom_in",
+        description=ZOOM_IN_DESCRIPTION,
+        parameters=ZOOM_IN_PARAMETERS,
+        fn=_zoom,
+    )

evalrx/models/whitebox/__init__.py

@@ -0,0 +1,26 @@
+"""White-box (local) model entry points — per-version convenience factories.
+
+Identity lives in ``evalrx.specs``; these are thin wrappers over
+``compose(spec, "hf_local")``.  Import a specific version factory, e.g.::
+
+    from evalrx.models.whitebox import qwen3_8b, qwen3_vl_8b_instruct, qwen3_omni_30b_a3b_instruct
+"""
+
+from evalrx.models.whitebox import qwen as _qwen
+from evalrx.models.whitebox import qwen2_5_omni as _qwen2_5_omni
+from evalrx.models.whitebox import qwen2_audio as _qwen2_audio
+from evalrx.models.whitebox import qwen_omni as _qwen_omni
+from evalrx.models.whitebox import qwen_vl as _qwen_vl
+from evalrx.models.whitebox.qwen import *  # noqa: F401,F403  (QwenLLM + qwen text factories)
+from evalrx.models.whitebox.qwen2_5_omni import *  # noqa: F401,F403  (qwen2.5-omni factory)
+from evalrx.models.whitebox.qwen2_audio import *  # noqa: F401,F403  (qwen2-audio factory)
+from evalrx.models.whitebox.qwen_omni import *  # noqa: F401,F403  (qwen3-omni factories)
+from evalrx.models.whitebox.qwen_vl import *  # noqa: F401,F403  (QwenVL + qwen-vl factories)
+
+__all__ = sorted(
+    set(_qwen.__all__)
+    | set(_qwen_vl.__all__)
+    | set(_qwen_omni.__all__)
+    | set(_qwen2_5_omni.__all__)
+    | set(_qwen2_audio.__all__)
+)

evalrx/models/whitebox/agent.py

@@ -0,0 +1,31 @@
+"""Local agent wrapper with tool calling (white-box).
+
+Planned for Stage 2.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from evalrx.core.capability import Capability
+from evalrx.core.model import Trace
+from evalrx.models.base import BaseAgent
+from evalrx.models.whitebox.base import WhiteboxModel
+
+
+class WhiteboxAgent(WhiteboxModel, BaseAgent):
+    """Local model that can call external tools over multiple steps."""
+
+    capabilities = frozenset({Capability.GENERATE})
+
+    def load(self) -> None:
+        raise NotImplementedError("WhiteboxAgent is planned for Stage 2.")
+
+    def generate(self, inputs: Any, **kwargs) -> str:
+        raise NotImplementedError("WhiteboxAgent is planned for Stage 2.")
+
+    def forward(self, inputs: Any, capture: set[Capability]) -> Trace:
+        raise NotImplementedError("WhiteboxAgent is planned for Stage 2.")
+
+    def step(self, observation: str, **kwargs) -> str:
+        raise NotImplementedError("WhiteboxAgent is planned for Stage 2.")

evalrx/models/whitebox/base.py

@@ -0,0 +1,24 @@
+"""Base class for locally-deployed (white-box) models.
+
+White-box models have full parameter access, so they can provide rich
+capabilities (attention, hidden states, gradients).  Concrete subclasses
+declare their ``capabilities`` and implement ``generate`` + ``forward``.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+
+from evalrx.core.model import Model
+
+
+class WhiteboxModel(Model):
+    """Base for open-source models loaded with full parameter access.
+
+    Subclasses must implement :meth:`load`, :meth:`generate`, and
+    :meth:`forward`, and set the ``capabilities`` class attribute.
+    """
+
+    @abstractmethod
+    def load(self) -> None:
+        """Load model weights into memory (called lazily on first use)."""

evalrx/models/whitebox/qwen.py

@@ -0,0 +1,61 @@
+"""Qwen text LLMs (white-box, local) — per-version convenience factories.
+
+Model identity lives in :mod:`evalrx.specs`; these factories are **thin
+wrappers** over ``compose(spec, "hf_local")`` (via :func:`evalrx.load`), so
+there is NO per-version ``load``/``forward`` duplication — the single generic
+``hf_local`` backend does the work.  Each ``qwen…(**runtime)`` returns an
+hf_local model (caps: GENERATE, LOGITS, LOGPROBS, HIDDEN_STATES, ATTENTION; plus
+TOOL_CALLS when the model's chat template supports tools)::
+
+    from evalrx.models.whitebox.qwen import qwen3_8b
+    model = qwen3_8b(device="cuda", dtype="bfloat16")
+    # equivalent to: evalrx.load("qwen3-8b", backend="hf_local", ...)
+
+``QwenLLM(...)`` remains as a deprecated back-compat shim.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+# Spec keys exposed as factories (each must exist in evalrx.specs).
+_TEXT_KEYS = [
+    "qwen2.5-7b-instruct", "qwen2.5-14b-instruct", "qwen2.5-32b-instruct", "qwen2.5-72b-instruct",
+    "qwen3-4b", "qwen3-8b", "qwen3-14b", "qwen3-32b", "qwen3-30b-a3b", "qwen3-235b-a22b",
+]
+
+
+def _version_factory(key: str):
+    """A thin ``(**runtime) -> hf_local model`` builder for a spec *key*."""
+    def build(**runtime: Any):
+        from evalrx.models import load
+        return load(key, backend="hf_local", **runtime)
+
+    name = key.replace("-", "_").replace(".", "_")
+    build.__name__ = build.__qualname__ = name
+    build.__doc__ = (
+        f"Build {key!r} on the hf_local (white-box) backend. "
+        f"Thin wrapper over compose('{key}', 'hf_local')."
+    )
+    return build
+
+
+for _k in _TEXT_KEYS:
+    globals()[_k.replace("-", "_").replace(".", "_")] = _version_factory(_k)
+
+
+def QwenLLM(checkpoint: str | None = None, device: str = "auto", dtype: str = "bfloat16", **runtime: Any):
+    """Deprecated. Use a version factory (e.g. ``qwen2_5_7b_instruct()``) or
+    ``evalrx.load('qwen2.5-7b-instruct')``."""
+    warnings.warn(
+        "QwenLLM is deprecated; use a version factory (e.g. qwen2_5_7b_instruct()) "
+        "or evalrx.load('qwen2.5-7b-instruct').",
+        DeprecationWarning, stacklevel=2,
+    )
+    from evalrx.models import load
+    return load("qwen2.5-7b-instruct", backend="hf_local",
+                checkpoint=checkpoint, device=device, dtype=dtype, **runtime)
+
+
+__all__ = ["QwenLLM"] + [k.replace("-", "_").replace(".", "_") for k in _TEXT_KEYS]

evalrx/models/whitebox/qwen2_5_omni.py

@@ -0,0 +1,29 @@
+"""Qwen2.5-Omni (white-box, local) — convenience factory.
+
+Same pattern as :mod:`evalrx.models.whitebox.qwen_omni`: a thin wrapper over
+``compose(spec, "hf_local")`` (via :func:`evalrx.load`); identity lives in
+:mod:`evalrx.specs`. Registered separately from the Qwen3-Omni family
+because it is the checkpoint published paper methods (e.g. audio contrastive
+decoding) tend to report hyperparameters against — see the spec's caveats for
+its 300s audio-window truncation guard::
+
+    from evalrx.models.whitebox.qwen2_5_omni import qwen2_5_omni_7b
+    model = qwen2_5_omni_7b(device="cuda", dtype="bfloat16")
+    model.modalities   # frozenset({'text', 'image', 'audio', 'video'})
+
+Reference: https://github.com/QwenLM/Qwen2.5-Omni
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def qwen2_5_omni_7b(**runtime: Any):
+    """Build 'qwen2.5-omni-7b' on the hf_local (white-box) backend."""
+    from evalrx.models import load
+
+    return load("qwen2.5-omni-7b", backend="hf_local", **runtime)
+
+
+__all__ = ["qwen2_5_omni_7b"]

evalrx/models/whitebox/qwen2_audio.py

@@ -0,0 +1,25 @@
+"""Qwen2-Audio-Instruct (white-box, local) — convenience factory.
+
+Audio-in / text-out only (no vision tower) — the simplest audio-capable spec
+in the registry. Same thin-wrapper pattern as the other whitebox factories::
+
+    from evalrx.models.whitebox.qwen2_audio import qwen2_audio_7b_instruct
+    model = qwen2_audio_7b_instruct(device="cuda", dtype="bfloat16")
+    model.modalities   # frozenset({'text', 'audio'})
+
+Reference: https://github.com/QwenLM/Qwen2-Audio
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def qwen2_audio_7b_instruct(**runtime: Any):
+    """Build 'qwen2-audio-7b-instruct' on the hf_local (white-box) backend."""
+    from evalrx.models import load
+
+    return load("qwen2-audio-7b-instruct", backend="hf_local", **runtime)
+
+
+__all__ = ["qwen2_audio_7b_instruct"]

evalrx/models/whitebox/qwen_omni.py

@@ -0,0 +1,53 @@
+"""Qwen3-Omni models (white-box, local) — per-version convenience factories.
+
+Same pattern as :mod:`evalrx.models.whitebox.qwen` /
+:mod:`~evalrx.models.whitebox.qwen_vl`: thin wrappers over
+``compose(spec, "hf_local")`` (via :func:`evalrx.load`); identity lives in
+:mod:`evalrx.specs`.  An "omni" model is **not** a new class — it is a spec
+that carries vision *and* audio (+ video), so its modality set is
+``{"text", "image", "audio", "video"}`` and analyzers match on it::
+
+    from evalrx.models.whitebox.qwen_omni import qwen3_omni_30b_a3b_instruct
+    model = qwen3_omni_30b_a3b_instruct(device="cuda", dtype="bfloat16")
+    model.modalities   # frozenset({'text', 'image', 'audio', 'video'})
+
+NOTE: text generation works via the thinker; full multimodal generate
+(image/audio/video in) and white-box forward-capture over the vision/audio towers
+are Stage-2 (needs ``transformers>=5.2.0`` and ``qwen_omni_utils.process_mm_info``;
+pass ``use_audio_in_video`` consistently).  The Captioner is audio-in / text-out
+(modalities ``{"text", "audio"}``).
+
+Reference: https://github.com/QwenLM/Qwen3-Omni
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Spec keys exposed as factories (each must exist in evalrx.specs).
+_OMNI_KEYS = [
+    "qwen3-omni-30b-a3b-instruct",
+    "qwen3-omni-30b-a3b-thinking",
+    "qwen3-omni-30b-a3b-captioner",
+]
+
+
+def _version_factory(key: str):
+    def build(**runtime: Any):
+        from evalrx.models import load
+        return load(key, backend="hf_local", **runtime)
+
+    name = key.replace("-", "_").replace(".", "_")
+    build.__name__ = build.__qualname__ = name
+    build.__doc__ = (
+        f"Build {key!r} on the hf_local (white-box) backend. "
+        f"Thin wrapper over compose('{key}', 'hf_local')."
+    )
+    return build
+
+
+for _k in _OMNI_KEYS:
+    globals()[_k.replace("-", "_").replace(".", "_")] = _version_factory(_k)
+
+
+__all__ = [k.replace("-", "_").replace(".", "_") for k in _OMNI_KEYS]

evalrx/models/whitebox/qwen_vl.py

@@ -0,0 +1,62 @@
+"""Qwen vision-language models (white-box, local) — per-version convenience factories.
+
+Same pattern as :mod:`evalrx.models.whitebox.qwen`: thin wrappers over
+``compose(spec, "hf_local")`` (via :func:`evalrx.load`); identity lives in
+:mod:`evalrx.specs`.  Each ``qwen…vl…(**runtime)`` returns an hf_local VLM
+(modalities ``{"text", "image"}``)::
+
+    from evalrx.models.whitebox.qwen_vl import qwen3_vl_8b_instruct
+    model = qwen3_vl_8b_instruct(device="cuda", dtype="bfloat16")
+
+NOTE: text generation + logprobs work today; white-box forward-capture over image
+tokens (attention/hidden) uses the hf_local VLM path + ``core.tokentype.TokenTypeMap``.
+``QwenVL(...)`` remains as a deprecated back-compat shim.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+# Spec keys exposed as factories (each must exist in evalrx.specs).
+_VL_KEYS = [
+    "qwen2-vl-7b-instruct",
+    "qwen2.5-vl-3b-instruct", "qwen2.5-vl-7b-instruct",
+    "qwen2.5-vl-32b-instruct", "qwen2.5-vl-72b-instruct",
+    "qwen3-vl-2b-instruct", "qwen3-vl-4b-instruct", "qwen3-vl-8b-instruct",
+    "qwen3-vl-30b-a3b-instruct", "qwen3-vl-235b-a22b-instruct",
+]
+
+
+def _version_factory(key: str):
+    def build(**runtime: Any):
+        from evalrx.models import load
+        return load(key, backend="hf_local", **runtime)
+
+    name = key.replace("-", "_").replace(".", "_")
+    build.__name__ = build.__qualname__ = name
+    build.__doc__ = (
+        f"Build {key!r} on the hf_local (white-box) backend. "
+        f"Thin wrapper over compose('{key}', 'hf_local')."
+    )
+    return build
+
+
+for _k in _VL_KEYS:
+    globals()[_k.replace("-", "_").replace(".", "_")] = _version_factory(_k)
+
+
+def QwenVL(checkpoint: str | None = None, device: str = "auto", dtype: str = "bfloat16", **runtime: Any):
+    """Deprecated. Use a version factory (e.g. ``qwen3_vl_8b_instruct()``) or
+    ``evalrx.load('qwen2.5-vl-7b-instruct')``."""
+    warnings.warn(
+        "QwenVL is deprecated; use a version factory (e.g. qwen3_vl_8b_instruct()) "
+        "or evalrx.load('qwen2.5-vl-7b-instruct').",
+        DeprecationWarning, stacklevel=2,
+    )
+    from evalrx.models import load
+    return load("qwen2.5-vl-7b-instruct", backend="hf_local",
+                checkpoint=checkpoint, device=device, dtype=dtype, **runtime)
+
+
+__all__ = ["QwenVL"] + [k.replace("-", "_").replace(".", "_") for k in _VL_KEYS]

evalrx/observability/__init__.py

@@ -0,0 +1,21 @@
+"""EvalRX Observability Engine.
+
+Full OpenTelemetry and Langfuse integration for agent auditing, execution tracing,
+multi-dimensional probe measurement, and model I/O tracking.
+"""
+
+from __future__ import annotations
+
+from evalrx.observability.tracer import (
+    DiagnosticTracer,
+    backfill_run_to_langfuse,
+    export_to_langfuse_bundle,
+    sync_to_langfuse_live,
+)
+
+__all__ = [
+    "DiagnosticTracer",
+    "backfill_run_to_langfuse",
+    "export_to_langfuse_bundle",
+    "sync_to_langfuse_live",
+]

evalrx/observability/envelope.py

@@ -0,0 +1,122 @@
+"""Stable event and artifact envelopes shared by writers and future readers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import mimetypes
+import uuid
+from pathlib import Path
+from typing import Any  # noqa: I001 - kept with Path for Python 3.10 compatibility notes
+
+OBSERVABILITY_SCHEMA_VERSION = 1
+_EVENT_NAMESPACE = uuid.UUID("3a09f2ed-28b1-4dd4-914f-b8da031edab2")
+
+
+def make_event_envelope(
+    event: dict[str, Any], *, trace_id: str, event_seq: int,
+    artifact_refs: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Normalize a run-log record into an idempotent observability event."""
+    event_type = str(event.get("event") or "event")
+    event_id = str(uuid.uuid5(_EVENT_NAMESPACE, f"{trace_id}:{event_seq}:{event_type}"))
+    return {
+        "schema_version": OBSERVABILITY_SCHEMA_VERSION,
+        "event_id": event_id,
+        "trace_id": trace_id,
+        "event_seq": event_seq,
+        "timestamp": event.get("ts"),
+        "event_type": event_type,
+        "stage": _stage_for(event),
+        "cycle": event.get("cycle"),
+        "parent_id": event.get("span_id"),
+        "status": _status_for(event),
+        "payload": event,
+        "artifact_refs": artifact_refs or [],
+    }
+
+
+def artifact_manifest(path: str | Path, *, run_dir: str | Path, role: str = "artifact") -> dict[str, Any]:
+    """Describe an artifact without reading it into the event payload."""
+    artifact_path = Path(path)
+    root = Path(run_dir).resolve()
+    digest = hashlib.sha256()
+    with artifact_path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    try:
+        relative = str(artifact_path.relative_to(root))
+    except ValueError:
+        relative = artifact_path.name
+    return {
+        "artifact_id": f"sha256:{digest.hexdigest()}",
+        "role": role,
+        "path": relative,
+        "filename": artifact_path.name,
+        "mime_type": mimetypes.guess_type(artifact_path.name)[0] or "application/octet-stream",
+        "size_bytes": artifact_path.stat().st_size,
+    }
+
+
+def artifact_manifests_for_event(event: dict[str, Any], *, run_dir: str | Path) -> list[dict[str, Any]]:
+    """Find file references in a run event and turn them into content manifests.
+
+    Event fields intentionally contain relative paths, never inline binary
+    content.  This small adapter gives the Langfuse writer a complete upload
+    manifest without changing the established JSONL event shapes.
+    """
+    root = Path(run_dir).resolve()
+    candidates: list[tuple[str, str]] = []
+
+    def visit(value: Any, key: str = "artifact", path_like: bool = False) -> None:
+        if isinstance(value, dict):
+            for child_key, child in value.items():
+                child_key = str(child_key)
+                visit(child, child_key, path_like or child_key.endswith("path") or child_key.endswith("_paths") or child_key == "record")
+        elif isinstance(value, list):
+            for child in value:
+                visit(child, key, path_like)
+        elif isinstance(value, str) and path_like:
+            candidates.append((key, value))
+
+    visit(event)
+    manifests: list[dict[str, Any]] = []
+    seen: set[Path] = set()
+    for role, relative in candidates:
+        path = (root / relative).resolve()
+        if root not in path.parents:
+            continue
+        if not path.is_file() or path in seen:
+            continue
+        seen.add(path)
+        try:
+            manifests.append(artifact_manifest(path, run_dir=root, role=role))
+        except OSError:
+            continue
+    return manifests
+
+
+def canonical_json(value: Any) -> str:
+    """Canonical form used by parity checks and tests."""
+    return json.dumps(value, ensure_ascii=False, default=str, sort_keys=True, separators=(",", ":"))
+
+
+def _stage_for(event: dict[str, Any]) -> str:
+    # Lifecycle events carry their target stage in the payload; preserving it
+    # keeps a deliberately skipped M5 beside the rest of its evidence in
+    # Langfuse instead of burying it under an undifferentiated RUN row.
+    event_type = str(event.get("event") or "event")
+    if event_type == "stage_skipped":
+        return str(event.get("stage") or "RUN")
+    return {
+        "probe_search": "PRE_M1", "probe": "M1", "analysis": "M2",
+        "explore": "M2", "diagnosis": "M3", "surgery": "M4",
+        "fix": "M5", "experiment": "M5",
+        "case_record": "DATA", "report_published": "REPORT",
+    }.get(event_type, "RUN")
+
+
+def _status_for(event: dict[str, Any]) -> str:
+    if event.get("ok") is False or event.get("status") in {"failed", "error"}:
+        return "failed"
+    return "completed"