Skip to content

autonomy.analyse.abci.app_spec

Generates the specification for a given ABCI app in YAML/JSON/Mermaid format.

JSON output is deprecated and will be removed in a future release; use YAML or Mermaid instead.

validate_fsm_spec

def validate_fsm_spec(data: Dict) -> None

Validate FSM specificaiton file.

DFASpecificationError Objects

class DFASpecificationError(Exception)

Simple class to raise errors when parsing a DFA.

FSMSpecificationLoader Objects

class FSMSpecificationLoader()

FSM specification loader utilities.

OutputFormats Objects

class OutputFormats()

Output formats.

from_yaml

@staticmethod
def from_yaml(file: Path) -> Dict

Load from yaml.

from_json

@staticmethod
def from_json(file: Path) -> Dict

Load from json.

load

@classmethod
def load(cls, file: Path, spec_format: str = OutputFormats.YAML) -> Dict

Load FSM specification.

dump_json

@staticmethod
def dump_json(dfa: "DFA", file: Path) -> None

Dump to a json file (deprecated).

JSON output is deprecated; prefer YAML or Mermaid. The DeprecationWarning is emitted by dump() so that stacklevel always points at the external caller.

Arguments:

  • dfa: DFA object to serialize.
  • file: Output file path.

dump_yaml

@staticmethod
def dump_yaml(dfa: "DFA", file: Path) -> None

Dump to a yaml file.

dump_mermaid

@staticmethod
def dump_mermaid(dfa: "DFA",
                 file: Path,
                 abci_app_cls: Optional[_AbciAppLike] = None,
                 dev_skills: Optional[Set[str]] = None) -> None

Dumps this DFA spec. to a file in Mermaid format.

When abci_app_cls is supplied AND its rounds span more than one sub-app, the diagram collapses every THIRD-PARTY sub-app into a single node (one box per sub-app), and leaves dev sub-apps expanded with their atomic rounds. dev_skills is the set of skill names the local repo authored (typically derived from the dev section of packages/packages.json); any sub-app not in this set is treated as third-party and collapsed.

Falls back to the flat per-round diagram when abci_app_cls is None, when dev_skills is empty or None (i.e. no packages.json info available), or when all rounds belong to a single sub-app.

Arguments:

  • dfa: DFA object to render.
  • file: Output file path.
  • abci_app_cls: Optional composed AbciApp class used to classify rounds by sub-app for the composition-aware view.
  • dev_skills: Optional set of dev skill names (from packages.json); sub-apps not in this set are collapsed.

dump

@classmethod
def dump(cls,
         dfa: "DFA",
         file: Path,
         spec_format: str = OutputFormats.YAML,
         abci_app_cls: Optional[_AbciAppLike] = None,
         dev_skills: Optional[Set[str]] = None) -> None

Dumps this DFA spec. to a file in YAML/JSON/Mermaid format.

abci_app_cls and dev_skills are only used by the Mermaid renderer to collapse third-party sub-apps into single nodes while keeping dev sub-apps expanded (see dump_mermaid). Other formats ignore them.

Arguments:

  • dfa: DFA object to serialize.
  • file: Output file path.
  • spec_format: One of OutputFormats.YAML, JSON, or MERMAID.
  • abci_app_cls: Optional composed AbciApp class (Mermaid only).
  • dev_skills: Optional set of dev skill names (Mermaid only).

DFA Objects

class DFA()

Simple specification of a deterministic finite automaton (DFA).

__init__

def __init__(label: str, states: Set[str], default_start_state: str,
             start_states: Set[str], final_states: Set[str],
             alphabet_in: Set[str], transition_func: Dict[Tuple[str, str],
                                                          str])

Initialize DFA object.

validate_naming_conventions

def validate_naming_conventions() -> None

Validate state names to see if they follow the naming conventions below

  • A round name should end with Round
  • ABCI app class name should end with AbciApp

is_transition_func_total

def is_transition_func_total() -> bool

Outputs True if the transition function of the DFA is total.

A transition function is total when it explicitly defines all the transitions for all the possible pairs (state, input_symbol). By convention, when a transition (state, input_symbol) is not defined for a certain input_symbol, it will be automatically regarded as a self-transition to the same state.

Returns:

True if the transition function is total. False otherwise.

get_transitions

def get_transitions(input_sequence: List[str]) -> List[str]

Runs the DFA given the input sequence of symbols, and outputs the list of state transitions.

parse_transition_func

def parse_transition_func() -> Dict[str, Dict[str, str]]

Parse the transition function from the spec to a nested dictionary.

__eq__

def __eq__(other: object) -> bool

Compares two DFAs

generate

def generate() -> Dict[str, Any]

Retrieves an exportable representation for YAML/JSON dump of this DFA.

load

@classmethod
def load(
        cls,
        file: Path,
        spec_format: str = FSMSpecificationLoader.OutputFormats.YAML) -> "DFA"

Loads a DFA JSON specification from file.

abci_to_dfa

@classmethod
def abci_to_dfa(cls, abci_app_cls: Any, label: str = "") -> "DFA"

Translates an AbciApp class into a DFA.

check_unreferenced_events

def check_unreferenced_events(abci_app_cls: Any) -> List[str]

Check for unreferenced events in the AbciApp.

For every round in the transition function, computes the set of events the round can effectively emit and compares it to the events the FSM expects. An event is considered emitted if it is either:

  1. The effective value of a *_event class attribute, resolved leaf-first through the MRO (so an override masks the parent value).
  2. Referenced as Event.X in the source of the round or any of its non-builtin superclasses, with *_event = Event.X attribute definitions stripped out (those are covered by case 1, and a parent-class definition would otherwise be reported even after the subclass overrides the attribute). Each round resolves its own Event enum from its leaf-most *_event attribute, so names absent from that enum are dropped to avoid cross-skill collisions (e.g. market_manager.Event.FETCH_ERROR referenced from a parent class living in a different skill).
  3. Declared via a # fsm-specs: returns(EVENT_NAME, ...) annotation on the round class -- the supported syntax for rounds that build events dynamically (e.g. Event(payload_value)).

Arguments:

  • abci_app_cls: AbciApp to check unreferenced events.

Returns:

List of error strings.