"""What AI Labs offers, in code.

This module is the single source of truth for every model id, every option
value and every limit the surface exposes. It is code rather than a table
for the same reason the achievement catalogue is: the *meaning* of an entry
lives in the executor that reads it, so a DB row could never be the whole
definition, and a config table would let production drift from the code that
interprets it.

**Every value here was measured against the live Singapore endpoint on the
date its entry records — nothing is copied from documentation.** That
discipline earned its keep twice while this file was being written:

* ``wan3.0-video-prime`` **silently ignores the ``size`` parameter.** Three
  submissions on 2026-09-03 asking for ``1280*720``, ``960*960`` and
  ``720*1280`` all succeeded and all reported an output ratio unrelated to
  the request (``1:1``, ``16:9``, ``16:9`` respectively), with ``SR`` pinned
  at 1080 every time. So this catalogue exposes **no aspect-ratio control**
  for video: shipping a dropdown that changes nothing would be worse than
  shipping none. ``resolution`` *is* honoured (``480P`` → SR 480, ``1080P``
  → SR 1080), so that is the one quality knob offered.
* Half the plausible model ids were returning ``403
  AllocationQuota.FreeTierOnly`` because of a per-model console switch, not
  because they were unavailable. Picking "a stable older model" from the
  docs would have shipped a dead capability. See
  :mod:`app.domains.bailian.media_client` for the full story.

``server/scripts/verify_ai_labs_catalog.py`` re-checks this file against the
configured key and prints a per-entry verdict. Run it when adding an entry,
and after any Bailian console change.
"""
from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any

from app.domains.bailian.media_client import (
    PATH_MULTIMODAL,
    PATH_VIDEO,
)

#: Bump when an entry is added, removed or re-pointed. Surfaced by the admin
#: console so an operator can tell which catalogue a deployment is serving.
CATALOG_VERSION = "2026-09-03.2"


# ── chat models ────────────────────────────────────────────────

#: Tier drives ordering and the badge the UI shows. Not a capability claim.
TIER_FLAGSHIP = "flagship"
TIER_FAST = "fast"
TIER_ALTERNATIVE = "alternative"


@dataclass(frozen=True)
class ChatModel:
    """One selectable chat model."""

    #: Stable key stored on conversations. Re-pointing ``vendor_model`` later
    #: keeps existing threads working; renaming a key would orphan them.
    key: str
    vendor_model: str
    tier: str
    #: Who made it — the UI groups by this so "other vendors' models" is an
    #: honest label rather than everything looking like Qwen.
    vendor: str
    #: Verified by sending a real image part, not assumed from the name.
    supports_vision: bool
    #: Whether the vendor accepts ``enable_thinking``.
    supports_thinking: bool
    #: Our default for the toggle. False everywhere it is supported: the
    #: qwen3.7 family defaults to deep thinking and takes 15-18s to emit a
    #: first token, which reads as a broken page.
    default_thinking: bool
    verified_on: str
    #: Rough first-token latency measured on a one-line prompt, in seconds.
    #: Shown as a hint so an employee can pick "fast" deliberately.
    measured_ttfb_seconds: float | None = None


CHAT_MODELS: tuple[ChatModel, ...] = (
    ChatModel(
        key="qwen3.8-max", vendor_model="qwen3.8-max",
        tier=TIER_FLAGSHIP, vendor="qwen",
        supports_vision=True, supports_thinking=True, default_thinking=False,
        verified_on="2026-09-03", measured_ttfb_seconds=2.3,
    ),
    ChatModel(
        key="qwen3.8-flash", vendor_model="qwen3.8-flash",
        tier=TIER_FAST, vendor="qwen",
        supports_vision=True, supports_thinking=True, default_thinking=False,
        verified_on="2026-09-03", measured_ttfb_seconds=3.8,
    ),
    ChatModel(
        key="qwen3-max", vendor_model="qwen3-max",
        tier=TIER_ALTERNATIVE, vendor="qwen",
        supports_vision=True, supports_thinking=True, default_thinking=False,
        verified_on="2026-09-03", measured_ttfb_seconds=2.1,
    ),
    ChatModel(
        key="qwen3-vl-plus", vendor_model="qwen3-vl-plus",
        tier=TIER_ALTERNATIVE, vendor="qwen",
        supports_vision=True, supports_thinking=True, default_thinking=False,
        verified_on="2026-09-03",
    ),
    ChatModel(
        key="deepseek-v4-pro", vendor_model="deepseek-v4-pro",
        tier=TIER_ALTERNATIVE, vendor="deepseek",
        supports_vision=True, supports_thinking=True, default_thinking=False,
        verified_on="2026-09-03", measured_ttfb_seconds=11.4,
    ),
    ChatModel(
        key="glm-5.2", vendor_model="glm-5.2",
        tier=TIER_ALTERNATIVE, vendor="zhipu",
        supports_vision=True, supports_thinking=True, default_thinking=False,
        verified_on="2026-09-03", measured_ttfb_seconds=16.5,
    ),
    ChatModel(
        key="kimi-k3", vendor_model="kimi-k3",
        tier=TIER_ALTERNATIVE, vendor="moonshot",
        supports_vision=True, supports_thinking=True, default_thinking=False,
        verified_on="2026-09-03", measured_ttfb_seconds=10.4,
    ),
)

