atif-sql 0.2.0__py3-none-any.whl

atif_converter/application/convert_codex.py

@@ -0,0 +1,210 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Use case: convert one Codex rollout AND account for what conversion lost.
+
+The Codex counterpart of
+:mod:`atif_converter.application.convert_and_audit`, composed the same way and
+under the same discipline: the rollout is read once, fingerprinted and parsed
+in the same pass, the converter and the audit consume that one list of
+records, and the fingerprints are re-checked once the artifacts are built, so
+the census, the trajectory and ``edges.jsonl`` all describe the same bytes of a
+rollout that Codex may still be appending to.
+
+What differs is only what a rollout IS. One file, no side-file tree, a record
+taxonomy of its own, and a set of gaps of its own — so the census, the edges
+and the enrichment come from the Codex modules while the snapshot machinery,
+the error taxonomy and the returned ``(ConversionResult, LossReport)`` pair are
+shared with the Claude Code path.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from loguru import logger
+
+from atif_converter.domain.blobs import BlobCollector, extract_codex_blobs
+from atif_converter.domain.codex_edges import build_codex_edges, codex_edges_jsonl_lines
+from atif_converter.domain.codex_enrichment import enrich_codex_trajectory
+from atif_converter.domain.codex_fidelity import (
+    CODEX_STRUCTURAL_GAPS,
+    CodexFidelityGap,
+    CodexRecordType,
+)
+from atif_converter.domain.errors import SourceMutatedDuringConversion
+from atif_converter.domain.fidelity import AnyRecordType, LossReport
+from atif_converter.domain.result_signals import annotate_codex_trajectory
+from atif_converter.domain.session_events import (
+    codex_session_events,
+    session_events_jsonl_lines,
+)
+from atif_converter.infrastructure.codex_adapter import convert_loaded_codex_session
+from atif_converter.infrastructure.codex_census import (
+    CodexSessionCensus,
+    codex_census_from_records,
+)
+from atif_converter.infrastructure.harbor_adapter import (
+    ConversionResult,
+    read_session,
+    validate_trajectory,
+)
+from atif_converter.infrastructure.raw_records import SessionSnapshot, mutated_files
+from atif_converter.infrastructure.source_archive import SourceArchiveWriter
+
+#: Response-item payload types whose presence in a rollout means a specific
+#: content-shaped gap was actually exercised, rather than merely being possible.
+_ITEM_TYPE_GAPS: dict[str, CodexFidelityGap] = {
+    "reasoning": CodexFidelityGap.REASONING_ENCRYPTED_DROPPED,
+    "tool_search_call": CodexFidelityGap.TOOL_SEARCH_CALLS_DROPPED,
+    "tool_search_output": CodexFidelityGap.TOOL_SEARCH_CALLS_DROPPED,
+}
+
+
+def _loss_report(
+    census: CodexSessionCensus, *, developer_messages: int, captured: int = 0
+) -> LossReport:
+    """Loss accounting for one rollout: total records vs items that convert.
+
+    ``records_converted`` counts the CONVERTIBLE RESPONSE ITEMS, not every
+    response item and not every record: ``event_msg`` and ``turn_context``
+    records are read for token counts and turn ids while producing no step of
+    their own, so counting them as converted would claim the trajectory
+    carries content it does not.
+    """
+    total = sum(census.record_counts.values())
+    converted = census.convertible_items
+    dropped = total - converted - captured
+
+    gaps = set(CODEX_STRUCTURAL_GAPS)
+    if dropped:
+        gaps.add(CodexFidelityGap.NON_ITEM_RECORDS_DROPPED)
+    if census.record_counts.get(CodexRecordType.COMPACTED):
+        gaps.add(CodexFidelityGap.COMPACTION_UNHANDLED)
+    if developer_messages:
+        gaps.add(CodexFidelityGap.DEVELOPER_ROLE_FLATTENED_TO_SYSTEM)
+    for item_type, gap in _ITEM_TYPE_GAPS.items():
+        if census.item_type_counts.get(item_type):
+            gaps.add(gap)
+
+    # Named rather than inlined: LossReport is shared by both agents, so its
+    # key type is the UNION of the two record taxonomies and a same-typed dict
+    # of one agent's members does not match the constructor overload without
+    # being widened here.
+    record_counts: dict[AnyRecordType, int] = {**census.record_counts}
+    return LossReport(
+        record_counts=record_counts,
+        records_converted=converted,
+        records_captured=captured,
+        records_dropped=dropped,
+        gaps_observed=frozenset(gaps),
+        # A Codex sub-agent writes its OWN rollout under its own session id, so
+        # a rollout never carries a subagent side-file. Zero here is a fact
+        # about the format, not an unmeasured field.
+        subagent_files_found=0,
+        subagent_files_convertible=0,
+        workflow_subagent_files_found=0,
+    )
+
+
+def _developer_message_count(records: list[tuple[dict[str, object], str]]) -> int:
+    """How many ``developer``-role messages the rollout carried."""
+    count = 0
+    for record, _source_file in records:
+        if record.get("type") != "response_item":
+            continue
+        payload = record.get("payload")
+        if not isinstance(payload, dict):
+            continue
+        if payload.get("type") == "message" and payload.get("role") == "developer":
+            count += 1
+    return count
+
+
+def _refuse_if_mutated(
+    snapshot: SessionSnapshot, archive: SourceArchiveWriter | None = None
+) -> None:
+    mutated = mutated_files(snapshot, archive=archive)
+    if not mutated:
+        if archive is not None:
+            # The verifying read already archived the transcripts AND the
+            # parsed sidecars; the sweep takes only files nothing parsed.
+            archive.archive_side_files(
+                snapshot.session_jsonl,
+                already=(*snapshot.files, *snapshot.sidecar_fingerprints),
+            )
+        return
+    logger.warning(
+        "convert_codex: {} source file(s) changed while converting {}; refusing",
+        len(mutated),
+        snapshot.session_jsonl,
+    )
+    raise SourceMutatedDuringConversion(snapshot.session_jsonl, mutated)
+
+
+def convert_codex_and_audit(
+    rollout_jsonl: Path,
+    *,
+    archive: SourceArchiveWriter | None = None,
+) -> tuple[ConversionResult, LossReport]:
+    """Convert ``rollout_jsonl`` to ATIF and produce its loss accounting.
+
+    The returned :class:`ConversionResult` carries the ENRICHED trajectory
+    (``source_uuids`` on steps, ``cache_creation_total`` and the compaction
+    count on the trajectory — see
+    :func:`~atif_converter.domain.codex_enrichment.enrich_codex_trajectory`)
+    plus the ready-to-write ``edges.jsonl`` lines derived from the RAW records.
+    Validation is re-run post-enrichment.
+
+    With ``archive``, the verifying re-read also streams every source file
+    into that writer (see
+    :mod:`atif_converter.infrastructure.source_archive`): the archive costs
+    no extra open of a transcript and holds exactly the bytes that were
+    parsed. It is complete only when this function returns; on any raise the
+    caller must discard it.
+
+    Raises
+    ------
+        InvalidSessionInput: ``rollout_jsonl`` is not an existing ``.jsonl`` file.
+        SourceMutatedDuringConversion: the rollout changed between the
+            read and the end of the audit, so the artifacts would not
+            describe the rollout as it stands.
+    """
+    loaded = read_session(rollout_jsonl)
+    snapshot = loaded.snapshot
+    # Attachments out BEFORE conversion, named by the same record ids the
+    # enrichment pass writes into ``source_uuids`` (an edge's uuid depends on
+    # the record's ids and position, never on the content being rewritten).
+    records = loaded.record_pairs()
+    record_keys = [str(edge["uuid"]) for edge in build_codex_edges(records)]
+    collector = BlobCollector()
+    blob_index = extract_codex_blobs(
+        [record for record, _src in records], collector, record_keys=record_keys
+    )
+    result = convert_loaded_codex_session(loaded)
+
+    census = codex_census_from_records(rollout_jsonl, records)
+    events = codex_session_events(records)
+    report = _loss_report(
+        census,
+        developer_messages=_developer_message_count(records),
+        captured=len(events),
+    )
+    edges_lines = tuple(codex_edges_jsonl_lines(records))
+    events_lines = tuple(session_events_jsonl_lines(events))
+    # The harbor trajectory has no other consumer, so enrich in place rather
+    # than deep-copying a whole rollout's worth of steps.
+    enriched = enrich_codex_trajectory(result.trajectory, records, copy_input=False)
+    annotate_codex_trajectory(enriched, [record for record, _src in records], blob_index)
+    del records, loaded, events
+    _refuse_if_mutated(snapshot, archive)
+
+    return (
+        ConversionResult(
+            trajectory=enriched,
+            validation_errors=validate_trajectory(enriched),
+            edges_lines=edges_lines,
+            events_lines=events_lines,
+            blobs=collector.blobs,
+        ),
+        report,
+    )

