Overview SemanticConfig defines the configuration for both language models and optional embedding models used in semantic operations. It ensures that all configured models are valid and supported by their respective providers.Constructor from fenic.api.session.config import SemanticConfig config = SemanticConfig( language_models = { ... }, default_language_model = "model_alias" , embedding_models = { ... }, default_embedding_model = "embedding_alias" )
Parameters Mapping of model aliases to language model configurations. The alias is used to reference the model in semantic operations. Supported model types:
OpenAILanguageModelAnthropicLanguageModelGoogleDeveloperLanguageModelGoogleVertexLanguageModelOpenRouterLanguageModel See Model Configuration for detailed configuration options. The alias of the default language model to use for semantic operations. Required if multiple language models are configured. If only one language model is configured, it is automatically set as the default.
embedding_models
dict[str, EmbeddingModel]
Mapping of model aliases to embedding model configurations. Only required for operations that need semantic search or embedding capabilities. Supported embedding model types:
OpenAIEmbeddingModelGoogleDeveloperEmbeddingModelGoogleVertexEmbeddingModelCohereEmbeddingModel The alias of the default embedding model to use for semantic operations. Required if multiple embedding models are configured.
Configuration for LLM response caching. Stores the results of language model API calls to reduce costs and improve performance. Show LLMResponseCacheConfig Properties
Whether caching is enabled.
backend
CacheBackend
default: "LOCAL"
Cache backend to use. Currently only CacheBackend.LOCAL is supported.
Time-to-live duration string. Format: <number><unit> where unit is s/m/h/d. Examples: "30s", "15m", "2h", "7d" Maximum: 30 days, Minimum: 1 second.
Maximum cache size in MB before LRU eviction. Must be between 1 and 100,000.
Cache namespace for isolation. Useful for multi-tenant applications.
Examples Single Language Model Minimal configuration with one language model:
from fenic.api.session.config import SemanticConfig, OpenAILanguageModel config = SemanticConfig( language_models = { "gpt4" : OpenAILanguageModel( model_name = "gpt-4.1-nano" , rpm = 100 , tpm = 1000 ) } # default_language_model is automatically set to "gpt4" )
Multiple Language Models Configuration with multiple models from different providers:
from fenic.api.session.config import ( SemanticConfig, OpenAILanguageModel, AnthropicLanguageModel, GoogleDeveloperLanguageModel, ) config = SemanticConfig( language_models = { "gpt4" : OpenAILanguageModel( model_name = "gpt-4.1-nano" , rpm = 100 , tpm = 1000 ), "claude" : AnthropicLanguageModel( model_name = "claude-3-5-haiku-latest" , rpm = 100 , input_tpm = 100 , output_tpm = 100 ), "gemini" : GoogleDeveloperLanguageModel( model_name = "gemini-2.0-flash" , rpm = 100 , tpm = 10000 ), }, default_language_model = "gpt4" , )
With Embedding Models Configuration with both language and embedding models:
from fenic.api.session.config import ( SemanticConfig, OpenAILanguageModel, OpenAIEmbeddingModel, ) config = SemanticConfig( language_models = { "gpt4" : OpenAILanguageModel( model_name = "gpt-4.1-nano" , rpm = 100 , tpm = 1000 ) }, embedding_models = { "openai_embed" : OpenAIEmbeddingModel( model_name = "text-embedding-3-small" , rpm = 100 , tpm = 1000 ) }, )
With Model Profiles Configure models with multiple profiles for different use cases:
from fenic.api.session.config import ( SemanticConfig, OpenAILanguageModel, AnthropicLanguageModel, ) config = SemanticConfig( language_models = { "gpt4" : OpenAILanguageModel( model_name = "o4-mini" , rpm = 100 , tpm = 1000 , profiles = { "fast" : OpenAILanguageModel.Profile( reasoning_effort = "low" ), "thorough" : OpenAILanguageModel.Profile( reasoning_effort = "high" ), }, default_profile = "fast" , ), "claude" : AnthropicLanguageModel( model_name = "claude-opus-4-0" , rpm = 100 , input_tpm = 100 , output_tpm = 100 , profiles = { "fast" : AnthropicLanguageModel.Profile( thinking_token_budget = 1024 ), "thorough" : AnthropicLanguageModel.Profile( thinking_token_budget = 4096 ), }, default_profile = "fast" , ), }, default_language_model = "gpt4" , )
Using Profiles in Operations Reference different profiles in semantic operations:
from fenic import ModelAlias # Use default profile df.semantic.map( instruction = "Analyze {text} " , model_alias = "gpt4" ) # Use specific profile df.semantic.map( instruction = "Analyze {text} " , model_alias = ModelAlias( name = "gpt4" , profile = "thorough" ) )
With LLM Response Caching Enable response caching to reduce costs:
from fenic.api.session.config import ( SemanticConfig, OpenAILanguageModel, LLMResponseCacheConfig, ) config = SemanticConfig( language_models = { "gpt4" : OpenAILanguageModel( model_name = "gpt-4.1-nano" , rpm = 100 , tpm = 1000 ) }, llm_response_cache = LLMResponseCacheConfig( enabled = True , ttl = "7d" , # Cache for 7 days max_size_mb = 5000 , # 5GB cache namespace = "production" , ), )
Validation SemanticConfig automatically validates:
Model names are supported by their respective providers
Default models are specified when multiple models are configured
Default models exist in the configured model mappings
Profile configurations are compatible with model capabilities
Embedding dimensions are valid for the model
Notes The embedding model is optional and only required for operations that need semantic search or embedding capabilities, such as semantic.join() or embedding.create().
When using profiles, ensure the default profile is set if multiple profiles are configured. The system will automatically set the default if only one profile exists.
