API Reference

`genie_flow`

Classes

`GenieEnvironment`

The GenieEnvironment deals with maintaining the templates registry, rendering templates and invoking Invokers with a data context and a dialogue.

Functions

`register_model(model_key, model_class)`

Register a model class, so it can be stored in the object store. Also registers the model with the given model_key for the API.

Parameters:

Name	Type	Description	Default
`model_key`	`str`	the key at which the genie flow is reachable for the given model_class	required
`model_class`	`Type[BaseModel]`	the class of the model that needs to be registered	required

`GenieFlow`

`GenieFlowContainer`

Bases: DeclarativeContainer

Modules

`app`

Classes

`celery`

Classes

`CeleryManager`

The CeleryManager instance deals with compiling and enqueuing Celery tasks.

Functions

enqueue_task(state_machine, model, target_state)

Create a new Celery DAG and place it on the Celery queue.

The DAG is compiled using the TaskCompiler, the error handler gets assigned, the DAG is enqueued and a new GenieTaskProgress object is persisted.

This is also the point in time where the render_data is created (by using the render_data property of the machine) and therefore frozen. That then becomes the render_data that is used inside the DAG.

Parameters:

Name	Type	Description	Default
`state_machine`	`GenieStateMachine`	the active state machine to use	required
`model`	`GenieModel`	the data model	required
`target_state`	`State`	the state we will transition into	required

Functions

Modules

`compiler`

Classes

TaskCompiler

`progress`

Classes

ProgressLoggingTask

Bases: Task

This is a celery task that logs the progress of a session. It also updates the progress of the session in the session lock manager.

`transition`

Classes

TransitionManager

Functions

before_transition(event_data)

This hook determines how the transition will be conducted. It will set the property transition_type to a tuple containing the source type and the destination type. This hook also determines if and how the event argument should be stored as part of the dialogue. The property dialogue_persistence is set to "NONE", "RAW" or "RENDERED". Finally, this hook also sets the actor_input property to the first argument that was passed with the triggering event.

Parameters:

Name	Type	Description	Default
`event_data`	`EventData`	The event data object provided by the state machine	required

`containers`

`environment`

Classes

`GenieEnvironment`

The GenieEnvironment deals with maintaining the templates registry, rendering templates and invoking Invokers with a data context and a dialogue.

Functions

register_model(model_key, model_class)

Register a model class, so it can be stored in the object store. Also registers the model with the given model_key for the API.

Parameters:

Name	Type	Description	Default
`model_key`	`str`	the key at which the genie flow is reachable for the given model_class	required
`model_class`	`Type[BaseModel]`	the class of the model that needs to be registered	required

`genie`

Classes

`GenieModel`

Bases: VersionedModel

The base model for all models that will carry data in the dialogue. Contains the attributes that are required and expected by the GenieStateMachine such as state and session_id/

This class also carries the dialogue - a list of DialogueElements of the chat so far.

And it carries a number of state-dependent attributes that are important to the progress of the dialogue, such as running_task_id which indicates if there is a currently running task, as well as actor and actor_text, both indicators for the most recent interaction.

This class is a subclass of the pydantic_redis Model class, which makes it possible to persist the values into Reids and retrieve it again by its primary key. The attribute _primary_key_field is used to determine the name of the primary key.

Attributes

current_response property

Return the most recent DialogueElement from the dialogue list.

render_data property

Returns a dictionary containing all data that can be used to render a template.

NOTE We are using the serialize_as_any flag here to make sure that properties in the secondary_storage are also included.

It will contain: - "state_id": The ID of the current state of the state machine - "current_datetime": The ISO 8601 formatted current date and time in UTC - "dialogue" The string output of the current dialogue - all keys and values of the machine's current model

Functions

add_dialogue_element(actor, actor_text)

Add a given actor and actor text to the dialogue.

Parameters:

Name	Type	Description	Default
`actor`	`str`	the name of the actor	required
`actor_text`	`str`	the actor text	required

format_dialogue(target_format)

Apply the given target format to the dialogue of this instance.

get_state_machine_class() classmethod

Property that returns the class of the state machine that this model should be managed by.

record_dialogue_element()

Record the current actor and actor_input into the dialogue.

serialize(compression=False, include=None, exclude=None)

