coord2region.ai_model_interface#

AI model interface and provider abstraction with retry support.

All provider calls are wrapped with an exponential backoff retry to cope with transient failures. The retry behaviour can be configured via retries parameters on the public methods.

The AIModelInterface constructor accepts optional API keys for multiple providers. Notably, the openai_api_key and anthropic_api_key parameters (or the OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables) enable OpenAI and Anthropic models respectively.

Notes

This module requires the openai (version >=1.0), google-genai, anthropic, requests, transformers and diffusers packages.

Attributes#

PromptType

Classes#

ModelProvider

Base class for all model providers.

AIModelInterface

Register and dispatch to different AI model providers.

Functions#

load_env_file() → None)

Load configuration-managed credentials before falling back to .env.

huggingface_credentials_present(→ bool)

Check whether Hugging Face credentials are available.

pick_first_supported_model(→ str | None)

Return the first supported model from a list of candidates.

build_generation_summary(→ str)

Return a JSON summary describing a text generation output.

Module Contents#

coord2region.ai_model_interface.PromptType[source]#
coord2region.ai_model_interface.load_env_file(path: str | Path = Path('.env')) → None[source]#

Load configuration-managed credentials before falling back to .env.

Parameters:

path (str or Path, optional) – Path to the environment file to load. Defaults to .env.

coord2region.ai_model_interface.huggingface_credentials_present() → bool[source]#

Check whether Hugging Face credentials are available.

Returns:

True if either Hugging Face API key environment variable is set.

Return type:

bool

coord2region.ai_model_interface.pick_first_supported_model(ai: AIModelInterface, candidates: Iterable[str]) → str | None[source]#

Return the first supported model from a list of candidates.

Parameters:

  • ai (AIModelInterface) – Interface used to query model availability.

  • candidates (iterable of str) – Candidate model names evaluated in order of preference.

Returns:

First supported model name or None if no match is found.

Return type:

str or None

coord2region.ai_model_interface.build_generation_summary(model: str, response: str, provider: str) → str[source]#

Return a JSON summary describing a text generation output.

Parameters:

  • model (str) – Model name used for the generation.

  • response (str) – Raw text produced by the model.

  • provider (str) – Provider label for the selected model.

Returns:

JSON-formatted metadata describing the generation.

Return type:

str

class coord2region.ai_model_interface.ModelProvider(models: dict[str, str])[source]#

Bases: abc.ABC

Base class for all model providers.

See the README section Adding a Custom LLM Provider for guidance on implementing subclasses.

Parameters:

models (dict) – Mapping of friendly model names to provider-specific identifiers.

supports_batching: bool = False[source]#
models[source]#
supports(model: str) → bool[source]#

Return True if the provider exposes the requested model.

abstract generate_text(model: str, prompt: PromptType, max_tokens: int) → str[source]#

Generate text from the given model.

async generate_text_async(model: str, prompt: PromptType, max_tokens: int) → str[source]#

Asynchronously generate text.

Providers that expose native async APIs should override this method. The default implementation simply delegates to generate_text() using asyncio.to_thread to avoid blocking the event loop.

stream_generate_text(model: str, prompt: PromptType, max_tokens: int) → Iterator[str][source]#

Yield generated text chunks.

Providers that support server-side streaming should override this method. The base implementation yields the full response in a single chunk.

class coord2region.ai_model_interface.AIModelInterface(gemini_api_key: str | None = None, openrouter_api_key: str | None = None, openai_api_key: str | None = None, openai_project: str | None = None, anthropic_api_key: str | None = None, huggingface_api_key: str | None = None, groq_api_key: str | None = None, deepseek_api_key: str | None = None, together_api_key: str | None = None, local_openai_base_url: str | None = None, local_openai_api_key: str | None = None, local_openai_models: dict[str, str] | None = None, enabled_providers: list[str] | None = None)[source]#

Register and dispatch to different AI model providers.

register_provider(provider: ModelProvider | str, *, enabled: bool = True, **config: Any) → None[source]#

Register a provider and its models.

Parameters:

  • provider (ModelProvider | str) – Either an instantiated provider or the name of a provider defined in _PROVIDER_CLASSES.

  • enabled (bool, optional) – When False the provider is skipped.

  • **config (dict, optional) – Configuration forwarded to the provider constructor when provider is given as a string.

supports(model: str) → bool[source]#

Return whether model is registered with any provider.

supports_batching(model: str) → bool[source]#

Return whether the provider for model supports batching.

generate_text(model: str, prompt: PromptType, max_tokens: int = 1000, retries: int = 3) → str[source]#

Generate text using a registered model with retry.

Parameters:
async generate_text_async(model: str, prompt: PromptType, max_tokens: int = 1000, retries: int = 3) → str[source]#

Asynchronously generate text using a registered model with retry.

Parameters:
stream_generate_text(model: str, prompt: PromptType, max_tokens: int = 1000, retries: int = 3) → Iterator[str][source]#

Stream generated text chunks from a registered model with retry.

Parameters:
generate_image(model: str, prompt: str, retries: int = 3, **kwargs: Any) → bytes[source]#

Generate an image using a registered model with retry.

list_available_models() → list[str][source]#

Return the list of registered model names.

provider_name(model: str) → str[source]#

Return the provider class name registered for model.