Python SDK

The Genius Python SDK enables users to build probabilistic models and query them directly in Python. This guide shows an overview of the different types of features provided by the SDK. For complete documentation visit the Python SDK reference section.

Installing the Python SDK

pip install genius-client-sdk

Importing

The following lines can be used to import the main classes used in the SDK:

Genius model: from genius_client_sdk.model import GeniusModel
Genis agent: from genius_client_sdk.agent import GeniusAgent
POMDP model: from genius_client_sdk.pomdp import POMDPModel

Additional helper functions can be imported through the utils module:

from genius_client_sdk.utils import (
    control_map,
    flatten_nested_list,
    get_policy_space,
    onehot,
    plot_categorical,
    policy_map,
)

Extra import

Other imported modules used by this quickstart

import logging
import numpy as np

Connecting a Genius agent

Authentication

Before you begin, you need to choose an authentication method in order to connect to your Genius agent. These are the available options:

1. API Key

After importing Genius SDK in your python environment, you need to set up this credential:

from genius_client_sdk.auth import ApiKeyConfig

auth_config = ApiKeyConfig(api_key="<YOUR_API_KEY>")

2.Bearer Token ^{(not available yet)}

3.OAuth2 Client Credential ^{(not available yet)}

Agent

Once you have installed the Python SDK, you must connect it to a Genius agent. To connect to the Genius agent you must use agent's URL that was provided to you. For the purpose of example we will assume that the agent's URL is https://my.agent.hostname. When you initialize the agent, pass in the HTTP protocol, hostname, and port as follows:

from genius_client_sdk.agent import GeniusAgent

agent = GeniusAgent(
        agent_http_protocol="https",
        agent_hostname="my.agent.hostname",
        agent_port=443,
        auth_config=auth_config)

Usually, the agent will raise an AssertionError or HTTP 401 if the credential is not valid.

Additionally, it is recommended to configure the logging so only necessary information is output:

# Configure logging so we can see output from the library without extra noise
for handler in logging.root.handlers[:]:
    logging.root.removeHandler(handler)
logging.basicConfig(level=logging.INFO, format="%(message)s")

Building a factor graph in Python

Genius models must be uploaded in JSON model format. One can type out the model in JSON format directly or, more conveniently, construct this JSON model in Python. We now demonstrate how to build a factor graph in Python using the GeniusModel class with the SDK, focusing on the simple sprinkler model introduced in the knowledge center:

After importing the GeniusModel class it must be initialized.

model = GeniusModel(agent_url=agent.agent_url)
model.vfg

VFG(version='0.5.0', metadata=None, variables={}, factors=[], visualization_metadata=None)

At this point the model.vfg instance variable is empty because we have not added any variables or factors. The first step to building the model is to add the variables using the add_variable() class method. If you try to add factors first you will get an error. The variables must be specified with a name and the categories or values associated with that variable. We replicate the structure of the variables in the sprinkler model below.

model.add_variable(name="cloudy", values=["no", "yes"])
model.add_variable(name="rain", values=["no", "yes"])
model.add_variable(name="sprinkler", values=["off", "on"])
model.add_variable(name="wet_grass", values=["no", "yes"])
model.vfg

VFG(version='0.5.0', metadata=None, variables={'cloudy': Variable(root=DiscreteVariableNamedElements(elements=['no', 'yes'], role=None)), 'rain': Variable(root=DiscreteVariableNamedElements(elements=['no', 'yes'], role=None)), 'sprinkler': Variable(root=DiscreteVariableNamedElements(elements=['off', 'on'], role=None)), 'wet_grass': Variable(root=DiscreteVariableNamedElements(elements=['no', 'yes'], role=None))}, factors=[], visualization_metadata=None)

If you wish to add a latent variable to your model, you can pass in an optional role="latent" argument to model.add_variable(). This will indicate to Genius that the variable is latent and therefore not available in any datasets used for training (parameter learning).

Now our variables have been added to the model so it is time to add factors. To add a factor you must specify:

A target variable for this factor
The parent(s) of this target variable (if any)
The probabilities associated with the target and parent variables.

In the sprinkler example there are four possible factors. The table below lists the different target variables and parents for each factor:

Factor

Target

Parent(s)

$P(cloudy)$

$cloudy$

None

$P(rain \mid cloudy)$

$rain$

$cloudy$

$P(sprinkler \mid cloudy)$

$sprinkler$

$cloudy$

$P(wetGrass \mid rain, cloudy)$

$wetGrass$

$rain, cloudy$

The first factor is a marginal distribution and thus has no parent as dependencies. The other distributions all have one or more parent variable that it depends on. The probability table associated with each factor is shown in the image above. First we specify the probabilities:

The dimensions of the probability table for a factor must correspond to the order of the variables that are associated with this factor. For example, if the factor is $P(wetGrass \mid rain, cloudy)$ then the dimensions of the factor probability table will have three dimensions. The first dimension will be the target variable ( $wetGrass$ ), the second dimension will be the $rain$ and the third dimension will be $cloudy$ . This means that the target variable is always on the rows and the additional dimensions correspond to the parent variables in order.

F1_probs = np.array([0.5, 0.5])

F2_probs = np.array([[0.5, 0.9], 
                     [0.5, 0.1]])

F3_probs = np.array([[0.8, 0.2], 
                     [0.2, 0.8]])

F4_probs = np.array(
    [[[1.0, 0.1], [0.1, 0.01]], 
     [[0.0, 0.9], [0.9, 0.99]]]
)

Next, we add the probabilities, targets, and parents to the factor graph.

It is also possible to add "roles" to each factor which indicate a special function for this factor. This achieved through the role argument to the add_factor() method which accepts a string. These roles come into play when creating active inference models. The four possible role types are: "NoRole", "Transition", "Preference", "Likelihood" and "InitialStatePrior".

model.add_factor(values=F1_probs, target="cloudy", parents=None)
model.add_factor(values=F2_probs, target="sprinkler", parents=["cloudy"])
model.add_factor(values=F3_probs, target="rain", parents=["cloudy"])
model.add_factor(values=F4_probs, target="wet_grass", parents=["sprinkler", "rain"])

model.vfg

VFG(version='0.5.0', metadata=None, variables={'cloudy': Variable(root=DiscreteVariableNamedElements(elements=['no', 'yes'], role=None)), 'rain': Variable(root=DiscreteVariableNamedElements(elements=['no', 'yes'], role=None)), 'sprinkler': Variable(root=DiscreteVariableNamedElements(elements=['off', 'on'], role=None)), 'wet_grass': Variable(root=DiscreteVariableNamedElements(elements=['no', 'yes'], role=None))}, factors=[Factor(variables=['cloudy'], distribution=<Distribution.Categorical: 'categorical'>, counts=None, values=array([0.5, 0.5]), role=None), Factor(variables=['sprinkler', 'cloudy'], distribution=<Distribution.CategoricalConditional: 'categorical_conditional'>, counts=None, values=array([[0.5, 0.9], [0.5, 0.1]]), role=None), Factor(variables=['rain', 'cloudy'], distribution=<Distribution.CategoricalConditional: 'categorical_conditional'>, counts=None, values=array([[0.8, 0.2], [0.2, 0.8]]), role=None), Factor(variables=['wet_grass', 'sprinkler', 'rain'], distribution=<Distribution.CategoricalConditional: 'categorical_conditional'>, counts=None, values=array([[[1. , 0.1 ], [0.1 , 0.01]], [[0. , 0.9 ], [0.9 , 0.99]]]), role=None)], visualization_metadata=None)

Before proceeding, it is important to validate your model to ensure that the structure and data types are correct. This can be achieved with the validate() class method:

model.validate()

Model validated successfully. []

Now save the model with the save() class method, specifying the outpath.

model.save(out_path="sprinkler.json")

Finally, we can also visualize the model. This is a simple visual just to get an idea of what the factor graph looks like. For a better view it is recommended that the model is exported to JSON and loaded into the model editor.

model.visualize()

Exploring a Genius model's structure

The GeniusModel class comes equipped with a number of convenience functions that can be used to investigate the structure of the model. Running get_variable_names() will list all variables in the model:

model.get_variable_names()

['rain', 'sprinkler', 'wet_grass', 'cloudy']

Running get_variable_values(variable_id) and passing in a variable string from the list above will return the categories associated with that variable:

model.get_variable_values(variable_id="cloudy")

['no', 'yes']

model.get_variable_values(variable_id="sprinkler")

['off', 'on']

Running get_factor_attributes(factor_id, attribute) and passing in an integer for the factor id of interest and the attribute to return will the desired properties of the factor. There are four possible attributes: the variables associated with the factor, the distribution type for the factor, the probability values associated with the factor, and the factor's role. In many cases a factor may have no role but in some cases, such as POMDP models, the factor may have a specific role of interest such as "likelihood" or (state) "transition".

model.get_factor_attributes(factor_id=0, attribute="variables")

['cloudy']

model.get_factor_attributes(factor_id=2, attribute="distribution")

<Distribution.CategoricalConditional: 'categorical_conditional'>

model.get_factor_attributes(factor_id=3, attribute="values")

array([[[1. , 0.1 ], [0.1 , 0.01]], [[0. , 0.9 ], [0.9 , 0.99]]])

model.get_factor_attributes(factor_id=1, attribute="role")

None

Creating a Genius agent

To create a Genius agent, first initialize the class and connect to the agent.

