solace-agent-mesh 1.7.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/agent/protocol/protocol_llm.txt

@@ -1,81 +0,0 @@
-# DEVELOPER GUIDE: protocol
-
-## Quick Summary
-The `protocol` directory implements the core logic for Agent-to-Agent (A2A) communication. It handles receiving and processing requests, responses, and discovery messages (Agent Cards) over the Solace event mesh. It acts as the bridge between the A2A protocol and the underlying Google ADK execution environment.
-
-## Files Overview
-- `__init__.py` - Empty package initialization file
-- `event_handlers.py` - Contains the primary logic for handling all A2A protocol events, including routing incoming messages, managing task execution, and handling agent discovery
-
-## Developer API Reference
-
-### __init__.py
-**Purpose:** Standard Python package initialization file
-**Import:** `from solace_agent_mesh.agent.protocol import *`
-
-This is an empty package initialization file and has no public interfaces.
-
-### event_handlers.py
-**Purpose:** Central hub for processing all events related to the A2A protocol. Routes events to appropriate handlers and manages task lifecycle.
-**Import:** `from solace_agent_mesh.agent.protocol.event_handlers import process_event, handle_a2a_request, handle_agent_card_message, handle_a2a_response, publish_agent_card, handle_sam_event, cleanup_agent_session`
-
-**Functions:**
-- `process_event(component, event: Event) -> None` - Main event router that processes incoming events and delegates to specific handlers based on event type and topic
-- `handle_a2a_request(component, message: SolaceMessage) -> None` - Handles incoming A2A request messages, starts ADK runner for SendTask requests, and processes CancelTask requests
-- `handle_agent_card_message(component, message: SolaceMessage) -> None` - Processes incoming Agent Card discovery messages and updates peer agent registry
-- `handle_a2a_response(component, message: SolaceMessage) -> None` - Handles responses and status updates from peer agents, manages parallel task completion
-- `publish_agent_card(component) -> None` - Publishes the agent's capabilities and information to the discovery topic
-- `handle_sam_event(component, message: SolaceMessage, topic: str) -> None` - Handles incoming SAM system events like session deletion
-- `cleanup_agent_session(component, session_id: str, user_id: str) -> None` - Cleans up agent-side session data when sessions are deleted
-
-**Internal Helper Functions:**
-- `_register_peer_artifacts_in_parent_context(parent_task_context: "TaskExecutionContext", peer_task_object: Task, log_identifier: str) -> None` - Registers artifacts produced by peer agents in the parent task context
-- `_publish_peer_tool_result_notification(component: "SamAgentComponent", correlation_data: Dict[str, Any], payload_to_queue: Any, log_identifier: str) -> None` - Publishes a ToolResultData status update for a completed peer tool call
-
-**Usage Examples:**
-```python
-# Main event processing (typically called by the SAC framework)
-from solace_agent_mesh.agent.protocol.event_handlers import process_event
-from solace_ai_connector.common.event import Event, EventType
-
-# Process an incoming event
-await process_event(component, event)
-
-# Publish agent discovery card
-from solace_agent_mesh.agent.protocol.event_handlers import publish_agent_card
-
-publish_agent_card(component)
-
-# Handle specific message types (usually called internally by process_event)
-from solace_agent_mesh.agent.protocol.event_handlers import handle_a2a_request
-
-await handle_a2a_request(component, solace_message)
-
-# Handle SAM system events
-from solace_agent_mesh.agent.protocol.event_handlers import handle_sam_event
-
-handle_sam_event(component, message, topic)
-
-# Clean up session data
-from solace_agent_mesh.agent.protocol.event_handlers import cleanup_agent_session
-
-await cleanup_agent_session(component, "session_123", "user_456")
-```
-
-**Key Event Flow:**
-1. `process_event()` receives all events and routes based on type (MESSAGE, TIMER, CACHE_EXPIRY)
-2. For MESSAGE events, routes to specific handlers based on topic patterns:
-   - Agent request topics → `handle_a2a_request()`
-   - Discovery topics → `handle_agent_card_message()`
-   - Response/status topics → `handle_a2a_response()`
-   - SAM events topics → `handle_sam_event()`
-3. For TIMER events, handles periodic agent card publishing
-4. For CACHE_EXPIRY events, delegates to component's cache handling
-
-**Dependencies:**
-- Requires `SamAgentComponent` instance with proper configuration
-- Uses A2A protocol types from `a2a.types`
-- Integrates with Google ADK for task execution
-- Manages task contexts through `TaskExecutionContext`
-
-# content_hash: 02e6f51922fe92594201d9e7a07ae8469cad977a13297c53db5a75534ca1e9f7

