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

solace_agent_mesh/agent/adk/artifacts/artifacts_llm.txt

@@ -1,171 +0,0 @@
-# DEVELOPER GUIDE: artifacts
-
-## Quick Summary
-The artifacts directory provides ADK ArtifactService implementations for the Solace Agent Mesh. It includes filesystem and S3-compatible storage backends for managing artifacts with versioning, user namespacing, and session-based organization.
-
-## Files Overview
-- `__init__.py` - Package initialization for artifact service implementations
-- `filesystem_artifact_service.py` - Local filesystem-based artifact storage implementation
-- `s3_artifact_service.py` - Amazon S3 compatible storage implementation for artifacts
-
-## Developer API Reference
-
-### filesystem_artifact_service.py
-**Purpose:** Provides local filesystem storage for artifacts with structured directory organization and metadata management.
-
-**Import:** `from solace_agent_mesh.agent.adk.artifacts.filesystem_artifact_service import FilesystemArtifactService`
-
-**Classes:**
-- `FilesystemArtifactService(base_path: str)` - Filesystem-based artifact service implementation
-  - `save_artifact(*, app_name: str, user_id: str, session_id: str, filename: str, artifact: adk_types.Part) -> int` - Saves an artifact and returns version number
-  - `load_artifact(*, app_name: str, user_id: str, session_id: str, filename: str, version: int | None = None) -> adk_types.Part | None` - Loads an artifact by version (latest if None)
-  - `list_artifact_keys(*, app_name: str, user_id: str, session_id: str) -> list[str]` - Lists all artifact filenames for a scope
-  - `delete_artifact(*, app_name: str, user_id: str, session_id: str, filename: str) -> None` - Deletes all versions of an artifact
-  - `list_versions(*, app_name: str, user_id: str, session_id: str, filename: str) -> list[int]` - Lists all version numbers for an artifact
-  - `base_path: str` - Root directory for artifact storage
-
-**Constants/Variables:**
-- `METADATA_FILE_SUFFIX: str` - File suffix for metadata files (".meta")
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.adk.artifacts.filesystem_artifact_service import FilesystemArtifactService
-from google.genai import types as adk_types
-
-# Initialize the service
-artifact_service = FilesystemArtifactService(base_path="/path/to/artifacts")
-
-# Save an artifact
-artifact_data = b"Hello, World!"
-artifact_part = adk_types.Part.from_bytes(data=artifact_data, mime_type="text/plain")
-version = await artifact_service.save_artifact(
-    app_name="my_app",
-    user_id="user123",
-    session_id="session456",
-    filename="greeting.txt",
-    artifact=artifact_part
-)
-
-# Load the latest version
-loaded_artifact = await artifact_service.load_artifact(
-    app_name="my_app",
-    user_id="user123", 
-    session_id="session456",
-    filename="greeting.txt"
-)
-
-# Load a specific version
-specific_version = await artifact_service.load_artifact(
-    app_name="my_app",
-    user_id="user123",
-    session_id="session456", 
-    filename="greeting.txt",
-    version=1
-)
-
-# List all artifacts
-artifact_keys = await artifact_service.list_artifact_keys(
-    app_name="my_app",
-    user_id="user123",
-    session_id="session456"
-)
-
-# List versions of an artifact
-versions = await artifact_service.list_versions(
-    app_name="my_app",
-    user_id="user123",
-    session_id="session456",
-    filename="greeting.txt"
-)
-
-# Delete an artifact
-await artifact_service.delete_artifact(
-    app_name="my_app",
-    user_id="user123",
-    session_id="session456",
-    filename="greeting.txt"
-)
-```
-
-### s3_artifact_service.py
-**Purpose:** Provides S3-compatible storage for artifacts with structured key organization and AWS integration.
-
-**Import:** `from solace_agent_mesh.agent.adk.artifacts.s3_artifact_service import S3ArtifactService`
-
-**Classes:**
-- `S3ArtifactService(bucket_name: str, s3_client: BaseClient | None = None, **kwargs)` - S3-based artifact service implementation
-  - `save_artifact(*, app_name: str, user_id: str, session_id: str, filename: str, artifact: adk_types.Part) -> int` - Saves an artifact to S3 and returns version number
-  - `load_artifact(*, app_name: str, user_id: str, session_id: str, filename: str, version: int | None = None) -> adk_types.Part | None` - Loads an artifact from S3 by version (latest if None)
-  - `list_artifact_keys(*, app_name: str, user_id: str, session_id: str) -> list[str]` - Lists all artifact filenames for a scope
-  - `delete_artifact(*, app_name: str, user_id: str, session_id: str, filename: str) -> None` - Deletes all versions of an artifact from S3
-  - `list_versions(*, app_name: str, user_id: str, session_id: str, filename: str) -> list[int]` - Lists all version numbers for an artifact
-  - `bucket_name: str` - S3 bucket name for storage
-  - `s3: BaseClient` - Boto3 S3 client instance
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.adk.artifacts.s3_artifact_service import S3ArtifactService
-from google.genai import types as adk_types
-import boto3
-
-# Initialize with default credentials
-artifact_service = S3ArtifactService(bucket_name="my-artifacts-bucket")
-
-# Initialize with custom S3 client
-s3_client = boto3.client(
-    's3',
-    endpoint_url='https://minio.example.com',
-    aws_access_key_id='access_key',
-    aws_secret_access_key='secret_key'
-)
-artifact_service = S3ArtifactService(
-    bucket_name="my-artifacts-bucket",
-    s3_client=s3_client
-)
-
-# Save an artifact
-artifact_data = b"Hello, S3!"
-artifact_part = adk_types.Part.from_bytes(data=artifact_data, mime_type="text/plain")
-version = await artifact_service.save_artifact(
-    app_name="my_app",
-    user_id="user123",
-    session_id="session456", 
-    filename="greeting.txt",
-    artifact=artifact_part
-)
-
-# Load the latest version
-loaded_artifact = await artifact_service.load_artifact(
-    app_name="my_app",
-    user_id="user123",
-    session_id="session456",
-    filename="greeting.txt"
-)
-
-# Save user-scoped artifact (persists across sessions)
-user_artifact = adk_types.Part.from_bytes(data=b"User data", mime_type="text/plain")
-await artifact_service.save_artifact(
-    app_name="my_app", 
-    user_id="user123",
-    session_id="session456",
-    filename="user:profile.json",  # user: prefix for user-scoped storage
-    artifact=user_artifact
-)
-
-# List all artifacts (includes both session and user-scoped)
-artifact_keys = await artifact_service.list_artifact_keys(
-    app_name="my_app",
-    user_id="user123", 
-    session_id="session456"
-)
-
-# Delete an artifact
-await artifact_service.delete_artifact(
-    app_name="my_app",
-    user_id="user123",
-    session_id="session456",
-    filename="greeting.txt"
-)
-```
-
-# content_hash: 8edcfe37e688e203ddb9d14f62b8e5f8dcb6129fc3c08816eea26de02ff6eb69

solace_agent_mesh/agent/adk/models/models_llm.txt

@@ -1,189 +0,0 @@
-# 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