archastro.platform.types.artifacts

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: c85f0df95fc5
  4
  5from datetime import datetime
  6from typing import Any
  7
  8from pydantic import BaseModel, Field
  9
 10from .common import Acl
 11from .image import ImageSource
 12
 13
 14class Artifact(BaseModel):
 15    """
 16    A versioned artifact produced or managed by an agent, such as a generated file, report, or code output.
 17    """
 18
 19    acl: Acl | None = Field(
 20        default=None,
 21        description="Access control list for the artifact. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions` (`read`, `write`). `null` when the artifact has no grants or the viewer is not its owner.",
 22    )
 23    agent: str | None = Field(
 24        default=None,
 25        description="ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.",
 26    )
 27    content_type: str | None = Field(
 28        default=None,
 29        description='MIME type of the current version\'s file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.',
 30    )
 31    created_at: datetime | None = Field(
 32        default=None, description="When the artifact was first created (ISO 8601)."
 33    )
 34    current_version: str | None = Field(
 35        default=None,
 36        description="ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.",
 37    )
 38    description: str | None = Field(
 39        default=None,
 40        description="Optional longer description of the artifact's contents or purpose. `null` if not set.",
 41    )
 42    file: str | None = Field(
 43        default=None,
 44        description="Storage file ID for the current version (`fil_...`). `null` if no file is attached.",
 45    )
 46    file_name: str | None = Field(
 47        default=None,
 48        description='Original filename of the current version\'s file, e.g. `"output.csv"`. `null` if no file is attached.',
 49    )
 50    file_url: str | None = Field(
 51        default=None,
 52        description="Short-lived signed URL for downloading the current version's file. `null` if no file is attached.",
 53    )
 54    group_key: str | None = Field(
 55        default=None,
 56        description="Optional nonunique, case-sensitive grouping key, limited to 1024 UTF-8 bytes. Null when unset; belongs to the artifact, not a content version.",
 57    )
 58    id: str = Field(..., description="Artifact ID (`art_...`).")
 59    image_source: ImageSource | None = Field(
 60        default=None,
 61        description='Image source metadata for rendering the current version\'s file inline. Present only when `content_type` starts with `"image/"`. `null` otherwise.',
 62    )
 63    name: str | None = Field(
 64        default=None,
 65        description='Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.',
 66    )
 67    org: str | None = Field(
 68        default=None, description="ID of the organization this artifact belongs to (`org_...`)."
 69    )
 70    sandbox: str | None = Field(
 71        default=None,
 72        description="Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.",
 73    )
 74    system: bool | None = Field(
 75        default=None,
 76        description="True when the artifact has no user, team, or agent owner. An organization may own a system artifact.",
 77    )
 78    team: str | None = Field(
 79        default=None,
 80        description="ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.",
 81    )
 82    thread: str | None = Field(
 83        default=None,
 84        description="ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.",
 85    )
 86    updated_at: datetime | None = Field(
 87        default=None, description="When the artifact record was last modified (ISO 8601)."
 88    )
 89    user: str | None = Field(
 90        default=None,
 91        description="ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.",
 92    )
 93    version: int | None = Field(
 94        default=None,
 95        description="Current version number of the artifact. Increments each time a new version is published.",
 96    )
 97
 98
 99class ArtifactEditingAck(BaseModel):
100    """
101    Acknowledges an Artifact editing presence or leave request.
102    """
103
104    ok: bool
105
106
107class ArtifactEditingCursor(BaseModel):
108    """
109    A Unicode code-point cursor and optional selection endpoint.
110    """
111
112    position: int = Field(..., description="Zero-based Unicode code-point position.")
113    selection_end: int | None = Field(
114        default=None, description="Zero-based Unicode code-point selection endpoint."
115    )
116
117
118class ArtifactEditingActor(BaseModel):
119    """
120    A server-issued collaborator identity and its ephemeral presence.
121    """
122
123    actor_id: str = Field(..., description="Opaque identity unique to this channel join.")
124    cursor: ArtifactEditingCursor | None = Field(
125        default=None, description="Current code-point cursor, or null."
126    )
127    meta: dict[str, Any] = Field(..., description="Server-derived collaborator display metadata.")
128
129
130class ArtifactEditingCheckpointResponse(BaseModel):
131    """
132    Confirms the exact live revision that reached durable ArtifactVersion storage.
133    """
134
135    artifact_version: str = Field(..., description="New durable ArtifactVersion ID.")
136    artifact_version_number: int
137    checkpointed_revision: int
138    dirty: bool = Field(..., description="True when later live operations remain unsaved.")
139    incarnation: str
140
141
142class ArtifactEditingJoinResponse(BaseModel):
143    """
144    Authoritative live Artifact snapshot returned by an editing-channel join.
145    """
146
147    actor_id: str = Field(..., description="Server-issued identity for this channel join.")
148    actors: list[ArtifactEditingActor]
149    artifact: str = Field(..., description="Public Artifact ID (`art_...`).")
150    artifact_version: str = Field(..., description="Durable version ID (`artv_...`).")
151    artifact_version_number: int
152    can_write: bool
153    checkpoint_error: str | None = Field(
154        default=None, description="Last durable-save failure reason, or null."
155    )
156    checkpointed_revision: int = Field(..., description="Latest revision known durable.")
157    connection_id: str = Field(..., description="Server-issued connection identity.")
158    content: str = Field(..., description="UTF-8 document content.")
159    dirty: bool = Field(..., description="True while a live tail remains crash-loss exposed.")
160    incarnation: str = Field(..., description="Opaque live-session fence token.")
161    revision: int = Field(..., description="Live OT revision in Unicode code points.")
162
163
164class ArtifactEditingOperationAck(BaseModel):
165    """
166    Acknowledges an operation only after the authoritative OT server applied it.
167    """
168
169    revision: int = Field(..., description="Authoritative live revision after application.")