Definition

According to wikipedia, “Semantic translation is the process of using semantic information to aid in the translation of data in one representation or data model to another representation or data model.”

Purpose

This is one way to add additional functionality to a pico.

A pico’s functionality (it’s API) is the sum of all of the rulesets it has installed.

Sometimes we want to augment the functionality of a pico by installing a ruleset which “listens in,” or eavesdrops, on a ruleset already in the pico. In this way, the pico will be able to do additional things which perhaps were not imagined by the authors of the previously installed ruleset.

Example: a game-playing agent

There are rulesets which allow a pico to become an Aries agent, and when these are installed in a pico, we call that pico a Pico Agent.

Agent to agent communication

When two Pico Agents are connected, they have a point-to-point, pairwise, communications channel, using a protocol named DIDComm. Part of this protocol is a “basicmessage.” As with all other communications through such a channel, all messages are encrypted and signed.

The agent ruleset handles an incoming basicmessage with this rule:

//
// basicmessage/message
//
  rule handle_basicmessage_message {
    select when sovrin basicmessage_message
    pre {
      their_key = event:attr("sender_key")
      conn = ent:connections{their_key}
      msg = event:attr("message")
      wmsg = conn.put(
        "messages",
        conn{"messages"}.defaultsTo([])
          .append(msg.put("from","incoming"))
      )
    }
    fired {
      ent:connections{their_key} := wmsg
    }
  }

So the behavior of a Pico Agent is that, when a basicmessage comes in, the event sovrin:basicmessage_message is raised, and selected by this rule, which ends up adding the message to an array of messages in the connection identified by the sender_key (tagging it as “incoming”).

Playing Tic Tac Toe

Suppose we want two of our agents to entertain their owners with a game of Tic Tac Toe. A protocol has been documented for this game (as an example of how a protocol should be documented).

There are rulesets which can be installed into a Pico Agent to allow it to do this.

The did-sov-SLfEi9esrjzybysFxQZbfq ruleset handles an incoming basicmessage with the rule shown below. The rule selects (line 12) on the same event, sovrin:basicmessage_message, but only when (line 13) the content of the message is a Map which has a key “@type” whose value matches the mturi pattern (line 4) (this is defined in the Tic Tac Toe protocol).

ruleset did-sov-SLfEi9esrjzybysFxQZbfq {
  ...
  global {
      mturi = re#did:sov:SLfEi9esrjzybysFxQZbfq;spec/tictactoe/1.0/([A-Za-z0-9_.-]+)#
      ...
  }
...
//
// eavesdrop incoming agent basicmessages for one of interest
//
  rule eavesdrop_basicmessage {
    select when sovrin basicmessage_message
      where event:attr("message"){["content","@type"]}.match(mturi)
    pre {
      content = event:attr("message"){"content"}
      event_type = content{"@type"}.extract(mturi).head()
      conn = event_type => agent:connections(){event:attr("sender_key")}
                         | null
    }
    if event_type && conn then noop()
    fired {
      ent:opponent := conn{"label"}
      ent:their_vk := conn{"their_vk"}
      ent:my_did := conn{"my_did"}
      raise tictactoe event event_type attributes content
    }
  }

The rule performs a semantic translation. The translation completes in line 25. The event which came in has domain sovrin, whose attribute is a map named message. The event raised by this rule has domain tictactoe whose attributes are the Map from the content of the incoming basicmessage.

So the incoming event is translated from the sovrin domain to the tictactoe domain, based on the semantics of the content.

How it works

An alert reader will have noticed that there are rulesets installed in the same pico which both select a rule on the sovrin:basicmessage_message event. It is indeterminate which of the two rules will be evaluated first, but they don’t interfere with each other, so that doesn’t matter. Both selected rules will evaluate.

The upshot is that two different things will happen when the sovrin:basicmessage_message event comes in to the Pico Agent. Both will happen, in some order:

The message will be added to the messages array for the connection (on which it arrived)
The content of that message will become the attributes for a new event (either tictactoe:move or tictactoe:outcome (the two message types defined in the Tic Tac Toe protocol))

The handle_basicmessage_message rule of the agent ruleset is a “terminal rule” in that no further rules will be evaluated for the agent ruleset.

On the other hand, the eavesdrop_basicmessage rule will cause a further rule to be evaluated within the did-sov-SLfEi9esrjzybysFxQZbfq ruleset.

The further rule will be one of these, depending on the type and the state of the Pico Agent:

//
// tictactoe/1.0/move
//
  rule handle_initial_move_message {
    select when tictactoe move
      me re#^([XO])$# setting(me)
      where event:attr("@id") && ent:thid.isnull()
    ...
  }
...
  rule handle_subsequent_moves {
    select when tictactoe move
      me re#^([XO])$# setting(me)
    ...
  }
...
//
// tictactoe/1.0/outcome
//
  rule handle_outcome_message {
    select when tictactoe outcome
    fired {
      raise tictactoe event "game_over"
    }
  }

Note

This code is also an example of “Event Stream Splitting.”

developer

Example of semantic translation