Model management

This guide covers the Models management API, which provides endpoints for managing RxInfer models in RxInferServer. You'll learn how to create, manage, and interact with models and their episodes.

For information about how to create and add new models to the server, please refer to the How to Add a Model manual.

Prerequisites

Before using the Models API, you need a valid authentication token. If you haven't obtained one yet, please refer to the Authentication guide. The examples below assume you have already set up authentication:

import RxInferClientOpenAPI.OpenAPI.Clients: Client
import RxInferClientOpenAPI: ModelsApi

client = Client(basepath(ModelsApi); headers = Dict(
    "Authorization" => "Bearer $token"
))

api = ModelsApi(client)

Terminology

In RxInferServer, a model is a type of probabilistic program that you can create and interact with. We distinguish between available models and model instances.

Available models are the models that you can use to create an instance of. They contain all the code and configuration to create an actual model instance and are usually identified by their model_name.
Model instances are the actual instances of a model that you have created. They contain the state of the model, including the learned parameters. You can have multiple model instances of the same model which are identified by a unique instance_id. Individual instances are isolated from each other, meaning that they do not share state.

Discovering Available Models

Before creating a new model instance, you can explore which model types are available on the server with the get_available_models operation:

import RxInferClientOpenAPI: get_available_models

available_models, _ = get_available_models(api)

# only show the model details as the full configuration is quite large
map(model -> model.details, available_models)

3-element Vector{RxInferClientOpenAPI.AvailableModelDetails}:
 {
  "name": "BetaBernoulli-v1",
  "description": "A simple Beta-Bernoulli model",
  "author": "Lazy Dynamics",
  "roles": [
    "user"
  ]
}

 {
  "name": "Drone3D-v1",
  "description": "A 3D drone model",
  "author": "Lazy Dynamics",
  "roles": [
    "user"
  ]
}

 {
  "name": "LinearStateSpaceModel-v1",
  "description": "This model represents a linear Guassian dynamical system with unknown dynamics.\nThe state transition is modeled as a matrix with Gaussian prior on the elements.\nThe observational model is assumed to be the diagonal matrix with `1` on the diagonal.\n",
  "author": "Lazy Dynamics",
  "roles": [
    "user"
  ]
}

Note that the list of available models depends on the roles assigned to the token used to make the request as well as server settings.

Inspecting Available Model Details and Configuration

Each model type comes with detailed configuration and specifications. For example:

available_models[1].details

{
  "name": "BetaBernoulli-v1",
  "description": "A simple Beta-Bernoulli model",
  "author": "Lazy Dynamics",
  "roles": [
    "user"
  ]
}

available_models[1].config

