gabrieltool.statemachine package

Subpackages

• gabrieltool.statemachine.callable_zoo package
  • Subpackages
    • gabrieltool.statemachine.callable_zoo.predicate_zoo package
      • Submodules
      • gabrieltool.statemachine.callable_zoo.predicate_zoo.base module
      • Module contents
    • gabrieltool.statemachine.callable_zoo.processor_zoo package
      • Submodules
      • gabrieltool.statemachine.callable_zoo.processor_zoo.base module
      • gabrieltool.statemachine.callable_zoo.processor_zoo.containerized module
      • gabrieltool.statemachine.callable_zoo.processor_zoo.tfutils module
      • Module contents
  • Submodules
  • gabrieltool.statemachine.callable_zoo.base module
  • Module contents

Submodules

gabrieltool.statemachine.fsm module

Components to Create a Finite State Machine.

See FSM’s wikipedia page for its basics: https://en.wikipedia.org/wiki/Finite-state_machine.

This modules provides components to create, edit, serialize, and deserialize a finite state machine. Below is a list of key concepts.

• State: FSM states represents the status of a cognitive assistant. States

  have Processors, which are executed to analyze the input data when the application is in the state.

• Transitions: Transitions define the conditions (TransitionPredicate) for

  state change and actions (Instruction) to take when changing states.

• Finite State Machine (StateMachine): An FSM is a set of states and

  transitions. Helper functions are provided in the StateMachine class for serialization, deserialization and traversal.

class Instruction(name=None, audio=None, image=None, video=None)

Bases: gabrieltool.statemachine.fsm._FSMObjBase

Instruction to return when a transition is taken.

__init__(name=None, audio=None, image=None, video=None)

Instructions can have audio, image, or video.

Parameters:

• name (string, optional) – Name of the instruction. Defaults to None.
• audio (string, optional) – Verbal instruction in text. Defaults to None.
• image (bytes, optional) – Encoded Image in bytes. Defaults to None.
• video (url string, optional) – Video Url in string. Defaults to None.

from_desc(desc)

Construct an object from its serialized description.

to_desc()

Returned the serialized description of this object as a protobuf message.

class Processor(name=None, callable_obj=None)

Bases: gabrieltool.statemachine.fsm._FSMCallable

Processor specifies how to process input (e.g. an image) in a state.

__init__(name=None, callable_obj=None)

Construct a processor.

Parameters:

• name (string, optional) – Name of the processor. Defaults to None.
• callable_obj (subclass of callable_zoo.CallableBase, optional) – An object whose type is a subclass of callable_zoo.CallableBase. This object is called/executed when there is a new input (e.g. an image). This callable_obj should expect exact one positional argument. Defaults to None.

callable_obj

The callable object to invoke when this object is called.

from_desc(data)

Construct an object from its serialized description.

prepare()

Invoke prepare() method of the callable_obj if it has any.

This prepare method is called when the FSM runner starts executing to give callables an opportunity to initialize themselves.

to_desc()

Returned the serialized description of this object as a protobuf message.

class State(name=None, processors=None, transitions=None)

Bases: gabrieltool.statemachine.fsm._FSMObjBase

A FSM state represents the status of the system.

A state can have many processors and transitions.

__init__(name=None, processors=None, transitions=None)

Construct a FSM state.

Parameters:

• name (string, required) – Name of the State. Each state in a FSM needs to have an unique name.
• processors (list of Processor, optional) – Processor to run on an input in this state. Each processor will be called with exactly one positional argument (input), and should return a dictionary that contains the extracted information. The returned dictionaries from multiple processors will be unioned together to serve as inputs to transition predicates. Defaults to None.
• transitions (list of Transition, optional) – Possible Transitions from this state. Transitions are evaluated one by one in the order of this list. The first transition that satisfies will be taken. Defaults to None.

from_desc()

Do not call this method directly.

State itself does not know enough information to build from its description. The next_state in state’s transitions depends on a FSM. Use StateMachine Helper Class instead.

Raises:NotImplementedError – Always

prepare()

Prepare a state (e.g. initialize all processors and transition predicates.)

This method is called when the FSM runner first starts to give callables an opportunity to initialize themselves.

processors

The list of processors to be executed in this state.

to_desc()

Returned the serialized description of this object as a protobuf message.

transitions

The list of possible transitions to take in this state.

class StateMachine

Bases: object

Helper class to serialize, deserialize, and traverse a state machine.

classmethod bfs(start_state)

Generator for a breadth-first traversal on the FSM.

This method can be used to enumerate states in an FSM.

Parameters:start_state (State) – The start state of the traversal. Yields:State – The current state of the traversal.

classmethod from_bytes(data)

Load a State Machine from bytes.

Parameters:

• data (bytes) – Serialized FSM in bytes. Format is specified in
• wca_state_machine.proto. –

Raises:

ValueError – raised when there are duplicate state names.

Returns:

The start state of the FSM.

Return type:

State

classmethod to_bytes(name, start_state)

Serialize a FSM to bytes.

States in the FSM are discovered using a breadth-first search (see the bfs method in this class).

Parameters:

• name (string) – The name of the FSM.
• start_state (State) – The start state of the FSM.

Raises:

ValueError – raised when there are duplicate state names.

Returns:

Serialized FSM in bytes. Format is defined in wca_state_machine.proto.

Return type:

bytes

class Transition(name=None, predicates=None, instruction=None, next_state=None)

Bases: gabrieltool.statemachine.fsm._FSMObjBase

Links among FSM states that defines state changes and results to return when changing states.

A Transition has the following components:

• transition predicates: The conditions that need to be satisfied to take this transition.
• next_state: The next FSM state to visit after taking the transition.
• instructions: Instructions returned to users when this transition is taken.

__init__(name=None, predicates=None, instruction=None, next_state=None)

Construct a Transition

Parameters:

• name (string, optional) – Name of the transition. Defaults to None.
• predicates (a list of TransitionPredicate, optional) – A list of condition to satisfy. They are daisy-chained (AND) together when evaluating whether this transition takes place. Defaults to None.
• instruction (Instruction, optional) – Instruction to give. Defaults to None.
• next_state (State, optional) – Next state to move to. Defaults to None.

from_desc()

Do not call this method directly.

Transition itself does not know enough information to build from its description. next_state variable depends on a FSM. Use StateMachine Helper Class instead.

Raises:NotImplementedError – Always

predicates

The list of TransitionPredicates.

to_desc()

Returned the serialized description of this object as a protobuf message.

class TransitionPredicate(name=None, callable_obj=None)

Bases: gabrieltool.statemachine.fsm._FSMCallable

Condition for state transition.

TransitionPredicate determines whether a state transition should taken. TransitionPredciate implements the callable interface so that its objects can be evaluated as a function. A state transition is taken when a TransitionPredicate evaluates to True.

__init__(name=None, callable_obj=None)

Construct a transition predicate.

Parameters:

• name (string, optional) – Name of the TransitionPredicate. Defaults to None.
• callable_obj (subclass of callable_zoo.CallableBase, optional) – An object whose type is a subclass of callable_zoo.CallableBase. This object is called/executed when this transition predicate is called to determine whether the current transition should be taken. This callable_obj should expect exact one positional argument of type dictionary, which contains the output of current state’s processors. Defaults to None.

callable_obj

The callable object to invoke when this object is called.

from_desc(data)

Construct an object from its serialized description.

prepare()

Invoke prepare() method of the callable_obj if it has any.

This prepare method is called when the FSM runner starts executing to give callables an opportunity to initialize themselves.

to_desc()

Returned the serialized description of this object as a protobuf message.

gabrieltool.statemachine.instruction_pb2 module

gabrieltool.statemachine.runner module

Finite State Machine Runner.

Runner to run the cognitive assistants that are expressed as state machines.

class BasicCognitiveEngineRunner(engine_name, fsm)

Bases: gabriel_server.cognitive_engine.Engine

A basic Gabriel Cognitive Engine Runner for FSM based cognitive assistants.

This runner will start a Gabriel cognitive engine that follows the logic defined in a FSM. This class is basic as it restricts the sensor input to be images and the instruction output to be audio or images.

__init__(engine_name, fsm)

Construct a Gabriel Cognitive Engine Runner.

Parameters:

• engine_name (string) – Name of the cognitive engine.
• fsm (State) – The start state of an FSM.

handle(from_client)

Do not call directly.

This method is invoked by the gabriel framework when a user input is available.

class Runner(start_state, prepare_to_run=True)

Bases: object

Finite State Machine Runner.

A basic finite state machine runner. Make sure the fsm is constructed fully before creating a runner.

__init__(start_state, prepare_to_run=True)

Construct a FSM runner.

Parameters:

• start_state (State) – The start state of a FSM.
• prepare_to_run (bool, optional) – Whether to call prepare() functions on all state before running. It should be set to true unless debugging. Defaults to True.

feed(data, debug=False)

Feed the FSM an input to get an output.

Parameters:

• data (any) – Input data.
• debug (bool, optional) – Defaults to False.

Raises:

ValueError – when current state is None.

Returns:

Instruction from the FSM.

Return type:

Instruction

gabrieltool.statemachine.wca_state_machine_pb2 module

Module contents

Library to build application logic as a Finite State Machine.

_pb2 modules are generated python modules by Protobuf for serialization. See the proto directory for the serialization formats.