roboto.templating
Generic {{name}} placeholder substitution shared across the SDK.
The same lightweight templating primitive powers reusable agent definitions (client-side substitution of caller-supplied values before a thread starts) and event triggers (server-side substitution of event-derived variables into a target’s request). A VariableResolver binds placeholders to a source of values, so the substitution engine stays agnostic to where those values come from.
Submodules
Package Contents
MappingResolver
A VariableResolver backed by a flat name -> value mapping.
Values are coerced to str on access; a missing key or a None value resolves to None (leaving the placeholder unexpanded).
Parameters
values Mapping[str, Any]MappingResolver.resolve()
Parameters
name strReturn type
PLACEHOLDER_RE
Recognizes {{name}} placeholders. Names start with a letter or underscore; dots are allowed so dotted names ({{dataset.id}}, {{action.name}}) work as a namespace convention for entity-bound expansion by a VariableResolver. The engine treats the full dotted string as one opaque key — the resolver decides what, if anything, it expands to.
VARIABLE_NAME_RE
Mirrors PLACEHOLDER_RE so every declared variable name is referenceable by {{name}}.
VariableResolver
Bases: Protocol
Decides what each {{name}} placeholder expands to during substitution.
Implementations bind placeholders to a source of values — a flat mapping for agent launch, or a lazily-hydrated event namespace for triggers — keeping the substitution engine itself agnostic to where values come from.
VariableResolver.resolve()
Return the substitution string for placeholder name, or None.
Parameters
name strThe placeholder name written between {{ and }}, dots included (e.g. dataset.id).
Returns
The string to splice in, or None to leave the literal {{name}} in place.
collect_placeholders()
Return every {{name}} placeholder found in the string leaves of node.
node is the JSON form of a template (nested dicts, lists, scalars). Only string values are scanned; placeholder syntax in dict keys is rejected so a templated key can’t silently collapse two entries into one.
Parameters
node AnyRaises
ValueErrorA dict key contains {{...}} placeholder syntax.
Return type
substitute()
Return a copy of node with each {{name}} in a string leaf expanded via resolver.
Embedded and repeated placeholders within one string are supported. A name the resolver returns None for is left as the literal {{name}}; callers that require full resolution validate the placeholder set up front with collect_placeholders().
Parameters
node Anyresolver VariableResolverReturn type