agent = GeniusAgent()

Loading and viewing a model

There are two options available for loading a model.

Load a model from a JSON file path

To upload a model from a JSON file path, first ensure that your model is in the correct format. If JSON model is not available create one first in either the model editor or the Python SDK and then exported to JSON. Then run the following:

agent.load_model_from_json(json_path="sprinkler.json")

Load a model from an instance of GeniusModel

If you have already created a model using the GeniusModel class, as shown in the Building a Factor Graph in Python section above, then this model can be loaded into the Genius agent as follows:

agent.load_genius_model(model=model)

To view the loaded model run:

agent.log_model()

{"version": "0.5.0","metadata": null,"variables": {"cloudy": {"elements": ["no","yes"],"role": null},"rain": {"elements": ["no","yes"],"role": null},"sprinkler": {"elements": ["off","on"],"role": null}, ... }],"visualization_metadata": null }

You can also pass in the optional argument summary=True to view a summary of the model contents in a more readable format:

agent.log_model(summary=True)

Model contents: 4 variables: ['cloudy', 'rain', 'sprinkler', 'wet_grass'] 4 factors: [['cloudy'], ['rain', 'cloudy'], ['sprinkler', 'cloudy'], ['wet_grass', 'sprinkler', 'rain']] Factor probabilities: [0.5 0.5]

[[0.5 0.9] [0.5 0.1]]

[[0.8 0.2] [0.2 0.8]]

[[[1. 0.1 ] [0.1 0.01]]

[[0. 0.9 ] [0.9 0.99]]]

Probabilistic inference

To perform probabilistic inference, use the infer(variable_id, evidence) method of the GeniusAgent class. This function can be used for conditioning or Bayesian inference. To infer the probability that the grass is wet given the evidence that it is raining and the sprinkler is off:

variable_id = "wet_grass"
evidence = {"rain": "yes", "sprinkler": "off"}

inference_result = agent.infer(variables=variable_id, evidence=evidence)

{'no': 0.10000000372529039, 'yes': 0.8999999962747096}

To perform Bayesian inference to invert a dependency relationship the same method is used:

variable_id = "cloudy"
evidence = {"wet_grass": "yes", "rain": "yes"}

inference_result = agent.infer(variables=variable_id, evidence=evidence)

{'no': 0.20628684298847688, 'yes': 0.7937131570115231}

Parameter learning

Parameter learning uses the learn() method of the GeniusAgent class. To perform parameter learning we have two options for input:

Import a CSV file
Provide the data in code

Parameter learning with CSV data

To use an existing CSV file as data for parameter learning first ensure that it is properly formatted with variable names as headers and rows of observations for each category corresponding to the variable. See the section on CSV data format for more details. Then run:

learning_result = agent.learn(csv_path="sprinkler_data.csv")

Learning successful. Use log_model() to see updated probabilities.

Parameter learning from Python

In the second instance, learning requires a list of strings for each variable name and a nested list of observations corresponding to each variable. For example:

variables = ["cloudy", "rain", "sprinkler", "wet_grass"]
observations = [["yes", "yes", "on", "yes"], ["no", "no", "off", "no"]]

learning_result = agent.learn(variables=variables, observations=observations)

Learning successful. Use log_model() to see updated probabilities.

There is no direct output from learning but the updated probabilities may be viewed using agent.log_model() or inspecting the dict stored in the agent.model instance variable.

Active inference

Active inference uses a special type of model known as a partially observable Markov decision process (POMDP). To construct a POMDP, one needs to define specific types of variables and factors. This is described in more detail in the active inference tutorial and agent navigation examples.

Creating a POMDP model

To create a POMDP model in the Python SDK we need to specify the following four factors:

Likelihood
Transition
State prior (optional)
Preference

In the active inference literature, these factors are usually referred to by single letter names for convenience. The likelihood is referred to as A, the state-transitions as B, the preferences as C, and the state prior as D.

We also need to specify the following three variables:

State
Observation (data)
Action

We are free to name these variable as we wish so that they correspond to the problem at hand. First, we initialize the POMDPModel() class so we can construct the POMDP model.

It is also possible to create a POMDP model with the GeniusModel class. However, the POMDPModel class provides some convenient helper functions to help construct the model.

model = POMDPModel()

Below, we show an example of a POMDP construction for the agent navigation example. First, we define some generic states and observations categories as the numbers 0-8.

n_states = 9
n_obs = 9
states = [str(s) for s in list(np.arange(n_states))]
observations = [str(s) for s in list(np.arange(n_obs))]

We also define the possible actions the agent can take and the number of possible actions:

actions = ["UP", "DOWN", "LEFT", "RIGHT", "STAY"]
n_actions = len(actions)

We will name the states as position and keep the names of the observations and actions as observation and action respectively. Now we add these variables to the model

