Skip to content

OpenAI Client API Reference

Direct OpenAI API client for GPT models. This client implements the BaseLLMClient interface using httpx to communicate directly with the OpenAI API.

Overview

The OpenAI client provides:

  • Direct HTTP communication with OpenAI's API
  • Implements the BaseLLMClient abstract interface
  • JSON response parsing with error handling
  • Call counting for usage tracking
  • Cost estimation for API calls
  • Configurable timeout and retry settings

Usage

from causaliq_knowledge.llm import OpenAIClient, OpenAIConfig

# Create client with custom config
config = OpenAIConfig(
    model="gpt-4o-mini",
    temperature=0.1,
    max_tokens=500,
)
client = OpenAIClient(config=config)

# Make a completion request
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is 2+2?"},
]
response = client.completion(messages)
print(response.content)

# Parse JSON response
json_data = response.parse_json()

Environment Variables

The OpenAI client requires the OPENAI_API_KEY environment variable to be set:

export OPENAI_API_KEY=your_api_key_here

OpenAIConfig

OpenAIConfig dataclass 

OpenAIConfig(
    model: str = "gpt-4o-mini",
    temperature: float = 0.1,
    max_tokens: int = 500,
    timeout: float = 30.0,
    api_key: Optional[str] = None,
)

Configuration for OpenAI API client.

Extends OpenAICompatConfig with OpenAI-specific defaults.

Attributes:

  • model (str) –

    OpenAI model identifier (default: gpt-4o-mini).

  • temperature (float) –

    Sampling temperature (default: 0.1).

  • max_tokens (int) –

    Maximum response tokens (default: 500).

  • timeout (float) –

    Request timeout in seconds (default: 30.0).

  • api_key (Optional[str]) –

    OpenAI API key (falls back to OPENAI_API_KEY env var).

Methods:

  • __post_init__ –

    Set API key from environment if not provided.

api_key class-attribute instance-attribute 

api_key: Optional[str] = None

max_tokens class-attribute instance-attribute 

max_tokens: int = 500

model class-attribute instance-attribute 

model: str = 'gpt-4o-mini'

temperature class-attribute instance-attribute 

temperature: float = 0.1

timeout class-attribute instance-attribute 

timeout: float = 30.0

__post_init__ 

__post_init__() -> None

Set API key from environment if not provided.

OpenAIClient

OpenAIClient 

OpenAIClient(config: Optional[OpenAIConfig] = None)

Direct OpenAI API client.

Implements the BaseLLMClient interface for OpenAI's API. Uses httpx for HTTP requests.

Example

config = OpenAIConfig(model="gpt-4o-mini") client = OpenAIClient(config) msgs = [{"role": "user", "content": "Hello"}] response = client.completion(msgs) print(response.content)

Parameters:

  • config

    (Optional[OpenAIConfig], default: None ) –

    OpenAI configuration. If None, uses defaults with API key from OPENAI_API_KEY environment variable.

Methods:

Attributes:

BASE_URL class-attribute instance-attribute 

BASE_URL = 'https://api.openai.com/v1'

ENV_VAR class-attribute instance-attribute 

ENV_VAR = 'OPENAI_API_KEY'

PROVIDER_NAME class-attribute instance-attribute 

PROVIDER_NAME = 'openai'

_total_calls instance-attribute 

_total_calls = 0

cache property 

cache: Optional['TokenCache']

Return the configured cache, if any.

call_count property 

call_count: int

Return the number of API calls made.

config instance-attribute 

config = config or _default_config()

model_name property 

model_name: str

Return the model name being used.

Returns:

  • str –

    Model identifier string.

provider_name property 

provider_name: str

Return the provider name.

use_cache property 

use_cache: bool

Return whether caching is enabled.

_build_cache_key 

_build_cache_key(
    messages: List[Dict[str, str]],
    temperature: Optional[float] = None,
    max_tokens: Optional[int] = None,
) -> str

Build a deterministic cache key for the request.

Creates a SHA-256 hash from the model, messages, temperature, and max_tokens. The hash is truncated to 16 hex characters (64 bits).

