Skip to content

refactor: Implement conditional imports for all integration modules #480

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 8 commits into from
Jul 10, 2025
Merged

refactor: Implement conditional imports for all integration modules #480

merged 8 commits into from
Jul 10, 2025

Conversation

viniciusdsmello
Copy link
Contributor

Implement conditional imports for all integration modules

Summary

Converts all integration modules to use conditional imports, making external dependencies truly optional. Users can now install only the integrations they need without being forced to install all third-party libraries.

Problem Solved

Previously, importing any integration module would fail if the corresponding third-party library wasn't installed, even if users didn't intend to use that specific integration. This created poor UX and unnecessary dependency bloat.

Changes Made

Integration Modules Updated

  • ✅ openai_tracer.py - OpenAI SDK support
  • ✅ async_openai_tracer.py - Async OpenAI SDK support
  • ✅ anthropic_tracer.py - Anthropic SDK support
  • ✅ groq_tracer.py - Groq SDK support
  • ✅ mistral_tracer.py - Mistral SDK support
  • ✅ langchain_callback.py - LangChain support
  • ✅ openai_agents.py - OpenAI Agents SDK support (already implemented)

Implementation Pattern

Each module now follows a consistent conditional import pattern:

from typing import TYPE_CHECKING

try:
    import third_party_lib
    HAVE_LIB = True
except ImportError:
    HAVE_LIB = False

if TYPE_CHECKING:
    import third_party_lib

# Functions use string type annotations
def trace_lib(client: "third_party_lib.Client") -> "third_party_lib.Client":
    if not HAVE_LIB:
        raise ImportError("Library not installed. Install with: pip install library")
    # ... implementation

User Experience Improvements

Before

pip install openlayer
>>> import openlayer.lib.integrations.anthrophic_tracer
ImportError: No module named 'openai'  # Even if user doesn't need OpenAI

After

pip install openlayer  # Works fine, no integration deps required
>>> import openlayer.lib.integrations.openai_tracer  # ✅ Imports successfully
>>> from openlayer.lib.integrations.openai_tracer import trace_openai
>>> trace_openai(client)
ImportError: OpenAI library is not installed. Please install it with: pip install openai

Key Features

1. Graceful Import Handling

  • All modules import successfully without dependencies
  • Clear error messages when attempting to use missing dependencies
  • Type hints work correctly via TYPE_CHECKING

2. Availability Flags

  • Each module exposes HAVE_* flags for programmatic detection
  • Enables conditional feature availability in user code

3. Helpful Error Messages

  • Specific installation instructions for each library
  • Errors only occur when actually trying to use functionality

4. Type Safety Preserved

  • String literal type annotations prevent runtime NameError
  • Full type checking support when dependencies are installed

Testing

Comprehensive testing ensures all modules:

  • Import successfully without dependencies installed
  • Raise appropriate ImportError when functionality is accessed
  • Have correct availability flags
  • Maintain type annotation compatibility

Dependencies

No changes to pyproject.toml required - integration libraries were already correctly excluded from required dependencies. This change makes the existing dependency structure work as intended.

Impact

  • Reduced installation size - Users only install what they need
  • Improved developer experience - Clear error messages guide users
  • Better modularity - True optional dependencies
  • Maintained functionality - No breaking changes when deps are installed

Checklist

  • Applied conditional import pattern to all integration modules
  • Added availability flags (HAVE_*) to all modules
  • Implemented helpful error messages
  • Used string type annotations for forward compatibility
  • Verified all modules import without dependencies
  • Verified functionality works when dependencies are present
  • Cleaned up temporary test files
  • Followed existing project conventions

@viniciusdsmello
feat(tests): add integration tests for conditional imports in modules
a30e0fd 
- Introduced a new test suite to validate that integration modules handle optional dependencies correctly.
- Ensured modules can be imported when dependencies are missing and provide helpful error messages.
- Verified that all integration modules exist and can be imported when dependencies are available.
- Implemented comprehensive checks for availability flags and graceful import handling.
- This addition prevents regressions in conditional import handling across all integrations.
@viniciusdsmello
feat(tracer): enhance conditional imports and type hinting for Anthro…
3229f41 
…pic integration

- Implemented conditional import handling for the `anthropic` library, allowing for graceful degradation when the library is not installed.
- Added type hints for `anthropic` types using forward references to improve code clarity and maintainability.
- Introduced an informative error message when the `anthropic` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the Anthropic integration.
@viniciusdsmello
feat(tracer): improve conditional imports and type hinting for OpenAI…
eda36c0 
… integration

- Implemented conditional import handling for the `openai` library, allowing for graceful degradation when the library is not installed.
- Enhanced type hints using forward references for `openai` types to improve code clarity and maintainability.
- Introduced informative error messages when the `openai` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the OpenAI integration.
@viniciusdsmello
feat(tracer): enhance conditional imports and type hinting for Mistra…
9801e91 
…l integration

- Implemented conditional import handling for the `mistralai` library, allowing for graceful degradation when the library is not installed.
- Improved type hints using forward references for `mistralai` types to enhance code clarity and maintainability.
- Introduced an informative error message when the `mistralai` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the Mistral integration.
@viniciusdsmello
feat(tracer): enhance conditional imports and type hinting for Groq i…
7639007 
…ntegration