atif_converter/domain/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pure domain layer: fidelity policy types, the error taxonomy, the two conversions.
+
+The innermost layer of the converter hexagon. It holds the ATIF data classes
+(the output contract, vendored from harbor under :mod:`atif_converter.domain.atif`)
+and does no file I/O beyond :mod:`atif_converter.domain.pricing` reading the
+vendored price table beside it. Nothing here imports harbor or litellm.
+"""

atif_converter/domain/agents.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Which agent produced a transcript — the one enum every layer keys off.
+
+An ATIF corpus can hold trajectories from more than one coding agent, and the
+two this workspace converts write nothing alike: Claude Code appends one JSONL
+per session under ``<config>/projects/<project>/``, Codex CLI writes one
+rollout per session under ``$CODEX_HOME/sessions/<YYYY>/<MM>/<DD>/``. Discovery,
+the record taxonomy, the fidelity gaps and the harbor adapter all differ, so
+the agent is a first-class value carried from the CLI flag down to the census
+rather than inferred from a path shape at each layer.
+
+Pure value object: no harbor import, no I/O. The string values are WIRE
+CONTRACT — they are the ``--agent`` flag's accepted spellings, the
+``agent.name`` harbor stamps into a trajectory, and the ``agent`` key in
+``meta.json``.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class AgentSource(StrEnum):
+    """A coding agent whose transcripts this workspace can convert.
+
+    The value doubles as harbor's ``Trajectory.agent.name`` for that agent
+    (verified 2026-09-11 against harbor 0.22.0: ``ClaudeCode`` stamps
+    ``claude-code`` and ``Codex`` stamps ``codex``), which is what lets
+    atif-duck's ``sessions.agent`` column come straight from the trajectory
+    instead of from a second provenance file.
+    """
+
+    CLAUDE_CODE = "claude-code"
+    CODEX = "codex"
+
+
+#: The agent assumed when a caller names none — the interactive corpus nearly
+#: every user has, and the only agent this workspace supported before 2026-09-11.
+DEFAULT_AGENT: AgentSource = AgentSource.CLAUDE_CODE

atif_converter/domain/atif/__init__.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/__init__.py
+# (Apache-2.0, Copyright the Harbor authors), with the provenance constants
+# below added.
+
+"""Pydantic models for Agent Trajectory Interchange Format (ATIF).
+
+The ATIF data classes and the trajectory validator, vendored from harbor
+(https://github.com/laude-institute/harbor) at :data:`UPSTREAM_VERSION` under
+its Apache-2.0 license, so atif-sql converts and validates trajectories
+without installing harbor and the dependency tree harbor's agent runtime
+carries. Every sibling module is upstream's file byte for byte apart from its
+header and the import path (``harbor.models.trajectories`` reads
+``atif_converter.domain.atif`` here); this ``__init__`` adds only the two
+constants.
+
+harbor stays a dev dependency, and the converter's tests hold this copy to it:
+``tests/test_vendored_atif.py`` compares each file to the installed upstream
+source and round-trips the golden trajectories through both sets of models and
+both validators. A harbor bump that changes the models fails there, and the fix
+is to re-vendor the changed files and move :data:`UPSTREAM_VERSION`.
+"""
+
+from atif_converter.domain.atif.agent import Agent
+from atif_converter.domain.atif.content import AudioSource, ContentPart, ImageSource
+from atif_converter.domain.atif.final_metrics import FinalMetrics
+from atif_converter.domain.atif.metrics import Metrics
+from atif_converter.domain.atif.observation import Observation
+from atif_converter.domain.atif.observation_result import ObservationResult
+from atif_converter.domain.atif.step import Step
+from atif_converter.domain.atif.subagent_trajectory_ref import SubagentTrajectoryRef
+from atif_converter.domain.atif.tool_call import ToolCall
+from atif_converter.domain.atif.trajectory import Trajectory
+
+#: The distribution these files were vendored from.
+UPSTREAM_DISTRIBUTION = "harbor"
+#: The upstream release the files match; ``meta.json`` records it as ``harbor_version``.
+UPSTREAM_VERSION = "0.24.0"
+
+__all__ = [
+    "UPSTREAM_DISTRIBUTION",
+    "UPSTREAM_VERSION",
+    "Agent",
+    "AudioSource",
+    "ContentPart",
+    "FinalMetrics",
+    "ImageSource",
+    "Metrics",
+    "Observation",
+    "ObservationResult",
+    "Step",
+    "SubagentTrajectoryRef",
+    "ToolCall",
+    "Trajectory",
+]

atif_converter/domain/atif/agent.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/agent.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.
+"""Agent configuration model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Agent(BaseModel):
+    """Agent configuration."""
+
+    name: str = Field(
+        default=...,
+        description="The name of the agent system",
+    )
+    version: str = Field(
+        default=...,
+        description="The version identifier of the agent system",
+    )
+    model_name: str | None = Field(
+        default=None,
+        description="Default LLM model used for this trajectory",
+    )
+    tool_definitions: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Array of tool/function definitions available to the agent. Each element follows OpenAI's function calling schema.",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom agent configuration details",
+    )
+
+    model_config = {"extra": "forbid"}

