model-library 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

model_library/providers/google/google.py

@@ -1,5 +1,6 @@
 import base64
 import io
+import json
 import logging
 import uuid
 from typing import Any, Literal, Sequence, cast
@@ -25,6 +26,7 @@ from google.genai.types import (
     ToolListUnion,
     UploadFileConfig,
 )
+from google.oauth2 import service_account
 from typing_extensions import override
 
 from model_library import model_library_settings
@@ -95,31 +97,50 @@ class GoogleModel(LLM):
         ),
     ]
 
-    @override
-    def get_client(self) -> Client:
-        if self.provider_config.use_vertex:
-            # Preview Gemini releases from September 2025 are only served from the global
-            # Vertex region. The public docs for these SKUs list `global` as the sole
-            # availability region (see September 25, 2025 release notes), so we override
-            # the default `us-central1` when we detect them.
-            # https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash
-            MODEL_REGION_OVERRIDES: dict[str, str] = {
-                "gemini-2.5-flash-preview-09-2025": "global",
-                "gemini-2.5-flash-lite-preview-09-2025": "global",
+    def _get_default_api_key(self) -> str:
+        if not self.provider_config.use_vertex:
+            return model_library_settings.GOOGLE_API_KEY
+
+        return json.dumps(
+            {
+                "GCP_REGION": model_library_settings.GCP_REGION,
+                "GCP_PROJECT_ID": model_library_settings.GCP_PROJECT_ID,
+                "GCP_CREDS": model_library_settings.GCP_CREDS,
             }
-            region = model_library_settings.GCP_REGION
-            if self.model_name in MODEL_REGION_OVERRIDES:
-                region = MODEL_REGION_OVERRIDES[self.model_name]
-
-            return Client(
-                vertexai=True,
-                project=model_library_settings.GCP_PROJECT_ID,
-                location=region,
-                # Credentials object is not typed, so we have to ignore the error
-                credentials=model_library_settings.GCP_CREDS,
-            )
+        )
 
-        return Client(api_key=model_library_settings.GOOGLE_API_KEY)
+    @override
+    def get_client(self, api_key: str | None = None) -> Client:
+        if not self.has_client():
+            assert api_key
+            if self.provider_config.use_vertex:
+                # Gemini preview releases are only server from the global Vertex region after September 2025.
+                MODEL_REGION_OVERRIDES: dict[str, str] = {
+                    "gemini-2.5-flash-preview-09-2025": "global",
+                    "gemini-2.5-flash-lite-preview-09-2025": "global",
+                    "gemini-3-flash-preview": "global",
+                    "gemini-3-pro-preview": "global",
+                }
+
+                creds = json.loads(api_key)
+
+                region = creds["GCP_REGION"]
+                if self.model_name in MODEL_REGION_OVERRIDES:
+                    region = MODEL_REGION_OVERRIDES[self.model_name]
+
+                client = Client(
+                    vertexai=True,
+                    project=creds["GCP_PROJECT_ID"],
+                    location=region,
+                    credentials=service_account.Credentials.from_service_account_info(  # type: ignore
+                        json.loads(creds["GCP_CREDS"]),
+                        scopes=["https://www.googleapis.com/auth/cloud-platform"],
+                    ),
+                )
+            else:
+                client = Client(api_key=api_key)
+            self.assign_client(client)
+        return super().get_client()
 
     def __init__(
         self,
@@ -141,8 +162,6 @@ class GoogleModel(LLM):
             GoogleBatchMixin(self) if self.supports_batch else None
         )
 
-        self.client = self.get_client()
-
     @override
     async def parse_input(
         self,
@@ -260,7 +279,7 @@ class GoogleModel(LLM):
             )
 
         mime = f"image/{mime}" if type == "image" else mime  # TODO:
-        response: File = self.client.files.upload(
+        response: File = self.get_client().files.upload(
             file=bytes, config=UploadFileConfig(mime_type=mime)
         )
         if not response.name:
@@ -338,20 +357,25 @@ class GoogleModel(LLM):
 
         metadata: GenerateContentResponseUsageMetadata | None = None
 
-        stream = await self.client.aio.models.generate_content_stream(**body)
+        stream = await self.get_client().aio.models.generate_content_stream(**body)
         contents: list[Content | None] = []
         finish_reason: FinishReason | None = None
 
+        chunks: list[GenerateContentResponse] = []
+
         async for chunk in stream:
+            chunks.append(chunk)
             candidates = chunk.candidates
             if not candidates:
                 continue
 
             content = candidates[0].content
 
+            meaningful_content = False
             if content and content.parts:
                 for part in content.parts:
                     if part.function_call:
+                        meaningful_content = True
                         if not part.function_call.name:
                             raise Exception(f"Invalid function call: {part}")
 
@@ -368,13 +392,15 @@ class GoogleModel(LLM):
                     if not part.text:
                         continue
                     if part.thought:
+                        meaningful_content = True
                         reasoning += part.text
                     else:
+                        meaningful_content = True
                         text += part.text
 
             if chunk.usage_metadata:
                 metadata = chunk.usage_metadata
-            if content:
+            if content and meaningful_content:
                 contents.append(content)
             if candidates[0].finish_reason:
                 finish_reason = candidates[0].finish_reason
@@ -383,6 +409,7 @@ class GoogleModel(LLM):
             self.logger.error(f"Unexpected finish reason: {finish_reason}")
 
         if not text and not reasoning and not tool_calls:
+            self.logger.error(f"Chunks: {chunks}")
             raise ModelNoOutputError("Model returned empty response")
 
         result = QueryResult(
@@ -437,7 +464,7 @@ class GoogleModel(LLM):
             tools=parsed_tools,
         )
 
-        response = await self.client.aio.models.count_tokens(
+        response = await self.get_client().aio.models.count_tokens(
             model=self.model_name,
             contents=cast(Any, contents),
             config=config,
@@ -503,7 +530,7 @@ class GoogleModel(LLM):
         # Make the request with retry wrapper
         async def _query():
             try:
-                return await self.client.aio.models.generate_content(**body)
+                return await self.get_client().aio.models.generate_content(**body)
             except (genai_errors.ServerError, genai_errors.UnknownApiResponseError):
                 raise ImmediateRetryException("Failed to connect to Google API")
 

model_library/providers/inception.py

@@ -1,13 +1,14 @@
 from typing import Literal
 
+from pydantic import SecretStr
+
 from model_library import model_library_settings
 from model_library.base import (
+    DelegateConfig,
     DelegateOnly,
     LLMConfig,
 )
-from model_library.providers.openai import OpenAIModel
 from model_library.register_models import register_provider
-from model_library.utils import create_openai_client_with_defaults
 
 
 @register_provider("inception")
@@ -22,13 +23,12 @@ class MercuryModel(DelegateOnly):
         super().__init__(model_name, provider, config=config)
 
         # https://docs.inceptionlabs.ai/get-started/get-started#external-libraries-compatibility
-        self.delegate = OpenAIModel(
-            model_name=self.model_name,
-            provider=self.provider,
+        self.init_delegate(
             config=config,
-            custom_client=create_openai_client_with_defaults(
-                api_key=model_library_settings.MERCURY_API_KEY,
+            delegate_config=DelegateConfig(
                 base_url="https://api.inceptionlabs.ai/v1/",
+                api_key=SecretStr(model_library_settings.MERCURY_API_KEY),
             ),
             use_completions=True,
+            delegate_provider="openai",
         )

model_library/providers/kimi.py

@@ -1,13 +1,16 @@
-from typing import Literal
+from typing import Any, Literal
+
+from typing_extensions import override
+
+from pydantic import SecretStr
 
 from model_library import model_library_settings
 from model_library.base import (
+    DelegateConfig,
     DelegateOnly,
     LLMConfig,
 )
-from model_library.providers.openai import OpenAIModel
 from model_library.register_models import register_provider
-from model_library.utils import create_openai_client_with_defaults
 
 
 @register_provider("kimi")
@@ -22,13 +25,20 @@ class KimiModel(DelegateOnly):
         super().__init__(model_name, provider, config=config)
 
         # https://platform.moonshot.ai/docs/guide/migrating-from-openai-to-kimi#about-api-compatibility
-        self.delegate = OpenAIModel(
-            model_name=self.model_name,
-            provider=self.provider,
+        self.init_delegate(
             config=config,
-            custom_client=create_openai_client_with_defaults(
-                api_key=model_library_settings.KIMI_API_KEY,
+            delegate_config=DelegateConfig(
                 base_url="https://api.moonshot.ai/v1/",
+                api_key=SecretStr(model_library_settings.KIMI_API_KEY),
             ),
             use_completions=True,
+            delegate_provider="openai",
         )
+
+    @override
+    def _get_extra_body(self) -> dict[str, Any]:
+        """
+        Build extra body parameters for Kimi-specific features.
+        see https://platform.moonshot.ai/docs/guide/kimi-k2-5-quickstart#parameters-differences-in-request-body
+        """
+        return {"thinking": {"type": "enabled" if self.reasoning else "disabled"}}

model_library/providers/minimax.py

@@ -1,16 +1,17 @@
-from typing import Literal
+from typing import Literal, Sequence
+
+from pydantic import SecretStr
+from typing_extensions import override
 
 from model_library import model_library_settings
-from model_library.base import DelegateOnly, LLMConfig
-from model_library.base.input import InputItem, ToolDefinition
-from model_library.providers.anthropic import AnthropicModel
+from model_library.base import (
+    DelegateConfig,
+    DelegateOnly,
+    InputItem,
+    LLMConfig,
+    ToolDefinition,
+)
 from model_library.register_models import register_provider
-from model_library.utils import default_httpx_client
-
-from anthropic import AsyncAnthropic
-
-from typing import Sequence
-from typing_extensions import override
 
 
 @register_provider("minimax")
@@ -24,16 +25,13 @@ class MinimaxModel(DelegateOnly):
     ):
         super().__init__(model_name, provider, config=config)
 
-        self.delegate = AnthropicModel(
-            model_name=self.model_name,
-            provider=self.provider,
+        self.init_delegate(
             config=config,
-            custom_client=AsyncAnthropic(
-                api_key=model_library_settings.MINIMAX_API_KEY,
+            delegate_config=DelegateConfig(
                 base_url="https://api.minimax.io/anthropic",
-                http_client=default_httpx_client(),
-                max_retries=1,
+                api_key=SecretStr(model_library_settings.MINIMAX_API_KEY),
             ),
+            delegate_provider="anthropic",
         )
 
     # minimax client shares anthropic's syntax

model_library/providers/mistral.py

@@ -3,7 +3,13 @@ import logging
 from collections.abc import Sequence
 from typing import Any, Literal
 
-from mistralai import AssistantMessage, ContentChunk, Mistral, TextChunk, ThinkChunk
+from mistralai import (
+    AssistantMessage,
+    ContentChunk,
+    Mistral,
+    TextChunk,
+    ThinkChunk,
+)
 from mistralai.models.completionevent import CompletionEvent
 from mistralai.models.toolcall import ToolCall as MistralToolCall
 from mistralai.utils.eventstreaming import EventStreamAsync
@@ -40,16 +46,20 @@ from model_library.utils import default_httpx_client
 
 @register_provider("mistralai")
 class MistralModel(LLM):
-    _client: Mistral | None = None
+    @override
+    def _get_default_api_key(self) -> str:
+        return model_library_settings.MISTRAL_API_KEY
 
     @override
-    def get_client(self) -> Mistral:
-        if not MistralModel._client:
-            MistralModel._client = Mistral(
-                api_key=model_library_settings.MISTRAL_API_KEY,
+    def get_client(self, api_key: str | None = None) -> Mistral:
+        if not self.has_client():
+            assert api_key
+            client = Mistral(
+                api_key=api_key,
                 async_client=default_httpx_client(),
             )
-        return MistralModel._client
+            self.assign_client(client)
+        return super().get_client()
 
     def __init__(
         self,
@@ -198,12 +208,14 @@ class MistralModel(LLM):
 
         body: dict[str, Any] = {
             "model": self.model_name,
-            "max_tokens": self.max_tokens,
             "messages": messages,
             "prompt_mode": "reasoning" if self.reasoning else None,
             "tools": tools,
         }
 
+        if self.max_tokens:
+            body["max_tokens"] = self.max_tokens
+
         if self.supports_temperature:
             if self.temperature is not None:
                 body["temperature"] = self.temperature

model_library/providers/openai.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import datetime
 import io
 import json
 import logging
+import time
 from typing import Any, Literal, Sequence, cast
 
 from openai import APIConnectionError, AsyncOpenAI
@@ -30,6 +32,7 @@ from model_library.base import (
     LLM,
     BatchResult,
     Citation,
+    DelegateConfig,
     FileBase,
     FileInput,
     FileWithBase64,
@@ -44,6 +47,7 @@ from model_library.base import (
     QueryResultCost,
     QueryResultExtras,
     QueryResultMetadata,
+    RateLimit,
     RawInput,
     RawResponse,
     TextInput,
@@ -60,6 +64,7 @@ from model_library.exceptions import (
 )
 from model_library.model_utils import get_reasoning_in_tag
 from model_library.register_models import register_provider
+from model_library.retriers.base import BaseRetrier
 from model_library.utils import create_openai_client_with_defaults
 
 
@@ -234,23 +239,31 @@ class OpenAIBatchMixin(LLMBatchMixin):
 
 class OpenAIConfig(ProviderConfig):
     deep_research: bool = False
+    verbosity: Literal["low", "medium", "high"] | None = None
 
 
 @register_provider("openai")
 class OpenAIModel(LLM):
     provider_config = OpenAIConfig()
 
-    _client: AsyncOpenAI | None = None
+    @override
+    def _get_default_api_key(self) -> str:
+        if self.delegate_config:
+            return self.delegate_config.api_key.get_secret_value()
+        return model_library_settings.OPENAI_API_KEY
 
     @override
-    def get_client(self) -> AsyncOpenAI:
-        if self._delegate_client:
-            return self._delegate_client
-        if not OpenAIModel._client:
-            OpenAIModel._client = create_openai_client_with_defaults(
-                api_key=model_library_settings.OPENAI_API_KEY
+    def get_client(self, api_key: str | None = None) -> AsyncOpenAI:
+        if not self.has_client():
+            assert api_key
+            client = create_openai_client_with_defaults(
+                base_url=self.delegate_config.base_url
+                if self.delegate_config
+                else None,
+                api_key=api_key,
             )
-        return OpenAIModel._client
+            self.assign_client(client)
+        return super().get_client()
 
     def __init__(
         self,
@@ -258,20 +271,21 @@ class OpenAIModel(LLM):
         provider: str = "openai",
         *,
         config: LLMConfig | None = None,
-        custom_client: AsyncOpenAI | None = None,
         use_completions: bool = False,
+        delegate_config: DelegateConfig | None = None,
     ):
-        super().__init__(model_name, provider, config=config)
         self.use_completions: bool = (
             use_completions  # TODO: do completions in a separate file
         )
-        self.deep_research = self.provider_config.deep_research
+        self.delegate_config = delegate_config
 
-        # allow custom client to act as delegate (native)
-        self._delegate_client: AsyncOpenAI | None = custom_client
+        super().__init__(model_name, provider, config=config)
+
+        self.deep_research = self.provider_config.deep_research
+        self.verbosity = self.provider_config.verbosity
 
         # batch client
-        self.supports_batch: bool = self.supports_batch and not custom_client
+        self.supports_batch: bool = self.supports_batch and not self.delegate_config
         self.batch: LLMBatchMixin | None = (
             OpenAIBatchMixin(self) if self.supports_batch else None
         )
@@ -361,7 +375,6 @@ class OpenAIModel(LLM):
                         )
                 case RawResponse():
                     if self.use_completions:
-                        pass
                         new_input.append(item.response)
                     else:
                         new_input.extend(item.response)
@@ -522,18 +535,20 @@ class OpenAIModel(LLM):
 
         body: dict[str, Any] = {
             "model": self.model_name,
-            "max_tokens": self.max_tokens,
             "messages": parsed_input,
             # enable usage data in streaming responses
             "stream_options": {"include_usage": True},
         }
 
+        if self.max_tokens:
+            body["max_tokens"] = self.max_tokens
+
         if self.supports_tools:
             parsed_tools = await self.parse_tools(tools)
             if parsed_tools:
                 body["tools"] = parsed_tools
 
-        if self.reasoning:
+        if self.reasoning and self.max_tokens:
             del body["max_tokens"]
             body["max_completion_tokens"] = self.max_tokens
 
@@ -687,7 +702,7 @@ class OpenAIModel(LLM):
         self, tools: Sequence[ToolDefinition], **kwargs: object
     ) -> None:
         min_tokens = 30_000
-        if self.max_tokens < min_tokens:
+        if not self.max_tokens or self.max_tokens < min_tokens:
             self.logger.warning(
                 f"Recommended to set max_tokens >= {min_tokens} for deep research models"
             )
@@ -745,10 +760,12 @@ class OpenAIModel(LLM):
 
         body: dict[str, Any] = {
             "model": self.model_name,
-            "max_output_tokens": self.max_tokens,
             "input": parsed_input,
         }
 
+        if self.max_tokens:
+            body["max_output_tokens"] = self.max_tokens
+
         if parsed_tools:
             body["tools"] = parsed_tools
         else:
@@ -759,6 +776,9 @@ class OpenAIModel(LLM):
             if self.reasoning_effort is not None:
                 body["reasoning"]["effort"] = self.reasoning_effort  # type: ignore[reportArgumentType]
 
+        if self.verbosity is not None:
+            body["text"] = {"format": {"type": "text"}, "verbosity": self.verbosity}
+
         if self.supports_temperature:
             if self.temperature is not None:
                 body["temperature"] = self.temperature
@@ -883,6 +903,61 @@ class OpenAIModel(LLM):
 
         return result
 
+    @override
+    async def get_rate_limit(self) -> RateLimit | None:
+        headers = {}
+
+        try:
+            # NOTE: with_streaming_response doesn't seem to always work
+            if self.use_completions:
+                response = (
+                    await self.get_client().chat.completions.with_raw_response.create(
+                        max_completion_tokens=16,
+                        model=self.model_name,
+                        messages=[
+                            {
+                                "role": "user",
+                                "content": "Ping",
+                            }
+                        ],
+                        stream=True,
+                    )
+                )
+            else:
+                response = await self.get_client().responses.with_raw_response.create(
+                    max_output_tokens=16,
+                    input="Ping",
+                    model=self.model_name,
+                )
+            headers = response.headers
+
+            server_time_str = headers.get("date")
+            if server_time_str:
+                server_time = datetime.datetime.strptime(
+                    server_time_str, "%a, %d %b %Y %H:%M:%S GMT"
+                ).replace(tzinfo=datetime.timezone.utc)
+                timestamp = server_time.timestamp()
+            else:
+                timestamp = time.time()
+
+            # NOTE: for openai, max_tokens is used to reject requests if the amount of tokens left is less than the max_tokens
+
+            # we calculate estimated_tokens as (character_count / 4) + max_tokens. Note that OpenAI's rate limiter doesn't tokenize the request using the model's specific tokenizer but relies on a character count-based heuristic.
+
+            return RateLimit(
+                raw=headers,
+                unix_timestamp=timestamp,
+                request_limit=headers.get("x-ratelimit-limit-requests", None)
+                or headers.get("x-ratelimit-limit", None),
+                request_remaining=headers.get("x-ratelimit-remaining-requests", None)
+                or headers.get("x-ratelimit-remaining"),
+                token_limit=int(headers["x-ratelimit-limit-tokens"]),
+                token_remaining=int(headers["x-ratelimit-remaining-tokens"]),
+            )
+        except Exception as e:
+            self.logger.warning(f"Failed to get rate limit: {e}")
+            return None
+
     @override
     async def query_json(
         self,
@@ -906,7 +981,9 @@ class OpenAIModel(LLM):
             except APIConnectionError:
                 raise ImmediateRetryException("Failed to connect to OpenAI")
 
-        response = await LLM.immediate_retry_wrapper(func=_query, logger=self.logger)
+        response = await BaseRetrier.immediate_retry_wrapper(
+            func=_query, logger=self.logger
+        )
 
         parsed: PydanticT | None = response.output_parsed
         if parsed is None:
@@ -937,7 +1014,7 @@ class OpenAIModel(LLM):
 
             return response.data[0].embedding
 
-        return await LLM.immediate_retry_wrapper(
+        return await BaseRetrier.immediate_retry_wrapper(
             func=_get_embedding, logger=self.logger
         )
 
@@ -952,7 +1029,7 @@ class OpenAIModel(LLM):
             except Exception as e:
                 raise Exception("Failed to query OpenAI's Moderation endpoint") from e
 
-        return await LLM.immediate_retry_wrapper(
+        return await BaseRetrier.immediate_retry_wrapper(
             func=_moderate_content, logger=self.logger
         )
 

model_library/providers/openrouter.py

@@ -0,0 +1,34 @@
+from typing import Literal
+
+from pydantic import SecretStr
+
+from model_library import model_library_settings
+from model_library.base import (
+    DelegateConfig,
+    DelegateOnly,
+    LLMConfig,
+)
+from model_library.register_models import register_provider
+
+
+@register_provider("openrouter")
+class OpenRouterModel(DelegateOnly):
+    def __init__(
+        self,
+        model_name: str,
+        provider: Literal["openrouter"] = "openrouter",
+        *,
+        config: LLMConfig | None = None,
+    ):
+        super().__init__(model_name, provider, config=config)
+
+        # https://openrouter.ai/docs/guides/community/openai-sdk
+        self.init_delegate(
+            config=config,
+            delegate_config=DelegateConfig(
+                base_url="https://openrouter.ai/api/v1",
+                api_key=SecretStr(model_library_settings.OPENROUTER_API_KEY),
+            ),
+            use_completions=True,
+            delegate_provider="openai",
+        )

model_library/providers/perplexity.py

@@ -1,13 +1,14 @@
 from typing import Literal
 
+from pydantic import SecretStr
+
 from model_library import model_library_settings
 from model_library.base import (
+    DelegateConfig,
     DelegateOnly,
     LLMConfig,
 )
-from model_library.providers.openai import OpenAIModel
 from model_library.register_models import register_provider
-from model_library.utils import create_openai_client_with_defaults
 
 
 @register_provider("perplexity")
@@ -22,13 +23,12 @@ class PerplexityModel(DelegateOnly):
         super().__init__(model_name, provider, config=config)
 
         # https://docs.perplexity.ai/guides/chat-completions-guide
-        self.delegate = OpenAIModel(
-            model_name=self.model_name,
-            provider=self.provider,
+        self.init_delegate(
             config=config,
-            custom_client=create_openai_client_with_defaults(
-                api_key=model_library_settings.PERPLEXITY_API_KEY,
+            delegate_config=DelegateConfig(
                 base_url="https://api.perplexity.ai",
+                api_key=SecretStr(model_library_settings.PERPLEXITY_API_KEY),
             ),
             use_completions=True,
+            delegate_provider="openai",
         )