Parameters:

  • messages
    (List[Dict[str, str]]) –

    List of message dicts with "role" and "content" keys.

  • temperature
    (Optional[float], default: None ) –

    Sampling temperature (defaults to config value).

  • max_tokens
    (Optional[int], default: None ) –

    Maximum tokens (defaults to config value).

Returns:

  • str –

    16-character hex string cache key.

_calculate_cost 

_calculate_cost(model: str, input_tokens: int, output_tokens: int) -> float

Calculate approximate cost for API call.

Parameters:

  • model
    (str) –

    Model identifier.

  • input_tokens
    (int) –

    Number of input tokens.

  • output_tokens
    (int) –

    Number of output tokens.

Returns:

  • float –

    Estimated cost in USD.

_default_config 

_default_config() -> OpenAIConfig

Return default OpenAI configuration.

_filter_models 

_filter_models(models: List[str]) -> List[str]

Filter to OpenAI chat models only.

Parameters:

  • models
    (List[str]) –

    List of all model IDs from API.

Returns:

  • List[str] –

    Filtered list of GPT and o1/o3 models.

_get_pricing 

_get_pricing() -> Dict[str, Dict[str, float]]

Return OpenAI pricing per 1M tokens.

Returns:

  • Dict[str, Dict[str, float]] –

    Dict mapping model prefixes to input/output costs.

cached_completion 

cached_completion(messages: List[Dict[str, str]], **kwargs: Any) -> LLMResponse

Make a completion request with caching.

If caching is enabled and a cached response exists, returns the cached response without making an API call. Otherwise, makes the API call and caches the result.

Parameters:

  • messages
    (List[Dict[str, str]]) –

    List of message dicts with "role" and "content" keys.

  • **kwargs
    (Any, default: {} ) –

    Provider-specific options (temperature, max_tokens, etc.)

Returns:

  • LLMResponse –

    LLMResponse with the generated content and metadata.

complete_json 

complete_json(
    messages: List[Dict[str, str]], **kwargs: Any
) -> tuple[Optional[Dict[str, Any]], LLMResponse]

Make a completion request and parse response as JSON.

Parameters:

  • messages
    (List[Dict[str, str]]) –

    List of message dicts with "role" and "content" keys.

  • **kwargs
    (Any, default: {} ) –

    Override config options passed to completion().

Returns:

  • tuple[Optional[Dict[str, Any]], LLMResponse] –

    Tuple of (parsed JSON dict or None, raw LLMResponse).

completion 

completion(messages: List[Dict[str, str]], **kwargs: Any) -> LLMResponse

Make a chat completion request.

Parameters:

  • messages
    (List[Dict[str, str]]) –

    List of message dicts with "role" and "content" keys.

  • **kwargs
    (Any, default: {} ) –

    Override config options (temperature, max_tokens).

Returns:

  • LLMResponse –

    LLMResponse with the generated content and metadata.

Raises:

  • ValueError –

    If the API request fails.

is_available 

is_available() -> bool

Check if the API is available.

Returns:

  • bool –

    True if API key is configured.

list_models 

list_models() -> List[str]

List available models from the API.

Queries the API to get models accessible with the current API key, then filters using _filter_models().

Returns:

  • List[str] –

    List of model identifiers.

Raises:

  • ValueError –

    If the API request fails.

set_cache 

set_cache(cache: Optional['TokenCache'], use_cache: bool = True) -> None

Configure caching for this client.

Parameters:

  • cache
    (Optional['TokenCache']) –

    TokenCache instance for caching, or None to disable.

  • use_cache
    (bool, default: True ) –

    Whether to use the cache (default True).

Supported Models

OpenAI provides the GPT family of models:

Model Description Free Tier
gpt-4o GPT-4o - flagship multimodal model ❌ No
gpt-4o-mini GPT-4o Mini - affordable and fast ❌ No
gpt-4-turbo GPT-4 Turbo - high capability ❌ No
gpt-3.5-turbo GPT-3.5 Turbo - fast and economical ❌ No
o1 o1 - reasoning model ❌ No
o1-mini o1 Mini - efficient reasoning ❌ No

See OpenAI documentation for the full list of available models and pricing.