This is a WEB interface to the NetworkAPI feature of the htm.core library. This allows a network enabled application to call a web server to implement an AI application without having the htm.core library installed locally.
The server is generic in that it responds to the REST web messages to create and act upon a unique resource which in this case is a Network class object stored in the server. The client app sends the REST messages as needed to implement its application.
-
Network; This is a container for all of the resources in an application. Any number of resources can be contained in a Network resource and can be arranged in any order and connected in any sequence.
-
Region; This represents an instance of an algorithm. The htm.core library contains a number of built-in region types which each of which is a wrapper around one of the primitive algorithms of the library. Each region type has predefined parameters, inputs, and outputs. All of these are defined in the JSON or YAML encoded configuration string. A description of all of the built-in regions can be found in [NetworkAPI Region docs](docs/NetworkAPI Regions.md)
-
Parameter; This represents a parameter that is passed to the wrapped algorithm either during initialization (Create Access), during iteration execution (ReadWrite Access) or are generated by the algorithm during execution (ReadOnly Access). The Create Access parameters must be defined in the Network configuration. Only ReadWrite Access parameters may be set with a PUT request. All types of parameters may be accessed with a GET request.
-
Input; This represents an end-point on a data flow which is an input to a region. A region may have several inputs. This data is passed on into the primitive algorithm that is wrapped by the region with data type conversions applied as needed.
-
Output; This represents a starting point of a data flow which is an output of a region. A region may have several outputs. This data is taken from the results of applying the wrapped algorithm during a run cycle, with data type conversions applied as needed.
-
Link; This represents a data flow between the output of one region and the input of another. There can be multiple links originating at one output (fan out) and there can be multiple links terminating on a single input (fan in). Links cannot be made between regions in different Networks.
-
Run; This causes the NetworkAPI engine to orchestrate the data flows and execute each primitive algorithm in the sequence defined in the Network's configuration. Each time it is called it implements the specified number of iterations. Between calls the client may pass data by using the parameters or an input stream.
The NetworkAPI supports the following object structure.
Network (key is id)
Regions (key is region name)
Parameters (key is parameter name)
Inputs (key is input name)
Outputs (key is output name)
Links (key is "from_region.from_output", "to_region.to_input")
So a full key structure would look like:
/network/<id>/region/<region name>/param/<param name>
/network/<id>/region/<region name>/input/<param name>
/network/<id>/region/<region name>/output/<param name>
/network/<id>/link/<from>/<to>
A REST application uses operators to act on web resources.
-
POST - means create a new instance of the object and return an identifier. In this case the resource being created is the Network object. Each POST for a /network object will return a unique id that identifies that object (its key) for use by subsequent operations. In our case, all resources subordinate to the Network object are defined in the configuration string passed in when the Network object is created. The resources are not persistent in this server so if the server is stopped, all resources (Network objects) and subordinate objects (Regions, Links, Inputs, and Outputs) are destroyed.
-
PUT - means assign a new value to a resource identified by a key. For an example, '
PUT /network/0001/region/SP/param/abc/?data=123' means set the abc parameter on the SP region of network 0001 to the value '123'. -
GET - means fetch the current value on the resource identified by a key. For example, '
GET /network/001/region/SP/param/abc' will return its value '123'. -
DELETE - means remove the resource identified by the key.
Protocol for the NetworkAPI REST feature for all operations currently implemented are as follows:
POST /network?id=<previous id>
Create a new Network class object as a resource identified by id.
The 'id' field is optional. If given will replace the resource identified by 'id'.
The body of the POST is JSON formatted configuration string.
Refer to the details of the function Network::configure(string) for the syntax
of this configuration string.
Returns a new id for the created resource or an Error message.
PUT /network/<id>/region/<region name>/param/<param name>?data=<url encoded JSON data>
Set the value of a region parameter. The <data> could also be in the body. Returns OK.
GET /network/<id>/region/<region name>/param/<param name>
Get the value of a region parameter. Returns JSON encoded value.
PUT /network/<id>/region/<region name>/input/<input name>?data=<JSON encoded array>
Set the value of a region's input. The data could also be in the body. Returns OK.
GET /network/<id>/region/<region name>/input/<input name>
Get the value of a region's input. Returns a JSON encoded Array object.
GET /network/<id>/region/<region name>/output/<output name>
Get the value of a region's output. Returns a JSON encoded Array object.
DELETE /network/<id>/region/<region name>
Delete the specified region. Returns OK.
DELETE /network/<id>/link/<source name>/<dest_name>
Delete the specified link. Returns OK.
DELETE /network/<id>/ALL
Delete the entire Network object. Returns OK.
GET /network/<id>/run?iterations=<iterations>
Execute all regions in phase order. Repeat <iterations> times. Returns OK.
GET /hi
Respond with "Hello World" as a way to check client to server connection.
GET /stop
Stop the server. All resources are released. Returns OK.
All responses are in JSON syntax. A successful response will be in the 'result' field where result_value may be a scalar value, an array of values, or a map of values.
{"result": result_value}
An error response will be in the 'err' field where 'error_msg' will be the text of the error message.
{"err": error_msg}
The configuration string allows an application to be assembled by connecting regions with data flows. Include an 'addRegion' element for each instance of a region needed in the app and then add 'addLink' elements for each data flow link between the regions to connect them up.
YAML Syntax:
network:
- registerRegion: (TODO:)
type: <region type>
path: <path to shared lib to link to>
class: <classname to load>
- addRegion:
name: <region name>
type: <region type>
params: <list of parameters> (optional)
phase: <phase number> (optional)
- addLink:
src: <Name of the source region "." Output name>
dest: <Name of the destination region "." Input name>
delay: <iterations to delay> (optional, default=0)
JSON syntax:
{network: [
{addRegion: {name: <region name>, type: <region type>, params: {<parameters>}, phase: <phase>}},
{addLink:{src: "<region name>.<output name>", dest: "<region name>.<output name>", delay: <delay>}},
]}
JSON example:
{network: [
{addRegion: {name: "encoder", type: "RDSEEncoderRegion", params: {size: 1000, sparsity: 0.2, radius: 0.03, seed: 2019, noise: 0.01}}},
{addRegion: {name: "sp", type: "SPRegion", params: {columnCount: 2048, globalInhibition: true}}},
{addRegion: {name: "tm", type: "TMRegion", params: {cellsPerColumn: 8, orColumnOutputs: true}}},
{addLink: {src: "encoder.encoded", dest: "sp.bottomUpIn"}},
{addLink: {src: "sp.bottomUpOut", dest: "tm.bottomUpIn"}}
]}