atif-sql 0.2.0__py3-none-any.whl

atif_converter/domain/atif/step.py

@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/step.py
+# (Apache-2.0, Copyright the Harbor authors). Byte for byte upstream apart
+# from these header lines and the import path, which reads
+# atif_converter.domain.atif where upstream reads harbor.models.trajectories.
+"""Step model for ATIF trajectories."""
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from atif_converter.domain.atif.content import ContentPart
+from atif_converter.domain.atif.metrics import Metrics
+from atif_converter.domain.atif.observation import Observation
+from atif_converter.domain.atif.tool_call import ToolCall
+
+
+class Step(BaseModel):
+    """A single step in the trajectory."""
+
+    step_id: int = Field(
+        default=...,
+        ge=1,
+        description="Ordinal index of the turn (starting from 1)",
+    )
+    timestamp: str | None = Field(
+        default=None,
+        description="ISO 8601 timestamp indicating when this step occurred",
+    )
+    source: Literal["system", "user", "agent"] = Field(
+        default=...,
+        description="The originator of this step",
+    )
+    model_name: str | None = Field(
+        default=None,
+        description=(
+            "The specific LLM model used for this turn. Omission implies the model "
+            "defined in the root-level agent config."
+        ),
+    )
+    reasoning_effort: str | float | None = Field(
+        default=None,
+        description="Qualitative or quantitative measure of effort",
+    )
+    message: str | list[ContentPart] = Field(
+        default=...,
+        description=(
+            "The dialogue message. String for text-only content, or array of "
+            "ContentPart for multimodal content (added in ATIF-v1.6)."
+        ),
+    )
+    reasoning_content: str | None = Field(
+        default=None,
+        description="The agent's explicit internal reasoning",
+    )
+    tool_calls: list[ToolCall] | None = Field(
+        default=None,
+        description="Array of structured objects for the agent's actions",
+    )
+    observation: Observation | None = Field(
+        default=None,
+        description="Environment feedback/result after actions or system events",
+    )
+    metrics: Metrics | None = Field(
+        default=None,
+        description="LLM operational and confidence data for this step",
+    )
+    is_copied_context: bool | None = Field(
+        default=None,
+        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."
+        ),
+    )
+    llm_call_count: int | None = Field(
+        default=None,
+        ge=0,
+        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."
+        ),
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom step-level metadata",
+    )
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("timestamp")
+    @classmethod
+    def validate_timestamp(cls, v: str | None) -> str | None:
+        """Validate that timestamp is a valid ISO 8601 string."""
+        if v is not None:
+            try:
+                datetime.fromisoformat(v.replace("Z", "+00:00"))
+            except ValueError as e:
+                raise ValueError(f"Invalid ISO 8601 timestamp: {e}")
+        return v
+
+    @model_validator(mode="after")
+    def validate_agent_only_fields(self) -> "Step":
+        """Validate that certain fields are only present for agent steps."""
+        if self.source != "agent":
+            agent_only_fields = [
+                "model_name",
+                "reasoning_effort",
+                "reasoning_content",
+                "tool_calls",
+                "metrics",
+            ]
+            for field in agent_only_fields:
+                if getattr(self, field) is not None:
+                    raise ValueError(
+                        f"Field '{field}' is only applicable when source is 'agent', "
+                        f"but source is '{self.source}'"
+                    )
+        return self
+
+    @model_validator(mode="after")
+    def validate_llm_call_count_zero_fields(self) -> "Step":
+        """Enforce ATIF v1.7 no-LLM orchestration rule.
+
+        When ``llm_call_count == 0`` on a ``source: "agent"`` step, the step
+        represents a deterministic (non-LLM) dispatch. LLM-specific fields
+        (``metrics``, ``reasoning_content``) MUST be absent on such steps.
+        """
+        if self.llm_call_count == 0 and self.source == "agent":
+            llm_only_fields = ["metrics", "reasoning_content"]
+            for field in llm_only_fields:
+                if getattr(self, field) is not None:
+                    raise ValueError(
+                        f"Field '{field}' must be absent when llm_call_count is 0 "
+                        f"(deterministic dispatch on a 'source: agent' step)"
+                    )
+        return self