Dict{String, Any} with 7 entries:
  "name"        => "BetaBernoulli-v1"
  "author"      => "Lazy Dynamics"
  "arguments"   => Any[Dict{String, Any}("name"=>"prior_a", "default"=>1, "requ…
  "parameters"  => Any[Dict{String, Any}("name"=>"posterior_a", "description"=>…
  "data"        => Any[Dict{String, Any}("name"=>"observation", "required"=>tru…
  "roles"       => Any["user"]
  "description" => "A simple Beta-Bernoulli model"

Alternatively, you can inspect these using the get_available_model operation with the specific model name:

import RxInferClientOpenAPI: get_available_model

some_model, _ = get_available_model(api, available_models[1].details.name)

The response provides two key pieces of information:

details: Light-weight model information
config: Model-specific configuration

some_model.details

{
  "name": "BetaBernoulli-v1",
  "description": "A simple Beta-Bernoulli model",
  "author": "Lazy Dynamics",
  "roles": [
    "user"
  ]
}

some_model.config

Dict{String, Any} with 7 entries:
  "name"        => "BetaBernoulli-v1"
  "author"      => "Lazy Dynamics"
  "arguments"   => Any[Dict{String, Any}("name"=>"prior_a", "default"=>1, "requ…
  "parameters"  => Any[Dict{String, Any}("name"=>"posterior_a", "description"=>…
  "data"        => Any[Dict{String, Any}("name"=>"observation", "required"=>tru…
  "roles"       => Any["user"]
  "description" => "A simple Beta-Bernoulli model"

Creating a Model Instance

Once you have selected the model you want to use, you can create a new instance of it with the create_model_instance operation together with the CreateModelInstanceRequest type:

import RxInferClientOpenAPI: create_model_instance, CreateModelInstanceRequest

request = CreateModelInstanceRequest(
    model_name = available_models[1].details.name,
    description = """
    An arbitrary instance description,
    which can be used to identify the instance later on
    """,
    # Optional: Customize model behavior with arguments
    # arguments = Dict(...)
)

response, _ = create_model_instance(api, request)
instance_id = response.instance_id

"9b2a9b30-26f0-4245-bf19-a837a99c23f1"

If successful, the server returns a unique instance_id that you'll use to interact with this specific model instance. A server may return an error if the model is not found or if the instance already exists.

response, _ = create_model_instance(api, CreateModelInstanceRequest(
    model_name = "non_existent_model"
))
response

{
  "error": "Not Found",
  "message": "The requested model name `non_existent_model` could not be found"
}

Listing Created Model Instances

View all instances of models you've created with the get_model_instances operation:

import RxInferClientOpenAPI: get_model_instances

created_models, _ = get_model_instances(api)
created_models

1-element Vector{RxInferClientOpenAPI.ModelInstance}:
 {
  "instance_id": "9b2a9b30-26f0-4245-bf19-a837a99c23f1",
  "model_name": "BetaBernoulli-v1",
  "created_at": "2025-04-14T13:14:00.034+00:00",
  "description": "An arbitrary instance description, \nwhich can be used to identify the instance later on\n",
  "arguments": {
    "prior_b": 1,
    "prior_a": 1
  },
  "current_episode": "default"
}

We can see indeed that the list contains the instance we created earlier.

created_models[1].instance_id == instance_id

true

Getting Details of a Specific Model Instance

Previously we retrieved a list of all model instances. Now we can retrieve details about a specific model instance with the get_model_instance operation:

import RxInferClientOpenAPI: get_model_instance

response, _ = get_model_instance(api, instance_id)
response

{
  "instance_id": "9b2a9b30-26f0-4245-bf19-a837a99c23f1",
  "model_name": "BetaBernoulli-v1",
  "created_at": "2025-04-14T13:14:00.034+00:00",
  "description": "An arbitrary instance description, \nwhich can be used to identify the instance later on\n",
  "arguments": {
    "prior_b": 1,
    "prior_a": 1
  },
  "current_episode": "default"
}

Checking the State of a Specific Model Instance

Monitor the current state of your model with the get_model_instance_state operation:

import RxInferClientOpenAPI: get_model_instance_state

response, _ = get_model_instance_state(api, instance_id)
response

{
  "state": {
    "prior_b": 1,
    "prior_a": 1,
    "number_of_infer_calls": 0
  }
}

Checking the Parameters of a Specific Model Instance

Monitor the current parameters of your model with the get_model_instance_parameters operation:

import RxInferClientOpenAPI: get_model_instance_parameters

response, _ = get_model_instance_parameters(api, instance_id)
response

{
  "parameters": {
    "posterior_a": 1,
    "posterior_b": 1
  }
}

State of a Model Instance vs Parameters of a Model Instance

Note that the state of a model instance is not the same as the parameters of the model. You can consider the state as an internal implementation detail of the model and is not exposed to the user. The parameters are, however, directly exposed through the Learning API and can be updated and learned from data using different episodes.

Deleting a Model Instance

When you're done with a model instance, you can remove it completely with the delete_model_instance operation:

import RxInferClientOpenAPI: delete_model_instance

response, _ = delete_model_instance(api, instance_id)
response

{
  "message": "Model instance deleted successfully"
}

Cascade Deletion

Deleting an instance automatically removes all its episodes, read more about episodes in the Learning parameters of a model section
Deleting an instance does not delete other instances of the same model
This action cannot be undone
Make sure to save any important data before deletion

Verify the model has been removed:

# Check model list
created_models, _ = get_model_instances(api)
created_models

RxInferClientOpenAPI.ModelInstance[]

# Check model list
response, _ = get_model_instance(api, instance_id)
response

{
  "error": "Not Found",
  "message": "The requested model instance could not be found"
}