- Implemented conditional import handling for the `groq` library, allowing for graceful degradation when the library is not installed.
- Improved type hints using forward references for `groq` types to enhance code clarity and maintainability.
- Introduced an informative error message when the `groq` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the Groq integration.
@viniciusdsmello
feat(tracer): enhance conditional imports and type hinting for OpenAI…
d521c4b 
… integration

- Improved conditional import handling for the `openai` library, ensuring graceful degradation when the library is not installed.
- Enhanced type hints using forward references for `openai` types to improve code clarity and maintainability.
- Added an informative error message when the `openai` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the OpenAI integration.
@viniciusdsmello
feat(langchain): enhance conditional imports and type hinting for Lan…
23dc35d 
…gChain integration

- Implemented conditional import handling for the `langchain` library, allowing for graceful degradation when the library is not installed.
- Improved type hints using forward references for `langchain` types to enhance code clarity and maintainability.
- Introduced an informative error message when the `langchain` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the LangChain integration.
@viniciusdsmello viniciusdsmello self-assigned this Jul 10, 2025
@viniciusdsmello viniciusdsmello added the enhancement New feature or request label Jul 10, 2025
@whoseoyster whoseoyster changed the base branch from main to next July 10, 2025 17:52
@viniciusdsmello
fix(tests): improve exception handling in integration test for condit…
03facc3 
…ional imports

- Enhanced exception handling in the `run_integration_test` function by specifying `FileNotFoundError` and `OSError` in the exception clause, ensuring more precise error management.
- This update prevents potential silent failures when attempting to unlink temporary files, improving the robustness of the integration tests for conditional imports.
@viniciusdsmello viniciusdsmello merged commit bf99015 into next Jul 10, 2025
4 checks passed
@viniciusdsmello viniciusdsmello deleted the adds-conditional-imports-pattern branch July 10, 2025 18:30
@stainless-app stainless-app bot mentioned this pull request Jul 10, 2025
Merged
stainless-app bot pushed a commit that referenced this pull request Jul 11, 2025
@viniciusdsmello @stainless-app
refactor: Implement conditional imports for all integration modules (#…
e20a448 
…480)

* feat(tests): add integration tests for conditional imports in modules

- Introduced a new test suite to validate that integration modules handle optional dependencies correctly.
- Ensured modules can be imported when dependencies are missing and provide helpful error messages.
- Verified that all integration modules exist and can be imported when dependencies are available.
- Implemented comprehensive checks for availability flags and graceful import handling.
- This addition prevents regressions in conditional import handling across all integrations.

* feat(tracer): enhance conditional imports and type hinting for Anthropic integration

- Implemented conditional import handling for the `anthropic` library, allowing for graceful degradation when the library is not installed.
- Added type hints for `anthropic` types using forward references to improve code clarity and maintainability.
- Introduced an informative error message when the `anthropic` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the Anthropic integration.

* feat(tracer): improve conditional imports and type hinting for OpenAI integration

- Implemented conditional import handling for the `openai` library, allowing for graceful degradation when the library is not installed.
- Enhanced type hints using forward references for `openai` types to improve code clarity and maintainability.
- Introduced informative error messages when the `openai` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the OpenAI integration.

* feat(tracer): enhance conditional imports and type hinting for Mistral integration

- Implemented conditional import handling for the `mistralai` library, allowing for graceful degradation when the library is not installed.
- Improved type hints using forward references for `mistralai` types to enhance code clarity and maintainability.
- Introduced an informative error message when the `mistralai` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the Mistral integration.

* feat(tracer): enhance conditional imports and type hinting for Groq integration

- Implemented conditional import handling for the `groq` library, allowing for graceful degradation when the library is not installed.
- Improved type hints using forward references for `groq` types to enhance code clarity and maintainability.
- Introduced an informative error message when the `groq` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the Groq integration.

* feat(tracer): enhance conditional imports and type hinting for OpenAI integration

- Improved conditional import handling for the `openai` library, ensuring graceful degradation when the library is not installed.
- Enhanced type hints using forward references for `openai` types to improve code clarity and maintainability.
- Added an informative error message when the `openai` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the OpenAI integration.

* feat(langchain): enhance conditional imports and type hinting for LangChain integration

- Implemented conditional import handling for the `langchain` library, allowing for graceful degradation when the library is not installed.
- Improved type hints using forward references for `langchain` types to enhance code clarity and maintainability.
- Introduced an informative error message when the `langchain` library is missing, guiding users on how to install it.
- This update ensures better compatibility and user experience when working with optional dependencies in the LangChain integration.

* fix(tests): improve exception handling in integration test for conditional imports

- Enhanced exception handling in the `run_integration_test` function by specifying `FileNotFoundError` and `OSError` in the exception clause, ensuring more precise error management.
- This update prevents potential silent failures when attempting to unlink temporary files, improving the robustness of the integration tests for conditional imports.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@whoseoyster whoseoyster whoseoyster approved these changes

Assignees

@viniciusdsmello viniciusdsmello

Labels
enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@viniciusdsmello @whoseoyster
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy