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

solace_agent_mesh/common/data_parts.py

@@ -4,7 +4,7 @@ These models correspond to the JSON schemas defined in a2a_spec/schemas/
 and are used for validating non-visible status update messages.
 """
 
-from typing import Any, Dict, Literal, Union
+from typing import Any, Dict, Literal, Optional, Union
 from pydantic import BaseModel, Field
 
 
@@ -39,6 +39,10 @@ class LlmInvocationData(BaseModel):
         ...,
         description="A sanitized representation of the LlmRequest object sent to the model.",
     )
+    usage: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Token usage information for this LLM call (input_tokens, output_tokens, cached_input_tokens, model)",
+    )
 
 
 class AgentProgressUpdateData(BaseModel):
@@ -88,6 +92,10 @@ class ToolResultData(BaseModel):
     function_call_id: str = Field(
         ..., description="The ID from the LLM's function call."
     )
+    llm_usage: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Token usage if this tool made LLM calls (input_tokens, output_tokens, cached_input_tokens, model)",
+    )
 
 
 SignalData = Union[

solace_agent_mesh/common/middleware/middleware_llm_detail.txt

@@ -0,0 +1,185 @@
+# LLM Summary Detail File
+
+This file is a concatenation of all individual *llm.txt files found in the 'middleware' directory tree. Each section below corresponds to a specific directory's summary file.
+
+================================================================================
+
+## Section 1: solace_agent_mesh/common/middleware/middleware_llm.txt
+
+**Source file:** `solace_agent_mesh/common/middleware/middleware_llm.txt`
+
+# DEVELOPER GUIDE: middleware
+
+## Quick Summary
+The `middleware` directory provides a pluggable framework for system components that can be extended or replaced at runtime. It offers a registry system to dynamically bind custom implementations for core functionalities like configuration resolution. The default implementations provide permissive behavior, making them suitable for development and testing environments where all features are enabled by default.
+
+## Files Overview
+- `__init__.py`: Exposes the main public classes of the middleware package for easy importing.
+- `config_resolver.py`: Defines the default, permissive configuration resolution middleware.
+- `registry.py`: Provides the `MiddlewareRegistry` for dynamically binding custom middleware implementations.
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** This file serves as the entry point to the `middleware` package, exporting the primary public interfaces for developers to use.
+
+**Import:** `from solace_agent_mesh.common.middleware import ConfigResolver, MiddlewareRegistry`
+
+**Usage Examples:**
+```python
+# Import the main classes directly from the middleware package
+from solace_agent_mesh.common.middleware import ConfigResolver, MiddlewareRegistry
+
+# Now you can use ConfigResolver and MiddlewareRegistry
+print(ConfigResolver)
+print(MiddlewareRegistry)
+```
+
+### config_resolver.py
+**Purpose:** This file provides a pluggable interface for resolving user-specific configuration and determining feature availability. The default `ConfigResolver` class is permissive, allowing all operations and enabling all features, which is ideal for development or simple deployments.
+
+**Import:** `from solace_agent_mesh.common.middleware import ConfigResolver`
+
+**Classes:**
+- `ConfigResolver()` - A class containing static methods to resolve user-specific configuration and determine feature availability. This default implementation is permissive.
+  - `resolve_user_config(user_identity: Any, gateway_context: Dict[str, Any], base_config: Dict[str, Any]) -> Dict[str, Any]` - (async) Resolves user-specific configuration. The default implementation returns the `base_config` unchanged.
+  - `is_feature_enabled(user_config: Dict[str, Any], feature_descriptor: Dict[str, Any], context: Dict[str, Any]) -> bool` - Checks if a feature is enabled for a user. The default implementation always returns `True`.
+  - `validate_operation_config(user_config: Dict[str, Any], operation_spec: Dict[str, Any], validation_context: Dict[str, Any]) -> Dict[str, Any]` - Validates if an operation is allowed for a user. The default implementation always returns a dictionary with `{'valid': True}`.
+  - `filter_available_options(user_config: Dict[str, Any], available_options: List[Dict[str, Any]], filter_context: Dict[str, Any]) -> List[Dict[str, Any]]` - Filters a list of options based on user permissions. The default implementation returns the original `available_options` list.
+
+**Usage Examples:**
+```python
+import asyncio
+from solace_agent_mesh.common.middleware import ConfigResolver
+
+async def main():
+    # Example user identity and base configuration
+    user_id = "test-user@example.com"
+    base_conf = {"api_key": "default_key", "allowed_models": ["gpt-3.5-turbo"]}
+
+    # 1. Resolve user configuration (default implementation returns base_conf)
+    user_config = await ConfigResolver.resolve_user_config(
+        user_identity=user_id,
+        gateway_context={"gateway_id": "gw-1"},
+        base_config=base_conf
+    )
+    print(f"Resolved User Config: {user_config}")
+
+    # 2. Check if a feature is enabled (default is always True)
+    feature_desc = {"feature_type": "ai_tool", "function_name": "code_interpreter"}
+    is_enabled = ConfigResolver.is_feature_enabled(
+        user_config=user_config,
+        feature_descriptor=feature_desc,
+        context={}
+    )
+    print(f"Is Feature Enabled: {is_enabled}")
+
+    # 3. Validate an operation (default is always valid)
+    op_spec = {"operation_type": "model_inference", "model": "gpt-4"}
+    validation = ConfigResolver.validate_operation_config(
+        user_config=user_config,
+        operation_spec=op_spec,
+        validation_context={}
+    )
+    print(f"Operation Validation: {validation}")
+
+    # 4. Filter available options (default returns all options)
+    all_models = [
+        {"name": "gpt-3.5-turbo", "provider": "openai"},
+        {"name": "gpt-4", "provider": "openai"},
+    ]
+    available_models = ConfigResolver.filter_available_options(
+        user_config=user_config,
+        available_options=all_models,
+        filter_context={"type": "language_model"}
+    )
+    print(f"Filtered Options: {available_models}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### registry.py
+**Purpose:** This file provides the `MiddlewareRegistry`, a static class that allows developers to dynamically bind, or "plug in," their own custom middleware implementations at runtime. This is the core of the pluggable system.
+
+**Import:** `from solace_agent_mesh.common.middleware import MiddlewareRegistry`
+
+**Classes:**
+- `MiddlewareRegistry()` - A registry for managing middleware implementations. All methods are class methods.
+  - `bind_config_resolver(resolver_class: Type)` - Binds a custom class that implements the `ConfigResolver` interface. This new class will be used for all subsequent configuration resolution calls.
+  - `get_config_resolver() -> Type` - Returns the currently bound `ConfigResolver` class. If no custom resolver has been bound, it returns the default `ConfigResolver`.
+  - `register_initialization_callback(callback: callable)` - Registers a function to be executed when `initialize_middleware()` is called. Useful for setting up custom middleware components at application startup.
+  - `initialize_middleware()` - Executes all registered initialization callbacks. This should be called once during application startup.
+  - `reset_bindings()` - Resets all bindings back to their defaults. This is primarily useful for testing environments.
+  - `get_registry_status() -> Dict[str, Any]` - Returns a dictionary containing the current status of the registry, such as which resolver is bound.
+
+**Usage Examples:**
+```python
+import asyncio
+from typing import Any, Dict, List
+from solace_agent_mesh.common.middleware import MiddlewareRegistry, ConfigResolver
+
+# 1. Define a custom ConfigResolver implementation
+class MyCustomConfigResolver:
+    """A custom resolver that only allows 'admin' users to use 'gpt-4'."""
+    @staticmethod
+    async def resolve_user_config(user_identity: Any, gateway_context: Dict[str, Any], base_config: Dict[str, Any]) -> Dict[str, Any]:
+        if user_identity == "admin":
+            return {"role": "admin", "allowed_models": ["gpt-4", "gpt-3.5-turbo"]}
+        return {"role": "user", "allowed_models": ["gpt-3.5-turbo"]}
+
+    @staticmethod
+    def validate_operation_config(user_config: Dict, operation_spec: Dict, validation_context: Dict) -> Dict:
+        model = operation_spec.get("model")
+        if model and model not in user_config.get("allowed_models", []):
+            return {"valid": False, "reason": f"Model '{model}' not allowed for this user."}
+        return {"valid": True}
+    
+    # Inherit other methods from the default for simplicity
+    is_feature_enabled = ConfigResolver.is_feature_enabled
+    filter_available_options = ConfigResolver.filter_available_options
+
+# 2. Define an initialization callback
+def setup_custom_logging():
+    print("Custom middleware initialization logic is running!")
+
+# 3. Bind the custom components
+MiddlewareRegistry.bind_config_resolver(MyCustomConfigResolver)
+MiddlewareRegistry.register_initialization_callback(setup_custom_logging)
+
+# 4. Initialize the middleware (e.g., at application startup)
+print("--- Initializing Middleware ---")
+MiddlewareRegistry.initialize_middleware()
+print("--- Initialization Complete ---")
+
+# 5. Use the middleware system
+async def check_permissions():
+    # The registry will now use MyCustomConfigResolver automatically
+    CurrentResolver = MiddlewareRegistry.get_config_resolver()
+    print(f"Current resolver is: {CurrentResolver.__name__}")
+
+    # Check an admin user
+    admin_config = await CurrentResolver.resolve_user_config("admin", {}, {})
+    validation_result = CurrentResolver.validate_operation_config(
+        admin_config, {"model": "gpt-4"}, {}
+    )
+    print(f"Admin validation for gpt-4: {validation_result}")
+
+    # Check a regular user
+    user_config = await CurrentResolver.resolve_user_config("user", {}, {})
+    validation_result = CurrentResolver.validate_operation_config(
+        user_config, {"model": "gpt-4"}, {}
+    )
+    print(f"User validation for gpt-4: {validation_result}")
+
+# Run the example
+asyncio.run(check_permissions())
+
+# 6. Check status and reset (useful for testing)
+print(f"\nRegistry Status: {MiddlewareRegistry.get_registry_status()}")
+MiddlewareRegistry.reset_bindings()
+print(f"Registry Status after reset: {MiddlewareRegistry.get_registry_status()}")
+```
+
+================================================================================
+

solace_agent_mesh/common/sac/sac_llm.txt

@@ -68,4 +68,4 @@ agent.run()
 agent.cleanup()
 ```
 
-# content_hash: 44ffaa77554dd658386afa3a420ade21c016b72b1e5394fdba814ea897b3480c
+# content_hash: 8ba90bbcaab8684e6611224e74cb0bb86a9cf87d6dccd25352d70ee3d851a06b

solace_agent_mesh/common/sac/sac_llm_detail.txt

@@ -0,0 +1,82 @@
+# LLM Summary Detail File
+
+This file is a concatenation of all individual *llm.txt files found in the 'sac' directory tree. Each section below corresponds to a specific directory's summary file.
+
+================================================================================
+
+## Section 1: solace_agent_mesh/common/sac/sac_llm.txt
+
+**Source file:** `solace_agent_mesh/common/sac/sac_llm.txt`
+
+# DEVELOPER GUIDE: sac
+
+## Quick Summary
+The `sac` directory provides the base component framework for Solace Agent Mesh (SAM) implementations in the Solace AI Connector. It offers a standardized foundation for building high-level SAM components like Agents and Gateways with built-in async operations management and message publishing capabilities.
+
+## Files Overview
+- `__init__.py` - Empty package initialization file
+- `sam_component_base.py` - Abstract base class providing async thread management and A2A message publishing for SAM components
+
+## Developer API Reference
+
+### sam_component_base.py
+**Purpose:** Provides an abstract base class for SAM components with managed asyncio event loops and message publishing
+**Import:** `from solace_agent_mesh.common.sac.sam_component_base import SamComponentBase`
+
+**Classes:**
+- `SamComponentBase(info: Dict[str, Any], **kwargs: Any)` - Abstract base class for high-level SAM components (Agents, Gateways)
+  - `publish_a2a_message(payload: Dict, topic: str, user_properties: Optional[Dict] = None) -> None` - Publishes A2A messages with size validation
+  - `run() -> None` - Starts the component's dedicated async thread
+  - `cleanup() -> None` - Cleans up resources including async thread and loop
+  - `get_async_loop() -> Optional[asyncio.AbstractEventLoop]` - Returns the dedicated asyncio event loop
+  - `_async_setup_and_run() -> None` - Abstract method for subclasses to implement main async logic
+  - `_pre_async_cleanup() -> None` - Abstract method for cleanup before async loop stops
+  - `namespace: str` - The configured namespace for the component
+  - `max_message_size_bytes: int` - Maximum allowed message size in bytes
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.common.sac.sam_component_base import SamComponentBase
+from typing import Dict, Any
+import asyncio
+
+class MyAgent(SamComponentBase):
+    def __init__(self, info: Dict[str, Any], **kwargs: Any):
+        super().__init__(info, **kwargs)
+        # Additional initialization
+    
+    async def _async_setup_and_run(self) -> None:
+        """Implement your main async logic here"""
+        while not self.stop_signal.is_set():
+            # Your async operations
+            await asyncio.sleep(1)
+    
+    def _pre_async_cleanup(self) -> None:
+        """Cleanup before async loop stops"""
+        # Your cleanup logic
+        pass
+
+# Usage
+config = {
+    "namespace": "my_namespace",
+    "max_message_size_bytes": 1048576  # 1MB
+}
+agent = MyAgent(config)
+
+# Publish a message
+payload = {"message": "Hello World"}
+agent.publish_a2a_message(
+    payload=payload,
+    topic="sam/agents/my_agent/response",
+    user_properties={"correlation_id": "123"}
+)
+
+# Start the component
+agent.run()
+
+# Later, cleanup
+agent.cleanup()
+```
+
+================================================================================
+

solace_agent_mesh/common/sam_events/sam_events_llm.txt

@@ -0,0 +1,104 @@
+# DEVELOPER GUIDE: sam_events
+
+## Quick Summary
+The `sam_events` directory provides system-level event messaging for Solace Agent Mesh (SAM). It enables clean separation between agent-to-agent (A2A) task communication and system events like session lifecycle, agent health, and configuration changes.
+
+## Files Overview
+- `__init__.py` - Package initialization and public API exports
+- `event_service.py` - Core event service implementation with publishing/subscription capabilities
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Package entry point that exports the main classes for SAM event handling
+**Import:** `from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent`
+
+### event_service.py
+**Purpose:** Implements the core event messaging service for system-level events in SAM
+**Import:** `from solace_agent_mesh.common.sam_events.event_service import SamEventService, SamEvent, SessionDeletedEvent`
+
+**Classes:**
+
+- `SamEvent(event_type: str, event_id: str, timestamp: str, source_component: str, namespace: str, data: Dict[str, Any])` - Base class for all SAM system events
+  - `create(event_type: str, source_component: str, namespace: str, data: Dict[str, Any]) -> SamEvent` - Create a new event with auto-generated ID and timestamp
+  - `to_dict() -> Dict[str, Any]` - Convert event to dictionary for messaging
+  - `event_type: str` - Type of event (e.g., "session.deleted")
+  - `event_id: str` - Unique identifier for the event
+  - `timestamp: str` - ISO format timestamp when event was created
+  - `source_component: str` - Component that generated the event
+  - `namespace: str` - SAM namespace
+  - `data: Dict[str, Any]` - Event-specific data payload
+
+- `SessionDeletedEvent(SamEvent)` - Specialized event for session deletion notifications
+  - `create(namespace: str, source_component: str, session_id: str, user_id: str, agent_id: str, gateway_id: str) -> SessionDeletedEvent` - Create a session deleted event
+
+- `SamEventService(namespace: str, component_name: str, publish_func: Callable[[str, Dict, Optional[Dict]], None])` - Service for publishing and subscribing to SAM system events
+  - `publish_event(event: SamEvent) -> bool` - Publish a system event
+  - `publish_session_deleted(session_id: str, user_id: str, agent_id: str, gateway_id: str) -> bool` - Convenience method to publish session deleted event
+  - `subscribe_to_events(event_type: str, handler: Callable[[SamEvent], None]) -> bool` - Subscribe to events of a specific type
+  - `handle_incoming_event(topic: str, payload: Dict[str, Any]) -> None` - Handle incoming events from messaging system
+  - `namespace: str` - The SAM namespace
+  - `component_name: str` - Name of the component using this service
+
+**Functions:**
+
+- `SamEventService.get_event_topic(namespace: str, event_type: str) -> str` - Get the topic for a specific event type
+
+**Usage Examples:**
+
+```python
+# Basic event service setup
+from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent
+
+# Initialize the event service
+def my_publish_func(topic: str, payload: dict, headers: dict = None):
+    # Your A2A publishing implementation
+    pass
+
+event_service = SamEventService(
+    namespace="my_namespace",
+    component_name="my_component", 
+    publish_func=my_publish_func
+)
+
+# Create and publish a custom event
+custom_event = SamEvent.create(
+    event_type="agent.health_check",
+    source_component="health_monitor",
+    namespace="my_namespace",
+    data={"status": "healthy", "cpu_usage": 45.2}
+)
+success = event_service.publish_event(custom_event)
+
+# Publish a session deleted event (convenience method)
+success = event_service.publish_session_deleted(
+    session_id="sess_123",
+    user_id="user_456", 
+    agent_id="agent_789",
+    gateway_id="gateway_001"
+)
+
+# Subscribe to events
+def handle_session_deleted(event: SamEvent):
+    session_id = event.data["session_id"]
+    print(f"Session {session_id} was deleted")
+
+event_service.subscribe_to_events("session.deleted", handle_session_deleted)
+
+# Handle incoming events (typically called by your messaging infrastructure)
+incoming_payload = {
+    "event_type": "session.deleted",
+    "event_id": "evt_123",
+    "timestamp": "2024-01-01T12:00:00Z",
+    "source_component": "gateway",
+    "namespace": "my_namespace",
+    "data": {"session_id": "sess_123", "user_id": "user_456"}
+}
+event_service.handle_incoming_event("sam/events/session/deleted", incoming_payload)
+
+# Get topic for an event type
+topic = SamEventService.get_event_topic("my_namespace", "session.deleted")
+print(topic)  # Returns the proper SAM events topic
+```
+
+# content_hash: e2f1353fe6841458c68f294efc03e1fdbac3632f78507e6e58044bb0c59919af

solace_agent_mesh/common/sam_events/sam_events_llm_detail.txt

@@ -0,0 +1,115 @@
+# LLM Summary Detail File
+
+This file is a concatenation of all individual *llm.txt files found in the 'sam_events' directory tree. Each section below corresponds to a specific directory's summary file.
+
+================================================================================
+
+## Section 1: solace_agent_mesh/common/sam_events/sam_events_llm.txt
+
+**Source file:** `solace_agent_mesh/common/sam_events/sam_events_llm.txt`
+
+# DEVELOPER GUIDE: sam_events
+
+## Quick Summary
+The `sam_events` directory provides system-level event messaging for Solace Agent Mesh (SAM). It enables clean separation between agent-to-agent (A2A) task communication and system events like session lifecycle, agent health, and configuration changes.
+
+## Files Overview
+- `__init__.py` - Package initialization and public API exports
+- `event_service.py` - Core event service implementation with publishing/subscription capabilities
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Package entry point that exports the main classes for SAM event handling
+**Import:** `from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent`
+
+### event_service.py
+**Purpose:** Implements the core event messaging service for system-level events in SAM
+**Import:** `from solace_agent_mesh.common.sam_events.event_service import SamEventService, SamEvent, SessionDeletedEvent`
+
+**Classes:**
+
+- `SamEvent(event_type: str, event_id: str, timestamp: str, source_component: str, namespace: str, data: Dict[str, Any])` - Base class for all SAM system events
+  - `create(event_type: str, source_component: str, namespace: str, data: Dict[str, Any]) -> SamEvent` - Create a new event with auto-generated ID and timestamp
+  - `to_dict() -> Dict[str, Any]` - Convert event to dictionary for messaging
+  - `event_type: str` - Type of event (e.g., "session.deleted")
+  - `event_id: str` - Unique identifier for the event
+  - `timestamp: str` - ISO format timestamp when event was created
+  - `source_component: str` - Component that generated the event
+  - `namespace: str` - SAM namespace
+  - `data: Dict[str, Any]` - Event-specific data payload
+
+- `SessionDeletedEvent(SamEvent)` - Specialized event for session deletion notifications
+  - `create(namespace: str, source_component: str, session_id: str, user_id: str, agent_id: str, gateway_id: str) -> SessionDeletedEvent` - Create a session deleted event
+
+- `SamEventService(namespace: str, component_name: str, publish_func: Callable[[str, Dict, Optional[Dict]], None])` - Service for publishing and subscribing to SAM system events
+  - `publish_event(event: SamEvent) -> bool` - Publish a system event
+  - `publish_session_deleted(session_id: str, user_id: str, agent_id: str, gateway_id: str) -> bool` - Convenience method to publish session deleted event
+  - `subscribe_to_events(event_type: str, handler: Callable[[SamEvent], None]) -> bool` - Subscribe to events of a specific type
+  - `handle_incoming_event(topic: str, payload: Dict[str, Any]) -> None` - Handle incoming events from messaging system
+  - `namespace: str` - The SAM namespace
+  - `component_name: str` - Name of the component using this service
+
+**Functions:**
+
+- `SamEventService.get_event_topic(namespace: str, event_type: str) -> str` - Get the topic for a specific event type
+
+**Usage Examples:**
+
+```python
+# Basic event service setup
+from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent
+
+# Initialize the event service
+def my_publish_func(topic: str, payload: dict, headers: dict = None):
+    # Your A2A publishing implementation
+    pass
+
+event_service = SamEventService(
+    namespace="my_namespace",
+    component_name="my_component", 
+    publish_func=my_publish_func
+)
+
+# Create and publish a custom event
+custom_event = SamEvent.create(
+    event_type="agent.health_check",
+    source_component="health_monitor",
+    namespace="my_namespace",
+    data={"status": "healthy", "cpu_usage": 45.2}
+)
+success = event_service.publish_event(custom_event)
+
+# Publish a session deleted event (convenience method)
+success = event_service.publish_session_deleted(
+    session_id="sess_123",
+    user_id="user_456", 
+    agent_id="agent_789",
+    gateway_id="gateway_001"
+)
+
+# Subscribe to events
+def handle_session_deleted(event: SamEvent):
+    session_id = event.data["session_id"]
+    print(f"Session {session_id} was deleted")
+
+event_service.subscribe_to_events("session.deleted", handle_session_deleted)
+
+# Handle incoming events (typically called by your messaging infrastructure)
+incoming_payload = {
+    "event_type": "session.deleted",
+    "event_id": "evt_123",
+    "timestamp": "2024-01-01T12:00:00Z",
+    "source_component": "gateway",
+    "namespace": "my_namespace",
+    "data": {"session_id": "sess_123", "user_id": "user_456"}
+}
+event_service.handle_incoming_event("sam/events/session/deleted", incoming_payload)
+
+# Get topic for an event type
+topic = SamEventService.get_event_topic("my_namespace", "session.deleted")
+print(topic)  # Returns the proper SAM events topic
+```
+
+================================================================================
+

solace_agent_mesh/common/services/services_llm.txt

@@ -3,7 +3,7 @@
 ## Quick Summary
 The `services` directory provides a modular and extensible framework for integrating external data sources related to identity and employee information into the Solace AI Connector. It is built on a provider pattern, defining abstract base classes (`BaseIdentityService`, `BaseEmployeeService`) that establish a clear contract for what data and functionality a service must provide.
 
-The core architecture revolves around factory functions (`create_identity_service`, `create_employee_service`) that instantiate specific service providers based on a configuration dictionary. This allows the application to remain decoupled from the concrete implementations. Providers can be either built-in (like the file-based identity service located in the `providers/` subdirectory) or dynamically loaded as external plugins, making the system highly flexible and easy to extend.
+The core architecture revolves around factory functions (`create_identity_service`, `create_employee_service`) that instantiate specific service providers based on a configuration dictionary. This allows the application to remain decoupled from the concrete implementations. The `providers/` subdirectory contains concrete implementations, including a built-in file-based identity service, while external providers can be dynamically loaded as plugins through Python's entry points system.
 
 ## Files and Subdirectories Overview
 - **Direct files:**
@@ -44,12 +44,10 @@ The core architecture revolves around factory functions (`create_identity_servic
 ### Subdirectory APIs
 
 #### providers/
-**Purpose:** This subdirectory contains concrete implementations of the abstract service classes. It ships with a built-in provider for the `IdentityService` that is useful for development and testing.
+**Purpose:** Contains concrete implementations of the abstract service classes, providing specific ways to fulfill service contracts such as sourcing user identity information from local files
 **Key Exports:** `LocalFileIdentityService`
 **Import Examples:**
 ```python
-# Typically, you would use the factory function.
-# But for direct instantiation (e.g., in tests), you can do this:
 from solace_agent_mesh.common.services.providers.local_file_identity_service import LocalFileIdentityService
 ```
 
@@ -307,6 +305,59 @@ async def main():
 asyncio.run(main())
 ```
 
-This comprehensive guide shows how the services framework provides a clean, extensible way to integrate various data sources while maintaining consistent interfaces and supporting both built-in providers and external plugins.
+### 5. Using the Built-in LocalFileIdentityService
+The `providers/` subdirectory includes a ready-to-use file-based identity service that's perfect for development and testing.
 
-# content_hash: 63457e2c72256810f713e62325c1601a675951fe47c1121a647c404690179206
+**Example: Setting up LocalFileIdentityService with Factory**
+
+```python
+import asyncio
+import json
+from solace_agent_mesh.common.services.identity_service import create_identity_service
+
+async def setup_file_based_identity():
+    # Create sample users.json file
+    users_data = [
+        {
+            "id": "jdoe",
+            "email": "jane.doe@example.com", 
+            "name": "Jane Doe",
+            "title": "Senior Engineer",
+            "manager_id": "ssmith"
+        },
+        {
+            "id": "ssmith",
+            "email": "sam.smith@example.com",
+            "name": "Sam Smith", 
+            "title": "Engineering Manager"
+        }
+    ]
+
+    with open("users.json", "w") as f:
+        json.dump(users_data, f)
+
+    # Use factory to create the service
+    config = {
+        "type": "local_file",  # This triggers the built-in provider
+        "file_path": "users.json",
+        "lookup_key": "email",  # Use email for lookups
+        "cache_ttl_seconds": 3600
+    }
+    
+    identity_service = create_identity_service(config)
+    
+    # Test the service
+    auth_claims = {"email": "jane.doe@example.com"}
+    profile = await identity_service.get_user_profile(auth_claims)
+    print(f"Profile found: {profile}")
+    
+    # Search functionality
+    search_results = await identity_service.search_users("jane")
+    print(f"Search results: {search_results}")
+
+asyncio.run(setup_file_based_identity())
+```
+
+This comprehensive guide shows how the services framework provides a clean, extensible way to integrate various data sources while maintaining consistent interfaces and supporting both built-in providers and external plugins through the factory pattern and plugin system.
+
+# content_hash: 879562926a7d3b7c6782ae395159d6c1f8a55663ce052a93eea8966e69b04444