API Reference

This section provides a detailed reference for the llm-kit-pro API.

Core

class llm_kit_pro.core.base.BaseLLMClient[source]

Bases: ABC

Base contract for all LLM providers.

Providers must implement text and structured generation. Files (PDFs, images, etc.) are optional first-class inputs.

abstractmethod async generate_json(prompt: str, schema: Type[BaseModel], *, files: List[LLMFile] | None = None, **kwargs: Any) → Dict[str, Any][source]

Generate structured JSON output matching the provided Pydantic model.

Parameters:

prompt – User prompt / instruction.
schema – Pydantic model class describing expected output.
files – Optional list of attached files (PDF, image, etc.).
**kwargs – Provider-specific options (temperature, max_tokens, etc.). Note: The model is typically set in the config during client initialization.

Returns:

Validated JSON output as a dictionary.

abstractmethod async generate_text(prompt: str, *, files: List[LLMFile] | None = None, **kwargs: Any) → str[source]

Generate free-form text output.

Parameters:

prompt – User prompt / instruction.
files – Optional list of attached files (PDF, image, etc.).
**kwargs – Provider-specific options (temperature, max_tokens, etc.). Note: The model is typically set in the config during client initialization.

Returns:

Generated text.

llm_kit_pro.core.registry.get_provider(name: Literal['bedrock']) → Type['BedrockClient'][source]
llm_kit_pro.core.registry.get_provider(name: Literal['gemini']) → Type['GeminiClient']
llm_kit_pro.core.registry.get_provider(name: Literal['openai']) → Type['OpenAIClient']
llm_kit_pro.core.registry.get_provider(name: Literal['anthropic']) → Type['AnthropicClient']

llm_kit_pro.core.registry.register_provider(name: str, client: Type[BaseLLMClient]) → None[source]

class llm_kit_pro.core.inputs.LLMFile(content: bytes, mime_type: Literal['application/pdf', 'image/png', 'image/jpeg', 'text/plain'], filename: str | None = None)[source]

Bases: object

content: bytes

filename: str | None = None

mime_type: Literal['application/pdf', 'image/png', 'image/jpeg', 'text/plain']

Helpers

Helper utilities for converting files from local paths or URLs to LLMFile objects.

exception llm_kit_pro.core.helpers.file_url_to_llm_file.FileLoadError[source]

Bases: Exception

Raised when file loading fails.

exception llm_kit_pro.core.helpers.file_url_to_llm_file.UnsupportedMimeTypeError[source]

Bases: Exception

Raised when the detected MIME type is not supported.

llm_kit_pro.core.helpers.file_url_to_llm_file.load_file(source: str | Path, mime_type: str | None = None, filename: str | None = None, timeout: float = 30.0) → LLMFile[source]

Universal file loader that handles both local paths and URLs (synchronous).

This is the main entry point for loading files. It automatically detects whether the source is a local file path or a URL and handles it accordingly.

Parameters:

