Client Utilities

This document describes the utility functions available in the Venice AI client library for Python.

Overview

The Venice AI client library includes a set of utility functions that simplify common operations when working with the Venice AI API. These utilities are available in the venice_ai.utils module and can be used alongside the main client classes.

class venice_ai.utils.NotGivenType[source]

Sentinel type used to distinguish between a parameter not being provided and a parameter being provided with a None value.

venice_ai.utils.estimate_token_count(text: str, model_id: str | None = None)[source]

Estimates the number of tokens in the given text using tiktoken or a fallback heuristic.

This function attempts to use the tiktoken library for accurate token counting based on the OpenAI tokenization standard. If tiktoken is not available, it falls back to a simple character-based heuristic (approximately 1 token per 4 characters).

The function handles various input types by converting them to strings, but provides different behavior based on the original input type to maintain consistency with expected token counting behavior.

Parameters:

  • text (str) – Text content to estimate token count for. Will be converted to string if not already a string.

  • model_id (Optional[str]) – Optional model identifier for model-specific encoding. Currently unused but reserved for future model-specific tokenization support.

Returns:

Estimated number of tokens in the text. Returns 0 for empty strings or non-string/non-numeric inputs when using fallback estimation.

Return type:

int

Raises:

AttributeError – If text is None.

Warning

If tiktoken is not available, a UserWarning will be issued and the function will use a simple character-based heuristic that may be less accurate.

Example

>>> # Estimate tokens for a simple text
>>> token_count = estimate_token_count("Hello, world!")
>>> print(token_count)  # Output depends on tiktoken availability

>>> # With model specification (reserved for future use)
>>> token_count = estimate_token_count("Hello, world!", model_id="gpt-4")
async venice_ai.utils.find_model_by_id(client: venice_ai._client.VeniceClient | venice_ai._async_client.AsyncVeniceClient, model_id: str)[source]

Retrieve full details of a specific model by its unique identifier.

This function searches through all available models from the Venice.ai API to find a model with the specified ID. It handles both synchronous and asynchronous clients, automatically adapting the API call method based on the client type.

Parameters:

  • client (Union[venice_ai._client.VeniceClient, venice_ai._async_client.AsyncVeniceClient]) – An instance of ~venice_ai.VeniceClient or ~venice_ai.AsyncVeniceClient used to fetch the model list from the API.

  • model_id (str) – Unique identifier of the model to search for. This should match the id field of a model exactly.

Returns:

The complete Model object if a model with the specified ID is found, otherwise None.

Return type:

Optional[venice_ai.types.models.Model]

Raises:

Exception – If there’s an error fetching models from the API (returns None).

Note

When using a synchronous client, a deprecation warning will be issued to encourage proper async/await usage patterns.

Example

>>> # Find a specific model by ID
>>> model = await find_model_by_id(client, "gpt-4")
>>> if model:
...     print(f"Found model: {model['id']}")
...     print(f"Model type: {model.get('type')}")
... else:
...     print("Model not found")
venice_ai.utils.find_model_by_id_or_name_or_slug(identifier: str)[source]

Find a model by its ID, name, or slug from a predefined static list.

Note

This function queries a hardcoded list of sample model data (MODELS_DATA) within the library and does not perform any live API requests. It is intended for illustrative purposes or offline scenarios with sample data. For live API model lookups, use functions that interact with a client instance.

Parameters:

identifier (str) – The model identifier (ID, name, or slug) to search for.

Returns:

The model if found in the static list, otherwise None.

Return type:

Optional[Model]

venice_ai.utils.format_tool_response(tool_call_id: str, content: Any)[source]

Helper function to format a tool response message for the Chat API.

This function creates a properly formatted message with role "tool" that responds to an assistant’s tool call. It handles content conversion to ensure the response is in the correct string format required by the API, automatically converting complex objects to JSON strings and handling None values appropriately.

Parameters:

  • tool_call_id (str) – The unique identifier of the tool call this response is for. This must match the id field from a tool call in an assistant message.

  • content (Any) –

    The result from the tool execution. Non-string content will be automatically converted:

    • None becomes "null" (JSON representation)

    • Dictionaries and lists are converted to JSON strings

    • Other types are converted using str()

Returns:

A dictionary formatted as a tool response message with role, tool_call_id, and content fields properly set for use in chat completions.

Return type:

Dict[str, Any]

Example

>>> # Format a simple string response
>>> response = format_tool_response("call_123", "Operation completed successfully")
>>> print(response)
{'role': 'tool', 'tool_call_id': 'call_123', 'content': 'Operation completed successfully'}

