API Reference

This page documents the public API of the core yasmin package. It covers all classes needed to create states, state machines, and concurrent containers in both C++ and Python.

State

The base class for all states. To create a custom state, subclass State and implement the execute() method. The constructor receives the set of valid outcome strings that execute() may return.

Constructor

C++

State(const std::set<std::string> &outcomes);

Python

State(outcomes: list[str])

Core Methods

Method	C++ Signature	Python Signature	Description
`execute`	`virtual std::string execute( Blackboard::SharedPtr blackboard)`	`def execute(self, blackboard: Blackboard) -> str`	Override to implement the state's logic. Must return one of the declared outcomes.
`configure`	`virtual void configure()`	`def configure(self) -> None`	Called once before the first execution inside a container. Override to allocate resources or validate configuration.
`cancel_state`	`virtual void cancel_state()`	`def cancel_state(self) -> None`	Signals the state to stop. Sets the internal status to `CANCELED`.
`operator()` / call	`std::string operator()( Blackboard::SharedPtr blackboard)`	`state(blackboard: Blackboard) -> str`	Executes the state and returns the outcome. Validates that the returned string belongs to the declared outcomes.
`get_outcomes`	`const std::set<std::string> &get_outcomes() const`	`def get_outcomes(self) -> list[str]`	Returns the set of declared outcomes.

Status Methods

Method	Return type	Description
`is_idle()`	`bool`	True when the state has not yet started executing.
`is_running()`	`bool`	True while `execute()` is in progress.
`is_canceled()`	`bool`	True after `cancel_state()` has been called.
`is_completed()`	`bool`	True after `execute()` returns successfully.

Metadata Methods

Metadata is declared in the constructor and describes the state's interface to external tools such as the editor and factory.

Method	C++ Signature	Python Signature	Description
`set_description`	`void set_description(const std::string &description)`	`def set_description(self, description: str) -> None`	Sets a human-readable description of the state's purpose.
`get_description`	`const std::string &get_description() const`	`def get_description(self) -> str`	Returns the state description.
`set_outcome_description`	`void set_outcome_description( const std::string &outcome, const std::string &description)`	`def set_outcome_description( self, outcome: str, description: str) -> None`	Attaches a description to a specific outcome string.
`get_outcome_description`	`const std::string &get_outcome_description( const std::string &outcome) const`	`def get_outcome_description( self, outcome: str) -> str`	Returns the description for a given outcome.
`get_outcome_descriptions`	`const std::unordered_map<std::string, std::string> &get_outcome_descriptions() const`	`def get_outcome_descriptions(self) -> dict[str, str]`	Returns all outcome descriptions as a map.
`add_input_key`	`void add_input_key( const std::string &key_name, const std::string &description = "", T default_value = {})`	`def add_input_key( self, key_name: str, description: str = "", default_value = None) -> None`	Declares a blackboard key the state reads. An optional default value is injected when the key is absent at runtime.
`get_input_keys`	`const std::vector<BlackboardKeyInfo> &get_input_keys() const`	`def get_input_keys(self) -> list`	Returns the declared input key metadata list.
`add_output_key`	`void add_output_key( const std::string &key_name, const std::string &description = "")`	`def add_output_key( self, key_name: str, description: str = "") -> None`	Declares a blackboard key the state writes.
`get_output_keys`	`const std::vector<BlackboardKeyInfo> &get_output_keys() const`	`def get_output_keys(self) -> list`	Returns the declared output key metadata list.
`declare_parameter`	`void declare_parameter( const std::string &parameter_name, const std::string &description = "", T default_value = {})`	`def declare_parameter( self, parameter_name: str, description: str = "", default_value = None) -> None`	Declares a state-local configuration parameter with an optional default value.
`has_parameter`	`bool has_parameter(const std::string &name) const`	`def has_parameter(self, name: str) -> bool`	Returns `True` if the parameter key exists in the state's local storage.
`get_parameter`	`T get_parameter<T>(const std::string &name) const`	`def get_parameter(self, name: str) -> Any`	Reads a parameter from the state's local storage.
`set_parameter`	`void set_parameter<T>(const std::string &name, T value)`	`def set_parameter(self, name: str, value: Any) -> None`	Writes a parameter to the state's local storage.
`get_parameters`	`const std::vector<BlackboardKeyInfo> &get_parameters() const`	`def get_parameters(self) -> list`	Returns the declared parameter metadata list.
`get_metadata`	`const StateMetadata &get_metadata() const`	`def get_metadata(self) -> StateMetadata`	Returns the complete metadata object (description, outcome descriptions, input keys, output keys, parameters).

