schrodinger.application.bunsen.client module

Qt client for the Bunsen web application.

exception schrodinger.application.bunsen.client.BunsenError

Bases: Exception

Base exception for all BunsenClient errors.

exception schrodinger.application.bunsen.client.BunsenAuthenticationError

Bases: BunsenError

The server rejected the PAT (HTTP 401).

exception schrodinger.application.bunsen.client.BunsenSessionNotFoundError

Bases: BunsenError

The session was not found or the ID is malformed (HTTP 404/422).

exception schrodinger.application.bunsen.client.BunsenServerError

Bases: BunsenError

The server returned an internal error (HTTP 5xx).

exception schrodinger.application.bunsen.client.BunsenInvalidURLError

Bases: BunsenError

The server URL could not be reached (DNS failure, connection refused).

exception schrodinger.application.bunsen.client.BunsenConnectionError

Bases: BunsenError

A transient network failure prevented the request (e.g. timeout).

class schrodinger.application.bunsen.client.BunsenClient(base_url: str, session_id: str, token: str | None = None, instance_id: str | None = None, parent: PyQt6.QtCore.QObject | None = None)

Bases: QObject

Client for interacting with a running Bunsen session.

Provides synchronous REST methods for chat, file operations, and WebSocket-based real-time monitoring via Qt signals.

Example usage:

client = BunsenClient("https://bunsen.example.com", "session-uuid")
session = client.getSession()
messages = client.getChatMessages()
client.sendChatMessage("Hello, Bunsen!")

# Monitor real-time events
client.messageReceived.connect(on_message)
client.connectWebSocket()
Parameters:

  • base_url – Base URL of the Bunsen server (e.g. "https://bunsen.example.com").

  • session_id – UUID string of the session to connect to.

  • token – Optional Bunsen Personal Access Token for authentication.

messageReceived

A pyqtSignal emitted by instances of the class.

connected

A pyqtSignal emitted by instances of the class.

disconnected

A pyqtSignal emitted by instances of the class.

connectionFailed

A pyqtSignal emitted by instances of the class.

static parseChatUrl(url: str) → tuple[str, str] | tuple[None, None]

Extract server URL and session ID from a Bunsen chat URL.

Parameters:

url – Full chat URL (e.g. "https://bunsen.example.com/session/abc-123").

Returns:

(server_url, session_id) or (None, None) if invalid.

static getSettingsUrl(server_url: str) → str

Return the user-settings page URL for the given server.

Parameters:

server_url – Base URL of the Bunsen server.

__init__(base_url: str, session_id: str, token: str | None = None, instance_id: str | None = None, parent: PyQt6.QtCore.QObject | None = None)
getInstanceId() → str
getSessionUrl() → str

Return the full URL of the session.

getSession() → dict
getChatMessages(offset: int = 0) → list[dict]

Get chat message history.

Parameters:

offset – Pagination offset.

sendChatMessage(content: str) → dict

Send a chat message.

The message is processed asynchronously by the Bunsen pod. Use the WebSocket connection to monitor the response.

Parameters:

content – Message text.

sendAnswer(answers: dict) → dict

Submit an answer to a pending AskUserQuestion.

Parameters:

answers – Dict mapping question IDs to answer strings.

listFiles(showHidden: bool = False) → list[dict]

List files in the session workspace.

Parameters:

showHidden – If True, include hidden files (dotfiles).

downloadFile(remotePath: str, localPath: str)

Download a file from the session workspace.

Parameters:

  • remotePath – Path of the file in the workspace (e.g. "src/main.py").

  • localPath – Local filesystem path to save to.

downloadWorkspace(localPath: str)

Download the entire workspace as a tar.gz archive.

Parameters:

localPath – Local filesystem path to save the archive to.

uploadFile(localPath: str, remotePath: str | None = None) → dict

Upload a local file to the session workspace.

Parameters:

  • localPath – Local filesystem path of the file to upload.

  • remotePath – Optional remote directory path. If None, uploads to the workspace root.

sendWebSocketMessage(data: dict)

Send a JSON message over the WebSocket connection.

Parameters:

data – Dict to serialize as JSON and send.

Raises:

RuntimeError – If the WebSocket is not connected.

connectWebSocket()

Start WebSocket monitoring with auto-reconnect.

Events are delivered via the messageReceived, connected, and disconnected signals.

disconnectWebSocket()

Stop WebSocket monitoring.

The socket is closed, then retired after a short delay: it is kept referenced and deleted only once WS_RETIRE_DELAY_MS has elapsed, so any queued macOS CFSocket callout drains while the object is still alive. Deleting (or dropping the reference to) the socket immediately races a Qt use-after-free on wss teardown (QTBUG-146208; BUNSEN-359). Reconnecting is blocked until the old socket has been retired.