source – Either a local file path or a URL (http://, https://, or file://)
mime_type – Optional explicit MIME type. If not provided, will be auto-detected
filename – Optional filename override
timeout – Request timeout in seconds for URL downloads (default: 30.0)

Returns:

LLMFile object containing the file content and metadata

Raises:

FileLoadError – If the file cannot be loaded
UnsupportedMimeTypeError – If the MIME type is not supported

Examples

>>> # Load from local path
>>> file = load_file("/path/to/document.pdf")
>>>
>>> # Load from URL
>>> file = load_file("https://example.com/image.png")
>>>
>>> # Load with explicit MIME type
>>> file = load_file("/path/to/file", mime_type="text/plain")
>>>
>>> # Load with custom filename
>>> file = load_file("https://example.com/doc", filename="my_doc.pdf")

async llm_kit_pro.core.helpers.file_url_to_llm_file.load_file_async(source: str | Path, mime_type: str | None = None, filename: str | None = None, timeout: float = 30.0) → LLMFile[source]

Universal file loader that handles both local paths and URLs (asynchronous).

This is the async version of load_file(). It automatically detects whether the source is a local file path or a URL and handles it accordingly.

Parameters:

source – Either a local file path or a URL (http://, https://, or file://)
mime_type – Optional explicit MIME type. If not provided, will be auto-detected
filename – Optional filename override
timeout – Request timeout in seconds for URL downloads (default: 30.0)

Returns:

LLMFile object containing the file content and metadata

Raises:

FileLoadError – If the file cannot be loaded
UnsupportedMimeTypeError – If the MIME type is not supported

Examples

>>> # Load from local path
>>> file = await load_file_async("/path/to/document.pdf")
>>>
>>> # Load from URL
>>> file = await load_file_async("https://example.com/image.png")
>>>
>>> # Load with explicit MIME type
>>> file = await load_file_async("/path/to/file", mime_type="text/plain")
>>>
>>> # Load with custom filename
>>> file = await load_file_async("https://example.com/doc", filename="my_doc.pdf")

llm_kit_pro.core.helpers.file_url_to_llm_file.load_file_from_path(file_path: str, mime_type: str | None = None, filename: str | None = None) → LLMFile[source]

Load a file from a local filesystem path and convert to LLMFile.

Parameters:

file_path – Path to the local file
mime_type – Optional explicit MIME type. If not provided, will be auto-detected
filename – Optional filename override. If not provided, uses the file’s basename

Returns:

LLMFile object containing the file content and metadata

Raises:

FileLoadError – If the file cannot be read
UnsupportedMimeTypeError – If the MIME type is not supported

llm_kit_pro.core.helpers.file_url_to_llm_file.load_file_from_url(url: str, mime_type: str | None = None, filename: str | None = None, timeout: float = 30.0) → LLMFile[source]

Download a file from a URL and convert to LLMFile (synchronous).

Parameters:

url – URL to download the file from
mime_type – Optional explicit MIME type. If not provided, will be auto-detected
filename – Optional filename override. If not provided, extracts from URL
timeout – Request timeout in seconds (default: 30.0)

Returns:

LLMFile object containing the downloaded file content and metadata

Raises:

FileLoadError – If the download fails
UnsupportedMimeTypeError – If the MIME type is not supported

async llm_kit_pro.core.helpers.file_url_to_llm_file.load_file_from_url_async(url: str, mime_type: str | None = None, filename: str | None = None, timeout: float = 30.0) → LLMFile[source]

Download a file from a URL and convert to LLMFile (asynchronous).

Parameters:

url – URL to download the file from
mime_type – Optional explicit MIME type. If not provided, will be auto-detected
filename – Optional filename override. If not provided, extracts from URL
timeout – Request timeout in seconds (default: 30.0)

Returns:

LLMFile object containing the downloaded file content and metadata

Raises:

FileLoadError – If the download fails
UnsupportedMimeTypeError – If the MIME type is not supported

exception llm_kit_pro.core.helpers.json.JSONExtractionError[source]

Bases: ValueError

Raised when JSON cannot be extracted from the provided text.

llm_kit_pro.core.helpers.json.extract_json(text: str) → Dict[str, Any] | List[Any][source]

Extracts and repairs JSON from a given text string.

Uses a combination of stack-based extraction and json_repair to find and fix common JSON issues in LLM outputs.

Providers

class llm_kit_pro.providers.gemini.client.GeminiClient(config: GeminiConfig)[source]

Bases: BaseLLMClient

Google Gemini LLM client implementation.

Parameters:: config – GeminiConfig instance with api_key and model (required).

Example

>>> from llm_kit_pro.providers.gemini import GeminiClient
>>> from llm_kit_pro.providers.gemini.config import GeminiConfig
>>> client = GeminiClient(GeminiConfig(api_key="your-key", model="gemini-2.5-flash"))

async generate_json(prompt: str, schema: Type[BaseModel], *, files: List[LLMFile] | None = None, **kwargs: Any) → Dict[str, Any][source]

Generate structured JSON output matching the provided Pydantic model.

Parameters:

prompt – User prompt / instruction.
schema – Pydantic model class describing expected output.
files – Optional list of attached files (PDF, image, etc.).
**kwargs – Provider-specific options (temperature, max_tokens, etc.). Note: The model is typically set in the config during client initialization.

Returns:

Validated JSON output as a dictionary.

async generate_text(prompt: str, *, files: List[LLMFile] | None = None, **kwargs: Any) → str[source]

Generate free-form text output.

Parameters:

prompt – User prompt / instruction.
files – Optional list of attached files (PDF, image, etc.).
**kwargs – Provider-specific options (temperature, max_tokens, etc.). Note: The model is typically set in the config during client initialization.

Returns:

Generated text.

class llm_kit_pro.providers.bedrock.client.BedrockClient(config: BedrockConfig)[source]

Bases: BaseLLMClient

AWS Bedrock LLM client implementation.

Parameters:: config – BedrockConfig instance with access_key, secret_key, region, and model (all required).

Example

>>> from llm_kit_pro.providers.bedrock import BedrockClient
>>> from llm_kit_pro.providers.bedrock.config import BedrockConfig
>>> client = BedrockClient(BedrockConfig(
...     access_key="your-access-key",
...     secret_key="your-secret-key",
...     region="us-east-1",
...     model="global.anthropic.claude-sonnet-4-5-20250929-v1:0"
... ))

async generate_json(prompt: str, schema: Type[BaseModel], *, files: List[LLMFile] | None = None, **kwargs: Any) → Dict[str, Any][source]

Generate structured JSON output matching the provided Pydantic model.

Parameters:

prompt – User prompt / instruction.
schema – Pydantic model class describing expected output.
files – Optional list of attached files (PDF, image, etc.).
**kwargs – Provider-specific options (temperature, max_tokens, etc.). Note: The model is typically set in the config during client initialization.

Returns:

Validated JSON output as a dictionary.

async generate_text(prompt: str, *, files: List[LLMFile] | None = None, **kwargs: Any) → str[source]

Generate free-form text output.

Parameters:

prompt – User prompt / instruction.
files – Optional list of attached files (PDF, image, etc.).
**kwargs – Provider-specific options (temperature, max_tokens, etc.). Note: The model is typically set in the config during client initialization.

Returns:

Generated text.