Embodiment's Code Organization

From OpenCog


This page describes briefly how the embodiment code is organized. This was initially created as result of a study to identify what parts of the Embodiment code-base could be extracted from opencog/embodiment folder and become an independent library to be reused by any other OpenCog component or application.

This result is shown at the end of this page.

Embodiment's folders and libraries (on May 19th, 2009)

  • Control: This is the folder where the classes that compose the controller for an agent (pet) live.
    • OperationalAvatarController: defines the main library and the executable for OperationalAvatarController (OAC). The main classes are:
      • OAC
      • Pet
      • RuleEngine
    • PerceptionActionInterface: library for Perception & Action Interface (PAI class).
    • Predavese: contains a parser for natural language sentences and identifies the related actions (commands given by pet's owner) to be executed.
    • PredicateUpdaters: defines how the basic predicates should be updated once a new Opencog/OAC cycle takes place (i.e., after new perceptions are received and stored in OAC's AtomSpace and the time goes on).
    • Procedure: contains a procedure repository to store and persist both the built-in and learned procedures and a procedure interpreter to execute any of these procedures (most of them in combo language) when requested.
    • MessagingSystem: defines the protocol for communication between Embodiment's elements (or components). Click here for more information on this.
  • AtomSpaceExtensions: library with utility methods to store, manipulate and retrieve atoms (usually Embodiment-related ones) from an AtomSpace.
  • Learning: This is the folder where all learning-related classes live.
    • LearningServer: defines the ls lib and the LS executable
    • Filter: define filters to be applied to procedure candidates generated by the learning algorithm based on the perceptions (actions and other predicates) of a trick exemplar period.
    • PetaverseMOSES: petaverse-specific moses learning module
    • FitnessEstimator: classes for estimating fitness of procedure candidates for tricks
    • PetaverseHC: petaverse-specific hillclimbing learning module
    • NoSpaceLife:
    • behavior: classes to retrieve, categorize and manipulate behavior descriptions (see BDs, Retrieving BDs and Behavior similarity for more information on this.
    • RewritingRules: classes to rewrite (reduce or reduce) procedure candidates after being generated by a learning algorithm.
    • LearningServerMessages: messages used in communication between LS and OAC
    • main: define some utility programs used during development of learning module (interactive-hillclimbing.cc, moses-petbrain.cc, post_learning-rewriter.cc)
  • RuleValidation: development tool used to show how rule engine behaves with a given set of rules. It is useful for tuning rules parameters (like rules' weight and preconditions). Click here for more information on this.
    • Processor: process the embodiment rules for a given agent (pet or humanoid)
    • VirtualWorldData: class to represent the virtual world data (state, entities and actions) that are used as input for the RuleValidation processor.
  • WorldWrapper: a layer used between the procedure (combo) interpreter and the world it is interpreted in.
  • AGISimSim: An AGI World Simulator used for tests (mainly at the beginning of the project) using simple scenarios.
    • server: the AGI Sim server, where the world/scenario is read and the simulator engine runs.
    • client: a client that connects to the AGISim server to enter commands to move object within world it's simulating.
    • shared: a set of classes and definitions shared between AGISim client and server.
    • proxy: The component used to connect to the AGISim server. This is used by AGISim client and by PetaverseProxySimulator (the Embodiment Proxy for AGISimSim), which is described next.
  • PetaverseProxySimulator: the Embodiment Proxy for an AGISimSim world. It simulates a Proxy to a more popular Virtual World Platform like SecondLife, Multiverse or RealXtend.
  • PetComboVocabulary: defines the vocabulary used in combo procedures to control Pet's behavior. This includes pet actions, operators, perceptions and indefinite objects.
  • AutomatedSystemTest: this contains classes used to create automated system tests based on golden standards, which are sequences of messages exchanged between an Proxy and the Embodiment's system (spawner, router and OACs) recorded during the execution of a successful manual test. Click here to read more about automated system tests.

Cyclic library dependencies

While checking for parts of the Embodiment codebase that could become independent libraries I found the following cyclic dependencies between the embodiment libraries:

  ImaginaryLife => WorldWrapper => ImaginaryLife
  PAI => Predavese => WorldWrapper => PAI
  PAI => Predavese => WorldWrapper => ImaginaryLife => behavior => PAI
  MessagingSystem -> LearningServerMessages -> MessagingSystem

A suggestion to remove the 3 first cyclic dependencies is to replace the usage of concrete classes by pure abstract classes (interfaces) when passing them as argument of a class in another library. For example, we could have a PAI pure abstract class and have a PAIImplementation class that does the current role of PAI class. The same stands for PredaveseParser, WorldWrapper and ImaginaryLife, I guess. The last cyclic dependency can be removed by creating a registration method in Message class to register subclasses based on their code (an integer value from a predefined set of values). This way only LearningServerMessages would depend on MessagingSystem, not the opposite.

Components that could become independent libraries

I've detected the following components that could be decoupled from Embodiment's codebase through not so hard changes to their current design:


This library contains both the Repository and the Interpreter for procedures.

The Repository is simply a subclass of AtomSpace's SavableRepository abstract class, which is an interface to be implemented for any component that needs to be persisted to disk by AtomSpace's SavingLoading. In addition to AtomSpace library, Repository depends on PAI library because it also handles BuiltInProcedure objects through thte BuiltInProcedureRepository (one of its members). Built-in procedures are tightly coupled to PetAction class (which lives in PAI lib) because each of these procedures mean a single pet action (see PetActionSchema class inside Procedure/BuiltIn folder for more details). However, we can get rid of all these built-in procedures and replace them by equivalent combo procedures (which can be also built-in, i.e., predefined). This is the path to make the repository part of the Procedure library be independent from PAI lib. Of course, the combo language (which the other type of procedure is written with) needs to have a pet vocabulary of actions so that it handles the single-action procedures, but this will be handled in ComboInterpreter, not by the repository.

The Interpreter also depends on PAI lib basically because it needs to create action plans and send them through the PAI, which encapsulate the messages to an Embodiment Proxy in a XML format. However, instead of using a concrete PAI class, we could use an pure abstract class (interface) of PAI and let OPC instantiate a concrete PAI class when creating the Procedure interpreter object.


In order to make this an external (of Embodiment) module, one must resolve the following dependencies:

  • AtomSpaceUtil: Used to create/read predicates, add Nodes and Links.
  • Combo: Extensively use Combo Interpreter/Procedure repository in SchemaRunner to execute the actions
  • PAI/PAIUtils: Used to consult the latestTimeStamp, timeFactor and send emotionalFellins messages to Proxy.
  • OPC: Get Current AtomSpace, get latest owner's request command, get the agent's type and id.
  • EmbodimentConfig: Used to retrieve some config parameters. It can be modified to use the opencog config manager class.


AGISimSim is a simplification of the implementation of AGISim project(see http://sourceforge.net/projects/agisim/) that simulates a 2D World (instead of a 3D World as AGISim does). This was mainly used in the beginning of the Petaverse project (former name of Embodiment) when we needed a simulated world to start experimenting with while a Proxy to a 3D World simulator was still in development. We still have AGISimSim (and PetaverseProxySimulator, which is a Proxy for AGISimSim) as an option for making tests with Embodiment system, but since other 3D worlds are richer in details, it is not that useful anymore. Anyway, this part of the project is fully independent and can be extracted from Embodiment folder if someone wants to use it for another purpose.

Learning engine

(to be written by Nil, if it is really feasible to have a generic learning engine with reasonably small effort)