Purpose

To demonstrate what is possible with the API, and to provide a more practical interface to the data, we have created a set of tools which can be found in the api-tools repository.

Python Library

The planning_domains_api.py library provides access to the API through the following functions (more to be added in the future):

Example that demonstrates how to test on every problem in the "All IPC" set (note, this assumes that you have already run the command line utility to set up the location of the planning. domains repository):

import sys

print "Loading domains...",
sys.stdout.flush()

import planning_domains_api as api

# 12 is the collection for all STRIPS IPC domains
domains = {}
for dom in api.get_domains(12):

    # Turn the links into relative paths for this machine
    probs = api.get_problems(dom['domain_id'])

    # Map the domain name to the list of domain-problem pairs
    domains[dom['domain_name']] = []
    for p in probs:
        domains[dom['domain_name']].append((p['domain_path'], p['problem_path']))

print "done!"

Command-line Utility

The planning.domains.py command-line utility allows you to setup your repository of domains and do primitive queries. It will check out the domains repository if you wish, and store a local settings file so that it can be automatically retrieved using the planning_domains_api.py library.

The local settings file is also used by the API in order to store the user's email and (if available) access token for making changes to the API attributes.

The tool is interactive to set things up, so just run ./planning.domains.py from the command line to get started. You can also run it without parameters to get the usage:

> ./planning.domains.py

 No command-line options given.  Usage:

 planning.domains.py update                                Update the local domain repository.

 planning.domains.py register                              Register your email and token for making API edits

 planning.domains.py find collections [string]             Find collections whose title/ID contains 'string'
 planning.domains.py find domains [string]                 Find domains whose title/ID contains 'string'
 planning.domains.py find problems [string]                Find problems whose title/ID contains 'string'

 planning.domains.py show collection [integer]             Find collections whose title/ID contains 'integer'
 planning.domains.py show domain [integer]                 Find domains whose title/ID contains 'integer'
 planning.domains.py show problem [integer]                Find problems whose title/ID contains 'integer'
 planning.domains.py show plan [integer]                   Show the plan (if any) matching the given problem ID

 planning.domains.py list collections                      Lists all of the collections.
 planning.domains.py list tags                             Lists all of the available tags.
 planning.domains.py list null-attribute [string]          Lists all of the problems that have a null attribute setting (string)

 planning.domains.py tag collection [integer] [string]     Tags the specified collection (integer) with a tag (string)
 planning.domains.py tag domain [integer] [string]         Tags the specified domain (integer) with a tag (string)
 planning.domains.py tag problem [integer] [string]        Tags the specified problem (integer) with a tag (string)
 planning.domains.py untag collection [integer] [string]   Un-tags the specified collection (integer) with a tag (string)
 planning.domains.py untag domain [integer] [string]       Un-tags the specified domain (integer) with a tag (string)
 planning.domains.py untag problem [integer] [string]      Un-tags the specified problem (integer) with a tag (string)

 planning.domains.py submit plan [integer] [plan file]     Submit the provided plan for validation and possible storage

 planning.domains.py generate-lab [integer] [string]       Generate a lab-style python file (string) given a collection (integer)
                    

Javascript Library

The planning-domains.js library makes it quick and easy to display problems, domains, and collections on a website. Both jQuery and Bootstrap are prerequisites, but other than that all you need to do is include the JavaScript file somewhere on your page:

<script type="text/javascript" src="planning-domains.js"></script>

Once loaded, you can call any of the following JavaScript functions to populate a div with the appropriate HTML:

• insert_navigator(parent_div, selection_func_name)
  

  Inserts a full navigator of the collections / domains / problems in the API as the HTML text of parent_div. The function matching the name selection_func_name will be invoked with a single parameter corresponding to the problem ID once the user has navigated to a problem and selected it. The selection_func_name parameter is optional, and to see it in action, use the "Import" functionality of editor.planning.domains.

• fetch_collections(query_string, parent_div, selection_func_name)
  

  Populates parent_div with a table of collections matching the query string query_string (e.g., '/collections'). The option selection_func_name will be used as a callback if a row corresponding to a collection is selected, and the collection ID will be used as a parameter.

• fetch_domains(query_string, parent_div, selection_func_name)
  

  Populates parent_div with a table of domains matching the query string query_string (e.g., '/domains/12'). The option selection_func_name will be used as a callback if a row corresponding to a domain is selected, and the domain ID will be used as a parameter.

• fetch_problems(query_string, parent_div, selection_func_name)
  

  Populates parent_div with a table of problems matching the query string query_string (e.g., '/problems/search?domain_name=blocks'). The option selection_func_name will be used as a callback if a row corresponding to a problem is selected, and the problem ID will be used as a parameter.

For examples, see the /web directory of the API Tools Repository.