- QnA Test Agent: An example agent is provided with the download which runs and validates a non-comprehensive set of unit tests based upon available sample data source instances/queries.
All of these steps are discussed in more detail below:
- Build SoarQnA
- Develop desired data source drivers
- Describe driver instances in configuration files
- Create a Soar kernel instance accessible remotely (such as a debugger)
- From a terminal, run the following with host/port/agent corresponding to step #4 and config to step #3
java SoarQnA <host> <port> <agent> <config>
- Run your agent
SoarQnA is a Java application so should work well on any platform (note: it was developed and has only been tested using JDK6).
The class path should include the lib folder and Soar SML java components in addition to any other classes (such as JDBC drivers).
A SQLite JDBC driver has been included in the lib directory for demonstration/demo purposes.
Developing Data Source Drivers
If you wish to develop custom data source drivers, see included demos for guidance. The big picture is as simple as implementing a set of interfaces:
- DataSourceDriver: creates instance connections to a data source.
- DataSourceConnection: creates QueryState instances given query parameters and disconnects an instance connection when appropriate.
- QueryState: maintains all necessary state for an executed query and allows for incremental access to results.
SoarQnA requires two levels of configuration:
- Distinct instance enumeration
- Individual instance description
SoarQnA simply registers for callbacks and thus Soar systems require no modification, aside from being accessible remotely.
The program arguments include standard information to find a remote Soar instance, as well as the main configuration file (described above, such as qna.ini). It is the user's responsibility to provide proper access to Soar SML components (such as via environmental variables). The program will provide status information to standard out as to each of the data source instances in configuration. It then registers for callbacks and waits for the attached Soar kernel to shutdown, at which point it quits.
Once running, SoarQnA will create on the agent input-link a "registry" of all available data source instances and their associated queries. Agents should condition upon this structure for issuing queries.
IO link Specification
The basic input/output-link structures are as follows:
- An agent issues a "qna-query" that specifies the source, query name, query parameters, and how results should be provided (all at once or incrementally).
- If the query is unsucessful, the output command will be augmented with a "^status error" WME.
- If the query is successful, the output command will be augmented with a "^status success" WME as well as an "id" integer-valued WME (which is useful for debugging purposes, as well as if a next command is issued for incremental results). The first "result" will also augment the command. The result identifier has a "features" identifier, with key/value pairs below, and a "next" WME. The next augmentation is either "nil" (no further results), "pending" (additional results, incremental), or a recursive identifier (additional results, all).
- Agents can get additional incremental results via the "qna-next" output command, which requires a "query" WME, with integer value referring to the "id" of a qna-query, and receives a status augmentation. If successful, the "^next pending" WME of the associated query will be replaced with an identifier, with associated features and next.<< nil pending >>.
Note that currently all results come back during a single output phase. Care should be taken to avoid costly queries, which will severely impact Soar decision cycle time. Ideally a future version will support multi-cycle queries to eliminate this weakness.Developer
- Nate Derbinsky, email@example.com
- Soar 9
- Java, C++
- Laird, J. E., Derbinsky, N. Tinkerhess, M.: A Case Study in Integrating Probabilistic Decision Making and Learning in a Symbolic Cognitive Architecture: Soar Plays Dice. Papers from the 2011 AAAI Fall Symposium Series: Advances in Cognitive Systems. Arlington, VA