solace_agent_mesh/agent/protocol/protocol_llm_detail.txt

@@ -1,92 +0,0 @@
-# LLM Summary Detail File
-
-This file is a concatenation of all individual *llm.txt files found in the 'protocol' directory tree. Each section below corresponds to a specific directory's summary file.
-
-================================================================================
-
-## Section 1: solace_agent_mesh/agent/protocol/protocol_llm.txt
-
-**Source file:** `solace_agent_mesh/agent/protocol/protocol_llm.txt`
-
-# DEVELOPER GUIDE: protocol
-
-## Quick Summary
-The `protocol` directory implements the core logic for Agent-to-Agent (A2A) communication. It handles receiving and processing requests, responses, and discovery messages (Agent Cards) over the Solace event mesh. It acts as the bridge between the A2A protocol and the underlying Google ADK execution environment.
-
-## Files Overview
-- `__init__.py` - Empty package initialization file
-- `event_handlers.py` - Contains the primary logic for handling all A2A protocol events, including routing incoming messages, managing task execution, and handling agent discovery
-
-## Developer API Reference
-
-### __init__.py
-**Purpose:** Standard Python package initialization file
-**Import:** `from solace_agent_mesh.agent.protocol import *`
-
-This is an empty package initialization file and has no public interfaces.
-
-### event_handlers.py
-**Purpose:** Central hub for processing all events related to the A2A protocol. Routes events to appropriate handlers and manages task lifecycle.
-**Import:** `from solace_agent_mesh.agent.protocol.event_handlers import process_event, handle_a2a_request, handle_agent_card_message, handle_a2a_response, publish_agent_card, handle_sam_event, cleanup_agent_session`
-
-**Functions:**
-- `process_event(component, event: Event) -> None` - Main event router that processes incoming events and delegates to specific handlers based on event type and topic
-- `handle_a2a_request(component, message: SolaceMessage) -> None` - Handles incoming A2A request messages, starts ADK runner for SendTask requests, and processes CancelTask requests
-- `handle_agent_card_message(component, message: SolaceMessage) -> None` - Processes incoming Agent Card discovery messages and updates peer agent registry
-- `handle_a2a_response(component, message: SolaceMessage) -> None` - Handles responses and status updates from peer agents, manages parallel task completion
-- `publish_agent_card(component) -> None` - Publishes the agent's capabilities and information to the discovery topic
-- `handle_sam_event(component, message: SolaceMessage, topic: str) -> None` - Handles incoming SAM system events like session deletion
-- `cleanup_agent_session(component, session_id: str, user_id: str) -> None` - Cleans up agent-side session data when sessions are deleted
-
-**Internal Helper Functions:**
-- `_register_peer_artifacts_in_parent_context(parent_task_context: "TaskExecutionContext", peer_task_object: Task, log_identifier: str) -> None` - Registers artifacts produced by peer agents in the parent task context
-- `_publish_peer_tool_result_notification(component: "SamAgentComponent", correlation_data: Dict[str, Any], payload_to_queue: Any, log_identifier: str) -> None` - Publishes a ToolResultData status update for a completed peer tool call
-
-**Usage Examples:**
-```python
-# Main event processing (typically called by the SAC framework)
-from solace_agent_mesh.agent.protocol.event_handlers import process_event
-from solace_ai_connector.common.event import Event, EventType
-
-# Process an incoming event
-await process_event(component, event)
-
-# Publish agent discovery card
-from solace_agent_mesh.agent.protocol.event_handlers import publish_agent_card
-
-publish_agent_card(component)
-
-# Handle specific message types (usually called internally by process_event)
-from solace_agent_mesh.agent.protocol.event_handlers import handle_a2a_request
-
-await handle_a2a_request(component, solace_message)
-
-# Handle SAM system events
-from solace_agent_mesh.agent.protocol.event_handlers import handle_sam_event
-
-handle_sam_event(component, message, topic)
-
-# Clean up session data
-from solace_agent_mesh.agent.protocol.event_handlers import cleanup_agent_session
-
-await cleanup_agent_session(component, "session_123", "user_456")
-```
-
-**Key Event Flow:**
-1. `process_event()` receives all events and routes based on type (MESSAGE, TIMER, CACHE_EXPIRY)
-2. For MESSAGE events, routes to specific handlers based on topic patterns:
-   - Agent request topics → `handle_a2a_request()`
-   - Discovery topics → `handle_agent_card_message()`
-   - Response/status topics → `handle_a2a_response()`
-   - SAM events topics → `handle_sam_event()`
-3. For TIMER events, handles periodic agent card publishing
-4. For CACHE_EXPIRY events, delegates to component's cache handling
-
-**Dependencies:**
-- Requires `SamAgentComponent` instance with proper configuration
-- Uses A2A protocol types from `a2a.types`
-- Integrates with Google ADK for task execution
-- Manages task contexts through `TaskExecutionContext`
-
-================================================================================
-