Example

C++

#include "yasmin/state.hpp"
#include "yasmin/blackboard.hpp"

class FooState : public yasmin::State {
public:
    FooState() : yasmin::State({"outcome1", "outcome2"}) {
        this->set_description("Performs the Foo operation.");
        this->add_output_key("foo_str", "Result string produced by FooState.");
    }

    std::string execute(yasmin::Blackboard::SharedPtr blackboard) override {
        blackboard->set<std::string>("foo_str", "Hello from Foo");
        return "outcome1";
    }
};

Python

from yasmin import State, Blackboard

class FooState(State):
    def __init__(self):
        super().__init__(["outcome1", "outcome2"])
        self.set_description("Performs the Foo operation.")
        self.add_output_key("foo_str", "Result string produced by FooState.")

    def execute(self, blackboard: Blackboard) -> str:
        blackboard["foo_str"] = "Hello from Foo"
        return "outcome1"

StateMachine

StateMachine extends State, so it can be nested inside another state machine. It manages a collection of states, their transitions, and optional remappings and parameter mappings.

Constructor

C++

// Without a name (name defaults to the class type name)
StateMachine(const std::set<std::string> &outcomes,
             bool handle_sigint = false);

// With an explicit name
StateMachine(const std::string &name,
             const std::set<std::string> &outcomes,
             bool handle_sigint = false);

Python

StateMachine(outcomes: list[str], handle_sigint: bool = False)

State Management

Method	C++ Signature	Python Signature	Description
`add_state`	`void add_state( const std::string &name, State::SharedPtr state, const Transitions &transitions = {}, const Remappings &remappings = {}, const ParameterMappings &parameter_mappings = {})`	`def add_state( self, name: str, state: State, transitions: dict[str, str] = {}, remappings: dict[str, str] = {}, parameter_mappings: dict[str, str] = {}) -> None`	Adds a state with its transitions, optional blackboard remappings, and optional parameter mappings. `transitions` maps outcome strings to target state names (or terminal outcomes of the machine). `remappings` maps the state's local key names to blackboard key names. `parameter_mappings` maps child parameter names to parent parameter names (`child -> parent`).
`set_start_state`	`void set_start_state(const std::string &state_name)`	`def set_start_state(self, state_name: str) -> None`	Sets the initial state. Defaults to the first state added when not called explicitly.
`get_start_state`	`const std::string &get_start_state() const`	`def get_start_state(self) -> str`	Returns the name of the start state.
`get_states`	`const StateMap &get_states() const`	`def get_states(self) -> dict[str, State]`	Returns the map of registered state names to state objects.
`get_transitions`	`const TransitionsMap &get_transitions() const`	`def get_transitions(self) -> dict[str, dict[str, str]]`	Returns the complete transition table.
`get_current_state`	`const std::string &get_current_state() const`	`def get_current_state(self) -> str`	Returns the name of the currently active state.
`validate`	`void validate(bool strict_mode = false)`	`def validate(self, strict_mode: bool = False) -> None`	Validates the state machine configuration. In strict mode, also checks that every declared outcome is reachable and every state outcome has a transition.

Execution

Method	C++ Signature	Python Signature	Description
`execute`	`std::string execute( Blackboard::SharedPtr blackboard)`	`def execute(self, blackboard: Blackboard) -> str`	Runs the state machine with the provided blackboard.
`execute` (no-arg)	`std::string execute()`	`def execute(self) -> str`	Runs the state machine using an internally created empty blackboard.
`operator()` / call	`std::string operator()()`	`sm() -> str`	Invokes the state machine with a new empty blackboard.
`cancel_state`	`void cancel_state() override`	`def cancel_state(self) -> None`	Forwards the cancel request to the currently active child state.
`cancel_state_machine`	`void cancel_state_machine()`	`def cancel_state_machine(self) -> None`	Hard-stops the entire state machine, propagating the cancel recursively through nested machines.

Naming and Callbacks

Method	C++ Signature	Python Signature	Description
`set_name`	`void set_name(const std::string &name)`	`def set_name(self, name: str) -> None`	Sets a display name for this state machine.
`get_name`	`const std::string &get_name() const`	`def get_name(self) -> str`	Returns the display name.
`add_start_cb`	`void add_start_cb( function<void(Blackboard::SharedPtr, const string&)> cb)`	`def add_start_cb( self, cb: Callable[[Blackboard, str], None]) -> None`	Registers a callback invoked when the state machine starts. The callback receives the blackboard and the start state name.
`add_transition_cb`	`void add_transition_cb( function<void(Blackboard::SharedPtr, const string&, const string&, const string&)> cb)`	`def add_transition_cb( self, cb: Callable[[Blackboard, str, str, str], None]) -> None`	Registers a callback invoked on every state transition. The callback receives the blackboard, the previous state name, the outcome, and the next state name.
`add_end_cb`	`void add_end_cb( function<void(Blackboard::SharedPtr, const string&)> cb)`	`def add_end_cb( self, cb: Callable[[Blackboard, str], None]) -> None`	Registers a callback invoked when the state machine finishes. The callback receives the blackboard and the terminal outcome.

