nat.utils.telemetry.events

Event schemas for NAT CLI telemetry.

The base TelemetryEvent enforces that every concrete subclass declares an _event_name ClassVar (validated at subclass-creation time so mistakes fail before the first instance is built). All event payloads use camelCase wire aliases while keeping snake_case Python attribute names.

The wire shape mirrors the NeMo Usage Telemetry project schema (clientId 184482118588404). Fields use sentinel values for unknowns (-1 for ints, "undefined" for strings) rather than nullable types, matching the schema’s additionalProperties: false + all-required-fields convention.

Classes

NemoSourceEnum	The NeMo product that emitted the event. Discriminator across NeMo products
TaskStatusEnum	Outcome of the task being reported.
TelemetryEvent	Base class for all NAT telemetry events.
CliCommandEvent	Single invocation of a top-level NAT CLI command (e.g. nat run).

Module Contents

class NemoSourceEnum

Bases: enum.StrEnum

The NeMo product that emitted the event. Discriminator across NeMo products sharing the NeMo Usage Telemetry schema.

Values mirror the schema-1.5 NemoSourceEnum definition in nemo-telemetry/schemas/anonymous_events.json. NAT itself only emits AGENT_TOOLKIT; the other values exist so this enum is a faithful mirror of the published schema (e.g. tests can deserialize foreign payloads, and future upstream additions surface as diff conflicts here).

Initialize self. See help(type(self)) for accurate signature.

INFERENCE = 'inference'

AUDITOR = 'auditor'

DATADESIGNER = 'datadesigner'

EVALUATOR = 'evaluator'

GUARDRAILS = 'guardrails'

SAFE_SYNTHESIZER = 'safe-synthesizer'

ANONYMIZER = 'anonymizer'

AGENT_TOOLKIT = 'agent_toolkit'

UNDEFINED = 'undefined'

class TaskStatusEnum

Bases: enum.StrEnum

Outcome of the task being reported.

Values mirror the schema-1.5 TaskStatusEnum definition. NAT’s CliCommandEvent only emits SUCCESS / FAILURE / INTERRUPTED; the other values exist for schema-mirror parity with other NeMo products.

Initialize self. See help(type(self)) for accurate signature.

SUCCESS = 'success'

FAILURE = 'failure'

COMPLETED = 'completed'

ERROR = 'error'

CANCELED = 'canceled'

INTERRUPTED = 'interrupted'

UNDEFINED = 'undefined'

class TelemetryEvent(/, **data: Any)

Bases: pydantic.BaseModel

Base class for all NAT telemetry events.

Subclasses must set _event_name as a ClassVar. Attempting to define a subclass without it raises TypeError at class-creation time.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

_event_name: ClassVar[str]

_schema_version: ClassVar[str] = '1.5'

class CliCommandEvent(/, **data: Any)

Bases: TelemetryEvent

Single invocation of a top-level NAT CLI command (e.g. nat run).

Privacy: this schema is deliberately minimal. It must never carry command arguments, option values, file paths, config contents, workflow/function names, hostnames, usernames, or any other user-supplied strings. The only free-form string is error_class, which is the exception class name on failure (never the message).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

_event_name: ClassVar[str] = 'nat_cli_command'

nemo_source: NemoSourceEnum = None

command: str = None

subcommand: str = None

task_status: TaskStatusEnum = None

duration_ms: int = None

exit_code: int = None

error_class: str = None

python_version: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].