atif_converter/domain/atif/content.py

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/content.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.
+"""Content models for multimodal ATIF trajectories.
+
+Added in ATIF-v1.6 to support multimodal content (images) in trajectories.
+Extended in ATIF-v1.8 with audio.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+# Canonical audio MIME types, chosen to cover what multimodal and transcription
+# APIs actually accept: Gemini audio understanding (wav, mp3, aiff, aac, ogg,
+# flac), OpenAI transcription (flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm),
+# and `audio/webm`, which is what a browser's MediaRecorder produces and so what
+# human-recorded task data usually arrives as.
+AudioMediaType = Literal[
+    "audio/wav",
+    "audio/mpeg",
+    "audio/mp4",
+    "audio/aac",
+    "audio/ogg",
+    "audio/flac",
+    "audio/webm",
+    "audio/aiff",
+]
+
+# Aliases producers emit in place of the registered MIME type, normalized on the
+# way in so consumers only ever see one spelling per format. `audio/mp3` is the
+# important one: it is not a registered type, but the Gemini API documents and
+# emits it, so a producer copying a provider response verbatim would otherwise
+# fail validation.
+_AUDIO_MEDIA_TYPE_ALIASES = {
+    "audio/mp3": "audio/mpeg",
+    "audio/mpga": "audio/mpeg",
+    "audio/x-mpeg": "audio/mpeg",
+    "audio/x-wav": "audio/wav",
+    "audio/wave": "audio/wav",
+    "audio/vnd.wave": "audio/wav",
+    "audio/x-m4a": "audio/mp4",
+    "audio/m4a": "audio/mp4",
+    "audio/x-aac": "audio/aac",
+    "audio/x-flac": "audio/flac",
+    "audio/x-aiff": "audio/aiff",
+}
+
+
+class ImageSource(BaseModel):
+    """Image source specification for images stored as files or at remote URLs."""
+
+    media_type: Literal["image/jpeg", "image/png", "image/gif", "image/webp"] = Field(
+        default=...,
+        description="MIME type of the image",
+    )
+    path: str = Field(
+        default=...,
+        description=(
+            "Location of the image. Can be a relative or absolute file path, or a URL."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+class AudioSource(BaseModel):
+    """Audio source specification for audio stored as files or at remote URLs.
+
+    Added in ATIF-v1.8. Mirrors ``ImageSource`` so that consumers can treat any
+    referenced media the same way, with one addition: ``duration_sec``. Duration
+    is worth recording because several providers bill audio per second and
+    dataset statistics need it, and unlike an image's dimensions it cannot be
+    recovered without decoding the file.
+    """
+
+    media_type: AudioMediaType = Field(
+        default=...,
+        description="MIME type of the audio",
+    )
+    path: str = Field(
+        default=...,
+        description=(
+            "Location of the audio. Can be a relative or absolute file path, or a URL."
+        ),
+    )
+    duration_sec: float | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Optional duration of the audio in seconds. Useful for cost "
+            "accounting and dataset statistics; omit when unknown."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("media_type", mode="before")
+    @classmethod
+    def normalize_media_type(cls, value: Any) -> Any:
+        """Accept common non-registered spellings, storing the canonical one."""
+        if isinstance(value, str):
+            normalized = value.strip().lower()
+            return _AUDIO_MEDIA_TYPE_ALIASES.get(normalized, normalized)
+        return value
+
+
+class ContentPart(BaseModel):
+    """A single content part within a multimodal message.
+
+    Used when a message or observation contains mixed content types (text,
+    images, or audio). For text-only content, a plain string can still be used
+    instead of a ContentPart array.
+    """
+
+    type: Literal["text", "image", "audio"] = Field(
+        default=...,
+        description="The type of content",
+    )
+    text: str | None = Field(
+        default=None,
+        description="Text content. Required when type='text'.",
+    )
+    source: ImageSource | AudioSource | None = Field(
+        default=None,
+        description=(
+            "Media source (file reference). Required when type='image' or "
+            "type='audio', and must match that type."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def validate_content_type(self) -> "ContentPart":
+        """Validate that the correct fields are present for each content type."""
+        if self.type == "text":
+            if self.text is None:
+                raise ValueError("'text' field is required when type='text'")
+            if self.source is not None:
+                raise ValueError("'source' field is not allowed when type='text'")
+            return self
+
+        # Media parts: a source is required, text is not allowed, and the source
+        # must be of the kind the `type` declares. Without the last check a
+        # `source` union would happily accept an ImageSource under
+        # type='audio' (and vice versa), silently mislabelling the content.
+        if self.source is None:
+            raise ValueError(f"'source' field is required when type='{self.type}'")
+        if self.text is not None:
+            raise ValueError(f"'text' field is not allowed when type='{self.type}'")
+
+        expected = ImageSource if self.type == "image" else AudioSource
+        if not isinstance(self.source, expected):
+            raise ValueError(
+                f"type='{self.type}' requires a {expected.__name__}, but the "
+                f"source's media_type is {self.source.media_type!r}"
+            )
+        return self

atif_converter/domain/atif/final_metrics.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/final_metrics.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.
+"""Final metrics model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FinalMetrics(BaseModel):
+    """Aggregate statistics for the entire trajectory."""
+
+    total_prompt_tokens: int | None = Field(
+        default=None,
+        description="Sum of all prompt tokens across all steps, including cached tokens",
+    )
+    total_completion_tokens: int | None = Field(
+        default=None,
+        description="Sum of all completion tokens across all steps",
+    )
+    total_cached_tokens: int | None = Field(
+        default=None,
+        description="Sum of all cached tokens across all steps",
+    )
+    total_cost_usd: float | None = Field(
+        default=None,
+        description="Total real monetary cost for the entire trajectory, including cost for subagents, if any",
+    )
+    total_steps: int | None = Field(
+        default=None,
+        ge=0,
+        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."
+        ),
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Custom aggregate metrics",
+    )
+
+    model_config = {"extra": "forbid"}

