Model configuration

Model configuration#

CyteOnto uses two models. An LLM, called through a pydantic-ai agent, describes cell types and splits compound labels, and an embedding model turns the descriptions into vectors. LlmConfig names the LLM of the agent, and EmbdConfig configures the embedding requests. The ModelArtifactKey of each model names the cache files, so each model pair has files of its own. Descriptions from a fallback agent are saved in the files of the primary LLM.

from cyteonto import EmbdConfig, LlmConfig

llm = LlmConfig(provider="nebius", model="moonshotai/Kimi-K2.6")
embedding = EmbdConfig(provider="nebius", model="Qwen/Qwen3-Embedding-8B")

These two configurations match the precomputed ontology files that python -m cyteonto.setup downloads. Models and providers explains how to choose a model pair, set API keys and add fallback models.

class cyteonto.LlmConfig(*, provider, model)#

LLM routing identity for description generation caches.

model must equal the model_name of the agent’s model. provider is only a label for the cache files; the agent decides where requests go.

provider: str#: Required. Provider slug, such as nebius, fireworks or together. It is lowercased in the cache key.

model: str#: Required. The model id, as agent.model.model_name reports it, such as moonshotai/Kimi-K2.6.

to_artifact_key()#

Return the cache key of this model.

Return type:: ModelArtifactKey

class cyteonto.EmbdConfig(*, provider='openrouter', model='qwen/qwen3-embedding-8b', apiKey=None, modelSettings=None, maxConcurrent=10)#

Parameters used to call an embedding provider.

Defaults target OpenRouter with qwen/qwen3-embedding-8b routed primarily to DeepInfra. Pass modelSettings={} to disable the default routing, or override it with your own {"provider": {...}} block.

provider: str = 'openrouter'#: The embedding provider: deepinfra, fireworks, google, nebius, ollama, openai, openrouter or together. ollama sends the requests to a local Ollama server and needs no API key.

model: str = 'qwen/qwen3-embedding-8b'#: The model id, as the provider names it. It also names the cache files, so its case matters.

apiKey: str | None = None#: API key of the provider. When None, CyteOnto reads it from the provider’s environment variable, such as NEBIUS_API_KEY, or else from EMBEDDING_MODEL_API_KEY.

modelSettings: dict[str, Any] | None = None#: Fields added to each request body, for openrouter only. For openrouter, None becomes {"provider": {"order": ["deepinfra"], "allow_fallbacks": True}}, which routes requests to DeepInfra first. Pass {} to send no routing.

maxConcurrent: int = 10#: Maximum number of embedding requests that run at the same time; at least 1. Each text is sent in a request of its own.

to_artifact_key()#

Return the cache key of this model.

Return type:: ModelArtifactKey

class cyteonto.ModelArtifactKey(*, provider, model)#

Canonical cache key for an LLM or embedding model configuration.

The provider is lowercased; the model id keeps its case. filename_segment() names the cache files of the model.

provider: str#: Required. Provider slug, lowercased.

model: str#: Required. The full model id.

property company: str#: The part of model before the first /, or all of it.

property modelName: str#: The part of model after the first /, or all of it.

filename_segment()#

{provider}_{company}-{modelName} after filesystem sanitization.

/ and : become -, and spaces become _. For example, nebius and moonshotai/Kimi-K2.6 give nebius_moonshotai-Kimi-K2.6.

Return type:: str

classmethod from_provider_model(provider, model)#

Return the key of model served by provider.

Return type:: ModelArtifactKey

Model configuration

Contents

Model configuration#