agent-apprenticeship 0.2.0 → 0.3.0

package/src/agent_apprenticeship/agent_env_exporter.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+import shutil
+import tempfile
+
+from .io import validate_trace_tree, write_json
+
+_EXCLUDED = {'agent_env', '__pycache__', 'node_modules', 'build', 'dist', 'roles'}
+
+
+def export_agent_env(source: Path) -> Path:
+    source = source.resolve()
+    destination = source / 'agent_env'
+    validate_trace_tree(source)
+    with tempfile.TemporaryDirectory(prefix='.agentenv-', dir=source) as temp:
+        staging = Path(temp)
+        artifact = staging / 'artifacts' / 'experience'
+        snapshot = artifact / 'snapshot'
+        snapshot.mkdir(parents=True)
+        files = []
+        for directory, dirs, names in os.walk(source, followlinks=False):
+            dirs[:] = sorted(d for d in dirs if not d.startswith('.') and d not in _EXCLUDED
+                             and not (Path(directory) / d).is_symlink())
+            for name in sorted(names):
+                path = Path(directory) / name
+                if name.startswith('.') or path.is_symlink() or not path.is_file():
+                    continue
+                if name.endswith(('.pyc', '.log')) or name in {'stdout.txt', 'stderr.txt', 'rejected_agent_response.txt'}:
+                    continue
+                relative = path.relative_to(source)
+                target = snapshot / relative
+                target.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copyfile(path, target)
+                files.append({'path': relative.as_posix(), 'sha256': hashlib.sha256(target.read_bytes()).hexdigest()})
+        write_json(artifact / 'snapshot.json', {'files': files})
+        shutil.copyfile(Path(__file__).with_name('agent_env_verify.py'), artifact / 'verify.py')
+        write_json(staging / 'tasks' / 'experience.json', [
+            {'id': 'sandbox', 'type': 'deploy_sandbox', 'sandbox_name': 'experience',
+             'sandbox_mode': 'vm', 'sandbox_type': 'local'},
+            {'id': 'restore', 'type': 'load_artifact', 'sandbox_name': 'experience',
+             'artifact_id': 'experience', 'destination_path': '/app/experience', 'depends_on': ['sandbox']},
+            {'id': 'verify', 'type': 'verify_sandbox', 'sandbox_name': 'experience',
+             'base_dir': '/app/experience', 'verifier_id': 'experience_integrity', 'depends_on': ['restore'],
+             'criteria': [{'type': 'bash_cmd_succeeds', 'criterion': 'snapshot_integrity',
+                           'bash_cmd': 'python3 verify.py'}]},
+        ])
+        if destination.exists():
+            shutil.rmtree(destination)
+        staging.rename(destination)
+    return destination

package/src/agent_apprenticeship/agent_env_verify.py

@@ -0,0 +1,32 @@
+import hashlib
+import json
+from pathlib import Path
+
+
+def verify(root):
+    root = Path(root)
+    snapshot = (root / 'snapshot').resolve()
+    manifest = json.loads((root / 'snapshot.json').read_text(encoding='utf-8'))
+    files = manifest['files']
+    if not isinstance(files, list) or not files:
+        return False
+    seen = set()
+    for entry in files:
+        relative = Path(entry['path'])
+        path = snapshot / relative
+        if relative.is_absolute() or '..' in relative.parts or path.is_symlink():
+            return False
+        if not path.resolve().is_relative_to(snapshot) or not path.is_file() or relative.as_posix() in seen:
+            return False
+        seen.add(relative.as_posix())
+        if hashlib.sha256(path.read_bytes()).hexdigest() != entry['sha256']:
+            return False
+    return True
+
+
+if __name__ == '__main__':
+    try:
+        passed = verify(Path(__file__).resolve().parent)
+    except (OSError, ValueError, KeyError, TypeError):
+        passed = False
+    raise SystemExit(0 if passed else 1)

package/src/agent_apprenticeship/atif.py