CHAT_MODELS_BY_KEY: dict[str, ChatModel] = {m.key: m for m in CHAT_MODELS}

#: What a new conversation gets. Flagship, thinking off — fastest first
#: token of the strong models (2.3s measured).
DEFAULT_CHAT_MODEL_KEY = "qwen3.8-max"


def chat_model(key: str | None) -> ChatModel:
    """Resolve a stored/requested key, falling back to the default.

    Never raises: a conversation whose model was removed from the catalogue
    must keep opening, and an unknown key from a client is a validation
    concern for the router, not a reason to 500 a history read.
    """
    if key and key in CHAT_MODELS_BY_KEY:
        return CHAT_MODELS_BY_KEY[key]
    return CHAT_MODELS_BY_KEY[DEFAULT_CHAT_MODEL_KEY]


# ── generation capabilities ────────────────────────────────────

CAP_IMAGE = "image"
CAP_IMAGE_EDIT = "image_edit"
CAP_VIDEO = "video"
CAP_SPEECH = "speech"
CAP_TRANSCRIBE = "transcribe"

#: How the executor talks to the vendor for a capability.
TRANSPORT_SYNC = "sync_multimodal"
TRANSPORT_ASYNC = "async_task"

#: What lands on the row when the job succeeds.
OUTPUT_IMAGE = "image"
OUTPUT_VIDEO = "video"
OUTPUT_AUDIO = "audio"
OUTPUT_TEXT = "text"

#: What the employee may attach as input.
INPUT_NONE = "none"
INPUT_IMAGE = "image"
INPUT_AUDIO = "audio"


@dataclass(frozen=True)
class Option:
    """One selectable value of a generation parameter."""

    value: Any
    #: Suffix of the i18n key the frontend renders
    #: (``aiLabs.option.<param>.<label>``). Never a display string — this
    #: module must not contain user-facing text.
    label: str
    #: Only for entries whose acceptance was individually measured.
    verified_on: str | None = None


@dataclass(frozen=True)
class Param:
    """One generation parameter and its closed set of allowed values."""

    name: str
    options: tuple[Option, ...]
    default: Any
    #: Sent to the vendor under this name. Usually identical; kept explicit
    #: so a vendor rename does not force a stored-value migration.
    vendor_name: str | None = None

    @property
    def wire_name(self) -> str:
        return self.vendor_name or self.name

    def allowed_values(self) -> tuple[Any, ...]:
        return tuple(option.value for option in self.options)


@dataclass(frozen=True)
class GenerationCapability:
    """One media capability: which model, which transport, which options."""

    key: str
    vendor_model: str
    transport: str
    output_kind: str
    #: Async transports only.
    task_path: str | None = None
    #: Whether the employee's prompt is required, optional or unused.
    prompt_required: bool = True
    #: Cap on prompt length. Generous — the point is to stop a paste of a
    #: whole document into an image prompt, not to edit anyone's wording.
    prompt_max_chars: int = 4000
    input_kind: str = INPUT_NONE
    min_inputs: int = 0
    max_inputs: int = 0
    params: tuple[Param, ...] = ()
    #: Highest number of artifacts one job may produce.
    max_outputs: int = 1
    #: Wall-clock ceiling before the reaper gives up on a job, in seconds.
    #: Measured worst case x ~4: a 1080p/10s clip took 95s, so 600s is
    #: generous while still bounded.
    deadline_seconds: int = 600
    #: Slowest measured end-to-end completion, for the UI's expectation
    #: setting ("usually under a minute").
    measured_seconds: int | None = None
    verified_on: str = ""
    #: Extra fixed parameters always sent to the vendor. ``prompt_extend``
    #: is pinned OFF everywhere: it is the vendor rewriting the employee's
    #: prompt, and this product promises not to do that.
    fixed_params: dict[str, Any] = field(default_factory=dict)

    def param(self, name: str) -> Param | None:
        for candidate in self.params:
            if candidate.name == name:
                return candidate
        return None


