kiarina-lib-openai 1.31.0

OpenAI API client library for kiarina namespace

kiarina-lib-openai

A Python library for OpenAI API integration with configuration management using pydantic-settings-manager.

Features

• Configuration Management: Use pydantic-settings-manager for flexible configuration
• Type Safety: Full type hints and Pydantic validation
• Secure Credential Handling: API keys are protected using SecretStr
• Multiple Configurations: Support for multiple named configurations (e.g., different projects/environments)
• Environment Variable Support: Configure via environment variables with KIARINA_LIB_OPENAI_ prefix
• Custom Base URL: Support for custom OpenAI-compatible API endpoints

Installation

pip install kiarina-lib-openai

Quick Start

Basic Usage

from kiarina.lib.openai import OpenAISettings, settings_manager

# Configure OpenAI API
settings_manager.user_config = {
    "default": {
        "api_key": "sk-your-api-key-here"
    }
}

# Get settings
settings = settings_manager.settings
print(f"API Key configured: {settings.api_key.get_secret_value()[:10]}...")

Using with OpenAI Client

from openai import AsyncOpenAI
from kiarina.lib.openai import settings_manager

# Configure settings
settings_manager.user_config = {
    "default": {
        "api_key": "sk-your-api-key-here",
        "organization_id": "org-your-org-id",
        "base_url": "https://api.openai.com/v1"
    }
}

# Get client initialization arguments
settings = settings_manager.settings
client_kwargs = settings.to_client_kwargs()

# Initialize OpenAI client
client = AsyncOpenAI(**client_kwargs)

Environment Variable Configuration

Configure authentication using environment variables:

export KIARINA_LIB_OPENAI_API_KEY="sk-your-api-key-here"
export KIARINA_LIB_OPENAI_ORGANIZATION_ID="org-your-org-id"  # Optional

from kiarina.lib.openai import settings_manager

# Settings are automatically loaded from environment variables
settings = settings_manager.settings
print(f"API Key configured: {settings.api_key.get_secret_value()[:10]}...")

Multiple Configurations

Manage multiple OpenAI configurations (e.g., different projects or environments):

from kiarina.lib.openai import settings_manager

# Configure multiple projects
settings_manager.user_config = {
    "project_a": {
        "api_key": "sk-project-a-key",
        "organization_id": "org-project-a"
    },
    "project_b": {
        "api_key": "sk-project-b-key",
        "organization_id": "org-project-b"
    }
}

# Switch between configurations
settings_manager.active_key = "project_a"
project_a_settings = settings_manager.settings
print(f"Project A Org: {project_a_settings.organization_id}")

settings_manager.active_key = "project_b"
project_b_settings = settings_manager.settings
print(f"Project B Org: {project_b_settings.organization_id}")

Custom Base URL

Use with OpenAI-compatible APIs (e.g., Azure OpenAI, local models):

from kiarina.lib.openai import settings_manager

settings_manager.user_config = {
    "azure": {
        "api_key": "your-azure-key",
        "base_url": "https://your-resource.openai.azure.com/openai/deployments/your-deployment"
    }
}

settings = settings_manager.settings
print(f"Base URL: {settings.base_url}")

Configuration

This library uses pydantic-settings-manager for flexible configuration management.

OpenAISettings

The OpenAISettings class provides the following configuration fields:

Field	Type	Required	Description
api_key	SecretStr	Yes	OpenAI API key (masked in logs)
organization_id	str | None	No	OpenAI organization ID
base_url	str | None	No	Custom base URL for OpenAI-compatible APIs

Environment Variables

All settings can be configured via environment variables with the KIARINA_LIB_OPENAI_ prefix:

# API Key (required)
export KIARINA_LIB_OPENAI_API_KEY="sk-your-api-key"

# Organization ID (optional)
export KIARINA_LIB_OPENAI_ORGANIZATION_ID="org-your-org-id"

# Custom Base URL (optional)
export KIARINA_LIB_OPENAI_BASE_URL="https://api.openai.com/v1"

Programmatic Configuration

from pydantic import SecretStr
from kiarina.lib.openai import OpenAISettings, settings_manager

# Direct settings object
settings = OpenAISettings(
    api_key=SecretStr("sk-your-api-key"),
    organization_id="org-your-org-id"
)

# Via settings manager
settings_manager.user_config = {
    "default": {
        "api_key": "sk-your-api-key",  # Automatically converted to SecretStr
        "organization_id": "org-your-org-id"
    }
}

Runtime Overrides

from kiarina.lib.openai import settings_manager

# Override specific settings at runtime
settings_manager.cli_args = {
    "organization_id": "org-override-id"
}

settings = settings_manager.settings
print(f"Organization ID: {settings.organization_id}")  # Uses overridden value

Security

API Key Protection

API keys are stored using Pydantic's SecretStr type, which provides the following security benefits:

• Masked in logs: Keys are displayed as ********** in string representations
• Prevents accidental exposure: Keys won't appear in debug output or error messages
• Explicit access required: Must use .get_secret_value() to access the actual key

from kiarina.lib.openai import settings_manager

settings = settings_manager.settings

# API key is masked in string representation
print(settings)  # api_key=SecretStr('**********')

# Explicit access to get the actual key
api_key = settings.api_key.get_secret_value()

API Reference

OpenAISettings

class OpenAISettings(BaseSettings):
    api_key: SecretStr
    organization_id: str | None = None
    base_url: str | None = None
    
    def to_client_kwargs(self) -> dict[str, Any]:
        """Convert settings to OpenAI client initialization arguments."""

Pydantic settings model for OpenAI API configuration.

Fields:

• api_key (SecretStr): OpenAI API key (protected)
• organization_id (str | None): Optional organization ID
• base_url (str | None): Optional custom base URL for OpenAI-compatible APIs

Methods:

• to_client_kwargs() -> dict[str, Any]: Convert settings to OpenAI client initialization arguments. Returns a dictionary with non-None values that can be passed directly to OpenAI() or AsyncOpenAI() constructors.

settings_manager

settings_manager: SettingsManager[OpenAISettings]

Global settings manager instance for OpenAI configuration. See: pydantic-settings-manager

Development

Prerequisites

• Python 3.12+

Setup

# Clone the repository
git clone https://github.com/kiarina/kiarina-python.git
cd kiarina-python

# Setup development environment
mise run setup

Running Tests

# Run format, lint, type checks and tests
mise run package kiarina-lib-openai

# Coverage report
mise run package:test kiarina-lib-openai --coverage

Dependencies

• pydantic-settings - Settings management
• pydantic-settings-manager - Advanced settings management

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

This is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.

Related Projects

• kiarina-python - The main monorepo containing this package
• pydantic-settings-manager - Configuration management library used by this package