venice_ai.models.selection
Dynamic Model Selection for Venice AI SDK.
This module provides intelligent model selection capabilities with caching, preference handling, capability-based filtering, and custom selection strategies for production use.
Classes: ModelCache: Cache for model information with TTL support DynamicModelSelector: Intelligent model selector with capability filtering
Functions: create_model_selector: Factory function to create a model selector get_chat_model: Quick helper to get a chat model get_embedding_model: Quick helper to get an embedding model get_video_model: Quick helper to get a video model get_cheapest_video_model: Quick helper to find the cheapest video model via quoting get_multiple_models: Quick helper to get multiple models for concurrency
Types: ModelSelectorType: Type alias for custom model selection functions CheapestVideoResult: Dataclass returned by select_cheapest_video_model
Example:
>>> from venice_ai import VeniceClient, create_model_selector
>>>
>>> async with VeniceClient(api_key="...") as client:
... selector = create_model_selector(client)
... model = await selector.select_chat_model(
... preferred_models=["llama-3.3-70b"],
... require_function_calling=True
... )
# With custom selector for cost optimization:
>>> def cheapest_model(candidates):
... # Custom logic to pick cheapest model
... return candidates[0]["id"]
>>> selector = create_model_selector(client, default_selector=cheapest_model)
CheapestVideoResult Objects
@dataclass
class CheapestVideoResult()
Result from cost-aware video model selection via the quote API.
Attributes:
model- The model ID with the lowest quoted price.quote_usd- The quoted cost in USD for the selected model.all_quotes- Mapping of every successfully quoted model ID to its USD price. Useful for debugging or displaying alternatives.
ModelCache Objects
@dataclass
class ModelCache()
Cache for model information with TTL support.
ModelCache.ttl_seconds
ttl_seconds = 300.0
5 minutes
ModelCache.is_expired
def is_expired() -> bool
Check if cache has expired.
ModelCache.get_models
def get_models(resource_type: str | None = None) -> list[str]
Get list of model IDs, optionally filtered by resource type.
ModelCache.update
def update(models: dict[str, Any]) -> None
Update cache with new model data.
DynamicModelSelector Objects
class DynamicModelSelector()
Dynamic model selector that fetches available models and provides intelligent selection for production and testing scenarios.
Supports custom selection strategies via the default_selector parameter or per-call selector argument. Strategies receive full model dictionaries including pricing data for cost-aware selection.
DynamicModelSelector.__init__
def __init__(client: Any,
cache_ttl: float = 300.0,
default_selector: ModelSelectorType | None = None)
Initialize the model selector.
Arguments:
client- Venice AI client instance for API callscache_ttl- Time-to-live for model cache in secondsdefault_selector- Optional custom selection function that receives a list of model dicts and returns the selected model ID. Used as fallback when no per-call selector is provided.
DynamicModelSelector.select_by_trait
async def select_by_trait(trait: str,
resource_type: str | None = None) -> str | None
Select the model assigned to a specific Venice trait.
Venice assigns traits like "default", "fastest", "default_code", "default_reasoning", "default_vision", "function_calling_default", "most_intelligent", "most_uncensored" to indicate canonical model roles.
Arguments:
trait- The trait to search for (e.g., "default", "fastest", "default_code")resource_type- Optional filter by resource type (e.g., "text", "image")
Returns:
The model ID with the matching trait, or None if no model has that trait
DynamicModelSelector.get_available_models
async def get_available_models(resource_type: str | None = None,
force_refresh: bool = False) -> list[str]
Get list of available models, excluding offline and past-deprecation models.
Arguments:
resource_type- Filter by resource type ('text', 'image', 'video', etc.)force_refresh- Force refresh of model cache
Returns:
List of available model IDs (excludes offline models and models whose
deprecation.date has passed). Callers who need a deprecated model
should pass it directly to client.chat.completions.create(model=...)
rather than going through the resolver.
DynamicModelSelector.select_chat_model
async def select_chat_model(preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
require_function_calling: bool = False,
require_vision: bool = False,
require_reasoning: bool = False,
require_code_optimization: bool = False,
require_response_schema: bool = False,
min_context_tokens: int | None = None,
require_private: bool = False,
exclude_beta: bool = False,
prefer_recommended: bool = False,
selector: ModelSelectorType | None = None) -> str
Select a suitable chat completion model.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionrequire_function_calling- If True, only select models that support function callingrequire_vision- If True, only select models that support vision (image input)require_reasoning- If True, only select models that support reasoning with thinking blocksrequire_code_optimization- If True, only select models optimized for code generationrequire_response_schema- If True, only select models that support structured output via response schemamin_context_tokens- If set, only select models with at least this many context tokensrequire_private- If True, only select models with privacy="private" (no data stored by provider)exclude_beta- If True, exclude models marked as betaprefer_recommended- If True, prefer models in Venice's "venice_recommendations" model setselector- Optional custom selection function. Takes precedence over default_selector. Receives list of model dicts, returns model ID.
Returns:
Selected model ID
Raises:
ValueError- If no suitable model found
DynamicModelSelector.select_function_calling_model
async def select_function_calling_model(
preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a chat model that supports function calling/tools.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function. Takes precedence over default_selector. Receives list of model dicts, returns model ID.
Returns:
Selected model ID that supports function calling
Raises:
ValueError- If no suitable function calling model found
DynamicModelSelector.select_code_model
async def select_code_model(preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a model optimized for code generation.
Uses the 'default_code' trait as the primary selection, falling back to any model with optimizedForCode=True capability.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function
Returns:
Selected model ID optimized for code
Raises:
ValueError- If no suitable code model found
DynamicModelSelector.select_vision_model
async def select_vision_model(
preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a model that supports vision (image input).
Uses the 'default_vision' trait as the primary selection, falling back to any model with supportsVision=True capability.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function
Returns:
Selected model ID with vision support
Raises:
ValueError- If no suitable vision model found
DynamicModelSelector.select_reasoning_model
async def select_reasoning_model(
preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a model that supports reasoning with thinking blocks.
Uses the 'default_reasoning' trait as the primary selection, falling back to any model with supportsReasoning=True capability.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function
Returns:
Selected model ID with reasoning support
Raises:
ValueError- If no suitable reasoning model found
DynamicModelSelector.select_embedding_model
async def select_embedding_model(
preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a suitable embedding model.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function. Takes precedence over default_selector. Receives list of model dicts, returns model ID.
Returns:
Selected model ID
Raises:
ValueError- If no suitable model found
DynamicModelSelector.select_image_model
async def select_image_model(preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a suitable image generation model.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function. Takes precedence over default_selector. Receives list of model dicts, returns model ID.
Returns:
Selected model ID
Raises:
ValueError- If no suitable model found
DynamicModelSelector.select_video_model
async def select_video_model(model_type: str | None = None,
require_audio: bool = False,
min_resolution: str | None = None,
min_duration: str | None = None,
preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
exclude_beta: bool = False,
selector: ModelSelectorType | None = None) -> str
Select a suitable video generation model.
Arguments:
model_type- Filter by video model type ("text-to-video" or "image-to-video")require_audio- If True, only select models that support audio generationmin_resolution- Minimum resolution (e.g., "720p", "1080p", "4k"). Models must support this resolution or higher.min_duration- Minimum duration (e.g., "5s", "10s"). Models must support at least this duration.preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionexclude_beta- If True, exclude models marked as betaselector- Optional custom selection function
Returns:
Selected model ID
Raises:
ValueError- If no suitable video model found
DynamicModelSelector.select_cheapest_video_model
async def select_cheapest_video_model(
*,
duration: str = "5s",
model_type: str | None = None,
resolution: str | None = None,
audio: bool | None = None,
aspect_ratio: str | None = None,
require_audio: bool = False,
min_resolution: str | None = None,
min_duration: str | None = None,
exclude_models: set[str] | None = None,
exclude_beta: bool = True) -> CheapestVideoResult
Select the cheapest video model by quoting all viable candidates.
This method first filters video models using the same constraint logic
as :meth:select_video_model (model_type, audio support, resolution,
duration), then concurrently calls the POST /video/quote endpoint
for every candidate and returns the model with the lowest USD quote.
.. note:
Each call issues *N* quote API requests (one per candidate).
Quotes are free (no generation occurs), but this is more expensive
in terms of network round-trips than :meth:`select_video_model`.
Consider caching the result across a test session.
Arguments:
duration- Video duration for the quote (e.g.,"5s").model_type- Filter by"text-to-video"or"image-to-video".resolution- Resolution to quote (e.g.,"720p").Noneuses each model's default (typically cheapest).audio- Whether to include audio in the quote.Noneomits the parameter (uses model default).aspect_ratio- Aspect ratio for the quote (e.g.,"16:9").require_audio- Constraint filter — only consider models that support audio.min_resolution- Constraint filter — minimum supported resolution.min_duration- Constraint filter — minimum supported duration.exclude_models- Model IDs to exclude from consideration.exclude_beta- IfTrue, exclude beta models.
Returns:
A :class:CheapestVideoResult containing the cheapest model ID,
its quoted USD price, and a dict of all successful quotes.
Raises:
ValueError- If no candidate models remain after filtering, or if every candidate fails to return a valid quote.
Example:
>>> selector = create_model_selector(client)
>>> result = await selector.select_cheapest_video_model(
... model_type="text-to-video",
... duration="5s",
... )
>>> print(f"Cheapest: {result.model} at ${result.quote_usd:.4f}")
DynamicModelSelector.select_audio_model
async def select_audio_model(preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a suitable audio/speech generation model.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function. Takes precedence over default_selector. Receives list of model dicts, returns model ID.
Returns:
Selected model ID
Raises:
ValueError- If no suitable model found
DynamicModelSelector.select_inpaint_model
async def select_inpaint_model(
preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a suitable inpaint (image editing) model.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function
Returns:
Selected model ID
Raises:
ValueError- If no suitable inpaint model found
DynamicModelSelector.select_asr_model
async def select_asr_model(preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a suitable ASR (Automatic Speech Recognition) model.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function
Returns:
Selected model ID
Raises:
ValueError- If no suitable ASR model found
DynamicModelSelector.select_music_model
async def select_music_model(preferred_models: list[str] | None = None,
exclude_models: set[str] | None = None,
selector: ModelSelectorType | None = None) -> str
Select a suitable music generation model.
Arguments:
preferred_models- List of preferred models in priority orderexclude_models- Set of models to exclude from selectionselector- Optional custom selection function. Takes precedence over default_selector. Receives list of model dicts, returns model ID.
Returns:
Selected model ID
Raises:
ValueError- If no suitable music model found
DynamicModelSelector.select_models_for_concurrency_test
async def select_models_for_concurrency_test(
count: int = 2,
resource_type: str = "text",
exclude_models: set[str] | None = None) -> list[str]
Select multiple models for concurrency testing or production use.
Arguments:
count- Number of models to selectresource_type- Type of models to select (default "text"). Use "text" for chat models, "image" for image models, etc.exclude_models- Set of models to exclude from selection
Returns:
List of selected model IDs
Raises:
ValueError- If not enough models available
DynamicModelSelector.get_model_info
async def get_model_info(model_id: str) -> dict[str, Any] | None
Get detailed information about a specific model.
Arguments:
model_id- ID of the model to get info for
Returns:
Model information dict or None if not found
DynamicModelSelector.get_cache_info
def get_cache_info() -> dict[str, Any]
Get information about the current cache state.
create_model_selector
def create_model_selector(
client: Any,
cache_ttl: float = 300.0,
default_selector: ModelSelectorType | None = None
) -> DynamicModelSelector
Factory function to create a model selector instance.
.. deprecated:
Use ``client.models.resolve()`` instead. This function will be removed
in a future release.
Arguments:
client- Venice AI client instancecache_ttl- Cache TTL in secondsdefault_selector- Optional custom selection function that receives a list of model dicts and returns the selected model ID.
Returns:
DynamicModelSelector instance
get_chat_model
async def get_chat_model(client: Any,
preferred: list[str] | None = None) -> str
Quick helper to get a chat model for production or testing.
get_embedding_model
async def get_embedding_model(client: Any,
preferred: list[str] | None = None) -> str
Quick helper to get an embedding model for production or testing.
get_multiple_models
async def get_multiple_models(client: Any, count: int = 2) -> list[str]
Quick helper to get multiple models for concurrency testing or production use.
get_video_model
async def get_video_model(client: Any,
model_type: str | None = None,
preferred: list[str] | None = None) -> str
Quick helper to get a video model.
get_cheapest_video_model
async def get_cheapest_video_model(client: Any,
model_type: str | None = None,
duration: str = "5s",
**kwargs: Any) -> CheapestVideoResult
Quick helper to find the cheapest video model for given parameters.
Queries the POST /video/quote endpoint for every eligible model and
returns a :class:CheapestVideoResult with the model that has the lowest
cost.
Arguments:
client- Venice AI client instance.model_type-"text-to-video"or"image-to-video".duration- Video duration for the quote (default"5s").**kwargs- Forwarded to :meth:DynamicModelSelector.select_cheapest_video_model.
Returns:
A :class:CheapestVideoResult with the cheapest model, its USD
price, and all successful quotes.
Example:
>>> result = await get_cheapest_video_model(client, model_type="text-to-video")
>>> print(f"Use model {result.model} (${result.quote_usd:.4f})")