#: Image sizes, each individually submitted and confirmed to come back at
#: exactly the requested pixel dimensions (2026-09-03, 7.3-9.3s each).
_IMAGE_SIZES = Param(
    name="size",
    options=(
        Option("1024*1024", "square", "2026-09-03"),
        Option("1664*928", "landscape", "2026-09-03"),
        Option("928*1664", "portrait", "2026-09-03"),
        Option("1472*1140", "classic", "2026-09-03"),
    ),
    default="1024*1024",
)

#: Video quality. ``resolution`` is the parameter the model actually honours
#: — see the module docstring for why ``size`` is absent. All three were
#: rendered end-to-end and the vendor's reported ``SR`` matched the request
#: every time (480P→480 in 36s, 720P→720 in 36s, 1080P→1080 in 51s, each a
#: 5-second clip on 2026-09-03).
_VIDEO_RESOLUTION = Param(
    name="resolution",
    options=(
        Option("480P", "sd", "2026-09-03"),
        Option("720P", "hd", "2026-09-03"),
        Option("1080P", "fullhd", "2026-09-03"),
    ),
    default="720P",
)

#: Clip length. Both measured: 5s at 480P completed in 29s, 10s at 1080P in
#: 95s. The model advertises up to 30s; longer clips are not offered because
#: a 30s 1080p file runs to hundreds of megabytes, and every artifact is
#: re-homed through the backend's memory into S3.
_VIDEO_DURATION = Param(
    name="duration",
    options=(
        Option(5, "fiveSeconds", "2026-09-03"),
        Option(10, "tenSeconds", "2026-09-03"),
    ),
    default=5,
)

#: Voices, each individually synthesised and confirmed (2026-09-03).
#: ``Dylan`` was excluded: its probe came back rate-limited rather than
#: successful, so it is unverified, and an option that might 400 is worse
#: than one fewer voice.
_SPEECH_VOICE = Param(
    name="voice",
    options=(
        Option("Cherry", "cherry", "2026-09-03"),
        Option("Serena", "serena", "2026-09-03"),
        Option("Ethan", "ethan", "2026-09-03"),
        Option("Chelsie", "chelsie", "2026-09-03"),
    ),
    default="Cherry",
)


GENERATION_CAPABILITIES: tuple[GenerationCapability, ...] = (
    GenerationCapability(
        key=CAP_IMAGE,
        vendor_model="qwen-image-3.0-pro",
        transport=TRANSPORT_SYNC,
        output_kind=OUTPUT_IMAGE,
        prompt_required=True,
        params=(_IMAGE_SIZES,),
        max_outputs=1,
        deadline_seconds=300,
        measured_seconds=9,
        verified_on="2026-09-03",
        fixed_params={"n": 1, "watermark": False, "prompt_extend": False},
    ),
    GenerationCapability(
        key=CAP_IMAGE_EDIT,
        vendor_model="qwen-image-edit-max",
        transport=TRANSPORT_SYNC,
        output_kind=OUTPUT_IMAGE,
        prompt_required=True,
        input_kind=INPUT_IMAGE,
        # The vendor's own bound, quoted verbatim in its 400: "the message
        # must contain 1~3 image content items".
        min_inputs=1,
        max_inputs=3,
        max_outputs=1,
        deadline_seconds=300,
        verified_on="2026-09-03",
        fixed_params={"watermark": False, "prompt_extend": False},
    ),
    GenerationCapability(
        key=CAP_VIDEO,
        vendor_model="wan3.0-video-prime",
        transport=TRANSPORT_ASYNC,
        task_path=PATH_VIDEO,
        output_kind=OUTPUT_VIDEO,
        prompt_required=True,
        prompt_max_chars=2000,
        # An optional reference image turns text-to-video into
        # image-to-video on the same model and endpoint.
        input_kind=INPUT_IMAGE,
        min_inputs=0,
        max_inputs=1,
        params=(_VIDEO_RESOLUTION, _VIDEO_DURATION),
        max_outputs=1,
        deadline_seconds=900,
        measured_seconds=95,
        verified_on="2026-09-03",
        fixed_params={"watermark": False, "prompt_extend": False},
    ),
    GenerationCapability(
        key=CAP_SPEECH,
        vendor_model="qwen3-tts-instruct-flash",
        transport=TRANSPORT_SYNC,
        output_kind=OUTPUT_AUDIO,
        prompt_required=True,
        # One vendor request per synthesis; long text is what a document
        # reader is for, not this.
        prompt_max_chars=1500,
        params=(_SPEECH_VOICE,),
        max_outputs=1,
        deadline_seconds=180,
        verified_on="2026-09-03",
    ),
    GenerationCapability(
        key=CAP_TRANSCRIBE,
        vendor_model="qwen3-asr-flash-2026-02-10",
        transport=TRANSPORT_SYNC,
        output_kind=OUTPUT_TEXT,
        prompt_required=False,
        # Zero, not the 4000-char default. The vendor request for this
        # capability is built from the audio alone — there is nowhere for a
        # prompt to go — and inheriting the default made the studio render
        # a 提示词 textarea with a character counter that did nothing:
        # anyone typing "output Traditional Chinese" or "identify
        # speakers" had it stored, echoed back on the tile, and silently
        # discarded. The frontend renders the field from
        # ``prompt_required || prompt_max_chars > 0``, so this is what
        # removes it, and the service now refuses a prompt here instead of
        # keeping one it will not use.
        prompt_max_chars=0,
        input_kind=INPUT_AUDIO,
        min_inputs=1,
        max_inputs=1,
        max_outputs=0,
        deadline_seconds=600,
        verified_on="2026-09-03",
    ),
)