solace_agent_mesh/agent/proxies/a2a/a2a_llm.txt

@@ -1,190 +0,0 @@
-# DEVELOPER GUIDE: a2a
-
-## Quick Summary
-The `a2a` directory provides a concrete implementation for proxying standard A2A-over-HTTPS agents. It enables the Solace Agent Mesh to communicate with downstream agents that implement the A2A (Agent-to-Agent) protocol over HTTP/HTTPS, handling authentication, request forwarding, and response processing.
-
-## Files Overview
-- `__init__.py` - Package initialization for A2A-over-HTTPS proxy implementation
-- `app.py` - Main application class that validates A2A-specific configuration
-- `component.py` - Core proxy component that handles A2A protocol communication and request forwarding
-- `config.py` - Pydantic configuration models for A2A proxy settings and authentication
-- `oauth_token_cache.py` - OAuth 2.0 token caching system with automatic expiration
-
-## Developer API Reference
-
-### app.py
-**Purpose:** Provides the main application class for A2A proxy with configuration validation
-**Import:** `from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp`
-
-**Classes:**
-- `A2AProxyApp(app_info: Dict[str, Any], **kwargs)` - Main A2A proxy application class
-  - Inherits from `BaseProxyApp` and adds A2A-specific configuration validation
-  - Validates authentication settings, URLs, and other A2A-specific parameters
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.proxies.a2a.app import A2AProxyApp
-
-# Create A2A proxy app with configuration
-app_info = {
-    "app_config": {
-        "proxied_agents": [
-            {
-                "name": "my-agent",
-                "url": "https://agent.example.com",
-                "authentication": {
-                    "type": "oauth2_client_credentials",
-                    "token_url": "https://auth.example.com/token",
-                    "client_id": "my-client-id",
-                    "client_secret": "my-secret"
-                }
-            }
-        ]
-    }
-}
-
-app = A2AProxyApp(app_info)
-```
-
-### component.py
-**Purpose:** Core component that handles A2A protocol communication, authentication, and request forwarding
-**Import:** `from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent`
-
-**Classes:**
-- `A2AProxyComponent(**kwargs: Any)` - Main proxy component for A2A-over-HTTPS agents
-  - `clear_client_cache() -> None` - Clears all cached A2A clients and OAuth tokens
-  - `cleanup() -> None` - Cleans up resources on component shutdown
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.proxies.a2a.component import A2AProxyComponent
-
-# Create component (typically done by the framework)
-component = A2AProxyComponent(
-    proxied_agents_config=[
-        {
-            "name": "my-agent",
-            "url": "https://agent.example.com",
-            "authentication": {
-                "type": "static_bearer",
-                "token": "my-bearer-token"
-            }
-        }
-    ]
-)
-
-# Clear cache if needed (useful for testing)
-component.clear_client_cache()
-
-# Cleanup when shutting down
-component.cleanup()
-```
-
-### config.py
-**Purpose:** Pydantic configuration models for A2A proxy settings and authentication validation
-**Import:** `from solace_agent_mesh.agent.proxies.a2a.config import A2AProxyAppConfig, AuthenticationConfig, A2AProxiedAgentConfig`
-
-**Classes:**
-- `AuthenticationConfig()` - Authentication configuration for downstream A2A agents
-  - `type: Optional[Literal["static_bearer", "static_apikey", "oauth2_client_credentials"]]` - Authentication type
-  - `token: Optional[str]` - Authentication token (for static types)
-  - `token_url: Optional[str]` - OAuth 2.0 token endpoint URL
-  - `client_id: Optional[str]` - OAuth 2.0 client identifier
-  - `client_secret: Optional[str]` - OAuth 2.0 client secret
-  - `scope: Optional[str]` - OAuth 2.0 scope string
-  - `token_cache_duration_seconds: int` - Token cache duration (default: 3300)
-
-- `A2AProxiedAgentConfig()` - Configuration for a single A2A agent
-  - `url: str` - Base URL of the downstream A2A agent
-  - `authentication: Optional[AuthenticationConfig]` - Authentication details
-
-- `A2AProxyAppConfig()` - Complete configuration for A2A proxy application
-  - `proxied_agents: List[A2AProxiedAgentConfig]` - List of agents to proxy
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.proxies.a2a.config import (
-    A2AProxyAppConfig, 
-    A2AProxiedAgentConfig, 
-    AuthenticationConfig
-)
-
-# OAuth 2.0 authentication
-oauth_auth = AuthenticationConfig(
-    type="oauth2_client_credentials",
-    token_url="https://auth.example.com/token",
-    client_id="my-client-id",
-    client_secret="my-secret",
-    scope="agent:read agent:write",
-    token_cache_duration_seconds=3300
-)
-
-# Static bearer token authentication
-bearer_auth = AuthenticationConfig(
-    type="static_bearer",
-    token="my-bearer-token"
-)
-
-# Agent configuration
-agent_config = A2AProxiedAgentConfig(
-    name="my-agent",
-    url="https://agent.example.com",
-    authentication=oauth_auth
-)
-
-# Complete app configuration
-app_config = A2AProxyAppConfig(
-    proxied_agents=[agent_config]
-)
-
-# Validate configuration
-validated_config = A2AProxyAppConfig.model_validate({
-    "proxied_agents": [
-        {
-            "name": "test-agent",
-            "url": "https://agent.example.com",
-            "authentication": {
-                "type": "static_bearer",
-                "token": "abc123"
-            }
-        }
-    ]
-})
-```
-
-### oauth_token_cache.py
-**Purpose:** Thread-safe OAuth 2.0 token caching with automatic expiration
-**Import:** `from solace_agent_mesh.agent.proxies.a2a.oauth_token_cache import OAuth2TokenCache, CachedToken`
-
-**Classes:**
-- `CachedToken(access_token: str, expires_at: float)` - Represents a cached token with expiration
-  - `access_token: str` - The OAuth 2.0 access token
-  - `expires_at: float` - Unix timestamp when token expires
-
-- `OAuth2TokenCache()` - Thread-safe in-memory cache for OAuth tokens
-  - `get(agent_name: str) -> Optional[str]` - Retrieves cached token if valid
-  - `set(agent_name: str, access_token: str, cache_duration_seconds: int) -> None` - Caches token with expiration
-  - `invalidate(agent_name: str) -> None` - Removes token from cache
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.proxies.a2a.oauth_token_cache import OAuth2TokenCache
-
-# Create token cache
-cache = OAuth2TokenCache()
-
-# Cache a token for 1 hour
-await cache.set("my-agent", "access_token_123", 3600)
-
-# Retrieve cached token
-token = await cache.get("my-agent")
-if token:
-    print(f"Using cached token: {token}")
-else:
-    print("No valid cached token found")
-
-# Invalidate cached token
-await cache.invalidate("my-agent")
-```
-
-# content_hash: 7bb671773b0ece239704f18e12a92ac5dc3f97dd0ebb154ac56f53e0d277a1b7