model.add_state_variable(name="position", values=states)
model.add_observation_variable(name="observation", values=observations)
model.add_action_variable(name="action", values=actions)

First, we construct the likelihood. The likelihood connects states (position in this example) to observations.

likelihood_vars = ["observation", "position"]
likelihood_probs = np.array(
    [
        [1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
        [0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
        [0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
        [0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0],
        [0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0],
        [0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
        [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
        [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0],
        [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
    ]
)

model.add_likelihood_factor(
    values=likelihood_probs, target=likelihood_vars[0], parents=likelihood_vars[1:]
)

The state transition connects the state at the current time step (position) with the state at the next time step (position) and also depends on the action performed.

transition_vars = ["position", "position", "action"]
transition_probs = np.array(
    [
        [
            [1.0, 0.0, 0.0, 1.0, 1.0],
            [0.0, 0.0, 0.0, 1.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
        ],
        [
            [0.0, 1.0, 0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0, 0.0, 1.0],
            [0.0, 0.0, 0.0, 1.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
        ],
        [
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 0.0, 0.0, 0.0],
            [1.0, 1.0, 0.0, 0.0, 1.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
        ],
        [
            [0.0, 0.0, 1.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 1.0, 1.0],
            [0.0, 0.0, 0.0, 1.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
        ],
        [
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 1.0],
            [0.0, 0.0, 0.0, 1.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
        ],
        [
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 0.0, 0.0, 1.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0, 0.0, 0.0],
        ],
        [
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 1.0, 1.0],
            [0.0, 0.0, 0.0, 1.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
        ],
        [
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 0.0, 1.0],
            [0.0, 0.0, 0.0, 1.0, 0.0],
        ],
        [
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 0.0, 0.0],
            [0.0, 0.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 1.0, 0.0, 1.0],
        ],
    ]
)

model.add_transition_factor(
    values=transition_probs, target=transition_vars[0], parents=transition_vars[1:]
)

The agent's preferences are defined in terms of the probability that it expects to receive a particular observation:

preferences_vars = ["observation"]
preference_probs = np.array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0])

model.add_preference_factor(
    values=preference_probs, target=preferences_vars[0], parents=preferences_vars[1:]
)

Finally, the optional state prior factor can be added:

state_prior_vars = ["position"]
state_prior_probs = np.array([0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0])

model.add_prior_factor(
    values=state_prior_probs, target=state_prior_vars[0], parents=state_prior_vars[1:]
)

Once the components are added, it is important to validate your model. If you are using the POMDPAgent class, then the validation will also check that all model components needed for a POMDP model are present.

model.validate()

Model validated successfully.

Action selection

To perform action selection, the agent needs to have a model loaded.

agent.load_genius_model(model=model)

Next, we pass in an observation and a policy length. A policy is a sequence of actions the agent could take. Active inference agents plan their actions as sequences instead of individual actions so the policy length serves as "lookahead" to define how far into the future the agent will be planning. The following executes action selection:

action_result = agent.act(observation=1, policy_len=1)

Explainability and interpretability

The action_result contains a number of different pieces of information that reveal how the agent came to its decision and its beliefs about the state of the world. These pieces include:

The agent's belief about the unobserved state that it infers on the basis of the observation it receives.
The agent's belief over all policies under consideration given the actions and policy length.
The expected free energy (EFE) for each policy which is used by the agent to rank policies.
A break down of each component of EFE for each policy which indicates the type of behavior the agent is currently prioritizes (reward-seeking or exploratory).
A break down of EFE contributions for the currently selected actions.

For more detailed information on these components see the action data reference section.

PreviousModel editor NextFrequently asked questions, tips and tricks

Last updated 9 months ago

hashtagInstalling the Python SDK

hashtagImporting

hashtagExtra import

hashtagConnecting a Genius agent

hashtagAuthentication

hashtag1. API Key

hashtag2.Bearer Token (not available yet)

hashtag3.OAuth2 Client Credential (not available yet)

hashtagAgent

hashtagBuilding a factor graph in Python

hashtagExploring a Genius model's structure

hashtagCreating a Genius agent

hashtagLoading and viewing a model

hashtagProbabilistic inference

hashtagParameter learning

hashtagActive inference

hashtagCreating a POMDP model

hashtagAction selection

hashtagExplainability and interpretability

Installing the Python SDK

Importing

Extra import

Connecting a Genius agent

Authentication

1. API Key

2.Bearer Token ^{(not available yet)}

3.OAuth2 Client Credential ^{(not available yet)}

Agent

Building a factor graph in Python

Exploring a Genius model's structure

Creating a Genius agent

Loading and viewing a model

Probabilistic inference

Parameter learning

Active inference

Creating a POMDP model

Action selection

Explainability and interpretability