Enhance openai-agents with Model Improvements, Retry Logic, and Caching

[adhishthite]

Pull Request Summary

Overall Summary

This PR enhances the openai-agents package by improving its model interaction capabilities. Key improvements include:

• Structured Module: The new __init__.py organizes the models module, making it easier to use and extend.
• Improved OpenAI Utilities: Enhanced type safety, documentation, and client creation in _openai_shared.py.
• Retry Logic: ModelRetrySettings adds resilience to API failures with configurable retries and backoff.
• Provider Enhancements: openai_provider.py gains better default model handling and error management.
• Utilities: New caching, token estimation, and validation functions in utils.py improve performance and reliability.
• Version Bump: Updated to 0.0.8, marking a significant feature release.

These changes collectively make the package more robust, maintainable, and efficient for interacting with OpenAI models.

---

File-by-File Changes

1. src/agents/models/__init__.py (New File)

• Purpose: Initializes the models module, providing a clear entry point for model-related functionality.
• Changes:
  • Exports key components from submodules: _openai_shared, interface, openai_chatcompletions, openai_provider, openai_responses, and utils.
  • Defines the module's public API via __all__, including:
    • Interfaces: Model, ModelProvider, ModelRetrySettings, ModelTracing
    • OpenAI utilities: TOpenAIClient, create_client, etc.
    • Model implementations: OpenAIChatCompletionsModel, OpenAIProvider, OpenAIResponsesModel
    • Utilities: cache_model_response, get_token_count_estimate, etc.
• Impact: Establishes a structured and modular approach to model implementations and utilities.

2. src/agents/models/_openai_shared.py

• Purpose: Contains shared utilities for OpenAI client management.
• Changes:
  • Imports and Type Aliases:
    • Added logging and type aliases: TOpenAIClient = AsyncOpenAI and TOpenAIClientOptions = dict[str, Any] for better type hinting.
  • Logger:
    • Introduced _logger for error logging.
  • Function Enhancements:
    • Added docstrings to set_default_openai_key, get_default_openai_key, set_default_openai_client, get_default_openai_client, set_use_responses_by_default, and get_use_responses_by_default for clarity.
    • New function create_client standardizes OpenAI client creation with optional parameters (api_key, base_url, etc.).
• Impact: Improves code maintainability, documentation, and consistency in client instantiation.

3. src/agents/models/interface.py

• Purpose: Defines interfaces and settings for model interactions.
• Changes:
  • Imports:
    • Added asyncio, dataclass, field from dataclasses, and Any, Callable from typing.
  • New ModelRetrySettings Class:
    • A dataclass to manage retry logic for model API calls.
    • Attributes: max_retries (default 3), initial_backoff_seconds (1.0), max_backoff_seconds (30.0), backoff_multiplier (2.0), and retryable_status_codes (e.g., 429, 500).
    • Method execute_with_retry: Implements exponential backoff retry logic for async operations.
• Impact: Enhances reliability by providing a robust retry mechanism for handling transient API failures.

4. src/agents/models/openai_provider.py

• Purpose: Implements the OpenAI provider for model interactions.
• Changes:
  • Imports and Logger:
    • Added logging and _logger, plus TOpenAIClient and create_client from _openai_shared.
  • Default Model:
    • Updated DEFAULT_MODEL to "gpt-4o".
  • Constructor:
    • Added default_model parameter (defaults to DEFAULT_MODEL).
    • _client typed as TOpenAIClient | None.
  • Client Creation:
    • _get_client now uses create_client if no default client exists, with error logging for failures.
  • Model Retrieval:
    • get_model uses default_model if no model_name is provided, returning an appropriate OpenAI model implementation.
• Impact: Improves flexibility, error handling, and default model management.

5. src/agents/models/utils.py (New File)

• Purpose: Provides utility functions for model implementations.
• Changes:
  • Cache Management:
    • Functions: set_cache_ttl, clear_cache, compute_cache_key, and a cache_model_response decorator.
    • Uses an in-memory cache with a default 5-minute TTL.
  • Token Estimation:
    • get_token_count_estimate: Estimates token count (approx. 4 characters per token).
  • Response Validation:
    • validate_response: Checks if a response is a valid ChatCompletion or Response object.
• Impact: Boosts performance via caching and provides helper tools for token counting and response validation.

6. uv.lock

• Purpose: Tracks package dependencies and versions.
• Changes:
  • Updated openai-agents version from 0.0.7 to 0.0.8.
• Impact: Reflects a new release incorporating these changes.