From 5b4450007d11beb809fdadae070b83e18e07a336 Mon Sep 17 00:00:00 2001 From: Bahareh Darbandi Date: Thu, 19 Nov 2026 14:39:46 +0100 Subject: [PATCH] feat: mark_run_skipped, the intentional-skip marker on an agent run rius.mark_run_skipped(reason) and Observation.mark_skipped(reason) set rius.run.skipped_reason on a recording AGENT span, so Rius's empty-run detection reports a run that had nothing to do on purpose as informational instead of a warning. The reason is whitespace-collapsed and cut to 200 characters; it is metadata, so it survives capture_content=False. Any other span is left unmarked and the call returns False. --- README.md | 25 +++++++++ src/rius/__init__.py | 2 + src/rius/run.py | 92 ++++++++++++++++++++++++++++++++ src/rius/spans.py | 9 ++++ tests/test_run_skipped.py | 108 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 236 insertions(+) create mode 100644 src/rius/run.py create mode 100644 tests/test_run_skipped.py diff --git a/README.md b/README.md index 3e994e7..904c534 100644 --- a/README.md +++ b/README.md @@ -377,6 +377,31 @@ that started it; it reaches only copies of the context made after the call. The summary is content: its size in bytes is always sent, and its text follows `capture_content` and `mask` like a prompt does. +## Intentional skips + +A run that finishes without calling a model or a tool looks, to Rius, like a +run whose work went missing, and Rius's empty-run detection flags it when the +agent usually does work. When the run had nothing to do on purpose, say so on +its agent span: + +```python +@rius.observe(kind=rius.SpanKind.AGENT) +def triage() -> None: + tickets = load_new_tickets() + if not tickets: + rius.mark_run_skipped("no new tickets") + return + ... +``` + +The run is then an informational finding that alerts nobody, and it stays out +of the agent's baseline. `Observation.mark_skipped(reason)` marks a span you +hold instead of the current one. The marker belongs on the run's outermost +agent span; on any other span it returns `False` and sets nothing. The reason +is shown to people as quoted text: keep it short and operational. It is +metadata, so it is sent even with `capture_content=False`; never put user +input or secrets in it. An empty reason raises `ValueError`. + ## Reliability Export is designed to never block or crash your application: diff --git a/src/rius/__init__.py b/src/rius/__init__.py index ea26a30..527f5f8 100644 --- a/src/rius/__init__.py +++ b/src/rius/__init__.py @@ -8,6 +8,7 @@ from .export_health import ProbeTransport from .generation import Generation, start_as_current_generation, start_generation from .observe import observe +from .run import mark_run_skipped from .semconv import SpanKind from .session import session from .spans import Observation, start_as_current_span, start_span @@ -26,6 +27,7 @@ "get_tracer", "init", "mark_compaction", + "mark_run_skipped", "observe", "register_workspace", "resolve_config", diff --git a/src/rius/run.py b/src/rius/run.py new file mode 100644 index 0000000..28bee78 --- /dev/null +++ b/src/rius/run.py @@ -0,0 +1,92 @@ +"""Intentional skips: saying a run had nothing to do, on purpose. + +A run that finished without calling a model or a tool looks the same to the +backend whether it meant to (an empty queue, a guard that decided no work was +needed) or its work went missing. Rius's empty-run detection (CF-05) flags the +second; :func:`mark_run_skipped` tells it about the first, so the run is an +informational finding instead of a warning and stays out of the agent's +baseline. +""" + +from __future__ import annotations + +import logging + +from opentelemetry import trace +from opentelemetry.trace import Span + +from .semconv import OPENINFERENCE_SPAN_KIND, SpanKind + +logger = logging.getLogger(__name__) + +#: The agent-root attribute that marks an intentional skip. Planned in the +#: rius-semconv registry (``RIUS_RUN_SKIPPED_REASON``); it moves to the +#: generated constants once a registry release ships the row. +RUN_SKIPPED_REASON = "rius.run.skipped_reason" + +#: The longest reason sent. The backend cuts what it shows to 200 characters +#: too, and strips control characters. +MAX_SKIPPED_REASON_CHARS = 200 + + +def _clean(reason: str) -> str: + if not isinstance(reason, str): + raise TypeError(f"reason must be a str, got {type(reason).__name__}") + cleaned = " ".join(reason.split()) + if not cleaned: + raise ValueError("reason must not be empty: an empty reason is no skip marker") + return cleaned[:MAX_SKIPPED_REASON_CHARS] + + +def mark_skipped(span: Span, reason: str) -> bool: + """Mark ``span``, an agent span, as a run skipped on purpose. + + Returns True when the attribute was set, False (with a debug log) when the + span is not recording or is not an AGENT span: the marker means something + only on the run's agent root, and setting it elsewhere would be silently + ignored. Raises ``ValueError`` for an empty or whitespace-only reason and + ``TypeError`` for a reason that is not a string. + """ + cleaned = _clean(reason) + if not span.is_recording(): + logger.debug("mark_run_skipped: the span is not recording; nothing marked") + return False + attributes = getattr(span, "attributes", None) or {} + if attributes.get(OPENINFERENCE_SPAN_KIND) != SpanKind.AGENT.value: + logger.debug("mark_run_skipped: the span is not an AGENT span; nothing marked") + return False + span.set_attribute(RUN_SKIPPED_REASON, cleaned) + return True + + +def mark_run_skipped(reason: str) -> bool: + """Mark the current agent run as intentionally skipped, with a short reason. + + Call it inside the run's agent span, before it ends: in a function + decorated ``@observe(kind=SpanKind.AGENT)`` or in + ``start_as_current_span(..., kind=SpanKind.AGENT)``, when the run decides + it has nothing to do:: + + @rius.observe(kind=rius.SpanKind.AGENT) + def triage() -> None: + tickets = fetch_new_tickets_from_cache() + if not tickets: + rius.mark_run_skipped("no new tickets") + return + ... + + The backend reads the marker on the run's root agent span only: mark the + outermost agent of the trace. A marked run that still calls a model or a + tool is judged on that work, not on the marker. + + ``reason`` is shown to people as quoted text: keep it short and + operational ("no new tickets", "input already processed"). Whitespace is + collapsed and it is cut to 200 characters. It is metadata, not content, so + it is sent even with ``capture_content=False`` and is not masked: never put + user input, message text or secrets in it. + + Returns True when the current span was marked, False (with a debug log) + when the current span is not a recording AGENT span. Raises ``ValueError`` + for an empty reason. + """ + return mark_skipped(trace.get_current_span(), reason) diff --git a/src/rius/spans.py b/src/rius/spans.py index 3fe4af2..41c5ebb 100644 --- a/src/rius/spans.py +++ b/src/rius/spans.py @@ -32,6 +32,7 @@ from ._errors import record_error from ._serde import attribute_value, serialize, text_value from ._tracer import sdk_tracer +from .run import mark_skipped from .semconv import ( GEN_AI_RETRIEVAL_DOCUMENTS, INPUT_VALUE, @@ -128,6 +129,14 @@ class Observation: def __init__(self, span: Span) -> None: self._span = span + def mark_skipped(self, reason: str) -> bool: + """Mark this agent span's run as skipped on purpose, with a short reason. + + See :func:`rius.mark_run_skipped`; this marks this span instead of the + current one. Returns False when the span is not a recording AGENT span. + """ + return mark_skipped(self._span, reason) + def set_input(self, value: Any) -> None: """Record the span input (the ``input.value`` attribute). diff --git a/tests/test_run_skipped.py b/tests/test_run_skipped.py new file mode 100644 index 0000000..217feb2 --- /dev/null +++ b/tests/test_run_skipped.py @@ -0,0 +1,108 @@ +"""``mark_run_skipped``: a run that had nothing to do says so on its agent span. + +The empty-run detector (CF-05) reads ``rius.run.skipped_reason`` on the run's +root agent span; a marked run is an info finding, never a warning. +""" + +from __future__ import annotations + +from collections.abc import Iterator +from typing import Any + +import pytest +from opentelemetry.sdk.trace import ReadableSpan, TracerProvider +from opentelemetry.sdk.trace.export import SimpleSpanProcessor +from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter + +import rius +from rius import _tracer +from rius.masking import MaskingSpanExporter +from rius.run import MAX_SKIPPED_REASON_CHARS, RUN_SKIPPED_REASON +from rius.semconv import SpanKind + + +class _Pipeline: + def __init__(self, *, capture_content: bool = True) -> None: + self.exporter = InMemorySpanExporter() + sink: Any = self.exporter + if not capture_content: + sink = MaskingSpanExporter(sink, capture_content=False) + self.provider = TracerProvider() + self.provider.add_span_processor(SimpleSpanProcessor(sink)) + _tracer.publish(self.provider) + + def named(self, name: str) -> ReadableSpan: + (span,) = [s for s in self.exporter.get_finished_spans() if s.name == name] + return span + + +@pytest.fixture +def pipeline() -> Iterator[_Pipeline]: + yield _Pipeline() + + +def _reason(span: ReadableSpan) -> Any: + return dict(span.attributes or {}).get(RUN_SKIPPED_REASON) + + +def test_marks_the_current_agent_span(pipeline: _Pipeline) -> None: + with rius.start_as_current_span("triage", kind=SpanKind.AGENT): + assert rius.mark_run_skipped("no new tickets") is True + assert _reason(pipeline.named("triage")) == "no new tickets" + + +def test_marks_an_observed_agent(pipeline: _Pipeline) -> None: + @rius.observe(name="nightly", kind=SpanKind.AGENT) + def nightly() -> None: + rius.mark_run_skipped(" input already\nprocessed ") + + nightly() + assert _reason(pipeline.named("nightly")) == "input already processed" + + +def test_observation_marks_its_own_span(pipeline: _Pipeline) -> None: + with ( + rius.start_as_current_span("run", kind=SpanKind.AGENT) as run, + rius.start_as_current_span("step"), + ): + assert run.mark_skipped("guard said no") is True + assert _reason(pipeline.named("run")) == "guard said no" + assert _reason(pipeline.named("step")) is None + + +def test_a_non_agent_span_is_not_marked(pipeline: _Pipeline) -> None: + with rius.start_as_current_span("step"): + assert rius.mark_run_skipped("nothing to do") is False + assert _reason(pipeline.named("step")) is None + + +def test_no_span_is_not_an_error(pipeline: _Pipeline) -> None: + assert rius.mark_run_skipped("nothing to do") is False + + +@pytest.mark.parametrize("reason", ["", " ", "\n\t"]) +def test_an_empty_reason_is_refused(pipeline: _Pipeline, reason: str) -> None: + with ( + rius.start_as_current_span("run", kind=SpanKind.AGENT), + pytest.raises(ValueError, match="must not be empty"), + ): + rius.mark_run_skipped(reason) + assert _reason(pipeline.named("run")) is None + + +def test_a_non_string_reason_is_refused(pipeline: _Pipeline) -> None: + with rius.start_as_current_span("run", kind=SpanKind.AGENT), pytest.raises(TypeError): + rius.mark_run_skipped(None) # type: ignore[arg-type] + + +def test_an_oversized_reason_is_cut(pipeline: _Pipeline) -> None: + with rius.start_as_current_span("run", kind=SpanKind.AGENT): + rius.mark_run_skipped("x" * 5000) + assert _reason(pipeline.named("run")) == "x" * MAX_SKIPPED_REASON_CHARS + + +def test_the_marker_survives_content_masking() -> None: + pipeline = _Pipeline(capture_content=False) + with rius.start_as_current_span("run", kind=SpanKind.AGENT): + rius.mark_run_skipped("no new tickets") + assert _reason(pipeline.named("run")) == "no new tickets"