Factory Functions

The factory module provides convenient functions for creating model providers with simplified configuration and automatic environment variable support.

Functions

create_provider()

Create a model provider with automatic configuration from environment variables.

def create_provider(
    provider_type: str = "openai",
    api_key: Optional[str] = None,
    model: Optional[str] = None,
    base_url: Optional[str] = None,
    temperature: float = 0.7,
    **kwargs
) -> BaseModelProvider:
    """Create a model provider with automatic configuration.
    
    This factory function creates a model provider based on the specified type.
    It supports environment variable fallbacks for common configuration options.
    
    Args:
        provider_type: Type of provider to create (openai, zhipu, qwen, etc.)
        api_key: API key (falls back to environment variable)
        model: Model name (falls back to environment variable)
        base_url: Custom API endpoint (falls back to environment variable)
        temperature: Sampling temperature
        **kwargs: Additional provider-specific configuration
        
    Returns:
        BaseModelProvider: Configured model provider
        
    Raises:
        ValueError: If provider type is not supported or required config is missing
        NotImplementedError: If provider is not yet implemented
    """

Supported Provider Types

openai: OpenAI and OpenAI-compatible APIs ✅
zhipu: Zhipu AI (智谱AI) 🚧 Coming Soon
qwen: Alibaba Qwen (通义千问) 🚧 Coming Soon
deepseek: DeepSeek AI 🚧 Coming Soon
anthropic: Anthropic Claude 🚧 Coming Soon

Environment Variables by Provider

OpenAI:

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_TEMPERATURE=0.7

Examples

Using explicit configuration:

from ag_kit_py.providers import create_provider

provider = create_provider(
    provider_type="openai",
    api_key="sk-...",
    model="gpt-4o-mini",
    temperature=0.7
)

Using environment variables:

import os
from ag_kit_py.providers import create_provider

# Set environment variables
os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["OPENAI_MODEL"] = "gpt-4o-mini"

# Create provider (automatically loads from environment)
provider = create_provider(provider_type="openai")

Mixing explicit and environment configuration:

import os
from ag_kit_py.providers import create_provider

# API key from environment
os.environ["OPENAI_API_KEY"] = "sk-..."

# Override model explicitly
provider = create_provider(
    provider_type="openai",
    model="gpt-4o",  # Override default
    temperature=0.9
)

With additional configuration:

from ag_kit_py.providers import create_provider

provider = create_provider(
    provider_type="openai",
    api_key="sk-...",
    model="gpt-4o-mini",
    temperature=0.7,
    timeout=60000,        # 60 seconds
    max_retries=5,
    organization="org-..."
)

create_provider_from_env()

Create a model provider using only environment variables.

def create_provider_from_env(
    provider_type: str = "openai",
    **kwargs
) -> BaseModelProvider:
    """Create a model provider using only environment variables.
    
    This is a convenience function that creates a provider using environment
    variables for all configuration. It's useful for deployment scenarios
    where configuration is managed through environment variables.
    
    Args:
        provider_type: Type of provider to create
        **kwargs: Additional configuration to override environment variables
        
    Returns:
        BaseModelProvider: Configured model provider
    """

Examples

Pure environment configuration:

import os
from ag_kit_py.providers import create_provider_from_env

# Set all configuration via environment
os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["OPENAI_MODEL"] = "gpt-4o-mini"
os.environ["OPENAI_TEMPERATURE"] = "0.7"

# Create provider from environment
provider = create_provider_from_env("openai")

With selective overrides:

import os
from ag_kit_py.providers import create_provider_from_env

# Base configuration from environment
os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["OPENAI_MODEL"] = "gpt-4o-mini"

# Override specific settings
provider = create_provider_from_env(
    "openai",
    temperature=0.9  # Override environment temperature
)

create_openai_provider()

Convenience function specifically for creating OpenAI providers.

