TAI42 — the OS for AI tools

The read/query half of the monitoring contract. Implement only if the backend has a read API. A read-incapable backend still exposes a reader object, but its methods raise MonitoringReadNotSupportedError on call (never a silent no-op). OpenTelemetry has no read/query standard — each backend invents its own read surface — so this face is the abstraction’s real value.

MonitoringReader

tai42_contract.monitoring.reader.MonitoringReader

class MonitoringReader(Protocol)

Query totals/analytics and the runtime span window.

Members

query_metrics

tai42_contract.monitoring.reader.MonitoringReader.query_metrics

async query_metrics(self, filter: MetricsFilter) -> MetricsResult

Totals / analytics screen — server-side aggregation. Counts (runs, tags), total cost, total tokens, latency, grouped by the requested dimensions. Parameters

Parameter	Type	Default	Description
`filter`	`MetricsFilter`	—	—

list_spans_in_window

tai42_contract.monitoring.reader.MonitoringReader.list_spans_in_window

async list_spans_in_window(
    self,
    t0: datetime,
    t1: datetime,
    *,
    run: str | None = None,
    kind: SpanKind | None = None,
    filter: MonitoringFilter | None = None,
    order_by: OrderBy | None = None,
) -> list[SpanWindowItem]

The smallest spans that ran in the half-open window [t0, t1). CONTRACT GUARANTEE: exactly one item per tool/node execution in the window. Every reader performs this tool-granularity selection — it is not an optional filter. run scopes to a single run (one trace); None = all runs in the window. kind narrows WITHIN the tool-granularity set (never widens or overrides the guarantee). filter applies the neutral MonitoringFilter clauses (tags live here, not as a discrete param). order_by sorts the result; omitted ⇒ newest-first (start desc). An unsupported order_by.field or filter clause raises MonitoringReadNotSupportedError. Parameters

Parameter	Type	Default	Description
`t0`	`datetime`	—	—
`t1`	`datetime`	—	—
`run`	`str \| None`	`None`	—
`kind`	`SpanKind \| None`	`None`	—
`filter`	`MonitoringFilter \| None`	`None`	—
`order_by`	`OrderBy \| None`	`None`	—

get_trace

tai42_contract.monitoring.reader.MonitoringReader.get_trace

async get_trace(self, trace_id: str) -> MonitoringTrace

Fetch one COMPLETE trace (top-level attrs + every observation, with full input/output) for replay / evaluation / normalization. Always returns a trace or raises — never None. An absent trace raises TraceNotFoundError; a transient/backend failure (e.g. a timeout) propagates its error so the caller sees the failure and may retry. Distinct from list_spans_in_window (trimmed dashboard units). Parameters

Parameter	Type	Default	Description
`trace_id`	`str`	—	—

list_traces

tai42_contract.monitoring.reader.MonitoringReader.list_traces

async list_traces(
    self,
    *,
    from_timestamp: datetime | None = None,
    to_timestamp: datetime | None = None,
    limit: int | None = None,
    page: int | None = None,
    filter: MonitoringFilter | None = None,
    order_by: OrderBy | None = None,
) -> list[MonitoringTrace]

List complete traces (each with its full observation set) matching the filters. An individual trace that cannot be fetched is kept in place with fetch_error set (not skipped), so one bad trace neither fails the batch nor silently vanishes. from_timestamp / to_timestamp bound the trace timestamp to the half-open window [from, to); either may be omitted for an open end. filter applies the neutral MonitoringFilter clauses (tags live here, not as a discrete param). order_by sorts the result; omitted ⇒ newest-first (timestamp desc). Sortable fields: timestamp, total_cost, name, id, latency, total_tokens — of these total_cost / latency / total_tokens rank globally (see OrderBy); the rest sort natively. An unsupported order_by.field or filter clause raises MonitoringReadNotSupportedError. Parameters

