clara.api.ws package

Submodules

clara.api.ws.connection_manager module

WebSocket Connection Lifetime and Broadcast Manager.

This module provides the ConnectionManager class to manage active WebSocket client connections, connection handshakes, disconnections, and concurrent message broadcasting with automatic stale connection pruning.

class clara.api.ws.connection_manager.ConnectionManager

Bases: object

Manages active WebSocket connections and client communication.

Provides mechanisms to accept new client connections, track active sockets, send targeted single-client messages, and broadcast events to all connected clients.

active_connections

A list of currently open and active WebSocket client connections.

Type:

List[WebSocket]

Example

>>> manager = ConnectionManager()
>>> await manager.connect(websocket)
>>> await manager.broadcast({"event": "status", "data": "ready"})

async connect(websocket)

Accepts a incoming WebSocket handshake and tracks the connection.

Parameters:

websocket (WebSocket) – The raw FastAPI WebSocket instance.

Return type:

None

disconnect(websocket)

Removes a WebSocket from the active connection pool.

Parameters:

websocket (WebSocket) – The WebSocket connection instance.

Raises:

ValueError – If connection is not found in the active pool.

Return type:

None

async send_clara_message(message, websocket)

Sends a JSON-serialized message to a single specific client.

Parameters:

• message (Dict[str, Any]) – Dictionary payload to transmit as JSON.

• websocket (WebSocket) – Target client WebSocket connection.

Return type:

None

async broadcast(data)

Broadcasts a JSON-serializable message to all active clients.

Automatically detects and prunes disconnected or broken client sockets during broadcast iteration.

Parameters:

data (Dict[str, Any]) – JSON payload to send to all active clients.

Return type:

None

clara.api.ws.connection_manager.manager: ConnectionManager = <clara.api.ws.connection_manager.ConnectionManager object>

Default global connection manager singleton.

clara.api.ws.event_streamer module

Real-time Event Streaming Module for Clara WebSocket Clients.

This module provides the EventStreamer class to format, wrap, and stream real-time agent progress events, execution updates, and response payloads to connected frontends.

class clara.api.ws.event_streamer.EventStreamer(manager)

Bases: object

Streams structured real-time events over active WebSocket connections.

Wraps raw application messages into consistent typed envelopes and broadcasts them to clients via a ConnectionManager.

Parameters:

manager (ConnectionManager)

manager

The WebSocket connection manager used for transmission.

Type:

ConnectionManager

Example

>>> streamer = EventStreamer(manager=manager)
>>> await streamer.broadcast_event("agent_thinking", {"step": 1})

async broadcast_event(event_type, payload)

Publishes a typed event payload to all connected clients.

Parameters:

• event_type (str) – Type tag identifying the event (e.g., ‘chat_response’, ‘agent_status’).

• payload (Any) – JSON-serializable data payload associated with the event.

Return type:

None

async send_to_user(user_id, event_type, payload)

Publishes an event targeted to a specific user.

Parameters:

• user_id (str) – Unique user identifier.

• event_type (str) – Type tag identifying the event.

• payload (Any) – Data payload associated with the event.

Return type:

None

clara.api.ws.router module

WebSocket API Router for Clara Real-time Chat and Skill Execution.

This module defines FastAPI WebSocket routing endpoints, message parsing routines, and automated intent routing to available skills (e.g. Email Assistant).

async clara.api.ws.router.websocket_chat_endpoint(websocket)

FastAPI WebSocket endpoint for interactive streaming chat with Clara.

Handles connection acceptance, incoming message loops, live event streaming, and graceful disconnection handling.

Parameters:

websocket (WebSocket) – Incoming FastAPI WebSocket connection.

Return type:

None

Route:

/ws/chat

Module contents