def create_openai_provider(
    api_key: str,
    model: Optional[str] = None,
    base_url: Optional[str] = None,
    temperature: float = 0.7,
    **kwargs
) -> OpenAIProvider:
    """Create an OpenAI provider with simplified configuration.
    
    Args:
        api_key: OpenAI API key
        model: Model name (default: gpt-4o-mini)
        base_url: Custom API endpoint
        temperature: Sampling temperature
        **kwargs: Additional configuration options
        
    Returns:
        OpenAIProvider: Configured OpenAI provider
    """

Examples

Basic usage:

from ag_kit_py.providers import create_openai_provider

provider = create_openai_provider(
    api_key="sk-...",
    model="gpt-4o-mini",
    temperature=0.7
)

With custom endpoint:

from ag_kit_py.providers import create_openai_provider

# Azure OpenAI
provider = create_openai_provider(
    api_key="your-azure-key",
    base_url="https://your-resource.openai.azure.com/openai/deployments/your-deployment",
    model="gpt-4o-mini"
)

# Local model (Ollama)
provider = create_openai_provider(
    api_key="ollama",
    base_url="http://localhost:11434/v1",
    model="llama2"
)

With advanced configuration:

from ag_kit_py.providers import create_openai_provider

provider = create_openai_provider(
    api_key="sk-...",
    model="gpt-4o-mini",
    temperature=0.7,
    timeout=60000,
    max_retries=5,
    organization="org-...",
    project="proj-..."
)

Usage Patterns

Development vs Production

Development (explicit configuration):

from ag_kit_py.providers import create_provider

# Explicit configuration for development
provider = create_provider(
    provider_type="openai",
    api_key="sk-...",
    model="gpt-4o-mini",
    temperature=0.7
)

Production (environment variables):

from ag_kit_py.providers import create_provider_from_env

# All configuration from environment
provider = create_provider_from_env("openai")

Configuration Priority

When both explicit parameters and environment variables are provided, explicit parameters take precedence:

import os
from ag_kit_py.providers import create_provider

# Environment variable
os.environ["OPENAI_MODEL"] = "gpt-4o-mini"

# Explicit parameter takes precedence
provider = create_provider(
    provider_type="openai",
    api_key="sk-...",
    model="gpt-4o"  # This overrides OPENAI_MODEL
)

# provider will use "gpt-4o", not "gpt-4o-mini"

Multi-Provider Setup

from ag_kit_py.providers import create_provider
import os

# Configure multiple providers
os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["OPENAI_MODEL"] = "gpt-4o-mini"

# Create providers for different use cases
fast_provider = create_provider(
    "openai",
    model="gpt-4o-mini",
    temperature=0.5
)

creative_provider = create_provider(
    "openai",
    model="gpt-4o",
    temperature=0.9
)

# Use appropriate provider for each task
quick_response = await fast_provider.create_completion(quick_params)
creative_response = await creative_provider.create_completion(creative_params)

Dynamic Provider Selection

from ag_kit_py.providers import create_provider
from typing import Dict, Any

def get_provider(config: Dict[str, Any]):
    """Dynamically create provider based on configuration."""
    provider_type = config.get("provider", "openai")
    
    return create_provider(
        provider_type=provider_type,
        api_key=config.get("api_key"),
        model=config.get("model"),
        temperature=config.get("temperature", 0.7),
        base_url=config.get("base_url")
    )

# Usage
config = {
    "provider": "openai",
    "api_key": "sk-...",
    "model": "gpt-4o-mini",
    "temperature": 0.7
}

provider = get_provider(config)

Environment Variable Management

Using .env Files

# .env file
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_TEMPERATURE=0.7
OPENAI_BASE_URL=https://api.openai.com/v1

# Load from .env file
from dotenv import load_dotenv
from ag_kit_py.providers import create_provider_from_env

load_dotenv()  # Load .env file

provider = create_provider_from_env("openai")

Environment-Specific Configuration

import os
from ag_kit_py.providers import create_provider_from_env

# Detect environment
env = os.getenv("ENVIRONMENT", "development")

if env == "production":
    # Production uses environment variables
    provider = create_provider_from_env("openai")
