nat.atif.atif_step_extra#

Typed models for NAT-owned ancestry / invocation metadata embedded in ATIF extra dicts.

The ATIF v1.7 spec does not define a typed ancestry model — producers embed ancestry-shaped data inside the optional extra field on records where it is meaningful. NAT’s convention places:

  • step-level ancestry at Step.extra["ancestry"] (AtifAncestry shape)

  • per-tool-call ancestry at ToolCall.extra["ancestry"] (AtifAncestry shape)

  • step-level invocation timing at Step.extra["invocation"] (AtifInvocationInfo shape)

  • per-tool-call invocation timing at ToolCall.extra["invocation"] (AtifInvocationInfo shape)

These models are validated representations of those payloads — producers MAY round-trip them through model_dump() before placing them in extra; consumers MAY parse them back with model_validate() to revalidate the shape. Direct dict use is also supported. The spec treats extra as a loosely-typed dict, so consumers MUST tolerate absence and missing keys.

Classes#

AtifAncestry

Validated ancestry metadata embedded in ATIF extra dicts.

AtifInvocationInfo

Invocation timing metadata embedded in ATIF extra dicts.

AtifStepExtra

Validated structure for NAT-owned ATIF Step.extra payload.

AtifToolCallExtra

Validated structure for NAT-owned ATIF ToolCall.extra payload.

Module Contents#

class AtifAncestry(/, **data: Any)#

Bases: pydantic.BaseModel

Validated ancestry metadata embedded in ATIF extra dicts.

Used in two locations under the NAT convention:

  • Step.extra["ancestry"] — step-level: which callable produced this step (e.g. an LLM node under a parent agent).

  • ToolCall.extra["ancestry"] — per-tool-call: which callable issued this tool invocation.

The model enforces a parent-pair invariant: parent_name MAY only be set when parent_id is also set. The inverse — parent_id set, parent_name unset — is allowed (the converter emits this when a parent’s UUID isn’t in the local name map).

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.

model_config#

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

function_id: str = None#
function_name: str = None#
parent_id: str | None = None#
parent_name: str | None = None#
_validate_parent_pair() → Self#
class AtifInvocationInfo(/, **data: Any)#

Bases: pydantic.BaseModel

Invocation timing metadata embedded in ATIF extra dicts.

Used at Step.extra["invocation"] for step-level timing and at ToolCall.extra["invocation"] for per-tool timing.

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.

model_config#

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

start_timestamp: float | None = None#
end_timestamp: float | None = None#
invocation_id: str | None = None#
status: str | None = None#
framework: str | None = None#
validate_timestamp_pairing() → Self#
class AtifStepExtra(/, **data: Any)#

Bases: pydantic.BaseModel

Validated structure for NAT-owned ATIF Step.extra payload.

NAT writes the following keys into Step.extra under this convention:

  • ancestry (required by NAT’s converter) — AtifAncestry shape: which callable produced this step.

  • invocation (optional) — AtifInvocationInfo shape: step-level timing.

  • data_schema (optional, opaque dict) — the producer-declared ATOF data_schema preserved for downstream validation.

Per-tool-call ancestry and timing live on ToolCall.extra, NOT here — they’re co-located with the tool_call they describe rather than aligned by index on the parent step. This is the v1.7-aligned layout (the spec adds extra to ToolCall for this purpose).

model_config = ConfigDict(extra="allow") so callers MAY add additional keys. The required ancestry field documents NAT’s own convention but does not preclude other producers from emitting different Step.extra shapes.

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.

model_config#

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

ancestry: AtifAncestry = None#
invocation: AtifInvocationInfo | None = None#
class AtifToolCallExtra(/, **data: Any)#

Bases: pydantic.BaseModel

Validated structure for NAT-owned ATIF ToolCall.extra payload.

NAT writes the following keys into ToolCall.extra under this convention:

  • ancestry (optional) — AtifAncestry shape: which callable issued this tool invocation.

  • invocation (optional) — AtifInvocationInfo shape: per-tool-call timing.

model_config = ConfigDict(extra="allow") so callers MAY add additional keys. extra="allow" also means a ToolCall.extra that lacks both keys still validates — neither is required by the NAT convention.

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.

model_config#

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

ancestry: AtifAncestry | None = None#
invocation: AtifInvocationInfo | None = None#