cell_annotator.BaseAnnotator

cell_annotator.BaseAnnotator#

class cell_annotator.BaseAnnotator(species, tissue, stage='adult', cluster_key='leiden', model=None, max_completion_tokens=None, provider=None, api_key=None, _skip_validation=False)#

Shared base class for annotation-related functionality.

Provides a unified interface for querying different LLM providers to annotate cell types based on marker genes. Supports automatic provider detection from model names and handles API key management.

Parameters:

  • %(species)s

  • %(tissue)s

  • %(stage)s

  • %(cluster_key)s

  • %(model)s

  • %(max_completion_tokens)s

  • %(provider)s

  • %(api_key)s

  • species (str)

  • tissue (str)

  • stage (str)

  • cluster_key (str)

  • model (str | None)

  • max_completion_tokens (int | None)

  • provider (str | None)

  • api_key (str | None)

  • _skip_validation (bool)

Attributes table#

api_keys

Access to API key manager.

Methods table#

check_api_access([provider, model])

Check API access and log warnings if needed.

list_available_models()

List available models for the current provider.

query_llm(instruction, response_format[, ...])

Query the LLM with a given instruction.

test_query([return_details])

Test if the LLM setup is working correctly.

Attributes#

BaseAnnotator.api_keys#

Access to API key manager.

Methods#

BaseAnnotator.check_api_access(provider=None, model=None)#

Check API access and log warnings if needed.

Return type:

bool

Parameters:

  • provider (str | None)

  • model (str | None)

BaseAnnotator.list_available_models()#

List available models for the current provider.

Return type:

list[str]

Returns:

list[str] List of available model names.

BaseAnnotator.query_llm(instruction, response_format, agent_description=None, other_messages=None)#

Query the LLM with a given instruction.

Parameters:

  • instruction (str) – Instruction to provide to the model.

  • response_format (type[BaseOutput]) – Response format class.

  • agent_description (str | None (default: None)) – Optional system prompt override. If None, uses the default cell-annotation prompt from self.prompts.

  • other_messages (list | None (default: None)) – Additional messages to provide to the model.

Return type:

BaseOutput

Returns:

Parsed response.

BaseAnnotator.test_query(return_details=False)#

Test if the LLM setup is working correctly.

Performs a simple structured-output query against the configured model. For OpenRouter slugs whose upstream model does not implement OpenAI’s .parse() endpoint, the provider’s fallback chain (extra_body json_schema → plain json_object → optional text-repair) carries the request, so the same code path works for every provider.

Parameters:

return_details (bool (default: False)) – If True, returns (success, message) tuple with detailed information. If False, returns only boolean success status.

Return type:

bool | tuple[bool, str]

Returns:

If return_details=False: True if the test query succeeds, False otherwise. If return_details=True: Tuple of (success, message) with detailed status.