Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
25 changes: 25 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 2 additions & 0 deletions src/rius/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -26,6 +27,7 @@
"get_tracer",
"init",
"mark_compaction",
"mark_run_skipped",
"observe",
"register_workspace",
"resolve_config",
Expand Down
92 changes: 92 additions & 0 deletions src/rius/run.py
Original file line number Diff line number Diff line change
@@ -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)
9 changes: 9 additions & 0 deletions src/rius/spans.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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).

Expand Down
108 changes: 108 additions & 0 deletions tests/test_run_skipped.py
Original file line number Diff line number Diff line change
@@ -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"
Loading