LLM configuration

CyteType.run() accepts your own models in llm_configs, a list of dicts. Each dict is validated against cytetype.api.LLMModelConfig before any file is uploaded: a missing required field raises a pydantic.ValidationError, and keys that are not fields of the model are ignored, so check their spelling (field names are case-sensitive). The server then checks every model before the job starts, and run() raises LLMValidationError if one fails. Use your own LLM explains when to use these fields, with examples.

adata = annotator.run(
    study_context="Human PBMCs from a healthy donor.",
    llm_configs=[
        {"provider": "openai", "name": "<model-name>", "apiKey": "<your-api-key>"},
    ],
)

Each configuration needs either apiKey or all three AWS fields (awsAccessKeyId, awsSecretAccessKey and awsDefaultRegion).

class cytetype.api.LLMModelConfig

The fields of one entry in llm_configs.

provider: str

Required. The model provider: anthropic, bedrock, deepseek, fireworks, google, groq, huggingface, mistral, nebius, openai, openrouter, together, vertex or xai.

name: str

Required. The model name, as the provider names it.

apiKey: str | None = None

Your API key for the provider. Required unless the three AWS fields are set.

baseUrl: str | None = None

The base URL of the provider’s API. The openai provider uses it to reach OpenAI-compatible servers, and vertex uses it too; other providers ignore it.

awsAccessKeyId: str | None = None

AWS access key ID for bedrock. Set all three AWS fields together.

awsSecretAccessKey: str | None = None

AWS secret access key for bedrock.

awsDefaultRegion: str | None = None

AWS region for bedrock.

modelSettings: dict[str, Any] | None = None

Extra settings for the requests to the model, such as temperature.

targetAgents: list[str] | None = []

The CyteType agents that use this model: contextualizer, annotator or reviewer. An empty list means all agents. summarizer, clinician and chat are also accepted but have no effect: the current workflow does not use the summarizer, and target analysis and Chat always use CyteType’s hosted models.

skipValidation: bool = False

Has no effect: the server validates every model regardless.

allowFallback: bool = False

If true, an agent tries this model only after its models without allowFallback.