atif_converter/domain/atif/subagent_trajectory_ref.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/subagent_trajectory_ref.py
+# (Apache-2.0, Copyright the Harbor authors). Byte for byte upstream apart
+# from these header lines and the import path, which reads
+# atif_converter.domain.atif where upstream reads harbor.models.trajectories.
+"""Subagent trajectory reference model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class SubagentTrajectoryRef(BaseModel):
+    """Reference to a delegated subagent trajectory.
+
+    A subagent reference is resolved by one of two mechanisms:
+
+    1. **Embedded form** — set `trajectory_id` to match the
+       `Trajectory.trajectory_id` of an entry in the parent's
+       `subagent_trajectories` array.
+    2. **File-ref form** — set `trajectory_path` to the location
+       (file path, S3 URL, etc.) of an external trajectory file.
+
+    These two mechanisms are the only resolution keys. `session_id`, when
+    present on the ref, is **informational only**: it records the run
+    identity of the delegated subagent for debug / correlation / cross-
+    trajectory search purposes, and MUST NOT be used as a matching key
+    (it is run-scoped and MAY collide across siblings — see
+    `Trajectory.session_id`). A ref therefore MUST set at least one of
+    `trajectory_id` or `trajectory_path`; `session_id` alone is not a
+    resolvable reference.
+    """
+
+    trajectory_id: str | None = Field(
+        default=None,
+        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`."
+        ),
+    )
+    session_id: str | None = Field(
+        default=None,
+        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 — consumers MUST resolve via `trajectory_id` "
+            "(embedded) or `trajectory_path` (external file)."
+        ),
+    )
+    trajectory_path: str | None = Field(
+        default=None,
+        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."
+        ),
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom metadata about the subagent execution",
+    )
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def validate_is_resolvable(self) -> "SubagentTrajectoryRef":
+        """A ref must be resolvable: set `trajectory_id` or `trajectory_path`.
+
+        `session_id` alone is not sufficient because it is run-scoped and
+        MAY collide across siblings (see `Trajectory.session_id`), so it
+        cannot unambiguously identify which subagent trajectory a ref
+        points at.
+        """
+        if self.trajectory_id is None and self.trajectory_path is None:
+            raise ValueError(
+                "SubagentTrajectoryRef must be resolvable: set either "
+                "`trajectory_id` (for embedded references) or "
+                "`trajectory_path` (for external-file references). "
+                "`session_id` alone is not a resolution key — it is "
+                "run-scoped and may collide across siblings."
+            )
+        return self

atif_converter/domain/atif/tool_call.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/tool_call.py
+# (Apache-2.0, Copyright the Harbor authors). Byte for byte upstream apart
+# from these header lines and the import path, which reads
+# atif_converter.domain.atif where upstream reads harbor.models.trajectories.
+"""Tool call model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolCall(BaseModel):
+    """A tool call within a step."""
+
+    tool_call_id: str = Field(
+        default=...,
+        description="Unique identifier for this specific tool call",
+    )
+    function_name: str = Field(
+        default=...,
+        description="The name of the function or tool being invoked",
+    )
+    arguments: dict[str, Any] = Field(
+        default=...,
+        description="Arguments passed to the function (can be empty dict)",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Custom tool-call-level metadata (e.g., timeout, retry count, tool version). "
+            "Added in ATIF-v1.7."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}

atif_converter/domain/atif/trajectory.py

