Merge pull request #31 from Roboy/docs

Merge to master

.gitignore

@@ -1,7 +1,9 @@
 *.class
-
+*.iml
 # Mobile Tools for Java (J2ME)
 .mtj.tmp/
+*.log
+*.log.lck
 
 # Package Files #
 *.jar
@@ -10,3 +12,6 @@
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
+
+.idea
+target

README.md

@@ -0,0 +1,23 @@
+# Roboy Memory Module
+
+Documentation can be found here:
+
+[![Documentation Status](https://readthedocs.org/projects/roboy-memory/badge/?version=latest)](http://roboy-memory.readthedocs.io/en/latest/?badge=latest)
+
+[![Documentation Status](https://readthedocs.org/projects/roboy-memory/badge/?version=docs)](http://roboy-memory.readthedocs.io/en/develop/?badge=develop)
+
+## What is it?
+
+This repository contains a memory module developed to use for Roboy (roboy.org), humanoid robot.
+The goal of the project is to provide Roboy with modern graph-based Knowledge Representation.
+
+Roboy should feature ability to remember information about himself: his name, his age, his origin, his location, his friends,
+etc.
+
+The same is applicable to Roboy speaking about people who are friends with him. Roboy should tell information about a person or an object and be able to provide basic automatic inference (supported by the graph nature of KR). This way, Roboy Memory Module serves as a long-term memory repository of actionable information acquired by other Roboy modules. Persistency layer is presented by a Neo4j graph database.
+
+## How does it work?
+
+Upon incoming request, a Java client will pre-process the request and initiate transaction with the database. Two ways of communication between Roboy Java client and Neo4J database are supported: communication using Neo4J driver operating Cypher query language and Neo4J native Java API. Cypher query language offers more flexible querying while communications via Neo4J Java API are implemented as usage-specific routines. Interfaces are implemented on top of ros through the Java client. The input is any type of information Roboy can retrieve from environment abiding by Knowledge Representation reference in format of Roboy Communication Standard protocol, the output are pieces of data related to the requested scope in the same form.
+
+

docs/ScopeContext/0_system_scope_and_context.rst

@@ -0,0 +1,17 @@
+Context
+--------
+
+The Memory Module receives input from other Cognition modules in form of ROS messages containing RCS payload which is then parsed internally.
+RCS payload contains valid request, otherwise exeption would be raised and Memory Module would answer with "FAIL" and error message.
+
+The main output of the Memory Module is either a single piece of data (JSON object) or set of **ID**s.
+
+The context of Roboy Memory Module illustrated in the following diagram:
+
+.. _context_within_environment:
+.. figure:: images/uml_system_context.*
+  :alt: Bulding blocks overview
+
+  UML System Context
+
+  **UML-type context diagram** - shows the birds eye view of the system (black box) described by this architecture within the ecosystem it is to be placed in. Shows orbit level interfaces on the user interaction and component scope.

docs/ScopeContext/1_conventions.rst

@@ -0,0 +1,11 @@
+Conventions
+-----------
+We follow the coding guidelines:
+
+.. csv-table:: Coding Guidelines
+   :header: "Language", "Guideline", "Tools"
+   :widths: 20, 20, 20
+
+   "Java", "https://google.github.io/styleguide/javaguide.html", ""
+   "Cypher", "https://neo4j.com/developer/cypher-query-language/", ""
+   "Redis", "https://redis.io/commands", ""

docs/ScopeContext/2_architecture_constraints.rst

@@ -0,0 +1,25 @@
+Architecture Constraints
+========================
+
+.. _runtime_interfaces:
+
+Technical Constraints / Runtime Interface Requirements
+------------------------------------------------------
+
+.. csv-table:: Operating System Constraints
+  :header: "Constraint Name", "Description"
+  :widths: 20, 40
+
+  "Ubuntu => 16.04", "Neo4j and ros are much more stable and easier to support on Linux and 
+  Ubuntu is the OS of Roboy as well"
+
+.. csv-table:: Programming Constraints
+  :header: "Constraint Name", "Description"
+  :widths: 20, 60
+
+  "IntelliJ IDEA", "There were difficulties with importing the project to NetBeans and Eclipse"
+  "rosjava", "Due to using both Java and ros"
+  "Java => 1.8.0", "Reasonably recent and stable Java release"
+  "Neo4j => 3.2.1", "Stable and tested in production"
+
+.. _conventions:

docs/ScopeContext/3_public_interfaces.rst

@@ -0,0 +1,152 @@
+.. _technical-interfaces:
+
+Public Interfaces (ROS)
+=======================
+
+Interfaces to other modules are realized through ROS (rosjava).
+Currently 5 interfaces (ROS services) have been designed for communication with Memory Module.
+
+ROS Services
+--------------------------------------------------
+
+All calls are complaint to this general form::
+
+    rosservice call /roboy/cognition/memory/---service_name--- "\"---header---\"" "\"---payload---\""
+
+- **create service**: Service called to perform a query writing data into Neo4j database.::
+
+	# argument: String header String payload
+	# returns: String answer
+
+	rosservice call /roboy/cognition/memory/create
+
+- **get service:** Service called to perform a query reading data from Neo4j database.::
+
+	## argument: String header String payload
+	# returns: String answer
+
+	rosservice call /roboy/cognition/memory/get
+
+- **update service:** Service called to perform a query altering data in Neo4j database.::
+
+	## argument: String header String payload
+	# returns: String answer
+
+	rosservice call /roboy/cognition/memory/update
+
+- **remove service:** Service called to perform a query deleting data from Neo4j database.::
+
+	## argument: String header String payload
+	# returns: String answer
+
+	rosservice call /roboy/cognition/memory/remove
+
+- **cypher service:** Service called to perform any Cypher query in Neo4j database.::
+
+	## argument: String header String payload
+	# returns: String answer
+
+	rosservice call /roboy/cognition/memory/cypher
+
+For the first 4 services the payload has to be defined according to :ref:`roboy-protocol`.
+
+**Payload Elements:**
+
+- 'label' specifies the class of node in the knowledge graph
+- 'id' of a node is a unique number specified for each node that may be accessed be searched or modified in the knowledge graph
+- 'relations' comprise a map of relationship types with an array of node ids for each of them, providing multiple relationships tracing
+- 'properties' = A map of property keys with values
+
+Each of this element is peculiar to respective service payload.
+
+The Cypher service uses a well-formed query in Cypher as the payload, see :ref:`cypher`.
+
+Responses
+--------------------------------------------------
+
+**Create query** provides the following responses.
+
+Success:::
+
+    {
+        'id': x
+    }
+
+Failure:
+
+- some properties are not specified properly::
+
+    {
+        status:"FAIL",
+        message:"no properties"
+    }
+
+- when creating a node, the name property is obligatory, name is missing::
+
+    {
+        status:"FAIL",
+        message:"no name specified in properties : name required"
+    }
+
+- trying to create a node with a non-existing label, see :ref:`know_rep`::
+
+    {
+        status:"FAIL",
+        message:"Label 'Xyz' doesn't exist in the DB"
+    }
+
+**Update query** provides the following responses.
+
+Success:::
+
+    {
+        status:"OK"
+    }
+
+Failure:
+
+- trying to create a relationship with a non-existing type, see :ref:`know_rep`::
+
+    {
+        status:"FAIL",
+        message:"The relationship type 'XYZ' doesn't exist in the DB"
+    }
+
+**Get query** provides the following responses.
+
+Success:
+
+- getting by ID::
+
+    {
+        'id': 15,
+        'labels': ["person"],
+        'properties': {
+            "birthdate":"01.01.1970",
+            "surname":"ki",
+            "sex":"male",
+            "name":"lucas"
+        },
+        'relations': {
+            "from":[28],
+            "friend_of":[124, 4, 26, 104, 106, 71, 96, 63],
+            "member_of":[20], "study_at":[16], "is":[17],
+            "has_hobby":[18],
+            "live_in":[23, 28]
+        }
+    }
+
+- getting IDs::
+
+    {
+        'id':[x, y]
+    }
+
+**Remove query** provides the following responses.
+
+Success:::
+
+    {
+        status:"OK"
+    }
+

docs/ScopeContext/4_user_interface.rst

@@ -0,0 +1,19 @@
+.. _user-interfaces:
+
+User Interfaces
+---------------
+
+There is a GUI for development purposes provided by Neo4j.
+In order to invoke the GUI, a user has to run a Neo4j instance, open a browser and go to::
+	
+	http://localhost:7474
+
+or if using a remote Neo4j instance::
+
+	http://85.10.197.57:7474
+
+which is the Roboy server.
+
+.. figure:: images/neo4j.*
+
+All other parts of the module are provided without GUI and offer interaction on a command line level.

docs/ScopeContext/5_knowledge_rep.rst

@@ -0,0 +1,111 @@
+.. _know_rep:
+
+Neo4j Memory Architecture
+================================
+
+Architecture of the Neo4j database in remote. Current version: 1.1.1.
+
+.. figure:: images/dbvisual.*
+
+Visualization of a DB scheme.
+
+Versioning of KR is performed by implementing architecture proposals and evaluating them, upon evaluation the version is fixed and then new proposals are collected. Adding nodes means major ver. X, adding relations is minor ver. Y, adding properties is patch ver. Z: ver. X.Y.Z.
+
+Node Classes (Labels)
+--------------------------------
+- Person
+- Robot
+- Organization
+
+  a. Company
+  b. University
+
+- Location
+
+  a. City
+  b. Country
+  c. Continent
+
+- Hobby
+- Type
+
+  a. Occupation
+
+- Object (which Roboy can detect/interact with)
+
+Edge Classes
+--------------------------------
+**(Person, Robot : Person, Robot)**
+
+- FRIEND_OF
+
+**(Person, Robot : Location)**
+
+- LIVE_IN
+- FROM
+
+**(Person : Organization)**
+
+- WORK_FOR
+- STUDY_AT
+- MEMBER_OF
+
+**(Person, Robot : Hobby)**
+
+- HAS_HOBBY
+
+**(Person, Robot : Object)**
+
+- KNOW
+
+**(Object, Robot, Person, Organization : Type)**
+
+- IS
+
+**(Organization, Robot : Organization)**
+
+- PART_OF
+
+**(Organization, Location : Location)**
+
+- IS_IN
+
+
+Property Keys
+--------------------------------
+
+**General**
+
+Describes non-specific prameters for any node
+
+- name [string]
+- id [int]
+
+**Person**
+
+Describes prameters specific to a person
+
+- surname [string]
+- birthdate [String]
+- sex [string]
+- face_id (facial features) [int]: reference to a face representation.
+- voice_id (voice signature) [int]: reference to a voice signature.
+- conversation_id (Topic (scope) of the last conversation) [int]: reference to a topic marker for the last conversation. It would refer to a word or summary def by Dialog to recall the previous conversation with a person.
+
+**Roboy**
+
+Describes prameters specific to Roboy
+
+- birthdate [string]
+- abilities [list of strings]
+- skills [list of strings]
+
+**Object**
+
+Describes prameters specific to objects
+
+- color [string]
+- speed [int]
+- price [int]
+- temperature [int]
+- usage [list of strings]