railtracks
Build agents and harnesses in plain Python: the loop, tools, context, and controls around an LLM
1# ------------------------------------------------------------- 2# Copyright (c) Railtown AI. All rights reserved. 3# Licensed under the MIT License. See LICENSE in project root for information. 4# ------------------------------------------------------------- 5"""Build agents and harnesses in plain Python: the loop, tools, context, and controls around an LLM""" 6 7from __future__ import annotations 8 9import importlib 10import logging 11from typing import TYPE_CHECKING 12 13from dotenv import load_dotenv 14 15if TYPE_CHECKING: 16 from railtracks import retrieval 17 from railtracks.interaction import interactive as interactive 18 19__all__ = [ 20 "call", 21 "astream", 22 "broadcast", 23 "call_batch", 24 "ExecutionInfo", 25 "ExecutorConfig", 26 "llm", 27 "guardrails", 28 "middleware", 29 "context", 30 "set_config", 31 "context", 32 "function_node", 33 "agent_node", 34 "decision_node", 35 "decisions", 36 "integrations", 37 "prebuilt", 38 "MCPStdioParams", 39 "MCPHttpParams", 40 "connect_mcp", 41 "create_mcp_server", 42 "ToolManifest", 43 "session_id", 44 "evaluations", 45 "observability", 46 "retrieval", 47 "Flow", 48 "FlowConnection", 49 "NodeMessageHistory", 50 "enable_logging", 51 "wrap_node", 52 "post_node", 53 "after_node", 54 "couple", 55 "pre_llm", 56 "post_llm", 57 "before_llm", 58 "after_llm", 59 "wrap_llm", 60 "input_guard", 61 "output_guard", 62 "escape_braces", 63] 64 65 66from railtracks.built_nodes.decisions import decision_node 67from railtracks.built_nodes.function import ( 68 function_node, 69) 70from railtracks.built_nodes.llm import agent_node 71 72from . import ( 73 context, 74 decisions, 75 evaluations, 76 guardrails, 77 integrations, 78 llm, 79 middleware, 80 observability, 81 prebuilt, 82 retrieval, 83) 84 85# Reachable for existing code, but out of __all__: the entry point is rt.Flow 86from ._session import Session as Session 87from ._session import session as session 88from .built_nodes.llm.middleware import ( 89 after_llm, 90 before_llm, 91 post_llm, 92 pre_llm, 93 wrap_llm, 94) 95from .context.central import session_id, set_config 96from .guardrails import input_guard, output_guard 97from .interaction import astream, broadcast, call, call_batch, couple 98from .llm.context_injection_utils import escape_braces 99from .middleware import after_node, post_node, wrap_node 100from .nodes.manifest import ToolManifest 101from .orchestration.connection import FlowConnection, NodeMessageHistory 102from .orchestration.flow import Flow 103from .rt_mcp import MCPHttpParams, MCPStdioParams, connect_mcp, create_mcp_server 104from .state.info import ExecutionInfo 105from .utils.config import ExecutorConfig 106from .utils.deprecation import warn_pending_change 107from .utils.logging.setup import enable_logging 108 109load_dotenv() 110 111# Library does not configure logging by default. Add NullHandler so the RT logger 112# never emits "No handlers could be found". Call enable_logging() to opt in. 113logging.getLogger("RT").addHandler(logging.NullHandler()) 114 115# Do not worry about changing this version number manually. It will updated on release. 116__version__ = "1.0.0" 117 118 119def __getattr__(name: str): 120 if name == "interactive": 121 # Not cached in globals() 122 warn_pending_change( 123 "rt.interactive", 124 change="is removed", 125 detail="There is no replacement; the local chat UI is going away.", 126 ) 127 return importlib.import_module("railtracks.interaction.interactive") 128 if name == "retrieval": 129 try: 130 module = importlib.import_module("railtracks.retrieval") 131 except ImportError as exc: 132 raise ImportError( 133 "railtracks.retrieval requires the retrieval extras. " 134 "Install with: pip install 'railtracks[retrieval]'" 135 ) from exc 136 globals()[name] = module 137 return module 138 raise AttributeError(f"module {__name__!r} has no attribute {name!r}") 139 140 141def __dir__() -> list[str]: 142 # Reachable but out of __all__, so pdoc does not advertise them 143 return sorted({*__all__, "interactive", "Session", "session"})
59async def call( 60 node_: type[Node[_P, _TOutput]] | RTFunction[_P, _TOutput], 61 *args: _P.args, 62 **kwargs: _P.kwargs, 63) -> _TOutput: 64 """ 65 Call a node from within a node inside the framework. This will return a coroutine that you can interact with 66 in whatever way using async/await logic. 67 68 Usage: 69 ```python 70 # for sequential operation 71 result = await call(NodeA, "hello world", 42) 72 73 # for parallel operation 74 tasks = [call(NodeA, "hello world", i) for i in range(10)] 75 results = await asyncio.gather(*tasks) 76 ``` 77 78 Args: 79 node: The node type you would like to create. This could be a function decorated with `@function_node`, a function, or a Node instance. 80 *args: The arguments to pass to the node 81 **kwargs: The keyword arguments to pass to the node 82 """ 83 node: type[Node[_P, _TOutput]] 84 85 if hasattr(node_, "node_type"): 86 # local import to prevent circular import issues (note it is a purely type checking import) 87 from railtracks.built_nodes.function.base import RTFunction 88 89 assert isinstance(node_, RTFunction) 90 node = extract_node_from_function(node_) 91 else: 92 node = node_ 93 94 # if the context is none then we will need to create a wrapper for the state object to work with. 95 if not is_context_present(): 96 # we have to use lazy import here to prevent a circular import issue. This is a must have unfortunately. 97 from railtracks import Session 98 99 with Session(): 100 result = await _start(node, args=args, kwargs=kwargs) 101 return result 102 103 # if the context is not active then we know this is the top level request 104 if not is_context_active(): 105 result = await _start(node, args=args, kwargs=kwargs) 106 return result 107 108 # if the context is active then we can just run the node 109 result = await _run(node, args=args, kwargs=kwargs) 110 return result
Call a node from within a node inside the framework. This will return a coroutine that you can interact with in whatever way using async/await logic.
Usage:
# for sequential operation
result = await call(NodeA, "hello world", 42)
# for parallel operation
tasks = [call(NodeA, "hello world", i) for i in range(10)]
results = await asyncio.gather(*tasks)
Arguments:
- node: The node type you would like to create. This could be a function decorated with
@function_node, a function, or a Node instance. - *args: The arguments to pass to the node
- **kwargs: The keyword arguments to pass to the node
264def astream( 265 node_: type[Node[_P, _TOutput]], 266 *args: _P.args, 267 **kwargs: _P.kwargs, 268) -> Stream[_TOutput]: 269 """ 270 Invoke an agent node with streaming enabled and return a `Stream` over its emitted chunks. 271 272 Async-iterate the returned `Stream` for token chunks and read `.result` for the final 273 return value, or `await` it directly when you only want the result. Streaming is 274 frame-local: only the node invoked here streams its LLM responses; nested `rt.call` 275 children run buffered. 276 277 Args: 278 node_: The agent node class to invoke (built with `rt.agent_node(...)`). Only agent 279 nodes are accepted; a `@function_node` / tool node has no token stream to 280 surface, so use `rt.call` for those. 281 *args: The positional arguments to pass to the node. 282 **kwargs: The keyword arguments to pass to the node. 283 284 Returns: 285 Stream[_TOutput]: An async iterator over the chunks, with the final result available 286 via `.result` (or by awaiting the stream). 287 288 Raises: 289 NodeCreationError: If `node_` is not an agent node. 290 """ 291 # local import to prevent circular import issues (mirrors rt.call) 292 from railtracks.nodes.nodes import Node 293 294 # rt.astream streams an agent's LLM tokens, so it only accepts agent nodes built with 295 # rt.agent_node(...). Validate the input up front: anything that is not an agent `Node` 296 # subclass (a @function_node / tool node, or a raw value) has no token stream to surface, 297 # so it is rejected here rather than unpacked use rt.call instead. 298 is_agent_node = ( 299 isinstance(node_, type) and issubclass(node_, Node) and node_.type() == "Agent" 300 ) 301 if not is_agent_node: 302 name = getattr(node_, "__name__", None) or repr(node_) 303 raise NodeCreationError( 304 message=f"rt.astream only supports agent nodes, but {name!r} is not one.", 305 notes=[ 306 "Pass an agent built with rt.agent_node(...) to rt.astream(...).", 307 "To run a function/tool node, use rt.call(...) instead.", 308 ], 309 ) 310 node = node_ 311 312 # Session lifecycle is owned here, not by the Stream handle. When called outside any 313 # session we open one and hold it in this closure; the Stream calls `_close` back once 314 # it finishes (see Stream.on_start / on_close), so the session's open/close logic lives 315 # with astream rather than inside the returned object. 316 owned: list[Session] = [] 317 318 def _open() -> None: 319 if not is_context_present(): 320 from railtracks import Session # lazy import to avoid a circular import 321 322 owned.append(Session()) 323 324 def _close() -> None: 325 while owned: 326 owned.pop().__exit__(None, None, None) 327 328 return Stream(node, args, kwargs, on_start=_open, on_close=_close)
Invoke an agent node with streaming enabled and return a Stream over its emitted chunks.
Async-iterate the returned Stream for token chunks and read .result for the final
return value, or await it directly when you only want the result. Streaming is
frame-local: only the node invoked here streams its LLM responses; nested rt.call
children run buffered.
Arguments:
- node_: The agent node class to invoke (built with
rt.agent_node(...)). Only agent nodes are accepted; a@function_node/ tool node has no token stream to surface, so usert.callfor those. - *args: The positional arguments to pass to the node.
- **kwargs: The keyword arguments to pass to the node.
Returns:
Stream[_TOutput]: An async iterator over the chunks, with the final result available via
.result(or by awaiting the stream).
Raises:
- NodeCreationError: If
node_is not an agent node.
8async def broadcast(item: str): 9 """ 10 Broadcasts a one-off **event** to the session bus. 11 12 This triggers the `broadcast_callback` you have provided to the `Session` (or via 13 `rt.set_config`). Each broadcast is a discrete event, independent of any LLM token 14 output an agent produces. 15 16 Args: 17 item (str): The item you want to broadcast. 18 """ 19 publisher = get_publisher() 20 21 await publisher.publish(BroadcastEvent(node_id=get_parent_id(), item=item))
Broadcasts a one-off event to the session bus.
This triggers the broadcast_callback you have provided to the Session (or via
rt.set_config). Each broadcast is a discrete event, independent of any LLM token
output an agent produces.
Arguments:
- item (str): The item you want to broadcast.
19async def call_batch( 20 node: type[Node[..., _TOutput]] | RTFunction[..., _TOutput], 21 *iterables: Iterable[Any], 22 return_exceptions: bool = True, 23): 24 """ 25 Complete a node over multiple iterables, allowing for parallel execution. 26 27 Note the results will be returned in the order of the iterables, not the order of completion. 28 29 If one of the nodes returns an exception, the thrown exception will be included as a response. 30 31 Args: 32 node: The node type to create. 33 *iterables: The iterables to map the node over. 34 return_exceptions: If True, exceptions will be returned as part of the results. 35 If False, exceptions will be raised immediately, and you will lose access to the results. 36 Defaults to true. 37 38 Returns: 39 An iterable of results from the node. 40 41 Usage: 42 ```python 43 results = await batch(NodeA, ["hello world"] * 10) 44 for result in results: 45 handle(result) 46 ``` 47 """ 48 # this is big typing disaster but there is no way around it. Try if if you want to. 49 contracts = [call(node, *args) for args in zip(*iterables)] 50 51 results = await asyncio.gather(*contracts, return_exceptions=return_exceptions) 52 return results
Complete a node over multiple iterables, allowing for parallel execution.
Note the results will be returned in the order of the iterables, not the order of completion.
If one of the nodes returns an exception, the thrown exception will be included as a response.
Arguments:
- node: The node type to create.
- *iterables: The iterables to map the node over.
- return_exceptions: If True, exceptions will be returned as part of the results. If False, exceptions will be raised immediately, and you will lose access to the results. Defaults to true.
Returns:
An iterable of results from the node.
Usage:
results = await batch(NodeA, ["hello world"] * 10) for result in results: handle(result)
19class ExecutionInfo: 20 """ 21 A class that contains the full details of the state of a run at any given point in time. 22 23 The class is designed to be used as a snapshot of state that can be used to display the state of the run, or to 24 create a graphical representation of the system. 25 """ 26 27 def __init__( 28 self, 29 request_forest: RequestForest, 30 node_forest: NodeForest, 31 stamper: StampManager, 32 ): 33 self.request_forest = request_forest 34 self.node_forest = node_forest 35 self.stamper = stamper 36 37 @classmethod 38 def default(cls) -> ExecutionInfo: 39 """Creates a new "empty" instance of the ExecutionInfo class with the default values.""" 40 return cls.create_new() 41 42 @classmethod 43 def create_new( 44 cls, 45 ) -> ExecutionInfo: 46 """ 47 Creates a new empty instance of state variables with the provided executor configuration. 48 49 """ 50 request_heap = RequestForest() 51 node_heap = NodeForest() 52 stamper = StampManager() 53 54 return ExecutionInfo( 55 request_forest=request_heap, 56 node_forest=node_heap, 57 stamper=stamper, 58 ) 59 60 @property 61 def answer(self): 62 """Convenience method to access the answer of the run.""" 63 return self.request_forest.answer 64 65 @property 66 def all_stamps(self) -> List[Stamp]: 67 """Convenience method to access all the stamps of the run.""" 68 return self.stamper.all_stamps 69 70 @property 71 def name(self): 72 """ 73 Gets the name of the graph by pulling the name of the insertion request. It will raise a ValueError if the insertion 74 request is not present or there are multiple insertion requests. 75 """ 76 insertion_requests = self.insertion_requests 77 78 # The name is only defined for the length of 1. 79 # NOTE: Maybe we should send a warning once to user in other cases. 80 if len(insertion_requests) != 1: 81 return None 82 83 i_r = insertion_requests[0] 84 85 return self.node_forest.get_node_type(i_r.sink_id).name() 86 87 @property 88 def insertion_requests(self): 89 """A convenience method to access all the insertion requests of the run.""" 90 return self.request_forest.insertion_request 91 92 def _get_info(self, ids: List[str] | str | None = None) -> ExecutionInfo: 93 """ 94 Gets a subset of the current state based on the provided node ids. It will contain all the children of the provided node ids 95 96 Note: If no ids are provided, the full state is returned. 97 98 Args: 99 ids (List[str] | str | None): A list of node ids to filter the state by. If None, the full state is returned. 100 101 Returns: 102 ExecutionInfo: A new instance of ExecutionInfo containing only the children of the provided ids. 103 104 """ 105 if ids is None: 106 return self 107 else: 108 # firstly lets 109 if isinstance(ids, str): 110 ids = [ids] 111 112 # we need to quickly check to make sure these ids are valid 113 for identifier in ids: 114 if identifier not in self.request_forest: 115 raise ValueError( 116 f"Identifier '{identifier}' not found in the current state." 117 ) 118 119 new_node_forest, new_request_forest = create_sub_state_info( 120 self.node_forest.heap(), 121 self.request_forest.heap(), 122 ids, 123 ) 124 return ExecutionInfo( 125 node_forest=new_node_forest, 126 request_forest=new_request_forest, 127 stamper=self.stamper, 128 ) 129 130 def _to_graph(self) -> Tuple[List[Vertex], List[Edge]]: 131 """ 132 Converts the current state into its graph representation. 133 134 Returns: 135 List[Node]: An iterable of nodes in the graph. 136 List[Edge]: An iterable of edges in the graph. 137 """ 138 return self.node_forest.to_vertices(), self.request_forest.to_edges() 139 140 def graph_serialization(self) -> dict[str, Any]: 141 """ 142 Creates a string (JSON) representation of this info object designed to be used to construct a graph for this 143 info object. 144 145 Some important notes about its structure are outlined below: 146 - The `nodes` key contains a list of all the nodes in the graph, represented as `Vertex` objects. 147 - The `edges` key contains a list of all the edges in the graph, represented as `Edge` objects. 148 - The `stamps` key contains an ease of use list of all the stamps associated with the run, represented as `Stamp` objects. 149 150 - The "nodes" and "requests" key will be outlined with normal graph details like connections and identifiers in addition to a loose details object. 151 - However, both will carry an addition param called "stamp" which is a timestamp style object. 152 - They also will carry a "parent" param which is a recursive structure that allows you to traverse the graph in time. 153 154 155 ``` 156 """ 157 parent_nodes = [x.identifier for x in self.insertion_requests] 158 159 infos = [self._get_info(parent_node) for parent_node in parent_nodes] 160 161 runs = [] 162 163 for info, parent_node_id in zip(infos, parent_nodes): 164 insertion_requests = info.request_forest.insertion_request 165 166 assert len(insertion_requests) == 1 167 parent_request = insertion_requests[0] 168 169 all_parents = parent_request.get_all_parents() 170 171 start_time = all_parents[-1].stamp.time 172 173 assert len([x for x in all_parents if x.status == "Completed"]) <= 1 174 end_time = None 175 for req in all_parents: 176 if req.status in ["Completed", "Failed"]: 177 end_time = req.stamp.time 178 break 179 180 entry = { 181 "name": info.name, 182 "run_id": parent_node_id, 183 "nodes": info.node_forest.to_vertices(), 184 "status": parent_request.status, 185 "edges": info.request_forest.to_edges(), 186 "steps": _get_stamps_from_forests( 187 info.node_forest, info.request_forest 188 ), 189 "start_time": start_time, 190 "end_time": end_time, 191 } 192 runs.append(entry) 193 194 return json.loads( 195 json.dumps( 196 runs, 197 cls=RTJSONEncoder, 198 ) 199 )
A class that contains the full details of the state of a run at any given point in time.
The class is designed to be used as a snapshot of state that can be used to display the state of the run, or to create a graphical representation of the system.
37 @classmethod 38 def default(cls) -> ExecutionInfo: 39 """Creates a new "empty" instance of the ExecutionInfo class with the default values.""" 40 return cls.create_new()
Creates a new "empty" instance of the ExecutionInfo class with the default values.
42 @classmethod 43 def create_new( 44 cls, 45 ) -> ExecutionInfo: 46 """ 47 Creates a new empty instance of state variables with the provided executor configuration. 48 49 """ 50 request_heap = RequestForest() 51 node_heap = NodeForest() 52 stamper = StampManager() 53 54 return ExecutionInfo( 55 request_forest=request_heap, 56 node_forest=node_heap, 57 stamper=stamper, 58 )
Creates a new empty instance of state variables with the provided executor configuration.
60 @property 61 def answer(self): 62 """Convenience method to access the answer of the run.""" 63 return self.request_forest.answer
Convenience method to access the answer of the run.
65 @property 66 def all_stamps(self) -> List[Stamp]: 67 """Convenience method to access all the stamps of the run.""" 68 return self.stamper.all_stamps
Convenience method to access all the stamps of the run.
70 @property 71 def name(self): 72 """ 73 Gets the name of the graph by pulling the name of the insertion request. It will raise a ValueError if the insertion 74 request is not present or there are multiple insertion requests. 75 """ 76 insertion_requests = self.insertion_requests 77 78 # The name is only defined for the length of 1. 79 # NOTE: Maybe we should send a warning once to user in other cases. 80 if len(insertion_requests) != 1: 81 return None 82 83 i_r = insertion_requests[0] 84 85 return self.node_forest.get_node_type(i_r.sink_id).name()
Gets the name of the graph by pulling the name of the insertion request. It will raise a ValueError if the insertion request is not present or there are multiple insertion requests.
87 @property 88 def insertion_requests(self): 89 """A convenience method to access all the insertion requests of the run.""" 90 return self.request_forest.insertion_request
A convenience method to access all the insertion requests of the run.
140 def graph_serialization(self) -> dict[str, Any]: 141 """ 142 Creates a string (JSON) representation of this info object designed to be used to construct a graph for this 143 info object. 144 145 Some important notes about its structure are outlined below: 146 - The `nodes` key contains a list of all the nodes in the graph, represented as `Vertex` objects. 147 - The `edges` key contains a list of all the edges in the graph, represented as `Edge` objects. 148 - The `stamps` key contains an ease of use list of all the stamps associated with the run, represented as `Stamp` objects. 149 150 - The "nodes" and "requests" key will be outlined with normal graph details like connections and identifiers in addition to a loose details object. 151 - However, both will carry an addition param called "stamp" which is a timestamp style object. 152 - They also will carry a "parent" param which is a recursive structure that allows you to traverse the graph in time. 153 154 155 ``` 156 """ 157 parent_nodes = [x.identifier for x in self.insertion_requests] 158 159 infos = [self._get_info(parent_node) for parent_node in parent_nodes] 160 161 runs = [] 162 163 for info, parent_node_id in zip(infos, parent_nodes): 164 insertion_requests = info.request_forest.insertion_request 165 166 assert len(insertion_requests) == 1 167 parent_request = insertion_requests[0] 168 169 all_parents = parent_request.get_all_parents() 170 171 start_time = all_parents[-1].stamp.time 172 173 assert len([x for x in all_parents if x.status == "Completed"]) <= 1 174 end_time = None 175 for req in all_parents: 176 if req.status in ["Completed", "Failed"]: 177 end_time = req.stamp.time 178 break 179 180 entry = { 181 "name": info.name, 182 "run_id": parent_node_id, 183 "nodes": info.node_forest.to_vertices(), 184 "status": parent_request.status, 185 "edges": info.request_forest.to_edges(), 186 "steps": _get_stamps_from_forests( 187 info.node_forest, info.request_forest 188 ), 189 "start_time": start_time, 190 "end_time": end_time, 191 } 192 runs.append(entry) 193 194 return json.loads( 195 json.dumps( 196 runs, 197 cls=RTJSONEncoder, 198 ) 199 )
Creates a string (JSON) representation of this info object designed to be used to construct a graph for this info object.
Some important notes about its structure are outlined below:
- The `nodes` key contains a list of all the nodes in the graph, represented as `Vertex` objects.
- The `edges` key contains a list of all the edges in the graph, represented as `Edge` objects.
- The `stamps` key contains an ease of use list of all the stamps associated with the run, represented as `Stamp` objects.
- The "nodes" and "requests" key will be outlined with normal graph details like connections and identifiers in addition to a loose details object.
- However, both will carry an addition param called "stamp" which is a timestamp style object.
- They also will carry a "parent" param which is a recursive structure that allows you to traverse the graph in time.
```
14class ExecutorConfig: 15 def __init__( 16 self, 17 *, 18 timeout: float | None = None, 19 end_on_error: bool = False, 20 broadcast_callback: ( 21 Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None 22 ) = None, 23 save_state: bool | None = None, 24 payload_callback: Callable[[dict[str, Any]], None] | None = None, 25 ): 26 """ 27 ExecutorConfig is special configuration object designed to allow customization of the executor in the RT system. 28 29 Args: 30 timeout (float | None): The maximum number of seconds to wait for a response to your top level request. Pass None (or omit) to disable the timeout entirely. 31 end_on_error (bool): If true, the executor will stop execution when an exception is encountered. 32 broadcast_callback (Callable or Coroutine): A function or coroutine that receives items published with `rt.broadcast`. 33 save_state (bool | None): Deprecated at the user-facing API layer (see Flow). `RAILTRACKS_DISABLE_EVENTS=True` skips the write regardless. Otherwise, explicit value wins; when unset, defaults to True (save). 34 """ 35 self.timeout = timeout 36 self.end_on_error = end_on_error 37 self.subscriber = broadcast_callback 38 # During test runs, disable save_state by default unless 39 # RAILTRACKS_ALLOW_PERSISTENCE is set (see `save_state` property). 40 self._user_save_state = save_state 41 42 self.payload_callback = payload_callback 43 44 # this is done because if we try to lock the save_state in init 45 # later when we want to allow a few tests to actually run persistance, they wont be able to do so 46 @property 47 def save_state(self) -> bool: 48 if os.getenv("RAILTRACKS_TEST_MODE") and not os.getenv( 49 "RAILTRACKS_ALLOW_PERSISTENCE" 50 ): 51 return False 52 if _disable_events(): 53 return False 54 return True if self._user_save_state is None else self._user_save_state 55 56 def precedence_overwritten( 57 self, 58 *, 59 timeout: float | None = None, 60 end_on_error: bool | None = None, 61 subscriber: ( 62 Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None 63 ) = None, 64 save_state: bool | None = None, 65 payload_callback: Callable[[dict[str, Any]], None] | None = None, 66 ): 67 """ 68 If any of the parameters are provided (not None), it will create a new update the current instance with the new values and return a deep copied reference to it. 69 """ 70 return ExecutorConfig( 71 timeout=timeout, 72 end_on_error=end_on_error 73 if end_on_error is not None 74 else self.end_on_error, 75 broadcast_callback=subscriber 76 if subscriber is not None 77 else self.subscriber, 78 save_state=save_state if save_state is not None else self._user_save_state, 79 payload_callback=payload_callback 80 if payload_callback is not None 81 else self.payload_callback, 82 ) 83 84 def __repr__(self): 85 return ( 86 f"ExecutorConfig(timeout={self.timeout}, end_on_error={self.end_on_error}, " 87 f"save_state={self._user_save_state}, payload_callback={self.payload_callback})" 88 )
15 def __init__( 16 self, 17 *, 18 timeout: float | None = None, 19 end_on_error: bool = False, 20 broadcast_callback: ( 21 Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None 22 ) = None, 23 save_state: bool | None = None, 24 payload_callback: Callable[[dict[str, Any]], None] | None = None, 25 ): 26 """ 27 ExecutorConfig is special configuration object designed to allow customization of the executor in the RT system. 28 29 Args: 30 timeout (float | None): The maximum number of seconds to wait for a response to your top level request. Pass None (or omit) to disable the timeout entirely. 31 end_on_error (bool): If true, the executor will stop execution when an exception is encountered. 32 broadcast_callback (Callable or Coroutine): A function or coroutine that receives items published with `rt.broadcast`. 33 save_state (bool | None): Deprecated at the user-facing API layer (see Flow). `RAILTRACKS_DISABLE_EVENTS=True` skips the write regardless. Otherwise, explicit value wins; when unset, defaults to True (save). 34 """ 35 self.timeout = timeout 36 self.end_on_error = end_on_error 37 self.subscriber = broadcast_callback 38 # During test runs, disable save_state by default unless 39 # RAILTRACKS_ALLOW_PERSISTENCE is set (see `save_state` property). 40 self._user_save_state = save_state 41 42 self.payload_callback = payload_callback
ExecutorConfig is special configuration object designed to allow customization of the executor in the RT system.
Arguments:
- timeout (float | None): The maximum number of seconds to wait for a response to your top level request. Pass None (or omit) to disable the timeout entirely.
- end_on_error (bool): If true, the executor will stop execution when an exception is encountered.
- broadcast_callback (Callable or Coroutine): A function or coroutine that receives items published with
rt.broadcast. - save_state (bool | None): Deprecated at the user-facing API layer (see Flow).
RAILTRACKS_DISABLE_EVENTS=Trueskips the write regardless. Otherwise, explicit value wins; when unset, defaults to True (save).
56 def precedence_overwritten( 57 self, 58 *, 59 timeout: float | None = None, 60 end_on_error: bool | None = None, 61 subscriber: ( 62 Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None 63 ) = None, 64 save_state: bool | None = None, 65 payload_callback: Callable[[dict[str, Any]], None] | None = None, 66 ): 67 """ 68 If any of the parameters are provided (not None), it will create a new update the current instance with the new values and return a deep copied reference to it. 69 """ 70 return ExecutorConfig( 71 timeout=timeout, 72 end_on_error=end_on_error 73 if end_on_error is not None 74 else self.end_on_error, 75 broadcast_callback=subscriber 76 if subscriber is not None 77 else self.subscriber, 78 save_state=save_state if save_state is not None else self._user_save_state, 79 payload_callback=payload_callback 80 if payload_callback is not None 81 else self.payload_callback, 82 )
If any of the parameters are provided (not None), it will create a new update the current instance with the new values and return a deep copied reference to it.
521def set_config( 522 *, 523 timeout: float | None = None, 524 end_on_error: bool | None = None, 525 broadcast_callback: ( 526 Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None 527 ) = None, 528 save_state: bool | None = None, 529) -> None: 530 """ 531 Sets the global configuration for the executor. This will be propagated to all new runners created after this call. 532 533 - If you call this function after the runner has been created, it will not affect the current runner. 534 - This function will only overwrite the values that are provided, leaving the rest unchanged. 535 536 Args: 537 broadcast_callback: A passive listener for one-off events published with `rt.broadcast`. 538 """ 539 540 if is_context_active(): 541 warnings.warn( 542 "The executor config is being set after the runner has been created, this is not recommended" 543 ) 544 545 config = global_executor_config.get() 546 547 new_config = config.precedence_overwritten( 548 timeout=timeout, 549 end_on_error=end_on_error, 550 subscriber=broadcast_callback, 551 save_state=save_state, 552 ) 553 554 global_executor_config.set(new_config)
Sets the global configuration for the executor. This will be propagated to all new runners created after this call.
- If you call this function after the runner has been created, it will not affect the current runner.
- This function will only overwrite the values that are provided, leaving the rest unchanged.
Arguments:
- broadcast_callback: A passive listener for one-off events published with
rt.broadcast.
347def function_node( 348 func: Callable[_P, Coroutine[None, None, _TOutput]] 349 | Callable[_P, _TOutput] 350 | List[Callable[_P, Coroutine[None, None, _TOutput]] | Callable[_P, _TOutput]] 351 | None = None, 352 /, 353 *, 354 name: str | None = None, 355 manifest: ToolManifest | None = None, 356 middleware: Iterable[Middleware[_P, _TOutput]] | None = None, 357) -> ( 358 CallableAsyncRTFunction[_P, _TOutput] 359 | CallableSyncRTFunction[_P, _TOutput] 360 | List[CallableAsyncRTFunction[_P, _TOutput] | CallableSyncRTFunction[_P, _TOutput]] 361 | Callable[ 362 [Callable[_P, Coroutine[None, None, _TOutput]] | Callable[_P, _TOutput]], 363 RTFunction[_P, _TOutput], 364 ] 365 | None 366): 367 """ 368 Creates a new Node type from a function that can be used in `rt.call()`. 369 370 By default, it will parse the function's docstring and turn them into tool details and parameters. However, if 371 you provide custom ToolManifest it will override that logic. 372 373 Can be used three ways:: 374 375 # 1. direct call 376 node = rt.function_node(my_fn, middleware=[guard]) 377 378 # 2. bare decorator 379 @rt.function_node 380 def my_fn(...): ... 381 382 # 3. parametrized decorator (attach middleware / guardrails declaratively) 383 @rt.function_node(middleware=[guard], name="echo") 384 def my_fn(...): ... 385 386 WARNING: If you overriding tool parameters. It is on you to make sure they will work with your function. 387 388 NOTE: If you have already converted this function to a node this function will do nothing 389 390 Args: 391 func (Callable, optional): The function to convert into a Node. Omit it to use the 392 parametrized-decorator form, which returns a decorator that takes the function. 393 name (str, optional): Human-readable name for the node/tool. 394 manifest (ToolManifest, optional): The details you would like to override the tool with. 395 middleware (list[Middleware] | None): Middleware applied around the node boundary. 396 """ 397 398 # No function yet -> parametrized-decorator form: bind the options and return 399 # a decorator that finishes the job once the function is supplied. 400 if func is None: 401 402 def _decorator( 403 f: Callable[_P, Coroutine[None, None, _TOutput]] | Callable[_P, _TOutput], 404 ) -> ( 405 CallableAsyncRTFunction[_P, _TOutput] | CallableSyncRTFunction[_P, _TOutput] 406 ): 407 return function_node(f, name=name, manifest=manifest, middleware=middleware) 408 409 return _decorator 410 411 # handle the case where a list of functions is provided 412 if isinstance(func, list): 413 return [ 414 function_node(f, name=name, manifest=manifest, middleware=middleware) 415 for f in func 416 ] 417 else: 418 return _single_function_node( 419 func, name=name, manifest=manifest, middleware=middleware 420 )
Creates a new Node type from a function that can be used in rt.call().
By default, it will parse the function's docstring and turn them into tool details and parameters. However, if you provide custom ToolManifest it will override that logic.
Can be used three ways::
# 1. direct call
node = rt.function_node(my_fn, middleware=[guard])
# 2. bare decorator
@rt.function_node
def my_fn(...): ...
# 3. parametrized decorator (attach middleware / guardrails declaratively)
@rt.function_node(middleware=[guard], name="echo")
def my_fn(...): ...
WARNING: If you overriding tool parameters. It is on you to make sure they will work with your function.
NOTE: If you have already converted this function to a node this function will do nothing
Arguments:
- func (Callable, optional): The function to convert into a Node. Omit it to use the parametrized-decorator form, which returns a decorator that takes the function.
- name (str, optional): Human-readable name for the node/tool.
- manifest (ToolManifest, optional): The details you would like to override the tool with.
- middleware (list[Middleware] | None): Middleware applied around the node boundary.
141def agent_node( 142 name: str | None = None, 143 *, 144 tool_nodes: Iterable[Type[Node] | RTFunction] | None = None, 145 output_schema: Type[_TBaseModel] | None = None, 146 llm: ModelSource, 147 system_message: SystemMessage | str | None = None, 148 manifest: ToolManifest | None = None, 149 middleware: Iterable[Middleware[_P, StructuredResponse[_TBaseModel]]] 150 | Iterable[Middleware[_P, StringResponse]] 151 | None = None, 152 model_middleware: Iterable[ModelMiddleware] | None = None, 153 _shape: Callable[_P, object] = _user_input_shape, 154) -> type[Node[_P, StringResponse]] | type[Node[_P, StructuredResponse[_TBaseModel]]]: 155 """ 156 Dynamically creates an agent based on the provided parameters. 157 158 Args: 159 name (str | None): The name of the agent. If none the default will be used. 160 tool_nodes (Iterable[Type[Node] | RTFunction] | None): If your agent has access to tools, what does it have access to? 161 Cannot be combined with output_schema -- see below. 162 output_schema (Type[_TBaseModel] | None): If your agent should return a structured output, what is the output_schema? 163 Cannot be combined with tool_nodes: providing both raises NodeCreationError, since the model does not 164 reliably call tools when a structured output_schema is also requested (it may fabricate a plausible 165 tool result instead of actually invoking the tool). 166 llm (ModelBase | Callable[[], ModelBase]): The LLM model to use, or a no-arg 167 factory resolved fresh on every model call (lets the agent pick its model 168 at invocation time, e.g. from config or rt.context). 169 system_message (SystemMessage | str | None): System message for the agent. 170 manifest (ToolManifest | None): How this agent appears when other agents use it as a tool. If None, 171 the description is built from the agent's name and system_message, and the agent takes a single 172 string parameter, `request`. A manifest without parameters also takes `request`. A manifest with 173 a blank description raises NodeCreationError. 174 middleware (list[Middleware] | None): Middleware applied around the agent's node boundary 175 (user_input -> Response). 176 model_middleware (list[Middleware] | None): Middleware applied around each raw model call 177 (messages/schema/tools -> Response), inside the tool-calling loop. 178 _shape (Callable[_P, object]): Internal use only. Used to infer the ParamSpec for the agent's input shape. 179 180 NOTE: Supplying a parameter `_shape` will break typing and you will be responsible for it. DO NOT USE THIS!! 181 """ 182 _check_no_combined_tools_and_schema(tool_nodes, output_schema) 183 184 unpacked_tool_nodes = _unpack_tool_nodes(tool_nodes) 185 186 if manifest is not None: 187 tool_details = manifest.description 188 tool_params = manifest.parameters 189 else: 190 tool_details = None 191 tool_params = None 192 193 return _build_dynamic_agent( 194 unpacked_tool_nodes=unpacked_tool_nodes, 195 output_schema=output_schema, 196 name=name, 197 llm=llm, 198 system_message=system_message, 199 tool_details=tool_details, 200 tool_params=tool_params, 201 middleware=middleware, 202 model_middleware=model_middleware, 203 )
Dynamically creates an agent based on the provided parameters.
Arguments:
- name (str | None): The name of the agent. If none the default will be used.
- tool_nodes (Iterable[Type[Node] | RTFunction] | None): If your agent has access to tools, what does it have access to? Cannot be combined with output_schema -- see below.
- output_schema (Type[_TBaseModel] | None): If your agent should return a structured output, what is the output_schema? Cannot be combined with tool_nodes: providing both raises NodeCreationError, since the model does not reliably call tools when a structured output_schema is also requested (it may fabricate a plausible tool result instead of actually invoking the tool).
- llm (ModelBase | Callable[[], ModelBase]): The LLM model to use, or a no-arg factory resolved fresh on every model call (lets the agent pick its model at invocation time, e.g. from config or rt.context).
- system_message (SystemMessage | str | None): System message for the agent.
- manifest (ToolManifest | None): How this agent appears when other agents use it as a tool. If None,
the description is built from the agent's name and system_message, and the agent takes a single
string parameter,
request. A manifest without parameters also takesrequest. A manifest with a blank description raises NodeCreationError. - middleware (list[Middleware] | None): Middleware applied around the agent's node boundary (user_input -> Response).
- model_middleware (list[Middleware] | None): Middleware applied around each raw model call (messages/schema/tools -> Response), inside the tool-calling loop.
- _shape (Callable[_P, object]): Internal use only. Used to infer the ParamSpec for the agent's input shape.
NOTE: Supplying a parameter _shape will break typing and you will be responsible for it. DO NOT USE THIS!!
27def decision_node( 28 name: str | None = None, 29 *, 30 model: DecisionModel, 31 schema: DecisionSchema, 32 description: str | None = None, 33 middleware: Iterable[Middleware[_P, DecisionResponse]] | None = None, 34 _shape: Callable[_P, object] = _state_shape, 35) -> type[Node[_P, DecisionResponse]]: 36 """Create a node that answers ``schema``'s questions about a state with ``model``. 37 38 The System One counterpart of `agent_node`. The node is a Tool: use it as a Flow's 39 entry point, with `rt.call`/`rt.call_batch`, or in an agent's ``tool_nodes``, where 40 the agent reads the response's compact ``str()``. 41 42 Args: 43 name (str | None): The node and tool name. Defaults to "Decision". 44 model (DecisionModel): The decision model, e.g. `rt.decisions.TypeSafeDecisions`, 45 `rt.decisions.OpenRouterDecisions` or `rt.decisions.OpenAIDecisions`. 46 schema (DecisionSchema): The questions to answer, as a `DecisionSchema`; 47 every model answers any schema. 48 description (str | None): The tool description an agent sees. Defaults to a 49 sentence listing each question's instructions. 50 middleware (Iterable[Middleware] | None): Node middleware (`wrap_node`, 51 `post_node`) applied around the node boundary (state -> DecisionResponse). 52 Model-only middleware (`pre_llm`, `post_llm`, `wrap_llm`, LLM guardrails, 53 `ContextInjection`) is rejected; any other `Middleware`, including 54 slot-agnostic ones such as `Retry`, is taken as node middleware. 55 _shape (Callable[_P, object]): Internal use only. Used to infer the ParamSpec for 56 the node's input shape. 57 58 Raises: 59 NodeCreationError: If the name is blank, the model is not a `DecisionModel`, 60 the schema is not a `DecisionSchema`, or ``middleware`` holds model-only 61 middleware. 62 """ 63 middleware = list(middleware) if middleware is not None else None 64 _validate(name, model, schema, middleware) 65 node_name = name if name is not None else "Decision" 66 detail = description if description is not None else _default_detail(schema) 67 68 # `str` so TypeMapper coerces an agent's tool argument; Python callers may pass JSON 69 async def invoke(state: str) -> DecisionResponse: 70 return await invoke_decision(model, state, schema) 71 72 tool = Tool( 73 name=node_name.replace(" ", "_"), 74 detail=detail, 75 parameters=[ 76 Parameter(name="state", description=STATE_DESCRIPTION, param_type="string") 77 ], 78 ) 79 builder = FunctionNodeBuilder.function( 80 invoke, 81 class_name="".join(node_name.split()), 82 name=node_name, 83 tool_info=tool, 84 middleware=cast( 85 Iterable[Middleware[[str], DecisionResponse]] | None, 86 middleware, 87 ), 88 ) 89 return cast(type[Node[_P, DecisionResponse]], builder.build())
Create a node that answers schema's questions about a state with model.
The System One counterpart of agent_node. The node is a Tool: use it as a Flow's
entry point, with rt.call/rt.call_batch, or in an agent's tool_nodes, where
the agent reads the response's compact str().
Arguments:
- name (str | None): The node and tool name. Defaults to "Decision".
- model (DecisionModel): The decision model, e.g.
rt.decisions.TypeSafeDecisions,rt.decisions.OpenRouterDecisionsorrt.decisions.OpenAIDecisions. - schema (DecisionSchema): The questions to answer, as a
DecisionSchema; every model answers any schema. - description (str | None): The tool description an agent sees. Defaults to a sentence listing each question's instructions.
- middleware (Iterable[Middleware] | None): Node middleware (
wrap_node,post_node) applied around the node boundary (state -> DecisionResponse). Model-only middleware (pre_llm,post_llm,wrap_llm, LLM guardrails,ContextInjection) is rejected; any otherMiddleware, including slot-agnostic ones such asRetry, is taken as node middleware. - _shape (Callable[_P, object]): Internal use only. Used to infer the ParamSpec for the node's input shape.
Raises:
- NodeCreationError: If the name is blank, the model is not a
DecisionModel, the schema is not aDecisionSchema, ormiddlewareholds model-only middleware.
25class MCPStdioParams(StdioServerParameters): 26 """ 27 Configuration parameters for STDIO-based MCP server connections. 28 29 Extends the standard StdioServerParameters with a timeout field. 30 31 Attributes: 32 timeout: Maximum time to wait for operations (default: 30 seconds) 33 """ 34 35 timeout: timedelta = timedelta(seconds=30) 36 37 def as_stdio_params(self) -> StdioServerParameters: 38 """ 39 Convert to standard StdioServerParameters, excluding the timeout field. 40 41 Returns: 42 StdioServerParameters without the timeout attribute 43 """ 44 stdio_kwargs = self.dict(exclude={"timeout"}) 45 return StdioServerParameters(**stdio_kwargs)
Configuration parameters for STDIO-based MCP server connections.
Extends the standard StdioServerParameters with a timeout field.
Attributes:
- timeout: Maximum time to wait for operations (default: 30 seconds)
37 def as_stdio_params(self) -> StdioServerParameters: 38 """ 39 Convert to standard StdioServerParameters, excluding the timeout field. 40 41 Returns: 42 StdioServerParameters without the timeout attribute 43 """ 44 stdio_kwargs = self.dict(exclude={"timeout"}) 45 return StdioServerParameters(**stdio_kwargs)
Convert to standard StdioServerParameters, excluding the timeout field.
Returns:
StdioServerParameters without the timeout attribute
48class MCPHttpParams(BaseModel): 49 """ 50 Configuration parameters for HTTP-based MCP server connections. 51 52 Supports both SSE (Server-Sent Events) and streamable HTTP transports. 53 The transport type is automatically determined based on the URL. 54 55 Attributes: 56 url: The MCP server URL (use /sse suffix for SSE transport) 57 headers: Optional HTTP headers for authentication 58 timeout: Connection timeout (default: 30 seconds) 59 sse_read_timeout: SSE read timeout (default: 5 minutes) 60 terminate_on_close: Whether to terminate connection on close (default: True) 61 auth: Optional HTTPX authentication handler 62 """ 63 64 model_config = {"arbitrary_types_allowed": True} 65 66 url: str 67 headers: dict[str, Any] | None = None 68 timeout: timedelta = timedelta(seconds=30) 69 sse_read_timeout: timedelta = timedelta(seconds=60 * 5) 70 terminate_on_close: bool = True 71 auth: httpx.Auth | None = None
Configuration parameters for HTTP-based MCP server connections.
Supports both SSE (Server-Sent Events) and streamable HTTP transports. The transport type is automatically determined based on the URL.
Attributes:
- url: The MCP server URL (use /sse suffix for SSE transport)
- headers: Optional HTTP headers for authentication
- timeout: Connection timeout (default: 30 seconds)
- sse_read_timeout: SSE read timeout (default: 5 minutes)
- terminate_on_close: Whether to terminate connection on close (default: True)
- auth: Optional HTTPX authentication handler
8def connect_mcp( 9 config: MCPStdioParams | MCPHttpParams, 10 client_session: ClientSession | None = None, 11 setup_timeout: float = 30, 12) -> MCPServer: 13 """ 14 Connect to an MCP server and return a server instance with available tools. 15 16 This is the primary entry point for using MCP servers in Railtracks. 17 The server will connect in the background, discover available tools, 18 and convert them to Railtracks Node classes. 19 20 The connection remains active until explicitly closed or the context exits. 21 22 Usage Examples: 23 # STDIO connection (local MCP server) 24 config = rt.MCPStdioParams( 25 command="uvx", 26 args=["mcp-server-time"] 27 ) 28 server = rt.connect_mcp(config) 29 30 # HTTP connection (remote MCP server) 31 config = rt.MCPHttpParams( 32 url="https://mcp.example.com/sse", 33 headers={"Authorization": "Bearer token"} 34 ) 35 server = rt.connect_mcp(config) 36 37 # Context manager (recommended) 38 with rt.connect_mcp(config) as server: 39 tools = server.tools 40 # Use tools... 41 # Automatically closed 42 43 # Access tools 44 for tool in server.tools: 45 print(f"Tool: {tool.name()}") 46 print(f"Description: {tool.tool_info().detail}") 47 48 Args: 49 config: Server configuration: 50 - MCPStdioParams: For local servers via stdin/stdout 51 - MCPHttpParams: For remote servers via HTTP/SSE 52 client_session: Optional pre-configured ClientSession for advanced use cases. 53 If not provided, a new session will be created automatically. 54 setup_timeout: Maximum seconds to wait for connection (default: 30). 55 Increase for slow servers or complex authentication flows. 56 57 Returns: 58 MCPServer: Connected server instance with: 59 - tools: List of Node classes representing MCP tools 60 - close(): Method to explicitly close the connection 61 - Context manager support for automatic cleanup 62 63 Raises: 64 FileNotFoundError: If STDIO command not found. Verify the command is: 65 - Installed and in your PATH 66 - Spelled correctly (check for typos) 67 - Executable (check permissions on Unix) 68 ConnectionError: If connection to server fails. Check: 69 - Server URL is correct and accessible 70 - Network connectivity and firewall settings 71 - Authentication credentials are valid 72 - Server is running and accepting connections 73 TimeoutError: If connection exceeds setup_timeout. Try: 74 - Increasing setup_timeout parameter 75 - Checking server performance/load 76 - Verifying server is responding 77 RuntimeError: For other setup failures (e.g., protocol errors, config issues) 78 79 Note: 80 - The connection runs in a background thread for sync/async bridging 81 - Tools are cached after first retrieval for performance 82 - Always close() the server when done or use context manager 83 - Jupyter compatibility patches are applied automatically 84 """ 85 # Apply Jupyter compatibility patches if needed 86 apply_patches() 87 88 return MCPServer( 89 config=config, client_session=client_session, setup_timeout=setup_timeout 90 )
Connect to an MCP server and return a server instance with available tools.
This is the primary entry point for using MCP servers in Railtracks. The server will connect in the background, discover available tools, and convert them to Railtracks Node classes.
The connection remains active until explicitly closed or the context exits.
Usage Examples:
STDIO connection (local MCP server)
config = rt.MCPStdioParams( command="uvx", args=["mcp-server-time"] ) server = rt.connect_mcp(config)
HTTP connection (remote MCP server)
config = rt.MCPHttpParams( url="https://mcp.example.com/sse", headers={"Authorization": "Bearer token"} ) server = rt.connect_mcp(config)
Context manager (recommended)
with rt.connect_mcp(config) as server: tools = server.tools # Use tools...
Automatically closed
Access tools
for tool in server.tools: print(f"Tool: {tool.name()}") print(f"Description: {tool.tool_info().detail}")
Arguments:
- config: Server configuration:
- MCPStdioParams: For local servers via stdin/stdout
- MCPHttpParams: For remote servers via HTTP/SSE
- client_session: Optional pre-configured ClientSession for advanced use cases. If not provided, a new session will be created automatically.
- setup_timeout: Maximum seconds to wait for connection (default: 30). Increase for slow servers or complex authentication flows.
Returns:
MCPServer: Connected server instance with: - tools: List of Node classes representing MCP tools - close(): Method to explicitly close the connection - Context manager support for automatic cleanup
Raises:
- FileNotFoundError: If STDIO command not found. Verify the command is:
- Installed and in your PATH
- Spelled correctly (check for typos)
- Executable (check permissions on Unix)
- ConnectionError: If connection to server fails. Check:
- Server URL is correct and accessible
- Network connectivity and firewall settings
- Authentication credentials are valid
- Server is running and accepting connections
- TimeoutError: If connection exceeds setup_timeout. Try:
- Increasing setup_timeout parameter
- Checking server performance/load
- Verifying server is responding
- RuntimeError: For other setup failures (e.g., protocol errors, config issues)
Note:
- The connection runs in a background thread for sync/async bridging
- Tools are cached after first retrieval for performance
- Always close() the server when done or use context manager
- Jupyter compatibility patches are applied automatically
89def create_mcp_server( 90 nodes: List[Node | RTFunction], 91 server_name: str = "MCP Server", 92 fastmcp: FastMCP | None = None, 93): 94 """ 95 Create a FastMCP server that can be used to run nodes as MCP tools. 96 97 Args: 98 nodes: List of Node classes to be registered as tools with the MCP server. 99 server_name: Name of the MCP server instance. 100 fastmcp: Optional FastMCP instance to use instead of creating a new one. 101 102 Returns: 103 A FastMCP server instance. 104 """ 105 if fastmcp is not None: 106 if not isinstance(fastmcp, FastMCP): 107 raise ValueError("Provided fastmcp must be an instance of FastMCP.") 108 mcp = fastmcp 109 else: 110 mcp = FastMCP(server_name) 111 112 for node in [n if not hasattr(n, "node_type") else n.node_type for n in nodes]: 113 node_info = node.tool_info() 114 func = _create_tool_function(node, node_info) 115 116 mcp._tool_manager._tools[node_info.name] = MCPTool( 117 fn=func, 118 name=node_info.name, 119 description=node_info.detail, 120 parameters=( 121 _parameters_to_json_schema(node_info.parameters) 122 if node_info.parameters is not None 123 else {} 124 ), 125 fn_metadata=func_metadata(func, []), 126 is_async=True, 127 context_kwarg=None, 128 annotations=None, 129 ) # Register the node as a tool 130 131 return mcp
Create a FastMCP server that can be used to run nodes as MCP tools.
Arguments:
- nodes: List of Node classes to be registered as tools with the MCP server.
- server_name: Name of the MCP server instance.
- fastmcp: Optional FastMCP instance to use instead of creating a new one.
Returns:
A FastMCP server instance.
7class ToolManifest: 8 """ 9 Creates a manifest for a tool, which includes its description and parameters. 10 11 Args: 12 description (str): A description of the tool. 13 parameters (Iterable[Parameter] | None): An iterable of parameters for the tool. If None, there are no paramerters. 14 """ 15 16 def __init__( 17 self, 18 description: str, 19 parameters: Iterable[Parameter] | None = None, 20 ): 21 self.description = description 22 self.parameters: List[Parameter] = ( 23 list(parameters) if parameters is not None else [] 24 )
Creates a manifest for a tool, which includes its description and parameters.
Arguments:
- description (str): A description of the tool.
- parameters (Iterable[Parameter] | None): An iterable of parameters for the tool. If None, there are no paramerters.
604def session_id() -> str | None: 605 """ 606 Gets the current session ID if it exists, otherwise returns None. 607 """ 608 try: 609 return get_session_id() 610 except ContextError: 611 return None
Gets the current session ID if it exists, otherwise returns None.
19class Flow(Generic[_P, _TOutput]): 20 """A reusable, configured entry point for running an agent graph. 21 22 Binds an entry-point node to a fixed set of runtime options so the same 23 configuration can be invoked repeatedly. Each invocation is fully isolated. 24 25 Typical usage:: 26 27 flow = Flow("my-agent", entry_point=my_node, context={"user": "alice"}) 28 result = await flow.ainvoke(query) # async (preferred) 29 result = flow.invoke(query) # sync 30 31 Args: 32 name (str): A unique name for the flow. This is used for logging and state management. 33 entry_point (Callable | RTSyncFunction | RTAsyncFunction): The starting point of your flow. 34 context (dict[str, Any], optional): Context to be passed to all instantiations (or runs) of this flow. Note that the context can be overridden at invocation time. 35 timeout (float, optional): The maximum number of seconds to wait for a response to your top-level request. 36 end_on_error (bool, optional): If True, the execution will stop when an exception is encountered. 37 broadcast_callback (Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None, optional): A passive listener for one-off events published with `rt.broadcast`. 38 save_state (bool, optional): If True, the state of the execution will be saved to a file at the end of the run in the `.railtracks/data/sessions/` directory. This argument emits a DeprecationWarning. 39 Default: True. Set `RAILTRACKS_DISABLE_EVENTS=True` to skip saving state regardless of this argument. If both are set, the environment variable takes precedence. 40 payload_callback (Callable[[dict[str, Any]], None], optional): A callback function that will run upon completion of the flow with the final payload as an argument. 41 """ 42 43 def __init__( 44 self, 45 name: str, 46 entry_point: (type[Node[_P, _TOutput]] | RTFunction[_P, _TOutput]), 47 *, 48 context: dict[str, Any] | None = None, 49 timeout: float | None = None, 50 end_on_error: bool | None = None, 51 broadcast_callback: ( 52 Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None 53 ) = None, 54 save_state: bool | None = None, 55 payload_callback: Callable[[dict[str, Any]], Any] | None = None, 56 ) -> None: 57 self.entry_point: type[Node[_P, _TOutput]] 58 59 if hasattr(entry_point, "node_type"): 60 self.entry_point = entry_point.node_type 61 else: 62 self.entry_point = entry_point 63 64 if save_state is not None: 65 warnings.warn( 66 "The save_state parameter is being deprecated. Use the " 67 "RAILTRACKS_DISABLE_EVENTS env var instead", 68 DeprecationWarning, 69 stacklevel=2, 70 ) 71 72 self.name = name 73 self._context: dict[str, Any] = context or {} 74 self._timeout = timeout 75 self._end_on_error = end_on_error 76 self._broadcast_callback = broadcast_callback 77 self._save_state = save_state 78 self._payload_callback = payload_callback 79 80 def update_context(self, context: dict[str, Any]) -> Flow[_P, _TOutput]: 81 """Return a new Flow with additional context values merged in. 82 83 The original flow is not modified. Values in ``context`` override 84 any existing keys; keys not present in ``context`` are preserved. 85 86 Args: 87 context: Entries to add or override in the flow's context. 88 89 Returns: 90 A new :class:`Flow` instance with the merged context. 91 """ 92 new_obj = copy.copy(self) 93 new_obj._context = {**self._context, **context} 94 return new_obj 95 96 def connect(self) -> FlowConnection[_P, _TOutput]: 97 """ 98 Opens a connection to this flow. 99 100 A `FlowConnection` invokes the flow exactly as `invoke`/`ainvoke` do, and 101 additionally keeps the run's context reachable. 102 103 conn = flow.connect() 104 result = await conn.ainvoke("text") # not flow.ainvoke if context is desired 105 106 Returns: 107 FlowConnection: A connection to current flow. 108 """ 109 return FlowConnection(self) 110 111 async def ainvoke(self, *args: _P.args, **kwargs: _P.kwargs) -> _TOutput: 112 return await self.connect().ainvoke(*args, **kwargs) 113 114 def invoke(self, *args: _P.args, **kwargs: _P.kwargs) -> _TOutput: 115 return self.connect().invoke(*args, **kwargs) 116 117 def equality_hash(self) -> str: 118 """Return a stable hash that identifies this flow's configuration. 119 120 Two flows with the same name produce the same hash regardless of 121 other parameters (timeout, context, etc.). 122 """ 123 config_string = json.dumps(self._get_hash_content(), sort_keys=True) 124 return hashlib.sha256(config_string.encode()).hexdigest() 125 126 def _get_hash_content(self) -> dict: 127 return { 128 "name": self.name, 129 }
A reusable, configured entry point for running an agent graph.
Binds an entry-point node to a fixed set of runtime options so the same configuration can be invoked repeatedly. Each invocation is fully isolated.
Typical usage::
flow = Flow("my-agent", entry_point=my_node, context={"user": "alice"})
result = await flow.ainvoke(query) # async (preferred)
result = flow.invoke(query) # sync
Arguments:
- name (str): A unique name for the flow. This is used for logging and state management.
- entry_point (Callable | RTSyncFunction | RTAsyncFunction): The starting point of your flow.
- context (dict[str, Any], optional): Context to be passed to all instantiations (or runs) of this flow. Note that the context can be overridden at invocation time.
- timeout (float, optional): The maximum number of seconds to wait for a response to your top-level request.
- end_on_error (bool, optional): If True, the execution will stop when an exception is encountered.
- broadcast_callback (Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None, optional): A passive listener for one-off events published with
rt.broadcast. - save_state (bool, optional): If True, the state of the execution will be saved to a file at the end of the run in the
.railtracks/data/sessions/directory. This argument emits a DeprecationWarning. Default: True. SetRAILTRACKS_DISABLE_EVENTS=Trueto skip saving state regardless of this argument. If both are set, the environment variable takes precedence. - payload_callback (Callable[[dict[str, Any]], None], optional): A callback function that will run upon completion of the flow with the final payload as an argument.
43 def __init__( 44 self, 45 name: str, 46 entry_point: (type[Node[_P, _TOutput]] | RTFunction[_P, _TOutput]), 47 *, 48 context: dict[str, Any] | None = None, 49 timeout: float | None = None, 50 end_on_error: bool | None = None, 51 broadcast_callback: ( 52 Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None 53 ) = None, 54 save_state: bool | None = None, 55 payload_callback: Callable[[dict[str, Any]], Any] | None = None, 56 ) -> None: 57 self.entry_point: type[Node[_P, _TOutput]] 58 59 if hasattr(entry_point, "node_type"): 60 self.entry_point = entry_point.node_type 61 else: 62 self.entry_point = entry_point 63 64 if save_state is not None: 65 warnings.warn( 66 "The save_state parameter is being deprecated. Use the " 67 "RAILTRACKS_DISABLE_EVENTS env var instead", 68 DeprecationWarning, 69 stacklevel=2, 70 ) 71 72 self.name = name 73 self._context: dict[str, Any] = context or {} 74 self._timeout = timeout 75 self._end_on_error = end_on_error 76 self._broadcast_callback = broadcast_callback 77 self._save_state = save_state 78 self._payload_callback = payload_callback
80 def update_context(self, context: dict[str, Any]) -> Flow[_P, _TOutput]: 81 """Return a new Flow with additional context values merged in. 82 83 The original flow is not modified. Values in ``context`` override 84 any existing keys; keys not present in ``context`` are preserved. 85 86 Args: 87 context: Entries to add or override in the flow's context. 88 89 Returns: 90 A new :class:`Flow` instance with the merged context. 91 """ 92 new_obj = copy.copy(self) 93 new_obj._context = {**self._context, **context} 94 return new_obj
Return a new Flow with additional context values merged in.
The original flow is not modified. Values in context override
any existing keys; keys not present in context are preserved.
Arguments:
- context: Entries to add or override in the flow's context.
Returns:
A new
Flowinstance with the merged context.
96 def connect(self) -> FlowConnection[_P, _TOutput]: 97 """ 98 Opens a connection to this flow. 99 100 A `FlowConnection` invokes the flow exactly as `invoke`/`ainvoke` do, and 101 additionally keeps the run's context reachable. 102 103 conn = flow.connect() 104 result = await conn.ainvoke("text") # not flow.ainvoke if context is desired 105 106 Returns: 107 FlowConnection: A connection to current flow. 108 """ 109 return FlowConnection(self)
Opens a connection to this flow.
A FlowConnection invokes the flow exactly as invoke/ainvoke do, and
additionally keeps the run's context reachable.
conn = flow.connect()
result = await conn.ainvoke("text") # not flow.ainvoke if context is desired
Returns:
FlowConnection: A connection to current flow.
117 def equality_hash(self) -> str: 118 """Return a stable hash that identifies this flow's configuration. 119 120 Two flows with the same name produce the same hash regardless of 121 other parameters (timeout, context, etc.). 122 """ 123 config_string = json.dumps(self._get_hash_content(), sort_keys=True) 124 return hashlib.sha256(config_string.encode()).hexdigest()
Return a stable hash that identifies this flow's configuration.
Two flows with the same name produce the same hash regardless of other parameters (timeout, context, etc.).
44class FlowConnection(Generic[_P, _TOutput]): 45 """ 46 A connection to a flow, through which it can be invoked. 47 48 Same invoke and behaviour as `Flow` object. 49 """ 50 51 def __init__(self, flow: Flow[_P, _TOutput]) -> None: 52 self._flow = flow 53 self._session: Session | None = None 54 self._in_flight = False 55 56 async def ainvoke(self, *args: _P.args, **kwargs: _P.kwargs) -> _TOutput: 57 """ 58 Runs the flow, leaving its context reachable on this connection. 59 60 Raises: 61 RuntimeError: If this connection is already running an invocation. 62 """ 63 if self._in_flight: 64 raise RuntimeError( 65 "This connection is already running an invocation. A connection " 66 "handles one at a time\n use a separate `flow.connect()`" 67 ) 68 69 flow = self._flow 70 self._in_flight = True 71 try: 72 with Session( 73 context=dict(flow._context), 74 flow_name=flow.name, 75 flow_id=flow.equality_hash(), 76 name=None, 77 timeout=flow._timeout, 78 end_on_error=flow._end_on_error, 79 broadcast_callback=flow._broadcast_callback, 80 save_state=flow._save_state, 81 payload_callback=flow._payload_callback, 82 ) as session: 83 # bound before the entry point runs, so the context of a failed 84 # invocation is still reachable afterwards 85 self._session = session 86 return await call(flow.entry_point, *args, **kwargs) 87 finally: 88 self._in_flight = False 89 90 def invoke(self, *args: _P.args, **kwargs: _P.kwargs) -> _TOutput: 91 """ 92 Synchronous `ainvoke`. 93 94 Note: 95 When no event loop is running, blocks until the flow finishes. 96 When called from inside a running event loop (e.g. a notebook or 97 async framework), the run is dispatched to a worker thread with its 98 own event loop; `contextvars.copy_context()` keeps Session and 99 logging context visible there. 100 """ 101 try: 102 asyncio.get_running_loop() 103 except RuntimeError: 104 return asyncio.run(self.ainvoke(*args, **kwargs)) 105 106 ctx = contextvars.copy_context() 107 with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool: 108 future = pool.submit(ctx.run, asyncio.run, self.ainvoke(*args, **kwargs)) 109 return future.result() 110 111 @property 112 def connected(self) -> bool: 113 """Whether this connection has begun an invocation yet.""" 114 return self._session is not None 115 116 def _require_session(self) -> Session: 117 if self._session is None: 118 raise RuntimeError( 119 "Nothing has run on this connection yet, so it has no context to read.\n" 120 "\n" 121 "Ensure FlowConnection is invoked instead of base Flow instance:\n" 122 "\n" 123 " conn = flow.connect()\n" 124 ' result = await conn.ainvoke("text") # NOT flow.ainvoke if context is desired\n' 125 ' conn.context.get("progress")\n' 126 ) 127 return self._session 128 129 @property 130 def context(self) -> MutableExternalContext: 131 """ 132 The context of the most recent invocation. 133 134 A live reference, not a copy. Context is not intended to be modified. 135 136 """ 137 return self._require_session().context 138 139 @property 140 def session_id(self) -> str: 141 """Identifier of the session backing the most recent invocation.""" 142 return self._require_session().identifier 143 144 @property 145 def session(self) -> Session: 146 """ 147 The session backing the most recent invocation, for inspection. 148 149 Already closed; the connection owns its lifecycle. `Session.payload()` 150 and `Session.info` expose the run's state representation. 151 """ 152 return self._require_session() 153 154 def message_histories(self) -> List[NodeMessageHistory]: 155 """ 156 Every model conversation from the most recent invocation, in the order the 157 runs were recorded. Concurrently called nodes have no guaranteed order. 158 159 Covers nested agents, unlike an `LLMResponse`, which carries only its 160 own. Nodes that made no model calls are omitted. 161 162 Walks the run's requests on every call rather than caching, so hold the 163 result if you need it more than once. 164 165 for h in conn.message_histories(): 166 print(h.node_name, len(h.message_history)) 167 168 Returns: 169 List[NodeMessageHistory]: One entry per node that called a model. 170 """ 171 info = self._require_session().info 172 node_forest = info.node_forest 173 174 histories: List[NodeMessageHistory] = [] 175 # a request is inserted into the heap when it is opened 176 for request in info.request_forest.heap().values(): 177 history = getattr(request.output, "message_history", None) 178 if history is None: 179 continue 180 node_type = node_forest.get_node_type(request.sink_id) 181 histories.append( 182 NodeMessageHistory( 183 node_name=node_type.name() 184 if node_type is not None 185 else "<unknown>", 186 node_id=request.sink_id, 187 request_id=request.identifier, 188 message_history=history, 189 ) 190 ) 191 192 return histories 193 194 def __repr__(self) -> str: 195 if self._session is None: 196 return f"FlowConnection(flow={self._flow.name!r}, not yet invoked)" 197 return ( 198 f"FlowConnection(flow={self._flow.name!r}, session_id={self.session_id!r})" 199 )
A connection to a flow, through which it can be invoked.
Same invoke and behaviour as Flow object.
56 async def ainvoke(self, *args: _P.args, **kwargs: _P.kwargs) -> _TOutput: 57 """ 58 Runs the flow, leaving its context reachable on this connection. 59 60 Raises: 61 RuntimeError: If this connection is already running an invocation. 62 """ 63 if self._in_flight: 64 raise RuntimeError( 65 "This connection is already running an invocation. A connection " 66 "handles one at a time\n use a separate `flow.connect()`" 67 ) 68 69 flow = self._flow 70 self._in_flight = True 71 try: 72 with Session( 73 context=dict(flow._context), 74 flow_name=flow.name, 75 flow_id=flow.equality_hash(), 76 name=None, 77 timeout=flow._timeout, 78 end_on_error=flow._end_on_error, 79 broadcast_callback=flow._broadcast_callback, 80 save_state=flow._save_state, 81 payload_callback=flow._payload_callback, 82 ) as session: 83 # bound before the entry point runs, so the context of a failed 84 # invocation is still reachable afterwards 85 self._session = session 86 return await call(flow.entry_point, *args, **kwargs) 87 finally: 88 self._in_flight = False
Runs the flow, leaving its context reachable on this connection.
Raises:
- RuntimeError: If this connection is already running an invocation.
90 def invoke(self, *args: _P.args, **kwargs: _P.kwargs) -> _TOutput: 91 """ 92 Synchronous `ainvoke`. 93 94 Note: 95 When no event loop is running, blocks until the flow finishes. 96 When called from inside a running event loop (e.g. a notebook or 97 async framework), the run is dispatched to a worker thread with its 98 own event loop; `contextvars.copy_context()` keeps Session and 99 logging context visible there. 100 """ 101 try: 102 asyncio.get_running_loop() 103 except RuntimeError: 104 return asyncio.run(self.ainvoke(*args, **kwargs)) 105 106 ctx = contextvars.copy_context() 107 with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool: 108 future = pool.submit(ctx.run, asyncio.run, self.ainvoke(*args, **kwargs)) 109 return future.result()
Synchronous ainvoke.
Note:
When no event loop is running, blocks until the flow finishes. When called from inside a running event loop (e.g. a notebook or async framework), the run is dispatched to a worker thread with its own event loop;
contextvars.copy_context()keeps Session and logging context visible there.
111 @property 112 def connected(self) -> bool: 113 """Whether this connection has begun an invocation yet.""" 114 return self._session is not None
Whether this connection has begun an invocation yet.
129 @property 130 def context(self) -> MutableExternalContext: 131 """ 132 The context of the most recent invocation. 133 134 A live reference, not a copy. Context is not intended to be modified. 135 136 """ 137 return self._require_session().context
The context of the most recent invocation.
A live reference, not a copy. Context is not intended to be modified.
139 @property 140 def session_id(self) -> str: 141 """Identifier of the session backing the most recent invocation.""" 142 return self._require_session().identifier
Identifier of the session backing the most recent invocation.
144 @property 145 def session(self) -> Session: 146 """ 147 The session backing the most recent invocation, for inspection. 148 149 Already closed; the connection owns its lifecycle. `Session.payload()` 150 and `Session.info` expose the run's state representation. 151 """ 152 return self._require_session()
The session backing the most recent invocation, for inspection.
Already closed; the connection owns its lifecycle. Session.payload()
and Session.info expose the run's state representation.
154 def message_histories(self) -> List[NodeMessageHistory]: 155 """ 156 Every model conversation from the most recent invocation, in the order the 157 runs were recorded. Concurrently called nodes have no guaranteed order. 158 159 Covers nested agents, unlike an `LLMResponse`, which carries only its 160 own. Nodes that made no model calls are omitted. 161 162 Walks the run's requests on every call rather than caching, so hold the 163 result if you need it more than once. 164 165 for h in conn.message_histories(): 166 print(h.node_name, len(h.message_history)) 167 168 Returns: 169 List[NodeMessageHistory]: One entry per node that called a model. 170 """ 171 info = self._require_session().info 172 node_forest = info.node_forest 173 174 histories: List[NodeMessageHistory] = [] 175 # a request is inserted into the heap when it is opened 176 for request in info.request_forest.heap().values(): 177 history = getattr(request.output, "message_history", None) 178 if history is None: 179 continue 180 node_type = node_forest.get_node_type(request.sink_id) 181 histories.append( 182 NodeMessageHistory( 183 node_name=node_type.name() 184 if node_type is not None 185 else "<unknown>", 186 node_id=request.sink_id, 187 request_id=request.identifier, 188 message_history=history, 189 ) 190 ) 191 192 return histories
Every model conversation from the most recent invocation, in the order the runs were recorded. Concurrently called nodes have no guaranteed order.
Covers nested agents, unlike an LLMResponse, which carries only its
own. Nodes that made no model calls are omitted.
Walks the run's requests on every call rather than caching, so hold the result if you need it more than once.
for h in conn.message_histories():
print(h.node_name, len(h.message_history))
Returns:
List[NodeMessageHistory]: One entry per node that called a model.
25@dataclass(frozen=True) 26class NodeMessageHistory: 27 """ 28 One node's conversation with its model. 29 30 Args: 31 node_name: Node that held the conversation, or 32 `"<unknown>"` if cannot resolve type. 33 node_id: Identifier of that node within the run. 34 request_id: Identifier of the request that produced it. 35 message_history: The messages exchanged, system prompt first. 36 """ 37 38 node_name: str 39 node_id: str 40 request_id: str 41 message_history: MessageHistory
One node's conversation with its model.
Arguments:
- node_name: Node that held the conversation, or
"<unknown>"if cannot resolve type. - node_id: Identifier of that node within the run.
- request_id: Identifier of the request that produced it.
- message_history: The messages exchanged, system prompt first.
82def enable_logging( 83 level: AllowableLogLevels = "INFO", 84 log_file: str | os.PathLike | None = None, 85 *, 86 name_style: LoggerNameDisplay = "short", 87) -> None: 88 """ 89 Opt-in helper to enable Railtracks logging. Call this explicitly from your 90 application entry point (CLI, main.py, server startup); the library never 91 calls it automatically. 92 93 Uses the given level and log_file; when None, reads RT_LOG_LEVEL and 94 RT_LOG_FILE from the environment. Sets up console output (and optional file) 95 with a ThreadAwareFilter for per-thread level control. 96 97 Runs print as an indented run view built from session events. The level picks 98 what it shows: ``WARNING`` the run's start and end plus failures, ``INFO`` adds 99 each node and LLM call, ``DEBUG`` adds arguments, responses, the run's result, 100 middleware decisions, and context operations. Only ``DEBUG`` prints arguments, 101 responses, and results; failure lines include the exception's message at every 102 level that shows failures. Each run uses the level of the thread it started in. 103 104 Args: 105 level: Logging level (default "INFO"). Overridden by RT_LOG_LEVEL when None. 106 log_file: Optional path for a log file. Overridden by RT_LOG_FILE when None. 107 name_style: Console column for logger name: ``full`` (dotted name) or 108 ``short`` (``RT.<Label>``: last segment with leading non-letters stripped, 109 then capitalized). Default ``short``. 110 """ 111 initialize_module_logging( 112 level=level, 113 log_file=log_file, 114 name_style=name_style, 115 )
Opt-in helper to enable Railtracks logging. Call this explicitly from your application entry point (CLI, main.py, server startup); the library never calls it automatically.
Uses the given level and log_file; when None, reads RT_LOG_LEVEL and RT_LOG_FILE from the environment. Sets up console output (and optional file) with a ThreadAwareFilter for per-thread level control.
Runs print as an indented run view built from session events. The level picks
what it shows: WARNING the run's start and end plus failures, INFO adds
each node and LLM call, DEBUG adds arguments, responses, the run's result,
middleware decisions, and context operations. Only DEBUG prints arguments,
responses, and results; failure lines include the exception's message at every
level that shows failures. Each run uses the level of the thread it started in.
Arguments:
- level: Logging level (default "INFO"). Overridden by RT_LOG_LEVEL when None.
- log_file: Optional path for a log file. Overridden by RT_LOG_FILE when None.
- name_style: Console column for logger name:
full(dotted name) orshort(RT.<Label>: last segment with leading non-letters stripped, then capitalized). Defaultshort.
31def post_node( 32 fn: Callable[[_R], Awaitable[_R]] | Callable[[_R], _R] | None = None, 33 /, 34 *, 35 name: str | None = None, 36) -> ( 37 Middleware[..., _R] 38 | Callable[ 39 [Callable[[_R], Awaitable[_R]] | Callable[[_R], _R]], Middleware[..., _R] 40 ] 41): 42 """ 43 Special decorator to create a middleware that runs after the node completes. The wrapped function will run and then your post function will be called upon successful completion of the function. 44 45 NOTE: This middleware will not run if the node raises an exception. 46 """ 47 48 if fn is None: 49 return lambda f: wrap_node(_wrapper(f), name=name) 50 51 return wrap_node(_wrapper(fn), name=name)
Special decorator to create a middleware that runs after the node completes. The wrapped function will run and then your post function will be called upon successful completion of the function.
NOTE: This middleware will not run if the node raises an exception.
28def after_node( 29 fn: Callable[[_R], Awaitable[_R]] | Callable[[_R], _R] | None = None, 30 /, 31 *, 32 name: str | None = None, 33) -> Any: 34 """Deprecated: Use ``rt.post_node`` instead.""" 35 warn_pending_change( 36 "rt.after_node", 37 change="is renamed", 38 instead="rt.post_node", 39 detail="The function itself is unchanged.", 40 ) 41 if fn is None: 42 return post_node(name=name) 43 return post_node(fn, name=name)
Deprecated: Use rt.post_node instead.
60def couple( 61 node: type[Node[_P, _R]] | RTFunction[_P, _R], 62 *, 63 middleware: Iterable[Middleware[_P, _R]] | None = None, 64 model_middleware: Iterable[ModelMiddleware] | None = None, 65) -> type[Node[_P, _R]] | RTFunction[_P, _R]: 66 """ 67 Attaches middleware to a Node or RTFunction. Returns a new Node or RTFunction; the one passed in is never modified. Middleware instances are shared with it rather than copied, so a ``MaxCalls`` budget or ``Lock`` already on ``node`` covers both. 68 69 Args: 70 node: The Node or RTFunction to attach middleware to. 71 middleware: Middleware instances to attach to the node. 72 model_middleware: ModelMiddleware instances to attach to the node. 73 74 Ordering: 75 - Middleware = [A, B, C] -> A wraps B, B wraps C, C wraps the node. A -> B -> C -> Node -> C -> B -> A 76 - Newly added middleware wraps around any existing middleware already on `node` 77 (the new middleware ends up outermost, farthest from the node). Call `couple()` 78 again on the result to add another, even-more-outer layer. 79 """ 80 from railtracks.built_nodes.function.base import RTFunction 81 82 if middleware is None and model_middleware is None: 83 return node 84 85 if isinstance(node, RTFunction): 86 if model_middleware is not None: 87 raise ValueError("Your function node does not have a model to wrap") 88 if middleware: 89 new_node_type = node.node_type.extend_middleware(*middleware) 90 else: 91 return node 92 93 return node.with_node_type(new_node_type) 94 95 new_klass = node 96 97 if middleware: 98 new_klass = new_klass.extend_middleware(*middleware) 99 if model_middleware: 100 new_klass = new_klass.extend_model_middleware(*model_middleware) 101 102 return new_klass
Attaches middleware to a Node or RTFunction. Returns a new Node or RTFunction; the one passed in is never modified. Middleware instances are shared with it rather than copied, so a MaxCalls budget or Lock already on node covers both.
Arguments:
- node: The Node or RTFunction to attach middleware to.
- middleware: Middleware instances to attach to the node.
- model_middleware: ModelMiddleware instances to attach to the node.
Ordering:
- Middleware = [A, B, C] -> A wraps B, B wraps C, C wraps the node. A -> B -> C -> Node -> C -> B -> A
- Newly added middleware wraps around any existing middleware already on
node(the new middleware ends up outermost, farthest from the node). Callcouple()again on the result to add another, even-more-outer layer.
51def pre_llm( 52 fn: Callable[ 53 [MessageHistory, type[BaseModel] | None, list[Tool] | None], 54 tuple[MessageHistory, type[BaseModel] | None, list[Tool] | None] 55 | Awaitable[tuple[MessageHistory, type[BaseModel] | None, list[Tool] | None]], 56 ] 57 | None = None, 58 /, 59 *, 60 name: str | None = None, 61) -> ( 62 ModelMiddleware 63 | Callable[ 64 [ 65 Callable[ 66 [MessageHistory, type[BaseModel] | None, list[Tool] | None], 67 tuple[MessageHistory, type[BaseModel] | None, list[Tool] | None] 68 | Awaitable[ 69 tuple[MessageHistory, type[BaseModel] | None, list[Tool] | None] 70 ], 71 ] 72 ], 73 ModelMiddleware, 74 ] 75): 76 """ 77 A special decorator to create a middleware that maps the inputs to a new input before every call to a model 78 79 Example usage: 80 ```python 81 @pre_llm 82 async def my_middleware(message_history, schema, tools): 83 # do something with the inputs 84 return message_history, schema, tools 85 ``` 86 """ 87 88 def decorator(fn): 89 @wrap_llm(name=name) 90 @functools.wraps(fn) 91 async def wrapper( 92 llm_call: LLM_CALL, 93 message_history: MessageHistory, 94 schema: type[BaseModel] | None, 95 tools: list[Tool] | None, 96 ): 97 invocation_event = MiddlewareModelInputInvocationEvent( 98 message_history=message_history, 99 schema=schema, 100 tools=tools, 101 ) 102 await emit(invocation_event) 103 104 message_history, schema, tools = await unpack_async_sync( 105 fn(message_history, schema, tools) 106 ) 107 108 response_event = MiddlewareModelInputResponseEvent( 109 message_history=message_history, 110 schema=schema, 111 tools=tools, 112 ) 113 await emit(response_event) 114 115 return await llm_call(message_history, schema, tools) 116 117 return wrapper 118 119 if fn is None: 120 return decorator 121 return decorator(fn)
A special decorator to create a middleware that maps the inputs to a new input before every call to a model
Example usage:
@pre_llm
async def my_middleware(message_history, schema, tools):
# do something with the inputs
return message_history, schema, tools
37def post_llm( 38 fn: Callable[[Response], Response | Awaitable[Response]] | None = None, 39 /, 40 *, 41 name: str | None = None, 42) -> ( 43 ModelMiddleware 44 | Callable[[Callable[[Response], Response | Awaitable[Response]]], ModelMiddleware] 45): 46 """ 47 A special decorator to create a middleware that runs after every successful call to the model. 48 49 Example usage: 50 ```python 51 @post_llm 52 async def my_middleware(response): 53 # do something with the response 54 return response 55 ``` 56 """ 57 58 def decorator(fn): 59 @wrap_llm(name=name) 60 @functools.wraps(fn) 61 async def wrapper( 62 llm_call: LLM_CALL, 63 message_history: MessageHistory, 64 schema: type[BaseModel] | None, 65 tools: list[Tool] | None, 66 ): 67 response = await llm_call(message_history, schema, tools) 68 69 invocation_event = MiddlewareModelOutputInvocationEvent( 70 response=response, 71 ) 72 await emit(invocation_event) 73 74 try: 75 response = await unpack_async_sync(fn(response)) 76 except Exception as e: 77 failure_event = MiddlewareModelOutputFailureEvent.from_exception(e) 78 await emit(failure_event) 79 raise e 80 81 response_event = MiddlewareModelOutputResponseEvent( 82 response=response, 83 ) 84 await emit(response_event) 85 86 return response 87 88 return wrapper 89 90 if fn is None: 91 return decorator 92 return decorator(fn)
A special decorator to create a middleware that runs after every successful call to the model.
Example usage:
@post_llm
async def my_middleware(response):
# do something with the response
return response
46def before_llm( 47 fn: Callable[ 48 [MessageHistory, type[BaseModel] | None, list[Tool] | None], 49 tuple[MessageHistory, type[BaseModel] | None, list[Tool] | None] 50 | Awaitable[tuple[MessageHistory, type[BaseModel] | None, list[Tool] | None]], 51 ] 52 | None = None, 53 /, 54 *, 55 name: str | None = None, 56) -> Any: 57 """Deprecated: Use ``rt.pre_llm`` instead.""" 58 warn_pending_change( 59 "rt.before_llm", 60 change="is renamed", 61 instead="rt.pre_llm", 62 detail="The function itself is unchanged.", 63 ) 64 if fn is None: 65 return pre_llm(name=name) 66 return pre_llm(fn, name=name)
Deprecated: Use rt.pre_llm instead.
27def after_llm( 28 fn: Callable[[Response], Response | Awaitable[Response]] | None = None, 29 /, 30 *, 31 name: str | None = None, 32) -> Any: 33 """Deprecated: Use ``rt.post_llm`` instead.""" 34 warn_pending_change( 35 "rt.after_llm", 36 change="is renamed", 37 instead="rt.post_llm", 38 detail="The function itself is unchanged.", 39 ) 40 if fn is None: 41 return post_llm(name=name) 42 return post_llm(fn, name=name)
Deprecated: Use rt.post_llm instead.
47def wrap_llm( 48 fn: Callable[ 49 [LLM_CALL, MessageHistory, type[BaseModel] | None, list[Tool] | None], 50 Awaitable[Response], 51 ] 52 | None = None, 53 /, 54 *, 55 name: str | None = None, 56) -> ( 57 ModelMiddleware 58 | Callable[ 59 [ 60 Callable[ 61 [LLM_CALL, MessageHistory, type[BaseModel] | None, list[Tool] | None], 62 Awaitable[Response], 63 ] 64 ], 65 ModelMiddleware, 66 ] 67): 68 """ 69 A special decorator to create a middleware wrapper that wraps every call to an llm 70 71 Example usage: 72 ```python 73 @wrap_llm 74 async def my_middleware(llm_call, message_history, schema, tools): 75 # do something with the inputs 76 response = await llm_call(message_history, schema, tools) 77 # do something with the response 78 return response 79 ``` 80 """ 81 82 def decorator(fn): 83 @functools.wraps(fn) 84 async def wrapped( 85 llm_call: LLM_CALL, 86 message_history: MessageHistory, 87 schema: type[BaseModel] | None, 88 tools: list[Tool] | None, 89 ): 90 invocation_event = MiddlewareModelInvocationEvent( 91 message_history=message_history, 92 schema=schema, 93 tools=tools, 94 ) 95 await emit(invocation_event) 96 97 try: 98 response = await fn(llm_call, message_history, schema, tools) 99 except Exception as e: 100 failure_event = MiddlewareModelFailureEvent.from_exception(e) 101 await emit(failure_event) 102 raise e 103 104 response_event = MiddlewareModelResponseEvent( 105 response=response, 106 ) 107 await emit(response_event) 108 109 return response 110 111 return ModelOnlyMiddleware(wrapped, name=name) 112 113 if fn is None: 114 return decorator 115 return decorator(fn)
A special decorator to create a middleware wrapper that wraps every call to an llm
Example usage:
@wrap_llm
async def my_middleware(llm_call, message_history, schema, tools):
# do something with the inputs
response = await llm_call(message_history, schema, tools)
# do something with the response
return response
109def input_guard( 110 fn: _GuardFn | None = None, 111 *, 112 name: str | None = None, 113 fail_open: bool = False, 114): 115 """Turn a function into an :class:`InputGuard` instance. 116 117 The function receives an :class:`LLMGuardrailEvent` (INPUT phase; inspect 118 ``event.messages``) and returns a :class:`GuardrailDecision`. It may be sync or 119 ``async def``; an async rail is awaited, so it can ``await rt.call(...)``. 120 121 Usable bare or parameterized:: 122 123 @rt.input_guard 124 def guard(event): ... 125 126 127 @rt.input_guard(name="my_rail", fail_open=True) 128 async def guard(event): ... 129 130 Args: 131 fn: The guard function (supplied automatically in the bare form). 132 name: Rail name for traces; defaults to the function name. 133 fail_open: Allow the request through if the guard raises unexpectedly. 134 135 Returns: 136 An :class:`InputGuard` instance in the bare form, or a decorator in the 137 parameterized form. 138 """ 139 140 def decorate(func: _GuardFn, /) -> InputGuard: 141 return _make_guard(InputGuard, func, name=name, fail_open=fail_open) 142 143 if fn is not None: 144 return decorate(fn) 145 return decorate
Turn a function into an InputGuard instance.
The function receives an LLMGuardrailEvent (INPUT phase; inspect
event.messages) and returns a GuardrailDecision. It may be sync or
async def; an async rail is awaited, so it can await rt.call(...).
Usable bare or parameterized::
@rt.input_guard
def guard(event): ...
@rt.input_guard(name="my_rail", fail_open=True)
async def guard(event): ...
Arguments:
- fn: The guard function (supplied automatically in the bare form).
- name: Rail name for traces; defaults to the function name.
- fail_open: Allow the request through if the guard raises unexpectedly.
Returns:
An
InputGuardinstance in the bare form, or a decorator in the parameterized form.
154def output_guard( 155 fn: _GuardFn | None = None, 156 *, 157 name: str | None = None, 158 fail_open: bool = False, 159): 160 """Turn a function into an :class:`OutputGuard` instance. 161 162 The function receives an :class:`LLMGuardrailEvent` (OUTPUT phase; inspect 163 ``event.output_message``) and returns a :class:`GuardrailDecision`. It may be 164 sync or ``async def``; an async rail is awaited, so it can ``await rt.call(...)``. 165 Intermediate tool-call turns are skipped by :class:`OutputGuard`, so the 166 function fires only on the final reply. 167 168 Usable bare or parameterized:: 169 170 @rt.output_guard 171 def guard(event): ... 172 173 174 @rt.output_guard(name="my_rail", fail_open=True) 175 async def guard(event): ... 176 177 Args: 178 fn: The guard function (supplied automatically in the bare form). 179 name: Rail name for traces; defaults to the function name. 180 fail_open: Allow the response through if the guard raises unexpectedly. 181 182 Returns: 183 An :class:`OutputGuard` instance in the bare form, or a decorator in the 184 parameterized form. 185 """ 186 187 def decorate(func: _GuardFn, /) -> OutputGuard: 188 return _make_guard(OutputGuard, func, name=name, fail_open=fail_open) 189 190 if fn is not None: 191 return decorate(fn) 192 return decorate
Turn a function into an OutputGuard instance.
The function receives an LLMGuardrailEvent (OUTPUT phase; inspect
event.output_message) and returns a GuardrailDecision. It may be
sync or async def; an async rail is awaited, so it can await rt.call(...).
Intermediate tool-call turns are skipped by OutputGuard, so the
function fires only on the final reply.
Usable bare or parameterized::
@rt.output_guard
def guard(event): ...
@rt.output_guard(name="my_rail", fail_open=True)
async def guard(event): ...
Arguments:
- fn: The guard function (supplied automatically in the bare form).
- name: Rail name for traces; defaults to the function name.
- fail_open: Allow the response through if the guard raises unexpectedly.
Returns:
An
OutputGuardinstance in the bare form, or a decorator in the parameterized form.
10def escape_braces(text: str) -> str: 11 """ 12 Escape the braces in `text` so that context injection treats it as data. 13 14 Apply this to untrusted or arbitrary strings before embedding them in a message that 15 will have context values injected into it. Injecting the returned string yields 16 `text` back unchanged. 17 18 Args: 19 text: The string to escape. 20 21 Returns: 22 `text` with every `{` and `}` doubled. 23 """ 24 return text.replace("{", "{{").replace("}", "}}")
Escape the braces in text so that context injection treats it as data.
Apply this to untrusted or arbitrary strings before embedding them in a message that
will have context values injected into it. Injecting the returned string yields
text back unchanged.
Arguments:
- text: The string to escape.
Returns:
textwith every{and}doubled.