feat: add LLMWithGateway for enterprise OAuth support

Add LLMWithGateway subclass to support enterprise API gateways with
OAuth 2.0 authentication (e.g., APIGEE, Azure API Management).

Key features:
- OAuth 2.0 token fetch and automatic refresh
- Thread-safe token caching with TTL
- Custom header injection for gateway-specific requirements
- Template variable replacement for flexible configuration
- Fully generic implementation (no vendor lock-in)

Implementation approach:
- Separate LLMWithGateway class (addresses PR #963 feedback from neubig)
- Focused feature set for OAuth + custom headers (no over-engineering)
- Comprehensive test coverage
- Complete documentation with examples

This replaces the previous approach of modifying the main LLM class,
keeping the codebase cleaner and more maintainable.

Example usage (APIGEE + Tachyon):
```python
llm = LLMWithGateway(
    model="gemini-1.5-flash",
    base_url=os.environ["TACHYON_API_URL"],
    gateway_auth_url=os.environ["APIGEE_TOKEN_URL"],
    gateway_auth_headers={
        "X-Client-Id": os.environ["APIGEE_CLIENT_ID"],
        "X-Client-Secret": os.environ["APIGEE_CLIENT_SECRET"],
    },
    gateway_auth_body={"grant_type": "client_credentials"},
    custom_headers={"X-Tachyon-Key": os.environ["TACHYON_API_KEY"]},
)
```

Files added:
- openhands-sdk/openhands/sdk/llm/llm_with_gateway.py (new class)
- tests/sdk/llm/test_llm_with_gateway.py (comprehensive tests)
- openhands-sdk/docs/llm_with_gateway.md (API documentation)
- examples/apigee_tachyon_example.py (working example)

Author: ak684

examples/apigee_tachyon_example.py

@@ -0,0 +1,126 @@
+"""Example: Using OpenHands SDK with APIGEE + Tachyon Gateway
+
+This example demonstrates how to configure the OpenHands SDK to work with
+enterprise gateways that use OAuth 2.0 authentication, specifically APIGEE + Tachyon.
+
+Setup:
+1. Set environment variables for your credentials
+2. Run this script to test the connection
+3. Use the same configuration in your OpenHands CLI or application
+
+Requirements:
+- Access to APIGEE OAuth endpoint
+- APIGEE client credentials (key and secret)
+- Tachyon API access and key
+- Tachyon endpoint URL through APIGEE
+"""
+
+import os
+import sys
+
+from openhands.sdk.llm import LLMWithGateway
+
+
+def main():
+    # Check required environment variables
+    required_vars = [
+        "APIGEE_TOKEN_URL",
+        "APIGEE_CLIENT_ID",
+        "APIGEE_CLIENT_SECRET",
+        "TACHYON_API_URL",
+        "TACHYON_API_KEY",
+    ]
+
+    missing_vars = [var for var in required_vars if var not in os.environ]
+    if missing_vars:
+        print("Error: Missing required environment variables:")
+        for var in missing_vars:
+            print(f"  - {var}")
+        print("\nPlease set these variables in your environment:")
+        print("  export APIGEE_TOKEN_URL='https://apigee.example.com/oauth/token'")
+        print("  export APIGEE_CLIENT_ID='your-client-id'")
+        print("  export APIGEE_CLIENT_SECRET='your-client-secret'")
+        print("  export TACHYON_API_URL='https://apigee.example.com/.../tachyon/v1'")
+        print("  export TACHYON_API_KEY='your-tachyon-key'")
+        sys.exit(1)
+
+    # Configure LLM with gateway support
+    print("Configuring LLM with APIGEE + Tachyon gateway...")
+    llm = LLMWithGateway(
+        # Model configuration
+        model="gemini-1.5-flash",  # or "gemini-1.5-pro"
+        base_url=os.environ["TACHYON_API_URL"],
+        # APIGEE OAuth configuration
+        gateway_auth_url=os.environ["APIGEE_TOKEN_URL"],
+        gateway_auth_method="POST",
+        gateway_auth_headers={
+            "Content-Type": "application/json",
+            "X-Client-Id": os.environ["APIGEE_CLIENT_ID"],
+            "X-Client-Secret": os.environ["APIGEE_CLIENT_SECRET"],
+        },
+        gateway_auth_body={
+            "grant_type": "client_credentials",
+            # Add any additional fields required by your APIGEE setup:
+            # "scope": "llm:access",
+            # "audience": "tachyon-api",
+        },
+        gateway_auth_token_path="access_token",  # Adjust if your response differs
+        gateway_auth_token_ttl=86400,  # 24 hours (adjust based on your token expiry)
+        # Tachyon-specific configuration
+        custom_headers={
+            "X-Tachyon-Key": os.environ["TACHYON_API_KEY"],
+            # Add any additional Tachyon headers here
+        },
+        # LLM configuration
+        temperature=0.7,
+        max_output_tokens=1000,
+        usage_id="apigee-tachyon-example",
+    )
+
+    print("✓ LLM configured successfully")
+    print("\nTesting connection...")
+
+    try:
+        # Test with a simple query
+        messages = [{"role": "user", "content": "What is 2 + 2? Reply with just the number."}]
+
+        print("Sending test message to LLM...")
+        response = llm.completion(messages)
+
+        print("✓ Connection successful!")
+        print(f"\nResponse: {response.content[0].text}")
+        print(f"\nMetrics:")
+        print(f"  - Model: {response.model}")
+        print(f"  - Input tokens: {llm.metrics.input_tokens}")
+        print(f"  - Output tokens: {llm.metrics.output_tokens}")
+        print(f"  - Total cost: ${llm.metrics.accumulated_cost:.4f}")
+
+        # Test with a more complex query
+        print("\n" + "=" * 50)
+        print("Testing with a more complex query...")
+
+        messages = [
+            {
+                "role": "user",
+                "content": "Explain what enterprise API gateways like APIGEE do in one sentence.",
+            }
+        ]
+
+        response = llm.completion(messages)
+        print(f"\nResponse: {response.content[0].text}")
+
+        print("\n✓ All tests passed! Your APIGEE + Tachyon setup is working correctly.")
+
+    except Exception as e:
+        print(f"\n✗ Error: {e}")
+        print("\nTroubleshooting:")
+        print("1. Verify your APIGEE credentials are correct")
+        print("2. Check that the APIGEE OAuth URL is accessible")
+        print("3. Ensure the Tachyon API URL is correct")
+        print("4. Verify the Tachyon API key is valid")
+        print("5. Check network connectivity to APIGEE endpoints")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()