answerrocket-client 0.2.105__tar.gz → 0.2.106__tar.gz

{answerrocket_client-0.2.105 → answerrocket_client-0.2.106}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: answerrocket-client
-Version: 0.2.105
+Version: 0.2.106
 Summary: Python client for interacting with AnswerRocket's skill API
 Requires-Python: >=3.10.7
 Description-Content-Type: text/markdown

{answerrocket_client-0.2.105 → answerrocket_client-0.2.106}/answer_rocket/__init__.py

@@ -5,7 +5,7 @@ __all__ = [
     'MetaDataFrame'
 ]
 
-__version__ = "0.2.105"
+__version__ = "0.2.106"
 
 from answer_rocket.client import AnswerRocketClient
 from answer_rocket.error import AnswerRocketClientError

{answerrocket_client-0.2.105 → answerrocket_client-0.2.106}/answer_rocket/client.py

@@ -10,6 +10,7 @@ from answer_rocket.skill import Skill
 from answer_rocket.llm import Llm
 from answer_rocket.layouts import DynamicLayouts
 from answer_rocket.email import Email
+from answer_rocket.observability import Observability
 
 class AnswerRocketClient:
 	"""
@@ -41,6 +42,7 @@ class AnswerRocketClient:
 		self.llm = Llm(self._client_config, self._gql_client)
 		self.dynamic_layouts = DynamicLayouts(self._client_config, self._gql_client)
 		self.email = Email(self._client_config, self._gql_client)
+		self.observability = Observability(self._client_config, self._gql_client)
 
 	def can_connect(self) -> bool:
 		"""

{answerrocket_client-0.2.105 → answerrocket_client-0.2.106}/answer_rocket/data.py

@@ -2452,33 +2452,9 @@ class Data:
         self, dataset_id: UUID
     ) -> List[TrackedDimensionAttribute]:
         """
-        Get currently-active starred values for the calling user on a dataset,
-        grouped by dimension.
-
-        Parameters
-        ----------
-        dataset_id : UUID
-            Dataset the starred values belong to.
-
-        Returns
-        -------
-        List[TrackedDimensionAttribute]
-            One entry per dimension the caller has stars in. Each entry exposes
-            ``dimension_attribute_id``, ``dimension_name``, and ``values``
-            (currently-active starred values for that dimension).
-
-        Examples
-        --------
-        >>> attrs = max.tracked_values.get_tracked_dimension_values(
-        ...     dataset_id=uuid.UUID("...")
-        ... )
-        >>> for attr in attrs:
-        ...     print(attr.dimension_name, attr.values)
-        """
-        query_args = {"datasetId": str(dataset_id)}
-        op = Operations.query.get_tracked_dimension_values
-        result = self._gql_client.submit(op, query_args)
-        return result.get_tracked_dimension_values
+        DEPRECATED in v0.2.106
+        """
+        raise DeprecationWarning("Deprecated in v0.2.106")
 
     def get_all_tracked_dimension_values(
         self,
@@ -2489,48 +2465,6 @@ class Data:
         sort: Optional[list] = None,
     ) -> TrackedDimensionValuesPage:
         """
-        Get a flat, paginated view of tracked values. Admins see every user's
-        rows; non-admins see only their own.
-
-        Parameters
-        ----------
-        offset : int, default 0
-            Zero-based offset for paging.
-        limit : int, default 100
-            Max rows to return.
-        dataset_id : UUID, optional
-            If provided, scope results to a single dataset.
-        filters : dict, optional
-            AG-Grid filterModel JSON (per-column filters). Keys are column ids
-            (e.g. ``"userName"``, ``"value"``, ``"addedUtc"``); values follow
-            AG-Grid's text/set/date filter shapes.
-        sort : list, optional
-            AG-Grid sortModel JSON (list of ``{"colId": ..., "sort": "asc" |
-            "desc", "sortIndex": ...}`` entries).
-
-        Returns
-        -------
-        TrackedDimensionValuesPage
-            Object with ``total_count`` (count after filters but before paging)
-            and ``rows`` (the requested page of joined user/dataset rows).
-
-        Examples
-        --------
-        >>> page = max.tracked_values.get_all_tracked_dimension_values(
-        ...     dataset_id=uuid.UUID("..."),
-        ...     limit=500,
-        ... )
-        >>> print(page.total_count)
-        >>> for row in page.rows:
-        ...     print(row.user_name, row.dimension_name, row.value)
-        """
-        query_args: dict[str, Any] = {
-            "offset": offset,
-            "limit": limit,
-            "datasetId": str(dataset_id) if dataset_id is not None else None,
-            "filters": filters,
-            "sort": sort,
-        }
-        op = Operations.query.get_all_tracked_dimension_values
-        result = self._gql_client.submit(op, query_args)
-        return result.get_all_tracked_dimension_values
+        DEPRECATED in v0.2.106
+        """
+        raise DeprecationWarning("Deprecated in v0.2.106")

{answerrocket_client-0.2.105 → answerrocket_client-0.2.106}/answer_rocket/graphql/client.py

