API End Points

The Apprentice Learner Architecture is implemented in the form of a RESTful API. Here we document the expected request and response structures for each of the API endpoints. The 5 current end points are:

• Create
• Request
• Train
• Check
• Report

Create

Description: Used to instantiate new agents remotely.

Target: localhost:8000/create/

Methods: POST

Example

Request

{
  "agent_type": "ModularAgent",
  "args": {
    "when_learner": "decisiontree",
    "where_learner": "mostspecific",
    "heuristic_learner": "proportioncorrect",
    "how_cull_rule": "mostparsimonious",
    "planner": "vectorized_planner",
    "search_depth": 2,
    "numerical_epsilon": 0.0,
    "feature_set": [],
    "function_set": [],
  },
}

Response

{"agent_id":12}

Request Format

Required Fields

• agent_type - Defines the type of agent you want to create and changes the interpretation of some of the other fields, see below. Must be one of the following: ModularAgent, WhereWhenHowNoFoa, RLAgent, Memo, Stub.

Optional Fields

• name - A human readable name for the agent that can also be used to reference it in future calls.
• args - Used to provide additional parameters to the creation of the Agent based on agent_type. See the page on Agent Types for more information on the expected structure for each agent_type.
• project_id - Associates the agent to a particular project. Projects are mainly used for organization and to provide a agents with a common set of initial operators for relational inference and how search. Agents are automatically assigned to the default project (1) if left unspecified. Must be an integer > 0.
• feature_set - A list specifying an additional set of initial operators this agent can use to perform relational inference. Must be a list of int ids or string names.
• function_set - A list specifying an additional set of initial operators this agent can use to perform how search. Must be a list of int ids or string names.
• stay_active - A boolean flag for whether to maintain the agent in RAM as the active agent or allowing it to be saved in and out of RAM. Default is false.
• dont_save - A boolean flag for whether to prevent saving the agent into the database during future calls. Default is false.

Response Format

Fields

• agent_id - The id used to reference the created agent in the future.

Request

Description: Used to request an action description from the

Targets: localhost:8000/request/{agent_id}

localhost:8000/request/{agent_name}

Methods: POST

Example

Request

{
  "state": {
    "?ele-carry1": {"id": "carry1", "value": "", "contentEditable": true }, 
    "?ele-carry2": {"id": "carry2", "value": "", "contentEditable": true },
    "?ele-carry3": {"id": "carry3", "value": "", "contentEditable": true },
    "?ele-ctatdiv51": {"id": "ctatdiv51"},
    "?ele-ctatdiv54": {"id": "ctatdiv54"},
    "?ele-ctatdiv68": {"id": "ctatdiv68"},
    "?ele-done": {"id": "done"},
    "?ele-hint": {"id": "hint"},
    "?ele-inpA1": {"id": "inpA1", "value": "2", "contentEditable": false },
    "?ele-inpA2": {"id": "inpA2", "value": "2", "contentEditable": false },
    "?ele-inpA3": {"id": "inpA3", "value": "2", "contentEditable": false },
    "?ele-inpB1": {"id": "inpB1", "value": "2", "contentEditable": false },
    "?ele-inpB2": {"id": "inpB2", "value": "3", "contentEditable": false },
    "?ele-inpB3": {"id": "inpB3", "value": "1", "contentEditable": false },
    "?ele-out1": {"id": "out1", "value": "", "contentEditable": true },
    "?ele-out2": {"id": "out2", "value": "", "contentEditable": true },
    "?ele-out3": {"id": "out3", "value": "", "contentEditable": true },
    "?ele-out4": {"id": "out4", "value": "", "contentEditable": true }
  }
}

Response

If the agent has a skill relevant to the state:

{
  "selection":"out1",
  "action":"UpdateTextField",
  "inputs":{ "value":"4" }
}

If the agent does not have a skill relevant to the state:

{}

Request Format

Required Field

• state - A JSON description of the current state of the interface or learning environment. The format used within this state description can vary widely and there are number of special encoding formalism that can be applied. In general, we support the super-set of the JSON specification used in the concept_formation library.

Response Format

The response format to an action request varies depending on whether or not the agent was able to successfully produce an action for the provided state.

Fields

If the agent could produce an action:

• selection - The name of the element being acted on
• action - The operation being performed on the selection
• inputs - An object containing the named arguments to the action being performed.

If the agent could not produce an action it will currently return an empty object. This imply it will require a training demonstration in order to act in a similar situation in the future.

Train

Description: Used to provide a training demonstration to an agent.

Targets: localhost:8000/train/{agent_id}

localhost:8000/train/{agent_name}

Methods: POST

Example

Request

