@evolvingmachines/evolve 0.0.55-project-sable.20260916.db0bc0bb

package/spec/atif/trajectory.schema.json

@@ -0,0 +1,865 @@
+{
+  "$comment": "GENERATED \u2014 do not hand-edit. Emitted by pydantic's model_json_schema() from Harbor's Trajectory model (src/harbor/models/trajectories/), Harbor commit 4698544ea9d5ee95d01b05aeaa9ccbd161d5a7f6. Regenerate per spec/atif/README.md.",
+  "$defs": {
+    "Agent": {
+      "additionalProperties": false,
+      "description": "Agent configuration.",
+      "properties": {
+        "extra": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Custom agent configuration details",
+          "title": "Extra"
+        },
+        "model_name": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Default LLM model used for this trajectory",
+          "title": "Model Name"
+        },
+        "name": {
+          "description": "The name of the agent system",
+          "title": "Name",
+          "type": "string"
+        },
+        "tool_definitions": {
+          "anyOf": [
+            {
+              "items": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Array of tool/function definitions available to the agent. Each element follows OpenAI's function calling schema.",
+          "title": "Tool Definitions"
+        },
+        "version": {
+          "description": "The version identifier of the agent system",
+          "title": "Version",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "version"
+      ],
+      "title": "Agent",
+      "type": "object"
+    },
+    "ContentPart": {
+      "additionalProperties": false,
+      "description": "A single content part within a multimodal message.\n\nUsed when a message or observation contains mixed content types (text and images).\nFor text-only content, a plain string can still be used instead of a ContentPart array.",
+      "properties": {
+        "source": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/ImageSource"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Image source (file reference). Required when type='image'."
+        },
+        "text": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Text content. Required when type='text'.",
+          "title": "Text"
+        },
+        "type": {
+          "description": "The type of content",
+          "enum": [
+            "text",
+            "image"
+          ],
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "title": "ContentPart",
+      "type": "object"
+    },
+    "FinalMetrics": {
+      "additionalProperties": false,
+      "description": "Aggregate statistics for the entire trajectory.",
+      "properties": {
+        "extra": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Custom aggregate metrics",
+          "title": "Extra"
+        },
+        "total_cached_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Sum of all cached tokens across all steps",
+          "title": "Total Cached Tokens"
+        },
+        "total_completion_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Sum of all completion tokens across all steps",
+          "title": "Total Completion Tokens"
+        },
+        "total_cost_usd": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Total real monetary cost for the entire trajectory, including cost for subagents, if any",
+          "title": "Total Cost Usd"
+        },
+        "total_prompt_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Sum of all prompt tokens across all steps, including cached tokens",
+          "title": "Total Prompt Tokens"
+        },
+        "total_steps": {
+          "anyOf": [
+            {
+              "minimum": 0,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Total number of steps. If not equivalent to the number of steps in the trajectory, must be documented in the root-level notes field.",
+          "title": "Total Steps"
+        }
+      },
+      "title": "FinalMetrics",
+      "type": "object"
+    },
+    "ImageSource": {
+      "additionalProperties": false,
+      "description": "Image source specification for images stored as files or at remote URLs.",
+      "properties": {
+        "media_type": {
+          "description": "MIME type of the image",
+          "enum": [
+            "image/jpeg",
+            "image/png",
+            "image/gif",
+            "image/webp"
+          ],
+          "title": "Media Type",
+          "type": "string"
+        },
+        "path": {
+          "description": "Location of the image. Can be a relative or absolute file path, or a URL.",
+          "title": "Path",
+          "type": "string"
+        }
+      },
+      "required": [
+        "media_type",
+        "path"
+      ],
+      "title": "ImageSource",
+      "type": "object"
+    },
+    "Metrics": {
+      "additionalProperties": false,
+      "description": "LLM operational and confidence data.",
+      "properties": {
+        "cached_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Subset of prompt_tokens that were cache hits",
+          "title": "Cached Tokens"
+        },
+        "completion_token_ids": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "integer"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Token IDs for completion (response) tokens, enabling RL training without retokenization drift",
+          "title": "Completion Token Ids"
+        },
+        "completion_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Total tokens generated by the LLM response",
+          "title": "Completion Tokens"
+        },
+        "cost_usd": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Monetary cost of the API call in USD",
+          "title": "Cost Usd"
+        },
+        "extra": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Other metrics",
+          "title": "Extra"
+        },
+        "logprobs": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "number"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Log probability assigned to each generated token",
+          "title": "Logprobs"
+        },
+        "prompt_token_ids": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "integer"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Token IDs for prompt (input) tokens sent to the LLM, including chat history (if applicable)",
+          "title": "Prompt Token Ids"
+        },
+        "prompt_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Total input tokens including cached and non-cached",
+          "title": "Prompt Tokens"
+        }
+      },
+      "title": "Metrics",
+      "type": "object"
+    },
+    "Observation": {
+      "additionalProperties": false,
+      "description": "Environment feedback/result after actions or system events.",
+      "properties": {
+        "results": {
+          "description": "Array of result objects from tool calls or actions",
+          "items": {
+            "$ref": "#/$defs/ObservationResult"
+          },
+          "title": "Results",
+          "type": "array"
+        }
+      },
+      "required": [
+        "results"
+      ],
+      "title": "Observation",
+      "type": "object"
+    },
+    "ObservationResult": {
+      "additionalProperties": false,
+      "description": "A single result within an observation.",
+      "properties": {
+        "content": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "items": {
+                "$ref": "#/$defs/ContentPart"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The output or result from the tool execution. String for text-only content, or array of ContentPart for multimodal content (added in ATIF-v1.6).",
+          "title": "Content"
+        },
+        "extra": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Custom observation-result-level metadata (e.g., confidence score, retrieval score, source document ID). Added in ATIF-v1.7.",
+          "title": "Extra"
+        },
+        "source_call_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The `tool_call_id` from the _tool_calls_ array in _StepObject_ that this result corresponds to. If null or omitted, the result comes from an action that doesn't use the standard tool calling format (e.g., agent actions without tool calls or system-initiated operations).",
+          "title": "Source Call Id"
+        },
+        "subagent_trajectory_ref": {
+          "anyOf": [
+            {
+              "items": {
+                "$ref": "#/$defs/SubagentTrajectoryRef"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Array of references to delegated subagent trajectories",
+          "title": "Subagent Trajectory Ref"
+        }
+      },
+      "title": "ObservationResult",
+      "type": "object"
+    },
+    "Step": {
+      "additionalProperties": false,
+      "description": "A single step in the trajectory.",
+      "properties": {
+        "extra": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Custom step-level metadata",
+          "title": "Extra"
+        },
+        "is_copied_context": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Indicates whether this step was copied from a previous trajectory for context (e.g., during continuation after summarization). Steps marked as copied context should not be included in training data as they represent previously-trained interactions. Added in ATIF-v1.5.",
+          "title": "Is Copied Context"
+        },
+        "llm_call_count": {
+          "anyOf": [
+            {
+              "minimum": 0,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Number of LLM inferences this step represents. When >1, metrics are aggregated across multiple LLM calls. When 1, the step represents exactly one inference. When 0 on a `source: 'agent'` step, the step represents a deterministic (non-LLM) dispatch; `metrics` and `reasoning_content` MUST be absent in that case. When null, the producer did not track this (backward-compatible default). Added in ATIF-v1.7.",
+          "title": "Llm Call Count"
+        },
+        "message": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "items": {
+                "$ref": "#/$defs/ContentPart"
+              },
+              "type": "array"
+            }
+          ],
+          "description": "The dialogue message. String for text-only content, or array of ContentPart for multimodal content (added in ATIF-v1.6).",
+          "title": "Message"
+        },
+        "metrics": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Metrics"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "LLM operational and confidence data for this step"
+        },
+        "model_name": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The specific LLM model used for this turn. Omission implies the model defined in the root-level agent config.",
+          "title": "Model Name"
+        },
+        "observation": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Observation"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Environment feedback/result after actions or system events"
+        },
+        "reasoning_content": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "The agent's explicit internal reasoning",
+          "title": "Reasoning Content"
+        },
+        "reasoning_effort": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Qualitative or quantitative measure of effort",
+          "title": "Reasoning Effort"
+        },
+        "source": {
+          "description": "The originator of this step",
+          "enum": [
+            "system",
+            "user",
+            "agent"
+          ],
+          "title": "Source",
+          "type": "string"
+        },
+        "step_id": {
+          "description": "Ordinal index of the turn (starting from 1)",
+          "minimum": 1,
+          "title": "Step Id",
+          "type": "integer"
+        },
+        "timestamp": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "ISO 8601 timestamp indicating when this step occurred",
+          "title": "Timestamp"
+        },
+        "tool_calls": {
+          "anyOf": [
+            {
+              "items": {
+                "$ref": "#/$defs/ToolCall"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Array of structured objects for the agent's actions",
+          "title": "Tool Calls"
+        }
+      },
+      "required": [
+        "step_id",
+        "source",
+        "message"
+      ],
+      "title": "Step",
+      "type": "object"
+    },
+    "SubagentTrajectoryRef": {
+      "additionalProperties": false,
+      "description": "Reference to a delegated subagent trajectory.\n\nA subagent reference is resolved by one of two mechanisms:\n\n1. **Embedded form** \u2014 set `trajectory_id` to match the\n   `Trajectory.trajectory_id` of an entry in the parent's\n   `subagent_trajectories` array.\n2. **File-ref form** \u2014 set `trajectory_path` to the location\n   (file path, S3 URL, etc.) of an external trajectory file.\n\nThese two mechanisms are the only resolution keys. `session_id`, when\npresent on the ref, is **informational only**: it records the run\nidentity of the delegated subagent for debug / correlation / cross-\ntrajectory search purposes, and MUST NOT be used as a matching key\n(it is run-scoped and MAY collide across siblings \u2014 see\n`Trajectory.session_id`). A ref therefore MUST set at least one of\n`trajectory_id` or `trajectory_path`; `session_id` alone is not a\nresolvable reference.",
+      "properties": {
+        "extra": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Custom metadata about the subagent execution",
+          "title": "Extra"
+        },
+        "session_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Run identity of the delegated subagent trajectory. Informational only: recorded so consumers can correlate this ref back to the subagent's run for debug / search / display purposes. Run-scoped (see `Trajectory.session_id`) and therefore NOT a valid resolution key \u2014 consumers MUST resolve via `trajectory_id` (embedded) or `trajectory_path` (external file).",
+          "title": "Session Id"
+        },
+        "trajectory_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Canonical identifier of the delegated subagent trajectory. Matches `Trajectory.trajectory_id` of an entry in the parent's `subagent_trajectories` array and is the resolution key for embedded references. Added in ATIF-v1.7 to provide a document-unique matching key without overloading `session_id`.",
+          "title": "Trajectory Id"
+        },
+        "trajectory_path": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Location of the complete subagent trajectory as an external file (file path, S3 URL, database reference, etc.). Resolution key for file-ref references. When both `trajectory_id` and `trajectory_path` are set, consumers MAY choose either; typically `trajectory_id` is preferred when the embedded trajectory is available in-memory.",
+          "title": "Trajectory Path"
+        }
+      },
+      "title": "SubagentTrajectoryRef",
+      "type": "object"
+    },
+    "ToolCall": {
+      "additionalProperties": false,
+      "description": "A tool call within a step.",
+      "properties": {
+        "arguments": {
+          "additionalProperties": true,
+          "description": "Arguments passed to the function (can be empty dict)",
+          "title": "Arguments",
+          "type": "object"
+        },
+        "extra": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Custom tool-call-level metadata (e.g., timeout, retry count, tool version). Added in ATIF-v1.7.",
+          "title": "Extra"
+        },
+        "function_name": {
+          "description": "The name of the function or tool being invoked",
+          "title": "Function Name",
+          "type": "string"
+        },
+        "tool_call_id": {
+          "description": "Unique identifier for this specific tool call",
+          "title": "Tool Call Id",
+          "type": "string"
+        }
+      },
+      "required": [
+        "tool_call_id",
+        "function_name",
+        "arguments"
+      ],
+      "title": "ToolCall",
+      "type": "object"
+    },
+    "Trajectory": {
+      "additionalProperties": false,
+      "description": "Agent Trajectory in ATIF (Agent Trajectory Interchange Format).",
+      "properties": {
+        "agent": {
+          "$ref": "#/$defs/Agent",
+          "description": "Object specifying the agent configuration"
+        },
+        "continued_trajectory_ref": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Reference to the continuation trajectory file if this trajectory is continued in another file",
+          "title": "Continued Trajectory Ref"
+        },
+        "extra": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Custom root-level metadata",
+          "title": "Extra"
+        },
+        "final_metrics": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/FinalMetrics"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Summary metrics for the entire trajectory"
+        },
+        "notes": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Custom information, design notes, or explanations",
+          "title": "Notes"
+        },
+        "schema_version": {
+          "default": "ATIF-v1.7",
+          "description": "String defining ATIF compatibility",
+          "enum": [
+            "ATIF-v1.0",
+            "ATIF-v1.1",
+            "ATIF-v1.2",
+            "ATIF-v1.3",
+            "ATIF-v1.4",
+            "ATIF-v1.5",
+            "ATIF-v1.6",
+            "ATIF-v1.7"
+          ],
+          "title": "Schema Version",
+          "type": "string"
+        },
+        "session_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Identifier for the agent run this trajectory belongs to. Scoped to the run, NOT to an individual trajectory document: multiple Trajectory objects MAY share the same `session_id` when they represent the same logical run (e.g., a parent trajectory and its embedded subagents, or a trajectory and its continuation segments linked via `continued_trajectory_ref`). Therefore `session_id`s within a parent's `subagent_trajectories` array are NOT required to be unique. Use `trajectory_id` when a per-trajectory-document unique identifier is required (e.g., for `SubagentTrajectoryRef` resolution). Optional since ATIF-v1.7; producers SHOULD set this on root trajectories for run-level traceability, and MAY omit it on embedded subagents that inherit the parent's run identity.",
+          "title": "Session Id"
+        },
+        "steps": {
+          "description": "Array of step objects representing the complete interaction history",
+          "items": {
+            "$ref": "#/$defs/Step"
+          },
+          "minItems": 1,
+          "title": "Steps",
+          "type": "array"
+        },
+        "subagent_trajectories": {
+          "anyOf": [
+            {
+              "items": {
+                "$ref": "#/$defs/Trajectory"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Array of embedded subagent trajectories. Each element is a complete, independently-valid ATIF Trajectory with its own schema_version, agent, and step_id sequence starting at 1. Enables single-file storage of multi-agent workflows: when a SubagentTrajectoryRef.trajectory_path is null, consumers resolve the reference by matching SubagentTrajectoryRef.trajectory_id against Trajectory.trajectory_id of entries in this array. Uniqueness rules: every embedded subagent MUST set `trajectory_id`, and `trajectory_id`s within this array MUST be unique. `session_id`, by contrast, is run-scoped and MAY collide across siblings (or match the parent) when all trajectories belong to the same logical run; embedded subagents MAY also omit `session_id` entirely to inherit the parent's run identity. Added in ATIF-v1.7.",
+          "title": "Subagent Trajectories"
+        },
+        "trajectory_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Canonical per-trajectory-document identifier, distinct from `session_id`. Unlike `session_id` (which is run-scoped and MAY be shared), `trajectory_id` uniquely identifies THIS trajectory object. Used to resolve `SubagentTrajectoryRef` entries against the root's `subagent_trajectories` array without overloading `session_id`'s run-scoped semantics. Optional on standalone trajectories, but REQUIRED on any trajectory embedded in a parent's `subagent_trajectories` array. `trajectory_id`s within a single parent's `subagent_trajectories` array MUST be unique. Added in ATIF-v1.7.",
+          "title": "Trajectory Id"
+        }
+      },
+      "required": [
+        "agent",
+        "steps"
+      ],
+      "title": "Trajectory",
+      "type": "object"
+    }
+  },
+  "$ref": "#/$defs/Trajectory",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ATIF Trajectory"
+}