mixle.telemetry package¶

Local-first telemetry for model, placement, routing, and reasoning decisions.

Telemetry records typed decision events with features, choices, outcomes, tags, and timestamps. These records support dashboards, auditing, and learned orchestration policies. Only kind is a closed vocabulary; the log itself is JSONL, and a rewrite preserves every row already in it, including rows another writer put there.

Nothing here filters what a caller records, and the log is an ordinary local file. features, choice, outcome and tags are serialized as given: there is no per-kind schema, no allowlist, no redaction, no size limit, no classification, no encryption, no access control and no retention policy. A prompt, an answer, an API key or a customer record passed through the normal API therefore lands verbatim in a long-lived file on disk. Recording only derived, non-identifying quantities – counts, sizes, durations, costs, method names – is a convention this package expects of its callers, not a property it enforces on their behalf; a caller handling sensitive material must minimize or redact before calling record(), and must govern the log file’s location, permissions and lifetime itself.

A process-global recorder makes record(...) convenient, while tests and isolated workflows can use their own Telemetry instance.

dashboard(telemetry)[source]

Fold the telemetry stream into a receipt summary (see module docstring).

Parameters:: telemetry (Any)
Return type:: dict[str, Any]

render_dashboard(telemetry)[source]

The dashboard as plain markdown – printable in a terminal, embeddable in a report.

Parameters:: telemetry (Any)
Return type:: str

class Event(kind, features=<factory>, choice=None, outcome=<factory>, tags=<factory>, ts=0.0)[source]

Bases: object

One typed, timestamped decision record. Features/choice describe the decision; outcome scores it.

outcome is deliberately mutable after the fact – that is the documented “close the loop later” pattern Telemetry.record() describes. The event’s identity is not: kind and ts are re-validated on every assignment, not only at construction. Because a flush rewrites the whole log from the current field values, an event mutated into an invalid state would otherwise rewrite already-persisted history as something no reader can load back.

Parameters:

kind (str)
features (dict[str, Any])
choice (Any)
outcome (dict[str, Any])
tags (dict[str, str])
ts (float)

as_row()[source]

Return this event as a JSON-serializable row.

Return type:: dict[str, Any]

class Telemetry(path=None, *, flush_every=1)[source]

Bases: object

A local-first event recorder: buffer in memory, append to a JSONL log, read back for training.

record(kind, features=..., choice=..., outcome=..., tags=...) appends one Event. events(kind=...) yields the buffer (optionally filtered). training_rows(kind) yields the (features, choice, outcome) triples the learned-orchestration models consume.

Parameters:

path (str | None)
flush_every (int)

record(kind, *, features=None, choice=None, outcome=None, tags=None, when=None)[source]

Record one decision event; returns it (mutate .outcome later to close the loop).

The mutation updates this recorder’s in-memory buffer immediately and is captured by the next flush – an explicit flush() call, or the next automatic flush once flush_every more events have been recorded – because every flush rewrites the full buffered log rather than only appending whatever is new. Until that next flush, the JSONL file on disk (and any other reader with it open) still shows the pre-mutation value.

Parameters:

kind (str)
features (dict[str, Any] | None)
choice (Any)
outcome (dict[str, Any] | None)
tags (dict[str, str] | None)
when (float | None)

Return type:

Event

events(*, kind=None)[source]

Yield recorded events, optionally filtered by kind.

Parameters:: kind (str | None)
Return type:: Iterator[Event]

training_rows(kind)[source]

The (features, choice, outcome) triples for a decision kind.

Parameters:: kind (str)
Return type:: list[tuple[dict[str, Any], Any, dict[str, Any]]]

flush()[source]

Flush any buffered events to the configured JSONL log.

Return type:: None

record(kind, **kw)[source]

Record an event on the process-global recorder (see Telemetry.record()).

Parameters:

kind (str)
kw (Any)

Return type:

Event

get_default_recorder()[source]

The process-global recorder (a no-path in-memory buffer until one is configured).

Return type:: Telemetry

set_default_recorder(recorder)[source]

Install (or clear) the process-global recorder – e.g. point it at the user’s telemetry log.

Parameters:: recorder (Telemetry | None)
Return type:: None

mixle.telemetry package¶

Submodules¶