Providers API

The built-in providers implement the interface expected by the top-level helper functions.

llm_feature_gen.providers

providers

Provider implementations for remote and local LLM backends.

Modules:

• base_provider –

  Token usage tracking shared by the providers.

• local_provider –
• openai_provider –

Classes:

• LocalProvider –

  Thin adapter around OpenAI-compatible LOCAL endpoints.

• OpenAIProvider –

  Thin adapter around OpenAI (Azure or personal) for feature discovery/generation.

LocalProvider(base_url: Optional[str] = None, api_key: Optional[str] = None, default_text_model: Optional[str] = None, default_vision_model: Optional[str] = None, max_retries: int = 5, temperature: float = 0.0, max_tokens: int = 2048)

Bases: BaseProvider

Thin adapter around OpenAI-compatible LOCAL endpoints. Supports: - Ollama - vLLM - LM Studio - Any OpenAI-compatible local server

• Reads configuration from .env: LOCAL_OPENAI_BASE_URL LOCAL_OPENAI_API_KEY LOCAL_MODEL_TEXT LOCAL_MODEL_VISION LOCAL_WHISPER_MODEL_SIZE LOCAL_WHISPER_DEVICE

• Two entry points: image_features(image_base64_list, prompt=None, deployment_name=None, feature_gen=False, as_set=False) text_features(text_list, prompt=None, deployment_name=None, feature_gen=False) transcribe_audio(audio_path)

• Returns a list of dicts (one per input item) in the usual case. If as_set=True, returns a list with a single dict corresponding to the joint call.

Provider is configured via environment variables.

Methods:

• image_features –

  For each base64 image, ask the LLM to extract features.

• text_features –

  For each text, ask the LLM to extract features.

• transcribe_audio –

  Transcribes audio file using local Faster-Whisper.

image_features(image_base64_list: List[str], prompt: Optional[str] = None, deployment_name: Optional[str] = None, feature_gen: bool = False, as_set: bool = False, extra_context: Optional[str] = None, system_prompt: Optional[str] = None) -> List[Dict[str, Any]]

For each base64 image, ask the LLM to extract features.

• If as_set=False (default): behaves as before — one request per image.
• If as_set=True: sends ALL images in ONE request. prompt contains the task instructions sent with the images; system_prompt overrides the model's role and behavioral instructions.

text_features(text_list: List[str], prompt: Optional[str] = None, deployment_name: Optional[str] = None, feature_gen: bool = False, system_prompt: Optional[str] = None) -> List[Dict[str, Any]]

For each text, ask the LLM to extract features. When feature_gen=True and system_prompt is omitted, the provider uses its JSON-focused default system instruction. prompt contains the task instructions; system_prompt overrides the model's role and behavioral instructions.

transcribe_audio(audio_path: str) -> str

Transcribes audio file using local Faster-Whisper.

OpenAIProvider(api_key: Optional[str] = None, api_version: Optional[str] = None, endpoint: Optional[str] = None, default_deployment_name: Optional[str] = None, max_retries: int = 5, temperature: float = 0.0, max_tokens: Optional[int] = None, default_audio_model: Optional[str] = None, *, max_completion_tokens: Optional[int] = None, reasoning_effort: Optional[str] = None)

Bases: BaseProvider

Thin adapter around OpenAI (Azure or personal) for feature discovery/generation. Supports: - Azure OpenAI - Personal / private OpenAI API

• Reads credentials from .env: AZURE_OPENAI_API_KEY AZURE_OPENAI_API_VERSION AZURE_OPENAI_ENDPOINT AZURE_OPENAI_GPT41_DEPLOYMENT_NAME (default deployment/model name)

• Two entry points: image_features(image_base64_list, prompt=None, deployment_name=None, feature_gen=False, as_set=False) text_features(text_list, prompt=None, deployment_name=None, feature_gen=False)

• Returns a list of dicts (one per input item) in the usual case. If as_set=True, returns a list with a single dict corresponding to the joint call.

Provider is auto-detected from environment variables.

Methods:

• image_features –

  For each base64 image, ask the LLM to extract features.

• text_features –

  For each text, ask the LLM to extract features.

• transcribe_audio –

  Transcribes audio file using OpenAI Whisper (Cloud).

image_features(image_base64_list: List[str], prompt: Optional[str] = None, deployment_name: Optional[str] = None, feature_gen: bool = False, as_set: bool = False, extra_context: Optional[str] = None, system_prompt: Optional[str] = None, response_schema: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]

For each base64 image, ask the LLM to extract features.

• If as_set=False (default): behaves as before — one request per image, returns a list of dicts.
• If as_set=True: sends ALL images in ONE request (for comparative / discovery prompts) and returns a list with a single dict.

When feature_gen=True and system_prompt is omitted, the provider uses its JSON-focused default system instruction. prompt contains the task instructions sent with the images; system_prompt overrides the model's role and behavioral instructions.

text_features(text_list: List[str], prompt: Optional[str] = None, deployment_name: Optional[str] = None, feature_gen: bool = False, system_prompt: Optional[str] = None, response_schema: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]

For each text, ask the LLM to extract features. When feature_gen=True and system_prompt is omitted, the provider uses its JSON-focused default system instruction and appends a custom task prompt when supplied. prompt contains the task instructions; system_prompt overrides the model's role and behavioral instructions.

transcribe_audio(audio_path: str) -> str

