solace-agent-mesh 1.4.12__py3-none-any.whl → 1.5.1__py3-none-any.whl

solace_agent_mesh/common/a2a_spec/schemas/llm_invocation.json

@@ -12,6 +12,29 @@
         "request": {
             "type": "object",
             "description": "A sanitized representation of the LlmRequest object sent to the model."
+        },
+        "usage": {
+            "type": "object",
+            "description": "Token usage information for this LLM call.",
+            "properties": {
+                "input_tokens": {
+                    "type": "integer",
+                    "description": "Number of input/prompt tokens."
+                },
+                "output_tokens": {
+                    "type": "integer",
+                    "description": "Number of output/completion tokens."
+                },
+                "cached_input_tokens": {
+                    "type": "integer",
+                    "description": "Number of cached input tokens (optional)."
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Model identifier used for this call."
+                }
+            },
+            "required": ["input_tokens", "output_tokens", "model"]
         }
     },
     "required": ["type", "request"]

solace_agent_mesh/common/a2a_spec/schemas/schemas_llm.txt

@@ -6,9 +6,9 @@ This directory contains JSON Schema definitions for various agent-to-agent (A2A)
 ## 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
+- `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
+- `tool_result.json` - Schema for tool execution completion results with optional LLM usage
 - `schemas_llm.txt` - Previous developer guide (legacy documentation)
 
 ## Developer API Reference
@@ -16,6 +16,12 @@ This directory contains JSON Schema definitions for various agent-to-agent (A2A)
 ### 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
 {
@@ -48,6 +54,12 @@ 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
 {
@@ -84,19 +96,36 @@ 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.
+**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"
+  "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
@@ -107,13 +136,19 @@ from jsonschema import validate
 with open('solace_agent_mesh/common/a2a_spec/schemas/llm_invocation.json') as f:
     schema = json.load(f)
 
-# Valid data example
+# 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)
@@ -122,6 +157,12 @@ 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
 {
@@ -161,7 +202,13 @@ 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.
+**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
@@ -169,7 +216,13 @@ validate(instance=data, schema=schema)
   "type": "tool_result",
   "tool_name": "string",
   "result_data": "any",
-  "function_call_id": "string"
+  "function_call_id": "string",
+  "llm_usage": {
+    "input_tokens": "integer",
+    "output_tokens": "integer",
+    "cached_input_tokens": "integer",
+    "model": "string"
+  }
 }
 ```
 
@@ -178,6 +231,11 @@ validate(instance=data, schema=schema)
 - `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
@@ -188,16 +246,20 @@ from jsonschema import validate
 with open('solace_agent_mesh/common/a2a_spec/schemas/tool_result.json') as f:
     schema = json.load(f)
 
-# Valid data example
+# Valid data example with LLM usage
 data = {
     "type": "tool_result",
-    "tool_name": "file_reader",
+    "tool_name": "web_search",
     "result_data": {
-        "content": "File contents here...",
-        "size": 1024,
-        "encoding": "utf-8"
+        "results": ["Result 1", "Result 2"],
+        "count": 2
     },
-    "function_call_id": "call_abc123"
+    "function_call_id": "call_abc123",
+    "llm_usage": {
+        "input_tokens": 200,
+        "output_tokens": 100,
+        "model": "gpt-4"
+    }
 }
 validate(instance=data, schema=schema)
 ```
@@ -207,8 +269,9 @@ validate(instance=data, schema=schema)
 import json
 from jsonschema import validate
 from pathlib import Path
+from typing import Dict, Any
 
-def validate_a2a_signal(signal_data: dict, schema_name: str) -> bool:
+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")
     
@@ -222,6 +285,12 @@ def validate_a2a_signal(signal_data: dict, schema_name: str) -> bool:
         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",
@@ -230,6 +299,15 @@ progress_data = {
 
 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: 3e5a2f693dc3f4536f9c958168677fe2e3a0e18b3dc319891aceccb5ccfdda8a
+# content_hash: 8d0325636918fd8bdabc0ba61bed79ae2b2be06778893406197aebfb7c3e3a21

solace_agent_mesh/common/a2a_spec/schemas/tool_result.json

@@ -19,6 +19,29 @@
         "function_call_id": {
             "type": "string",
             "description": "The ID from the LLM's function call that this result corresponds to."
+        },
+        "llm_usage": {
+            "type": "object",
+            "description": "Token usage if this tool made LLM calls.",
+            "properties": {
+                "input_tokens": {
+                    "type": "integer",
+                    "description": "Total input tokens used by tool's LLM calls."
+                },
+                "output_tokens": {
+                    "type": "integer",
+                    "description": "Total output tokens used by tool's LLM calls."
+                },
+                "cached_input_tokens": {
+                    "type": "integer",
+                    "description": "Number of cached input tokens (optional)."
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Model identifier(s) used by the tool."
+                }
+            },
+            "required": ["input_tokens", "output_tokens", "model"]
         }
     },
     "required": ["type", "tool_name", "result_data", "function_call_id"]

solace_agent_mesh/common/common_llm.txt

@@ -31,6 +31,8 @@ Together, these components form a cohesive ecosystem, enabling developers to eit
   - `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.
@@ -77,6 +79,8 @@ Together, these components form a cohesive ecosystem, enabling developers to eit
 
 **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.
@@ -91,6 +95,7 @@ Together, these components form a cohesive ecosystem, enabling developers to eit
 - **`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.
@@ -104,6 +109,7 @@ Together, these components form a cohesive ecosystem, enabling developers to eit
   - `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.
@@ -177,6 +183,22 @@ from solace_agent_mesh.common.client import A2AClient, A2ACardResolver
 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`
@@ -224,43 +246,6 @@ from solace_agent_mesh.common.types import (
     TaskState,
     AgentCard
 )
-from solace_agent_mesh.common.agent_registry import AgentRegistry
-
-# Create a message
-message = Message(
-    role="user",
-    parts=[TextPart(text="Hello, can you help me analyze this document?")]
-)
-
-# Translate to ADK format for processing
-adk_content = translate_a2a_to_adk_content(message, "[Example]")
-print(f"ADK Content: {adk_content}")
-
-# Generate topic names for communication
-namespace = "my-company/ai-agents"
-agent_name = "document-analyzer"
-gateway_id = "gateway-001"
-task_id = str(uuid.uuid4())
-
-request_topic = get_agent_request_topic(namespace, agent_name)
-status_topic = get_gateway_status_topic(namespace, gateway_id, task_id)
-
-print(f"Request Topic: {request_topic}")
-print(f"Status Topic: {status_topic}")
-
-# Use agent registry to track discovered agents
-registry = AgentRegistry()
-agent_card = AgentCard(
-    name="document-analyzer",
-    display_name="Document Analyzer",
-    description="Analyzes and extracts information from documents",
-    url="https://agents.company.com/document-analyzer",
-    version="1.0.0",
-    capabilities={"streaming": True, "pushNotifications": False},
-    skills=[],
-    peer_agents={}
-)
-
-registry.add_or_update_agent(agent_
+from solace_
 
-# content_hash: 1e02a8692a4f781b66ebf5b56ec8adedbbcfec3a02cc8f1cd02a22b95e057b14
+# content_hash: 4cbf98260b5f5bef314fae44cf680520f4581948d2bfd8b08e7c6455bbcac1bc