@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/trajectory.py
+# (Apache-2.0, Copyright the Harbor authors). Byte for byte upstream apart
+# from these header lines and the import path, which reads
+# atif_converter.domain.atif where upstream reads harbor.models.trajectories.
+"""Trajectory model for ATIF (Agent Trajectory Interchange Format)."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from atif_converter.domain.atif.agent import Agent
+from atif_converter.domain.atif.final_metrics import FinalMetrics
+from atif_converter.domain.atif.step import Step
+
+
+class Trajectory(BaseModel):
+    """Agent Trajectory in ATIF (Agent Trajectory Interchange Format)."""
+
+    schema_version: Literal[
+        "ATIF-v1.0",
+        "ATIF-v1.1",
+        "ATIF-v1.2",
+        "ATIF-v1.3",
+        "ATIF-v1.4",
+        "ATIF-v1.5",
+        "ATIF-v1.6",
+        "ATIF-v1.7",
+        "ATIF-v1.8",
+    ] = Field(
+        default="ATIF-v1.8",
+        description="String defining ATIF compatibility",
+    )
+    session_id: str | None = Field(
+        default=None,
+        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."
+        ),
+    )
+    trajectory_id: str | None = Field(
+        default=None,
+        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."
+        ),
+    )
+    agent: Agent = Field(
+        default=...,
+        description="Object specifying the agent configuration",
+    )
+    steps: list[Step] = Field(
+        default=...,
+        min_length=1,
+        description="Array of step objects representing the complete interaction history",
+    )
+    notes: str | None = Field(
+        default=None,
+        description="Custom information, design notes, or explanations",
+    )
+    final_metrics: FinalMetrics | None = Field(
+        default=None,
+        description="Summary metrics for the entire trajectory",
+    )
+    continued_trajectory_ref: str | None = Field(
+        default=None,
+        description="Reference to the continuation trajectory file if this trajectory is continued in another file",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom root-level metadata",
+    )
+    subagent_trajectories: list["Trajectory"] | None = Field(
+        default=None,
+        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."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}
+
+    def to_json_dict(self, exclude_none: bool = True) -> dict[str, Any]:
+        """Export trajectory to a dictionary suitable for JSON serialization.
+
+        Args:
+            exclude_none: If True, exclude fields with None values from output.
+
+        Returns:
+            Dictionary representation of the trajectory.
+        """
+        return self.model_dump(exclude_none=exclude_none, mode="json")
+
+    @model_validator(mode="after")
+    def validate_step_ids(self) -> "Trajectory":
+        """Validate that step_ids are sequential starting from 1."""
+        for i, step in enumerate(self.steps):
+            expected_step_id = i + 1
+            if step.step_id != expected_step_id:
+                raise ValueError(
+                    f"steps[{i}].step_id: expected {expected_step_id} "
+                    f"(sequential from 1), got {step.step_id}"
+                )
+        return self
+
+    @model_validator(mode="after")
+    def validate_embedded_subagent_trajectory_ids(self) -> "Trajectory":
+        """Every embedded subagent must carry a unique, non-null `trajectory_id`.
+
+        Embedded subagents are resolved by matching
+        `SubagentTrajectoryRef.trajectory_id` against
+        `Trajectory.trajectory_id`, so the identifier must be present and
+        unique within a parent's `subagent_trajectories` array. Note that
+        no such constraint is placed on `session_id` — siblings MAY share
+        a `session_id` (or omit it entirely to inherit the parent's) when
+        they represent the same logical agent run.
+        """
+        if not self.subagent_trajectories:
+            return self
+        seen: set[str] = set()
+        for i, sub in enumerate(self.subagent_trajectories):
+            if sub.trajectory_id is None:
+                raise ValueError(
+                    f"subagent_trajectories[{i}].trajectory_id is required "
+                    f"for embedded subagents "
+                    f"(agent.name={sub.agent.name!r}, "
+                    f"session_id={sub.session_id!r})"
+                )
+            if sub.trajectory_id in seen:
+                raise ValueError(
+                    f"subagent_trajectories[{i}].trajectory_id "
+                    f"{sub.trajectory_id!r} is not unique within "
+                    f"subagent_trajectories"
+                )
+            seen.add(sub.trajectory_id)
+        return self
+
+    @model_validator(mode="after")
+    def validate_tool_call_references(self) -> "Trajectory":
+        """Validate that observation source_call_ids reference valid tool_call_ids."""
+        for step in self.steps:
+            if step.observation is None:
+                continue
+
+            # Collect all tool_call_ids from this step
+            tool_call_ids = set()
+            if step.tool_calls:
+                tool_call_ids = {tc.tool_call_id for tc in step.tool_calls}
+
+            # Check that source_call_ids reference valid tool_call_ids
+            for result in step.observation.results:
+                if result.source_call_id is not None:
+                    if result.source_call_id not in tool_call_ids:
+                        raise ValueError(
+                            f"Observation result references source_call_id "
+                            f"'{result.source_call_id}' which is not found in "
+                            f"step {step.step_id}'s tool_calls"
+                        )
+        return self
+
+    def has_multimodal_content(self) -> bool:
+        """Check if any step contains multimodal content (images or audio).
+
+        Returns:
+            True if any step message or observation contains a media content
+            part. Audio counts since ATIF-v1.8.
+        """
+        media_types = {"image", "audio"}
+        for step in self.steps:
+            if isinstance(step.message, list):
+                for part in step.message:
+                    if part.type in media_types:
+                        return True
+            if step.observation:
+                for result in step.observation.results:
+                    if isinstance(result.content, list):
+                        for part in result.content:
+                            if part.type in media_types:
+                                return True
+        return False