브라우저가 보낼 것과 받을 것을
따로 못 박는다

전체 구조에서의 위치

이 파일에는 함수가 하나도 없다. 변환은 routes/chat.py가 하고, 이 파일은 “무엇이 올바른 모양인가”만 선언한다.

전체 코드

from typing import Final, Literal

from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator

from app.engines.base import InferenceErrorCode


# TurboFieldfareServer owns the real limit (--max-context, default 16384 tokens) and
# reports context_too_long. FastAPI cannot tokenize, so these character caps are only
# a coarse guard: they stop absurd payloads before an 8 GB machine tokenizes them,
# and stay far above any conversation that would actually fit.
_MAX_MESSAGES: Final = 100
_MAX_MESSAGE_CHARS: Final = 16_000
_MAX_TOTAL_CHARS: Final = 64_000


class ChatContract(BaseModel):
    """Browser-facing JSON, deliberately separate from the engine contract."""

    model_config = ConfigDict(frozen=True, extra="forbid")


class ChatMessage(ChatContract):
    role: Literal["system", "user", "assistant"]
    content: str = Field(min_length=1, max_length=_MAX_MESSAGE_CHARS)

    @field_validator("content")
    @classmethod
    def require_visible_text(cls, value: str) -> str:
        """Trim the edges; whitespace alone carries nothing for the model to answer."""
        trimmed = value.strip()
        if not trimmed:
            raise ValueError("content must contain visible characters")
        return trimmed


class ChatRequest(ChatContract):
    """One stateless turn; the client resends the whole conversation."""

    messages: tuple[ChatMessage, ...] = Field(
        min_length=1, max_length=_MAX_MESSAGES
    )

    @model_validator(mode="after")
    def limit_conversation_size(self) -> "ChatRequest":
        """Reject payloads no context window could hold, before the model sees them."""
        total = sum(len(message.content) for message in self.messages)
        if total > _MAX_TOTAL_CHARS:
            raise ValueError(
                f"conversation is {total} characters, over the {_MAX_TOTAL_CHARS} limit"
            )
        return self


class ChatUsage(ChatContract):
    input_tokens: int = Field(ge=0)
    output_tokens: int = Field(ge=0)
    total_tokens: int = Field(ge=0)
    cached_input_tokens: int = Field(ge=0)


class ChatResponse(ChatContract):
    """What the browser receives; the server keeps none of it."""

    id: str
    model: str
    text: str
    finish_reason: Literal["stop", "length"]
    usage: ChatUsage


class ChatError(ChatContract):
    """Only the stable code; upstream wording never reaches the browser."""

    error_code: InferenceErrorCode

ChatContract — 네 class의 부모

class ChatContract(BaseModel):
    """Browser-facing JSON, deliberately separate from the engine contract."""

    model_config = ConfigDict(frozen=True, extra="forbid")

base.py의 Contract와 설정이 같다. 그래도 상속하지 않고 따로 둔 것이 분리의 실체다. 상속했다면 base.py의 설정을 바꿀 때 브라우저 API 동작까지 같이 바뀐다.

입력 상한 — 숫자를 어떻게 정했나

# TurboFieldfareServer owns the real limit (--max-context, default 16384 tokens) and
# reports context_too_long. FastAPI cannot tokenize, so these character caps are only
# a coarse guard: they stop absurd payloads before an 8 GB machine tokenizes them,
# and stay far above any conversation that would actually fit.
_MAX_MESSAGES: Final = 100
_MAX_MESSAGE_CHARS: Final = 16_000
_MAX_TOTAL_CHARS: Final = 64_000

FastAPI에는 tokenizer가 없다. 그래서 “이 대화가 문맥에 들어가는가”를 판단할 수 없다. 문자 수는 토큰 수의 나쁜 대리 지표다 — 영어는 토큰당 약 4자, 한국어는 약 1.5자다.

그래서 상한을 일부러 느슨하게 잡았다. 조이면 실제로는 들어갈 대화를 우리가 잘못 거부한다. 판정은 두 층으로 갈린다.

서버 기본값은 --max-context 16384 토큰이다. 64,000자는 그 문맥이 담을 수 있는 양보다 위에 있어서, 정상적인 대화가 이 상한에 먼저 걸리는 일은 없다.

ChatMessage — 공백만 있는 메시지를 막는다

class ChatMessage(ChatContract):
    role: Literal["system", "user", "assistant"]
    content: str = Field(min_length=1, max_length=_MAX_MESSAGE_CHARS)

    @field_validator("content")
    @classmethod
    def require_visible_text(cls, value: str) -> str:
        """Trim the edges; whitespace alone carries nothing for the model to answer."""
        trimmed = value.strip()
        if not trimmed:
            raise ValueError("content must contain visible characters")
        return trimmed

ChatRequest — 대화 전체 크기를 본다

class ChatRequest(ChatContract):
    """One stateless turn; the client resends the whole conversation."""

    messages: tuple[ChatMessage, ...] = Field(
        min_length=1, max_length=_MAX_MESSAGES
    )

    @model_validator(mode="after")
    def limit_conversation_size(self) -> "ChatRequest":
        """Reject payloads no context window could hold, before the model sees them."""
        total = sum(len(message.content) for message in self.messages)
        if total > _MAX_TOTAL_CHARS:
            raise ValueError(
                f"conversation is {total} characters, over the {_MAX_TOTAL_CHARS} limit"
            )
        return self

ChatResponse와 ChatError — 돌려주는 것

class ChatResponse(ChatContract):
    """What the browser receives; the server keeps none of it."""

    id: str
    model: str
    text: str
    finish_reason: Literal["stop", "length"]
    usage: ChatUsage


class ChatError(ChatContract):
    """Only the stable code; upstream wording never reaches the browser."""

    error_code: InferenceErrorCode

ChatError가 base.py의 InferenceErrorCode를 그대로 가져다 쓴다. 오류 코드가 늘면 응답 schema가 자동으로 따라간다. schemas/system.py가 이미 쓰던 방식이다.

거부되는 입력 — 실제 응답

{"messages":[{"role":"user","content":"   "}]}
  → 422  Value error, content must contain visible characters

{"messages":[{"role":"user","content":"  안녕  "}]}
  → 검증 통과. 엔진에는 "안녕" 으로 도착

{"messages":[{"role":"user","content":"x"*16001}]}
  → 422  String should have at most 16000 characters

{"messages":[...], "max_output_tokens":4096}
  → 422  extra="forbid" 가 거부. 생성 옵션은 서버가 소유

네 경우 모두 추론 엔진이 호출되지 않는다. 8GB 환경에서 30초짜리 생성을 낭비하지 않으려면 거절이 최대한 앞에서 일어나야 한다.

자주 발생하는 오류

설계 선택과 대안

이전 단계와 다음 파일

이 계약을 실제로 변환하는 코드는 routes/chat.py에 있다. 변환 대상인 내부 계약은 engines/base.py, 같은 방식으로 만들어진 상태 endpoint 계약은 schemas/system.py에서 읽는다.