@@ -0,0 +1,152 @@
+"""ATIF v1.8 interchange and lossless projections for workflow evaluation.
+
+Only ATIF documents cross persistence boundaries. Project-specific evidence lives
+in ``extra.agent_apprenticeship``; Harbor fields are preserved independently of
+our task/evaluation projection, including parallel calls and multimodal content.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+from pathlib import Path
+from typing import Any
+from .atif_models import Trajectory
+
+VERSION = "ATIF-v1.8"
+NAMESPACE = "agent_apprenticeship"
+
+
+def validate_trace(data: Any) -> dict:
+    if not isinstance(data, dict) or data.get("schema_version") != VERSION:
+        raise ValueError("Trace must declare schema_version ATIF-v1.8")
+    return Trajectory.model_validate(data).to_json_dict()
+
+
+def load_trace(path: Path) -> dict:
+    return validate_trace(json.loads(path.read_text(encoding="utf-8")))
+
+
+def dump_trace(path: Path, trace: Any) -> None:
+    if isinstance(trace, Trajectory):
+        trace = trace.to_json_dict()
+    data = validate_trace(trace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def _text(value: Any) -> str:
+    if value is None:
+        return ""
+    return value if isinstance(value, str) else json.dumps(value, ensure_ascii=False)
+
+
+def to_workflow(data: dict) -> dict:
+    """Project validated ATIF into the internal evaluator's task/step view."""
+    data = validate_trace(data)
+    meta = deepcopy((data.get("extra") or {}).get(NAMESPACE) or {})
+    # Filter extension fields for the strongly typed task projection.
+    from .schemas import WorkflowTrace, WorkflowTraceStep
+    meta = {k: v for k, v in meta.items() if k in WorkflowTrace.model_fields}
+    identity = data.get("trajectory_id") or data.get("session_id") or "external"
+    meta.setdefault("trace_id", identity)
+    meta.setdefault("run_id", data.get("session_id"))
+    meta.setdefault("task_id", identity)
+    meta.setdefault("attempt_id", identity)
+    meta.setdefault("attempt_kind", "other")
+    meta.setdefault("trace_mode", "live")
+    meta.setdefault("task", next((_text(s["message"]) for s in data["steps"] if s["source"] == "user"), ""))
+    meta.setdefault("agent_tools", sorted({c["function_name"] for s in data["steps"] for c in s.get("tool_calls") or []}))
+    meta.setdefault("termination_reason", "other")
+    meta["schema_version"] = VERSION
+    meta.setdefault("metadata_json", {})["_atif_original"] = deepcopy(data)
+    steps = []
+    for s in data["steps"]:
+        ext = deepcopy((s.get("extra") or {}).get(NAMESPACE) or {})
+        ext = {k: v for k, v in ext.items() if k in WorkflowTraceStep.model_fields}
+        ext.update(step=s["step_id"])
+        ext.setdefault("turn", s["step_id"])
+        ext.setdefault("actor", "user" if s["source"] == "user" else "agent:worker")
+        ext.setdefault("action", "user_message" if s["source"] == "user" else "agent_step")
+        ext.setdefault("input", _text(s["message"]))
+        if s["source"] != "user":
+            ext.setdefault("operation", "other")
+            calls = s.get("tool_calls") or []
+            ext.setdefault("tool", calls[0]["function_name"] if len(calls) == 1 else None)
+            results = (s.get("observation") or {}).get("results") or []
+            ext.setdefault("output", "\n".join(_text(r.get("content")) for r in results) or _text(s["message"]))
+            ext.setdefault("reasoning", s.get("reasoning_content"))
+        steps.append(ext)
+    meta["steps"] = steps
+    return meta
+
+
+def from_workflow(trace: dict) -> dict:
+    """Serialize a task projection as ATIF, retaining original Harbor content."""
+    trace = deepcopy(trace)
+    original = (trace.get("metadata_json") or {}).pop("_atif_original", None)
+    out = deepcopy(original) if original else {
+        "schema_version": VERSION,
+        "agent": {"name": "agent-apprenticeship", "version": "0.3.0"},
+    }
+    out["session_id"] = trace.get("run_id") or out.get("session_id") or trace.get("attempt_id") or trace["trace_id"]
+    out["trajectory_id"] = trace["trace_id"]
+    steps = []
+    for i, s in enumerate(trace.pop("steps"), 1):
+        prior = original["steps"][i-1] if original and i <= len(original["steps"]) else None
+        step = deepcopy(prior) if prior else {
+            "step_id": i,
+            "source": "user" if s.get("actor") == "user" else "system" if s.get("actor") == "system" else "agent",
+            "message": _text(s.get("input") if s.get("actor") == "user" else s.get("output") or s.get("input") or s.get("action")),
+        }
+        step["step_id"] = i
+        if not prior:
+            if s.get("started_at"):
+                step["timestamp"] = s["started_at"]
+            if step["source"] == "agent":
+                if s.get("reasoning"):
+                    step["reasoning_content"] = s["reasoning"]
+                if s.get("tool"):
+                    call_id = f"call_{i}"
+                    step["tool_calls"] = [{"tool_call_id": call_id, "function_name": s["tool"], "arguments": {"input": s.get("input") or ""}}]
+                    if s.get("output") is not None:
+                        step["observation"] = {"results": [{"source_call_id": call_id, "content": s["output"]}]}
+        step.setdefault("extra", {}).setdefault(NAMESPACE, {}).update({k: v for k, v in s.items() if v is not None and v != [] and v != {}})
+        steps.append(step)
+    out["steps"] = steps
+    trace.pop("schema_version", None)
+    out.setdefault("extra", {}).setdefault(NAMESPACE, {}).update({k: v for k, v in trace.items() if v is not None and v != [] and v != {}})
+    return validate_trace(out)
+
+
+def encode_traces(data: Any) -> Any:
+    """Encode trace objects even when nested in training/evaluation envelopes."""
+    if isinstance(data, list):
+        return [encode_traces(v) for v in data]
+    if not isinstance(data, dict):
+        return data
+    if isinstance(data.get("steps"), list) and "agent" in data:
+        return validate_trace(data)
+    if isinstance(data.get("steps"), list) and "trace_id" in data:
+        return from_workflow(data)
+    return {k: encode_traces(v) for k, v in data.items()}
+
+
+def decode_traces(data: Any) -> Any:
+    if isinstance(data, list):
+        return [decode_traces(v) for v in data]
+    if not isinstance(data, dict):
+        return data
+    if isinstance(data.get("steps"), list) and "agent" in data:
+        return to_workflow(data)
+    return {k: decode_traces(v) for k, v in data.items()}
+
+
+def event_trace(event: dict, name: str) -> dict:
+    """Represent a compiler/session event as a complete one-step trajectory."""
+    return validate_trace({
+        "schema_version": VERSION,
+        "session_id": event.get("session_id") or event.get("run_id"),
+        "agent": {"name": name, "version": "0.3.0"},
+        "steps": [{"step_id": 1, "source": "system", "message": _text(event.get("message") or event.get("instruction") or event.get("event_type")), "extra": {NAMESPACE: event}}],
+        "extra": {NAMESPACE: {"event": event}},
+    })