elif env == "staging":
    # Staging might use different model
    provider = create_provider_from_env(
        "openai",
        model="gpt-4o-mini"  # Override for staging
    )
else:
    # Development uses explicit config
    from ag_kit_py.providers import create_provider
    provider = create_provider(
        "openai",
        api_key="sk-dev-...",
        model="gpt-4o-mini"
    )

Validation

import os
from ag_kit_py.providers import create_provider

def create_validated_provider(provider_type: str = "openai"):
    """Create provider with validation."""
    api_key = os.getenv("OPENAI_API_KEY")
    
    if not api_key:
        raise ValueError(
            "OPENAI_API_KEY environment variable is required. "
            "Set it with: export OPENAI_API_KEY=sk-..."
        )
    
    if not api_key.startswith("sk-"):
        raise ValueError("Invalid OpenAI API key format")
    
    return create_provider(
        provider_type=provider_type,
        api_key=api_key
    )

# Usage
try:
    provider = create_validated_provider()
except ValueError as e:
    print(f"Configuration error: {e}")

Error Handling

Missing Configuration

from ag_kit_py.providers import create_provider

try:
    # Missing API key
    provider = create_provider("openai")
except ValueError as e:
    print(f"Configuration error: {e}")
    # Output: "OpenAI API key is required. Set OPENAI_API_KEY environment variable..."

Unsupported Provider

from ag_kit_py.providers import create_provider

try:
    provider = create_provider("unsupported_provider")
except ValueError as e:
    print(f"Error: {e}")
    # Output: "Unsupported provider type: unsupported_provider"

Not Yet Implemented

from ag_kit_py.providers import create_provider

try:
    provider = create_provider("zhipu")
except NotImplementedError as e:
    print(f"Error: {e}")
    # Output: "Zhipu provider is not yet implemented"

Best Practices

1. Use Environment Variables in Production

# Good: Production configuration
from ag_kit_py.providers import create_provider_from_env

provider = create_provider_from_env("openai")

# Bad: Hardcoded credentials
from ag_kit_py.providers import create_provider

provider = create_provider("openai", api_key="sk-...")  # Don't commit!

2. Validate Configuration Early

import os
from ag_kit_py.providers import create_provider

def setup_provider():
    """Setup provider with early validation."""
    required_vars = ["OPENAI_API_KEY", "OPENAI_MODEL"]
    missing = [var for var in required_vars if not os.getenv(var)]
    
    if missing:
        raise ValueError(f"Missing required environment variables: {missing}")
    
    return create_provider("openai")

# Fail fast if configuration is invalid
provider = setup_provider()

3. Use Type Hints

from ag_kit_py.providers import BaseModelProvider, create_provider
from typing import Optional

def create_configured_provider(
    provider_type: str = "openai",
    model: Optional[str] = None
) -> BaseModelProvider:
    """Create provider with type hints."""
    return create_provider(
        provider_type=provider_type,
        model=model
    )

# Type-safe usage
provider: BaseModelProvider = create_configured_provider()

4. Document Required Environment Variables

"""
Application Configuration

Required Environment Variables:
    OPENAI_API_KEY: OpenAI API key (required)
    OPENAI_MODEL: Model name (default: gpt-4o-mini)
    OPENAI_TEMPERATURE: Sampling temperature (default: 0.7)
    OPENAI_BASE_URL: Custom API endpoint (optional)

Example:
    export OPENAI_API_KEY=sk-...
    export OPENAI_MODEL=gpt-4o-mini
    python app.py
"""

from ag_kit_py.providers import create_provider_from_env

provider = create_provider_from_env("openai")

5. Provide Sensible Defaults

import os
from ag_kit_py.providers import create_provider

def create_app_provider():
    """Create provider with application defaults."""
    return create_provider(
        provider_type=os.getenv("PROVIDER_TYPE", "openai"),
        model=os.getenv("MODEL_NAME", "gpt-4o-mini"),
        temperature=float(os.getenv("TEMPERATURE", "0.7")),
        timeout=int(os.getenv("TIMEOUT", "30000")),
        max_retries=int(os.getenv("MAX_RETRIES", "3"))
    )

