Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

5.1 KB
Raw Blame
"""Public contracts for persistent chat context, independent of model or OS.

The snapshot is conversation data, never a replacement for runtime instructions.
Only the ingress owns delivery cursors and native compaction; the dashboard must
not manufacture a second summary or claim delivery from a browser-side counter.
"""

from typing import Literal

from pydantic import BaseModel, ConfigDict, Field, field_validator, model_serializer, model_validator
from pixel_image_transport import ImageReference, MAX_TURN_IMAGES


MAX_HISTORY_BYTES = 4 * 1024 * 1024
MAX_HISTORY_MESSAGES = 2000


class HistoryMessage(BaseModel):
    model_config = ConfigDict(extra="forbid", strict=True)

    role: Literal["user", "assistant"]
    content: str = Field(max_length=MAX_HISTORY_BYTES)
    images: list[ImageReference] | None = Field(default=None, min_length=1, max_length=MAX_TURN_IMAGES)

    @model_validator(mode="after")
    def owner_images_only(self):
        if self.images is not None:
            if self.role != "user" or len({image.id for image in self.images}) != len(self.images):
                raise ValueError("Only user messages may contain distinct image references")
        return self

    @model_serializer(mode="wrap")
    def preserve_legacy_shape(self, handler):
        value = handler(self)
        if self.images is None:
            value.pop("images", None)
        return value


class HistorySnapshot(BaseModel):
    model_config = ConfigDict(extra="forbid", strict=True)

    schemaVersion: Literal[1, 2]
    messages: list[HistoryMessage] = Field(min_length=1, max_length=MAX_HISTORY_MESSAGES)

    @field_validator("messages")
    @classmethod
    def bounded_content(cls, messages):
        if sum(len(item.content.encode("utf-8")) + sum(len(image.id) + len(image.sha256)
                   for image in (item.images or [])) for item in messages) > MAX_HISTORY_BYTES:
            raise ValueError("Conversation history exceeds its storage limit")
        return messages

    @model_validator(mode="after")
    def versioned_images(self):
        if self.schemaVersion == 1 and any(message.images is not None for message in self.messages):
            raise ValueError("Image history requires schema version 2")
        images = {}
        for message in self.messages:
            for image in message.images or []:
                if image.id in images and images[image.id] != image.sha256:
                    raise ValueError("A history image cannot change identity")
                images[image.id] = image.sha256
        return self


class _Projection(BaseModel):
    # Future internal fields (session files, summaries, credentials) must never
    # leak to the browser merely because the gateway adds them to its response.
    model_config = ConfigDict(extra="ignore", strict=True)


class ContextUsage(_Projection):
    used: int = Field(ge=0, le=100_000_000)
    window: int = Field(ge=1, le=10_000_000)
    measuredAt: str = Field(min_length=1, max_length=64, pattern=r"^[0-9TZ: .+\-]+$")


class ContextModel(_Projection):
    id: str = Field(min_length=1, max_length=512, pattern=r"^[^\x00-\x1f\x7f]+$")
    provider: str = Field(min_length=1, max_length=128, pattern=r"^[^\x00-\x1f\x7f]+$")
    contextWindow: int = Field(ge=1, le=10_000_000)
    routeFingerprint: str | None = Field(default=None, min_length=64, max_length=64, pattern=r"^[a-f0-9]{64}$")
    imageInput: Literal["supported", "unsupported", "unknown"] | None = None
    imageRouteFingerprint: str | None = Field(default=None, min_length=64, max_length=64, pattern=r"^[a-f0-9]{64}$")


class CompactionState(_Projection):
    status: Literal["idle", "running", "completed", "skipped", "failed", "unknown"]
    count: int = Field(ge=0)
    requestId: str | None = Field(default=None, pattern=r"^[A-Za-z0-9_-]{1,128}$")
    tokensBefore: int | None = Field(default=None, ge=0, le=100_000_000)
    tokensAfter: int | None = Field(default=None, ge=0, le=100_000_000)
    reason: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9-]{0,95}$")


class HistoryState(_Projection):
    status: Literal["ready", "pending", "unknown"]
    revision: str | None = Field(pattern=r"^[a-f0-9]{64}$")
    acknowledgedMessages: int = Field(ge=0, le=MAX_HISTORY_MESSAGES)
    reason: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9-]{0,95}$")


class ChatContextState(_Projection):
    schemaVersion: Literal[1]
    status: Literal["ready", "missing", "busy", "unavailable"]
    sessionRevision: str | None = Field(max_length=160, pattern=r"^[A-Za-z0-9:_-]+$")
    context: ContextUsage | None
    model: ContextModel | None
    compaction: CompactionState
    history: HistoryState


def public_context(value):
    state = ChatContextState.model_validate(value)
    if state.context and state.model and state.context.window != state.model.contextWindow:
        raise ValueError("Context measurement does not belong to the active model")
    result = state.model_dump(exclude_none=True)
    # These explicit nulls distinguish unavailable measurements from zero.
    for key in ("sessionRevision", "context", "model"):
        if getattr(state, key) is None:
            result[key] = None
    result["history"]["revision"] = state.history.revision
    return result