gooddata-eval 1.79.2.dev1__tar.gz → 1.80.0__tar.gz

{gooddata_eval-1.79.2.dev1 → gooddata_eval-1.80.0}/AGENTS.md

@@ -27,7 +27,7 @@ experiment. The newest and most actively developed package in the repo.
 | `core/agentic/` | multi-turn agentic evaluation per capability, **plus** all Langfuse trace polling and linking (`_langfuse.py`, `_trace_linker.py`) |
 | `core/chat/` | SSE client for the agent's streaming chat endpoint |
 | `core/summary/` | HTTP client for the dedicated dashboard-summary endpoint — a single-shot chat backend, not reporting |
-| `core/takeaway/` | HTTP client for the AI Publisher takeaway endpoint — a single-shot backend like `core/summary/`, keeping the whole response on `ChatResult.raw_response` — plus `evaluate_document_takeaway`, the K-run, gate and Langfuse entry point the Tavern shim calls |
+| `core/takeaway/` | HTTP client for the AI Publisher takeaway endpoint — a single-shot backend like `core/summary/`, keeping the whole response on `ChatResult.raw_response` — plus `evaluate_document_takeaway`, the K-run, gate and Langfuse entry point the Tavern shim calls. Also used by the agentic document skill to write the takeaways the copilot leaves to the editor, before the narrative is graded |
 | `core/dataset/` | dataset format, loading, and `from_insights.py` — dataset generation from a workspace's real insights |
 | `core/evaluators/` | single-shot evaluators and their registry |
 | `core/langfuse/` | the whole Langfuse v4 client: `_env` (base URL + credentials), `otlp` (OTLP/JSON encoding), `experiment` (root-span construction, score targets), `item_scope` (an item's experiment scope sent to gen-ai as baggage, and which conversations joined), `observations` (trace reads), `client` (httpx calls), `sink` (single-shot results as experiments) |

{gooddata_eval-1.79.2.dev1 → gooddata_eval-1.80.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gooddata-eval
-Version: 1.79.2.dev1
+Version: 1.80.0
 Summary: Evaluate the GoodData AI agent against your own questions and models.
 Project-URL: Source, https://github.com/gooddata/gooddata-python-sdk
 Author-email: GoodData <support@gooddata.com>
@@ -17,7 +17,7 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: gooddata-sdk~=1.79.2.dev1
+Requires-Dist: gooddata-sdk~=1.80.0
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: jsonpatch<2.0,>=1.33
 Requires-Dist: orjson<4.0.0,>=3.9.15
@@ -306,7 +306,8 @@ Each item additionally carries a per-phase breakdown:
 ```
 
 Every item reports `runs_ungraded` beside `runs_passed`: runs the agent answered but the LLM judge returned
-nothing readable for. Agentic items also list them as `unscored_runs` / `judge_errors` in their `detail`, and a
+nothing readable for. Agentic items also list them as `unscored_runs` / `judge_errors` in their `detail` (a document item whose takeaway-endpoint request failed
+lists that failure under `request_errors` instead), and a
 `dashboard_summary` item carries `ungraded_criteria`. Such a run — or, for `dashboard_summary`, such a
 criterion — is excluded from pass@K and from the quality score rather than counted as a failure: scoring it 0
 would be indistinguishable from the judge genuinely failing the answer, which is the confusion

{gooddata_eval-1.79.2.dev1 → gooddata_eval-1.80.0}/README.md

@@ -277,7 +277,8 @@ Each item additionally carries a per-phase breakdown:
 ```
 
 Every item reports `runs_ungraded` beside `runs_passed`: runs the agent answered but the LLM judge returned
-nothing readable for. Agentic items also list them as `unscored_runs` / `judge_errors` in their `detail`, and a
+nothing readable for. Agentic items also list them as `unscored_runs` / `judge_errors` in their `detail` (a document item whose takeaway-endpoint request failed
+lists that failure under `request_errors` instead), and a
 `dashboard_summary` item carries `ungraded_criteria`. Such a run — or, for `dashboard_summary`, such a
 criterion — is excluded from pass@K and from the quality score rather than counted as a failure: scoring it 0
 would be indistinguishable from the judge genuinely failing the answer, which is the confusion

{gooddata_eval-1.79.2.dev1 → gooddata_eval-1.80.0}/pyproject.toml

@@ -1,7 +1,7 @@
 # (C) 2026 GoodData Corporation
 [project]
 name = "gooddata-eval"
-version = "1.79.2.dev1"
+version = "1.80.0"
 description = "Evaluate the GoodData AI agent against your own questions and models."
 readme = "README.md"
 license = "MIT"
@@ -11,7 +11,7 @@ authors = [
 keywords = ["gooddata", "ai", "evaluation", "llm", "analytics", "cli"]
 requires-python = ">=3.10"
 dependencies = [
-    "gooddata-sdk~=1.79.2.dev1",
+    "gooddata-sdk~=1.80.0",
     "httpx>=0.27,<1.0",
     "jsonpatch>=1.33,<2.0",
     "orjson>=3.9.15,<4.0.0",

{gooddata_eval-1.79.2.dev1 → gooddata_eval-1.80.0}/src/gooddata_eval/cli/agentic_runner.py

@@ -16,7 +16,9 @@ from gooddata_eval.core.agentic.alert_skill import evaluate_agentic_alert_skill
 from gooddata_eval.core.agentic.anomaly_detection import evaluate_agentic_anomaly_detection
 from gooddata_eval.core.agentic.conversation import ConversationFixture, evaluate_agentic_conversation
 from gooddata_eval.core.agentic.dashboard_skill import evaluate_agentic_dashboard_skill
+from gooddata_eval.core.agentic.dashboard_summary import evaluate_agentic_dashboard_summary
 from gooddata_eval.core.agentic.document_skill import evaluate_agentic_document_skill
+from gooddata_eval.core.agentic.forecasting import evaluate_agentic_forecasting
 from gooddata_eval.core.agentic.general_question import evaluate_agentic_general_question
 from gooddata_eval.core.agentic.guardrail import evaluate_agentic_guardrail
 from gooddata_eval.core.agentic.kda_skill import evaluate_agentic_kda_skill
@@ -56,6 +58,8 @@ AGENTIC_TEST_KINDS = frozenset(
         "agentic_guardrail",
         "agentic_conversation",
         "agentic_kda_skill",
+        "agentic_forecasting",
+        "agentic_dashboard_summary",
         "agentic_anomaly_detection",
         "agentic_what_if",
     }
@@ -303,6 +307,41 @@ def _dispatch_agentic(
             user_context=item.user_context,
             **lf_kw,
         )
+    elif kind == "agentic_forecasting":
+        return evaluate_agentic_forecasting(
+            host=host,
+            token=token,
+            workspace_id=workspace_id,
+            question=item.question,
+            expected_output=eo if isinstance(eo, dict) else {},
+            k=k,
+            gate=gate,
+            agent_id=agent_id,
+            user_context=item.user_context,
+            **lf_kw,
+        )
+    elif kind == "agentic_dashboard_summary":
+        summary_input = item.summary_input
+        if summary_input is None:
+            raise ValueError(f"agentic_dashboard_summary item '{item.id}' is missing required 'summary_input'.")
+        return evaluate_agentic_dashboard_summary(
+            host=host,
+            token=token,
+            workspace_id=workspace_id,
+            dashboard_id=summary_input.dashboard_id,
+            expected_output=eo,
+            # The fixture's own wording is the prompt under test -- a localized fixture is
+            # only meaningful if its own phrasing is what reaches the agent.
+            question=item.question,
+            # Each widget costs an execution, so a fixture asserting on a handful of charts
+            # can name them instead of paying for the whole dashboard. Same field and meaning
+            # the headless /summary endpoint gives it; None summarizes everything.
+            only_visualizations=summary_input.visualizations,
+            k=k,
+            gate=gate,
+            agent_id=agent_id,
+            **lf_kw,
+        )
     elif kind == "agentic_what_if":
         return evaluate_agentic_what_if(
             host=host,
@@ -404,6 +443,18 @@ def _apply_timings(item_report: ItemReport, timings: Any) -> None:
     item_report.simulated_user_latency_s = timings.simulated_user_s
 
 
+def _apply_best_run_latency(item_report: ItemReport, source: Any) -> None:
+    """Copy the rank-selected run's own wall time, mirroring the single-shot path's
+    ``ItemReport.best_run_latency_s`` (see ``core/runner.py``'s ``_run_one_item``).
+
+    Kinds not yet wired to measure it pass None and keep the field at its own None
+    default rather than reporting an invented number.
+    """
+    best_run_latency_s = getattr(source, "best_run_latency_s", None)
+    if best_run_latency_s is not None:
+        item_report.best_run_latency_s = best_run_latency_s
+
+
 def run_agentic_items(
     items: list[DatasetItem],
     host: str,
@@ -501,6 +552,7 @@ def run_agentic_items(
             item_report.response_id = response_id
             item_report.best_detail = detail or {}
             _apply_timings(item_report, getattr(outcome, "timings", None))
+            _apply_best_run_latency(item_report, outcome)
             _apply_run_counts(item_report, outcome)
             _apply_failed_runs(item_report, outcome)
             _apply_run_latencies(item_report, outcome)
@@ -512,6 +564,7 @@ def run_agentic_items(
             item_report.response_id = getattr(exc, "response_id", None)
             item_report.best_detail = getattr(exc, "detail", None) or {}
             _apply_timings(item_report, getattr(exc, "timings", None))
+            _apply_best_run_latency(item_report, exc)
             _apply_run_counts(item_report, exc)
             _apply_failed_runs(item_report, exc)
             _apply_run_latencies(item_report, exc)
@@ -555,6 +608,7 @@ def run_agentic_items(
             # runs and then raised would otherwise show up in the per-response table and not in
             # the per-conversation one.
             traces.discard()
+            _apply_best_run_latency(item_report, exc)
         finally:
             item_report.latency_s = time.perf_counter() - t0
             item_report.trace_latencies_s = traces.stop()

gooddata_eval-1.80.0/src/gooddata_eval/core/agentic/_editor_takeaways.py

@@ -0,0 +1,274 @@
+# (C) 2026 GoodData Corporation. All rights reserved.
+"""The takeaway request the Publisher editor sends for an unwritten takeaway of a v2 document.
+
+Every visualization on the page, in layout order, each under the filters it is drawn with, a
+visualization drawn twice the same way sent once; ``filterContext`` empty; the takeaway's and the
+document's instructions. A visualization is drawn with the period on its own date dataset unless it
+ignores the period, a document date filter on that dataset with both ends set in the period's place
+(keeping its ``emptyValueHandling`` and, for a relative one, its ``boundedFilter``),
+and every document attribute and text filter that narrows the data. An attribute filter excluding
+nothing and a text filter with no value narrow nothing and are left out; measure value filters
+and any other kind are left out too, since the renderer draws no chart differently for them. Widget
+and page filters, and ``ignoreDocumentFilters``, are stored but not applied, so they are not applied
+here either.
+
+Two parts of the editor's request are left out: ``maxCharacters``, which the editor derives from the
+layout geometry and the theme, so the endpoint's default length applies; and resolving text variables
+in the instructions, which are sent as written, as the editor does while it has no values for them.
+
+Mirrors gdc-ui at commit 7e0f3719ca2 (``documentTakeawayRequest`` and ``copilotTakeaways`` of the
+publisher's v2 editor); check them again when the editor's request changes.
+
+Pure: no network.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from gooddata_eval.core.models import TakeawayInput, TakeawayInstructions, TakeawayVisualization
+
+# Publisher periods and dashboard date filters name granularities as GDC.time.*; AFM date filters
+# take the platform enum.
+_AFM_GRANULARITY = {
+    "GDC.time.year": "YEAR",
+    "GDC.time.quarter": "QUARTER",
+    "GDC.time.month": "MONTH",
+    "GDC.time.week_us": "WEEK",
+    "GDC.time.week": "WEEK",
+    "GDC.time.date": "DAY",
+    "GDC.time.hour": "HOUR",
+    "GDC.time.minute": "MINUTE",
+    "GDC.time.second": "SECOND",
+    "GDC.time.quarter_in_year": "QUARTER_OF_YEAR",
+    "GDC.time.month_in_year": "MONTH_OF_YEAR",
+    "GDC.time.week_in_year": "WEEK_OF_YEAR",
+    "GDC.time.day_in_year": "DAY_OF_YEAR",
+    "GDC.time.day_in_month": "DAY_OF_MONTH",
+    "GDC.time.day_in_week": "DAY_OF_WEEK",
+    "GDC.time.hour_in_day": "HOUR_OF_DAY",
+    "GDC.time.minute_in_hour": "MINUTE_OF_HOUR",
+    "GDC.time.minute_in_day": "MINUTE_OF_DAY",
+    "GDC.time.second_in_day": "SECOND_OF_DAY",
+    "GDC.time.second_in_minute": "SECOND_OF_MINUTE",
+    "GDC.time.fiscal_month": "FISCAL_MONTH",
+    "GDC.time.fiscal_quarter": "FISCAL_QUARTER",
+    "GDC.time.fiscal_year": "FISCAL_YEAR",
+}
+
+
+class _Unbuildable(Exception):
+    """The editor's request has a part this module cannot reproduce."""
+
+
+def _identifier(reference: Any) -> str | None:
+    """The id of a reference written as ``{"identifier": "..."}``, ``{"identifier": {"id": ...}}`` or a bare string."""
+    if isinstance(reference, dict):
+        reference = reference.get("identifier")
+        if isinstance(reference, dict):
+            reference = reference.get("id")
+    return reference if isinstance(reference, str) else None
+
+
+def _date_filter(
+    dataset: str, kind: Any, granularity: Any, start: Any, end: Any, options: dict[str, Any] | None = None
+) -> dict:
+    """The AFM date filter; ``options`` are the document filter's ``emptyValueHandling`` and ``boundedFilter``."""
+    dataset_ref = {"identifier": {"id": dataset, "type": "dataset"}}
+    options = options or {}
+    if kind == "absolute":
+        return {
+            "absoluteDateFilter": {
+                "dataset": dataset_ref,
+                "from": start,
+                "to": end,
+                **{key: value for key, value in options.items() if key == "emptyValueHandling"},
+            }
+        }
+    if kind == "relative":
+        afm_granularity = _AFM_GRANULARITY.get(granularity) if isinstance(granularity, str) else None
+        if afm_granularity is None:
+            raise _Unbuildable(f"relative date granularity {granularity!r} has no AFM form")
+        return {
+            "relativeDateFilter": {
+                "dataset": dataset_ref,
+                "granularity": afm_granularity,
+                "from": start,
+                "to": end,
+                **options,
+            }
+        }
+    raise _Unbuildable(f"date filter type {kind!r} has no AFM form")
+
+
+def _narrows_the_date(date_filter: dict) -> bool:
+    return date_filter.get("from") is not None and date_filter.get("to") is not None
+
+
+def _date_filters(widget: dict, period: Any, filters: list[Any]) -> list[dict]:
+    dataset = _identifier(widget.get("dateDataSet"))
+    if dataset is None:
+        return []
+    for item in filters:
+        date_filter = item.get("dateFilter") if isinstance(item, dict) else None
+        if (
+            isinstance(date_filter, dict)
+            and _narrows_the_date(date_filter)
+            and _identifier(date_filter.get("dataSet")) == dataset
+        ):
+            return [
+                _date_filter(
+                    dataset,
+                    date_filter.get("type"),
+                    date_filter.get("granularity"),
+                    date_filter.get("from"),
+                    date_filter.get("to"),
+                    {
+                        key: date_filter[key]
+                        for key in ("emptyValueHandling", "boundedFilter")
+                        if date_filter.get(key) is not None
+                    },
+                )
+            ]
+    if not isinstance(period, dict) or widget.get("ignoreDocumentPeriod") is True:
+        return []
+    return [_date_filter(dataset, period.get("type"), period.get("granularity"), period.get("from"), period.get("to"))]
+
+
+_MATCH_TYPES = {"contains": "CONTAINS", "startsWith": "STARTS_WITH", "endsWith": "ENDS_WITH"}
+
+
+def _label_ref(body: dict) -> dict:
+    label = _identifier(body.get("displayForm"))
+    if label is None:
+        raise _Unbuildable(f"filter {body!r} names no label, so it has no AFM form")
+    return {"identifier": {"id": label, "type": "label"}}
+
+
+def _element_filter(label_ref: dict, values: list[Any], negative: bool) -> dict | None:
+    """Selected elements as AFM; None for an exclusion of nothing, which keeps every row."""
+    if negative:
+        return {"negativeAttributeFilter": {"label": label_ref, "notIn": {"values": values}}} if values else None
+    return {"positiveAttributeFilter": {"label": label_ref, "in": {"values": values}}}
+
+
+def _attribute_filter(body: dict) -> dict | None:
+    elements = body.get("attributeElements")
+    elements = elements if isinstance(elements, dict) else {}
+    values = elements.get("uris") or elements.get("values") or []
+    if not isinstance(values, list):
+        raise _Unbuildable(f"attribute filter {body!r} has no element list, so it has no AFM form")
+    negative = body.get("negativeSelection") is True
+    if not values and not negative:
+        raise _Unbuildable(f"attribute filter {body!r} selects no element, which has no AFM form")
+    return _element_filter(_label_ref(body), values, negative)
+
+
+def _arbitrary_attribute_filter(body: dict) -> dict | None:
+    values = body.get("values")
+    if not isinstance(values, list):
+        raise _Unbuildable(f"text filter {body!r} has no value list, so it has no AFM form")
+    negative = body.get("negativeSelection") is True
+    # Tiger drops a text filter without values, so the editor's request carries none.
+    return _element_filter(_label_ref(body), values, negative) if values else None
+
+
+def _match_attribute_filter(body: dict) -> dict:
+    operator = body.get("operator")
+    match_type = _MATCH_TYPES.get(operator) if isinstance(operator, str) else None
+    literal = body.get("literal")
+    if match_type is None or not isinstance(literal, str):
+        raise _Unbuildable(f"text filter {body!r} has no AFM form")
+    return {
+        "matchAttributeFilter": {
+            "label": _label_ref(body),
+            "literal": literal,
+            "matchType": match_type,
+            "caseSensitive": body.get("caseSensitive") is True,
+            "negate": body.get("negativeSelection") is True,
+        }
+    }
+
+
+_ATTRIBUTE_KINDS = {
+    "attributeFilter": _attribute_filter,
+    "arbitraryAttributeFilter": _arbitrary_attribute_filter,
+    "matchAttributeFilter": _match_attribute_filter,
+}
+
+
+def _attribute_filters(filters: list[Any]) -> list[dict]:
+    """The AFM form of every document filter other than a date filter that narrows the data."""
+    afm: list[dict] = []
+    for item in filters:
+        if not isinstance(item, dict):
+            raise _Unbuildable(f"document filter {item!r} is not an object")
+        kind = next((kind for kind in _ATTRIBUTE_KINDS if kind in item), None)
+        if kind is None:
+            continue
+        body = item[kind]
+        if not isinstance(body, dict):
+            raise _Unbuildable(f"document filter {item!r} has no AFM form")
+        converted = _ATTRIBUTE_KINDS[kind](body)
+        if converted is not None:
+            afm.append(converted)
+    return afm
+
+
+def _visualization_widgets(node: Any) -> list[dict]:
+    """Every visualization widget with a visualization under ``node``, in layout order."""
+    if not isinstance(node, dict):
+        return []
+    children = node.get("children")
+    if isinstance(children, list):
+        return [widget for child in children for widget in _visualization_widgets(child)]
+    if node.get("type") == "visualization" and _identifier(node.get("visualization")) is not None:
+        return [node]
+    return []
+
+
+def _instruction(text: Any) -> str | None:
+    written = text.strip() if isinstance(text, str) else ""
+    return written or None
+
+
+def _generation_instructions(holder: Any) -> Any:
+    generation = holder.get("generation") if isinstance(holder, dict) else None
+    return generation.get("instructions") if isinstance(generation, dict) else None
+
+
+def editor_takeaway_input(document: dict, page: dict, takeaway: dict) -> TakeawayInput | str:
+    """The request the editor sends to write ``takeaway`` on ``page``, or why it cannot be built.
+
+    ``document`` is a v2 document in its declarative form, the one the editor reads, with its content
+    keys under ``content`` or at the top level.
+    """
+    content = document.get("content")
+    content = content if isinstance(content, dict) else document
+    filters = content.get("filters") or []
+    if not isinstance(filters, list):
+        return f"document filters {filters!r} are not a list"
+    try:
+        attribute_filters = _attribute_filters(filters)
+        placements: dict[str, TakeawayVisualization] = {}
+        for widget in _visualization_widgets(page.get("layout")):
+            placement = TakeawayVisualization(
+                visualization_id=_identifier(widget.get("visualization")) or "",
+                filters=[*_date_filters(widget, document.get("period"), filters), *attribute_filters],
+            )
+            placements.setdefault(json.dumps(placement.model_dump(), sort_keys=True), placement)
+    except _Unbuildable as exc:
+        return str(exc)
+    if not placements:
+        return f"page {page.get('id')!r} has no visualization to summarize"
+    defaults = content.get("defaults")
+    takeaway_defaults = defaults.get("takeaway") if isinstance(defaults, dict) else None
+    return TakeawayInput(
+        visualizations=list(placements.values()),
+        filter_context=[],
+        instructions=TakeawayInstructions(
+            slot=_instruction(_generation_instructions(takeaway)),
+            document=_instruction(_generation_instructions(takeaway_defaults)),
+        ),
+    )

gooddata_eval-1.80.0/src/gooddata_eval/core/agentic/_outcome.py

@@ -0,0 +1,123 @@
+# (C) 2026 GoodData Corporation
+"""The common tail of every ``evaluate_agentic_*`` function.
+
+Before this module, each of the agentic evaluators hand-wrote the same block: copy
+``reasoning_steps``/``conversation_id``/``response_id``/``detail``/``runs_passed``/
+``runs_effective``/``best_run_latency_s`` (and sometimes ``timings``) either onto a
+raised exception or into the returned ``AgenticEvalOutcome``. Eleven independent copies
+of the same ~7 lines meant a new universal field needed eleven edits, not one, and
+nothing failed loudly when a copy was missed -- exactly what happened to ``timings``
+(see ``AgenticAssertionError``'s docstring: "while it lived in eight copies, two
+declared timings and six did not") and again to ``best_run_latency_s`` (every agentic
+kind silently reported it as ``null`` until this was noticed and fixed kind-by-kind).
+
+``agentic_detail`` has the same motivation for the ``detail`` dict's timeline fields:
+``timeline_detail`` builds both ``latency_breakdown`` and ``tool_calls`` from the same
+events so they stay index-aligned, but roughly half the evaluators called
+``build_latency_breakdown`` directly and silently never got a ``tool_calls`` key.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+from gooddata_eval.core.models import (
+    AgenticAssertionError,
+    AgenticEvalOutcome,
+    ReasoningStepEvent,
+    ToolCallEvent,
+    timeline_detail,
+)
+from gooddata_eval.core.timing import PhaseTimings
+
+__all__ = ["agentic_detail", "agentic_success", "raise_agentic_failure"]
+
+
+def agentic_detail(
+    tool_call_events: list[ToolCallEvent],
+    reasoning_step_events: list[ReasoningStepEvent] | None,
+    **kind_specific: Any,
+) -> dict:
+    """A kind's full ``detail`` dict: its own fields plus the universal timeline ones.
+
+    ``kind_specific`` comes first in the merge so a kind can never accidentally shadow
+    ``latency_breakdown``/``tool_calls`` with a same-named field of its own.
+    """
+    return {**kind_specific, **timeline_detail(tool_call_events, reasoning_step_events)}
+
+
+def raise_agentic_failure(
+    exception_cls: type[AgenticAssertionError],
+    message: str,
+    *,
+    reasoning_steps: list[str],
+    conversation_id: str,
+    response_id: str | None,
+    detail: dict,
+    runs_passed: int,
+    runs_effective: int,
+    best_run_latency_s: float | None,
+    timings: PhaseTimings | None = None,
+    failed_runs: list[dict] | None = None,
+    run_latencies_s: list[float] | None = None,
+) -> NoReturn:
+    """Build ``exception_cls(message)`` with every common field attached, and raise it.
+
+    ``exception_cls`` must be an ``AgenticAssertionError`` subclass -- that base class is
+    what declares these fields as legal targets (see its docstring). A kind whose own
+    "no verdict at all" branch raises a bare ``JudgeResponseError`` instead (not a subclass)
+    does not go through this helper for that branch.
+
+    ``timings`` stays optional: only the three kinds that track per-run ``PhaseTimings``
+    (general_question, metric_skill, dashboard_skill) pass one -- the rest keep their
+    own ``PhaseTimings()`` zero default, same as before this helper existed. ``failed_runs``
+    and ``run_latencies_s`` are likewise optional: not every kind has built them by the
+    time it raises.
+    """
+    exc = exception_cls(message)
+    exc.reasoning_steps = reasoning_steps
+    exc.conversation_id = conversation_id
+    exc.response_id = response_id
+    exc.detail = detail
+    exc.runs_passed = runs_passed
+    exc.runs_effective = runs_effective
+    exc.best_run_latency_s = best_run_latency_s
+    if timings is not None:
+        exc.timings = timings
+    if failed_runs is not None:
+        exc.failed_runs = failed_runs
+    if run_latencies_s is not None:
+        exc.run_latencies_s = run_latencies_s
+    raise exc
+
+
+def agentic_success(
+    *,
+    reasoning_steps: list[str],
+    conversation_id: str | None,
+    response_id: str | None,
+    detail: dict,
+    runs_passed: int,
+    runs_effective: int,
+    best_run_latency_s: float | None,
+    timings: PhaseTimings | None = None,
+    failed_runs: list[dict] | None = None,
+    run_latencies_s: list[float] | None = None,
+) -> AgenticEvalOutcome:
+    """The success-path mirror of ``raise_agentic_failure`` -- same fields, same shape."""
+    kwargs: dict[str, Any] = {
+        "reasoning_steps": reasoning_steps,
+        "conversation_id": conversation_id,
+        "response_id": response_id,
+        "detail": detail,
+        "runs_passed": runs_passed,
+        "runs_effective": runs_effective,
+        "best_run_latency_s": best_run_latency_s,
+    }
+    if timings is not None:
+        kwargs["timings"] = timings
+    if failed_runs is not None:
+        kwargs["failed_runs"] = failed_runs
+    if run_latencies_s is not None:
+        kwargs["run_latencies_s"] = run_latencies_s
+    return AgenticEvalOutcome(**kwargs)