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

solace_agent_mesh/gateway/http_sse/http_sse_llm.txt

@@ -1,299 +0,0 @@
-# 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