nous-genai 0.1.0__py3-none-any.whl

nous/genai/reference/mappings.py

@@ -0,0 +1,467 @@
+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)

nous/genai/reference/mode_overrides.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class CapabilityOverride(TypedDict, total=False):
+    supports_stream: bool
+    supports_job: bool
+
+
+CAPABILITY_OVERRIDES: dict[str, dict[str, CapabilityOverride]] = {
+    # NOTE: Keep this table small and explicit.
+    #
+    # Purpose:
+    # - Fix known capability inference mistakes from heuristic `Adapter.capabilities(model_id)`.
+    # - Provide a reviewable, auditable source of truth for edge models.
+    #
+    # Keying:
+    # - provider: normalized lower-case provider name (e.g. "tuzi-web")
+    # - model_id: exact catalog model id string (case-sensitive)
+    #
+    # Example:
+    # "tuzi-web": {
+    #     "some-model-id": {"supports_stream": False, "supports_job": True},
+    # },
+}

nous/genai/reference/model_catalog.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+# Curated model catalog used by demos/CLI.
+#
+# Catalog only lists model ids per provider.
+# Capabilities (and display categories) are inferred at runtime from Adapter.capabilities().
+
+from .model_catalog_data.aliyun import MODELS as ALIYUN_MODELS
+from .model_catalog_data.anthropic import MODELS as ANTHROPIC_MODELS
+from .model_catalog_data.google import MODELS as GOOGLE_MODELS
+from .model_catalog_data.openai import MODELS as OPENAI_MODELS
+from .model_catalog_data.tuzi_anthropic import MODELS as TUZI_ANTHROPIC_MODELS
+from .model_catalog_data.tuzi_google import MODELS as TUZI_GOOGLE_MODELS
+from .model_catalog_data.tuzi_openai import MODELS as TUZI_OPENAI_MODELS
+from .model_catalog_data.tuzi_web import MODELS as TUZI_WEB_MODELS
+from .model_catalog_data.volcengine import MODELS as VOLCENGINE_MODELS
+
+
+MODEL_CATALOG: dict[str, list[str]] = {
+    "openai": OPENAI_MODELS,
+    "anthropic": ANTHROPIC_MODELS,
+    "google": GOOGLE_MODELS,
+    "volcengine": VOLCENGINE_MODELS,
+    "aliyun": ALIYUN_MODELS,
+    "tuzi-web": TUZI_WEB_MODELS,
+    "tuzi-openai": TUZI_OPENAI_MODELS,
+    "tuzi-google": TUZI_GOOGLE_MODELS,
+    "tuzi-anthropic": TUZI_ANTHROPIC_MODELS,
+}
+
+
+SUPPORTED_TESTS: dict[str, list[str]] = {
+    "openai": [
+        "chat",
+        "tools",
+        "transcription",
+        "image",
+        "video",
+        "audio",
+        "embedding",
+    ],
+    "anthropic": ["chat", "tools"],
+    "google": [
+        "chat",
+        "tools",
+        "transcription",
+        "image",
+        "video",
+        "audio",
+        "embedding",
+    ],
+    "volcengine": ["chat", "image", "video", "embedding"],
+    "aliyun": ["chat", "transcription", "image", "video", "audio", "embedding"],
+    "tuzi-web": [
+        "chat",
+        "tools",
+        "transcription",
+        "image",
+        "video",
+        "audio",
+        "embedding",
+    ],
+    "tuzi-openai": [
+        "chat",
+        "tools",
+        "transcription",
+        "image",
+        "video",
+        "audio",
+        "embedding",
+    ],
+    "tuzi-google": [
+        "chat",
+        "tools",
+        "transcription",
+        "image",
+        "video",
+        "audio",
+        "embedding",
+    ],
+    "tuzi-anthropic": ["chat", "tools"],
+}

nous/genai/reference/model_catalog_data/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

