# PySoarLib
## Aaron Mininger
### 2018

This is a python library module with code to help make working with Soar SML in python 
just a little bit easier. 

Methods do have docstrings, to read help information open a python shell and type
```
import pysoarlib
help(pysoarlib)
help(pysoarlib.SoarClient)
```

* [SoarClient](#soarclient)
* [Config Settings](#configsettings)
* [AgentConnector](#agentconnector)
* [IdentifierExtensions](#idextensions)
* [WMInterface](#wminterface)
* [SoarWME](#soarwme)
* [SVSCommands](#svscommands)
* [TimeConnector](#timeconnector)
* [util](#util)

<a name="soarclient"></a>
# SoarClient
Defines a class used for creating a soar agent, sending commands, running it, etc.
There are a number of settings that you can use to configure the client (see following subsection) and
can specify either by including them in the config file or by giving as keyword arguments
in the constructor. 

`SoarClient(config_filename=None, print_handler=None, **kwargs)`     
Will create the soar kernel and agent, as well as source the agent files. 
`print_handler` specifies how output is handled (defaults to python print) and 
`config_filename` names a file with client settings in it


`add_connector(AgentConnector, name:str)`    
Adds the given connector and will invoke callbacks on it (such as on_input_phase)

`get_connector(name:str)`    
Returns a connector of the given name, or None

`has_connector(name:str) -> Boolean`    
Returns true if the given connector exists

`add_print_event_handler(handler)`   
Will call the given handler during each soar print event (handler should be a method taking 1 string)

`connect()`     
Will register callbacks (call before running)

`disconnect()`     
Will deregister callbacks

`start()`     
Will cause the agent to start running in new thread (non-blocking)

`stop()`     
Will stop the agent

`execute_command(cmd:str, print_res:bool=False)`     
Sends the given command to the agent and returns the result as a string. If print_res=True it also prints the output using print_handler

`restart()`    
Completely destroys the agent and creates + sources a new one

`kill()`     
Will stop the agent and destroy the agent/kernel


## Config Settings (kwargs or config file)
<a name="configsettings"></a>

These can be passed as keyword arguments to the SoarClient constructor, 
or you can create a config file that contains these settings. 

| Argument           | Type     | Default    | Description                              |
| ------------------ | -------- | ---------- | ---------------------------------------- |
| `agent_name`       | str      | soaragent  | The soar agent's name |
| `agent_source`     | filename |            | The root soar file to source the agent productions  |
| `smem_source`      | filename |            | The root soar file that sources smem add commands |
| `source_output`    | enum str | summary    | How much detail to print when sourcing files: none, summary, or full |
| `watch_level`      | int      | 1          | Sets the soar watch/trace level, how much to print each DC (0=none) |
| `spawn_debugger`   | bool     | false      | If true, spawns the soar java debugger |
| `start_running`    | bool     | false      | If true, will automatically start running the agent |
| `write_to_stdout`  | bool     | false      | If true, will print all soar output to the print_handler |
| `print_handler`    | method   | print      | A method taking 1 string arg, handles agent output |
| `enable_log`       | bool     | false      | If true, writes all soar/agent output to a file |
| `log_filename`     | filename | agent-log.txt | The name of the log file to create |
| **time settings** <a name="timesettings"></a> |          |            |               |
| `use_time_connector`| bool    | false      | If true, creates a TimeConnector to put time info on the input-link |
| `clock_include_ms` | bool     | true       | Will include milliseconds for elapsed and clock times |
| `sim_clock`        | bool     | false      | If false, the clock shows real time. If true, it advances a fixed amount each DC |
| `clock_step_ms`    | int      | 50         | The number of milliseconds the simulated clock advances each decision cycle |

Instead of passing as arguments, you can include them in a file specified by config_filename
Each line in the file should be 'setting = value'

Example File:    
```
agent_name = Rosie    
agent_source = agent.soar    
spawn_debugger = false    
```


<a name="agentconnector"></a>
# AgentConnector
Defines an abstract base class for creating classes that connect to Soar's input/output links

`AgentConnector(client:SoarClient)`     


`add_output_command(command_name:str)`     
Will register a handler that listens to output link commands with the given name

`add_print_event_handler(handler:func)`     
Will register a print event handler (function taking 1 string argument) that will be called whenever a soar print event occurs. 

`on_init_soar()`     
Event Handler called when init-soar happens (need to release SML working memory objects)

`on_input_phase(input_link:Identifier)`     
Event Handler called every input phase

`on_output_event(command_name, root_id)`     
Event Handler called when a new output link command is created `(<output-link> ^command_name <root_id>)`





<a name="idextensions"></a>
# IdentifierExtensions 
These add a few helper methods to the sml.Identifier class:
(Do not need to import directly, come with any import from module)

`Identifier.GetChildString(attribute:str)`     
Given an attribute, will look for a child WME of the form `(<id> ^attribute <value>)` and return the value as a string

`Identifier.GetChildInt(attribute:str)`     
Given an attribute, will look for a child IntegerWME of the form `(<id> ^attribute <value>)` and return the value as an integer

`Identifier.GetChildFloat(attribute:str)`     
Given an attribute, will look for a child FloatWME of the form `(<id> ^attribute <value>)` and return the value as an float

`Identifier.GetChildId(attribute:str)`     
Given an attribute, will look for a child WME of the form `(<id> ^attribute <child_id>)` and return an Identifier with child_id as the root

`Identifier.GetAllChildIds(attribute:str=None)`     
Given an attribute, returns a list of Identifiers from all child WME's matching `(<id> ^attribute <child_id>)`
If no attribute is specified, all child Identifiers are returned

`Identifier.GetAllChildValues(attribute:str=None)`     
Given an attribute, returns a list of strings from all child WME's matching `(<id> ^attribute <value>)`
If no attribute is specified, all child WME values (non-identifiers) are returned

`Identifier.GetAllChildWmes()`     
Returns a list of (attr, val) tuples representing all wmes rooted at this identifier.
val will either be an Identifier or a string, depending on its type """


<a name="wminterface"></a>
# WMInterface:    
An interface class which defines a standard way of adding/removing structures from working memory:

`is_added()`    
Returns True if the structure is currently added to working memory

`add_to_wm(parent_id)`    
Adds the structure to working memory under the given identifier

`update_wm(parent_id=None)`    
Applies any changes to working memory    
Note, if a `parent_id` is given and the item is not yet added to wm, it will add it

`remove_from_wm()`    
Removes the structure from working memory


<a name="soarwme"></a>
# SoarWME:    
A class which can represent a WMElement with an `(<id> ^att value)` but takes care of actually interfacing with working memory

You can update its value whenever you want, it will not affect working memory. To change working memory, call `add_to_wm`, `update_wm`, and `remove_from_wm` during an event callback (like BEFORE_INPUT_PHASE)


<a name="svscommands"></a>
# SVSCommands:
A collection of helper functions to create string commands that can be send to SVS
Here pos, rot, and scl are lists of 3 numbers (like [1, 2.5, 3.1])

* `add_box(obj_id, pos=None, rot=None, scl=None)`
* `change_pos(obj_id, pos)`
* `change_rot(obj_id, rot)`
* `change_scl(obj_id, scl)`
* `delete(obj_id)`
* `add_tag(obj_id, tag_name, tag_value)`
* `change_tag(obj_id, tag_name, tag_value)`
* `delete_tag(obj_id, tag_name)`

<a name="timeconnector"></a>
# TimeConnector
An AgentConnector that will create time info on the input-link. 
Includes elapsed time since the agent started, and can have a real-time or simulated wall clock. 
It is enabled through the client setting `use-time-connector=True`
There are several settings that control its behavior as described in [Config Settings](#timesettings). 


```
# Will add and update the following on the input-link:
([il] ^time [t])
([t] ^seconds [secs] # real-time seconds elapsed since start of agent
     ^milliseconds [ms] # real-time milliseconds elapsed since start
     ^steps [steps] # number of decision cycles since start of agent
     ^clock [clock])
([clock] ^hour [hr] # 0-23
         ^minute [min] # 0-59
         ^second [sec] # 0-59
         ^millisecond [ms] # 0-999
         ^epoch [sec] # Unix epoch time in seconds)
```

Also, if using a simulated clock, the agent can change the time itself using an output command:
```
([out] ^set-time [cmd])
([cmd] ^hour 9
       ^minute 15
       ^second 30) # optional 
```

<a name="util"></a>
# pysoarlib.util
Package containing several utility functions for reading/writing working memory through sml structures.

#### `parse_wm_printout(text:str)`   

Given a printout of soar's working memory (p S1 -d 4), parses it into a dictionary of wmes, 
where the keys are identifiers, and the values are lists of wme triples rooted at that id.

You can wrap the result with a PrintoutIdentifier(wmes, root_id) which will provide an Identifier-like
iterface for crawling over the graph structure. It provides all the methods in the IdentifierExtensions interface.


#### `extract_wm_graph(root_id, max_depth)`

Recursively explores all working memory reachable from the given root_id (up to max_depth),
builds up a graph structure representing all that information. 

Note: max_depth is optional (defaults to no depth limit), and the function is smart about handling cycles (will not recurse forever)

```
# Returns a WMNode object wrapping the root_id and containing links to children
node.id = root_id (Identifier)
node.symbol = string (The root_id symbol e.g. O34)
node.attributes() - returns a list of child attribute strings
node['attr'] = WMNode   # for child identifiers
node['attr'] = constant # for string, double, or int value
node['attr'] = [ val1, val2, ... ] # for multi-valued attributes 
               (values can be constants or WMNodes)
str(node) - will pretty-print the node and all children recursively
```


#### `update_wm_from_tree(root_id, root_name, input_dict, wme_table)`

Will update working memory using the given `input_dict` as the provided structure rooted at `root_id`. 
Created wme's are stored in the given `wme_table`, which should be a dictionary that is kept across
multiple calls to this function. `root_name` specifies a prefix for each wme name in the wme_table. 

```
# input_dict should have the following structure:
{
  'attr1': getter() <- The value will be the result of calling the given getter function
  'attr2': dict   <- The value will be a child identifier with its own recursive substructure
}
```

#### `remove_tree_from_wm(wme_table)`    
      
Given a wme_table filled by `SoarUtils.update_wm_from_tree`, removes all wmes from working memory