Skip to main content

Actor

type​

Annotates a class as a Paranet data type. This annotation is required on the following types:

  • All skill handler method return or response types
  • Skill request response types
  • Nested classes in skill return, skill request, and broadcast types

The supported field types include:

  • scalar types (int, float, str)
  • user-defined classes also annotated with the type decorator
  • lists of a user-defined classes (scalar fields only) also annotated with the type decorator

Example type annotation:

@actor.type
class Location:
    lat: float
    lon: float

input​

Annotates a class as a Paranet input data type. This annotation is required on any class used as an argument to a skill method.

The supported field types include:

  • scalar types (int, float, str)

Example input annotation:

@actor.input
class Location:
    lat: float
    lon: float

actor​

Annotates a class as an actor. The class must extend the BaseActor class.

Use the following decorator arguments to configure the actor class:

  • name The name of the actor on the Paranet (optional). If not provided, defaults to the class name in lower case.
  • subject The default actor subject (optional). Skills provided by this actor will have this subject if not specified in the @actor.skill decorator. If not provided, the actor default subject will be the actor name.

Example actor class:

@actor.actor
class MyActor(BaseActor):
    @actor.skill
    def echo(self, s: str) -> str:
        return s

Since no arguments are provided the default actor name and subject default in this example is "myactor". Also, since no arguments are given to the skill method echo, the corresponding skill name would be "myactor/echo".

skill​

Annotates a method as a skill request handler. This actor will be registered as a provider for the corresponding skill and this method will be called when the actor receives a request for that skill.

The advertised skill is defined by the:

  • subject/action arguments of this decorator
  • input parameters of the method
  • return type of the method or the response argument of this decorator

The following decorator arguments are available to configure the skill/handler:

  • subject The skill subject (optional). If not provided, defaults to the actor's subject.
  • action The skill action (optional). If not provided, defaults to the name of the method.
  • background Indicates that the skill is asynchronous.
  • response The response type (implies background). The type must be a class annotated with @actor.type.
  • instance_param The instance parameter (optional). For multi-instance actors, this instance parameter contains an actor instance id.
  • id The id of a registered skillset that defines this skill.

The async keyword is not supported on skill methods.

Skill request handlers should not block for long periods of time. The actor cannot service any other requests while this method is running. For long running tasks, use asyncio.ensure_future to execute the task asynchronously and return immediately from the handler.

Example provided skill method:

@actor.actor
class MyActor(BaseActor):
    @actor.skill
    def echo(self, s: str) -> str:
        return s

observation​

Annotates a method as a skill observation handler. This actor does not provide the skill, but merely watches requests for the given skill. The handler is called whenever the skill is observed. The method parameters must match the skill requests inputs. The method must have a return type None.

  • subject The observed skill's subject (required).
  • action The The observed skill's action (required).

Example observation handler:

@actor.actor
class MyActor(BaseActor):
    @actor.observation(subject='order',action='new_order')
    def handle_new_order(self, order: Order) -> None:
        ...

skill_request​

Annotates a class as a Paranet skill request input signature. Actors that make skill requests must declare the skills they intend to use by defining a class with the skill_request annotation that you provide when you register the actor (see register method). Note that the input schema for the skill corresponds to the fields of this class, not the actual class itself. To make the skill request, you will call the send_request method with an instance of this class as the inputs for your request.

  • subject The subject of skill request (required).
  • action The action of skill request (required).
  • response A class corresponding to the response schema of the skill request which must be annotated with type.

The supported field types include:

  • scalar types (int, float, str)
  • user-defined classes also annotated with the type decorator
  • lists of a user-defined classes (scalar fields only) also annotated with the type decorator

Example skill request class:

@actor.skill_request(subject='occupancy', action='query')
class Location:
    lat: float
    lon: float

The corresponding skill definition is register0`yaml subject: occupancy actions:

  • action: query input: lat: paranet:number lon: paranet:number

broadcast​

Annotates a class as a Paranet broadcast request input signature. Actors that make broadcast requests must declare the broadcasts they intend to use by defining a class with this broadcast annotation that you provide when you register the actor (see register method). Note that the input schema for the broadcast corresponds to the fields of this class, not the actual class itself. To make the broadcast request, you will call the send_broadcast method with an instance of this class as the inputs for your request.

  • subject The subject of broadcast (required).
  • action The action of broadcast (required).

The supported field types include:

  • scalar types (int, float, str)
  • user-defined classes also annotated with the type decorator
  • lists of a user-defined classes (scalar fields only) also annotated with the type decorator

Example broadcast skill class:

@actor.broadcast(subject='nav', action='current_location')
class Location:
    lat: float
    lon: float

The corresponding broadcast definition is

  subject: nav
  actions:
    - action: current_location
      input:
        lat: paranet:number
        lon: paranet:number

Conversation Objects​

class Conversation()

Represents an instance of a skill request

cid​

Paranet conversation ID

send_complete​

Send notification of background skill's completion

send_response​

Send the response from a background skill request

BaseActor Objects​

class BaseActor()

Base class for all actors

send_request​

Send a skill request from this actor

send_broadcast​

Send a broadcast message from this actor

register_actor​

Registers an actor for deployment.

  • actor Instances of an actor class (i.e. class decorated with actor.actor).
  • requests List of skill request classes (i.e. classes decorated with actor.type) that define all the skill requests this actor makes.
  • broadcast List of broadcast classes (i.e. classes decorated with actor.type) that define all the messages this actor broadcasts.

deploy​

Deploy all registered actors.

  • prj Name of the created docker compose project.
  • restart Restart existing containers if already running.

If running directly on the host, this function will start a docker compose project with one container per actor which communicates with the Python actors via the connector service. In this case, the function will return an awaitable that returns when the deploy is complete.