>>> # Format a complex object response
>>> data = {"result": 42, "status": "success"}
>>> response = format_tool_response("call_456", data)
>>> print(response['content'])  # '{"result": 42, "status": "success"}'
venice_ai.utils.get_filtered_models(client: venice_ai._client.VeniceClient | venice_ai._async_client.AsyncVeniceClient, model_type: Literal['embedding', 'image', 'text', 'tts', 'upscale'] | None = None, supports_vision: bool | None = None, supports_reasoning: bool | None = None, supports_function_calling: bool | None = None, supports_web_search: bool | None = None, supports_log_probs: bool | None = None, optimized_for_code: bool | None = None, quantization: str | None = None, is_beta: bool | None = None, has_trait: str | None = None)[source]

Retrieves a list of models filtered by type and various capabilities.

This function provides a unified interface for filtering models from the Venice.ai API based on model type and specific capabilities. It automatically handles both synchronous and asynchronous clients.

Parameters:

  • client (typing.Union[venice_ai._client.VeniceClient, venice_ai._async_client.AsyncVeniceClient]) – An instance of ~venice_ai.VeniceClient or ~venice_ai.AsyncVeniceClient.

  • model_type (typing.Optional[typing.Literal['embedding', 'image', 'text', 'tts', 'upscale']]) – Optional. Filter for model type.

  • supports_vision (typing.Optional[bool]) – Optional. Filter by vision support.

  • supports_reasoning (typing.Optional[bool]) – Optional. Filter by reasoning support.

  • supports_function_calling (typing.Optional[bool]) – Optional. Filter by function calling support.

  • supports_web_search (typing.Optional[bool]) – Optional. Filter by web search support.

  • supports_log_probs (typing.Optional[bool]) – Optional. Filter by log probability support.

  • optimized_for_code (typing.Optional[bool]) – Optional. Filter by code optimization.

  • quantization (typing.Optional[str]) – Optional. Filter by quantization type (e.g., “fp16”, “fp8”).

  • is_beta (typing.Optional[bool]) – Optional. Filter by beta status.

  • has_trait (typing.Optional[str]) – Optional. Filter by a specific model trait.

Returns:

A list of Model objects that match the filters. If the client is asynchronous, this is an awaitable resolving to the list.

Return type:

Union[List[venice_ai.types.models.Model], Coroutine[Any, Any, List[venice_ai.types.models.Model]]]

Raises:

TypeError – If the client type is unsupported.

async venice_ai.utils.get_model_capabilities(client: venice_ai._client.VeniceClient | venice_ai._async_client.AsyncVeniceClient, model_id: str)[source]

Get the capabilities dictionary for a specific model by its ID.

This function retrieves the capabilities information for a model, which describes what features and functionality the model supports (e.g., streaming, function calling, vision, etc.). It first finds the model using find_model_by_id() and then extracts the capabilities from the model specification.

Parameters:

  • client (Union[venice_ai._client.VeniceClient, venice_ai._async_client.AsyncVeniceClient]) – An instance of ~venice_ai.VeniceClient or ~venice_ai.AsyncVeniceClient used to fetch model information from the API.

  • model_id (str) – Unique identifier of the model whose capabilities should be retrieved.

Returns:

The ModelCapabilities dictionary containing capability flags if the model is found, otherwise None.

Return type:

Optional[venice_ai.types.models.ModelCapabilities]

Raises:

Exception – If there’s an error fetching model information (returns None).

Note

This function depends on find_model_by_id() and will inherit any warnings or behaviors from that function, including deprecation warnings for synchronous clients.

Example

>>> # Get capabilities for a specific model
>>> capabilities = await get_model_capabilities(client, "gpt-4")
>>> if capabilities:
...     print(f"Supports streaming: {capabilities.get('streaming', False)}")
...     print(f"Supports functions: {capabilities.get('supports_functions', False)}")
... else:
...     print("Model not found or no capabilities available")
venice_ai.utils.get_model_capabilities_by_id_or_name_or_slug(identifier: str)[source]

Get model capabilities by ID, name, or slug from a predefined static list.

Note

This function retrieves capabilities based on a hardcoded list of sample model data (MODELS_DATA) by calling find_model_by_id_or_name_or_slug. It does not perform any live API requests. For live API model capability lookups, use functions that interact with a client instance (e.g., get_model_capabilities).

Parameters:

identifier (str) – The model identifier (ID, name, or slug) to search for.

Returns:

The model capabilities if found in the static list, otherwise None.

Return type:

Optional[ModelCapabilities]

venice_ai.utils.get_models_by_capability(models: List[venice_ai.types.models.Model], capability: str)[source]

Filters a list of models by a specific capability.

Supports both camelCase (API format) and snake_case (legacy format) capability names. For example, both “supportsFunctionCalling” and “supports_functions” will work.