Parameter	Type	Default	Description
`from_timestamp`	`datetime \| None`	`None`	—
`to_timestamp`	`datetime \| None`	`None`	—
`limit`	`int \| None`	`None`	—
`page`	`int \| None`	`None`	—
`filter`	`MonitoringFilter \| None`	`None`	—
`order_by`	`OrderBy \| None`	`None`	—

MonitoringWriter

tai42_contract.monitoring.writer.MonitoringWriter

class MonitoringWriter(Protocol)

Emit traces/spans/events, supply callbacks, and manage lifecycle. Every backend implements this face.

Members

start_span

tai42_contract.monitoring.writer.MonitoringWriter.start_span

start_span(
    self,
    *,
    name: str,
    kind: SpanKind,
    trace_context: TraceContext | None = None,
    input: Any = None,
    model: str | None = None,
    model_parameters: dict[str, Any] | None = None,
    metadata: dict[str, Any] | None = None,
) -> AbstractContextManager[Span]

Open a span for the duration of the block, yielding a Span handle. model / model_parameters carry GENERATION-span detail. model_parameters is open-time only (known before the call); model and usage_details can be amended later via the handle’s Span.update. A no-op under an active disable() block. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—
`kind`	`SpanKind`	—	—
`trace_context`	`TraceContext \| None`	`None`	—
`input`	`Any`	`None`	—
`model`	`str \| None`	`None`	—
`model_parameters`	`dict[str, Any] \| None`	`None`	—
`metadata`	`dict[str, Any] \| None`	`None`	—

record_span

tai42_contract.monitoring.writer.MonitoringWriter.record_span

record_span(
    self,
    *,
    name: str,
    kind: SpanKind,
    start: datetime,
    end: datetime,
    trace_context: TraceContext,
    input: Any = None,
    output: Any = None,
    level: MonitoringLevel | None = None,
    status_message: str | None = None,
    model: str | None = None,
    usage_details: dict[str, Any] | None = None,
    metadata: dict[str, Any] | None = None,
) -> None

Record an already-closed span with EXPLICIT start / end times. For a span whose execution window cannot be timed live in-process — work that ran across a pause and is reported afterwards. start / end are wall-clock datetime; the backend converts as needed. trace_context.trace_id is REQUIRED — the explicit-time path has no ambient context to fall back to, so a missing trace_id RAISES (a caller bug); parent_span_id nests the span. Backend emission failures are caught + logged like the other emit methods. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—
`kind`	`SpanKind`	—	—
`start`	`datetime`	—	—
`end`	`datetime`	—	—
`trace_context`	`TraceContext`	—	—
`input`	`Any`	`None`	—
`output`	`Any`	`None`	—
`level`	`MonitoringLevel \| None`	`None`	—
`status_message`	`str \| None`	`None`	—
`model`	`str \| None`	`None`	—
`usage_details`	`dict[str, Any] \| None`	`None`	—
`metadata`	`dict[str, Any] \| None`	`None`	—

create_event

tai42_contract.monitoring.writer.MonitoringWriter.create_event