{
  "selection": "out1",
  "action": "UpdateTextField",
  "inputs": {
    "value": "4"
  },
  "reward": 1,
  "state": {
    "?ele-carry1": {"id": "carry1", "value": "", "contentEditable": true }, 
    "?ele-carry2": {"id": "carry2", "value": "", "contentEditable": true },
    "?ele-carry3": {"id": "carry3", "value": "", "contentEditable": true },
    "?ele-ctatdiv51": {"id": "ctatdiv51"},
    "?ele-ctatdiv54": {"id": "ctatdiv54"},
    "?ele-ctatdiv68": {"id": "ctatdiv68"},
    "?ele-done": {"id": "done"},
    "?ele-hint": {"id": "hint"},
    "?ele-inpA1": {"id": "inpA1", "value": "2", "contentEditable": false },
    "?ele-inpA2": {"id": "inpA2", "value": "2", "contentEditable": false },
    "?ele-inpA3": {"id": "inpA3", "value": "2", "contentEditable": false },
    "?ele-inpB1": {"id": "inpB1", "value": "2", "contentEditable": false },
    "?ele-inpB2": {"id": "inpB2", "value": "3", "contentEditable": false },
    "?ele-inpB3": {"id": "inpB3", "value": "1", "contentEditable": false },
    "?ele-out1": {"id": "out1", "value": "", "contentEditable": true },
    "?ele-out2": {"id": "out2", "value": "", "contentEditable": true },
    "?ele-out3": {"id": "out3", "value": "", "contentEditable": true },
    "?ele-out4": {"id": "out4", "value": "", "contentEditable": true }
  }
}

Response

If the agent has a skill relevant to the state:

"OK"

Request Format

Required Field

• selection - The name of the target of the action being demonstrated.
• action - The name of the kind of action being demonstrated.
• inputs - An object whose fields describe the named arguments to the action being demonstrated.
• reward - A float value between -1.0 and 1.0 denoting whether the agent should view the action as positive or negative. 1.0 implies correct for categorical when learners, while -1.0 implies incorrect. Some configurations are able to interpret 0.0 as a neutral demonstration.
• state - A JSON description of the current state of the interface or learning environment. The format used within this state description can vary widely and there are number of special encoding formalism that can be applied. In general, we support the super-set of the JSON specification used in the concept_formation library.

Optional Fields

• skill_label - An explicit label for the skill being demonstrated. Skill labels represent a hard disjuncture in the agent's knowledge in that demonstrations for one skill_label will never be considered candidates for a different skill_label. If left off all demonstrations are assigned "NO_LABEL" and the agent will reason about which skills to associated the demonstration with.
• foci_of_attention - Specifies a set of foci of attention that describe the elements of the broader state that are specifically relevant for explaining the demonstration. Providing these can potentially improve performance.
• correct - A boolean describing whether or not the action should be viewed as correct. This can be used in place of the reward field, where a value of true is equivalent to a 1.0 reward. This is primarily kept around as a legacy support for how specifying correctness used to work.

Response Format

A train request is not meant to be treated as a transaction so if the agent is able to update this knowledge without errors it will return a simple HTTP 200 response of "OK".

#Check Description: Used to provide feedback given a state and action description.

Targets: localhost:8000/check/{agent_id}

localhost:8000/check/{agent_name}

Methods: POST

Example

Request

{
  "selection": "out1",
  "action": "UpdateTextField",
  "inputs": {
    "value": "4"
  },
  "state": {
    "?ele-carry1": {"id": "carry1", "value": "", "contentEditable": true }, 
    "?ele-carry2": {"id": "carry2", "value": "", "contentEditable": true },
    "?ele-carry3": {"id": "carry3", "value": "", "contentEditable": true },
    "?ele-ctatdiv51": {"id": "ctatdiv51"},
    "?ele-ctatdiv54": {"id": "ctatdiv54"},
    "?ele-ctatdiv68": {"id": "ctatdiv68"},
    "?ele-done": {"id": "done"},
    "?ele-hint": {"id": "hint"},
    "?ele-inpA1": {"id": "inpA1", "value": "2", "contentEditable": false },
    "?ele-inpA2": {"id": "inpA2", "value": "2", "contentEditable": false },
    "?ele-inpA3": {"id": "inpA3", "value": "2", "contentEditable": false },
    "?ele-inpB1": {"id": "inpB1", "value": "2", "contentEditable": false },
    "?ele-inpB2": {"id": "inpB2", "value": "3", "contentEditable": false },
    "?ele-inpB3": {"id": "inpB3", "value": "1", "contentEditable": false },
    "?ele-out1": {"id": "out1", "value": "", "contentEditable": true },
    "?ele-out2": {"id": "out2", "value": "", "contentEditable": true },
    "?ele-out3": {"id": "out3", "value": "", "contentEditable": true },
    "?ele-out4": {"id": "out4", "value": "", "contentEditable": true }
  }
}

Response

{"correct":true}

Request Format

Required Field

• selection - The name of the target of the action being assessed.
• action - The name of the kind of action being assessed.
• inputs - An object whose fields describe the named arguments to the action being assessed.
• state - A JSON description of the current state of the interface or learning environment. The format used within this state description can vary widely and there are number of special encoding formalism that can be applied. In general, we support the super-set of the JSON specification used in the concept_formation library.

Response Format

Fields

• correct - A boolean flag for whether the action is correct or not.

#Report Description: Used to provide basic usage statistic information on a particular agent.

Targets: localhost:8000/report/{agent_id}

localhost:8000/report/{agent_name}

Methods: GET

Example

Response

{
   "id": 2,
   "name": "Test-Agent",
   "num_request": 12,
   "num_train": 13,
   "num_check": 0,
   "created": Need to confirm format,
   "updated": Need to confirm format
}

Response Format

Fields

• id - The agent's id used to reference it.
• name - The agent's readable name that can also be used for reference.
• num_request - The number of times the request target has been called on the agent.
• num_train - The number of times the train target has been called on the agent.
• num_check - The number of times the check target has been called on the agent.
• created - The time stamp from when the agent was created. In the timezone of the server.
• updated - The time stamp of the last time the agent's internal state was updated. Functionally this corresponds to the last time a successful train request was made.