feat(conversations)!: filter items with contains and drop operation_name

.jscpd.json

@@ -14,6 +14,6 @@
   "mode": "weak",
   "kind": ["exact", "renamed"],
   "ignoreIdentifiers": true,
-  "threshold": 16.3,
+  "threshold": 16.31,
   "reporters": ["console"]
 }

examples/introspection_examples/reference/python_sdk.py

@@ -90,7 +90,9 @@ async def conversations_events_metrics(runner: AsyncRunner, task_id: str) -> Non
         print(c.id, c.cost.usd)
 
     # Tool calls only, e.g. a submit_result tool's arguments (a JSON string)
-    async for item in runner.conversations.items.list(task_id, operation_name="execute_tool"):
+    async for item in runner.conversations.items.list(
+        task_id, contains=["gen_ai.operation.name:execute_tool"]
+    ):
         tool = item.attributes.gen_ai.tool if item.attributes.gen_ai else None
         if tool and tool.call:
             print(tool.name, tool.call.arguments)

introspection_sdk/_async/protocols.py

@@ -249,7 +249,7 @@
 class AsyncConversationItemsResource(Protocol):
     """Protocol of :class:`~introspection_sdk.runner_resources.conversations.AsyncConversationItems`."""
 
     def list(
         self,
         conversation_id: str,
         *,
@@ -258,7 +258,7 @@
         include: builtins.list[ConversationItemInclude] | None = None,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        contains: builtins.list[str] | None = None,
         start_date: str | None = None,
         end_date: str | None = None,
         lookback_days: int | None = None,
@@ -366,7 +366,7 @@
         *,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        operation_name: str | builtins.list[str] | None = None,
         lookback_days: int | None = None,
         start_date: str | datetime | None = None,
         end_date: str | datetime | None = None,
@@ -378,7 +378,7 @@
         *,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        operation_name: str | builtins.list[str] | None = None,
         lookback_days: int | None = None,
         start_date: str | datetime | None = None,
         end_date: str | datetime | None = None,

introspection_sdk/_async/runner_resources/conversations.py

@@ -66,7 +66,7 @@
     *,
     agent: str | None = None,
     service_name: str | None = None,
-    operation_name: str | None = None,
+    operation_name: str | builtins.list[str] | None = None,
     lookback_days: int | None = None,
     start_date: str | datetime | None = None,
     end_date: str | datetime | None = None,
@@ -259,7 +259,7 @@
     def __init__(self, http: _AsyncHttpClient) -> None:
         self._http = http
 
     def list(
         self,
         conversation_id: str,
         *,
@@ -268,7 +268,7 @@
         include: builtins.list[ConversationItemInclude] | None = None,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        contains: builtins.list[str] | None = None,
         start_date: str | None = None,
         end_date: str | None = None,
         lookback_days: int | None = None,
@@ -285,6 +285,32 @@
         Items carry the turn-local delta in ``input_messages`` — only the
         messages new to that turn. Use :meth:`get` for the full input
         history of a span.
+
+        ``contains`` keeps the rows that contain any of the given
+        ``<path>:<value>`` pairs over the GenAI semconv attributes (at most
+        20, sent as the repeated ``contains`` key):
+
+        - ``gen_ai.input.messages.role:user``
+        - ``gen_ai.input.messages.parts.type:tool_call_response``
+        - ``gen_ai.input.messages.parts.name:<tool>``
+        - ``gen_ai.output.messages.parts.type:text``
+        - ``gen_ai.output.messages.parts.type:tool_call``
+        - ``gen_ai.output.messages.parts.name:<tool>``
+        - ``gen_ai.tool.name:<tool>``
+        - ``gen_ai.operation.name:<operation>``
+
+        A value on one of the four name paths may end in a single ``*`` to
+        match by prefix: ``gen_ai.output.messages.parts.name:mcp_browserbase_*``
+        or ``gen_ai.tool.name:mcp_*``, and ``gen_ai.input.messages.parts.name:*``
+        matches any name. The server rejects ``*`` anywhere else, or on a role
+        or part-type value, with a 422
+        (:class:`~introspection_sdk.ValidationError`).
+
+        Input paths are evaluated over the input messages new to the item,
+        not the full history ``include=["gen_ai.input.messages"]`` adds. An
+        item matched only by an input value returns only its new input
+        messages, one matched only by an output value only its output, and
+        one matched by an attribute path the whole item.
         """
         # unasync: end
         """List conversation items using an opaque ``next`` cursor. Iterate
@@ -298,6 +324,32 @@
         Items carry the turn-local delta in ``input_messages`` — only the
         messages new to that turn. Use :meth:`get` for the full input
         history of a span.
+
+        ``contains`` keeps the rows that contain any of the given
+        ``<path>:<value>`` pairs over the GenAI semconv attributes (at most
+        20, sent as the repeated ``contains`` key):
+
+        - ``gen_ai.input.messages.role:user``
+        - ``gen_ai.input.messages.parts.type:tool_call_response``
+        - ``gen_ai.input.messages.parts.name:<tool>``
+        - ``gen_ai.output.messages.parts.type:text``
+        - ``gen_ai.output.messages.parts.type:tool_call``
+        - ``gen_ai.output.messages.parts.name:<tool>``
+        - ``gen_ai.tool.name:<tool>``
+        - ``gen_ai.operation.name:<operation>``
+
+        A value on one of the four name paths may end in a single ``*`` to
+        match by prefix: ``gen_ai.output.messages.parts.name:mcp_browserbase_*``
+        or ``gen_ai.tool.name:mcp_*``, and ``gen_ai.input.messages.parts.name:*``
+        matches any name. The server rejects ``*`` anywhere else, or on a role
+        or part-type value, with a 422
+        (:class:`~introspection_sdk.ValidationError`).
+
+        Input paths are evaluated over the input messages new to the item,
+        not the full history ``include=["gen_ai.input.messages"]`` adds. An
+        item matched only by an input value returns only its new input
+        messages, one matched only by an output value only its output, and
+        one matched by an attribute path the whole item.
         """
 
         async def fetch(cursor: str | None) -> GenAiSpanList:
@@ -307,7 +359,7 @@
                 "include": include,
                 "agent": agent,
                 "service_name": service_name,
-                "operation_name": operation_name,
+                "contains": contains,
                 "start_date": start_date,
                 "end_date": end_date,
                 "lookback_days": lookback_days,
@@ -617,7 +669,7 @@
         *,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        operation_name: str | builtins.list[str] | None = None,
         lookback_days: int | None = None,
         start_date: str | datetime | None = None,
         end_date: str | datetime | None = None,
@@ -655,7 +707,7 @@
         *,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        operation_name: str | builtins.list[str] | None = None,
         lookback_days: int | None = None,
         start_date: str | datetime | None = None,
         end_date: str | datetime | None = None,

introspection_sdk/_sync/protocols.py

@@ -251,7 +251,7 @@
 class ConversationItemsResource(Protocol):
     """Protocol of :class:`~introspection_sdk.runner_resources.conversations.ConversationItems`."""
 
     def list(
         self,
         conversation_id: str,
         *,
@@ -260,7 +260,7 @@
         include: builtins.list[ConversationItemInclude] | None = None,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        contains: builtins.list[str] | None = None,
         start_date: str | None = None,
         end_date: str | None = None,
         lookback_days: int | None = None,
@@ -368,7 +368,7 @@
         *,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        operation_name: str | builtins.list[str] | None = None,
         lookback_days: int | None = None,
         start_date: str | datetime | None = None,
         end_date: str | datetime | None = None,
@@ -380,7 +380,7 @@
         *,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        operation_name: str | builtins.list[str] | None = None,
         lookback_days: int | None = None,
         start_date: str | datetime | None = None,
         end_date: str | datetime | None = None,

introspection_sdk/_sync/runner_resources/conversations.py

@@ -68,7 +68,7 @@
     *,
     agent: str | None = None,
     service_name: str | None = None,
-    operation_name: str | None = None,
+    operation_name: str | builtins.list[str] | None = None,
     lookback_days: int | None = None,
     start_date: str | datetime | None = None,
     end_date: str | datetime | None = None,
@@ -253,7 +253,7 @@
     def __init__(self, http: _HttpClient) -> None:
         self._http = http
 
     def list(
         self,
         conversation_id: str,
         *,
@@ -262,7 +262,7 @@
         include: builtins.list[ConversationItemInclude] | None = None,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        contains: builtins.list[str] | None = None,
         start_date: str | None = None,
         end_date: str | None = None,
         lookback_days: int | None = None,
@@ -278,6 +278,32 @@
         Items carry the turn-local delta in ``input_messages`` — only the
         messages new to that turn. Use :meth:`get` for the full input
         history of a span.
+
+        ``contains`` keeps the rows that contain any of the given
+        ``<path>:<value>`` pairs over the GenAI semconv attributes (at most
+        20, sent as the repeated ``contains`` key):
+
+        - ``gen_ai.input.messages.role:user``
+        - ``gen_ai.input.messages.parts.type:tool_call_response``
+        - ``gen_ai.input.messages.parts.name:<tool>``
+        - ``gen_ai.output.messages.parts.type:text``
+        - ``gen_ai.output.messages.parts.type:tool_call``
+        - ``gen_ai.output.messages.parts.name:<tool>``
+        - ``gen_ai.tool.name:<tool>``
+        - ``gen_ai.operation.name:<operation>``
+
+        A value on one of the four name paths may end in a single ``*`` to
+        match by prefix: ``gen_ai.output.messages.parts.name:mcp_browserbase_*``
+        or ``gen_ai.tool.name:mcp_*``, and ``gen_ai.input.messages.parts.name:*``
+        matches any name. The server rejects ``*`` anywhere else, or on a role
+        or part-type value, with a 422
+        (:class:`~introspection_sdk.ValidationError`).
+
+        Input paths are evaluated over the input messages new to the item,
+        not the full history ``include=["gen_ai.input.messages"]`` adds. An
+        item matched only by an input value returns only its new input
+        messages, one matched only by an output value only its output, and
+        one matched by an attribute path the whole item.
         """
 
         def fetch(cursor: str | None) -> GenAiSpanList:
@@ -287,7 +313,7 @@
                 "include": include,
                 "agent": agent,
                 "service_name": service_name,
-                "operation_name": operation_name,
+                "contains": contains,
                 "start_date": start_date,
                 "end_date": end_date,
                 "lookback_days": lookback_days,
@@ -575,7 +601,7 @@
         *,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        operation_name: str | builtins.list[str] | None = None,
         lookback_days: int | None = None,
         start_date: str | datetime | None = None,
         end_date: str | datetime | None = None,
@@ -613,7 +639,7 @@
         *,
         agent: str | None = None,
         service_name: str | None = None,
-        operation_name: str | None = None,
+        operation_name: str | builtins.list[str] | None = None,
         lookback_days: int | None = None,
         start_date: str | datetime | None = None,
         end_date: str | datetime | None = None,

introspection_sdk/atif.py

@@ -161,10 +161,11 @@ def add(self, span: GenAiSpan) -> list[AtifStep]:
                 )
             )
 
