esem-bridge communicates between the Node.js runtime and the Python worker using newline-delimited JSON messages over the subprocess’s stdin and stdout pipes. Node.js writes a request object followed by a newline character to the worker’s stdin; the worker processes it and writes a response object followed by a newline to its stdout. Every request carries a numericDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/Crane04/esem/llms.txt
Use this file to discover all available pages before exploring further.
id; every response echoes that id so the bridge can match it to the correct pending Promise. There is no framing beyond the newline delimiter and no transport layer beyond the two stdio streams.
Startup Signal
Before accepting any requests, the Python worker emits a single ready message to signal that it has initialised and is ready to process requests:bridge.js waits for this message before resolving the ensureWorker() promise. Any RPC calls made before the ready signal is received are queued and sent immediately after it arrives.
The request
id field is a monotonically incrementing integer managed by
bridge.js. The counter starts at 0 and is incremented for each outgoing
request (++requestCounter). Responses are matched to their originating
call using a Map keyed by id. This means requests can be in-flight
concurrently — responses do not need to arrive in order.Actions
The Python worker’sHANDLERS dict registers one handler function per action name. The six supported actions are documented below.
load — Load a module and return its exports
load — Load a module and return its exports
Loads a Python module by file path or package name and returns metadata about
all of its public exports. The bridge calls this once per unique module
specifier when building a module proxy.RequestResponse
Monotonically incrementing request identifier.
Must be
"load".Relative file path (e.g.
"./tools.py") or installed package name (e.g.
"numpy"). Paths starting with ./, /, or ending with .py are treated
as file paths; everything else is passed to importlib.import_module.A map of export name → export metadata. Each entry has a
kind field
("function", "class", or "value") and, for callables, a params
array of parameter name strings derived from inspect.signature.call — Call a module-level function
call — Call a module-level function
Calls a named function in a previously loaded (or auto-loaded) module with
the provided positional arguments and returns the serialized result.RequestResponse
Module specifier, same format as
load.Name of the function to call.
Positional arguments as typed wire-format envelopes. See
Type Mappings for the envelope schema.
Optional keyword arguments as a map of name → typed envelope.
The function’s return value as a typed wire-format envelope.
construct — Instantiate a class
construct — Instantiate a class
Instantiates a named class from a module, registers the resulting object in
the Python object registry, and returns the Response
ref_id together with the
instance’s public method signatures.RequestModule specifier.
Name of the class to instantiate.
Constructor arguments as typed wire-format envelopes.
Optional keyword constructor arguments.
Registry key for the new instance, e.g.
"py_obj_1". Pass this in
subsequent method_call or release requests.Map of public method name →
{kind: "method", params: [...]}. Private
methods (names starting with _) are excluded.method_call — Call a method on a proxied object
method_call — Call a method on a proxied object
Looks up a live Python object in the registry by Response
ref_id and calls one of
its methods.RequestRegistry key returned by a prior
construct response.Name of the method to call.
Positional arguments as typed wire-format envelopes.
Optional keyword arguments.
The method’s return value as a typed wire-format envelope.
get_attr — Get an attribute value
get_attr — Get an attribute value
Retrieves the value of a named attribute from a module or a proxied object.
Module-level constants and other non-callable values are fetched lazily via
this action.RequestResponse
Module specifier. Provide either
module or ref_id, not both.Registry key of a proxied object. Provide either
ref_id or module, not
both.Name of the attribute to read.
The attribute value as a typed wire-format envelope.
release — Release a proxied object
release — Release a proxied object
Removes a Python object from the registry, allowing it to be garbage-collected.
Call this when you are done with a class instance and want to free the memory
on the Python side.RequestResponseThe response carries no additional fields. After a successful release, any
further
Registry key of the object to release.
method_call or get_attr requests for the same ref_id will
return an error.Error Response
When any handler raises an exception, the worker catches it and sends an error response instead of a result.bridge.js converts this into a PythonError instance and rejects the pending Promise:
The string representation of the Python exception (
str(e)).The full Python traceback as produced by
traceback.format_exc().The Python exception class name, e.g.
"ValueError", "TypeError",
"ImportError". The resulting PythonError in JavaScript will have its
name property set to PythonError(<error_type>).Object Registry
The Python worker maintains a module-level_object_registry dictionary that maps ref_id strings to live Python objects. The _object_counter integer is incremented for each registration, ensuring ref IDs are unique within a worker lifetime.
- A class is instantiated via
construct— the new instance is registered. - A function or method returns a callable or a class object.
- A function or method returns any value that is not a primitive, list, or dict.
release action (_object_registry.pop(ref_id, None)). If you never call release, objects remain in the registry for the lifetime of the worker process.