atif 1.7.0a0__tar.gz

atif-1.7.0a0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

atif-1.7.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atif-1.7.0a0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: atif
+Version: 1.7.0a0
+Summary: Pydantic models for the Agent Trajectory Interchange Format (ATIF v1.7).
+Project-URL: Homepage, https://github.com/bolu61/python-atif
+Project-URL: Repository, https://github.com/bolu61/python-atif
+Project-URL: Issues, https://github.com/bolu61/python-atif/issues
+Project-URL: Specification, https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md
+Author-email: bolu61 <bolu61@zjc.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,atif,harbor,llm,pydantic,schema,trajectory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.9
+Description-Content-Type: text/markdown
+
+# atif
+
+Pydantic models for the [Agent Trajectory Interchange Format (ATIF)][spec], a
+standardized JSON schema for logging the complete interaction history of
+autonomous LLM agents — user messages, agent responses, tool calls, observations,
+metrics, and embedded subagent trajectories. Implements ATIF v1.7.
+
+## Install
+
+```bash
+pip install atif
+```
+
+## Usage
+
+```python
+from atif import Trajectory
+
+data = {
+    "schema_version": "ATIF-v1.7",
+    "agent": {"name": "my-agent", "version": "1.0.0", "model_name": "claude-sonnet-4-6"},
+    "steps": [
+        {"step_id": 1, "source": "user", "message": "What time is it?"},
+        {
+            "step_id": 2,
+            "source": "agent",
+            "message": "Let me check.",
+            "tool_calls": [
+                {"tool_call_id": "c1", "function_name": "now", "arguments": {}}
+            ],
+            "observation": {
+                "results": [{"source_call_id": "c1", "content": "2026-05-16T12:00:00Z"}]
+            },
+            "metrics": {"prompt_tokens": 120, "completion_tokens": 18},
+        },
+    ],
+}
+
+trajectory = Trajectory.model_validate(data)
+print(trajectory.steps[1].tool_calls[0].function_name)  # "now"
+print(trajectory.to_json_dict(exclude_none=True))
+```
+
+Validation enforces the ATIF rules: sequential `step_id`s, ISO 8601 timestamps,
+agent-only fields gated on `source == "agent"`, tool-call / observation
+correlation, embedded-subagent `trajectory_id` uniqueness, and
+`ContentPart` text/image XOR.
+
+## Versioning
+
+`atif`'s `MAJOR.MINOR` tracks the ATIF RFC version it implements
+(`1.7.x` ⇔ ATIF v1.7); `PATCH` is reserved for library-only fixes. Because
+the ATIF RFC occasionally introduces breaking changes on a MINOR bump
+(e.g. v1.7's `SubagentTrajectoryRef` resolution change), a MINOR bump of
+this library may be breaking too — pin to `atif~=1.7.0` if you need to
+stay on a single ATIF version.
+
+[spec]: https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md

atif-1.7.0a0/README.md

@@ -0,0 +1,58 @@
+# atif
+
+Pydantic models for the [Agent Trajectory Interchange Format (ATIF)][spec], a
+standardized JSON schema for logging the complete interaction history of
+autonomous LLM agents — user messages, agent responses, tool calls, observations,
+metrics, and embedded subagent trajectories. Implements ATIF v1.7.
+
+## Install
+
+```bash
+pip install atif
+```
+
+## Usage
+
+```python
+from atif import Trajectory
+
+data = {
+    "schema_version": "ATIF-v1.7",
+    "agent": {"name": "my-agent", "version": "1.0.0", "model_name": "claude-sonnet-4-6"},
+    "steps": [
+        {"step_id": 1, "source": "user", "message": "What time is it?"},
+        {
+            "step_id": 2,
+            "source": "agent",
+            "message": "Let me check.",
+            "tool_calls": [
+                {"tool_call_id": "c1", "function_name": "now", "arguments": {}}
+            ],
+            "observation": {
+                "results": [{"source_call_id": "c1", "content": "2026-05-16T12:00:00Z"}]
+            },
+            "metrics": {"prompt_tokens": 120, "completion_tokens": 18},
+        },
+    ],
+}
+
+trajectory = Trajectory.model_validate(data)
+print(trajectory.steps[1].tool_calls[0].function_name)  # "now"
+print(trajectory.to_json_dict(exclude_none=True))
+```
+
+Validation enforces the ATIF rules: sequential `step_id`s, ISO 8601 timestamps,
+agent-only fields gated on `source == "agent"`, tool-call / observation
+correlation, embedded-subagent `trajectory_id` uniqueness, and
+`ContentPart` text/image XOR.
+
+## Versioning
+
+`atif`'s `MAJOR.MINOR` tracks the ATIF RFC version it implements
+(`1.7.x` ⇔ ATIF v1.7); `PATCH` is reserved for library-only fixes. Because
+the ATIF RFC occasionally introduces breaking changes on a MINOR bump
+(e.g. v1.7's `SubagentTrajectoryRef` resolution change), a MINOR bump of
+this library may be breaking too — pin to `atif~=1.7.0` if you need to
+stay on a single ATIF version.
+
+[spec]: https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md

atif-1.7.0a0/atif/__init__.py

@@ -0,0 +1,33 @@
+"""Pydantic models for the Agent Trajectory Interchange Format (ATIF v1.7).
+
+Reference: https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md
+"""
+
+from .agent import Agent
+from .content import ContentPart, ContentPartType, ImageMediaType, ImageSource
+from .final_metrics import FinalMetrics
+from .metrics import Metrics
+from .observation import Observation
+from .observation_result import ObservationResult
+from .step import ReasoningEffort, Step, StepSource
+from .subagent_trajectory_ref import SubagentTrajectoryRef
+from .tool_call import ToolCall
+from .trajectory import Trajectory
+
+__all__ = [
+    "Agent",
+    "ContentPart",
+    "ContentPartType",
+    "FinalMetrics",
+    "ImageMediaType",
+    "ImageSource",
+    "Metrics",
+    "Observation",
+    "ObservationResult",
+    "ReasoningEffort",
+    "Step",
+    "StepSource",
+    "SubagentTrajectoryRef",
+    "ToolCall",
+    "Trajectory",
+]

atif-1.7.0a0/atif/agent.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Agent(BaseModel):
+    """Agent system that produced the trajectory (ATIF `AgentSchema`)."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    name: str = Field(..., description="Name of the agent system, e.g. 'openhands'.")
+    version: str = Field(..., description="Version identifier of the agent system.")
+    model_name: str | None = Field(
+        default=None,
+        description="Default LLM model for this trajectory; step-level model_name overrides.",
+    )
+    tool_definitions: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="OpenAI-style function/tool definitions available to the agent.",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom agent configuration not covered by the core schema.",
+    )

atif-1.7.0a0/atif/content.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+ImageMediaType = Literal["image/jpeg", "image/png", "image/gif", "image/webp"]
+ContentPartType = Literal["text", "image"]
+
+
+class ImageSource(BaseModel):
+    """Reference to an image stored alongside the trajectory (ATIF v1.6+)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    media_type: ImageMediaType = Field(..., description="MIME type of the image.")
+    path: str = Field(
+        ...,
+        description="Relative/absolute file path or URL pointing at the image.",
+    )
+
+
+class ContentPart(BaseModel):
+    """One element of a multimodal `message` or `content` array (ATIF v1.6+)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: ContentPartType
+    text: str | None = None
+    source: ImageSource | None = None
+
+    @model_validator(mode="after")
+    def _check_payload(self) -> "ContentPart":
+        if self.type == "text":
+            if self.text is None:
+                raise ValueError("ContentPart of type 'text' requires `text`.")
+            if self.source is not None:
+                raise ValueError("ContentPart of type 'text' must omit `source`.")
+        else:
+            if self.source is None:
+                raise ValueError("ContentPart of type 'image' requires `source`.")
+            if self.text is not None:
+                raise ValueError("ContentPart of type 'image' must omit `text`.")
+        return self

atif-1.7.0a0/atif/final_metrics.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FinalMetrics(BaseModel):
+    """Aggregate metrics for a whole trajectory (ATIF `FinalMetricsSchema`)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    total_prompt_tokens: int | None = Field(
+        default=None,
+        description="Sum of all `prompt_tokens` across steps (cached + non-cached).",
+    )
+    total_completion_tokens: int | None = Field(
+        default=None, description="Sum of all `completion_tokens` across steps."
+    )
+    total_cached_tokens: int | None = Field(
+        default=None,
+        description="Sum of all `cached_tokens` (subset of `total_prompt_tokens`).",
+    )
+    total_cost_usd: float | None = Field(
+        default=None, description="Total monetary cost across the trajectory in USD."
+    )
+    total_steps: int | None = Field(
+        default=None,
+        description=(
+            "Total step count. MAY diverge from `len(steps)` when explained in `notes`."
+        ),
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None, description="Custom aggregate metrics."
+    )

atif-1.7.0a0/atif/metrics.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Metrics(BaseModel):
+    """Per-step LLM metrics (ATIF `MetricsSchema`)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    prompt_tokens: int | None = Field(
+        default=None,
+        description=(
+            "All input tokens for this turn, including both cached and non-cached. "
+            "`cached_tokens` is a subset of this count."
+        ),
+    )
+    completion_tokens: int | None = Field(
+        default=None,
+        description="Tokens generated by the LLM response (reasoning + tool calls).",
+    )
+    cached_tokens: int | None = Field(
+        default=None,
+        description="Subset of `prompt_tokens` served from prompt cache.",
+    )
+    cost_usd: float | None = Field(
+        default=None, description="Monetary cost of this step in USD."
+    )
+    prompt_token_ids: list[int] | None = Field(
+        default=None,
+        description="Integer token IDs for the prompt (v1.4+).",
+    )
+    completion_token_ids: list[int] | None = Field(
+        default=None,
+        description="Integer token IDs for the completion (v1.3+).",
+    )
+    logprobs: list[float] | None = Field(
+        default=None,
+        description="Per-completion-token log probabilities; aligns with `completion_token_ids`.",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Provider-specific or experimental metrics (e.g. reasoning_tokens).",
+    )

atif-1.7.0a0/atif/observation.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .observation_result import ObservationResult
+
+
+class Observation(BaseModel):
+    """Environment/system feedback after a step (ATIF `ObservationSchema`)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    results: list[ObservationResult] = Field(
+        ...,
+        description="One entry per tool call, action, or system-event result.",
+    )

atif-1.7.0a0/atif/observation_result.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .content import ContentPart
+from .subagent_trajectory_ref import SubagentTrajectoryRef
+
+
+class ObservationResult(BaseModel):
+    """Single observation result (ATIF `ObservationResultSchema`).
+
+    `content` MAY be omitted when `subagent_trajectory_ref` is present.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    source_call_id: str | None = Field(
+        default=None,
+        description=(
+            "The `ToolCall.tool_call_id` this result corresponds to. "
+            "If null/omitted the result comes from a non-tool action or system event."
+        ),
+    )
+    content: str | list[ContentPart] | None = Field(
+        default=None,
+        description="Tool/action output; string or multimodal `ContentPart` array (v1.6+).",
+    )
+    subagent_trajectory_ref: list[SubagentTrajectoryRef] | None = Field(
+        default=None,
+        description="Refs to delegated subagent trajectories; use a singleton array for one.",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom result-level metadata (e.g. retrieval_score, source_doc_id).",
+    )

atif-1.7.0a0/atif/step.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from .content import ContentPart
+from .metrics import Metrics
+from .observation import Observation
+from .tool_call import ToolCall
+
+StepSource = Literal["system", "user", "agent"]
+ReasoningEffort = str | float
+
+
+class Step(BaseModel):
+    """A single turn in a trajectory (ATIF `StepObject`).
+
+    Represents a system prompt, a user message, or one complete agent turn
+    (LLM inference, action execution, observation receipt).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    step_id: int = Field(..., ge=1, description="Ordinal index of the turn (starting at 1).")
+    timestamp: str | None = Field(
+        default=None,
+        description="ISO 8601 timestamp, e.g. '2025-10-16T14:30:00Z'.",
+    )
+    source: StepSource = Field(..., description="Originator of this step.")
+    model_name: str | None = Field(
+        default=None,
+        description="Specific LLM used. Agent-only; falls back to `Trajectory.agent.model_name`.",
+    )
+    reasoning_effort: ReasoningEffort | None = Field(
+        default=None,
+        description="Qualitative/quantitative effort score. Agent-only.",
+    )
+    message: str | list[ContentPart] = Field(
+        ...,
+        description=(
+            "Dialogue message. String for text, or `ContentPart` array for multimodal (v1.6+)."
+        ),
+    )
+    reasoning_content: str | None = Field(
+        default=None,
+        description="Explicit internal reasoning. Agent-only.",
+    )
+    tool_calls: list[ToolCall] | None = Field(
+        default=None,
+        description="Structured actions for this turn. Agent-only.",
+    )
+    observation: Observation | None = Field(
+        default=None,
+        description=(
+            "Environment / system feedback. For agent steps, results from tool calls or "
+            "non-tool actions. For system steps, results from infrastructure events."
+        ),
+    )
+    metrics: Metrics | None = Field(
+        default=None, description="LLM operational/confidence data. Agent-only."
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None, description="Custom step-level metadata."
+    )
+    llm_call_count: int | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Number of LLM inferences for this step. `0` on an agent step signals a "
+            "deterministic (non-LLM) dispatch (metrics and reasoning_content MUST be absent). "
+            "`>1` means metrics are aggregated."
+        ),
+    )
+    is_copied_context: bool | None = Field(
+        default=None,
+        description=(
+            "True if this step was copied from a prior trajectory for context. "
+            "Consumers MUST filter such steps out of SFT training data."
+        ),
+    )
+
+    @field_validator("timestamp")
+    @classmethod
+    def _validate_timestamp(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        try:
+            datetime.fromisoformat(v.replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise ValueError(f"timestamp must be ISO 8601, got {v!r}") from exc
+        return v
+
+    @model_validator(mode="after")
+    def _check_source_constraints(self) -> "Step":
+        agent_only = {
+            "model_name": self.model_name,
+            "reasoning_effort": self.reasoning_effort,
+            "reasoning_content": self.reasoning_content,
+            "tool_calls": self.tool_calls,
+            "metrics": self.metrics,
+        }
+        if self.source != "agent":
+            for name, value in agent_only.items():
+                if value is not None:
+                    raise ValueError(
+                        f"Field `{name}` is only valid on `source='agent'` steps "
+                        f"(this step has source={self.source!r})."
+                    )
+
+        if self.source == "agent" and self.llm_call_count == 0:
+            if self.metrics is not None:
+                raise ValueError(
+                    "When `llm_call_count == 0` on an agent step, `metrics` MUST be absent."
+                )
+            if self.reasoning_content is not None:
+                raise ValueError(
+                    "When `llm_call_count == 0` on an agent step, "
+                    "`reasoning_content` MUST be absent."
+                )
+
+        if self.observation is not None and self.tool_calls is not None:
+            tool_call_ids = {tc.tool_call_id for tc in self.tool_calls}
+            for result in self.observation.results:
+                if (
+                    result.source_call_id is not None
+                    and result.source_call_id not in tool_call_ids
+                ):
+                    raise ValueError(
+                        f"observation.results[*].source_call_id={result.source_call_id!r} "
+                        f"does not match any tool_call in step {self.step_id}."
+                    )
+        return self

atif-1.7.0a0/atif/subagent_trajectory_ref.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class SubagentTrajectoryRef(BaseModel):
+    """Reference to a delegated subagent trajectory (ATIF `SubagentTrajectoryRefSchema`).
+
+    Two resolution mechanisms (at least one MUST be set):
+    - Embedded: `trajectory_id` matches an entry in the parent's `subagent_trajectories`.
+    - File-ref: `trajectory_path` points at an external trajectory file.
+
+    `session_id` is run-scoped and **informational only** — not a valid resolution key.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    trajectory_id: str | None = Field(
+        default=None,
+        description="Canonical id for embedded refs; matches `Trajectory.trajectory_id`.",
+    )
+    trajectory_path: str | None = Field(
+        default=None,
+        description="External location of the subagent trajectory (path, URL, DB ref).",
+    )
+    session_id: str | None = Field(
+        default=None,
+        description="Informational run identity; NOT a valid resolution key.",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom metadata about the subagent execution.",
+    )
+
+    @model_validator(mode="after")
+    def _require_resolvable(self) -> "SubagentTrajectoryRef":
+        if self.trajectory_id is None and self.trajectory_path is None:
+            raise ValueError(
+                "SubagentTrajectoryRef must set at least one of "
+                "`trajectory_id` (embedded) or `trajectory_path` (file-ref)."
+            )
+        return self

atif-1.7.0a0/atif/tool_call.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ToolCall(BaseModel):
+    """A single function/tool invocation in an agent step (ATIF `ToolCallSchema`)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    tool_call_id: str = Field(
+        ...,
+        description="Unique identifier; correlated with `ObservationResult.source_call_id`.",
+    )
+    function_name: str = Field(..., description="Name of the function/tool invoked.")
+    arguments: dict[str, Any] = Field(
+        ...,
+        description="JSON object of arguments; MAY be empty (`{}`) when no args are needed.",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom tool-call metadata (e.g. timeout, retry count, tool version).",
+    )

atif-1.7.0a0/atif/trajectory.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .agent import Agent
+from .content import ContentPart
+from .final_metrics import FinalMetrics
+from .step import Step
+
+
+class Trajectory(BaseModel):
+    """Root ATIF trajectory document (ATIF `Trajectory`).
+
+    A trajectory is a sequence of interactions between a user and an agent,
+    including the agent's internal reasoning, actions, and observations.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: str = Field(
+        ...,
+        description="ATIF compatibility tag, e.g. 'ATIF-v1.7'.",
+    )
+    session_id: str | None = Field(
+        default=None,
+        description=(
+            "Run-scoped identifier. MAY be shared across siblings or continuation segments. "
+            "Not a valid resolution key for subagent refs."
+        ),
+    )
+    trajectory_id: str | None = Field(
+        default=None,
+        description=(
+            "Per-document identifier (v1.7+). REQUIRED on embedded subagents and unique "
+            "within a parent's `subagent_trajectories`."
+        ),
+    )
+    agent: Agent = Field(..., description="Agent system configuration.")
+    steps: list[Step] = Field(
+        ..., description="Complete interaction history in turn order."
+    )
+    notes: str | None = Field(
+        default=None,
+        description="Developer notes / explanations for format discrepancies.",
+    )
+    final_metrics: FinalMetrics | None = Field(
+        default=None, description="Aggregate metrics for the whole trajectory."
+    )
+    continued_trajectory_ref: str | None = Field(
+        default=None,
+        description="Pointer to a continuation trajectory file (e.g. post-summarization).",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None, description="Custom root-level metadata."
+    )
+    subagent_trajectories: list["Trajectory"] | None = Field(
+        default=None,
+        description=(
+            "Embedded subagent trajectories (v1.7+). Each entry MUST set `trajectory_id` "
+            "and ids MUST be unique within this array."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _validate_steps_and_subagents(self) -> "Trajectory":
+        for index, step in enumerate(self.steps, start=1):
+            if step.step_id != index:
+                raise ValueError(
+                    f"steps[{index - 1}].step_id={step.step_id} is not sequential; "
+                    f"expected {index}."
+                )
+
+        if self.subagent_trajectories:
+            seen: set[str] = set()
+            for i, sub in enumerate(self.subagent_trajectories):
+                if sub.trajectory_id is None:
+                    raise ValueError(
+                        f"subagent_trajectories[{i}] must set `trajectory_id` "
+                        "when embedded in a parent trajectory."
+                    )
+                if sub.trajectory_id in seen:
+                    raise ValueError(
+                        f"Duplicate trajectory_id={sub.trajectory_id!r} in "
+                        "`subagent_trajectories`."
+                    )
+                seen.add(sub.trajectory_id)
+        return self
+
+    def has_multimodal_content(self) -> bool:
+        """True if any step message or observation content uses `ContentPart` arrays."""
+        for step in self.steps:
+            if isinstance(step.message, list):
+                return True
+            if step.observation is not None:
+                for result in step.observation.results:
+                    if isinstance(result.content, list):
+                        return True
+        if self.subagent_trajectories:
+            return any(s.has_multimodal_content() for s in self.subagent_trajectories)
+        return False
+
+    def to_json_dict(self, exclude_none: bool = True) -> dict[str, Any]:
+        """Dump to a JSON-serialisable dict, dropping unset fields by default."""
+        return self.model_dump(mode="json", exclude_none=exclude_none)
+
+
+Trajectory.model_rebuild()
+# Re-export so callers can `from atif.trajectory import ContentPart` if they want.
+__all__ = ["Trajectory", "ContentPart"]

atif-1.7.0a0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "atif"
+dynamic = ["version"]
+description = "Pydantic models for the Agent Trajectory Interchange Format (ATIF v1.7)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "bolu61", email = "bolu61@zjc.dev" },
+]
+keywords = ["atif", "agent", "trajectory", "llm", "pydantic", "harbor", "schema"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/bolu61/python-atif"
+Repository = "https://github.com/bolu61/python-atif"
+Issues = "https://github.com/bolu61/python-atif/issues"
+Specification = "https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["atif"]
+
+[tool.hatch.build.targets.sdist]
+include = ["atif", "README.md", "LICENSE", "pyproject.toml"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--cov=atif", "--cov-report=term-missing"]
+
+[tool.coverage.run]
+source = ["atif"]
+branch = true
+omit = ["atif/_version.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]