@@ -34,3 +34,4 @@ class GraphQlClient:
         if variables:
             return Operation(Mutation, variables=variables)
         return Operation(Mutation)
+

{answerrocket_client-0.2.105 → answerrocket_client-0.2.106}/answer_rocket/graphql/schema.py

@@ -335,6 +335,22 @@ class MaxDomainEntity(sgqlc.types.Interface):
     attributes = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null(MaxDomainAttribute))), graphql_name='attributes')
 
 
+class AnyValue(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('string_value', 'bool_value', 'int_value', 'double_value', 'array_value')
+    string_value = sgqlc.types.Field(String, graphql_name='stringValue')
+    bool_value = sgqlc.types.Field(Boolean, graphql_name='boolValue')
+    int_value = sgqlc.types.Field(String, graphql_name='intValue')
+    double_value = sgqlc.types.Field(Float, graphql_name='doubleValue')
+    array_value = sgqlc.types.Field('ArrayValue', graphql_name='arrayValue')
+
+
+class ArrayValue(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('values',)
+    values = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null(AnyValue))), graphql_name='values')
+
+
 class AsyncSkillRunResponse(sgqlc.types.Type):
     __schema__ = schema
     __field_names__ = ('execution_id', 'success', 'code', 'error')
@@ -763,6 +779,20 @@ class HydratedReport(sgqlc.types.Type):
     meta = sgqlc.types.Field(JSON, graphql_name='meta')
 
 
+class InstrumentationScope(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('name', 'version')
+    name = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='name')
+    version = sgqlc.types.Field(String, graphql_name='version')
+
+
+class KeyValue(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('key', 'value')
+    key = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='key')
+    value = sgqlc.types.Field(sgqlc.types.non_null(AnyValue), graphql_name='value')
+
+
 class LayoutPdfResponse(sgqlc.types.Type):
     __schema__ = schema
     __field_names__ = ('success', 'code', 'error', 'pdf')
@@ -1636,6 +1666,27 @@ class Mutation(sgqlc.types.Type):
     )
 
 
+class ObservabilityTrace(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('resource_spans',)
+    resource_spans = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null('ResourceSpans'))), graphql_name='resourceSpans')
+
+
+class ObservabilityTracesResult(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('count', 'has_more', 'next_cursor', 'traces')
+    count = sgqlc.types.Field(sgqlc.types.non_null(Int), graphql_name='count')
+    has_more = sgqlc.types.Field(sgqlc.types.non_null(Boolean), graphql_name='hasMore')
+    next_cursor = sgqlc.types.Field(String, graphql_name='nextCursor')
+    traces = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null(ObservabilityTrace))), graphql_name='traces')
+
+
+class OtlpResource(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('attributes',)
+    attributes = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null(KeyValue))), graphql_name='attributes')
+
+
 class PagedChatArtifacts(sgqlc.types.Type):
     __schema__ = schema
     __field_names__ = ('total_rows', 'rows')
@@ -1696,7 +1747,7 @@ class ParameterDefinition(sgqlc.types.Type):
 
 class Query(sgqlc.types.Type):
     __schema__ = schema
-    __field_names__ = ('ping', 'current_user', 'get_copilot_skill_artifact_by_path', 'get_copilots', 'get_copilot_info', 'get_copilot_skill', 'run_copilot_skill', 'get_skill_components', 'get_copilot_hydrated_reports', 'get_async_skill_run_status', 'get_copilot_test_run', 'get_paged_copilot_test_runs', 'get_copilot_question_folders', 'get_max_agent_workflow', 'execute_sql_query', 'execute_rql_query', 'get_databases', 'get_database', 'get_database_tables', 'get_dataset_id', 'get_dataset', 'get_dataset2', 'get_datasets', 'get_domain_object', 'get_domain_object_by_name', 'get_grounded_value', 'get_database_kshots', 'get_database_kshot_by_id', 'get_dataset_kshots', 'get_dataset_kshot_by_id', 'run_max_sql_gen', 'run_sql_ai', 'generate_visualization', 'llmapi_config_for_sdk', 'generate_embeddings', 'get_max_llm_prompt', 'user_chat_threads', 'user_chat_entries', 'chat_thread', 'chat_entry', 'user', 'all_chat_entries', 'skill_memory', 'chat_completion', 'narrative_completion', 'narrative_completion_with_prompt', 'sql_completion', 'research_completion', 'chat_completion_with_prompt', 'research_completion_with_prompt', 'get_chat_artifact', 'get_chat_artifacts', 'get_dynamic_layout', 'get_tracked_dimension_values', 'get_all_tracked_dimension_values')
+    __field_names__ = ('ping', 'current_user', 'get_copilot_skill_artifact_by_path', 'get_copilots', 'get_copilot_info', 'get_copilot_skill', 'run_copilot_skill', 'get_skill_components', 'get_copilot_hydrated_reports', 'get_async_skill_run_status', 'get_copilot_test_run', 'get_paged_copilot_test_runs', 'get_copilot_question_folders', 'get_max_agent_workflow', 'execute_sql_query', 'execute_rql_query', 'get_databases', 'get_database', 'get_database_tables', 'get_dataset_id', 'get_dataset', 'get_dataset2', 'get_datasets', 'get_domain_object', 'get_domain_object_by_name', 'get_grounded_value', 'get_database_kshots', 'get_database_kshot_by_id', 'get_dataset_kshots', 'get_dataset_kshot_by_id', 'run_max_sql_gen', 'run_sql_ai', 'generate_visualization', 'llmapi_config_for_sdk', 'generate_embeddings', 'get_max_llm_prompt', 'user_chat_threads', 'user_chat_entries', 'chat_thread', 'chat_entry', 'user', 'all_chat_entries', 'skill_memory', 'chat_completion', 'narrative_completion', 'narrative_completion_with_prompt', 'sql_completion', 'research_completion', 'chat_completion_with_prompt', 'research_completion_with_prompt', 'get_chat_artifact', 'get_chat_artifacts', 'get_dynamic_layout', 'get_tracked_dimension_values', 'get_all_tracked_dimension_values', 'observability_traces')
     ping = sgqlc.types.Field(String, graphql_name='ping')
     current_user = sgqlc.types.Field(MaxUser, graphql_name='currentUser')
     get_copilot_skill_artifact_by_path = sgqlc.types.Field(CopilotSkillArtifact, graphql_name='getCopilotSkillArtifactByPath', args=sgqlc.types.ArgDict((
@@ -1989,6 +2040,18 @@ class Query(sgqlc.types.Type):
         ('sort', sgqlc.types.Arg(JSON, graphql_name='sort', default=None)),
 ))
     )