+        introspection = span.attributes.introspection
+        history = introspection.history if introspection else None
         declared = (
-            span.attributes.introspection.conversation.new_messages_start
-            if span.attributes.introspection
-            and span.attributes.introspection.conversation
+            history.new_messages.start
+            if history and history.new_messages
             else None
         )
         for message in self._new_messages(lane, inputs, declared):

introspection_sdk/runner_resources/_conversations_common.py

@@ -11,7 +11,7 @@ class ConversationExportParams(TypedDict, total=False):
 
     agent: str
     service_name: str
-    operation_name: str
+    operation_name: str | list[str]
     lookback_days: int
     start_date: str | datetime
     end_date: str | datetime

introspection_sdk/schemas/__init__.py

@@ -38,8 +38,12 @@
     Conversation,
     ConversationAgent,
     ConversationCost,
+    ConversationExperiment,
     ConversationItemInclude,
     ConversationMetrics,
+    ConversationOwner,
+    ConversationRecipe,
+    ConversationRuntime,
     ConversationSortField,
     ConversationUsage,
 )
@@ -177,8 +181,12 @@
     "Conversation",
     "ConversationAgent",
     "ConversationCost",
+    "ConversationExperiment",
     "ConversationItemInclude",
     "ConversationMetrics",
+    "ConversationOwner",
+    "ConversationRecipe",
+    "ConversationRuntime",
     "ConversationSortField",
     "ConversationUsage",
     "Event",