StateMachine inherits all State metadata methods (set_description, add_input_key, add_output_key, declare_parameter, etc.).

Example

C++

#include "yasmin/state_machine.hpp"
#include "yasmin/blackboard.hpp"

auto sm = std::make_shared<yasmin::StateMachine>(
    std::set<std::string>{"outcome1", "outcome2"});

sm->set_description("A simple state machine.");
sm->add_input_key("foo_str", "Input string for FooState.");

sm->add_state("FOO", std::make_shared<FooState>(),
              {{"outcome1", "BAR"}, {"outcome2", "outcome2"}});
sm->add_state("BAR", std::make_shared<BarState>(),
              {{"outcome3", "outcome1"}});

auto blackboard = std::make_shared<yasmin::Blackboard>();
blackboard->set<std::string>("foo_str", "hello");
std::string outcome = (*sm)(blackboard);

Python

from yasmin import StateMachine, Blackboard

sm = StateMachine(outcomes=["outcome1", "outcome2"])
sm.set_description("A simple state machine.")
sm.add_input_key("foo_str", "Input string for FooState.")

sm.add_state("FOO", FooState(),
             transitions={"outcome1": "BAR", "outcome2": "outcome2"})
sm.add_state("BAR", BarState(),
             transitions={"outcome3": "outcome1"})

blackboard = Blackboard()
blackboard["foo_str"] = "hello"
outcome = sm(blackboard)

Blackboard

A thread-safe key-value store that all states in a state machine share during execution. In Python the standard subscript syntax (blackboard["key"]) is supported in addition to the explicit get / set calls.

Constructor

C++

Blackboard();

Python

Blackboard()

Methods

Method	C++ Signature	Python Signature	Description
`set`	`void set<T>(const std::string &key, T value)`	`blackboard[key] = value` or `def set(self, key: str, value: Any) -> None`	Stores a value under the given key.
`get`	`T get<T>(const std::string &key) const`	`blackboard[key]` or `def get(self, key: str) -> Any`	Retrieves the value stored under the given key. Raises `std::runtime_error` / `KeyError` if the key does not exist.
`contains`	`bool contains(const std::string &key) const`	`def contains(self, key: str) -> bool`	Returns `true` if the key is present.
`remove`	`void remove(const std::string &key)`	`def remove(self, key: str) -> None`	Removes the entry for the given key.
`size`	`int size() const`	`def size(self) -> int`	Returns the number of stored entries.
`keys`	`std::vector<std::string> keys() const`	`def keys(self) -> list[str]`	Returns the list of keys visible in the current remapping scope.
`get_type`	`std::string get_type(const std::string &key) const`	`def get_type(self, key: str) -> str`	Returns the stored type name for the given key.
`to_string`	`std::string to_string() const`	`def to_string(self) -> str`	Returns a human-readable representation of all entries.
`set_remappings`	`void set_remappings(const Remappings &remappings)`	`def set_remappings(self, remappings: dict[str, str]) -> None`	Sets the local remapping table. A remapping entry `a -> b` redirects all accesses to key `a` to the underlying key `b`.
`copy_value_from`	`void copy_value_from( const Blackboard &other, const std::string &source_key, const std::string &target_key)`	`def copy_value_from( self, other: Blackboard, source_key: str, target_key: str) -> None`	Copies a value from another blackboard without knowing the type at compile time.

Example

C++

#include "yasmin/blackboard.hpp"

auto bb = std::make_shared<yasmin::Blackboard>();
bb->set<int>("counter", 0);
int v = bb->get<int>("counter");   // 0
bb->remove("counter");
bool exists = bb->contains("counter"); // false

Python

from yasmin import Blackboard

bb = Blackboard()
bb["counter"] = 0
v = bb["counter"]   # 0
bb.remove("counter")
exists = bb.contains("counter")  # False

CbState

A convenience state that wraps a plain callback function. Use it when the state logic is too simple to justify a dedicated subclass.

Constructor

C++

CbState(const std::set<std::string> &outcomes,
        std::function<std::string(Blackboard::SharedPtr)> callback);

