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

solace_agent_mesh/common/a2a_spec/schemas/schemas_llm.txt

@@ -1,313 +0,0 @@
-# DEVELOPER GUIDE: schemas
-
-## Quick Summary
-This directory contains JSON Schema definitions for various agent-to-agent (A2A) communication signals in the Solace Agent Mesh. These schemas define the structure and validation rules for different types of progress updates, tool invocations, and LLM interactions that agents can send to each other.
-
-## Files Overview
-- `agent_progress_update.json` - Schema for general agent progress status messages
-- `artifact_creation_progress.json` - Schema for tracking file/artifact creation progress with chunked data
-- `llm_invocation.json` - Schema for LLM model invocation signals with usage tracking
-- `tool_invocation_start.json` - Schema for tool execution start notifications
-- `tool_result.json` - Schema for tool execution completion results with optional LLM usage
-- `schemas_llm.txt` - Previous developer guide (legacy documentation)
-
-## Developer API Reference
-
-### agent_progress_update.json
-**Purpose:** Defines the schema for agent progress update signals that communicate human-readable status messages between agents.
-
-**Import:** Load as JSON schema for validation
-```python
-import json
-from jsonschema import validate
-```
-
-**Schema Structure:**
-```json
-{
-  "type": "agent_progress_update",
-  "status_text": "string"
-}
-```
-
-**Properties:**
-- `type: "agent_progress_update"` - Constant identifier for this signal type (required)
-- `status_text: string` - Human-readable progress message (required)
-
-**Usage Examples:**
-```python
-import json
-from jsonschema import validate
-
-# Load and use schema
-with open('solace_agent_mesh/common/a2a_spec/schemas/agent_progress_update.json') as f:
-    schema = json.load(f)
-
-# Valid data example
-data = {
-    "type": "agent_progress_update",
-    "status_text": "Analyzing the report..."
-}
-validate(instance=data, schema=schema)
-```
-
-### artifact_creation_progress.json
-**Purpose:** Defines the schema for tracking progress during file or artifact creation operations with chunked data transfer.
-
-**Import:** Load as JSON schema for validation
-```python
-import json
-from jsonschema import validate
-```
-
-**Schema Structure:**
-```json
-{
-  "type": "artifact_creation_progress",
-  "filename": "string",
-  "bytes_saved": "integer",
-  "artifact_chunk": "string"
-}
-```
-
-**Properties:**
-- `type: "artifact_creation_progress"` - Constant identifier for this signal type (required)
-- `filename: string` - Name of the artifact being created (required)
-- `bytes_saved: integer` - Number of bytes saved so far (required)
-- `artifact_chunk: string` - The chunk of artifact data that was saved in this update (required)
-
-**Usage Examples:**
-```python
-import json
-from jsonschema import validate
-
-# Load and use schema
-with open('solace_agent_mesh/common/a2a_spec/schemas/artifact_creation_progress.json') as f:
-    schema = json.load(f)
-
-# Valid data example
-data = {
-    "type": "artifact_creation_progress",
-    "filename": "report.pdf",
-    "bytes_saved": 1024,
-    "artifact_chunk": "JVBERi0xLjQKJcOkw7zDtsO..."
-}
-validate(instance=data, schema=schema)
-```
-
-### llm_invocation.json
-**Purpose:** Defines the schema for LLM invocation signals that communicate when an agent is calling a language model, including token usage tracking.
-
-**Import:** Load as JSON schema for validation
-```python
-import json
-from jsonschema import validate
-```
-
-**Schema Structure:**
-```json
-{
-  "type": "llm_invocation",
-  "request": "object",
-  "usage": {
-    "input_tokens": "integer",
-    "output_tokens": "integer",
-    "cached_input_tokens": "integer",
-    "model": "string"
-  }
-}
-```
-
-**Properties:**
-- `type: "llm_invocation"` - Constant identifier for this signal type (required)
-- `request: object` - Sanitized representation of the LlmRequest object sent to the model (required)
-- `usage: object` - Token usage information for this LLM call (optional)
-  - `input_tokens: integer` - Number of input/prompt tokens (required in usage)
-  - `output_tokens: integer` - Number of output/completion tokens (required in usage)
-  - `cached_input_tokens: integer` - Number of cached input tokens (optional)
-  - `model: string` - Model identifier used for this call (required in usage)
-
-**Usage Examples:**
-```python
-import json
-from jsonschema import validate
-
-# Load and use schema
-with open('solace_agent_mesh/common/a2a_spec/schemas/llm_invocation.json') as f:
-    schema = json.load(f)
-
-# Valid data example with usage tracking
-data = {
-    "type": "llm_invocation",
-    "request": {
-        "model": "gpt-4",
-        "messages": [{"role": "user", "content": "Analyze this data"}],
-        "temperature": 0.7
-    },
-    "usage": {
-        "input_tokens": 150,
-        "output_tokens": 75,
-        "cached_input_tokens": 50,
-        "model": "gpt-4"
-    }
-}
-validate(instance=data, schema=schema)
-```
-
-### tool_invocation_start.json
-**Purpose:** Defines the schema for tool invocation start signals that notify when an agent begins executing a tool.
-
-**Import:** Load as JSON schema for validation
-```python
-import json
-from jsonschema import validate
-```
-
-**Schema Structure:**
-```json
-{
-  "type": "tool_invocation_start",
-  "tool_name": "string",
-  "tool_args": "object",
-  "function_call_id": "string"
-}
-```
-
-**Properties:**
-- `type: "tool_invocation_start"` - Constant identifier for this signal type (required)
-- `tool_name: string` - Name of the tool being called (required)
-- `tool_args: object` - Arguments passed to the tool (required)
-- `function_call_id: string` - ID from the LLM's function call (required)
-
-**Usage Examples:**
-```python
-import json
-from jsonschema import validate
-
-# Load and use schema
-with open('solace_agent_mesh/common/a2a_spec/schemas/tool_invocation_start.json') as f:
-    schema = json.load(f)
-
-# Valid data example
-data = {
-    "type": "tool_invocation_start",
-    "tool_name": "file_reader",
-    "tool_args": {
-        "filepath": "/path/to/file.txt",
-        "encoding": "utf-8"
-    },
-    "function_call_id": "call_abc123"
-}
-validate(instance=data, schema=schema)
-```
-
-### tool_result.json
-**Purpose:** Defines the schema for tool execution result signals that communicate the completion and results of tool invocations, with optional LLM usage tracking.
-
-**Import:** Load as JSON schema for validation
-```python
-import json
-from jsonschema import validate
-```
-
-**Schema Structure:**
-```json
-{
-  "type": "tool_result",
-  "tool_name": "string",
-  "result_data": "any",
-  "function_call_id": "string",
-  "llm_usage": {
-    "input_tokens": "integer",
-    "output_tokens": "integer",
-    "cached_input_tokens": "integer",
-    "model": "string"
-  }
-}
-```
-
-**Properties:**
-- `type: "tool_result"` - Constant identifier for this signal type (required)
-- `tool_name: string` - Name of the tool that was called (required)
-- `result_data: any` - The data returned by the tool (required, can be any type)
-- `function_call_id: string` - ID from the LLM's function call that this result corresponds to (required)
-- `llm_usage: object` - Token usage if this tool made LLM calls (optional)
-  - `input_tokens: integer` - Total input tokens used by tool's LLM calls (required in llm_usage)
-  - `output_tokens: integer` - Total output tokens used by tool's LLM calls (required in llm_usage)
-  - `cached_input_tokens: integer` - Number of cached input tokens (optional)
-  - `model: string` - Model identifier(s) used by the tool (required in llm_usage)
-
-**Usage Examples:**
-```python
-import json
-from jsonschema import validate
-
-# Load and use schema
-with open('solace_agent_mesh/common/a2a_spec/schemas/tool_result.json') as f:
-    schema = json.load(f)
-
-# Valid data example with LLM usage
-data = {
-    "type": "tool_result",
-    "tool_name": "web_search",
-    "result_data": {
-        "results": ["Result 1", "Result 2"],
-        "count": 2
-    },
-    "function_call_id": "call_abc123",
-    "llm_usage": {
-        "input_tokens": 200,
-        "output_tokens": 100,
-        "model": "gpt-4"
-    }
-}
-validate(instance=data, schema=schema)
-```
-
-**Common Usage Pattern:**
-```python
-import json
-from jsonschema import validate
-from pathlib import Path
-from typing import Dict, Any
-
-def validate_a2a_signal(signal_data: Dict[str, Any], schema_name: str) -> bool:
-    """Validate A2A signal data against its schema."""
-    schema_path = Path(f"solace_agent_mesh/common/a2a_spec/schemas/{schema_name}.json")
-    
-    with open(schema_path) as f:
-        schema = json.load(f)
-    
-    try:
-        validate(instance=signal_data, schema=schema)
-        return True
-    except Exception as e:
-        print(f"Validation failed: {e}")
-        return False
-
-def load_schema(schema_name: str) -> Dict[str, Any]:
-    """Load a specific A2A signal schema."""
-    schema_path = Path(f"solace_agent_mesh/common/a2a_spec/schemas/{schema_name}.json")
-    with open(schema_path) as f:
-        return json.load(f)
-
-# Example usage
-progress_data = {
-    "type": "agent_progress_update",
-    "status_text": "Processing request..."
-}
-
-if validate_a2a_signal(progress_data, "agent_progress_update"):
-    print("Signal is valid!")
-
-# Load all schemas for batch validation
-schemas = {
-    "agent_progress": load_schema("agent_progress_update"),
-    "artifact_progress": load_schema("artifact_creation_progress"),
-    "llm_invocation": load_schema("llm_invocation"),
-    "tool_start": load_schema("tool_invocation_start"),
-    "tool_result": load_schema("tool_result")
-}
-```
-
-# content_hash: 8d0325636918fd8bdabc0ba61bed79ae2b2be06778893406197aebfb7c3e3a21