package/src/agent_apprenticeship/atif_models/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/src/agent_apprenticeship/atif_models/__init__.py

@@ -0,0 +1,38 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""Pydantic models for Agent Trajectory Interchange Format (ATIF).
+
+This module provides Pydantic models for validating and constructing
+trajectory data following the ATIF specification (RFC 0001).
+"""
+
+from agent_apprenticeship.atif_models.agent import Agent
+from agent_apprenticeship.atif_models.content import (
+    AudioSource,
+    ContentPart,
+    ImageSource,
+)
+from agent_apprenticeship.atif_models.final_metrics import FinalMetrics
+from agent_apprenticeship.atif_models.metrics import Metrics
+from agent_apprenticeship.atif_models.observation import Observation
+from agent_apprenticeship.atif_models.observation_result import ObservationResult
+from agent_apprenticeship.atif_models.step import Step
+from agent_apprenticeship.atif_models.subagent_trajectory_ref import SubagentTrajectoryRef
+from agent_apprenticeship.atif_models.tool_call import ToolCall
+from agent_apprenticeship.atif_models.trajectory import Trajectory
+
+__all__ = [
+    "Agent",
+    "AudioSource",
+    "ContentPart",
+    "FinalMetrics",
+    "ImageSource",
+    "Metrics",
+    "Observation",
+    "ObservationResult",
+    "Step",
+    "SubagentTrajectoryRef",
+    "ToolCall",
+    "Trajectory",
+]

package/src/agent_apprenticeship/atif_models/agent.py

@@ -0,0 +1,35 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""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"}

package/src/agent_apprenticeship/atif_models/content.py

@@ -0,0 +1,159 @@
+# Harbor ATIF models (Apache-2.0; see LICENSE).
+# Source: harbor-framework/harbor@357c5e74020fc0890d69fb3a7db610896b9ce57d
+# Modified: local imports; trajectory schema version pinned to v1.8.
+"""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