Parameters:

  • models (List[Model]) – A list of model objects to filter.

  • capability (str) – The capability to filter by (e.g., “supportsReasoning”).

Returns:

A new list of models that have the specified capability.

Return type:

List[Model]

venice_ai.utils.import_module_from_path(module_name: str, file_path: str)[source]

Dynamically imports a Python module from a file path.

Parameters:

  • module_name (str) – Name to assign to the imported module.

  • file_path (str) – Path to the Python file to import.

Returns:

The imported module object.

Return type:

Module

Raises:

ImportError – If the module cannot be loaded from the specified path.

venice_ai.utils.normalize_model_capabilities(capabilities: Any)[source]

Normalize capability field names between API (camelCase) and SDK (snake_case).

This provides backward compatibility while supporting the new API structure. Adds snake_case aliases for camelCase fields to maintain compatibility with existing code that expects snake_case field names.

Parameters:

capabilities (Dict[str, Any]) – The capabilities dictionary from the API response.

Returns:

Normalized capabilities with both camelCase and snake_case fields.

Return type:

Dict[str, Any]

venice_ai.utils.truncate_string(s: str | None, max_len: int)[source]

Truncates a string if its length exceeds max_len, appending ‘…’.

Parameters:
Return type:

typing.Optional[str]

venice_ai.utils.validate_chat_messages(messages: List[Dict[str, Any]], max_messages: int | None = None, max_total_chars: int | None = None)[source]

Validates the structure, roles, content, and ordering of chat messages for API compatibility.

This function performs comprehensive validation of chat message arrays according to the Venice.ai Chat API requirements. It checks message structure, validates roles and content, ensures proper message sequencing, and validates tool call/response patterns.

The validation covers: - Message structure and required fields - Valid role values and role-specific requirements - Content format validation (string, multimodal, etc.) - Message ordering rules (system first, no consecutive same roles) - Tool call structure and tool response matching - Optional limits on message count and total character length

Parameters:

  • messages (List[Dict[str, Any]]) – List of message dictionaries to validate. Each message should contain at minimum a 'role' field and appropriate content based on the role type.

  • max_messages (Optional[int]) – Optional maximum number of messages allowed in the conversation. If specified, validation will fail if the message count exceeds this limit.

  • max_total_chars (Optional[int]) – Optional maximum total character count allowed across all message content. If specified, validation will fail if the total exceeds this limit.

Returns:

Dictionary containing validation results with two keys: - "errors": List of validation failures that must be fixed - "warnings": List of potential issues or recommendations

Return type:

Dict[str, List[str]]

Raises:

AttributeError – If messages is None.

Note

Valid message roles are: 'system', 'user', 'assistant', and 'tool'.

  • System messages must be first and contain string content

  • User messages can have string or multimodal list content

  • Assistant messages can have content and/or tool_calls

  • Tool messages must follow assistant messages and reference valid tool_call_ids

Example

>>> messages = [
...     {"role": "system", "content": "You are a helpful assistant."},
...     {"role": "user", "content": "Hello!"},
...     {"role": "assistant", "content": "Hi there!"}
... ]
>>> result = validate_chat_messages(messages, max_messages=10)
>>> if result["errors"]:
...     print("Validation failed:", result["errors"])
>>> else:
...     print("Messages are valid!")

Utility Functions

Helper functions for common tasks.

Token Estimation

venice_ai.utils.estimate_token_count(text: str, model_id: str | None = None)[source]

Estimates the number of tokens in the given text using tiktoken or a fallback heuristic.

This function attempts to use the tiktoken library for accurate token counting based on the OpenAI tokenization standard. If tiktoken is not available, it falls back to a simple character-based heuristic (approximately 1 token per 4 characters).

The function handles various input types by converting them to strings, but provides different behavior based on the original input type to maintain consistency with expected token counting behavior.

Parameters:

  • text (str) – Text content to estimate token count for. Will be converted to string if not already a string.

  • model_id (Optional[str]) – Optional model identifier for model-specific encoding. Currently unused but reserved for future model-specific tokenization support.

Returns:

Estimated number of tokens in the text. Returns 0 for empty strings or non-string/non-numeric inputs when using fallback estimation.

Return type:

int

Raises:

AttributeError – If text is None.

Warning

If tiktoken is not available, a UserWarning will be issued and the function will use a simple character-based heuristic that may be less accurate.

Example

>>> # Estimate tokens for a simple text
>>> token_count = estimate_token_count("Hello, world!")
>>> print(token_count)  # Output depends on tiktoken availability

>>> # With model specification (reserved for future use)
>>> token_count = estimate_token_count("Hello, world!", model_id="gpt-4")