introspection_sdk/schemas/conversations.py

@@ -1,3 +1,3 @@
 """Conversation resources and query vocabulary for ``/v1/conversations``.
 
 The message-family ``include`` values are gone. The items read returns the
@@ -18,8 +18,12 @@
     "Conversation",
     "ConversationAgent",
     "ConversationCost",
+    "ConversationExperiment",
     "ConversationItemInclude",
     "ConversationMetrics",
+    "ConversationOwner",
+    "ConversationRecipe",
+    "ConversationRuntime",
     "ConversationSortField",
     "ConversationUsage",
     "SpanKind",
@@ -36,7 +40,13 @@
 
 
 class ConversationUsage(OmitNoneModel):
-    input_tokens: int = 0
+    """Token totals across the conversation.
+
+    ``total_input_tokens`` counts uncached input plus cache reads and writes,
+    so it is not the sum of the items' ``gen_ai.usage.input_tokens``.
+    """
+
+    total_input_tokens: int = 0
     output_tokens: int = 0
     total_tokens: int = 0
 
@@ -48,12 +58,30 @@
 class ConversationMetrics(OmitNoneModel):
     duration_ms: float = 0.0
     trace_count: int = 0
+    max_turn: int | None = None
     span_count: int = 0
     tool_use_count: int = 0
     failed_tool_use_count: int = 0
     has_errors: bool = False
 
 
+class ConversationRuntime(OmitNoneModel):
+    id: UUID | None = None
+    group_id: UUID | None = None
+
+
+class ConversationExperiment(OmitNoneModel):
+    id: UUID | None = None
+
+
+class ConversationRecipe(OmitNoneModel):
+    git_commit_sha: str | None = None
+
+
+class ConversationOwner(OmitNoneModel):
+    key: str | None = None
+
+
 class Conversation(OmitNoneModel):
     object: Literal["conversation"] = "conversation"
     id: str
@@ -66,11 +94,10 @@
     metrics: ConversationMetrics = Field(default_factory=ConversationMetrics)
     environment: str | None = None
     service_name: str | None = None
-    runtime_id: UUID | None = None
-    runtime_group_id: UUID | None = None
-    experiment_id: UUID | None = None
-    recipe_git_commit_sha: str | None = None
-    owner_key: str | None = None
+    runtime: ConversationRuntime | None = None
+    experiment: ConversationExperiment | None = None
+    recipe: ConversationRecipe | None = None
+    owner: ConversationOwner | None = None
     metadata: dict[str, str] | None = None