solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/agent/adk/models/models_llm.txt

@@ -0,0 +1,189 @@
+# DEVELOPER GUIDE for models directory
+
+## Quick Summary
+This directory contains concrete implementations of the `BaseLlm` interface, providing wrappers for various Large Language Model APIs. These classes translate the ADK's standard `LlmRequest` into provider-specific formats and parse responses back into standard `LlmResponse` objects.
+
+## Files Overview
+- `lite_llm.py` - LLM client using the `litellm` library to support hundreds of models from different providers
+- `oauth2_token_manager.py` - OAuth 2.0 Client Credentials token manager for LLM authentication
+
+## Developer API Reference
+
+### lite_llm.py
+**Purpose:** Provides the `LiteLlm` class, a `BaseLlm` implementation that interfaces with hundreds of LLM models through the `litellm` library. Supports models from OpenAI, Anthropic, Vertex AI, and many other providers by simply changing the model string.
+
+**Import:** `from solace_agent_mesh.agent.adk.models.lite_llm import LiteLlm`
+
+**Classes:**
+- `LiteLlm(model: str, cache_strategy: str = "5m", **kwargs)` - Wrapper around `litellm` supporting any model it recognizes
+  - `generate_content_async(llm_request: LlmRequest, stream: bool = False) -> AsyncGenerator[LlmResponse, None]` - Generates content asynchronously with optional streaming
+  - `supported_models() -> list[str]` - Returns list of supported models (empty for LiteLlm due to dynamic model support)
+  - `model: str` - The name of the LiteLlm model
+  - `llm_client: LiteLLMClient` - The LLM client instance used for API calls
+
+- `LiteLLMClient()` - Internal client providing completion methods for better testability
+  - `acompletion(model, messages, tools, **kwargs) -> Union[ModelResponse, CustomStreamWrapper]` - Asynchronous completion call
+  - `completion(model, messages, tools, stream=False, **kwargs) -> Union[ModelResponse, CustomStreamWrapper]` - Synchronous completion call
+
+- `FunctionChunk(BaseModel)` - Represents a function call chunk in streaming responses
+  - `id: Optional[str]` - Function call ID
+  - `name: Optional[str]` - Function name
+  - `args: Optional[str]` - Function arguments as JSON string
+  - `index: Optional[int]` - Index of the function call
+
+- `TextChunk(BaseModel)` - Represents a text chunk in streaming responses
+  - `text: str` - The text content
+
+- `UsageMetadataChunk(BaseModel)` - Represents token usage information
+  - `prompt_tokens: int` - Number of tokens in the prompt
+  - `completion_tokens: int` - Number of tokens in the completion
+  - `total_tokens: int` - Total number of tokens used
+
+**Functions:**
+- `_content_to_message_param(content: types.Content) -> Union[Message, list[Message]]` - Converts ADK Content to litellm Message format
+- `_get_content(parts: Iterable[types.Part]) -> Union[OpenAIMessageContent, str]` - Converts parts to litellm content format
+- `_function_declaration_to_tool_param(function_declaration: types.FunctionDeclaration) -> dict` - Converts function declarations to OpenAPI spec format
+- `_model_response_to_generate_content_response(response: ModelResponse) -> LlmResponse` - Converts litellm response to LlmResponse
+
+**Usage Examples:**
+```python
+import asyncio
+import os
+from solace_agent_mesh.agent.adk.models.lite_llm import LiteLlm
+from solace_agent_mesh.agent.adk.models.llm_request import LlmRequest, LlmConfig
+from google.genai.types import Content, Part
+
+# Set environment variables for your chosen provider
+# For OpenAI:
+# os.environ["OPENAI_API_KEY"] = "your-api-key"
+# For Vertex AI:
+# os.environ["VERTEXAI_PROJECT"] = "your-project-id"
+# os.environ["VERTEXAI_LOCATION"] = "your-location"
+
+async def main():
+    # Initialize LiteLlm with a specific model
+    llm = LiteLlm(
+        model="gpt-4-turbo",
+        temperature=0.7,
+        max_completion_tokens=150,
+        cache_strategy="5m"  # Options: "none", "5m", "1h"
+    )
+    
+    # Create a request
+    request = LlmRequest(
+        contents=[
+            Content(
+                role="user",
+                parts=[Part.from_text("Explain quantum computing in simple terms")]
+            )
+        ],
+        config=LlmConfig(
+            temperature=0.5,
+            max_output_tokens=200
+        )
+    )
+    
+    # Non-streaming generation
+    print("=== Non-streaming ===")
+    async for response in llm.generate_content_async(request, stream=False):
+        print(f"Response: {response.text}")
+        if response.usage_metadata:
+            print(f"Tokens used: {response.usage_metadata.total_token_count}")
+    
+    # Streaming generation
+    print("\n=== Streaming ===")
+    async for response in llm.generate_content_async(request, stream=True):
+        if response.text:
+            print(response.text, end="", flush=True)
+        if response.usage_metadata:
+            print(f"\nTotal tokens: {response.usage_metadata.total_token_count}")
+
+# Example with OAuth authentication
+async def oauth_example():
+    llm = LiteLlm(
+        model="custom-model",
+        oauth_token_url="https://auth.example.com/oauth/token",
+        oauth_client_id="your-client-id",
+        oauth_client_secret="your-client-secret",
+        oauth_scope="llm.read llm.write",
+        oauth_ca_cert="/path/to/ca.crt",  # Optional
+        oauth_token_refresh_buffer_seconds=300,  # Optional
+        oauth_max_retries=3  # Optional
+    )
+    
+    request = LlmRequest(
+        contents=[Content(role="user", parts=[Part.from_text("Hello!")])]
+    )
+    
+    async for response in llm.generate_content_async(request):
+        print(response.text)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### oauth2_token_manager.py
+**Purpose:** Provides OAuth 2.0 Client Credentials flow implementation for LLM authentication with automatic token management, caching, and refresh capabilities.
+
+**Import:** `from solace_agent_mesh.agent.adk.models.oauth2_token_manager import OAuth2ClientCredentialsTokenManager`
+
+**Classes:**
+- `OAuth2ClientCredentialsTokenManager(token_url: str, client_id: str, client_secret: str, scope: Optional[str] = None, ca_cert_path: Optional[str] = None, refresh_buffer_seconds: int = 300, max_retries: int = 3)` - Manages OAuth 2.0 Client Credentials tokens with caching and automatic refresh
+  - `get_token() -> str` - Get a valid OAuth 2.0 access token (async)
+  - `token_url: str` - OAuth 2.0 token endpoint URL
+  - `client_id: str` - OAuth client identifier
+  - `client_secret: str` - OAuth client secret
+  - `scope: Optional[str]` - OAuth scope (space-separated string)
+  - `ca_cert_path: Optional[str]` - Path to custom CA certificate file
+  - `refresh_buffer_seconds: int` - Seconds before actual expiry to refresh token
+  - `max_retries: int` - Maximum number of retry attempts for token requests
+
+**Usage Examples:**
+```python
+import asyncio
+from solace_agent_mesh.agent.adk.models.oauth2_token_manager import OAuth2ClientCredentialsTokenManager
+
+async def main():
+    # Initialize OAuth token manager
+    token_manager = OAuth2ClientCredentialsTokenManager(
+        token_url="https://auth.example.com/oauth/token",
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+        scope="llm.read llm.write",  # Optional
+        ca_cert_path="/path/to/ca.crt",  # Optional for custom CA
+        refresh_buffer_seconds=300,  # Refresh 5 minutes before expiry
+        max_retries=3  # Retry failed requests up to 3 times
+    )
+    
+    try:
+        # Get a valid access token
+        access_token = await token_manager.get_token()
+        print(f"Access token: {access_token[:20]}...")
+        
+        # Token is automatically cached and reused
+        # Subsequent calls will return cached token if still valid
+        cached_token = await token_manager.get_token()
+        print(f"Cached token: {cached_token[:20]}...")
+        
+    except Exception as e:
+        print(f"Failed to get OAuth token: {e}")
+
+# Example with custom SSL configuration
+async def custom_ssl_example():
+    token_manager = OAuth2ClientCredentialsTokenManager(
+        token_url="https://secure-auth.example.com/oauth/token",
+        client_id="client-123",
+        client_secret="secret-456",
+        ca_cert_path="/etc/ssl/certs/custom-ca.pem",  # Custom CA certificate
+        refresh_buffer_seconds=600,  # Refresh 10 minutes early
+        max_retries=5  # More retries for unreliable networks
+    )
+    
+    token = await token_manager.get_token()
+    print(f"Token obtained with custom SSL: {token[:20]}...")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+# content_hash: 29d771563355d8e4b320350d4fe586f19717d8b16707487efb4372125d5e0f10