provider = create_app_provider()

Complete Example

"""
Complete example of provider factory usage with best practices.
"""

import os
from typing import Optional
from dotenv import load_dotenv
from ag_kit_py.providers import (
    BaseModelProvider,
    create_provider,
    create_provider_from_env,
    ModelProviderError
)

# Load environment variables from .env file
load_dotenv()

def create_production_provider() -> BaseModelProvider:
    """Create provider for production environment."""
    # Validate required environment variables
    if not os.getenv("OPENAI_API_KEY"):
        raise ValueError("OPENAI_API_KEY environment variable is required")
    
    # Create from environment
    return create_provider_from_env("openai")

def create_development_provider(
    api_key: Optional[str] = None,
    model: str = "gpt-4o-mini"
) -> BaseModelProvider:
    """Create provider for development environment."""
    return create_provider(
        provider_type="openai",
        api_key=api_key or os.getenv("OPENAI_API_KEY"),
        model=model,
        temperature=0.7
    )

def get_provider() -> BaseModelProvider:
    """Get provider based on environment."""
    env = os.getenv("ENVIRONMENT", "development")
    
    if env == "production":
        return create_production_provider()
    else:
        return create_development_provider()

# Usage
if __name__ == "__main__":
    try:
        provider = get_provider()
        print(f"Provider created: {provider.get_provider_name()}")
        print(f"Default model: {provider.default_model}")
    except ValueError as e:
        print(f"Configuration error: {e}")
    except ModelProviderError as e:
        print(f"Provider error: {e.message}")

Providers Overview - Provider system overview
Base Provider - Abstract base class
OpenAI Provider - OpenAI implementation
LangGraph Agent - Using providers with agents

TypeScript SDK

Python SDK

Headless UI Components

CLI Tools

Factory Functions

Factory Functions

Functions

create_provider()

Supported Provider Types

Environment Variables by Provider

Examples

create_provider_from_env()

Examples

create_openai_provider()

Examples

Usage Patterns

Development vs Production

Configuration Priority

Multi-Provider Setup

Dynamic Provider Selection

Environment Variable Management

Using .env Files

Environment-Specific Configuration

Validation

Error Handling

Missing Configuration

Unsupported Provider

Not Yet Implemented

Best Practices

1. Use Environment Variables in Production

2. Validate Configuration Early

3. Use Type Hints

4. Document Required Environment Variables

5. Provide Sensible Defaults

Complete Example

TypeScript SDK

Python SDK

Headless UI Components

CLI Tools

​Factory Functions

​Functions

​create_provider()

​Supported Provider Types

​Environment Variables by Provider

​Examples

​create_provider_from_env()

​Examples

​create_openai_provider()

​Examples

​Usage Patterns

​Development vs Production

​Configuration Priority

​Multi-Provider Setup

​Dynamic Provider Selection

​Environment Variable Management

​Using .env Files

​Environment-Specific Configuration

​Validation

​Error Handling

​Missing Configuration

​Unsupported Provider

​Not Yet Implemented

​Best Practices

​1. Use Environment Variables in Production

​2. Validate Configuration Early

​3. Use Type Hints

​4. Document Required Environment Variables

​5. Provide Sensible Defaults

​Complete Example

​Related Documentation

Factory Functions

Functions

create_provider()

Supported Provider Types

Environment Variables by Provider

Examples

create_provider_from_env()

Examples

create_openai_provider()

Examples

Usage Patterns

Development vs Production

Configuration Priority

Multi-Provider Setup

Dynamic Provider Selection

Environment Variable Management

Using .env Files

Environment-Specific Configuration

Validation

Error Handling

Missing Configuration

Unsupported Provider

Not Yet Implemented

Best Practices

1. Use Environment Variables in Production

2. Validate Configuration Early

3. Use Type Hints

4. Document Required Environment Variables

5. Provide Sensible Defaults

Complete Example

Related Documentation