create_event(
    self,
    *,
    name: str,
    level: MonitoringLevel = DEFAULT_LEVEL,
    trace_context: TraceContext | None = None,
    input: Any = None,
    output: Any = None,
    status_message: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> None

Record a point-in-time event, carrying input / output. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—
`level`	`MonitoringLevel`	`DEFAULT_LEVEL`	—
`trace_context`	`TraceContext \| None`	`None`	—
`input`	`Any`	`None`	—
`output`	`Any`	`None`	—
`status_message`	`str \| None`	`None`	—
`metadata`	`dict[str, Any] \| None`	`None`	—

update_current_span

tai42_contract.monitoring.writer.MonitoringWriter.update_current_span

update_current_span(
    self,
    *,
    level: MonitoringLevel | None = None,
    status_message: str | None = None,
    metadata: dict[str, Any] | None = None,
    output: Any = None,
) -> None

Mutate the CURRENT (ambient) span without opening a new one. Targets the span opened by the nearest enclosing start_span block (or the callback-handler span if none). Per-generation token/cost is recorded via the held Span.update handle, not here. Parameters

Parameter	Type	Default	Description
`level`	`MonitoringLevel \| None`	`None`	—
`status_message`	`str \| None`	`None`	—
`metadata`	`dict[str, Any] \| None`	`None`	—
`output`	`Any`	`None`	—

trace_attributes

tai42_contract.monitoring.writer.MonitoringWriter.trace_attributes

trace_attributes(
    self,
    *,
    name: str | None = None,
    tags: list[str] | None = None,
    metadata: dict[str, Any] | None = None,
) -> AbstractContextManager[None]

Set trace-level name/tags/metadata on the ambient trace for the block. Parameters

Parameter	Type	Default	Description
`name`	`str \| None`	`None`	—
`tags`	`list[str] \| None`	`None`	—
`metadata`	`dict[str, Any] \| None`	`None`	—

current_trace_id

tai42_contract.monitoring.writer.MonitoringWriter.current_trace_id

current_trace_id(self) -> str | None

The active ambient trace id, or None if no trace is active. Used to gate conditional emits (if writer.current_trace_id():) so none fire outside a trace.

inject_context

tai42_contract.monitoring.writer.MonitoringWriter.inject_context

inject_context(self, ctx: TraceContext) -> dict[str, Any]

Build the opaque downstream-propagation blob merged into the langgraph RunnableConfig. Carries ctx.tags + ctx.metadata. Parameters

Parameter	Type	Default	Description
`ctx`	`TraceContext`	—	—

get_monitoring_callbacks

tai42_contract.monitoring.writer.MonitoringWriter.get_monitoring_callbacks

get_monitoring_callbacks(self, ctx: TraceContext) -> list[object]

The LangChain/LangGraph callback handlers appended to the langgraph config["callbacks"]. The caller builds ctx (keeping the auto-generated-trace-id fallback); the impl reads its fields to construct the vendor handler. Parameters

Parameter	Type	Default	Description
`ctx`	`TraceContext`	—	—

scope

tai42_contract.monitoring.writer.MonitoringWriter.scope

scope(self, public_key: str) -> AbstractContextManager[None]

Bind tracing to a project (public_key) for the block. Mirrors a single-backend multi-project switch. OTel-native backends may no-op it; a real failure must raise (cross-project leak risk). Parameters

Parameter	Type	Default	Description
`public_key`	`str`	—	—

disable

tai42_contract.monitoring.writer.MonitoringWriter.disable

disable(self) -> AbstractContextManager[None]

Suppress emission within the block. The backend’s tracing-producing methods (and the handlers from get_monitoring_callbacks) MUST honor this. A backend that never emits may no-op it; an emitting backend may not.

flush

tai42_contract.monitoring.writer.MonitoringWriter.flush

flush(self) -> None

Flush any buffered telemetry.

shutdown

tai42_contract.monitoring.writer.MonitoringWriter.shutdown

shutdown(self) -> None

Tear the client down so the next use rebuilds clean (fork-safety). Must fully evict the underlying client, not merely flush — a forked child inherits dead background threads otherwise.

HTTP API

CLI

Settings

Python SDK

Catalog

Studio SDK

Monitoring (tai42_contract.monitoring)

MonitoringReader

Members

query_metrics

list_spans_in_window

get_trace

list_traces

MonitoringWriter

Members

start_span

record_span

create_event

update_current_span

trace_attributes

current_trace_id

inject_context

get_monitoring_callbacks

scope

disable

flush

shutdown

​MonitoringReader

​Members

​query_metrics

​list_spans_in_window

​get_trace

​list_traces

​MonitoringWriter

​Members

​start_span

​record_span

​create_event

​update_current_span

​trace_attributes

​current_trace_id

​inject_context

​get_monitoring_callbacks

​scope

​disable

​flush

​shutdown

MonitoringReader

Members

query_metrics

list_spans_in_window

get_trace

list_traces

MonitoringWriter

Members

start_span

record_span

create_event

update_current_span

trace_attributes

current_trace_id

inject_context

get_monitoring_callbacks

scope

disable

flush

shutdown