solace_agent_mesh/agent/proxies/base/base_llm.txt

@@ -1,148 +0,0 @@
-# DEVELOPER GUIDE: base
-
-## Quick Summary
-The `base` directory contains protocol-agnostic abstract base classes for implementing proxy applications in the Solace Agent Mesh. These classes handle common functionality like A2A message routing, agent discovery, task lifecycle management, and artifact resolution, allowing concrete proxy implementations to focus on protocol-specific details.
-
-## Files Overview
-- `__init__.py` - Package initialization for base proxy classes
-- `app.py` - Abstract base class for proxy applications with configuration validation and component setup
-- `component.py` - Abstract base class for proxy components handling Solace interaction and task management
-- `config.py` - Pydantic configuration models for proxy applications
-- `proxy_task_context.py` - Runtime state container for individual proxied agent tasks
-
-## Developer API Reference
-
-### __init__.py
-**Purpose:** Package initialization file for base proxy classes
-**Import:** `from solace_agent_mesh.agent.proxies.base import *`
-
-This file contains only package documentation and no public API.
-
-### app.py
-**Purpose:** Abstract base class for proxy applications that handles configuration validation and automatic component setup
-**Import:** `from solace_agent_mesh.agent.proxies.base.app import BaseProxyApp`
-
-**Classes:**
-- `BaseProxyApp(app_info: Dict[str, Any], **kwargs)` - Abstract base for proxy apps that automatically configures subscriptions and components
-  - `_get_component_class() -> Type[BaseProxyComponent]` - Abstract method to return the specific proxy component class
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.proxies.base.app import BaseProxyApp
-from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent
-
-class MyProxyApp(BaseProxyApp):
-    def _get_component_class(self):
-        return MyProxyComponent
-
-# App will automatically:
-# - Validate configuration against BaseProxyAppConfig
-# - Generate Solace subscriptions for all proxied agents
-# - Create component instance with proper broker settings
-```
-
-### component.py
-**Purpose:** Abstract base class for proxy components that handles Solace interaction, discovery, and task lifecycle
-**Import:** `from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent`
-
-**Classes:**
-- `BaseProxyComponent(**kwargs: Any)` - Abstract base for proxy components with async event processing
-  - `process_event(event: Event) -> None` - Processes incoming Solace events
-  - `invoke(message: SolaceMessage, data: dict) -> dict` - Placeholder invoke method (not used)
-  - `run() -> None` - Starts component operations and discovery timers
-  - `cleanup() -> None` - Cleans up resources on shutdown
-  - `clear_client_cache() -> None` - Clears cached clients (override in subclasses)
-  - `_fetch_agent_card(agent_config: dict) -> Optional[AgentCard]` - Abstract method to fetch agent cards
-  - `_forward_request(task_context: ProxyTaskContext, request: A2ARequest, agent_name: str) -> None` - Abstract method to forward requests
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.proxies.base.component import BaseProxyComponent
-from a2a.types import AgentCard, A2ARequest
-
-class MyProxyComponent(BaseProxyComponent):
-    async def _fetch_agent_card(self, agent_config: dict) -> Optional[AgentCard]:
-        # Implement protocol-specific agent discovery
-        url = agent_config.get("url")
-        # ... fetch and return AgentCard
-        
-    async def _forward_request(self, task_context, request: A2ARequest, agent_name: str):
-        # Implement protocol-specific request forwarding
-        # ... forward request to downstream agent
-        # ... handle responses and publish back to Solace
-```
-
-### config.py
-**Purpose:** Pydantic configuration models for proxy applications
-**Import:** `from solace_agent_mesh.agent.proxies.base.config import BaseProxyAppConfig, ProxiedAgentConfig, ArtifactServiceConfig`
-
-**Classes:**
-- `ArtifactServiceConfig()` - Configuration for artifact service
-  - `type: str` - Service type ('memory', 'gcs', 'filesystem')
-  - `base_path: Optional[str]` - Base directory for filesystem type
-  - `bucket_name: Optional[str]` - GCS bucket name
-  - `artifact_scope: Literal["namespace", "app", "custom"]` - Scope for artifacts
-  - `artifact_scope_value: Optional[str]` - Custom scope identifier
-
-- `ProxiedAgentConfig()` - Configuration for individual proxied agents
-  - `name: str` - Agent name on Solace mesh
-  - `request_timeout_seconds: Optional[int]` - Timeout override for this agent
-
-- `BaseProxyAppConfig()` - Base configuration for proxy applications
-  - `namespace: str` - Topic prefix for A2A communication
-  - `proxied_agents: List[ProxiedAgentConfig]` - List of agents to proxy
-  - `artifact_service: ArtifactServiceConfig` - Artifact service configuration
-  - `discovery_interval_seconds: int` - Agent discovery interval (default: 60)
-  - `default_request_timeout_seconds: int` - Default request timeout (default: 300)
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.proxies.base.config import BaseProxyAppConfig
-
-# Configuration validation
-config_dict = {
-    "namespace": "myorg/dev",
-    "proxied_agents": [
-        {"name": "my-agent", "request_timeout_seconds": 120}
-    ],
-    "artifact_service": {"type": "memory"},
-    "discovery_interval_seconds": 30
-}
-
-config = BaseProxyAppConfig.model_validate(config_dict)
-```
-
-### proxy_task_context.py
-**Purpose:** Runtime state container for individual proxied agent tasks
-**Import:** `from solace_agent_mesh.agent.proxies.base.proxy_task_context import ProxyTaskContext`
-
-**Classes:**
-- `ProxyTaskContext(task_id: str, a2a_context: Dict[str, Any])` - Runtime state for a proxied task
-  - `task_id: str` - Unique identifier for the task
-  - `a2a_context: Dict[str, Any]` - A2A protocol context information
-
-**Usage Examples:**
-```python
-from solace_agent_mesh.agent.proxies.base.proxy_task_context import ProxyTaskContext
-
-# Create task context when handling new request
-a2a_context = {
-    "jsonrpc_request_id": "req-123",
-    "logical_task_id": "task-456", 
-    "session_id": "session-789",
-    "user_id": "user123",
-    "status_topic": "status/topic",
-    "reply_to_topic": "reply/topic",
-    "is_streaming": False
-}
-
-task_context = ProxyTaskContext(
-    task_id="task-456",
-    a2a_context=a2a_context
-)
-
-# Store in active tasks for lifecycle management
-self.active_tasks[task_context.task_id] = task_context
-```
-
-# content_hash: 40cb6427440b8b946d69d0d721d47ca5994dd19621e6e631544e8e39b7a96624