CAPABILITIES_BY_KEY: dict[str, GenerationCapability] = {
    capability.key: capability for capability in GENERATION_CAPABILITIES
}


def capability(key: str) -> GenerationCapability | None:
    return CAPABILITIES_BY_KEY.get(key)


# ── translation ────────────────────────────────────────────────

#: Dedicated translation model. Not a chat model with an instruction bolted
#: on: the vendor takes the target language as a real parameter, which keeps
#: this surface honest about not editing the employee's text.
TRANSLATE_MODEL = "qwen-mt-plus"
TRANSLATE_VERIFIED_ON = "2026-09-03"
TRANSLATE_MAX_CHARS = 8000

#: Target languages. Every one was translated end-to-end on 2026-09-03 by
#: ``scripts/verify_ai_labs_catalog.py`` and returned real text in the
#: target script — "统一 IT 平台" → "unified IT platform" / "統合されたIT
#: プラットフォーム" / "통합 IT 플랫폼" / "منصة تكنولوجيا المعلومات" and so on.
#: ``label`` is an i18n key suffix, never display text.
TRANSLATE_LANGUAGES: tuple[Option, ...] = (
    Option("English", "en", "2026-09-03"),
    Option("Japanese", "ja", "2026-09-03"),
    Option("Chinese", "zh", "2026-09-03"),
    Option("Korean", "ko", "2026-09-03"),
    Option("French", "fr", "2026-09-03"),
    Option("German", "de", "2026-09-03"),
    Option("Spanish", "es", "2026-09-03"),
    Option("Russian", "ru", "2026-09-03"),
    Option("Portuguese", "pt", "2026-09-03"),
    Option("Italian", "it", "2026-09-03"),
    Option("Thai", "th", "2026-09-03"),
    Option("Vietnamese", "vi", "2026-09-03"),
    Option("Indonesian", "id", "2026-09-03"),
    Option("Arabic", "ar", "2026-09-03"),
)

TRANSLATE_LANGUAGE_VALUES: frozenset[str] = frozenset(
    option.value for option in TRANSLATE_LANGUAGES
)


# ── chat attachments ───────────────────────────────────────────

#: Image types accepted as a chat attachment or a generation input. Kept in
#: step with the platform upload allow-list; a type here that the presign
#: endpoint refuses would fail at upload time with a confusing message.
CHAT_IMAGE_CONTENT_TYPES: frozenset[str] = frozenset({
    "image/jpeg", "image/png", "image/webp",
})

#: Document types whose text the server extracts and attaches. PDF via
#: ``pypdf``, .docx via ``python-docx``, .xlsx via ``openpyxl``, the rest
#: read directly.
DOCUMENT_CONTENT_TYPES: frozenset[str] = frozenset({
    "application/pdf",
    (
        "application/vnd.openxmlformats-officedocument"
        ".wordprocessingml.document"
    ),
    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "text/plain",
    "text/markdown",
    "text/csv",
})