+    observability_traces = sgqlc.types.Field(sgqlc.types.non_null(ObservabilityTracesResult), graphql_name='observabilityTraces', args=sgqlc.types.ArgDict((
+        ('since', sgqlc.types.Arg(sgqlc.types.non_null(String), graphql_name='since', default=None)),
+        ('limit', sgqlc.types.Arg(Int, graphql_name='limit', default=None)),
+))
+    )
+
+
+class ResourceSpans(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('resource', 'scope_spans')
+    resource = sgqlc.types.Field(sgqlc.types.non_null(OtlpResource), graphql_name='resource')
+    scope_spans = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null('ScopeSpans'))), graphql_name='scopeSpans')
 
 
 class RunMaxSqlGenResponse(sgqlc.types.Type):
@@ -2019,6 +2082,13 @@ class RunSqlAiResponse(sgqlc.types.Type):
     prior_runs = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null('RunSqlAiResponse'))), graphql_name='priorRuns')
 
 
+class ScopeSpans(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('scope', 'spans')
+    scope = sgqlc.types.Field(sgqlc.types.non_null(InstrumentationScope), graphql_name='scope')
+    spans = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null('Span'))), graphql_name='spans')
+
+
 class SharedThread(sgqlc.types.Type):
     __schema__ = schema
     __field_names__ = ('id', 'user_id', 'original_thread_id', 'copilot_id', 'shared_by', 'last_updated_utc', 'created_utc', 'is_deleted', 'link_to_shared_thread')
@@ -2066,6 +2136,35 @@ class SkillParameter(sgqlc.types.Type):
     match_values = sgqlc.types.Field(MatchValues, graphql_name='matchValues')
 
 
