coord2region.ai_helpers#

Helpers for selecting AI models and loading environment variables.

This module consolidates the common glue used by examples so they can remain minimal. It provides:

  • load_environment: read .env (if present) into os.environ.

  • build_interface: construct an AIModelInterface with available providers.

  • select_model: choose a supported model from a candidate list with an optional

    override.

  • getenv_str: fetch and trim a string environment variable.

Examples import these helpers instead of duplicating logic.

Attributes#

TEXT_MODEL_CANDIDATES

IMAGE_MODEL_CANDIDATES

Functions#

load_environment(→ None)

Load environment variables from configuration files.

build_interface(...)

Initialise AIModelInterface with available providers.

select_model(→ str | None)

Return the first supported model, honouring an explicit override.

getenv_str(→ str | None)

Return the trimmed value of an environment variable.

Module Contents#

coord2region.ai_helpers.TEXT_MODEL_CANDIDATES: Sequence[str] = ('o4', 'o4-mini', 'o3-mini', 'gpt-4.1', 'gpt-4.1-mini', 'gpt-4o', 'gpt-4o-mini', 'deepseek-r1',...[source]#
coord2region.ai_helpers.IMAGE_MODEL_CANDIDATES: Sequence[str] = ('claude-image', 'gpt-image-1', 'dall-e-3', 'dall-e-2',...[source]#
coord2region.ai_helpers.load_environment(env_path: str | None = None) → None[source]#

Load environment variables from configuration files.

Parameters:

env_path (str, optional) – Override path to the .env file. Defaults to ".env" if not provided.

coord2region.ai_helpers.build_interface(*, enabled_providers: Sequence[str] | None = None) → AIModelInterface[source]#

Initialise AIModelInterface with available providers.

Parameters:

enabled_providers (sequence of str, optional) – Explicit list of provider names to register. If omitted, all detected providers are enabled.

Returns:

Interface capable of dispatching requests to the configured providers.

Return type:

AIModelInterface

coord2region.ai_helpers.select_model(ai: AIModelInterface, candidates: Sequence[str], *, explicit: str | None = None, kind: str = 'text') → str | None[source]#

Return the first supported model, honouring an explicit override.

Parameters:

  • ai (AIModelInterface) – Interface used to query available models.

  • candidates (sequence of str) – Preferred model aliases evaluated in order.

  • explicit (str, optional) – Explicit model request taking precedence if supported.

  • kind (str, optional) – Human-friendly label for the capability being selected (e.g., "text").

Returns:

Supported model name or None when no candidate is available.

Return type:

str or None

coord2region.ai_helpers.getenv_str(name: str) → str | None[source]#

Return the trimmed value of an environment variable.

Parameters:

name (str) – Environment variable to read and sanitize.

Returns:

Trimmed string value with surrounding quotes removed, or None if not set or empty.

Return type:

str or None