Transcribes audio file using OpenAI Whisper (Cloud).

llm_feature_gen.providers.openai_provider

openai_provider

Classes:

• OpenAIProvider –

  Thin adapter around OpenAI (Azure or personal) for feature discovery/generation.

OpenAIProvider(api_key: Optional[str] = None, api_version: Optional[str] = None, endpoint: Optional[str] = None, default_deployment_name: Optional[str] = None, max_retries: int = 5, temperature: float = 0.0, max_tokens: Optional[int] = None, default_audio_model: Optional[str] = None, *, max_completion_tokens: Optional[int] = None, reasoning_effort: Optional[str] = None)

Bases: BaseProvider

Thin adapter around OpenAI (Azure or personal) for feature discovery/generation. Supports: - Azure OpenAI - Personal / private OpenAI API

• Reads credentials from .env: AZURE_OPENAI_API_KEY AZURE_OPENAI_API_VERSION AZURE_OPENAI_ENDPOINT AZURE_OPENAI_GPT41_DEPLOYMENT_NAME (default deployment/model name)

• Two entry points: image_features(image_base64_list, prompt=None, deployment_name=None, feature_gen=False, as_set=False) text_features(text_list, prompt=None, deployment_name=None, feature_gen=False)

• Returns a list of dicts (one per input item) in the usual case. If as_set=True, returns a list with a single dict corresponding to the joint call.

Provider is auto-detected from environment variables.

Methods:

• image_features –

  For each base64 image, ask the LLM to extract features.

• text_features –

  For each text, ask the LLM to extract features.

• transcribe_audio –

  Transcribes audio file using OpenAI Whisper (Cloud).

image_features(image_base64_list: List[str], prompt: Optional[str] = None, deployment_name: Optional[str] = None, feature_gen: bool = False, as_set: bool = False, extra_context: Optional[str] = None, system_prompt: Optional[str] = None, response_schema: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]

For each base64 image, ask the LLM to extract features.

• If as_set=False (default): behaves as before — one request per image, returns a list of dicts.
• If as_set=True: sends ALL images in ONE request (for comparative / discovery prompts) and returns a list with a single dict.

When feature_gen=True and system_prompt is omitted, the provider uses its JSON-focused default system instruction. prompt contains the task instructions sent with the images; system_prompt overrides the model's role and behavioral instructions.

text_features(text_list: List[str], prompt: Optional[str] = None, deployment_name: Optional[str] = None, feature_gen: bool = False, system_prompt: Optional[str] = None, response_schema: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]

For each text, ask the LLM to extract features. When feature_gen=True and system_prompt is omitted, the provider uses its JSON-focused default system instruction and appends a custom task prompt when supplied. prompt contains the task instructions; system_prompt overrides the model's role and behavioral instructions.

transcribe_audio(audio_path: str) -> str

Transcribes audio file using OpenAI Whisper (Cloud).

llm_feature_gen.providers.local_provider

local_provider

Classes:

• LocalProvider –

  Thin adapter around OpenAI-compatible LOCAL endpoints.

LocalProvider(base_url: Optional[str] = None, api_key: Optional[str] = None, default_text_model: Optional[str] = None, default_vision_model: Optional[str] = None, max_retries: int = 5, temperature: float = 0.0, max_tokens: int = 2048)

Bases: BaseProvider

Thin adapter around OpenAI-compatible LOCAL endpoints. Supports: - Ollama - vLLM - LM Studio - Any OpenAI-compatible local server

• Reads configuration from .env: LOCAL_OPENAI_BASE_URL LOCAL_OPENAI_API_KEY LOCAL_MODEL_TEXT LOCAL_MODEL_VISION LOCAL_WHISPER_MODEL_SIZE LOCAL_WHISPER_DEVICE

• Two entry points: image_features(image_base64_list, prompt=None, deployment_name=None, feature_gen=False, as_set=False) text_features(text_list, prompt=None, deployment_name=None, feature_gen=False) transcribe_audio(audio_path)

• Returns a list of dicts (one per input item) in the usual case. If as_set=True, returns a list with a single dict corresponding to the joint call.

Provider is configured via environment variables.

Methods:

• image_features –

  For each base64 image, ask the LLM to extract features.

• text_features –

  For each text, ask the LLM to extract features.

• transcribe_audio –

  Transcribes audio file using local Faster-Whisper.

image_features(image_base64_list: List[str], prompt: Optional[str] = None, deployment_name: Optional[str] = None, feature_gen: bool = False, as_set: bool = False, extra_context: Optional[str] = None, system_prompt: Optional[str] = None) -> List[Dict[str, Any]]

For each base64 image, ask the LLM to extract features.

• If as_set=False (default): behaves as before — one request per image.
• If as_set=True: sends ALL images in ONE request. prompt contains the task instructions sent with the images; system_prompt overrides the model's role and behavioral instructions.

text_features(text_list: List[str], prompt: Optional[str] = None, deployment_name: Optional[str] = None, feature_gen: bool = False, system_prompt: Optional[str] = None) -> List[Dict[str, Any]]

For each text, ask the LLM to extract features. When feature_gen=True and system_prompt is omitted, the provider uses its JSON-focused default system instruction. prompt contains the task instructions; system_prompt overrides the model's role and behavioral instructions.

transcribe_audio(audio_path: str) -> str

Transcribes audio file using local Faster-Whisper.