Creates a serialization of the object. Serialization results in a bytes object, containing the schema version number, a compression indicator and the serialized version of the model object. All separated by a ':' character.

Computed fields will be excluded from serialization, except for those explicitly included.

Parameters:

Name	Type	Description	Default
`compression`	`bool`	a boolean indicating whether to use compression or not	`False`
`include`	`IncEx \| None`	fields to include in the serialization	`None`
`exclude`	`IncEx \| None`	fields to exclude from the serialization	`None`

Returns:

Type	Description
`bytes`	a bytes with the serialized version of the model object

upgrade_schema(from_version, model_data) classmethod

Upgrade the data in the model to the new schema version.

NOTE: This method should be overridden by subclasses.

Parameters:

Name	Type	Description	Default
`from_version`	`int`	the schema version to upgrade from	required
`model_data`	`dict`	the data that should be upgraded	required

Returns:

Type	Description
`dict`	the data that fits the current schema version

Raises:

Type	Description
`ValueError`	if the schema version cannot be made compatible with the current schema version

`GenieStateMachine`

Bases: StateMachine

A State Machine class that is able to manage an AI driven dialogue and extract information from it. The extracted information is stored in an accompanying data model (based on the GenieModel class).

Attributes

render_data property

Returns a dictionary containing all data that can be used to render a template.

It will contain: - "state_id": The ID of the current state of the state machine - "state_name": The name of the current state of the state machine - "dialogue" The string output of the current dialogue - all keys and values of the machine's current model

Functions

get_template_for_state(state)

Retrieve the template for a given state. Raises an exception if the given state does not have a template defined.

Parameters:

Name	Type	Description	Default
`state`	`State`	The state for which to retrieve the template for	required

Returns:

Type	Description
`CompositeTemplateType`	The template for the given state

Raises:

Type	Description
`AttributeError`	If this ob`ject does not have an attribute that carries the templates
`KeyError`	If there is no template defined for the given state

`model`

Modules

`api`

Classes

AIResponse

Bases: GenieMessageWithActions

The response that results from sending an event and the model instance's state machine to transition into the next state.

AIStatusResponse

Bases: GenieMessageWithActions

The GenieMessage that represents the status of a background task that may run for the model object that belongs to a session.

EventInput

Bases: GenieMessage

An event with accompanying information that is sent to progress the state machine that belongs to a session.

GenieMessage

Bases: BaseModel, ABC

The base class for any message that is exchanged through the endpoints.

GenieMessageWithActions

Bases: GenieMessage, ABC

The GenieMessage that also carries a list of events that can be sent, given the current state of the model instance.

`dialogue`

Classes

DialogueElement

Bases: BaseModel

An element of a dialogue. Typically, a phrase that is output by an originator.

`secondary_store`

Classes

SecondaryStore

Bases: RootModel[dict[str, VersionedModel]]

Represents a secondary data storage model that acts as a dict of str to VersionedModel instances. It tracks the state of its items for persistence purposes, ensuring that only values that are marked as NEW_OBJECT are stored.

Attributes

deleted_keys property

Returns a set of keys that are marked as deleted

has_deleted_values property

Does this SecondaryStore have any deleted values?

has_unpersisted_values property

Does this SecondaryStore have any unpersisted values?

unpersisted_values property

Returns a dictionary of keys and values that are marked as new

Functions

from_retrieved_values(retrieved_values) classmethod

Create a SecondaryStore from retrieved values. This ensures that the state of all properties is set to RETRIEVED_OBJECT.

Parameters:

Name	Type	Description	Default
`retrieved_values`	`dict[str, VersionedModel]`	a dictionary that this SecondaryStore should encapsulate	required

Returns:

Type	Description
`SecondaryStore`	a new SecondaryStore with the retrieved values as root values, and all states set to RETRIEVED_OBJECT

from_serialized(payloads) classmethod

Create a SecondaryStore from serialized values. This ensures that the state of all properties states are set to RETRIEVED_OBJECT.

Parameters:

Name	Type	Description	Default
`payloads`	`dict[str, bytes]`	a dictionary where the values for each key are serialized objects	required

Returns:

Type	Description
`SecondaryStore`	a new SecondaryStore with the retrieved values as root values, and all states set to RETRIEVED_OBJECT

mark_persisted(keys)

Marks the provided keys as persisted in the internal state dictionary. If any key is already marked as persisted, a KeyError is raised.

Parameters:

Name	Type	Description	Default
`keys`	`str \| list[str]`	A string representing a single key or a list of strings representing multiple keys to be marked as persisted.	required

Raises:

Type	Description
`KeyError`	If attempting to mark a key as persisted when it is already marked as such.

unpersisted_serialized(compression)

Serializes unpersisted values in the instance to a dictionary, encoding them with the proper format and optionally applying compression.

The function iterates over the unpersisted_values attribute, retrieves the fully qualified name (FQN) of each value's class, serializes the value itself, and combines the FQN with the serialized data. It then stores the result in a dictionary where keys are the original keys, and values are the encoded serialized results.

Parameters:

Name	Type	Description	Default
`compression`	`bool`	Flag indicating whether to apply compression during serialization.	required

Returns:

Type	Description
`dict[str, bytes]`	A dictionary mapping the original keys to the encoded serialized data.

Functions

`versioned`

Classes

VersionedModel

Bases: BaseModel

A base class for models that have a schema version.

This model provides built-in serialization and deserialization capabilities:

Serialization: Converts model instances to bytes format with schema versioning and optional compression
Deserialization: Restores model instances from bytes, handling schema version compatibility through upgrades
Schema versioning: Ensures data compatibility across different model versions through version tracking

Functions

serialize(compression=False, include=None, exclude=None)

Creates a serialization of the object. Serialization results in a bytes object, containing the schema version number, a compression indicator and the serialized version of the model object. All separated by a ':' character.

Computed fields will be excluded from serialization, except for those explicitly included.

Parameters:

Name	Type	Description	Default
`compression`	`bool`	a boolean indicating whether to use compression or not	`False`
`include`	`IncEx \| None`	fields to include in the serialization	`None`
`exclude`	`IncEx \| None`	fields to exclude from the serialization	`None`

Returns:

Type	Description
`bytes`	a bytes with the serialized version of the model object

upgrade_schema(from_version, model_data) classmethod

Upgrade the data in the model to the new schema version.

NOTE: This method should be overridden by subclasses.

Parameters:

Name	Type	Description	Default
`from_version`	`int`	the schema version to upgrade from	required
`model_data`	`dict`	the data that should be upgraded	required

Returns:

Type	Description
`dict`	the data that fits the current schema version

Raises:

Type	Description
`ValueError`	if the schema version cannot be made compatible with the current schema version

`mongo`

Classes

`session`

Classes

`SessionManager`

A SessionManager instance deals with the lifetime events against the state machine of a session. From conception (through a start_session call), to handling events being sent to the state machine.

Functions

create_new_session(model_key, user_info=None)

Create a new session. This method creates a new session id (ULID), creates a model instance of the given model class, initiates a state machine for that model instance and finally persists the model to Redis.

The state machine is initiated with the new_session flag true, forcing it to place the state machine into the initial state and setting the appropriate values of the new model instance.

The method then returns the appropriate AIResponse object with the (initial) response and the actions that the state machine can take from this initial state.

Parameters:

Name	Type	Description	Default
`model_key`	`str`	the key under which the model class is registered	required
`user_info`	`Optional[User]`	optional User instance containing information about the current user	`None`

Returns:

Type	Description
`AIResponse`	an instance of `AIResponse` with the appropriate values

get_model(model_key, session_id)

Retrieve the entire model instance that belongs to the given session id. Obtains a lock on the session to ensure consistency of the model values.

Parameters:

Name	Type	Description	Default
`model_key`	`str`	the key under which the model class is registered	required
`session_id`	`str`	the session id to retrieve the model instance for	required

Returns:

Type	Description
`GenieModel`	the model instance that belongs to the given session id

get_task_state(model_key, session_id)

Retrieves an instance of the model object and returns if that object has any running tasks against it. It obtains a lock on the given session id to ensure consistency of the model values.

The AIStatusResponse that this method returns indicates if the task is currently running, or, if it is no longer running, what the possible next actions are.

Parameters:

Name	Type	Description	Default
`model_key`	`str`	the key under which the model class is registered	required
`session_id`	`str`	the id of the session that the model instance belongs to	required

Returns:

Type	Description
`AIStatusResponse`	an instance of `AIStatusResponse`, indicating if the task is ready and what possible next actions can be sent in the current state of the model.

process_event(model_key, event)

Process incoming events. Claims a lock to the model instance that the event refers to and checks the event. If the event is a poll event, handling is performed by the _handle_poll method. If not, this method returns the result of processing the event.

Parameters:

Name	Type	Description	Default
`model_key`	`str`	the key under which the model class is registered	required
`event`	`EventInput`	the event to process	required

Returns:

Type	Description
`AIResponse`	an instance of `AIResponse` with the appropriate values

start_ephemeral_session(model_key, event, event_input, user_info=None)

Create a new ephemeral session. This method creates a new session id (ULID), creates a model and initiates a state machine for that model instance. It then immediately sends the event to the state machine and returns the appropriate nex actions that can be taken from the current state.

Parameters:

Name	Type	Description	Default
`model_key`	`str`	the key under which the model class is registered	required
`event`	`str`	the event to send to the state machine	required
`event_input`	`str`	the input to the event	required
`user_info`	`Optional[User]`	optional User instance containing information about the current user	`None`

Returns:

Type	Description
`AIResponse`	an instance of `AIResponse` with the appropriate values

`session_lock`

Classes

`SessionLockManager`

Classes

ModelContextManager

Functions

__init__(lock_manager, session_id, model_class)

A Context Manager for obtaining a locked GenieModel. This context manager obtains a lock for a particular session, then retrieves the GenieModel from store. Upon the exit of the context, that GenieModel is stored back into store and the lock is released.

Functions

__init__(redis_object_store, redis_lock_store, redis_progress_store, object_expiration_seconds, lock_expiration_seconds, progress_expiration_seconds, compression, application_prefix)

The SessionLockManager manages the session lock as well as the retrieval and persisting of model objects. When changes are (expected to be) made to the model of a particular session, this manager deals with locking multithreaded access to it when it retrieves from Store, and before it gets written back to it.

Parameters:

Name	Type	Description	Default
`redis_object_store`	`Redis`	The Redis object store	required
`redis_lock_store`	`Redis`	The Redis lock store	required
`redis_progress_store`	`Redis`	The Redis progress store	required
`object_expiration_seconds`	`int`	The expiration time for objects in seconds	required
`lock_expiration_seconds`	`int`	The expiration time of the lock in seconds	required
`progress_expiration_seconds`	`int`	The expiration time of the progress object in seconds	required
`compression`	`bool`	Whether or not to compress the model when persisting	required
`application_prefix`	`str`	The application prefix used to create the key for an object	required

get_model(session_id, model_class)

Retrieve the GenieModel for the object for the given session_id. This retrieval is done inside a locked context, so no writing of the GenieModel can happen when this retrieval is done.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	The session id that the object in question belongs to	required
`model_class`	`str \| Type[GenieModel]`	The GenieModel class to retrieve or the fqn of the class	required

Returns:

Type	Description
`GenieModel`	The GenieModel object for the given `session_id`

store_model(model)

Store a model into the object store. Also stores the secondary storage of the model. Storing happens inside a locked context, so no reading or writing of the GenieModel can happen when this method is executing.

Parameters:

Name	Type	Description	Default
`model`	`GenieModel`	the object to store	required

Functions

`utils`

Functions

`get_class_from_fully_qualified_name(class_path)`

Get the actual class of the given fully qualified name.

Parameters:

Name	Type	Description	Default
`class_path`		The FQN of the class to retrieve	required

Returns:

Type	Description
	The actual class that is referred to by the given FQN

`get_fully_qualified_name_from_class(o)`

Creates the fully qualified name of the class of the given object.

Parameters:

Name	Type	Description	Default
`o`	`Any`	The object of which to obtain the FQN form	required

Returns:

Type	Description
`str`	The fully qualified name of the class of the given object

`get_module_from_fully_qualified_name(class_fqn)`

Get the module of the given fully qualified name of a class.

Parameters:

Name	Type	Description	Default
`class_fqn`	`str`	The FQN of a class to retrieve the module from	required

Returns:

Type	Description
`ModuleType`	The module that the class of the given FQN is in