Struct PythonRuntime 

pub struct PythonRuntime { /* private fields */ }

Manages a dedicated Python thread with an asyncio event loop.

All Python/SDK interactions go through the command channel. This isolates GIL acquisition to the Python thread and keeps the tokio runtime responsive.

Implementations

impl PythonRuntime

pub fn new(config: RuntimeConfig) -> Result<Self, Error>

Spawn a new Python runtime on a dedicated thread.

Creates an asyncio event loop in the thread and starts the command dispatch loop.

Errors

Returns Error::BackendError if the thread fails to spawn or Python initialization fails.

pub async fn shutdown(self) -> Result<(), Error>

Graceful shutdown: send Shutdown command, then join the thread.

Errors

Returns Error::Timeout if the thread doesn’t join within the configured shutdown timeout, or Error::BackendError if the thread panicked.

pub const fn quota_state(&self) -> &Arc<QuotaState>

Access the shared quota state.

Trait Implementations

impl Debug for PythonRuntime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for PythonRuntime

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Runtime for PythonRuntime

async fn create_agent(&self, config: AgentConfig) -> Result<AgentId, Error>

Create an agent from the given config, returning its ID.

async fn chat( &self, agent_id: AgentId, content: &Content, ) -> Result<ChatResponseHandle, Error>

Send a chat message to the agent, returning a streaming response handle.

async fn shutdown_agent(&self, agent_id: AgentId) -> Result<(), Error>

Gracefully shut down the agent.

fn try_shutdown_agent(&self, agent_id: AgentId)

Best-effort synchronous shutdown signal, called from Drop.

async fn cancel(&self, agent_id: AgentId) -> Result<(), Error>

Interrupt any active prompt/chat run.

async fn wait_for_idle(&self, agent_id: AgentId) -> Result<(), Error>

Wait for the active run or conversational loop to stabilize.

async fn send(&self, agent_id: AgentId, content: &Content) -> Result<(), Error>

Send a message without waiting for completion.

async fn signal_idle(&self, agent_id: AgentId) -> Result<(), Error>

Signal that the agent is idle.

async fn wait_for_wakeup( &self, agent_id: AgentId, timeout: Duration, ) -> Result<bool, Error>

Wait for the agent to wake up. Returns true if woken, false if timed out.

async fn wait_for_quota(&self)

Wait if we’re in a quota backoff period.

async fn record_quota_hit(&self, retry_after: Duration)

Record a quota hit with the suggested retry duration.

fn quota_registry(&self) -> &QuotaRegistry

Access this runtime’s per-key quota registry.

async fn history( &self, agent_id: AgentId, ) -> Result<Vec<ConversationMessage>, Error>

Retrieve the conversation’s message history.

async fn turn_count(&self, agent_id: AgentId) -> Result<u32, Error>

Return the number of completed turns in the conversation.

async fn total_usage(&self, agent_id: AgentId) -> Result<UsageMetadata, Error>

Return cumulative token usage across all turns.

async fn last_turn_usage( &self, agent_id: AgentId, ) -> Result<UsageMetadata, Error>

Return token usage from the most recent turn only.

async fn clear_history(&self, agent_id: AgentId) -> Result<(), Error>

Clear the conversation history and reset state.

async fn compaction_indices(&self, agent_id: AgentId) -> Result<Vec<u32>, Error>

Return the step indices at which compaction occurred.

async fn last_response( &self, agent_id: AgentId, ) -> Result<Option<String>, Error>

Return the text of the last model response, if any.

async fn delete(&self, agent_id: AgentId) -> Result<(), Error>

Delete the conversation and all associated state.

async fn disconnect(&self, agent_id: AgentId) -> Result<(), Error>

Disconnect from the agent without deleting state.

async fn is_idle(&self, agent_id: AgentId) -> Result<bool, Error>

Check whether the agent is currently idle (not running a turn).