Chat Message Validation

venice_ai.utils.validate_chat_messages(messages: List[Dict[str, Any]], max_messages: int | None = None, max_total_chars: int | None = None)[source]

Validates the structure, roles, content, and ordering of chat messages for API compatibility.

This function performs comprehensive validation of chat message arrays according to the Venice.ai Chat API requirements. It checks message structure, validates roles and content, ensures proper message sequencing, and validates tool call/response patterns.

The validation covers: - Message structure and required fields - Valid role values and role-specific requirements - Content format validation (string, multimodal, etc.) - Message ordering rules (system first, no consecutive same roles) - Tool call structure and tool response matching - Optional limits on message count and total character length

Parameters:

  • messages (List[Dict[str, Any]]) – List of message dictionaries to validate. Each message should contain at minimum a 'role' field and appropriate content based on the role type.

  • max_messages (Optional[int]) – Optional maximum number of messages allowed in the conversation. If specified, validation will fail if the message count exceeds this limit.

  • max_total_chars (Optional[int]) – Optional maximum total character count allowed across all message content. If specified, validation will fail if the total exceeds this limit.

Returns:

Dictionary containing validation results with two keys: - "errors": List of validation failures that must be fixed - "warnings": List of potential issues or recommendations

Return type:

Dict[str, List[str]]

Raises:

AttributeError – If messages is None.

Note

Valid message roles are: 'system', 'user', 'assistant', and 'tool'.

  • System messages must be first and contain string content

  • User messages can have string or multimodal list content

  • Assistant messages can have content and/or tool_calls

  • Tool messages must follow assistant messages and reference valid tool_call_ids

Example

>>> messages = [
...     {"role": "system", "content": "You are a helpful assistant."},
...     {"role": "user", "content": "Hello!"},
...     {"role": "assistant", "content": "Hi there!"}
... ]
>>> result = validate_chat_messages(messages, max_messages=10)
>>> if result["errors"]:
...     print("Validation failed:", result["errors"])
>>> else:
...     print("Messages are valid!")

Usage Examples

Model Utilities

# Find and filter models
from venice_ai import VeniceClient
from venice_ai.utils import get_filtered_models, find_model_by_id, get_model_capabilities
import asyncio

async def example_model_utilities():
    client = VeniceClient(api_key="your-api-key")

    # Get all text models that support function calling
    text_models = await get_filtered_models(
        client,
        model_type="text",
        supports_capabilities=["supportsFunctionCalling"]
    )
    print(f"Found {len(text_models)} text models with function calling")

    # Find specific model
    model = await find_model_by_id(client, "llama-3.3-70b")
    if model:
        print(f"Found model: {model['id']}, Type: {model.get('type')}")

        # Check model capabilities
        capabilities = await get_model_capabilities(client, model['id'])
        if capabilities:
            print(f"Model capabilities: {capabilities}")

# Run the async example
asyncio.run(example_model_utilities())

Note: For detailed specifications of individual models, such as context window size (e.g., “Venice Large” supports up to 128k tokens), refer to the official Venice AI model documentation. Different models have varying capabilities that may affect your application’s design.

Chat Message Utilities

from venice_ai.utils import validate_chat_messages, format_tool_response

# Validate message structure
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the weather in New York?"},
    {"role": "assistant", "content": None, "tool_calls": [
        {
            "id": "call_abc123",
            "type": "function",
            "function": {
                "name": "get_weather",
                "arguments": "{\"location\":\"New York\"}"
            }
        }
    ]}
]

# Validate messages
result = validate_chat_messages(messages)
if not result["errors"]:
    print("Messages are valid")
else:
    print("Validation errors:", result["errors"])

# Format a tool response
weather_data = {"temperature": 22, "condition": "sunny"}
tool_message = format_tool_response("call_abc123", weather_data)
messages.append(tool_message)

# Check that new message sequence is valid
result = validate_chat_messages(messages)
print("Updated messages valid:", not result["errors"])

Token Counting

from venice_ai.utils import estimate_token_count

# Count tokens in various text chunks
text = "This is a sample text to count tokens in."
token_count = estimate_token_count(text)
print(f"Estimated token count: {token_count}")

Installation Requirements

Some utilities have optional dependencies:

  • For estimate_token_count to use the accurate tokenization method: pip install tiktoken

Best Practices

  • Error Handling: Always check for errors when using validation functions.

  • Capabilities Checking: Use the model utility functions to ensure you’re working with models that support your required features.

  • Token Management: Use estimate_token_count to proactively manage token usage, especially when working with models with large context windows like “Venice Large” (128k tokens), to stay within API and model limits.

  • Async Consistency: Most model utility functions are async and should be awaited properly.