Source code for venice_ai.types.embeddings

"""
Type definitions for Venice AI Embeddings API.

This module contains TypedDict definitions for request and response objects
in the Venice AI Embeddings API, covering the embeddings creation endpoint.
"""

from typing import List, Literal, Optional, Sequence, TypedDict, Union

# --- Request Types ---



class CreateEmbeddingRequest(TypedDict, total=False):
    """
    Request parameters for creating embeddings from text or token inputs.
    
    This TypedDict defines the structure for requests to the POST /embeddings endpoint,
    which generates vector embeddings from input text or tokens using specified models.
    The embeddings can be used for semantic search, clustering, and similarity tasks.
    
    Attributes:
        model: ID of the embedding model to use.
        input: Text or tokens to embed. Can be a string, list of strings, list of tokens, or list of token lists.
        dimensions: Optional. Number of dimensions for the output embeddings.
        encoding_format: Optional. Format for returned embeddings (``"float"`` or ``"base64"``). Defaults to ``"float"``.
        user: Optional. Unique identifier for the end-user.
    """
    
    model: str
    """ID of the model to use."""
    input: Union[str, List[str], List[int], List[List[int]]]
    """Input text or tokens to embed."""
    dimensions: Optional[int]
    """The number of dimensions the resulting output embedding should have.
    Only supported in text-embedding-3 and later models. Optional parameter."""
    encoding_format: Literal["float", "base64"]
    """The format to return the embeddings in. Can be ``"float"`` (default) or ``"base64"``. Optional parameter."""
    user: Optional[str]
    """A unique identifier representing your end-user, which can help Venice AI monitor and detect abuse. Optional parameter."""



# --- Response Types ---



class Embedding(TypedDict):
    """
    Represents a single embedding vector with its metadata.
    
    This TypedDict defines an individual embedding result containing the vector
    representation of input text along with its position index and object type.
    Each embedding is part of the response from the /embeddings endpoint and
    contains the actual numerical vector that can be used for similarity calculations.
    
    Attributes:
        embedding: Embedding vector as a list of floats or base64-encoded string.
        index: Index of this embedding in the list.
        object: Type of the object, always "embedding".
    """
    
    embedding: Union[List[float], str]
    """The embedding vector, which is a list of floats or a base64-encoded string (when encoding_format="base64"). The length of vector depends on the model used."""
    index: int
    """The index of the embedding in the list of embeddings."""
    object: Literal["embedding"]
    """The type of the object, which is always ``"embedding"``."""





class EmbeddingUsage(TypedDict):
    """
    Token usage statistics for an embedding request.
    
    This TypedDict provides information about token consumption during the
    embedding generation process, including both prompt tokens and total
    tokens used. This information is useful for tracking API usage and costs.
    
    Attributes:
        prompt_tokens: Number of tokens in the input.
        total_tokens: Total number of tokens used in the request.
    """
    
    prompt_tokens: int
    """The number of tokens used by the input prompt."""
    total_tokens: int
    """The total number of tokens used by the request."""





class EmbeddingList(TypedDict):
    """
    Complete response from the embeddings creation endpoint.
    
    This TypedDict represents the full response structure returned by the
    POST /embeddings endpoint, containing a list of embedding vectors,
    model information, and usage statistics. This is the primary response
    format for all embedding generation requests.
    
    Attributes:
        data: List of embedding objects.
        model: Model used to generate the embeddings.
        object: Type of the object, always "list".
        usage: Token usage statistics for the request.
    """
    
    data: List[Embedding]
    """The list of embeddings generated by the model."""
    model: str
    """The model ID used to generate the embeddings."""
    object: Literal["list"]
    """The object type, which is always ``"list"``."""
    usage: EmbeddingUsage
    """The usage statistics for the request."""