Exposing State Documentation / Metadata for Editor Integration

[Maik13579]

Hi,

first of all thanks for creating and maintaining YASMIN.

While working with the editor and adding custom states, I noticed that a state currently only exposes its outcomes, but there is no standardized way to provide additional information like:

• a short description of the state
• which blackboard keys the state reads
• which blackboard keys the state writes

For Python states this could maybe be solved by reading the class docstring, so developers could document their states directly in code and the editor could display it.

Example:

class PlanPath(State):
    """
    Plans a path from start to goal.

    Reads:
        goal

    Writes:
        path
   """

For C++ states there is no equivalent mechanism at runtime (at least I’m not aware of one). One option could be to read the description from the plugin.xml, since plugins already contain metadata and it would avoid adding additional documentation directly in the code.

For the blackboard keys, another idea could be to extend the state constructor to optionally include the keys used by the state, for example something like:

State(
  const std::vector<std::string>& outcomes,
  const std::vector<std::string>& input_keys,
  const std::vector<std::string>& output_keys
);

This would allow tools like the editor to:

• show documentation for states
• visualize blackboard data flow
• potentially validate blackboard keys

Curious what your thoughts are on this and whether something like this would fit into YASMIN.

If there are no existing plans for something like this, I’d also be happy to try implementing it and open a PR.

Thanks!

[mgonzs13]

Hi @Maik13579, I have also been thinking about this some time ago. My idea on this was to use new attributes for description and blackboard keys in the C++ State and then propagate it to the Python version using the binding. The blackboard keys could also include some default values to avoid cases when the blackboard does not contain them.

[Maik13579]

Maybe something along these lines:

namespace yasmin
{

using BlackboardValue = std::variant<int, double, bool, std::string>;

struct BlackboardKeyInfo
{
  std::string name;
  bool has_default{false};
  BlackboardValue default_value{};

  BlackboardKeyInfo() = default;

  explicit BlackboardKeyInfo(std::string key_name)
  : name(std::move(key_name))
  {
  }

  BlackboardKeyInfo(std::string key_name, BlackboardValue value)
  : name(std::move(key_name)), has_default(true), default_value(std::move(value))
  {
  }
};

struct StateMetadata
{
  std::string description;
  std::vector<BlackboardKeyInfo> input_keys;
  std::vector<BlackboardKeyInfo> output_keys;
};

}  // namespace yasmin

Then each state could provide its metadata through something like a createMetadata() function:

class PlanPathState : public yasmin::State
{
public:
  PlanPathState()
  : yasmin::State({"succeeded", "aborted"}, createMetadata())
  {
  }

  std::string execute(yasmin::Blackboard & blackboard) override;

private:
  static yasmin::StateMetadata createMetadata()
  {
    return {
      "Plans a path from start to goal.",
      {
        yasmin::BlackboardKeyInfo("goal"),
        yasmin::BlackboardKeyInfo("planner_id", std::string("astar"))
      },
      {
        yasmin::BlackboardKeyInfo("path")
      }
    };
  }
};

This would keep the metadata pretty compact in user code while still making it easy for tools (like the editor) to access things like the description and blackboard keys.

I’ve never worked much with Python bindings though, so I’m not sure if an interface like this would translate nicely to Python or if there would be a better pattern there.

[mgonzs13]

Yes, something similar to that solution, using std::shared_ptr<void> default_value{}; for the default value, and maybe also adding a description field to the BlackboardKeyInfo. I would also create new methods to add and get the metadata instead of modifying the constructors, at least for an initial version.

[mgonzs13]

@Maik13579, I have uploaded an initial version to a new branch. The editor could also be updated to show the new metadata. Besides, more changes could be made to the factory and the XML format to also add the default values.

[Maik13579]

BlackboardKeyInfo currently has no clean API for attaching human-readable descriptions to keys.

At the moment, the constructors mainly support:

• BlackboardKeyInfo(name)
• BlackboardKeyInfo(name, default_value)

What is missing is a stable and convenient way to express:

• name + description
• name + default_value + description

An attempt to add such constructor overloads caused problems (segfault when starting yasmin_editor).

[Maik13579]

Currently, BlackboardKeyInfo allows default values for both input_keys and output_keys.
For input keys this makes sense because missing values are injected into the blackboard before the state executes.

However, for output keys the situation is less clear: output values are typically expected to be produced by the state itself.

Does it make sense for output keys to support default values as well, or should defaults be limited to input keys only?

[mgonzs13]

Hi @Maik13579, thanks for the review. I also think the output should not have default value, though I have been playing with it. Could you make a PR with those changes?

[Maik13579]

Added the PR, but keep in mind that it throws a segfault in its current version

[Maik13579]

The current issue is that the API for add_input_key in C++ has a fundamental ambiguity when using std::string as the second argument.

Right now, we have the following overloads:

void add_input_key(const std::string &key_name,
                   const std::string &description);

template <typename T>
void add_input_key(const std::string &key_name, T default_value);

The issue appears when calling something like:

add_input_key("label", std::string("hello"));

From a user perspective, this is clearly intended to set a default value of type std::string.
However, from the compiler’s perspective, both overloads are equally valid:

• It can be interpreted as a description
• Or as a default value

In practice, the non-template overload is preferred, so "hello" is treated as a description instead of a default value.

We could make description mandatory:

void add_input_key(const std::string &key_name,
                   const std::string &description);

template <typename T>
void add_input_key(const std::string &key_name, const std::string &description ,T default_value);

Whats your opinion on this?

[mgonzs13]

Making description mandatory sounds good to me. Thanks for the work.