nous-genai 0.1.0__py3-none-any.whl

nous/__init__.py

@@ -0,0 +1,3 @@
+"""
+Nous namespace package.
+"""

nous/genai/__init__.py

@@ -0,0 +1,56 @@
+from . import reference
+from ._internal.errors import ErrorInfo, GenAIError
+from .client import Client
+from .types import (
+    Capability,
+    GenerateEvent,
+    GenerateParams,
+    GenerateRequest,
+    GenerateResponse,
+    JobInfo,
+    Message,
+    OutputAudioSpec,
+    OutputEmbeddingSpec,
+    OutputImageSpec,
+    OutputSpec,
+    OutputTextSpec,
+    OutputVideoSpec,
+    Part,
+    PartSourceBytes,
+    PartSourcePath,
+    PartSourceRef,
+    PartSourceUrl,
+    ReasoningSpec,
+    Tool,
+    ToolChoice,
+    Usage,
+)
+
+__all__ = [
+    "Capability",
+    "Client",
+    "ErrorInfo",
+    "GenerateEvent",
+    "GenerateParams",
+    "GenerateRequest",
+    "GenerateResponse",
+    "GenAIError",
+    "JobInfo",
+    "Message",
+    "OutputAudioSpec",
+    "OutputEmbeddingSpec",
+    "OutputImageSpec",
+    "OutputSpec",
+    "OutputTextSpec",
+    "OutputVideoSpec",
+    "Part",
+    "PartSourceBytes",
+    "PartSourcePath",
+    "PartSourceRef",
+    "PartSourceUrl",
+    "ReasoningSpec",
+    "Tool",
+    "ToolChoice",
+    "Usage",
+    "reference",
+]

nous/genai/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

nous/genai/_internal/__init__.py

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

nous/genai/_internal/capability_rules.py

