CEServer Usage

Using CEServer

The CEServer is useful for interacting with CENode over HTTP.

Basic use

The server can be run simply using:

$ node src/CEServer.js

Where src is a directory in the root of the cenode project when cloned from this repository or installed using NPM.

By default, the server runs on port 5555 with an agent named 'Moira'.

Server arguments

The port and default agent name can be changed using command-line arguments. For example:

$ node src/CEServer.js Mycroft 8080

By default, the server is launched with an empty knowledge base. You may instead prefer to instantiate it with any number of models found in the models/ directory. For example, to instantiate with both the core and server models, then issue:

$ node src/CEServer.js Mycroft 5000 core server

Currently the server does not support instantiation using a custom model. To accomplish this, launch the server using any bundled models that you need and then use POST /sentences (documented below) to add more knowledge.

Supported APIs

This section lists the HTTP APIs exposed by CEServer, including example responses where appropriate.

GET /concepts

Returns a JSON-encoded list of CEConcept names known by the node. Example:

HTTP GET /concepts

[
  {
    "id": "1",
    "name": "entity"
  },
  ...
]

GET /concept?id=:id

Return more details about a particular CEConcept by providing an ID. Typically this ID might be identified by GETting /concepts first. Example response:

HTTP GET /concept?id=15

{  
   "name":"policy",
   "ce":"conceptualise a ~ policy ~ P that is a entity and has the value A as ~ enabled ~ and has the agent A as ~ target ~.",
   "parents":[  
      {  
         "name":"entity",
         "id":1
      }
   ],
   "children":[  
      {  
         "name":"tell policy",
         "id":16
      },
      {  
         "name":"ask policy",
         "id":17
      },
      {  
         "name":"listen policy",
         "id":18
      },
      {  
         "name":"listen onbehalfof policy",
         "id":19
      },
      {  
         "name":"forwardall policy",
         "id":20
      },
      {  
         "name":"feedback policy",
         "id":21
      }
   ],
   "instances":[  
   ],
   "values":[  
      {  
         "label":"enabled",
         "targetName":0,
         "targetId":0
      },
      {  
         "label":"target",
         "targetName":"agent",
         "targetId":4
      }
   ],
   "relationships":[  
   ]
}

GET /instances

Retrieve a list of basic CEInstance information about all node-known instances. Example:

HTTP GET /instances

[  
  {  
    "name":"Moira",
    "id":1,
    "conceptName":"agent",
    "conceptId":4
  },
  ...
]

GET /instance?[id=:id,name=:name]

Retrieve more detailed information about a specific instance either by ID or name. When querying by name, the first instance with the specified name will be returned. Querying by ID is exact, but the internally-used ID will need to be determined first. Example:

HTTP GET /instance?id=1

or

HTTP GET /instance?name=Moira

gives:

{  
  "name":"Moira",
  "conceptName":"agent",
  "conceptId":4,
  "ce":"there is a agent named 'Moira'.",
  "synonyms":[  
  ],
  "subConcepts":[  
  ],
  "values":[  
  ],
  "relationships":[  
  ]
}

GET /info

Retrieve some general information about the CENode instance itself. Example:

HTTP GET /info

{  
  "recentInstances":[  
    {  
      "name":"Moira",
      "id":1,
      "conceptName":"agent",
      "conceptId":4
    }
  ],
  "recentConcepts":[  
    {  
      "name":"entity",
      "id":1
    },
    {  
      "name":"imageable thing",
      "id":2
    },
    {  
      "name":"timestamp",
      "id":3
    },
    {  
      "name":"agent",
      "id":4
    }
  ],
  "instanceCount":1,
  "conceptCount":21
}

GET /model

Retrieve the entire current state of the CENode internal knowledge base in line-separated CE format. This is useful for 'backing-up' the model for use in instantiating another node or to use for other purposes. Example:

HTTP GET /model

conceptualise a ~ entity ~ E
conceptualise a ~ imageable thing ~ I
conceptualise a ~ timestamp ~ T
there is a agent named 'Moira'

GET /cards?agent=:agent

Retrieve a line-separated list of CE cards that are addressed to the specified agent. Example:

HTTP GET /cards?agent=Moira

there is an nl card named card1 that is to the agent Moira and has 'Hello' as content
there is an ask card named card2 that is to the agent Moira and has 'what is tennis?' as content and is from the agent Mycroft

POST /sentences

Submit a newline-separated list of CE sentences to the server's node's knowledge base for processing. These could be direct CE or cards for the server's node's agent to process or cards for the server's node to keep hold of for other agents to retrieve and process.

For example:

HTTP POST /sentences

there is a person named Fred
the person Fred is married to the person Jane

POST /cards?agent=:agents

Note: We are aware of the semantically incorrect use of POST for this particular API. The reason is that the body of the request can be too long for standard URL parameters, as explained below.

Retrieve cards from the server's node's knowledge base. These are returned line-separated.

If the agent URL parameter is not provided, then all cards are returned. Otherwise, only return cards that have the agent agentName as is to. Multiple agents can be specified by comma-separating them. For example /cards?agent=Moira,Mycroft,Agent4.

A list of cards to ignore can be sent in the request body. This should be a line-separated list of card names that the server will not return as part of the response regardless of the state of the rest of the request.

For example:

HTTP POST /cards?agent=Mycroft

card1
card2
card3

PUT /reset

Resets the CENode's knowledge base by emptying it of all known concepts and instances.

HTTP PUT /reset

PUT /agent/name

Changes the name of the server's node's agent. The name should be specified in the body of the request. For example:

HTTP PUT /agent/name

Mycroft