Python

CbState(outcomes: list[str], callback: Callable[[Blackboard], str])

The callback receives the shared Blackboard and must return one of the declared outcome strings. CbState inherits all State metadata methods.

Example

C++

#include "yasmin/cb_state.hpp"

auto greeting_state = std::make_shared<yasmin::CbState>(
    std::set<std::string>{"done"},
    [](yasmin::Blackboard::SharedPtr bb) -> std::string {
        YASMIN_LOG_INFO("Hello from CbState");
        return "done";
    });

greeting_state->set_description("Prints a greeting message.");
sm->add_state("GREET", greeting_state, {{"done", "outcome1"}});

Python

from yasmin import CbState, Blackboard
import yasmin

def greeting_cb(blackboard: Blackboard) -> str:
    yasmin.YASMIN_LOG_INFO("Hello from CbState")
    return "done"

greeting_state = CbState(outcomes=["done"], callback=greeting_cb)
greeting_state.set_description("Prints a greeting message.")
sm.add_state("GREET", greeting_state, transitions={"done": "outcome1"})

Concurrence

Concurrence extends State and executes multiple child states in parallel threads. When all threads finish, the combined outcomes are matched against an outcome map to determine the overall outcome. If no rule matches, the default outcome is returned.

Constructor

C++

Concurrence(
    const StateMap &states,
    const std::string &default_outcome,
    const OutcomeMap &outcome_map,
    const ParameterMappingsMap &parameter_mappings = {});

Python

Concurrence(
    states: dict[str, State],
    default_outcome: str,
    outcome_map: dict[str, dict[str, str]])

states maps logical names to State objects. outcome_map maps desired overall outcome strings to dictionaries of required per-state outcomes, e.g.:

outcome_map = {
    "overall_success": {
        "STATE_A": "succeeded",
        "STATE_B": "done",
    }
}

This rule is satisfied when STATE_A returns "succeeded" and STATE_B returns "done". Rules are evaluated after all child threads finish. The first matching rule in iteration order is used.

Methods

Method	C++ Signature	Python Signature	Description
`execute`	`std::string execute( Blackboard::SharedPtr blackboard)`	`def execute(self, blackboard: Blackboard) -> str`	Runs all child states in parallel and returns the resolved outcome.
`cancel_state`	`void cancel_state() override`	`def cancel_state(self) -> None`	Cancels all currently running child states.
`get_states`	`const StateMap &get_states() const`	`def get_states(self) -> dict[str, State]`	Returns the child state map.
`get_outcome_map`	`const OutcomeMap &get_outcome_map() const`	`def get_outcome_map(self) -> dict[str, dict[str, str]]`	Returns the outcome map.
`get_default_outcome`	`const std::string &get_default_outcome() const`	`def get_default_outcome(self) -> str`	Returns the fallback outcome used when no rule matches.
`set_parameter_mappings`	`void set_parameter_mappings( const std::string &state_name, const ParameterMappings &parameter_mappings)`	N/A	Sets parameter mappings for a child state (`child_param -> parent_param`).

Concurrence inherits all State metadata methods.

Example

C++

#include "yasmin/concurrence.hpp"

auto foo_state = std::make_shared<FooState>();
auto bar_state = std::make_shared<BarState>();

auto concurrence_state = std::make_shared<yasmin::Concurrence>(
    yasmin::StateMap{{"FOO", foo_state}, {"BAR", bar_state}},
    "defaulted",
    yasmin::OutcomeMap{
        {"outcome1", {{"FOO", "outcome1"}, {"BAR", "outcome3"}}},
        {"outcome2", {{"FOO", "outcome2"}, {"BAR", "outcome3"}}},
    });

concurrence_state->set_description("Runs FOO and BAR in parallel.");

sm->add_state("CONCURRENT", concurrence_state,
              {{"outcome1", "outcome1"},
               {"outcome2", "outcome2"},
               {"defaulted", "outcome2"}});

Python

from yasmin import Concurrence

foo_state = FooState()
bar_state = BarState()

concurrence_state = Concurrence(
    states={"FOO": foo_state, "BAR": bar_state},
    default_outcome="defaulted",
    outcome_map={
        "outcome1": {"FOO": "outcome1", "BAR": "outcome3"},
        "outcome2": {"FOO": "outcome2", "BAR": "outcome3"},
    },
)
concurrence_state.set_description("Runs FOO and BAR in parallel.")

sm.add_state(
    "CONCURRENT",
    concurrence_state,
    transitions={
        "outcome1": "outcome1",
        "outcome2": "outcome2",
        "defaulted": "outcome2",
    },
)