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

solace_agent_mesh/gateway/http_sse/http_sse_llm.txt

@@ -0,0 +1,299 @@
+# DEVELOPER GUIDE: http_sse
+
+## Quick Summary
+The `http_sse` directory implements a complete HTTP/SSE (Server-Sent Events) gateway for the A2A (Agent-to-Agent) system. It serves as a bridge between web-based user interfaces and the backend A2A messaging fabric, providing real-time communication capabilities through HTTP REST APIs and Server-Sent Events streaming.
+
+The architecture centers around the `WebUIBackendComponent`, a custom Solace AI Connector (SAC) component that hosts an embedded FastAPI web server. This component manages shared resources including the `SSEManager` for real-time updates, `SessionManager` for user sessions, and `AgentRegistry` for agent discovery. The system provides comprehensive functionality including session management, task logging, data retention, feedback collection, and A2A message visualization.
+
+Subdirectories organize functionality by layer: `routers/` defines REST API endpoints, `services/` contains business logic, `repository/` handles data persistence, `components/` provides specialized SAC components, and `shared/` contains common utilities. The `dependencies.py` file uses FastAPI's dependency injection to provide clean separation between the web layer and core messaging components.
+
+## Files and Subdirectories Overview
+- **Direct files:**
+  - `__init__.py`: Standard Python package initializer
+  - `alembic.ini`: Alembic database migration configuration
+  - `app.py`: Main SAC `WebUIBackendApp` class defining configuration schema and component creation
+  - `component.py`: Core SAC component hosting FastAPI server and managing shared resources
+  - `dependencies.py`: FastAPI dependency injectors for accessing shared resources
+  - `main.py`: FastAPI application instance with middleware, routing, and exception handling
+  - `session_manager.py`: Web user session management and A2A identity mapping
+  - `sse_manager.py`: Server-Sent Event connection management for real-time streaming
+  - `sse_event_buffer.py`: Thread-safe buffer for early SSE events before client connection
+- **Subdirectories:**
+  - `alembic/`: Database migration configuration and version files
+  - `components/`: Specialized SAC components for message forwarding and visualization
+  - `repository/`: Data access layer with Repository pattern and SQLAlchemy ORM models
+  - `routers/`: FastAPI router modules defining REST API endpoints
+  - `services/`: Business logic layer for domain-specific operations
+  - `shared/`: Common utilities, constants, enums, and exception handling
+  - `utils/`: Utility functions for creating .stim file structures from task data
+
+## Developer API Reference
+
+### Direct Files
+
+#### app.py
+**Purpose:** Defines the main SAC application class with configuration schema for the HTTP/SSE gateway
+**Import:** `from solace_agent_mesh.gateway.http_sse.app import WebUIBackendApp`
+
+**Classes/Functions/Constants:**
+- **`WebUIBackendApp(BaseGatewayApp)`**: Main application class extending BaseGatewayApp with WebUI-specific configuration
+  - `get_component() -> WebUIBackendComponent | None`: Retrieves the running component instance
+  - `_get_gateway_component_class() -> type[BaseGatewayComponent]`: Returns WebUIBackendComponent class
+- **`SPECIFIC_APP_SCHEMA_PARAMS: List[Dict[str, Any]]`**: Configuration parameters including session_secret_key, FastAPI settings, frontend configuration, database settings, and feature flags
+
+#### component.py
+**Purpose:** Core SAC component hosting FastAPI server and managing all shared resources and A2A logic
+**Import:** `from solace_agent_mesh.gateway.http_sse.component import WebUIBackendComponent`
+
+**Classes/Functions/Constants:**
+- **`WebUIBackendComponent(BaseGatewayComponent)`**: Main component class implementing the gateway functionality
+  - **Public Accessor Methods:**
+    - `get_sse_manager() -> SSEManager`: Returns SSE manager for real-time updates
+    - `get_session_manager() -> SessionManager`: Returns session manager
+    - `get_agent_registry() -> AgentRegistry`: Returns agent registry
+    - `get_core_a2a_service() -> CoreA2AService`: Returns core A2A service
+    - `get_shared_artifact_service() -> BaseArtifactService | None`: Returns artifact service
+    - `get_namespace() -> str`: Returns A2A namespace
+    - `get_gateway_id() -> str`: Returns unique gateway identifier
+  - **Core Methods:**
+    - `publish_a2a(topic: str, payload: dict, user_properties: dict | None = None)`: Publishes A2A messages
+  - **GDK Implementation Methods:**
+    - `_start_listener()`: Starts FastAPI server
+    - `_stop_listener()`: Stops FastAPI server
+    - `_translate_external_input(...)`: Converts HTTP requests to A2A messages
+    - `_send_update_to_external(...)`: Sends intermediate updates via SSE
+    - `_send_final_response_to_external(...)`: Sends final responses via SSE
+    - `_send_error_to_external(...)`: Sends error notifications via SSE
+
+#### dependencies.py
+**Purpose:** FastAPI dependency injectors providing access to shared resources
+**Import:** `from solace_agent_mesh.gateway.http_sse.dependencies import get_sac_component, get_agent_registry, get_sse_manager, get_user_id`
+
+**Functions:**
+- `get_sac_component() -> WebUIBackendComponent`: Returns main component instance
+- `get_agent_registry() -> AgentRegistry`: Returns agent registry
+- `get_sse_manager() -> SSEManager`: Returns SSE manager
+- `get_session_manager() -> SessionManager`: Returns session manager
+- `get_user_id(request: Request) -> str`: Returns current user identity
+- `get_publish_a2a_func() -> PublishFunc`: Returns A2A publishing function
+- `get_core_a2a_service() -> CoreA2AService`: Returns core A2A service
+- `get_shared_artifact_service() -> BaseArtifactService | None`: Returns artifact service
+- `get_db() -> Generator[Session, None, None]`: Returns database session
+- `ValidatedUserConfig(required_scopes: list[str])`: Dependency class for scope validation
+
+#### main.py
+**Purpose:** FastAPI application instance with middleware, routing, and exception handling
+**Import:** `from solace_agent_mesh.gateway.http_sse.main import app, setup_dependencies`
+
+**Classes/Functions/Constants:**
+- **`app: FastAPI`**: Main FastAPI application instance
+- **`setup_dependencies(component: WebUIBackendComponent, database_url: str = None)`**: Configures middleware, routers, and dependency injection
+- **Exception Handlers:**
+  - `http_exception_handler()`: Handles HTTP exceptions with format detection
+  - `validation_exception_handler()`: Handles Pydantic validation errors
+  - `generic_exception_handler()`: Handles unexpected exceptions
+
+#### session_manager.py
+**Purpose:** Manages web user sessions and mapping to A2A Client IDs
+**Import:** `from solace_agent_mesh.gateway.http_sse.session_manager import SessionManager`
+
+**Classes/Functions/Constants:**
+- **`SessionManager(secret_key: str, app_config: Dict[str, Any])`**: Session management class
+  - `get_a2a_client_id(request: Request) -> str | None`: Returns A2A client ID
+  - `start_new_a2a_session(request: Request) -> str`: Creates new A2A session
+  - `ensure_a2a_session(request: Request) -> str`: Ensures session exists
+  - `store_auth_tokens(request: Request, access_token: str, refresh_token: str | None)`: Stores auth tokens
+  - `get_access_token(request: Request) -> str | None`: Retrieves access token
+  - `dep_get_client_id() -> Callable`: Returns FastAPI dependency callable
+
+#### sse_manager.py
+**Purpose:** Manages Server-Sent Event connections for streaming task updates
+**Import:** `from solace_agent_mesh.gateway.http_sse.sse_manager import SSEManager`
+
+**Classes/Functions/Constants:**
+- **`SSEManager(max_queue_size: int, event_buffer: SSEEventBuffer)`**: SSE connection manager
+  - `create_sse_connection(task_id: str) -> asyncio.Queue`: Creates SSE connection queue
+  - `send_event(task_id: str, event_data: Dict[str, Any], event_type: str)`: Sends event to connections
+  - `close_all_for_task(task_id: str)`: Closes connections for specific task
+  - `close_all()`: Closes all active connections
+
+#### sse_event_buffer.py
+**Purpose:** Thread-safe buffer for holding early SSE events before client connection
+**Import:** `from solace_agent_mesh.gateway.http_sse.sse_event_buffer import SSEEventBuffer`
+
+**Classes/Functions/Constants:**
+- **`SSEEventBuffer(max_queue_size: int, max_age_seconds: int)`**: Event buffering system
+  - `buffer_event(task_id: str, event: Dict[str, Any])`: Buffers event for task
+  - `get_and_remove_buffer(task_id: str) -> Optional[List[Dict[str, Any]]]`: Retrieves and removes buffer
+  - `cleanup_stale_buffers()`: Removes old buffers
+
+### Subdirectory APIs
+
+#### alembic/
+**Purpose:** Database migration configuration and version files for schema management
+**Key Exports:** Migration functions for schema evolution (upgrade/downgrade operations)
+**Import Examples:**
+```python
+# These are migration files executed by Alembic CLI, not directly imported
+# Access via Alembic commands:
+# alembic upgrade head
+# alembic downgrade base
+```
+
+#### components/
+**Purpose:** Specialized SAC components for message forwarding and visualization
+**Key Exports:** `VisualizationForwarderComponent`, `TaskLoggerForwarderComponent`
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.components import VisualizationForwarderComponent
+from solace_agent_mesh.gateway.http_sse.components.task_logger_forwarder import TaskLoggerForwarderComponent
+```
+
+#### repository/
+**Purpose:** Data access layer implementing Repository pattern with SQLAlchemy ORM models
+**Key Exports:** Repository interfaces, implementations, domain entities, and SQLAlchemy models
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.repository import (
+    ISessionRepository, ITaskRepository, SessionRepository, TaskRepository,
+    Session, Task, SessionModel, TaskModel, Base
+)
+```
+
+#### routers/
+**Purpose:** FastAPI router modules defining REST API endpoints
+**Key Exports:** Router instances for agents, tasks, SSE, artifacts, auth, config, sessions, people, users, visualization
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.routers import agents, tasks, sse, artifacts
+from solace_agent_mesh.gateway.http_sse.routers.tasks import CancelTaskApiPayload
+```
+
+#### services/
+**Purpose:** Business logic layer for domain-specific operations
+**Key Exports:** `AgentCardService`, `TaskService`, `PeopleService`, `SessionService`, `FeedbackService`, `TaskLoggerService`
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.services.agent_card_service import AgentCardService
+from solace_agent_mesh.gateway.http_sse.services.task_service import TaskService
+from solace_agent_mesh.gateway.http_sse.services.people_service import PeopleService
+```
+
+#### shared/
+**Purpose:** Common utilities, constants, enums, and exception handling
+**Key Exports:** Authentication utilities, timestamp functions, enums, exception handlers, and type definitions
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import get_current_user, now_epoch_ms
+from solace_agent_mesh.gateway.http_sse.shared.enums import SenderType, TaskStatus
+from solace_agent_mesh.gateway.http_sse.shared.types import UserId, SessionId, PaginationInfo
+```
+
+#### utils/
+**Purpose:** Utility functions for creating .stim file structures from task data
+**Key Exports:** `create_stim_from_task_data`
+**Import Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.utils.stim_utils import create_stim_from_task_data
+```
+
+## Complete Usage Guide
+
+### 1. Setting Up the Gateway Application
+
+```python
+from solace_agent_mesh.gateway.http_sse.app import WebUIBackendApp
+
+# Create the gateway app with configuration
+app_config = {
+    "name": "my-webui-gateway",
+    "session_secret_key": "your-secret-key-here",
+    "fastapi_host": "0.0.0.0",
+    "fastapi_port": 8000,
+    "namespace": "/my-namespace",
+    "gateway_id": "webui-gateway-01",
+    "cors_allowed_origins": ["http://localhost:3000"],
+    "frontend_welcome_message": "Welcome to my A2A system!",
+    "frontend_bot_name": "My Assistant",
+    # Database configuration for persistence
+    "session_service": {
+        "type": "sql",
+        "database_url": "sqlite:///./sessions.db"
+    },
+    # Task logging configuration
+    "task_logging": {
+        "enabled": True,
+        "log_status_updates": True,
+        "log_artifact_events": True
+    },
+    # Data retention configuration
+    "data_retention": {
+        "enabled": True,
+        "task_retention_days": 90,
+        "cleanup_interval_hours": 24
+    }
+}
+
+# Initialize and run the app
+webui_app = WebUIBackendApp(app_info=app_config)
+webui_app.run()
+```
+
+### 2. Using Dependencies in Custom Routers
+
+```python
+from fastapi import APIRouter, Depends
+from solace_agent_mesh.gateway.http_sse.dependencies import (
+    get_agent_registry,
+    get_user_id,
+    get_publish_a2a_func,
+    get_core_a2a_service,
+    get_sse_manager,
+    ValidatedUserConfig
+)
+from solace_agent_mesh.common.agent_registry import AgentRegistry
+
+router = APIRouter()
+
+@router.get("/my-custom-endpoint")
+async def my_custom_endpoint(
+    user_id: str = Depends(get_user_id),
+    agent_registry: AgentRegistry = Depends(get_agent_registry),
+    publish_func = Depends(get_publish_a2a_func),
+    user_config: dict = Depends(ValidatedUserConfig(["custom:endpoint:access"]))
+):
+    # Access discovered agents
+    agents = agent_registry.get_all_agents()
+    
+    # Publish a message to the A2A fabric
+    publish_func(
+        topic=f"/my-namespace/a2a/v1/agent/request/some-agent",
+        payload={"method": "custom/request", "params": {"user": user_id}},
+        user_properties={"clientId": user_id}
+    )
+    
+    return {"agents": len(agents), "user": user_id}
+```
+
+### 3. Working with Sessions and Tasks
+
+```python
+from fastapi import Depends
+from sqlalchemy.orm import Session
+from solace_agent_mesh.gateway.http_sse.dependencies import (
+    get_db, get_session_business_service_optional
+)
+from solace_agent_mesh.gateway.http_sse.services.session_service import SessionService
+from solace_agent_mesh.gateway.http_sse.shared.enums import SenderType
+
+@router.post("/sessions/{session_id}/tasks")
+async def save_task_to_session(
+    session_id: str,
+    task_data: dict,
+    user_id: str = Depends(get_user_id),
+    db: Session = Depends(get_db),
+    session_service: SessionService = Depends(get_session_business_service_optional)
+):
+    if session_service and db
+
+# content_hash: 7da6d9233d06a0b9137a843efe5238a14d1762ee3bba437875b5d915634e0f63