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.

Create

Description: Used to instantiate new agents remotely.

Target: localhost:8000/create/

Methods: POST

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.
• args - Used to provide additional parameters to the creation of the Agent based on agent_type,

Optional Fields

• 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.

ModularAgent

The ModularAgent type is the agent type you will use in most cases. It represents the current best implementation of the Apprentice Learner API as a modular architecture that can represent a number of different learners. The ModularAgent's args object contains the following optional fields:

• when_learner - Specifies which implementation to use for when learning. Must be one of the following:
  • decisiontree - A standard decision tree classifier. Uses the implementation of DecisionTreeClassifier from scikit.
  • cobweb - A hierarchical concept formation tree that can be applied to mixed nominal and numeric data. Uses the implementation of Cobweb3 from the concept_formation library.
  • trestle - A hierarhcical concept formation tree that can handle structured input data in addition to mixed nominal and numeric data. Uses the implementation of Trestle from the concept_formation library.
• where_learner - Specifies which implementation to use for where learning. Must be one of the following:
  • mostspecific
  • stateresponselearner
  • relationallearner
  • specifictogeneral
• heuristic_learner - Specifies which implementation to use for which learning. Must be one of the following:
  • proportioncorrect - Resolves skill conflicts by favoring the skill with the highest percentage of being correct in the past.
  • totalcorrect - Resolves skill conflicts by favoring the skill with the highest total correct applications.
• how_cull_rule - Specifies which implementation to use to limit the How Search. Must be one of the following:
  • first - how search returns the first explanation that successfully covers the demonstration.
  • mostparsimonious - how search returns the shortest explanation that successfully covers the demonstration
  • all - how search returns all explanations
• planner - Specifies which planner implementation to use for How Search. Must be one of the following:
  • fo_planner - A first order logic planner. This is the original implementation of the Apprentice Learner but can be slower in some situations.
  • vectorized_planner - A vectorized implementation of a planner. This implementation is faster but can currently only be applied to numerical data and a subset of operators.
• search_depth - Specifies the depth of explanation to use for how search.
• numerical_epsilon - Specifies a maximum difference between 2 float values for numbers to be considered equal during planner searches.

WhereWhenHowNoFoa

The WhereWhenHowNoFoa is an older implementation of the Apprentice Learner on which the ModularAgent is based. You will likely never use it directly unless you are trying to replicate an old finding or doing some regression testing. The WhereWhenHowNoFoa's args object contains the following optional fields:

• when_learner - Specifies which implementation to use for when learning. Must be one of the following: decisiontree, cobweb, or trestle.
• where_learner - Specifies which implementation to use for where learning. Must be one of the following: mostspecific, stateresponselearner, relationallearner, or specifictogeneral.
• search_depth - Specifies the depth of explanation to use for how search.
• numerical_epsilon - Specifies a maximum difference between 2 float values for numbers to be considered equal during planner searches.

RLAgent

The RLAgent is an early implementation of a Reinforcement Learning based agent. It is currently an experimental agent so it is not likely to be used. The RLAgent's args object does not support any fields.

Memo

The Memo agent is basic agent that simply memorizes state action pairs and responds with the highest reward, demonstrated action for a given request. It mainly exists for testing the other API targets.

Stub

Like the Memo agent, the Stub agent implements each of the core API targets as no-ops. It also mainly exists for API testing purposes.

Request

Description: Used to request an action description from the

Target: localhost:8000/create/

Methods: POST

Required Fields

Optional Fields

Train