from __future__ import annotations

import copy
from typing import Any


_MAPPINGS: list[dict[str, Any]] = [
    # === OpenAI (chat_completions) ===
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "common",
        "from": "params.idempotency_key",
        "to": "header.Idempotency-Key",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "params.temperature",
        "to": "body.temperature",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "params.top_p",
        "to": "body.top_p",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "params.seed",
        "to": "body.seed",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "params.reasoning.effort",
        "to": "body.reasoning_effort",
        "notes": "reasoning models（如 gpt-5/o 系列）",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "output.text.max_output_tokens | params.max_output_tokens",
        "to": "body.max_completion_tokens",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "params.stop",
        "to": "body.stop",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "provider_options['openai']",
        "to": "body.* (merge)",
        "notes": "显式透传；禁止覆盖 SDK 已设置字段",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "output.text.format/json_schema",
        "to": "body.response_format",
        "notes": "json_object/json_schema（text-only）",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "input[].text",
        "to": "messages[].content[].{type:text}",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "input[].image(bytes/path/url)",
        "to": "messages[].content[].{type:image_url}",
        "notes": "bytes/path 会内联为 data:...;base64",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "input[].audio(bytes/path/url)",
        "to": "messages[].content[].{type:input_audio}",
        "notes": "bytes/path/url 会转 base64；format 由 mime 推断(wav/mp3/m4a)",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "chat",
        "from": "output.modalities includes audio + output.audio.voice/format",
        "to": "body.modalities/body.audio",
        "notes": "音频输出为 message.audio(data base64 + transcript)",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "images",
        "from": "output.image.n",
        "to": "body.n",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "images",
        "from": "output.image.size",
        "to": "body.size",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "images",
        "from": "output.image.format",
        "to": "body.response_format",
        "notes": "url | b64_json（bytes/base64 会落到 b64_json）",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "images",
        "from": "provider_options['openai']",
        "to": "body.* (merge)",
        "notes": "显式透传 OpenAI 私参（quality/style/background 等）",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "embeddings",
        "from": "input[].text",
        "to": "body.input",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "embeddings",
        "from": "output.embedding.dimensions",
        "to": "body.dimensions",
        "notes": "仅 text-embedding-3-*",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "embeddings",
        "from": "provider_options['openai']",
        "to": "body.* (merge)",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "tts",
        "from": "output.audio.voice",
        "to": "body.voice",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "tts",
        "from": "output.audio.format",
        "to": "body.response_format",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "tts",
        "from": "input[].text",
        "to": "body.input",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "tts",
        "from": "provider_options['openai']",
        "to": "body.* (merge)",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "transcription",
        "from": "input[].audio",
        "to": "multipart.file",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "transcription",
        "from": "params.temperature",
        "to": "multipart.temperature",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "transcription",
        "from": "audio.meta.language",
        "to": "multipart.language",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "transcription",
        "from": "audio.meta.transcription_prompt | text(meta.transcription_prompt=true)",
        "to": "multipart.prompt",
        "notes": "默认不自动采集任意 text part（避免意外影响转写）",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "transcription",
        "from": "provider_options['openai']",
        "to": "multipart.* (merge)",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "video",
        "from": "output.video.duration_sec",
        "to": "body.seconds",
        "notes": "4/8/12 秒就近取值",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "video",
        "from": "output.video.aspect_ratio",
        "to": "body.size",
        "notes": "16:9/9:16 预置映射",
    },
    {
        "provider": "openai",
        "protocol": "chat_completions",
        "operation": "video",
        "from": "provider_options['openai']",
        "to": "body.* (merge)",
    },
    # === OpenAI (responses) ===
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "common",
        "from": "params.idempotency_key",
        "to": "header.Idempotency-Key",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "params.temperature",
        "to": "body.temperature",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "params.top_p",
        "to": "body.top_p",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "params.reasoning.effort",
        "to": "body.reasoning.effort",
        "notes": "reasoning models（如 gpt-5/o 系列）",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "output.text.max_output_tokens | params.max_output_tokens",
        "to": "body.max_output_tokens",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "output.text.format/json_schema",
        "to": "body.text.format",
        "notes": "json_object/json_schema（text-only）",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "input[].text",
        "to": "body.input[].content[].{type:input_text}",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "input[].image(bytes/path/url)",
        "to": "body.input[].content[].{type:input_image}",
        "notes": "bytes/path 会内联为 data:...;base64",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "params.seed / params.stop",
        "to": "not mapped",
        "notes": "OpenAI /responses 当前会返回 unknown_parameter",
    },
    {
        "provider": "openai",
        "protocol": "responses",
        "operation": "chat",
        "from": "provider_options['openai']",
        "to": "body.* (merge)",
        "notes": "显式透传；禁止覆盖 SDK 已设置字段",
    },
    # === Google AI Studio (Gemini Developer API) ===
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "params.temperature",
        "to": "generationConfig.temperature",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "params.top_p",
        "to": "generationConfig.topP",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "params.seed",
        "to": "generationConfig.seed",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "params.reasoning.effort",
        "to": "generationConfig.thinkingConfig.thinkingLevel | thinkingBudget(fallback)",
        "notes": "Gemini 3+ 优先 thinkingLevel（3 Pro 仅 low/high；3 Flash 支持 minimal/medium）；Gemini 2.5 / Robotics-ER 走 thinkingBudget；其他型号忽略",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "output.text.max_output_tokens | params.max_output_tokens",
        "to": "generationConfig.maxOutputTokens",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "params.stop",
        "to": "generationConfig.stopSequences",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "output.text.format/json_schema",
        "to": "generationConfig.responseMimeType/responseSchema",
        "notes": "application/json（text-only）",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "output.modalities",
        "to": "generationConfig.responseModalities",
        "notes": "TEXT/IMAGE/AUDIO（不支持 VIDEO 输出）",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "output.image.n",
        "to": "generationConfig.candidateCount",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "output.image.size",
        "to": "generationConfig.imageConfig.imageSize",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "output.audio.voice/language",
        "to": "generationConfig.speechConfig",
        "notes": "voiceName + languageCode",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "input[].(image/audio/video) path/url/bytes/ref",
        "to": "inlineData | fileData(fileUri)",
        "notes": "大文件会走 Files API 上传并等待 ACTIVE",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "generate",
        "from": "provider_options['google'|'gemini']",
        "to": "body.* / generationConfig.* (merge)",
        "notes": "显式透传；禁止覆盖 SDK 已设置字段",
    },
    {
        "provider": "google",
        "protocol": "gemini",
        "operation": "embedding",
        "from": "output.embedding.dimensions",
        "to": "outputDimensionality",
    },
    # === Anthropic (messages) ===
    {
        "provider": "anthropic",
        "protocol": "messages",
        "operation": "chat",
        "from": "params.reasoning.effort",
        "to": "body.thinking",
        "notes": "effort 映射到 thinking.enabled.budget_tokens（none 不传 thinking）",
    },
    # === OpenAI-compatible providers ===
    {
        "provider": "volcengine",
        "protocol": "chat_completions",
        "operation": "chat/embeddings/images",
        "from": "same as openai/chat_completions (subset)",
        "to": "same as openai/chat_completions (subset)",
        "notes": "Base URL 默认 https://ark.cn-beijing.volces.com/api/v3；API key=VOLCENGINE_API_KEY",
    },
    {
        "provider": "aliyun",
        "protocol": "chat_completions",
        "operation": "chat/embeddings",
        "from": "same as openai/chat_completions (subset)",
        "to": "same as openai/chat_completions (subset)",
        "notes": "Base URL 默认 https://dashscope.aliyuncs.com/compatible-mode/v1；API key=ALIYUN_API_KEY",
    },
    {
        "provider": "tuzi-openai",
        "protocol": "chat_completions",
        "operation": "chat/images/audio/embeddings",
        "from": "same as openai/chat_completions (subset)",
        "to": "same as openai/chat_completions (subset)",
        "notes": "Base URL 默认 https://api.tu-zi.com/v1；API key=TUZI_OPENAI_API_KEY（tuzi-web 则为 TUZI_WEB_API_KEY）",
    },
]


def get_parameter_mappings() -> list[dict[str, Any]]:
    """
    Return a JSON-friendly table of the current unified-params -> provider-params mapping.
    """
    return copy.deepcopy(_MAPPINGS)