nous/genai/reference/model_catalog_data/aliyun.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+MODELS: list[str] = [
+    "deepseek-v3",
+    "deepseek-v3.1",
+    "deepseek-v3.2",
+    "kimi-k2-thinking",
+    "qvq-max",
+    "qvq-plus",
+    "qwen-1.8b-chat",
+    "qwen-1.8b-longcontext-chat",
+    "qwen-14b-chat",
+    "qwen-72b-chat",
+    "qwen-7b-chat",
+    "qwen-coder-plus",
+    "qwen-coder-turbo",
+    "qwen-deep-search-planning",
+    "qwen-flash",
+    "qwen-flash-character",
+    "qwen-long",
+    "qwen-math-plus",
+    "qwen-math-turbo",
+    "qwen-max",
+    "qwen-max-longcontext",
+    "qwen-mt-flash",
+    "qwen-mt-lite",
+    "qwen-mt-plus",
+    "qwen-mt-turbo",
+    "qwen-omni-turbo",
+    "qwen-plus",
+    "qwen-turbo",
+    "qwen-vl-max",
+    "qwen-vl-ocr",
+    "qwen-vl-plus",
+    "qwen1.5-0.5b-chat",
+    "qwen1.5-1.8b-chat",
+    "qwen1.5-110b-chat",
+    "qwen1.5-14b-chat",
+    "qwen1.5-32b-chat",
+    "qwen1.5-72b-chat",
+    "qwen1.5-7b-chat",
+    "qwen2-0.5b-instruct",
+    "qwen2-1.5b-instruct",
+    "qwen2-57b-a14b-instruct",
+    "qwen2-7b-instruct",
+    "qwen2.5-0.5b-instruct",
+    "qwen2.5-1.5b-instruct",
+    "qwen2.5-14b-instruct",
+    "qwen2.5-14b-instruct-1m",
+    "qwen2.5-32b-instruct",
+    "qwen2.5-3b-instruct",
+    "qwen2.5-72b-instruct",
+    "qwen2.5-7b-instruct",
+    "qwen2.5-7b-instruct-1m",
+    "qwen2.5-coder-0.5b-instruct",
+    "qwen2.5-coder-14b-instruct",
+    "qwen2.5-coder-32b-instruct",
+    "qwen2.5-coder-3b-instruct",
+    "qwen2.5-coder-7b-instruct",
+    "qwen2.5-math-1.5b-instruct",
+    "qwen2.5-math-72b-instruct",
+    "qwen2.5-math-7b-instruct",
+    "qwen2.5-vl-32b-instruct",
+    "qwen3-0.6b",
+    "qwen3-1.7b",
+    "qwen3-14b",
+    "qwen3-235b-a22b",
+    "qwen3-235b-a22b-instruct-2507",
+    "qwen3-235b-a22b-thinking-2507",
+    "qwen3-30b-a3b",
+    "qwen3-30b-a3b-instruct-2507",
+    "qwen3-30b-a3b-thinking-2507",
+    "qwen3-32b",
+    "qwen3-4b",
+    "qwen3-8b",
+    "qwen3-coder-480b-a35b-instruct",
+    "qwen3-coder-flash",
+    "qwen3-coder-plus",
+    "qwen3-livetranslate-flash",
+    "qwen3-livetranslate-flash-realtime",
+    "qwen3-max-preview",
+    "qwen3-next-80b-a3b-instruct",
+    "qwen3-next-80b-a3b-thinking",
+    "qwen3-omni-flash",
+    "qwen3-omni-flash-realtime",
+    "qwen3-vl-flash",
+    "qwen3-vl-plus",
+    "qwq-plus",
+    "qwen3-asr-flash-realtime",
+    "qwen-image-edit-plus",
+    "qwen-image-max",
+    "z-image-turbo",
+    "qwen-tts",
+    "qwen3-tts-flash",
+    "qwen3-tts-flash-realtime",
+    "qwen3-tts-vc-realtime",
+    "qwen3-tts-vd-realtime",
+]

nous/genai/reference/model_catalog_data/anthropic.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+MODELS: list[str] = [
+    "claude-haiku-4",
+    "claude-haiku-4-5",
+    "claude-opus-4",
+    "claude-opus-4-5",
+    "claude-sonnet-4",
+    "claude-sonnet-4-5",
+]