solace_agent_mesh/agent/adk/models/oauth2_token_manager.py

@@ -0,0 +1,132 @@
+"""OAuth 2.0 Client Credentials Token Manager.
+
+This module provides OAuth 2.0 Client Credentials flow implementation for LLM authentication.
+It handles token acquisition, caching, and automatic refresh with proper error handling.
+"""
+
+import asyncio
+import logging
+from typing import Optional
+
+from solace_agent_mesh.common.oauth import OAuth2RetryClient, is_token_expired
+from solace_agent_mesh.common.utils.in_memory_cache import InMemoryCache
+
+logger = logging.getLogger(__name__)
+
+
+class OAuth2ClientCredentialsTokenManager:
+    """Manages OAuth 2.0 Client Credentials tokens with caching and automatic refresh.
+    
+    This class implements the OAuth 2.0 Client Credentials flow as defined in RFC 6749.
+    It provides thread-safe token management with automatic refresh before expiration
+    and integrates with the existing InMemoryCache for token storage.
+    
+    Attributes:
+        token_url: OAuth 2.0 token endpoint URL
+        client_id: OAuth client identifier
+        client_secret: OAuth client secret
+        scope: OAuth scope (optional)
+        ca_cert_path: Path to custom CA certificate (optional)
+        refresh_buffer_seconds: Seconds before expiry to refresh token
+    """
+
+    def __init__(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        scope: Optional[str] = None,
+        ca_cert_path: Optional[str] = None,
+        refresh_buffer_seconds: int = 300,
+        max_retries: int = 3,
+    ):
+        """Initialize the OAuth2 Client Credentials Token Manager.
+        
+        Args:
+            token_url: OAuth 2.0 token endpoint URL
+            client_id: OAuth client identifier
+            client_secret: OAuth client secret
+            scope: OAuth scope (optional, space-separated string)
+            ca_cert_path: Path to custom CA certificate file (optional)
+            refresh_buffer_seconds: Seconds before actual expiry to refresh token
+            max_retries: Maximum number of retry attempts for token requests
+            
+        Raises:
+            ValueError: If required parameters are missing or invalid
+        """
+        if not token_url:
+            raise ValueError("token_url is required")
+        if not client_id:
+            raise ValueError("client_id is required")
+        if not client_secret:
+            raise ValueError("client_secret is required")
+        if refresh_buffer_seconds < 0:
+            raise ValueError("refresh_buffer_seconds must be non-negative")
+            
+        self.token_url = token_url
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.scope = scope
+        self.ca_cert_path = ca_cert_path
+        self.refresh_buffer_seconds = refresh_buffer_seconds
+
+        # Thread-safe token access
+        self._lock = asyncio.Lock()
+
+        # Token cache using existing InMemoryCache singleton
+        self._cache = InMemoryCache()
+
+        # Cache key for this token manager instance
+        self._cache_key = f"oauth_token_{hash((token_url, client_id))}"
+
+        # OAuth client with retry logic
+        self._oauth_client = OAuth2RetryClient(max_retries=max_retries)
+
+        logger.info(
+            "OAuth2ClientCredentialsTokenManager initialized for endpoint: %s",
+            token_url
+        )
+
+    async def get_token(self) -> str:
+        """Get a valid OAuth 2.0 access token.
+        
+        This method checks the cache first and returns a cached token if it's still valid.
+        If no token exists or the token is expired/near expiry, it fetches a new token.
+        
+        Returns:
+            Valid OAuth 2.0 access token
+            
+        Raises:
+            httpx.HTTPError: If token request fails
+            ValueError: If token response is invalid
+        """
+        async with self._lock:
+            # Check if we have a cached token
+            cached_token_data = self._cache.get(self._cache_key)
+
+            if cached_token_data and not is_token_expired(
+                cached_token_data["expires_at"], buffer_seconds=self.refresh_buffer_seconds
+            ):
+                logger.debug("Using cached OAuth token")
+                return cached_token_data["access_token"]
+
+            # Fetch new token using common OAuth client
+            logger.info("Fetching new OAuth token from %s", self.token_url)
+            verify = self.ca_cert_path if self.ca_cert_path else True
+            token_data = await self._oauth_client.fetch_client_credentials_token(
+                token_url=self.token_url,
+                client_id=self.client_id,
+                client_secret=self.client_secret,
+                scope=self.scope,
+                verify=verify,
+                timeout=30.0,
+            )
+            
+            # Cache the token with TTL
+            expires_in = token_data.get("expires_in", 3600)  # Default 1 hour
+            cache_ttl = max(expires_in - self.refresh_buffer_seconds, 60)  # Min 1 minute
+            
+            self._cache.set(self._cache_key, token_data, ttl=cache_ttl)
+            
+            logger.info("OAuth token cached with TTL: %d seconds", cache_ttl)
+            return token_data["access_token"]