defined-compiler API Reference

Verb compiler — parses task YAML, expands verbs, gates capabilities, and emits BT XML.

Task Parser

parser

YAML task parser — loads verb task files.

Reads a task YAML from disk and returns the raw Python dict. The caller is responsible for schema validation and verb expansion.

Usage

from defined_compiler.parser import load_task

task = load_task("patrol.task.yaml")

load_task(path)

Load a YAML task file and return the raw task dict.

Parameters:

Name	Type	Description	Default
path	str | Path	Filesystem path to the task YAML file.	required

Returns:

Type	Description
dict[str, Any]	Parsed task as a plain Python dict.

Raises:

Type	Description
FileNotFoundError	If the file does not exist.
YAMLError	If the file is not valid YAML.

Verb Expander

verb_expander

Verb expander — expand high-level verbs into primitive sequences.

Loads verb YAML definitions from the verb library directory and resolves them into the intermediate representation consumed by the BT emitter and capability gate. Each expanded verb carries its Jinja2 template name, required capabilities, and caller-supplied parameter values.

Supports extends: defined/<name> for inheriting from built-in verbs.

Merge rules

• dependencies: additive union (apt/source/pip lists concatenate, deduplicated)
• All other top-level keys: shallow replace (local replaces base entirely)

Usage

from defined_compiler.verb_expander import expand_verb

verb_data = expand_verb("go_to", {"x": 1.0, "y": 2.0})

load_verb_definition(verb_name, verbs_dir=None)

Load a verb definition YAML from the verb library.

Parameters:

Name	Type	Description	Default
verb_name	str	Identifier of the verb (e.g. "go_to").	required
verbs_dir	Path | None	Directory to search. Defaults to the built-in verb_library/ shipped with defined-compiler.	None

Returns:

Type	Description
dict[str, Any]	Parsed verb definition as a plain Python dict.

Raises:

Type	Description
ValueError	If no YAML definition file exists for verb_name.

resolve_verb_definition(verb_name, verbs_dir=None)

Load and resolve a verb definition, handling extends.

If the verb has extends: defined/<base>, the base verb is loaded from the built-in library and merged with the local definition.

Merge rules: - dependencies: additive union (apt/source/pip concatenate, deduplicated) - All other top-level keys: shallow replace (local replaces base)

Parameters:

Name	Type	Description	Default
verb_name	str	Identifier of the verb (e.g. "go_to").	required
verbs_dir	Path | None	Project verb directory. Falls back to built-in library.	None

Returns:

Type	Description
dict[str, Any]	Fully resolved verb definition dict.

Raises:

Type	Description
ValueError	If extends target not found or has invalid prefix.

expand_verb(verb_name, params, verbs_dir=None)

Expand a verb into its intermediate representation.

Loads the verb's YAML definition (resolving extends if present) and merges it with the caller-supplied parameter values, producing the dict that the BT emitter and capability gate consume.

Parameters:

Name	Type	Description	Default
verb_name	str	Identifier of the verb (e.g. "go_to").	required
params	dict[str, Any]	Key/value parameters supplied by the task YAML.	required
verbs_dir	Path | None	Directory containing verb YAML and Jinja2 template files. Defaults to the built-in verb_library/.	None

Returns:

Type	Description
dict[str, Any]	Dict with keys verb, params, template,
dict[str, Any]	required_capabilities, and primitives.

Raises:

Type	Description
ValueError	If the verb has no definition in the library.

Capability Gate

capability_gate

Capability gating — check task requirements against RDF capabilities.

Validates that every capability required by a verb is present in the robot's RDF manifest before compilation proceeds. A failed gate causes the compilation to be rejected rather than producing an invalid BT XML.

Usage

from defined_compiler.capability_gate import check

result = check(registry, ["navigate_2d", "rgb_camera"]) if not result.passed: raise RuntimeError(f"Missing: {result.missing}")

GateResult

Result of a single capability gate check.

Attributes:

Name	Type	Description
passed		True if all required capabilities are satisfied.
missing		Names of capabilities that are absent from the registry.

status property

Return 'OK' if the gate passed, otherwise 'REJECTED'.

check(registry, required_capabilities)

Check whether all required capabilities are present in the registry.

Parameters:

Name	Type	Description	Default
registry	CapabilityRegistry	Capability registry built from the robot's RDF manifest.	required
required_capabilities	list[str]	List of capability identifiers that the verb requires (e.g. ["navigate_2d", "rgb_camera"]).	required

Returns:

Name	Type	Description
A	GateResult	class:GateResult with passed=True if all requirements are
	GateResult	met, or passed=False plus the list of missing capability names.

BT Emitter

bt_emitter

BT XML emitter — render BehaviorTree.CPP v4 XML from expanded verbs.

Takes the intermediate representation produced by the verb expander and renders a complete BehaviorTree.CPP v4 XML document, including the <TreeNodesModel> port manifest required by Groot2.

Usage

from defined_compiler.bt_emitter import render_bt_xml

xml = render_bt_xml(expanded_verbs, task_name="PatrolTask")

render_bt_xml(expanded_verbs, task_name='MainTask', verbs_dir=None)

Render a complete BehaviorTree.CPP v4 XML document.

Takes the list of expanded verb dicts produced by :func:defined_compiler.verb_expander.expand_verb and renders them through their Jinja2 templates into a single BT XML document with a <TreeNodesModel> port manifest.

Parameters:

Name	Type	Description	Default
expanded_verbs	list[dict[str, Any]]	Sequence of expanded verb dicts, each containing keys verb, params, template, and required_capabilities.	required
task_name	str	Name for the root <BehaviorTree> ID and the wrapping <Sequence>. Defaults to "MainTask".	'MainTask'
verbs_dir	Path | None	Directory containing the Jinja2 template files and verb YAML definitions. Defaults to the built-in verb_library/.	None

Returns:

Type	Description
str	Complete BehaviorTree.CPP v4 XML as a string.

Verb Schema

verb_schema

5-layer verb manifest schema.

Pydantic v2 models for the full verb package format:

• Layer 0: Identity (name, version, description)
• Layer 1: Capability gate (required_capabilities)
• Layer 2: BT template + parameters
• Layer 3: Software dependencies (apt, source, pip)
• Layer 4: Runtime configuration (ROS2 nodes, parameters)
• Layer 5: Interface contract (actions, topics, outputs)

Layers 3-5 are optional for backward compatibility with existing verb YAMLs that only define layers 0-2.

SourceDep

Bases: BaseModel

A source dependency — either a remote git repo or a local path.

Exactly one of repo or path must be set.

Dependencies

Bases: BaseModel

Layer 3 — software dependencies required by a verb.

NodeConfig

Bases: BaseModel

A ROS2 node to launch for this verb.

RuntimeConfig

Bases: BaseModel

Layer 4 — runtime configuration (ROS2 nodes and parameters).

ActionInterface

Bases: BaseModel

A ROS2 action this verb uses.

TopicInterface

Bases: BaseModel

Topics this verb subscribes to or publishes.

InterfaceContract

Bases: BaseModel

Layer 5 — interface contract declaring actions, topics, outputs.

VerbManifest

Bases: BaseModel

Complete 5-layer verb manifest.

Layers 0-2 match the existing verb YAML format. Layers 3-5 are new optional fields that carry dependency and runtime information.