atif_converter/domain/atif/metrics.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/metrics.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.
+"""Metrics model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Metrics(BaseModel):
+    """LLM operational and confidence data."""
+
+    prompt_tokens: int | None = Field(
+        default=None,
+        description="Total input tokens including cached and non-cached",
+    )
+    completion_tokens: int | None = Field(
+        default=None,
+        description="Total tokens generated by the LLM response",
+    )
+    cached_tokens: int | None = Field(
+        default=None,
+        description="Subset of prompt_tokens that were cache hits",
+    )
+    cost_usd: float | None = Field(
+        default=None,
+        description="Monetary cost of the API call in USD",
+    )
+    prompt_token_ids: list[int] | None = Field(
+        default=None,
+        description="Token IDs for prompt (input) tokens sent to the LLM, including chat history (if applicable)",
+    )
+    completion_token_ids: list[int] | None = Field(
+        default=None,
+        description="Token IDs for completion (response) tokens, enabling RL training without retokenization drift",
+    )
+    logprobs: list[float] | None = Field(
+        default=None,
+        description="Log probability assigned to each generated token",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description="Other metrics",
+    )
+
+    model_config = {"extra": "forbid"}

atif_converter/domain/atif/observation.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/observation.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.
+"""Observation model for ATIF trajectories."""
+
+from pydantic import BaseModel, Field
+
+from atif_converter.domain.atif.observation_result import ObservationResult
+
+
+class Observation(BaseModel):
+    """Environment feedback/result after actions or system events."""
+
+    results: list[ObservationResult] = Field(
+        default=...,
+        description="Array of result objects from tool calls or actions",
+    )
+
+    model_config = {"extra": "forbid"}

atif_converter/domain/atif/observation_result.py

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: Apache-2.0
+# Vendored from harbor 0.24.0, src/harbor/models/trajectories/observation_result.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.
+"""Observation result model for ATIF trajectories."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from atif_converter.domain.atif.content import ContentPart
+from atif_converter.domain.atif.subagent_trajectory_ref import SubagentTrajectoryRef
+
+
+class ObservationResult(BaseModel):
+    """A single result within an observation."""
+
+    source_call_id: str | None = Field(
+        default=None,
+        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)."
+        ),
+    )
+    content: str | list[ContentPart] | None = Field(
+        default=None,
+        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)."
+        ),
+    )
+    subagent_trajectory_ref: list[SubagentTrajectoryRef] | None = Field(
+        default=None,
+        description="Array of references to delegated subagent trajectories",
+    )
+    extra: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Custom observation-result-level metadata (e.g., confidence score, "
+            "retrieval score, source document ID). Added in ATIF-v1.7."
+        ),
+    )
+
+    model_config = {"extra": "forbid"}