Python-Rust Bridge (gRPC)

Relevant source files

The following files were used as context for generating this wiki page:

• loom-py/src/loom/bridge/README.md
• ARCHITECTURE.md
• loom-proto/proto/bridge.proto
• loom-py/src/loom/bridge/client.py
• bridge/src/lib.rs
• loom-proto/proto/action.proto
• loom-py/src/loom/agent/README.md

The Python-Rust Bridge is a gRPC-based communication layer that connects Python-based AI agents (the "Brain") with the high-performance Rust Core runtime (the "Hands"). This separation allows for rapid iteration on agent logic and prompt engineering in Python, while leveraging Rust for stable, secure, and performant infrastructure tasks like tool execution, event bus management, and system integration.

The bridge acts as the central nervous system for the Loom ecosystem, translating requests from Python agents into actions within the Rust Core and streaming events from the Core back to the agents. It is designed to be language-agnostic, enabling potential future SDKs in other languages to connect to the same Rust Core.

Sources: ARCHITECTURE.md, loom-py/src/loom/bridge/README.md:5-11

Architecture

The bridge architecture facilitates the "Brain/Hand Separation" design philosophy. The Python agent, containing the cognitive loop and business logic, communicates via the BridgeClient over gRPC. The Rust loom-bridge service receives these communications and interacts with the loom-core components like the Event Bus and Tool Registry.

Sources: ARCHITECTURE.md:12-35, loom-py/src/loom/bridge/README.md:13-35

The following diagram illustrates the high-level data flow between a Python agent and the Rust Core via the gRPC Bridge.

gRPC Service Definition

The bridge's API is formally defined using Protocol Buffers in bridge.proto. It exposes the Bridge service, which provides four main RPC methods for agent interaction.

Sources: loom-proto/proto/bridge.proto:106-112

RPC Method	Request Message	Response Message	Type	Description
RegisterAgent	AgentRegisterRequest	AgentRegisterResponse	Unary	Registers a new agent with the Core, specifying its ID, topics, and tools.
EventStream	stream ClientEvent	stream ServerEvent	Bidirectional Streaming	The main channel for real-time, asynchronous event communication.
ForwardToolCall	ToolCall	ToolResult	Unary	Synchronously forwards a tool execution request to the Rust Tool Registry.
Heartbeat	HeartbeatRequest	HeartbeatResponse	Unary	A keep-alive mechanism to check connection health.

Sources: loom-proto/proto/bridge.proto:106-112

RegisterAgent RPC

This is the first call an agent makes to join the Loom network. It sends metadata about the agent to the Rust Core.

• AgentRegisterRequest: Contains the agent_id, a list of subscribed_topics, and a list of ToolDescriptors that the agent provides.
• AgentRegisterResponse: A simple acknowledgement indicating if the registration was successful.

Sources: loom-proto/proto/bridge.proto:10-23

EventStream RPC

This bidirectional stream is the primary communication channel for agents.

• ClientEvent: Messages sent from the Python agent to the Rust Bridge. This can be a Publish message (to send an event to a topic), an Ack message, a Heartbeat (ping), or a ToolResult.
• ServerEvent: Messages sent from the Rust Bridge to the Python agent. This can be a Delivery (an event from a subscribed topic), a HeartbeatResponse (pong), an Error, or a ToolCall request.

Sources: loom-proto/proto/bridge.proto:29-40, 52-63

ForwardToolCall RPC

This unary call allows a Python agent to execute a tool that is registered within the Rust Core. This is a synchronous request/response pattern.

• ToolCall: Describes the tool to be invoked, including its name, JSON-formatted arguments, and an optional timeout_ms.
• ToolResult: Contains the outcome of the tool execution, including a status (e.g., TOOL_OK, TOOL_ERROR), the JSON-formatted output, and an optional ToolError message.

Sources: loom-proto/proto/action.proto:21-31, 33-41, loom-proto/proto/bridge.proto:110

Communication Flows

Agent Registration and Connection

This sequence diagram shows how a Python agent connects to the bridge and registers itself.

Bidirectional Event Streaming

The EventStream is used for publishing events and receiving deliveries from subscribed topics.

Tool Forwarding

This flow illustrates how a tool call from Python is executed in the Rust Core and the result is returned.

Key Components

Rust Bridge Service (loom-bridge)

The server-side implementation of the Bridge gRPC service. It is responsible for:

• Handling incoming gRPC connections from clients (BridgeClient).
• Managing agent sessions and lifecycles.
• Forwarding ToolCall requests to the ToolRegistry in loom-core.
• Interfacing with the EventBus to publish events from agents and subscribe agents to topics.
• Streaming events from the EventBus back to the appropriate clients.

Sources: bridge/src/lib.rs, bridge/Cargo.toml:3-7

Python BridgeClient

A Python class that acts as the client for the gRPC Bridge service.

• Manages the gRPC channel and connection state (connect, disconnect).
• Provides Pythonic methods that wrap the gRPC RPCs:
  • stream(): Handles the bidirectional EventStream.
  • forward_tool_call(): Executes the ForwardToolCall RPC.
  • save_plan(), check_duplicate(), etc.: Wraps memory service RPCs (though these are part of separate services, they are often used via the same client connection context).
• It is typically used within an EventContext to provide a high-level API to the agent developer.

Sources: loom-py/src/loom/bridge/client.py, loom-py/src/loom/bridge/README.md:38-41

Configuration

The address of the Bridge service can be configured in two ways, with the constructor argument taking precedence.

1. Environment Variable:

   export LOOM_BRIDGE_ADDR="localhost:50051"
   

2. Constructor Argument:

   from loom.bridge import BridgeClient
   client = BridgeClient(address="bridge.example.com:9999")
   

If neither is provided, it defaults to localhost:50051.

Sources: loom-py/src/loom/bridge/README.md:144-156