`mod atif`#

module atif#

ATIF (Agent Trajectory Interchange Format) exporter.

This module provides types and an exporter that collects lifecycle events from the NeMo Flow runtime and converts them into ATIF trajectories conforming to the ATIF v1.6 schema.

Overview

The AtifExporter registers as an event subscriber, collects all events, and can export them as an AtifTrajectory via AtifExporter::export.

Event-to-Step Mapping

The core conversion from NeMo Flow events to ATIF steps follows these rules:

NeMo Flow Event	ATIF Step	Notes
LLM Start	`user` step	Messages extracted from LlmRequest
LLM End	`agent` step	Response content, tool_calls promoted
Tool Start	(skipped)	tool_calls come from LLM End instead
Tool End	`system` observation	Consecutive tool ends merged
Mark (with data)	`system` step	Custom event data preserved
Scope Start/End	(skipped)	Structural events, not trajectory

The exporter serializes the full collected event stream into a single ATIF trajectory.

Variables

const ATIF_SCHEMA_VERSION: &str#: The ATIF schema version string embedded in all exported trajectories.

Currently "ATIF-v1.6". This constant is used by AtifTrajectory serialization and verified by downstream consumers to ensure compatibility.

Structs and Unions

struct AtifAgentInfo#

Information about the agent that produced the trajectory.

name: String#: Human-readable agent name.

version: String#: Agent version string.

model_name: Option<String>#: Default LLM model name used by the agent.

tool_definitions: Option<Vec<Json>>#: Tool definitions available to the agent.

extra: Option<Json>#: Extra metadata.

struct AtifAncestry#

Lineage node identifying a callable within an ATIF step.

function_id: String#: Unique identifier for the callable node (scope UUID).

function_name: String#: Human-readable name of the callable node.

parent_id: Option<String>#: Optional parent callable identifier.

parent_name: Option<String>#: Optional parent callable name.

struct AtifExporter#

Collects lifecycle events and exports them as ATIF trajectories.

Register this exporter as an event subscriber via AtifExporter::subscriber, then call AtifExporter::export to produce an AtifTrajectory.

Implementations

impl AtifExporter#

Functions

fn clear(&self)#: Clear all collected events from the internal buffer.

Returns

().

fn export(&self) -> AtifTrajectory#: Export the collected event history as an AtifTrajectory.

Returns

An AtifTrajectory synthesized from the events observed so far.

Notes

Exporting does not clear the buffered events. Call AtifExporter::clear when you need to reset the exporter between trajectories.

fn new(session_id: String, agent_info: AtifAgentInfo) -> Self#

Create a new exporter with the given session metadata.

Parameters

session_id: Stable identifier for the trajectory being collected.
agent_info: Metadata describing the emitting agent.

Returns

A new AtifExporter with an empty in-memory event buffer.

fn subscriber(&self) -> EventSubscriberFn#: Return an event subscriber function that records NeMo Flow events.

The returned callback can be registered with register_subscriber.

Returns

An EventSubscriberFn that appends each observed event to this exporter’s internal buffer.

struct AtifFinalMetrics#

Aggregate statistics for the entire trajectory (ATIF v1.6 final_metrics).

total_prompt_tokens: Option<u64>#: Sum of all prompt tokens across all steps, including cached tokens.

total_completion_tokens: Option<u64>#: Sum of all completion tokens across all steps.

total_cached_tokens: Option<u64>#: Sum of all cached tokens across all steps.

total_cost_usd: Option<f64>#: Total real monetary cost for the entire trajectory.

total_steps: Option<u64>#: Total number of steps. If not equivalent to steps.len(), document in notes.

extra: Option<Json>#: Custom aggregate metrics.

struct AtifInvocationInfo#

Invocation timing and correlation metadata for one execution occurrence.

start_timestamp and end_timestamp are always emitted together or not at all.

start_timestamp: Option<f64>#: Invocation start timestamp in Unix epoch seconds.

end_timestamp: Option<f64>#: Invocation end timestamp in Unix epoch seconds.

invocation_id: Option<String>#: Stable invocation identifier for correlation.

status: Option<String>#: Terminal status of the invocation.

framework: Option<String>#: Runtime or framework label.

struct AtifMetrics#

Token usage and cost metrics for a single step.

prompt_tokens: Option<u64>#: Number of prompt tokens.

completion_tokens: Option<u64>#: Number of completion tokens.

cached_tokens: Option<u64>#: Number of cached tokens.

cost_usd: Option<f64>#: Cost in USD.

prompt_token_ids: Option<Vec<u64>>#: Token IDs for prompt (input) tokens.

completion_token_ids: Option<Vec<u64>>#: Token IDs for completion (response) tokens.

logprobs: Option<Vec<f64>>#: Log probability assigned to each generated token.

extra: Option<Json>#: Other metrics (e.g. reasoning_tokens, cache_creation_input_tokens).

struct AtifObservation#

Observation results from tool execution.

results: Vec<AtifObservationResult>#: List of observation results (one per tool call).

struct AtifObservationResult#

A single observation result from a tool call.

source_call_id: Option<String>#: Correlation ID linking to the originating tool call.

content: Json#: The tool’s output content.

struct AtifStep#

A single step in an ATIF trajectory.

step_id: usize#: 1-based ordinal step ID.

source: String#: Source of the step: "system", "user", or "agent".

message: Json#: The message content (string or array of content parts).

timestamp: Option<String>#: ISO 8601 timestamp.

model_name: Option<String>#: LLM model name, if applicable.

reasoning_effort: Option<Json>#: Qualitative or quantitative measure of reasoning effort.

reasoning_content: Option<String>#: The agent’s explicit internal reasoning.

tool_calls: Option<Vec<AtifToolCall>>#: Tool calls made by the agent in this step.

observation: Option<AtifObservation>#: Observation (tool results) for this step.

metrics: Option<AtifMetrics>#: Token usage and cost metrics.

is_copied_context: Option<bool>#: Whether this step was copied from a previous trajectory for context.

extra: Option<Json>#: Extra metadata.

struct AtifStepExtra#

Lineage payload serialized into ATIF Step.extra.

tool_ancestry[i] and tool_invocations[i] align by index with Step.tool_calls[i].

ancestry: AtifAncestry#: Step-level callable lineage.

invocation: Option<AtifInvocationInfo>#: Step-level invocation timing.

tool_ancestry: Vec<AtifAncestry>#: Per-tool callable lineage, aligned with tool_calls.

tool_invocations: Option<Vec<AtifInvocationInfo>>#: Per-tool invocation timing, aligned with tool_calls.

struct AtifToolCall#

A tool call made by the agent.

tool_call_id: String#: Correlation ID linking this call to its observation result.

function_name: String#: Name of the tool/function called.

arguments: Json#: Arguments passed to the tool.

struct AtifTrajectory#

A complete ATIF trajectory.

schema_version: String#: Schema version (e.g., "ATIF-v1.6").

session_id: String#: Unique session identifier.

agent: AtifAgentInfo#: Information about the agent.

steps: Vec<AtifStep>#: Ordered list of trajectory steps.

notes: Option<String>#: Custom information, design notes, or explanations.

final_metrics: Option<AtifFinalMetrics>#: Aggregate metrics for the entire trajectory.

continued_trajectory_ref: Option<String>#: Reference to the continuation trajectory file if continued elsewhere.

extra: Option<Json>#: Extra metadata.

mod atif#

`mod atif`#