Add Programmatic Configuration Support for Tracing Decorators

🚀 Overview

This PR adds the ability to programmatically configure API keys and pipeline IDs for Openlayer tracing decorators, providing an alternative to environment variables for more flexible runtime configuration.

🎯 Problem

Previously, users could only configure tracing through environment variables:

# Only option before this PR
os.environ["OPENLAYER_API_KEY"] = "your_api_key_here"
os.environ["OPENLAYER_INFERENCE_PIPELINE_ID"] = "your_pipeline_id_here"

@trace()
def my_function():
    return "result"

This approach had limitations:

• No runtime flexibility - configuration must be set before application startup
• Multi-environment challenges - difficult to switch between different API keys/pipeline IDs
• Docker/containerization issues - requires environment variable management in deployment
• Testing complexity - harder to mock or override configuration in tests

✨ Solution

Added a new configure() function that allows programmatic configuration with a clear precedence chain:

🔧 New configure() Function

from openlayer.lib import configure, trace

# Configure once at application startup
configure(
    api_key="your_api_key_here",
    inference_pipeline_id="your_pipeline_id_here",
    base_url="https://custom.api.com/v1"  # Optional
)

# Use decorators normally - no environment variables needed
@trace()
def my_function():
    return "result"

📋 Configuration Precedence

1. Highest: Values passed directly to decorators (@trace(inference_pipeline_id="specific"))
2. Medium: Values set via configure() function
3. Lowest: Environment variables (maintains backward compatibility)

🎨 Key Features

✅ Flexible Configuration Options

# Basic programmatic configuration
configure(
    api_key="your_api_key",
    inference_pipeline_id="your_pipeline_id"
)

# Per-decorator override
@trace()  # Uses configured default
def func1():
    pass

@trace(inference_pipeline_id="override_pipeline")  # Overrides default
def func2():
    pass

# Mixed approach (environment + programmatic)
os.environ["OPENLAYER_API_KEY"] = "env_key"
configure(inference_pipeline_id="programmatic_pipeline")

✅ Runtime Configuration Changes

# Switch configurations at runtime
configure(api_key="dev_key", inference_pipeline_id="dev_pipeline")
run_development_tests()

configure(api_key="prod_key", inference_pipeline_id="prod_pipeline")  
run_production_workload()

✅ Testing Support

# Easy mocking in tests
def test_my_function():
    configure(
        api_key="test_key",
        inference_pipeline_id="test_pipeline"
    )
    # Test with known configuration
    result = my_traced_function()
    assert result == expected_value

🛠 Technical Implementation

Enhanced Client Initialization

• Modified _get_client() to use configured values with fallback to environment variables
• Client recreation when configuration changes (lazy initialization)
• Support for custom base URLs and SSL configuration

Pipeline ID Precedence Chain

• Updated _handle_trace_completion() to implement proper precedence logic
• Maintained all existing functionality while adding new configuration options

Public API Integration

• Added configure to public exports in src/openlayer/lib/__init__.py
• Comprehensive docstrings with usage examples

📝 Usage Examples

Multi-Environment Application

from openlayer.lib import configure

class MyApp:
    def __init__(self, environment: str):
        if environment == "development":
            configure(
                api_key=dev_config.openlayer_key,
                inference_pipeline_id=dev_config.pipeline_id
            )
        elif environment == "production":
            configure(
                api_key=prod_config.openlayer_key,
                inference_pipeline_id=prod_config.pipeline_id
            )

Dynamic Configuration

# Load from database, secrets manager, etc.
config = load_config_from_database()
configure(
    api_key=config.get("openlayer_api_key"),
    inference_pipeline_id=config.get("pipeline_id")
)

⚠️ Breaking Changes

None - This is a purely additive change that maintains full backward compatibility with existing environment variable usage.

🧪 Testing

• ✅ 9 new comprehensive tests covering all configuration scenarios
• ✅ Backward compatibility verified - existing environment variable behavior unchanged
• ✅ Integration tests - verified existing tracing functionality still works
• ✅ Precedence testing - confirmed proper fallback chain behavior

Test Coverage

python -m pytest tests/test_tracer_configuration.py -v
# ============================================ 9 passed in 7.78s ============================================

📁 Files Changed

• src/openlayer/lib/tracing/tracer.py - Added configure() function and enhanced client initialization
• src/openlayer/lib/__init__.py - Exported configure to public API
• examples/tracing/programmatic_configuration.py - Comprehensive usage examples
• tests/test_tracer_configuration.py - Full test suite covering all scenarios

🎉 Benefits

1. 🔄 Runtime Flexibility - Change configuration without restarting applications
2. 🏗️ Better Architecture - Cleaner separation of configuration from deployment
3. 🧪 Enhanced Testing - Easier to mock and test different configurations
4. 📦 Container-Friendly - Reduces dependency on environment variable management
5. 🔒 Security - Enables integration with secrets management systems
6. ⚡ Zero Disruption - Existing code continues to work unchanged

📖 Documentation

Added comprehensive examples in examples/tracing/programmatic_configuration.py demonstrating:

• Environment variable approach (existing)
• Programmatic configuration (new)
• Per-decorator overrides
• Mixed configuration strategies

All functions include detailed docstrings with usage examples and parameter descriptions.