-
Notifications
You must be signed in to change notification settings - Fork 2
API Reference
This document outlines the APIs provided by the CENode library when used programmatically and as a web service.
In this document, the term CENode is used to refer to the entire system (comprising of a CENode knowledge base - KB - and a CEAgent). It also may be used to refer to the actual CENode class and objects of this type. However, the distinction should generally be clear.
The node maintains a set of concepts and instances, which are represented respectively by the objects of the CEConcept and CEInstance classes.
Functions and properties of instances of the CENode class.
Construct a new CENode object. This is the only class of the library one should directly instantiate.
const node = new CENode(model1, model2, ...)
Constructing this object starts the lifecycle of a CEAgent, whose name is, by default, set to 'Moira'.
Any number of models (string arrays) can be passed upon instantiation in order to pre-populate the node's KB. See the documentation for more details.
Spawn a new CEAgent instance to manage cards and policies for this node.
If you pass an agent to this, it must be a subclass of CEAgent. If no arguments are given, a new Agent (named 'Moira') will be created.
Retrieve an array of CEInstances from the node, representing the instances currently known and maintained by the node's KB.
Optionally specify the concept type (str) to retrieve for, and specify whether you'd like to recurse (bool) to get instances of all children of the specified type.
For example, getInstances('card', true) returns all instances of concept 'card' and all descendants of the type 'card'.
When called without any arguments, this function returns all instances known by the node.
Retrieve an instance from the node by ID.
Retrieve an instance from the node by name. This method will return the first instance with the specified name.
The second argument is optional. Pass a CEConcept object here to scope the lookup to a particular concept type. This is useful for finding an instance that might share a name with another instance and since CENode does not permit two instances of the same concept type with the same name.
Retrieve a concept from the node by ID.
Retrieve a concept from the node by name. CENode does not permit multiple CEConcept objects with the same name.
Add a new sentence to be processed by the node. Internally, this function dynamically tries to evaluate the input string in the following order of events. If one stage fails, the function attempts the next:
- Attempt to parse the input string as valid CE. If successful, then this might result in the creation or modification of a concept or instance.
- Attempt to parse the input string as a question.
- Attempt to parse the input string as NL.
Internally, the function uses the function addCE(), askQuestion(), and addNL() and will return the results from these functions directly. Therefore see documentation on these functions for information on returned data. However, this function will not specify if the evaluation passed or failed, as parsing NL will always return some kind of response.
This function will evaluate {now} and {uid} placeholders in the input string to be a timestamp and locally-unique instance ID respectively. Typically, these are used in constructing new cards:
there is an nl card named 'msg_{uid}' that has the timestamp '{now}' as timestamp and is from the user 'Will' and is to the agent 'Moira' and has 'Hello, world' as content.
Add a CE sentence to the node. This may cause the node to create or modify an instance or a concept, and should be the only method used for inserting information into the KB.
This function returns a standard object containing these fields:
-
success- a boolean representing whether or not the node's CE-parser thinks the input is valid CE. -
data- a string representing the response, if any, from the node. Ifsuccessindicates a failure, this value might provide more insight. -
result- where appropriate (e.g. successful), this field will contain the CEConcept or CEInstance that was created or modified as the result of the input CE.
Queries the node's KB for information about a concept or instance.
This function returns a standard object containing these fields:
-
success- a boolean representing whether or not the node understood the question. -
data- a string representing a response or failure message.
Several forms of question are understood by the node:
- what - ask about a particular instance, concept, or property. Returns all information known about the instance, concept, or property
- who - synonymous to 'what' but nicer for querying people-like instances
- where - ask about the location of a particular instance
- what is on/in/at - ask about what is associated with a particular location
Example questions and responses:
- Who is Mrs Smith? - Mrs Smith is a teacher. Mrs Smith teaches the class 'B2' and has the subject 'Computing' as subject and has '45' as age.
- What is a teacher? - A teacher is a type of person. An instance of teacher teaches a type of class and has a type of subject called subject and has a value called age.
- what is teaches? - 'teaches' describes the relationship between a teacher and a subject (e.g. "the teacher 'TEACHER NAME' teaches the subject 'SUBJECT NAME'").
- Where is Mrs Smith? - Mrs Smith lives in the house 'Number 23'.
- What is in house Number 23? - Mrs Smith lives in the house 'Number 23'.
Asking a question will not update the node's KB.
Add a natural language sentence to be processed by the node. The node's NL-parser will do its best to try and work out what you mean, and will return a response in a familiar format (a standard object with the following fields):
-
data- If successful, a string representing a valid CE sentence based on the input NL, or an error message if otherwise.
Adding NL will not update the node's KB. However, submitting an NL card containing valid CE will be auto-confirmed by the node's agent.
Add an array of inputs to be processed by the node. This method simply calls addSentence() on each of the inputs, and will return an array of response objects, whose order maps onto the sentences in the input array.
Since addSentence() is used, the inputs can be a mixture of CE, questions, and NL.
Add an array of CE inputs to be interpreted by the node. Internally, this calls addCE() on each of the inputs, and returns an array of such responses in the order expressed by the input order.
Empty the node's KB of all instances and concepts.
Directly access the CEInstance representing an instance known by the node. When accessing, use the instance's lower-cased name using underscores instead of spaces. Examples:
-
node.instances.mrs_smith- gives the CEInstance of Mrs Smith -
node.instances.moira.name- gives the string 'Moira' (probably)
Directly access the CEConcept representing a concept known by the node. Access in a similar way to instances:
-
node.concepts.ce_card- gives the CEConcept representing the 'ce card' concept -
node.concepts.card.name- gives the string 'card'
The CEAgent object responsible for maintaining this node.
Functions and properties of instances of the CEConcept class. Objects of this class represent concepts maintained by the node.
A string representing the name of the concept.
An internally-used ID to help maintain the KB. Generally this can be ignored by applications using the API.
An array of CEInstances whose type is of the present CEConcept object.
An array of CEInstances whose type is of the present CEConcept object, and any of the descendants of the concept.
An array of CEConcepts representing the parents of the concept.
An array of CEConcepts representing all ancestors of the concept (parents, grandparents, etc.).
An array of CEConcepts representing the concepts to whom this concept is a parent.
An array of CEConcepts representing all descendants of the concepts (children, grandhildren, etc.).
An array of standard objects representing the relationships supported by this concept.
Object is of the form:
-
label- a string identifier describing the relationship -
concept- the CEConcept object the relationship is linked to.
An array of standard objects representing the values supported by this concept.
Object is of the form:
-
label- a string identifier describing the value -
concept- if the value is associated with another concept, this is the CEConcept object representing the relevant concept. Otherwise this is undefined.
An array of strings representing alternative names for this concept. Any of these names can be used when addressing the concept.
A string representing the CE sentence(s) that would be needed in order to construct the state of the current concept.
A string representing a more casual description of the concept. This is returned when asking the question: 'what is ?'.
Helpers are provided to allow you to access associated CEConcepts through values and relationships. For example, with the card CEConcept, card.is_to will give the CEConcept that the 'is to' relationship is associated with (probably a 'person' or 'agent' concept, depending on your implementation).
If you are trying to access a value which is not associated with another CEConcept, then instead the helper will just return the string 'value' to indicate that this value should simply be represented by a string and not an instance of a concept.
Functions and properties of instances of the CEInstance class. Objects of this class represent instances in the KB.
The name string of this instance.
An identifier used to internally recognise this instance.
An array of CE sentences that have been provided that have affected this instance.
The CEConcept object that this instance is a type of.
An array of standard objects representing the relationships to other instances.
Objects are of the form:
-
label- a string describing the relationship -
instance- the CEInstance object this instance relates to.
An array of standard objects representing the values held by this instance.
Objects are of the form:
-
label- a string describing the value -
instance- if the value refers to another instance, then this field holds a reference to that CEInstance. Otherwise this field holds a string.
Examples of this difference can be observed in the core CE model shipped with the library. CEInstances of type 'card' have a value called 'timestamp' that refers to another instance whose name is the actual value of the timestamp. Cards also have a value called 'content', whose value is a literal string.
If you're unsure on what type of value you're dealing with, ask about the parent concept (e.g. 'what is a card?'), and the response will describe the various properties supported by the concept.
Return the most recent value or relationship that has the label with the name specified. If the property is a relationship, then a CEInstance is returned. If it's a value, then either a CEInstance or a string is returned (see the values API documentation for more information).
If withSource is defined and true, then data will be returned in the format: {source: SOURCE, instance: DATA}, where SOURCE is the source input of the information (e.g. username), if any, and DATA is the returned information when used without the withSource flag.
Return an array of CEInstances or strings representing the values or relationships described by the input label.
As with property(), passing a true value for withSource includes the source input of each piece of information returned, with the output format for each list element as described in the notes for the property() function.
A list of strings representing alternative names for this instance. Any of these, or the instance's actual name, can be used when addressing this CEInstance.
A string representing the CE that would be required to generate the instance in its current form.
A string representing a more casual description of the CEInstance. This is the text returned when asking questions like 'what is ?' or 'who is ?'.
You can also directly access values and relationships as direct properties of the CEInstance object. For example, for a card instance, card.is_to gives the same result as calling card.property('is to'). This gives you the latest-reported value or relationship with this name.
Similarly, card.contents gives the same result as calling card.properties('content') - all you do is add an extra 's' at the end to access all of the values or relationships reported with that name.
Note that calling properties() and passing a property name that doesn't yet exist for the instance will return an empty array (as expected). However, accessing the information directly (as with card.is_to, for example) would return undefined, because that property has not yet been defined on the instance.
Functions and properties of the CEAgent class. Each CENode instance will usually have at least one agent spawned to help maintain it.
Set the name of the agent to the specified name.