#: Audio types accepted for transcription.
AUDIO_CONTENT_TYPES: frozenset[str] = frozenset({
    "audio/mpeg", "audio/mp4", "audio/wav", "audio/x-wav",
    "audio/webm", "audio/aac", "audio/ogg",
})

#: Characters of extracted document text handed to the model per attachment.
#: The window is ~258 K tokens, so this is not a vendor limit — it is a cost
#: and latency bound, and a signal to the employee that a 500-page PDF is
#: not what this surface is for. The truncation is disclosed in the UI, not
#: silent.
DOCUMENT_TEXT_MAX_CHARS = 120_000

#: Server-side backstop for one attachment of any kind, read after the
#: object is fetched. Deliberately the LARGEST of the per-purpose caps
#: below: the presign flow is the real gate, and this only catches an
#: object written by some other path.
MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024

#: The cap the browser is actually held to, per upload purpose. These are
#: not one number: ``storage_uploads.PURPOSE_MAX_BYTES`` narrows each
#: purpose separately, so publishing a single figure told the employee
#: 20 MB and then refused their 12 MB photo at presign time with a generic
#: 413 — a limit stated in the UI that was not the limit enforced. The
#: values MUST match ``PURPOSE_MAX_BYTES``; a contract test asserts it.
ATTACHMENT_BYTES_BY_PURPOSE: dict[str, int] = {
    "ai_labs_image": 10 * 1024 * 1024,
    "ai_labs_document": 20 * 1024 * 1024,
    "ai_labs_audio": 15 * 1024 * 1024,
}
#: Cap on attachments per turn.
MAX_ATTACHMENTS_PER_TURN = 6


# ── conversation shape ────────────────────────────────────────

#: Message ROWS of history sent to the vendor — roughly half this
#: many turns, since a turn is a question and a reply. Older turns stay readable in Helix
#: and simply stop being sent, which keeps a months-old thread cheap to
#: continue instead of quietly enormous.
MAX_HISTORY_MESSAGES = 40
#: Cap on one employee message.
MAX_MESSAGE_CHARS = 32_000
#: Tokens the model may produce per turn.
MAX_OUTPUT_TOKENS = 4000
#: Threads per person. Not a storage concern at 500 people; it bounds the
#: list query and stops a script from making the history page unusable.
MAX_CONVERSATIONS_PER_PERSON = 500


__all__ = [
    "AUDIO_CONTENT_TYPES",
    "CAPABILITIES_BY_KEY",
    "CAP_IMAGE",
    "CAP_IMAGE_EDIT",
    "CAP_SPEECH",
    "CAP_TRANSCRIBE",
    "CAP_VIDEO",
    "CATALOG_VERSION",
    "CHAT_IMAGE_CONTENT_TYPES",
    "CHAT_MODELS",
    "CHAT_MODELS_BY_KEY",
    "DEFAULT_CHAT_MODEL_KEY",
    "DOCUMENT_CONTENT_TYPES",
    "DOCUMENT_TEXT_MAX_CHARS",
    "GENERATION_CAPABILITIES",
    "INPUT_AUDIO",
    "INPUT_IMAGE",
    "INPUT_NONE",
    "MAX_ATTACHMENTS_PER_TURN",
    "ATTACHMENT_BYTES_BY_PURPOSE",
    "MAX_ATTACHMENT_BYTES",
    "MAX_CONVERSATIONS_PER_PERSON",
    "MAX_HISTORY_MESSAGES",
    "MAX_MESSAGE_CHARS",
    "MAX_OUTPUT_TOKENS",
    "OUTPUT_AUDIO",
    "OUTPUT_IMAGE",
    "OUTPUT_TEXT",
    "OUTPUT_VIDEO",
    "PATH_MULTIMODAL",
    "TIER_ALTERNATIVE",
    "TIER_FAST",
    "TIER_FLAGSHIP",
    "TRANSLATE_LANGUAGES",
    "TRANSLATE_LANGUAGE_VALUES",
    "TRANSLATE_MAX_CHARS",
    "TRANSLATE_MODEL",
    "TRANSLATE_VERIFIED_ON",
    "TRANSPORT_ASYNC",
    "TRANSPORT_SYNC",
    "ChatModel",
    "GenerationCapability",
    "Option",
    "Param",
    "capability",
    "chat_model",
]