@@ -0,0 +1,476 @@
+"""
+Central place for capability rules based on model series (usually shared prefixes).
+
+Rules here only look at model_id strings and are provider-agnostic. Provider adapters
+still own protocol details (stream/job semantics, routing, endpoint quirks).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final, Literal
+
+from ..types import Modality
+
+ModelKind = Literal["video", "image", "embedding", "tts", "transcribe", "chat"]
+GeminiModelKind = Literal["video", "embedding", "tts", "native_audio", "image", "chat"]
+
+
+def _mods(*values: Modality) -> set[Modality]:
+    return set(values)
+
+
+def _norm(model_id: str) -> str:
+    return model_id.lower().strip()
+
+
+def _starts_with_any(s: str, prefixes: tuple[str, ...]) -> bool:
+    return s.startswith(prefixes)
+
+
+_TOKEN_SPLIT_RE: Final[re.Pattern[str]] = re.compile(r"[^a-z0-9]+")
+
+
+def _has_token(s: str, token: str) -> bool:
+    # Token boundary: split by any non [a-z0-9] to avoid substring false-positives.
+    toks = _TOKEN_SPLIT_RE.split(s.lower())
+    return token.lower() in toks
+
+
+# ---- Model series for /v1-style protocols ----
+
+_SORA_PREFIX: Final[str] = "sora-"
+
+_VEO_PREFIX: Final[str] = "veo"
+_PIKA_PREFIX: Final[str] = "pika-"
+_RUNWAY_PREFIX: Final[str] = "runway-"
+_SEEDANCE_PREFIXES: Final[tuple[str, ...]] = ("seedance", "doubao-seedance")
+_KLING_VIDEO_PREFIXES: Final[tuple[str, ...]] = ("kling_video", "kling-video-")
+
+_DALLE_PREFIX: Final[str] = "dall-e-"
+_GPT_IMAGE_PREFIX: Final[str] = "gpt-image-"
+_CHATGPT_IMAGE_PREFIX: Final[str] = "chatgpt-image"
+_SEEDREAM_PREFIXES: Final[tuple[str, ...]] = ("seedream", "doubao-seedream")
+_SEEDEDIT_PREFIXES: Final[tuple[str, ...]] = ("seededit", "api-images-seededit")
+_FLUX_PREFIXES: Final[tuple[str, ...]] = ("flux-", "flux.")
+_SD3_PREFIX: Final[str] = "sd3"
+
+_TEXT_EMBEDDING_PREFIX: Final[str] = "text-embedding-"
+_EMBEDDING_PREFIX: Final[str] = "embedding-"
+_DOUBAO_EMBEDDING_PREFIX: Final[str] = "doubao-embedding-"
+
+_TTS_PREFIX: Final[str] = "tts-"
+_TTS_SUFFIX: Final[str] = "-tts"
+_VOICE_SUFFIXES: Final[tuple[str, ...]] = ("-voice", "_voice")
+_ADVANCED_VOICE_MODEL: Final[str] = "advanced-voice"
+_SUNO_PREFIX: Final[str] = "suno-"
+_CHIRP_PREFIX: Final[str] = "chirp-"
+
+_WHISPER_PREFIX: Final[str] = "whisper-"
+_DISTIL_WHISPER_PREFIX: Final[str] = "distil-whisper-"
+_TRANSCRIBE_MARKER: Final[str] = "-transcribe"
+_ASR_PREFIX: Final[str] = "asr"
+
+_IMAGE_MODELS_WITH_IMAGE_INPUT_PREFIXES: Final[tuple[str, ...]] = (
+    "gpt-image-1",
+    "chatgpt-image",
+)
+
+_Z_IMAGE_PREFIX: Final[str] = "z-image"
+
+_CHAT_IMAGE_INPUT_EXACT: Final[tuple[str, ...]] = (
+    "chatgpt-4o-latest",
+    "codex-mini-latest",
+    "computer-use-preview",
+    "omni-moderation-latest",
+)
+
+_DEEPSEEK_V3_PREFIX: Final[str] = "deepseek-v3"
+_KIMI_K2_PREFIX: Final[str] = "kimi-k2"
+_KIMI_LATEST_PREFIX: Final[str] = "kimi-latest"
+_QWEN_PREFIX: Final[str] = "qwen"
+_QVQ_PREFIX: Final[str] = "qvq"
+
+_CHAT_NO_IMAGE_PREFIXES: Final[tuple[str, ...]] = (
+    _DEEPSEEK_V3_PREFIX,
+    _KIMI_K2_PREFIX,
+    _QVQ_PREFIX,
+)
+
+_CHAT_TEXT_ONLY_EXACT: Final[tuple[str, ...]] = (
+    "gpt-4",
+    "gpt-4-turbo-preview",
+    "o1-mini",
+    "o1-preview",
+    "o3-mini",
+)
+
+_CHAT_TEXT_ONLY_MARKERS: Final[tuple[str, ...]] = ("search-preview",)
+
+_CHAT_AUDIO_PREFIXES: Final[tuple[str, ...]] = ("gpt-audio", "gpt-realtime")
+_CHAT_AUDIO_SUFFIXES: Final[tuple[str, ...]] = ("-audio-preview", "-realtime-preview")
+
+_CLAUDE_PREFIX: Final[str] = "claude-"
+
+
+def is_sora_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_SORA_PREFIX)
+
+
+def is_veo_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_VEO_PREFIX)
+
+
+def is_pika_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_PIKA_PREFIX)
+
+
+def is_runway_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_RUNWAY_PREFIX)
+
+
+def is_seedance_model(model_id: str) -> bool:
+    return _starts_with_any(_norm(model_id), _SEEDANCE_PREFIXES)
+
+
+def is_kling_video_model(model_id: str) -> bool:
+    return _starts_with_any(_norm(model_id), _KLING_VIDEO_PREFIXES)
+
+
+def is_video_model(model_id: str) -> bool:
+    return (
+        is_sora_model(model_id)
+        or is_veo_model(model_id)
+        or is_pika_model(model_id)
+        or is_runway_model(model_id)
+        or is_seedance_model(model_id)
+        or is_kling_video_model(model_id)
+    )
+
+
+def is_dall_e_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_DALLE_PREFIX)
+
+
+def is_gpt_image_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_GPT_IMAGE_PREFIX)
+
+
+def is_chatgpt_image_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_CHATGPT_IMAGE_PREFIX)
+
+
+def is_seedream_model(model_id: str) -> bool:
+    return _starts_with_any(_norm(model_id), _SEEDREAM_PREFIXES)
+
+
+def is_seededit_model(model_id: str) -> bool:
+    return _starts_with_any(_norm(model_id), _SEEDEDIT_PREFIXES)
+
+
+def is_flux_model(model_id: str) -> bool:
+    return _starts_with_any(_norm(model_id), _FLUX_PREFIXES)
+
+
+def is_sd3_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_SD3_PREFIX)
+
+
+def is_z_image_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_Z_IMAGE_PREFIX)
+
+
+def is_gpt_dash_image_model(model_id: str) -> bool:
+    mid_l = _norm(model_id)
+    return mid_l.startswith("gpt-") and "-image" in mid_l
+
+
+def is_image_model(model_id: str) -> bool:
+    return (
+        is_dall_e_model(model_id)
+        or is_gpt_image_model(model_id)
+        or is_gpt_dash_image_model(model_id)
+        or is_chatgpt_image_model(model_id)
+        or is_z_image_model(model_id)
+        or is_seedream_model(model_id)
+        or is_seededit_model(model_id)
+        or is_flux_model(model_id)
+        or is_sd3_model(model_id)
+    )
+
+
+def is_text_embedding_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_TEXT_EMBEDDING_PREFIX)
+
+
+def is_embedding_series_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_EMBEDDING_PREFIX)
+
+
+def is_doubao_embedding_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_DOUBAO_EMBEDDING_PREFIX)
+
+
+def is_embedding_model(model_id: str) -> bool:
+    return (
+        is_text_embedding_model(model_id)
+        or is_embedding_series_model(model_id)
+        or is_doubao_embedding_model(model_id)
+    )
+
+
+def is_tts_model(model_id: str) -> bool:
+    mid_l = _norm(model_id)
+    return (
+        mid_l.startswith(_TTS_PREFIX)
+        or mid_l.startswith(_SUNO_PREFIX)
+        or mid_l.startswith(_CHIRP_PREFIX)
+        or mid_l.endswith(_TTS_SUFFIX)
+        or mid_l.endswith(_VOICE_SUFFIXES)
+        or mid_l == _ADVANCED_VOICE_MODEL
+    )
+
+
+def is_whisper_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_WHISPER_PREFIX)
+
+
+def is_distil_whisper_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_DISTIL_WHISPER_PREFIX)
+
+
+def is_transcribe_marker_model(model_id: str) -> bool:
+    return _TRANSCRIBE_MARKER in _norm(model_id)
+
+
+def is_asr_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_ASR_PREFIX)
+
+
+def is_transcribe_model(model_id: str) -> bool:
+    return (
+        is_whisper_model(model_id)
+        or is_distil_whisper_model(model_id)
+        or is_transcribe_marker_model(model_id)
+        or is_asr_model(model_id)
+    )
+
+
+def infer_model_kind(model_id: str) -> ModelKind:
+    if is_video_model(model_id):
+        return "video"
+    if is_image_model(model_id):
+        return "image"
+    if is_embedding_model(model_id):
+        return "embedding"
+    if is_tts_model(model_id):
+        return "tts"
+    if is_transcribe_model(model_id):
+        return "transcribe"
+    return "chat"
+
+
+def output_modalities_for_kind(kind: ModelKind) -> set[Modality] | None:
+    if kind == "video":
+        return _mods("video")
+    if kind == "image":
+        return _mods("image")
+    if kind == "embedding":
+        return _mods("embedding")
+    if kind == "tts":
+        return _mods("audio")
+    if kind == "transcribe":
+        return _mods("text")
+    return None
+
+
+def transcribe_input_modalities(_: str) -> set[Modality]:
+    return _mods("audio")
+
+
+def is_claude_model(model_id: str) -> bool:
+    return _norm(model_id).startswith(_CLAUDE_PREFIX)
+
+
+def claude_input_modalities(model_id: str) -> set[Modality]:
+    if is_claude_model(model_id):
+        return _mods("text", "image")
+    return _mods("text")
+
+
+def image_input_modalities(model_id: str) -> set[Modality]:
+    mid_l = _norm(model_id)
+    if _starts_with_any(
+        mid_l, _IMAGE_MODELS_WITH_IMAGE_INPUT_PREFIXES
+    ) or mid_l.startswith(_Z_IMAGE_PREFIX):
+        return _mods("text", "image")
+    return _mods("text")
+
+
+def video_input_modalities(model_id: str) -> set[Modality]:
+    if is_veo_model(model_id):
+        return _mods("text", "image")
+    return _mods("text")
+
+
+def chat_input_modalities(model_id: str) -> set[Modality]:
+    mid_l = _norm(model_id)
+    out: set[Modality] = {"text"}
+    if _chat_supports_image_input(mid_l):
+        out.add("image")
+    if _chat_supports_audio_input(mid_l):
+        out.add("audio")
+    return out
+
+
+def chat_output_modalities(model_id: str) -> set[Modality]:
+    mid_l = _norm(model_id)
+    out: set[Modality] = {"text"}
+    if _chat_supports_audio_io(mid_l):
+        out.add("audio")
+    return out
+
+
+def chat_supports_audio_io(model_id: str) -> bool:
+    return _chat_supports_audio_io(_norm(model_id))
+
+
+def _chat_supports_audio_io(mid_l: str) -> bool:
+    return _starts_with_any(mid_l, _CHAT_AUDIO_PREFIXES) or mid_l.endswith(
+        _CHAT_AUDIO_SUFFIXES
+    )
+
+
+def _qwen_supports_image_input(mid_l: str) -> bool:
+    return _has_token(mid_l, "image") or _has_token(mid_l, "vl")
+
+
+def _qwen_supports_audio_input(mid_l: str) -> bool:
+    return _has_token(mid_l, "asr")
+
+
+def chat_supports_audio_input(model_id: str) -> bool:
+    return _chat_supports_audio_input(_norm(model_id))
+
+
+def _chat_supports_audio_input(mid_l: str) -> bool:
+    if _chat_supports_audio_io(mid_l):
+        return True
+    return mid_l.startswith(_QWEN_PREFIX) and _qwen_supports_audio_input(mid_l)
+
+
+def chat_supports_image_input(model_id: str) -> bool:
+    return _chat_supports_image_input(_norm(model_id))
+
+
+def _chat_supports_image_input(mid_l: str) -> bool:
+    if mid_l in _CHAT_TEXT_ONLY_EXACT:
+        return False
+    if any(marker in mid_l for marker in _CHAT_TEXT_ONLY_MARKERS):
+        return False
+
+    if _starts_with_any(mid_l, _CHAT_NO_IMAGE_PREFIXES):
+        return False
+    if mid_l.startswith(_KIMI_LATEST_PREFIX):
+        return True
+    if mid_l.startswith(_QWEN_PREFIX):
+        return _qwen_supports_image_input(mid_l)
+
+    if mid_l in _CHAT_IMAGE_INPUT_EXACT:
+        return True
+
+    return _openai_style_chat_supports_image_input(mid_l)
+
+
+def _openai_style_chat_supports_image_input(mid_l: str) -> bool:
+    if mid_l.startswith("gpt-realtime"):
+        return True
+    if mid_l.startswith("gpt-4o") and not _chat_supports_audio_io(mid_l):
+        return True
+    if mid_l.startswith("gpt-4-turbo") and mid_l != "gpt-4-turbo-preview":
+        return True
+    if mid_l.startswith(("gpt-4.1", "gpt-4.5", "gpt-5")):
+        return True
+    if mid_l == "o1" or mid_l.startswith("o1-"):
+        return True
+    if mid_l == "o3" or mid_l.startswith("o3-"):
+        return True
+    return mid_l.startswith("o4-")
+
+
+# ---- Gemini model series ----
+
+
+def _gemini_norm(model_id: str) -> str:
+    mid = model_id.lower().strip()
+    if mid.startswith("models/"):
+        mid = mid[len("models/") :]
+    return mid
+
+
+def _gemini_is_image_model(mid_l: str) -> bool:
+    return (
+        mid_l.startswith("imagen-")
+        or "image-generation" in mid_l
+        or mid_l.endswith("-image")
+        or mid_l.endswith("-image-preview")
+        or "-image-" in mid_l
+    )
+
+
+def gemini_is_video_model(model_id: str) -> bool:
+    return _gemini_norm(model_id).startswith("veo")
+
+
+def gemini_is_embedding_model(model_id: str) -> bool:
+    return "embedding" in _gemini_norm(model_id)
+
+
+def gemini_is_tts_model(model_id: str) -> bool:
+    return "tts" in _gemini_norm(model_id)
+
+
+def gemini_is_native_audio_model(model_id: str) -> bool:
+    return "native-audio" in _gemini_norm(model_id)
+
+
+def gemini_is_image_model(model_id: str) -> bool:
+    return _gemini_is_image_model(_gemini_norm(model_id))
+
+
+def gemini_image_input_modalities(model_id: str) -> set[Modality]:
+    mid_l = _gemini_norm(model_id)
+    if mid_l.startswith("imagen-"):
+        return _mods("text")
+    if "image-generation" in mid_l:
+        return _mods("text")
+    return _mods("text", "image")
+
+
+def gemini_model_kind(model_id: str) -> GeminiModelKind:
+    mid_l = _gemini_norm(model_id)
+    if mid_l.startswith("veo"):
+        return "video"
+    if "embedding" in mid_l:
+        return "embedding"
+    if "tts" in mid_l:
+        return "tts"
+    if "native-audio" in mid_l:
+        return "native_audio"
+    if _gemini_is_image_model(mid_l):
+        return "image"
+    return "chat"
+
+
+def gemini_output_modalities(kind: GeminiModelKind) -> set[Modality]:
+    if kind == "video":
+        return _mods("video")
+    if kind == "embedding":
+        return _mods("embedding")
+    if kind == "tts":
+        return _mods("audio")
+    if kind == "native_audio":
+        return _mods("text", "audio")
+    if kind == "image":
+        return _mods("image")
+    return _mods("text")

nous/genai/_internal/config.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+_ENV_PRIORITY = (".env.local", ".env.production", ".env.development", ".env.test")
+
+_ENV_PREFIX = "NOUS_GENAI_"
+
+
+def get_prefixed_env(name: str) -> str | None:
+    return os.environ.get(f"{_ENV_PREFIX}{name}")
+
+
+def _parse_env_line(line: str) -> tuple[str, str] | None:
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#"):
+        return None
+    if "=" not in stripped:
+        return None
+    key, value = stripped.split("=", 1)
+    key = key.strip()
+    value = value.strip()
+    if not key:
+        return None
+    if (value.startswith("'") and value.endswith("'")) or (
+        value.startswith('"') and value.endswith('"')
+    ):
+        value = value[1:-1]
+    return key, value
+
+
+def load_env_files(root: str | Path | None = None) -> list[Path]:
+    """
+    Load env files by priority:
+    `.env.local > .env.production > .env.development > .env.test`.
+
+    Implementation: apply higher priority first without overriding existing env.
+    """
+    base = Path(root) if root is not None else Path.cwd()
+    loaded: list[Path] = []
+    for name in _ENV_PRIORITY:
+        path = base / name
+        if not path.is_file():
+            continue
+        loaded.append(path)
+        for line in path.read_text(encoding="utf-8").splitlines():
+            parsed = _parse_env_line(line)
+            if parsed is None:
+                continue
+            key, value = parsed
+            os.environ.setdefault(key, value)
+    return loaded
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderKeys:
+    openai_api_key: str | None
+    google_api_key: str | None
+    anthropic_api_key: str | None
+    aliyun_api_key: str | None
+    volcengine_api_key: str | None
+    tuzi_web_api_key: str | None
+    tuzi_openai_api_key: str | None
+    tuzi_google_api_key: str | None
+    tuzi_anthropic_api_key: str | None
+
+
+def get_provider_keys() -> ProviderKeys:
+    return ProviderKeys(
+        openai_api_key=get_prefixed_env("OPENAI_API_KEY")
+        or os.environ.get("OPENAI_API_KEY"),
+        google_api_key=get_prefixed_env("GOOGLE_API_KEY")
+        or os.environ.get("GOOGLE_API_KEY"),
+        anthropic_api_key=get_prefixed_env("ANTHROPIC_API_KEY")
+        or os.environ.get("ANTHROPIC_API_KEY"),
+        aliyun_api_key=get_prefixed_env("ALIYUN_API_KEY")
+        or os.environ.get("ALIYUN_API_KEY"),
+        volcengine_api_key=get_prefixed_env("VOLCENGINE_API_KEY")
+        or os.environ.get("VOLCENGINE_API_KEY"),
+        tuzi_web_api_key=get_prefixed_env("TUZI_WEB_API_KEY")
+        or os.environ.get("TUZI_WEB_API_KEY"),
+        tuzi_openai_api_key=get_prefixed_env("TUZI_OPENAI_API_KEY")
+        or os.environ.get("TUZI_OPENAI_API_KEY"),
+        tuzi_google_api_key=get_prefixed_env("TUZI_GOOGLE_API_KEY")
+        or os.environ.get("TUZI_GOOGLE_API_KEY"),
+        tuzi_anthropic_api_key=get_prefixed_env("TUZI_ANTHROPIC_API_KEY")
+        or os.environ.get("TUZI_ANTHROPIC_API_KEY"),
+    )
+
+
+def get_default_timeout_ms() -> int:
+    raw = get_prefixed_env("TIMEOUT_MS")
+    if raw is None:
+        return 120_000
+    try:
+        value = int(raw)
+    except ValueError:
+        return 120_000
+    return max(1, value)

nous/genai/_internal/errors.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorInfo:
+    type: str
+    message: str
+    provider_code: str | None = None
+    retryable: bool = False
+
+
+class GenAIError(RuntimeError):
+    def __init__(self, info: ErrorInfo):
+        super().__init__(info.message)
+        self.info = info
+
+
+def auth_error(message: str, provider_code: str | None = None) -> GenAIError:
+    return GenAIError(
+        ErrorInfo(type="AuthError", message=message, provider_code=provider_code)
+    )
+
+
+def rate_limit_error(message: str, provider_code: str | None = None) -> GenAIError:
+    return GenAIError(
+        ErrorInfo(
+            type="RateLimitError",
+            message=message,
+            provider_code=provider_code,
+            retryable=True,
+        )
+    )
+
+
+def invalid_request_error(message: str, provider_code: str | None = None) -> GenAIError:
+    return GenAIError(
+        ErrorInfo(
+            type="InvalidRequestError", message=message, provider_code=provider_code
+        )
+    )
+
+
+def not_supported_error(message: str) -> GenAIError:
+    return GenAIError(ErrorInfo(type="NotSupportedError", message=message))
+
+
+def timeout_error(message: str) -> GenAIError:
+    return GenAIError(ErrorInfo(type="TimeoutError", message=message, retryable=True))
+
+
+def provider_error(
+    message: str, provider_code: str | None = None, retryable: bool = False
+) -> GenAIError:
+    return GenAIError(
+        ErrorInfo(
+            type="ProviderError",
+            message=message,
+            provider_code=provider_code,
+            retryable=retryable,
+        )
+    )