solace_agent_mesh/common/common_llm.txt

@@ -1,251 +0,0 @@
-# DEVELOPER GUIDE: common
-
-## Quick Summary
-The `common` directory provides the foundational infrastructure for Agent-to-Agent (A2A) communication within the Solace Agent Mesh. It establishes the core protocol, data types, and message translation logic that underpins all interactions between AI agents and gateways.
-
-The architecture is designed for clarity and extensibility. Core, low-level definitions are located in **direct files**:
-- `types.py` defines the canonical data structures (e.g., `Message`, `Task`, `AgentCard`).
-- `a2a_protocol.py` handles the construction of Solace topics and the translation between A2A and Google ADK message formats.
-- `agent_registry.py` provides a simple, thread-safe mechanism for discovering and tracking available agents.
-
-This foundation is then leveraged by specialized **subdirectories**, which provide higher-level, ready-to-use components:
-- `client/`: A complete client library for discovering and interacting with remote agents.
-- `server/`: A stand-alone server implementation for building A2A-compliant agents.
-- `middleware/`: A pluggable framework for customizing configuration and feature access.
-- `services/`: A factory-based system for integrating identity and other external data sources.
-- `utils/`: A collection of cross-cutting utilities for caching, logging, and dynamic content processing.
-
-Together, these components form a cohesive ecosystem, enabling developers to either build new agents from scratch using the `server` components or interact with existing agents using the `client` library, all while relying on the same underlying protocol and types.
-
-## Files and Subdirectories Overview
-- **Direct files:**
-  - `__init__.py`: Package initialization file.
-  - `a2a_protocol.py`: Handles A2A topic construction and translation between A2A and ADK message formats.
-  - `agent_registry.py`: A thread-safe registry for managing discovered agent cards.
-  - `constants.py`: Common constants used across the system.
-  - `data_parts.py`: Pydantic models for structured data payloads used in A2A DataPart objects.
-  - `exceptions.py`: Custom exceptions for Solace Agent Mesh.
-  - `types.py`: Contains all Pydantic models for A2A protocol messages, tasks, and data structures.
-- **Subdirectories:**
-  - `a2a/`: Comprehensive abstraction layer providing helper functions for creating, consuming, and translating A2A protocol objects.
-  - `a2a_spec/`: Complete JSON Schema specification for the A2A protocol.
-  - `client/`: Provides a high-level client for discovering and communicating with remote A2A agents.
-  - `middleware/`: A pluggable framework for configuration resolution and system extensibility.
-  - `sac/`: Base component framework for Solace Agent Mesh implementations in the Solace AI Connector.
-  - `sam_events/`: System-level event messaging for session lifecycle, agent health, and configuration changes.
-  - `server/`: A complete A2A server implementation with JSON-RPC support and task management.
-  - `services/`: Provides shared services like identity management using a factory pattern.
-  - `utils/`: Contains common utility functions and an embedded expression processing system.
-
-## Developer API Reference
-
-### Direct Files
-
-#### a2a_protocol.py
-**Purpose:** Provides the core functions for constructing Solace topics according to the A2A specification and for translating messages between the A2A format and the Google ADK format.
-**Import:** `from solace_agent_mesh.common.a2a_protocol import get_agent_request_topic, translate_a2a_to_adk_content`
-
-**Classes/Functions/Constants:**
-- **Constants**:
-  - `A2A_VERSION: str`: The current version of the A2A protocol (e.g., "v1").
-  - `A2A_BASE_PATH: str`: The base path used in all A2A topics (e.g., "a2a/v1").
-- **Topic Construction Functions**:
-  - `get_a2a_base_topic(namespace: str) -> str`: Returns the base topic prefix for all A2A communication.
-  - `get_discovery_topic(namespace: str) -> str`: Returns the topic for agent card discovery.
-  - `get_agent_request_topic(namespace: str, agent_name: str) -> str`: Returns the topic for sending requests to a specific agent.
-  - `get_gateway_status_topic(namespace: str, gateway_id: str, task_id: str) -> str`: Returns the topic for an agent to publish status updates to a gateway.
-  - `get_gateway_response_topic(namespace: str, gateway_id: str, task_id: str) -> str`: Returns the topic for an agent to publish final responses to a gateway.
-  - `get_client_response_topic(namespace: str, client_id: str) -> str`: Returns the topic for publishing final responses to a specific client.
-  - `get_client_status_topic(namespace: str, client_id: str, task_id: str) -> str`: Returns the topic for publishing status updates to a specific client.
-- **Message Translation Functions**:
-  - `translate_a2a_to_adk_content(a2a_message: A2AMessage, log_identifier: str) -> adk_types.Content`: Translates an A2A `Message` object into the Google ADK `Content` format.
-  - `format_adk_event_as_a2a(...) -> Tuple[Optional[JSONRPCResponse], ...]`: Translates an ADK `Event` into an A2A `JSONRPCResponse` containing a `TaskStatusUpdateEvent`.
-  - `format_and_route_adk_event(...) -> Tuple[Optional[Dict], Optional[str], ...]`: A higher-level wrapper that formats an ADK event and determines the correct Solace topic to publish it to.
-
-#### agent_registry.py
-**Purpose:** Provides a simple, thread-safe, in-memory store for discovered `AgentCard` objects. This is useful for components that need to keep track of available agents in the network.
-**Import:** `from solace_agent_mesh.common.agent_registry import AgentRegistry`
-
-**Classes/Functions/Constants:**
-- **`AgentRegistry`**: A thread-safe class for storing and managing agent cards.
-  - `add_or_update_agent(self, agent_card: AgentCard)`: Adds a new agent or updates an existing one.
-  - `get_agent(self, agent_name: str) -> Optional[AgentCard]`: Retrieves an agent card by its unique name.
-  - `get_agent_names(self) -> List[str]`: Returns a sorted list of all discovered agent names.
-  - `clear(self)`: Clears all agents from the registry.
-
-#### constants.py
-**Purpose:** Defines common constants used throughout the Solace Agent Mesh system.
-**Import:** `from solace_agent_mesh.common.constants import DEFAULT_COMMUNICATION_TIMEOUT`
-
-**Classes/Functions/Constants:**
-- `DEFAULT_COMMUNICATION_TIMEOUT: int`: Default timeout for communication operations (600 seconds / 10 minutes).
-- `TEXT_ARTIFACT_CONTEXT_MAX_LENGTH_CAPACITY: int`: Maximum number of characters that can be loaded from a text artifact (200,000).
-- `TEXT_ARTIFACT_CONTEXT_DEFAULT_LENGTH: int`: Default number of characters to load from a text artifact (100,000).
-
-#### data_parts.py
-**Purpose:** Defines Pydantic models for structured data payloads used in A2A DataPart objects, corresponding to JSON schemas for agent communication signals.
-**Import:** `from solace_agent_mesh.common.data_parts import ToolInvocationStartData, LlmInvocationData`
-
-**Classes/Functions/Constants:**
-- **`ToolInvocationStartData`**: Data model for tool invocation start signals.
-  - `type: Literal["tool_invocation_start"]`: The constant type identifier.
-  - `tool_name: str`: The name of the tool being called.
-  - `tool_args: Dict[str, Any]`: The arguments passed to the tool.
-  - `function_call_id: str`: The ID from the LLM's function call.
-- **`LlmInvocationData`**: Data model for LLM invocation signals.
-  - `type: Literal["llm_invocation"]`: The constant type identifier.
-  - `request: Dict[str, Any]`: A sanitized representation of the LlmRequest object.
-  - `usage: Optional[Dict[str, Any]]`: Token usage information for this LLM call.
-- **`AgentProgressUpdateData`**: Data model for agent progress update signals.
-  - `type: Literal["agent_progress_update"]`: The constant type identifier.
-  - `status_text: str`: A human-readable progress message.
-- **`ArtifactCreationProgressData`**: Data model for artifact creation progress signals.
-  - `type: Literal["artifact_creation_progress"]`: The constant type identifier.
-  - `filename: str`: The name of the artifact being created.
-  - `bytes_saved: int`: The number of bytes saved so far.
-  - `artifact_chunk: str`: The chunk of artifact data that was saved in this progress update.
-- **`ToolResultData`**: Data model for tool execution result signals.
-  - `type: Literal["tool_result"]`: The constant type identifier.
-  - `tool_name: str`: The name of the tool that was called.
-  - `result_data: Any`: The data returned by the tool.
-  - `function_call_id: str`: The ID from the LLM's function call.
-  - `llm_usage: Optional[Dict[str, Any]]`: Token usage if this tool made LLM calls.
-
-#### exceptions.py
-**Purpose:** Defines custom exceptions specific to the Solace Agent Mesh system.
-**Import:** `from solace_agent_mesh.common.exceptions import MessageSizeExceededError`
-
-**Classes/Functions/Constants:**
-- **`MessageSizeExceededError(Exception)`**: Raised when a message exceeds the maximum allowed size.
-  - `__init__(self, actual_size: int, max_size: int, message: str = None)`: Initialize with size information.
-  - `actual_size: int`: The actual size of the message in bytes.
-  - `max_size: int`: The maximum allowed size in bytes.
-
-#### types.py
-**Purpose:** Defines all the Pydantic data models that constitute the A2A protocol. These types ensure data consistency and provide validation across all components.
-**Import:** `from solace_agent_mesh.common.types import Message, Task, AgentCard, JSONRPCRequest, TaskState`
-
-**Classes/Functions/Constants:**
-- **Core Data Structures**:
-  - `Message`: Represents a message from a user or agent, containing a list of `Part` objects.
-  - `Part`: A discriminated union of `TextPart`, `FilePart`, and `DataPart`.
-  - `Task`: The central object representing a complete task, including its ID, status, history, and artifacts.
-  - `TaskStatus`: Describes the current state of a task (e.g., `WORKING`, `COMPLETED`).
-  - `TaskState(Enum)`: An enumeration of all possible task states.
-  - `AgentCard`: A comprehensive description of an agent's identity, capabilities, and skills.
-  - `Artifact`: Represents a task output, such as a generated file or structured data.
-- **JSON-RPC Structures**:
-  - `JSONRPCRequest`: The base model for all JSON-RPC requests.
-  - `JSONRPCResponse`: The base model for all JSON-RPC responses.
-  - `SendTaskRequest`, `GetTaskRequest`, etc.: Specific request types inheriting from `JSONRPCRequest`.
-- **Error Structures**:
-  - `JSONRPCError`: The base model for errors.
-  - `InternalError`, `TaskNotFoundError`, etc.: Specific error types inheriting from `JSONRPCError`.
-
-### Subdirectory APIs
-
-#### a2a/
-**Purpose:** Comprehensive abstraction layer providing helper functions for creating, consuming, and translating A2A protocol objects
-**Key Exports:** Helper functions for messages, tasks, artifacts, events, and protocol operations
-**Import Examples:**
-```python
-from solace_agent_mesh.common.a2a import create_agent_text_message, create_initial_task, translate_a2a_to_adk_content
-from solace_agent_mesh.common.a2a.message import create_text_part, get_text_from_message
-from solace_agent_mesh.common.a2a.protocol import get_agent_request_topic, create_send_message_request
-```
-
-#### a2a_spec/
-**Purpose:** Contains the complete Agent-to-Agent (A2A) communication specification including JSON schema definitions
-**Key Exports:** JSON Schema specifications for A2A protocol and agent communication signals
-**Import Examples:**
-```python
-import json
-from jsonschema import validate
-
-# Load main A2A schema
-with open('solace_agent_mesh/common/a2a_spec/a2a.json') as f:
-    a2a_schema = json.load(f)
-```
-
-#### client/
-**Purpose:** Provides a high-level, asynchronous client library for discovering and interacting with remote A2A agents.
-**Key Exports:** `A2AClient`, `A2ACardResolver`
-**Import Examples:**
-```python
-from solace_agent_mesh.common.client import A2AClient, A2ACardResolver
-```
-
-#### middleware/
-**Purpose:** A pluggable middleware framework for customizing system behavior, such as resolving user-specific configurations and feature flags.
-**Key Exports:** `ConfigResolver`, `MiddlewareRegistry`
-**Import Examples:**
-```python
-from solace_agent_mesh.common.middleware import ConfigResolver, MiddlewareRegistry
-```
-
-#### sac/
-**Purpose:** Base component framework for Solace Agent Mesh implementations in the Solace AI Connector with async operations management
-**Key Exports:** `SamComponentBase`
-**Import Examples:**
-```python
-from solace_agent_mesh.common.sac.sam_component_base import SamComponentBase
-```
-
-#### sam_events/
-**Purpose:** System-level event messaging for session lifecycle, agent health, and configuration changes separate from A2A task communication
-**Key Exports:** `SamEventService`, `SamEvent`, `SessionDeletedEvent`
-**Import Examples:**
-```python
-from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent
-```
-
-#### server/
-**Purpose:** A complete, stand-alone server for building A2A-compliant agents, handling HTTP requests, JSON-RPC, and task lifecycle management.
-**Key Exports:** `A2AServer`, `TaskManager`, `InMemoryTaskManager`
-**Import Examples:**
-```python
-from solace_agent_mesh.common.server import A2AServer, TaskManager, InMemoryTaskManager
-```
-
-#### services/
-**Purpose:** A factory-based system for integrating external data sources for identity, employee information, and more.
-**Key Exports:** `BaseIdentityService`, `create_identity_service`
-**Import Examples:**
-```python
-from solace_agent_mesh.common.services.identity_service import create_identity_service, BaseIdentityService
-```
-
-#### utils/
-**Purpose:** A collection of cross-cutting utilities for caching, logging, MIME type handling, and dynamic content processing.
-**Key Exports:** `InMemoryCache`, `is_text_based_mime_type`, `resolve_embeds_in_string`
-**Import Examples:**
-```python
-from solace_agent_mesh.common.utils.in_memory_cache import InMemoryCache
-from solace_agent_mesh.common.utils import is_text_based_mime_type
-from solace_agent_mesh.common.utils.embeds import resolve_embeds_recursively_in_string
-```
-
-## Complete Usage Guide
-
-### 1. Basic A2A Protocol Usage
-This example shows how to use the core protocol functions and types to build A2A communication.
-
-```python
-import uuid
-from datetime import datetime, timezone
-from solace_agent_mesh.common.a2a_protocol import (
-    get_agent_request_topic, 
-    get_gateway_status_topic,
-    translate_a2a_to_adk_content
-)
-from solace_agent_mesh.common.types import (
-    Message, 
-    TextPart, 
-    Task, 
-    TaskStatus, 
-    TaskState,
-    AgentCard
-)
-from solace_
-
-# content_hash: 4cbf98260b5f5bef314fae44cf680520f4581948d2bfd8b08e7c6455bbcac1bc