+class Span(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('trace_id', 'span_id', 'parent_span_id', 'name', 'kind', 'start_time_unix_nano', 'end_time_unix_nano', 'attributes', 'events', 'status')
+    trace_id = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='traceId')
+    span_id = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='spanId')
+    parent_span_id = sgqlc.types.Field(String, graphql_name='parentSpanId')
+    name = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='name')
+    kind = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='kind')
+    start_time_unix_nano = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='startTimeUnixNano')
+    end_time_unix_nano = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='endTimeUnixNano')
+    attributes = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null(KeyValue))), graphql_name='attributes')
+    events = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null('SpanEvent'))), graphql_name='events')
+    status = sgqlc.types.Field('SpanStatus', graphql_name='status')
+
+
+class SpanEvent(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('time_unix_nano', 'name', 'attributes')
+    time_unix_nano = sgqlc.types.Field(String, graphql_name='timeUnixNano')
+    name = sgqlc.types.Field(sgqlc.types.non_null(String), graphql_name='name')
+    attributes = sgqlc.types.Field(sgqlc.types.non_null(sgqlc.types.list_of(sgqlc.types.non_null(KeyValue))), graphql_name='attributes')
+
+
+class SpanStatus(sgqlc.types.Type):
+    __schema__ = schema
+    __field_names__ = ('code',)
+    code = sgqlc.types.Field(String, graphql_name='code')
+
+
 class TrackedDimensionAttribute(sgqlc.types.Type):
     __schema__ = schema
     __field_names__ = ('dimension_attribute_id', 'dimension_name', 'values')

answerrocket_client-0.2.106/answer_rocket/observability.py

@@ -0,0 +1,241 @@
+"""
+Observability client for AnswerRocket.
+
+Fetches pre-assembled OTLP/JSON traces from the observabilityTraces GraphQL
+endpoint and delivers them to callers for forwarding to any OTel collector's
+/v1/traces endpoint.
+
+OTLP assembly is performed server-side in Kotlin (ObservabilityPublicSchemaModule).
+Each trace is a complete OTLP ExportTraceServiceRequest object.
+
+Usage patterns:
+
+  # Single page
+  batch = client.observability.get_traces(since="2026-05-01T00:00:00Z")
+
+  # All pages from a cursor
+  for batch in client.observability.iter_traces(since="2026-05-01T00:00:00Z"):
+      forward_to_collector(batch)
+
+  # Continuous polling loop
+  for batch in client.observability.poll_traces(since="2026-05-01T00:00:00Z"):
+      forward_to_collector(batch)
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, Generator, Iterator
+
+from answer_rocket.client_config import ClientConfig
+from answer_rocket.graphql.client import GraphQlClient
+
+_logger = logging.getLogger("answer_rocket.observability")
+
+DEFAULT_LIMIT = 100
+DEFAULT_POLL_INTERVAL_SECONDS = 60.0
+
+
+@dataclass
+class TracesBatch:
+    """One page of OTLP/JSON traces."""
+    success: bool = False
+    error: str | None = None
+    count: int = 0
+    has_more: bool = False
+    next_cursor: str | None = None
+    traces: list[dict] = field(default_factory=list)
+
+
+class Observability:
+    def __init__(self, config: ClientConfig, gql_client: GraphQlClient):
+        self._config = config
+        self._gql_client = gql_client
+
+    def get_traces(
+        self,
+        since: str | datetime,
+        limit: int = DEFAULT_LIMIT,
+    ) -> TracesBatch:
+        since_str = _to_iso(since)
+        try:
+            op = self._gql_client.query()
+            obs = op.observability_traces(since=since_str, limit=limit)
+            obs.count()
+            obs.has_more()
+            obs.next_cursor()
+            # The full OTLP span tree is strongly typed in the schema, so every field
+            # (including attribute KeyValue/AnyValue) must be selected explicitly.
+            resource_spans = obs.traces().resource_spans()
+            _select_key_values(resource_spans.resource().attributes())
+            scope_spans = resource_spans.scope_spans()
+            scope = scope_spans.scope()
+            scope.name()
+            scope.version()
+            spans = scope_spans.spans()
+            spans.trace_id()
+            spans.span_id()
+            spans.parent_span_id()
+            spans.name()
+            spans.kind()
+            spans.start_time_unix_nano()
+            spans.end_time_unix_nano()
+            _select_key_values(spans.attributes())
+            events = spans.events()
+            events.time_unix_nano()
+            events.name()
+            _select_key_values(events.attributes())
+            spans.status().code()
+
+            result = self._gql_client.submit(op)
+            page = result.observability_traces
+        except Exception as exc:
+            return TracesBatch(success=False, error=str(exc))
+
+        return TracesBatch(
+            success=True,
+            count=page.count,
+            has_more=page.has_more,
+            next_cursor=page.next_cursor,
+            traces=[_trace_to_otlp(t) for t in (page.traces or [])],
+        )
+
+    def iter_traces(
+        self,
+        since: str | datetime,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Iterator[list[dict]]:
+        cursor: str | datetime = since
+        while True:
+            result = self.get_traces(cursor, limit=limit)
+            if not result.success:
+                _logger.error("iter_traces page error: %s", result.error)
+                return
+            if result.traces:
+                yield result.traces
+            if not result.has_more or not result.next_cursor:
+                return
+            cursor = result.next_cursor
+
+    def poll_traces(
+        self,
+        since: str | datetime,
+        on_batch: Callable[[list[dict]], None] | None = None,
+        limit: int = DEFAULT_LIMIT,
+        poll_interval_seconds: float = DEFAULT_POLL_INTERVAL_SECONDS,
+        max_iterations: int | None = None,
+    ) -> Generator[list[dict], None, None]:
+        cursor: str | datetime = since
+        iterations = 0
+        while max_iterations is None or iterations < max_iterations:
+            result = self.get_traces(cursor, limit=limit)
+            if not result.success:
+                _logger.warning("poll_traces error (will retry): %s", result.error)
+                time.sleep(poll_interval_seconds)
+                iterations += 1
+                continue
+            if result.traces:
+                if on_batch is not None:
+                    on_batch(result.traces)
+                yield result.traces
+            if result.next_cursor:
+                cursor = result.next_cursor
+            else:
+                time.sleep(poll_interval_seconds)
+            iterations += 1
+
+
+def _to_iso(dt: str | datetime) -> str:
+    if isinstance(dt, datetime):
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.isoformat()
+    return dt
+
+
+# ---------------------------------------------------------------------------
+# GraphQL selection + reconstruction of OTLP/JSON from the typed span tree.
+#
+# The server emits a fully-typed, versionable span tree; collectors want plain OTLP
+# JSON. These helpers select every typed field and map the objects back to the OTLP
+# wire shape, omitting absent optional fields so the output matches an OTLP exporter.
+# ---------------------------------------------------------------------------
+
+def _select_key_values(kv_selector) -> None:
+    """Select an OTLP KeyValue list, including one level of AnyValue.arrayValue."""
+    kv_selector.key()
+    value = kv_selector.value()
+    value.string_value()
+    value.bool_value()
+    value.int_value()
+    value.double_value()
+    inner = value.array_value().values()
+    inner.string_value()
+    inner.bool_value()
+    inner.int_value()
+    inner.double_value()
+
+
+def _trace_to_otlp(trace) -> dict:
+    return {"resourceSpans": [_resource_spans_to_otlp(rs) for rs in (trace.resource_spans or [])]}
+
+
+def _resource_spans_to_otlp(rs) -> dict:
+    return {
+        "resource": {"attributes": [_key_value_to_otlp(kv) for kv in (rs.resource.attributes or [])]},
+        "scopeSpans": [_scope_spans_to_otlp(ss) for ss in (rs.scope_spans or [])],
+    }
+
+
+def _scope_spans_to_otlp(ss) -> dict:
+    scope: dict = {"name": ss.scope.name}
+    if ss.scope.version is not None:
+        scope["version"] = ss.scope.version
+    return {"scope": scope, "spans": [_span_to_otlp(s) for s in (ss.spans or [])]}
+
+
+def _span_to_otlp(s) -> dict:
+    out = {
+        "traceId": s.trace_id,
+        "spanId": s.span_id,
+        "name": s.name,
+        "kind": s.kind,
+        "startTimeUnixNano": s.start_time_unix_nano,
+        "endTimeUnixNano": s.end_time_unix_nano,
+        "attributes": [_key_value_to_otlp(kv) for kv in (s.attributes or [])],
+        "events": [_event_to_otlp(e) for e in (s.events or [])],
+    }
+    if s.parent_span_id is not None:
+        out["parentSpanId"] = s.parent_span_id
+    if s.status is not None:
+        out["status"] = {"code": s.status.code}
+    return out
+
+
+def _event_to_otlp(e) -> dict:
+    out = {"name": e.name, "attributes": [_key_value_to_otlp(kv) for kv in (e.attributes or [])]}
+    if e.time_unix_nano is not None:
+        out["timeUnixNano"] = e.time_unix_nano
+    return out
+
+
+def _key_value_to_otlp(kv) -> dict:
+    return {"key": kv.key, "value": _any_value_to_otlp(kv.value)}
+
+
+def _any_value_to_otlp(v) -> dict:
+    """Map a typed OTLP AnyValue back to its single-key wire form."""
+    if v.string_value is not None:
+        return {"stringValue": v.string_value}
+    if v.bool_value is not None:
+        return {"boolValue": v.bool_value}
+    if v.int_value is not None:
+        return {"intValue": v.int_value}
+    if v.double_value is not None:
+        return {"doubleValue": v.double_value}
+    if v.array_value is not None:
+        return {"arrayValue": {"values": [_any_value_to_otlp(x) for x in (v.array_value.values or [])]}}
+    return {}

{answerrocket_client-0.2.105 → answerrocket_client-0.2.106}/answerrocket_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: answerrocket-client
-Version: 0.2.105
+Version: 0.2.106
 Summary: Python client for interacting with AnswerRocket's skill API
 Requires-Python: >=3.10.7
 Description-Content-Type: text/markdown

{answerrocket_client-0.2.105 → answerrocket_client-0.2.106}/answerrocket_client.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ answer_rocket/email.py
 answer_rocket/error.py
 answer_rocket/layouts.py
 answer_rocket/llm.py
+answer_rocket/observability.py
 answer_rocket/output.py
 answer_rocket/skill.py
 answer_rocket/types.py
@@ -25,4 +26,5 @@ answerrocket_client.egg-info/SOURCES.txt
 answerrocket_client.egg-info/dependency_links.txt
 answerrocket_client.egg-info/requires.txt
 answerrocket_client.egg-info/top_level.txt
-test/test_client.py
+test/test_client.py
+test/test_observability.py

answerrocket_client-0.2.106/test/test_observability.py

@@ -0,0 +1,437 @@
+"""Tests for the Observability client (GraphQL-backed, OTLP assembled server-side)."""
+
+import sys
+import os
+import json
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from unittest.mock import MagicMock, patch
+from datetime import datetime, timezone
+
+from answer_rocket.observability import Observability, TracesBatch, DEFAULT_LIMIT
+from answer_rocket.client_config import ClientConfig
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_SAMPLE_OTLP_TRACE = {
+    "resourceSpans": [{
+        "resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "answerrocket-copilot"}}]},
+        "scopeSpans": [{"scope": {"name": "answerrocket.copilot"}, "spans": [
+            {"traceId": "abc123", "spanId": "def456", "name": "chat.pipeline",
+             "kind": "SPAN_KIND_SERVER", "startTimeUnixNano": "1000", "endTimeUnixNano": "2000",
+             "attributes": [], "events": [], "status": {"code": "STATUS_CODE_OK"}},
+        ]}],
+    }]
+}
+
+
+def _typed_any_value(v):
+    """Mimic a typed sgqlc AnyValue from an OTLP value dict (one populated variant)."""
+    m = MagicMock()
+    m.string_value = v.get("stringValue")
+    m.bool_value = v.get("boolValue")
+    m.int_value = v.get("intValue")
+    m.double_value = v.get("doubleValue")
+    if "arrayValue" in v:
+        arr = MagicMock(); arr.values = [_typed_any_value(x) for x in v["arrayValue"]["values"]]
+        m.array_value = arr
+    else:
+        m.array_value = None
+    return m
+
+
+def _typed_key_value(kv):
+    m = MagicMock(); m.key = kv["key"]; m.value = _typed_any_value(kv["value"])
+    return m
+
+
+def _typed_event(e):
+    m = MagicMock(); m.name = e["name"]; m.time_unix_nano = e.get("timeUnixNano")
+    m.attributes = [_typed_key_value(kv) for kv in e.get("attributes", [])]
+    return m
+
+
+def _typed_span(s):
+    """Mimic a typed sgqlc Span object built from an OTLP span dict."""
+    m = MagicMock()
+    m.trace_id = s["traceId"]
+    m.span_id = s["spanId"]
+    m.name = s["name"]
+    m.kind = s["kind"]
+    m.start_time_unix_nano = s["startTimeUnixNano"]
+    m.end_time_unix_nano = s["endTimeUnixNano"]
+    m.attributes = [_typed_key_value(kv) for kv in s.get("attributes", [])]
+    m.events = [_typed_event(e) for e in s.get("events", [])]   # always a list (non-null in schema)
+    m.parent_span_id = s.get("parentSpanId")                    # None when absent
+    if "status" in s:
+        st = MagicMock(); st.code = s["status"]["code"]; m.status = st
+    else:
+        m.status = None
+    return m
+
+
+def _typed_scope_spans(ss):
+    m = MagicMock()
+    sc = MagicMock(); sc.name = ss["scope"]["name"]; sc.version = ss["scope"].get("version")
+    m.scope = sc
+    m.spans = [_typed_span(s) for s in ss["spans"]]
+    return m
+
+
+def _typed_resource_spans(rs):
+    m = MagicMock()
+    res = MagicMock(); res.attributes = [_typed_key_value(kv) for kv in rs["resource"]["attributes"]]
+    m.resource = res
+    m.scope_spans = [_typed_scope_spans(ss) for ss in rs["scopeSpans"]]
+    return m
+
+
+def _typed_trace(otlp):
+    """Mimic the typed sgqlc ObservabilityTrace tree built from an OTLP dict."""
+    t = MagicMock()
+    t.resource_spans = [_typed_resource_spans(rs) for rs in otlp["resourceSpans"]]
+    return t
+
+
+def _make_gql_page(traces=None, count=None, has_more=False, next_cursor=None):
+    """Build a mock sgqlc result whose `traces` are typed objects (as the server returns)."""
+    otlp = traces or []
+    page = MagicMock()
+    page.count = count if count is not None else len(otlp)
+    page.has_more = has_more
+    page.next_cursor = next_cursor
+    page.traces = [_typed_trace(t) for t in otlp]
+    return page
+
+
+def _make_client():
+    config = MagicMock(spec=ClientConfig)
+    config.tenant = "test_tenant"
+    gql_client = MagicMock()
+    return config, gql_client, Observability(config, gql_client)
+
+
+# ---------------------------------------------------------------------------
+# Basic attribute tests
+# ---------------------------------------------------------------------------
+
+def test_client_has_observability_attr():
+    _, _, obs = _make_client()
+    assert isinstance(obs, Observability)
+
+
+def test_to_iso_string_passthrough():
+    from answer_rocket.observability import _to_iso
+    assert _to_iso("2026-01-01T00:00:00Z") == "2026-01-01T00:00:00Z"
+
+
+def test_to_iso_datetime_naive():
+    from answer_rocket.observability import _to_iso
+    dt = datetime(2026, 1, 1, 12, 0, 0)
+    result = _to_iso(dt)
+    assert "2026-01-01" in result
+    assert "+00:00" in result or "UTC" in result
+
+
+def test_to_iso_datetime_aware():
+    from answer_rocket.observability import _to_iso
+    dt = datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc)
+    result = _to_iso(dt)
+    assert "2026-01-01" in result
+
+
+# ---------------------------------------------------------------------------
+# get_traces
+# ---------------------------------------------------------------------------
+
+def test_get_traces_success():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(
+        traces=[_SAMPLE_OTLP_TRACE], count=1, has_more=False
+    )
+    gql_client.submit.return_value = mock_result
+
+    batch = obs.get_traces("2026-01-01T00:00:00Z")
+
+    assert batch.success is True
+    assert batch.count == 1
+    assert batch.has_more is False
+    assert batch.next_cursor is None
+    assert len(batch.traces) == 1
+    assert batch.traces[0] == _SAMPLE_OTLP_TRACE
+
+
+def test_get_traces_passes_correct_variables():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page()
+    gql_client.submit.return_value = mock_result
+
+    mock_op = MagicMock()
+    mock_obs_field = MagicMock()
+    mock_op.observability_traces.return_value = mock_obs_field
+    gql_client.query.return_value = mock_op
+
+    obs.get_traces("2026-05-01T00:00:00Z", limit=50)
+
+    mock_op.observability_traces.assert_called_once_with(since="2026-05-01T00:00:00Z", limit=50)
+
+
+def test_get_traces_pagination_fields():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(
+        traces=[_SAMPLE_OTLP_TRACE], count=1, has_more=True, next_cursor="2026-06-01T00:00:00Z"
+    )
+    gql_client.submit.return_value = mock_result
+
+    batch = obs.get_traces("2026-01-01T00:00:00Z")
+
+    assert batch.has_more is True
+    assert batch.next_cursor == "2026-06-01T00:00:00Z"
+
+
+def test_get_traces_connection_error():
+    config, gql_client, obs = _make_client()
+    gql_client.submit.side_effect = ConnectionError("timeout")
+
+    batch = obs.get_traces("2026-01-01T00:00:00Z")
+
+    assert batch.success is False
+    assert "timeout" in batch.error
+    assert batch.traces == []
+
+
+def test_get_traces_empty_page():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(traces=[], count=0, has_more=False)
+    gql_client.submit.return_value = mock_result
+
+    batch = obs.get_traces("2026-01-01T00:00:00Z")
+
+    assert batch.success is True
+    assert batch.count == 0
+    assert batch.traces == []
+
+
+# ---------------------------------------------------------------------------
+# iter_traces
+# ---------------------------------------------------------------------------
+
+def test_iter_traces_follows_pages():
+    config, gql_client, obs = _make_client()
+    page1 = MagicMock()
+    page1.observability_traces = _make_gql_page(
+        traces=[_SAMPLE_OTLP_TRACE], count=1, has_more=True, next_cursor="cursor_1"
+    )
+    page2 = MagicMock()
+    page2.observability_traces = _make_gql_page(
+        traces=[_SAMPLE_OTLP_TRACE], count=1, has_more=False
+    )
+    gql_client.submit.side_effect = [page1, page2]
+
+    batches = list(obs.iter_traces("2026-01-01T00:00:00Z"))
+
+    assert len(batches) == 2
+    assert gql_client.submit.call_count == 2
+
+
+def test_iter_traces_stops_on_empty():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(traces=[], has_more=False)
+    gql_client.submit.return_value = mock_result
+
+    batches = list(obs.iter_traces("2026-01-01T00:00:00Z"))
+
+    assert batches == []
+
+
+def test_iter_traces_stops_on_error():
+    config, gql_client, obs = _make_client()
+    gql_client.submit.side_effect = Exception("server error")
+
+    batches = list(obs.iter_traces("2026-01-01T00:00:00Z"))
+
+    assert batches == []
+
+
+# ---------------------------------------------------------------------------
+# poll_traces
+# ---------------------------------------------------------------------------
+
+def test_poll_traces_max_iterations():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(
+        traces=[_SAMPLE_OTLP_TRACE], count=1, has_more=False
+    )
+    gql_client.submit.return_value = mock_result
+
+    with patch("time.sleep"):
+        batches = list(obs.poll_traces("2026-01-01T00:00:00Z", max_iterations=3))
+
+    assert len(batches) == 3
+
+
+def test_poll_traces_skips_empty_batches():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(traces=[], has_more=False)
+    gql_client.submit.return_value = mock_result
+
+    with patch("time.sleep"):
+        batches = list(obs.poll_traces("2026-01-01T00:00:00Z", max_iterations=2))
+
+    assert batches == []
+
+
+def test_poll_traces_on_batch_callback():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(
+        traces=[_SAMPLE_OTLP_TRACE], count=1, has_more=False
+    )
+    gql_client.submit.return_value = mock_result
+
+    received = []
+    with patch("time.sleep"):
+        for _ in obs.poll_traces("2026-01-01T00:00:00Z", on_batch=received.extend, max_iterations=1):
+            pass
+
+    assert len(received) == 1
+    assert received[0] == _SAMPLE_OTLP_TRACE
+
+
+# ---------------------------------------------------------------------------
+# Cursor handling
+# ---------------------------------------------------------------------------
+
+def test_get_traces_converts_datetime_cursor_to_iso():
+    config, gql_client, obs = _make_client()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page()
+    gql_client.submit.return_value = mock_result
+    mock_op = MagicMock()
+    gql_client.query.return_value = mock_op
+
+    obs.get_traces(datetime(2026, 5, 1, 12, 0, 0, tzinfo=timezone.utc), limit=10)
+
+    _, kwargs = mock_op.observability_traces.call_args
+    assert kwargs["since"].startswith("2026-05-01T12:00:00")
+    assert kwargs["limit"] == 10
+
+
+def test_iter_traces_threads_next_cursor_as_since():
+    """Page 2 must be requested with `since` == page 1's next_cursor (no re-scan, no gaps)."""
+    config, gql_client, obs = _make_client()
+    page1 = MagicMock()
+    page1.observability_traces = _make_gql_page(
+        traces=[_SAMPLE_OTLP_TRACE], has_more=True, next_cursor="2026-05-01T12:00:01Z"
+    )
+    page2 = MagicMock()
+    page2.observability_traces = _make_gql_page(traces=[_SAMPLE_OTLP_TRACE], has_more=False)
+    gql_client.submit.side_effect = [page1, page2]
+
+    mock_op = MagicMock()
+    gql_client.query.return_value = mock_op
+
+    list(obs.iter_traces("2026-05-01T00:00:00Z"))
+
+    calls = mock_op.observability_traces.call_args_list
+    assert len(calls) == 2
+    assert calls[0].kwargs["since"] == "2026-05-01T00:00:00Z"
+    assert calls[1].kwargs["since"] == "2026-05-01T12:00:01Z"
+
+
+# ---------------------------------------------------------------------------
+# Contract: SDK faithfully passes server-assembled OTLP through (ties both PRs)
+# ---------------------------------------------------------------------------
+
+def _load_golden_trace():
+    path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "fixtures", "example_otlp_trace.json")
+    with open(path) as f:
+        return json.load(f)
+
+
+def test_contract_reconstructs_real_server_trace_to_identical_otlp():
+    config, gql_client, obs = _make_client()
+    golden = _load_golden_trace()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(traces=[golden], count=1, has_more=False)
+    gql_client.submit.return_value = mock_result
+
+    batch = obs.get_traces("2026-05-01T00:00:00Z")
+
+    assert batch.success is True
+    assert batch.count == 1
+    # The typed span tree must reconstruct byte-identically to the server's OTLP.
+    assert batch.traces[0] == golden
+
+
+def test_reconstruction_handles_typed_attributes_and_optionals():
+    from answer_rocket.observability import _span_to_otlp
+    full = _typed_span({
+        "traceId": "t", "spanId": "s", "name": "n", "kind": "SPAN_KIND_INTERNAL",
+        "startTimeUnixNano": "1", "endTimeUnixNano": "2",
+        "attributes": [
+            {"key": "ar.run_id", "value": {"stringValue": "v"}},
+            {"key": "ar.tokens.total", "value": {"intValue": "42"}},
+            {"key": "ar.cost", "value": {"doubleValue": 0.01}},
+            {"key": "ar.flag", "value": {"boolValue": True}},
+            {"key": "ar.answer.suggestions", "value": {"arrayValue": {"values": [{"stringValue": "a"}, {"stringValue": "b"}]}}},
+        ],
+        "events": [{"name": "e", "attributes": []}],
+        "parentSpanId": "p", "status": {"code": "STATUS_CODE_OK"},
+    })
+    assert _span_to_otlp(full) == {
+        "traceId": "t", "spanId": "s", "name": "n", "kind": "SPAN_KIND_INTERNAL",
+        "startTimeUnixNano": "1", "endTimeUnixNano": "2",
+        "attributes": [
+            {"key": "ar.run_id", "value": {"stringValue": "v"}},
+            {"key": "ar.tokens.total", "value": {"intValue": "42"}},
+            {"key": "ar.cost", "value": {"doubleValue": 0.01}},
+            {"key": "ar.flag", "value": {"boolValue": True}},
+            {"key": "ar.answer.suggestions", "value": {"arrayValue": {"values": [{"stringValue": "a"}, {"stringValue": "b"}]}}},
+        ],
+        "events": [{"name": "e", "attributes": []}],
+        "parentSpanId": "p", "status": {"code": "STATUS_CODE_OK"},
+    }
+
+    # Optional parentSpanId/status are omitted when absent; events is always a (possibly empty) list.
+    minimal = _typed_span({
+        "traceId": "t", "spanId": "s", "name": "root", "kind": "SPAN_KIND_SERVER",
+        "startTimeUnixNano": "1", "endTimeUnixNano": "2", "attributes": [], "events": [],
+    })
+    out = _span_to_otlp(minimal)
+    assert "parentSpanId" not in out
+    assert "status" not in out
+    assert out["events"] == []
+    assert out["attributes"] == []
+
+
+def test_contract_returned_trace_is_valid_otlp():
+    config, gql_client, obs = _make_client()
+    golden = _load_golden_trace()
+    mock_result = MagicMock()
+    mock_result.observability_traces = _make_gql_page(traces=[golden], count=1)
+    gql_client.submit.return_value = mock_result
+
+    trace = obs.get_traces("2026-05-01T00:00:00Z").traces[0]
+
+    spans = trace["resourceSpans"][0]["scopeSpans"][0]["spans"]
+    names = [s["name"] for s in spans]
+    assert "chat.pipeline" in names
+    assert any(n.startswith("phase.") for n in names)
+    assert "skill.narrative" in names
+    # All spans share one traceId; every span has the required OTLP fields.
+    trace_ids = {s["traceId"] for s in spans}
+    assert len(trace_ids) == 1
+    for s in spans:
+        assert s["spanId"]
+        assert s["startTimeUnixNano"] and s["endTimeUnixNano"]
+        assert int(s["startTimeUnixNano"]) <= int(s["endTimeUnixNano"])