Adding py files

.gitattributes

@@ -6,6 +6,7 @@
 *.ftz filter=lfs diff=lfs merge=lfs -text
 *.gz filter=lfs diff=lfs merge=lfs -text
 *.h5 filter=lfs diff=lfs merge=lfs -text
+*.jar filter=lfs diff=lfs merge=lfs -text
 *.joblib filter=lfs diff=lfs merge=lfs -text
 *.lfs.* filter=lfs diff=lfs merge=lfs -text
 *.mlmodel filter=lfs diff=lfs merge=lfs -text
@@ -23,6 +24,7 @@
 *.pth filter=lfs diff=lfs merge=lfs -text
 *.rar filter=lfs diff=lfs merge=lfs -text
 *.safetensors filter=lfs diff=lfs merge=lfs -text
+*.so filter=lfs diff=lfs merge=lfs -text
 saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.tar.* filter=lfs diff=lfs merge=lfs -text
 *.tflite filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.10-slim-buster
+
+WORKDIR /app
+
+COPY requirements.txt requirements.txt
+RUN pip3 install -r requirements.txt
+
+ENV SOAR_HOME="/app/soar-bin_debian-buster"
+ENV PYTHONPATH="${SOAR_HOME}:${PYTHONPATH}"
+ENV DYLD_LIBRARY_PATH="${SOAR_HOME}:${DYLD_LIBRARY_PATH}"
+
+COPY . .
+
+RUN chmod 777 /app/*
+# RUN chmod 777 /app/data/*
+
+EXPOSE 7860 7860
+
+ENTRYPOINT ["python3"]
+CMD [ "gradio_app.py"]

README.md

@@ -1,8 +1,8 @@
 ---
 title: Soar
-emoji: 💩
-colorFrom: gray
-colorTo: pink
+emoji: 🦅
+colorFrom: white
+colorTo: blue
 sdk: docker
 pinned: false
 license: bsd

gradio_app.py

@@ -0,0 +1,45 @@
+import sys
+import gradio as gr
+
+from pysoarlib import SoarClient
+from soar_io import GeneralSoarIOConnector
+
+class SoarAgent():
+    def __init__(self):
+        self.client, self.agent_io = self.make_soar_agent()
+        print("Agent created.")
+
+    def make_soar_agent(self):
+        client = SoarClient(write_to_stdout=True,remote_connection=False)
+        myIOConnector = GeneralSoarIOConnector(client)
+        client.add_connector("generalIO", myIOConnector)
+        client.connect()
+
+        return client, myIOConnector
+
+    def execute_command(self, cmd):
+        try:
+            self.client.execute_command(str(cmd))
+        except:
+            print(" * ERROR: Caught exception from Soar", file=sys.stderr)
+
+    def get_output(self):
+        return self.agent_io.get_agent_output()
+
+    def kill(self):
+        self.client.kill()
+        print("Agent shut down.")
+
+
+soar_agent = SoarAgent()
+
+def run_soar(cmd):
+    soar_agent.execute_command(cmd)
+    agent_output = soar_agent.get_output()
+    return str(agent_output)
+
+gr.Interface(fn=run_soar,
+            inputs=["text"],
+            outputs=["text"]).launch(inbrowser=True, server_port=7860)
+
+soar_agent.kill()

pysoarlib/AgentConnector.py

@@ -0,0 +1,88 @@
+""" Generic Base Class for interfacing with a soar agent's input/output links
+
+A Connector can be added to a SoarClient and can handle input/output 
+    while taking care of specific SML calls and event registering
+"""
+
+from __future__ import print_function
+ 
+import traceback, sys
+
+class AgentConnector(object):
+    """ Base Class for handling input/output for a soar agent
+
+    Input:
+        on_input_phase will be automatically called before each input phase
+
+    Output:
+        call add_output_command to add the name of an output-link command to look for
+        on_output_event will then be called if such a command is added by the agent
+
+    Look at LanguageConnector for an example of an AgentConnector used in practice
+    """
+    def __init__(self, client):
+        """ Initialize the Connector (but won't register event handlers until connect)
+
+        client should be an instance of SoarClient
+        """
+        self.client = client
+        self.connected = False
+        self.output_handler_ids = { }
+
+
+    def add_output_command(self, command_name):
+        """ Will cause the connector to handle commands with the given name on the output-link """
+        if self.connected:
+            self.output_handler_ids[command_name] = self.client.agent.AddOutputHandler(
+                    command_name, AgentConnector._output_event_handler, self)
+        else:
+            self.output_handler_ids[command_name] = -1
+
+    def connect(self):
+        """ Adds event handlers, automatically called by the SoarClient """
+        if self.connected:
+            return
+
+        for command_name in self.output_handler_ids:
+            self.output_handler_ids[command_name] = self.client.agent.AddOutputHandler(
+                    command_name, AgentConnector._output_event_handler, self)
+
+        self.connected = True
+
+    def disconnect(self):
+        """ Removes event handlers, automatically called by the SoarClient """
+        if not self.connected:
+            return
+
+        for command_name in self.output_handler_ids:
+            self.client.agent.RemoveOutputHandler(self.output_handler_ids[command_name])
+            self.output_handler_ids[command_name] = -1
+
+        self.connected = False
+
+    def on_init_soar(self):
+        """ Override to handle an init-soar event (remove references to SML objects """
+        pass
+
+    def on_input_phase(self, input_link):
+        """ Override to update working memory, automatically called before each input phase """
+        pass
+
+    def on_output_event(self, command_name, root_id):
+        """ Override to handle output commands with the given name (added by add_output_command) 
+
+        root_id is the root Identifier of the command (e.g. (<output-link> ^command_name <root_id>)
+        """
+        pass
+
+    @staticmethod
+    def _output_event_handler(self, agent_name, att_name, wme):
+        """ OutputHandler callback for when a command is put on the output link """
+        try:
+            if wme.IsJustAdded() and wme.IsIdentifier():
+                root_id = wme.ConvertToIdentifier()
+                self.on_output_event(att_name, root_id)
+        except:
+            self.client.print_handler("ERROR IN OUTPUT EVENT HANDLER")
+            self.client.print_handler(traceback.format_exc())
+            self.client.print_handler("--------- END ---------------")

pysoarlib/IdentifierExtensions.py

@@ -0,0 +1,79 @@
+""" Defines additional helper methods for the Identifier class for accessing child values
+
+This module is not intended to be imported directly,
+Importing the pysoarlib module will cause these to be added to the Identifier class
+Note that the methods will use CamelCase, so get_child_str => GetChildStr
+"""
+_INTEGER_VAL = "int"
+_FLOAT_VAL = "double"
+_STRING_VAL = "string"
+
+def get_child_str(self, attribute): 
+    """ Given id and attribute, returns value for WME as string (self ^attribute value) """
+    wme = self.FindByAttribute(attribute, 0)
+    if wme == None or len(wme.GetValueAsString()) == 0:
+        return None
+    return wme.GetValueAsString()
+
+def get_child_int(self, attribute): 
+    """ Given id and attribute, returns integer value for WME (self ^attribute value) """
+    wme = self.FindByAttribute(attribute, 0)
+    if wme == None or wme.GetValueType() != _INTEGER_VAL:
+        return None
+    return wme.ConvertToIntElement().GetValue()
+
+def get_child_float(self, attribute): 
+    """ Given id and attribute, returns float value for WME (self ^attribute value) """
+    wme = self.FindByAttribute(attribute, 0)
+    if wme == None or wme.GetValueType() != _FLOAT_VAL:
+        return None
+    return wme.ConvertToFloatElement().GetValue()
+
+def get_child_id(self, attribute): 
+    """ Given id and attribute, returns identifier value of WME (self ^attribute child_id) """
+    wme = self.FindByAttribute(attribute, 0)
+    if wme == None or not wme.IsIdentifier():
+        return None
+    return wme.ConvertToIdentifier()
+
+def get_all_child_ids(self, attribute=None): 
+    """ Given id and attribute, returns a list of child identifiers from all WME's matching (self ^attribute child_id)
+
+    If no attribute is specified, all child identifiers are returned
+    """
+    child_ids = []
+    for index in range(self.GetNumberChildren()):
+        wme = self.GetChild(index)
+        if not wme.IsIdentifier():
+            continue
+        if attribute == None or wme.GetAttribute() == attribute:
+            child_ids.append(wme.ConvertToIdentifier())
+    return child_ids
+
+def get_all_child_values(self, attribute=None): 
+    """ Given id and attribute, returns a list of strings of non-identifier values from all WME's matching (self ^attribute value)
+    
+    If no attribute is specified, all child values (non-identifiers) are returned
+    """
+    child_values = []
+    for index in range(self.GetNumberChildren()):
+        wme = self.GetChild(index)
+        if wme.IsIdentifier():
+            continue
+        if attribute == None or wme.GetAttribute() == attribute:
+            child_values.append(wme.GetValueAsString())
+    return child_values
+
+def get_all_child_wmes(self):
+    """ 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 """
+    wmes = []
+    for index in range(self.GetNumberChildren()):
+        wme = self.GetChild(index)
+        if wme.IsIdentifier():
+            wmes.append( (wme.GetAttribute(), wme.ConvertToIdentifier()) )
+        else:
+            wmes.append( (wme.GetAttribute(), wme.GetValueAsString()) )
+    return wmes
+
+

pysoarlib/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Aaron Mininger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pysoarlib/README.md

@@ -0,0 +1,285 @@
+# 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 
+
+
+

pysoarlib/SVSCommands.py

@@ -0,0 +1,84 @@
+"""
+This module defines a set of methods that generate SVS string commands 
+"""
+class SVSCommands:
+    """ Contains static methods that generate SVS string commands
+
+    These can then be passed to agent.SendSVSCommands
+    Note that all transforms (pos, rot, scale) should be lists of 3 floats
+    """
+    @staticmethod
+    def pos_to_str(pos):
+        """ Returns a string of 3 space-separated position values """
+        return "{:f} {:f} {:f}".format(pos[0], pos[1], pos[2])
+    
+    @staticmethod
+    def rot_to_str(rot):
+        """ Returns a string of 3 space-separated rotation values """
+        return "{:f} {:f} {:f}".format(rot[0], rot[1], rot[2])
+    
+    @staticmethod
+    def scl_to_str(scl):
+        """ Returns a string of 3 space-separated scale values """
+        return "{:f} {:f} {:f}".format(scl[0], scl[1], scl[2])
+    
+    @staticmethod
+    def bbox_verts():
+        """ Returns a string of 8 vertices (24 numbers) forming a bounding box
+
+        It is of unit size centered at the origin
+        """
+        return "0.5 0.5 0.5 0.5 0.5 -0.5 0.5 -0.5 0.5 0.5 -0.5 -0.5 -0.5 0.5 0.5 -0.5 0.5 -0.5 -0.5 -0.5 0.5 -0.5 -0.5 -0.5"
+
+    @staticmethod
+    def add_node(node_id, pos=None, rot=None, scl=None, parent="world"):
+        """ Returns an SVS command for adding a graph node to the scene (no geometry) """
+        cmd = "add {:s} {:s} ".format(node_id, parent)
+        if pos: cmd += " p {:s}".format(SVSCommands.pos_to_str(pos))
+        if rot: cmd += " r {:s}".format(SVSCommands.rot_to_str(rot))
+        if scl: cmd += " s {:s}".format(SVSCommands.scl_to_str(scl))
+        return cmd
+    
+    @staticmethod
+    def add_box(obj_id, pos=None, rot=None, scl=None, parent="world"):
+        """ Returns an SVS command for adding a bounding box object to the scene """
+        cmd = "add {:s} {:s} v {:s}".format(obj_id, parent, SVSCommands.bbox_verts())
+        if pos: cmd += " p {:s}".format(SVSCommands.pos_to_str(pos))
+        if rot: cmd += " r {:s}".format(SVSCommands.rot_to_str(rot))
+        if scl: cmd += " s {:s}".format(SVSCommands.scl_to_str(scl))
+        return cmd
+    
+    @staticmethod
+    def change_pos(obj_id, pos):
+        """ Returns an SVS command for changing the position of an svs object """
+        return "change {:s} p {:s}".format(obj_id, SVSCommands.pos_to_str(pos))
+    
+    @staticmethod
+    def change_rot(obj_id, rot):
+        """ Returns an SVS command for changing the rotation of an svs object """
+        return "change {:s} r {:s}".format(obj_id, SVSCommands.rot_to_str(rot))
+    
+    @staticmethod
+    def change_scl(obj_id, scl):
+        """ Returns an SVS command for changing the scale of an svs object """
+        return "change {:s} s {:s}".format(obj_id, SVSCommands.scl_to_str(scl))
+    
+    @staticmethod
+    def delete(obj_id):
+        """ Returns an SVS command for deleting an object """
+        return "delete {:s}".format(obj_id)
+    
+    @staticmethod
+    def add_tag(obj_id, tag_name, tag_value):
+        """ Returns an SVS command for adding a tag to an object (^name value) """
+        return "tag add {:s} {:s} {:s}".format(obj_id, tag_name, tag_value)
+    
+    @staticmethod
+    def change_tag(obj_id, tag_name, tag_value):
+        """ Returns an SVS command for changing a tag on an object (^name value) """
+        return "tag change {:s} {:s} {:s}".format(obj_id, tag_name, tag_value)
+    
+    @staticmethod
+    def delete_tag(obj_id, tag_name):
+        """ Returns an SVS command for deleting a tag with the given name from an object """
+        return "tag delete {:s} {:s}".format(obj_id, tag_name)

pysoarlib/SoarClient.py

@@ -0,0 +1,375 @@
+from __future__ import print_function
+
+from threading import Thread
+import traceback
+from time import sleep
+
+import Python_sml_ClientInterface as sml
+from .SoarWME import SoarWME
+from .TimeConnector import TimeConnector
+
+class SoarClient():
+    """ A wrapper class for creating and using a soar SML Agent """
+    def __init__(self, print_handler=None, config_filename=None, **kwargs):
+        """ Will create a soar kernel and agent
+
+        print_handler determines how output is printed, defaults to python print
+        config_filename if specified will read config info (kwargs) from a file
+            Config file is a text file with lines of the form 'setting = value'
+
+        ============== kwargs =============
+
+        agent_name = [string] (default=soaragent)
+            Name to give the SML Agent when it is created
+
+        agent_source = [filename] (default=None)
+            Soar file to source when the agent is created
+
+        smem_source = [filename] (default=None)
+            Soar file with smem add commands to source the agent is created
+
+        source_output = full|summary|none (default=summary)
+            Determines how much output is printed when sourcing files
+
+        watch_level = [int] (default=1)
+            The watch level to use (controls amount of info printed, 0=none, 5=all)
+
+        start_running = true|false (default=false)
+            If true, will immediately start the agent running
+
+        spawn_debugger = true|false (default=false)
+            If true, will spawn the java soar debugger
+
+        write_to_stdout = true|false (default=false)
+            If true, will print all soar output to the given print_handler (default is python print)
+
+        enable_log = true|false
+            If true, will write all soar output to a file given by log_filename
+
+        log_filename = [filename] (default = agent-log.txt)
+            Specify the name of the log file to write
+
+        remote_connection = true|false (default=false)
+            If true, will connect to a remote kernel instead of creating a new one
+
+        use_time_connector = true|false (default=false)
+            If true, will create a TimeConnector to add time info the the input-link
+            See the Readme or TimeConnector.py for additional settings to control its behavior
+        
+        Note: Still need to call connect() to register event handlers
+        """
+
+        self.print_handler = print_handler
+        if print_handler == None:
+            self.print_handler = print
+        self.print_event_handlers = []
+
+        self.connectors = {}
+
+        # Gather settings, filling in defaults as needed
+        self.kwarg_keys = set(kwargs.keys())
+        self.settings = kwargs
+        self.config_filename = config_filename
+        self._read_config_file()
+        self._apply_settings()
+
+        self.connected = False
+        self.is_running = False
+        self.queue_stop = False
+
+        self.run_event_callback_id = -1
+        self.print_event_callback_id = -1
+        self.init_agent_callback_id = -1
+
+        if self.remote_connection:
+            self.kernel = sml.Kernel.CreateRemoteConnection()
+        else:
+            self.kernel = sml.Kernel.CreateKernelInNewThread()
+            self.kernel.SetAutoCommit(False)
+
+        if self.use_time_connector:
+            self.add_connector("time", TimeConnector(self, **self.settings))
+        self._create_soar_agent()
+
+    def add_connector(self, name, connector):
+        """ Adds an AgentConnector to the agent """
+        self.connectors[name] = connector
+
+    def has_connector(self, name):
+        """ Returns True if the agent has an AgentConnector with the given name """
+        return (name in self.connectors)
+
+    def get_connector(self, name):
+        """ Returns the AgentConnector with the given name, or None """
+        return self.connectors.get(name, None)
+
+    def add_print_event_handler(self, handler):
+        """ calls the given handler during each soar print event, 
+            where handler is a method taking a single string argument """
+        self.print_event_handlers.append(handler)
+
+    def start(self):
+        """ Will start the agent (uses another thread, so non-blocking) """
+        if self.is_running:
+            return
+
+        self.is_running = True
+        thread = Thread(target = SoarClient._run_thread, args = (self, ))
+        thread.start()
+
+    def stop(self):
+        """ Tell the running thread to stop
+        
+        Note: Non-blocking, agent may run for a bit after this call finishes"""
+        self.queue_stop = True
+
+    def execute_command(self, cmd, print_res=False):
+        """ Execute a soar command and return result, 
+            write output to print_handler if print_res is True """
+        result = self.agent.ExecuteCommandLine(cmd).strip()
+        if print_res:
+            self.print_handler(cmd)
+            self.print_handler(result)
+        return result
+
+    def connect(self):
+        """ Register event handlers for agent and connectors """
+        if self.connected:
+            return
+
+        self.run_event_callback_id = self.agent.RegisterForRunEvent(
+            sml.smlEVENT_BEFORE_INPUT_PHASE, SoarClient._run_event_handler, self)
+
+        self.print_event_callback_id = self.agent.RegisterForPrintEvent(
+                sml.smlEVENT_PRINT, SoarClient._print_event_handler, self)
+
+        self.init_agent_callback_id = self.kernel.RegisterForAgentEvent(
+                sml.smlEVENT_BEFORE_AGENT_REINITIALIZED, SoarClient._init_agent_handler, self)
+
+        for connector in self.connectors.values():
+            connector.connect()
+
+        self.connected = True
+
+        if self.start_running:
+            self.start()
+
+    def disconnect(self):
+        """ Unregister event handlers for agent and connectors """
+        if not self.connected:
+            return
+
+        if self.run_event_callback_id != -1:
+            self.agent.UnregisterForRunEvent(self.run_event_callback_id)
+            self.run_event_callback_id = -1
+
+        if self.print_event_callback_id != -1:
+            self.agent.UnregisterForPrintEvent(self.print_event_callback_id)
+            self.print_event_callback_id = -1
+
+        if self.init_agent_callback_id != -1:
+            self.kernel.UnregisterForAgentEvent(self.init_agent_callback_id)
+            self.init_agent_callback_id = -1
+
+        for connector in self.connectors.values():
+            connector.disconnect()
+
+        self.connected = False
+
+    def reset(self):
+        """ Will destroy the current agent and create + source a new one """
+        self._destroy_soar_agent()
+        self._create_soar_agent()
+        self.connect()
+
+    def kill(self):
+        """ Will destroy the current agent + kernel, cleans up everything """
+        self._destroy_soar_agent()
+        self.kernel.Shutdown()
+        self.kernel = None
+
+#### Internal Methods
+    def _read_config_file(self):
+        """ Will read the given config file and update self.settings as necessary (wont overwrite kwarg settings)
+
+        config_filename is a text file with lines of the form 'setting = value'"""
+
+        if self.config_filename is None:
+            return
+
+        # Add any settings in the config file (if it exists)
+        try:
+            with open(self.config_filename, 'r') as fin:
+                config_args = [ line.split() for line in fin ]
+
+            for args in config_args:
+                if len(args) == 3 and args[1] == '=':
+                    key = args[0].replace("-", "_")
+                    # Add settings from config file if not overridden in kwargs
+                    if key not in self.kwarg_keys:
+                        self.settings[key] = args[2]
+        except IOError:
+            pass
+
+    def _apply_settings(self):
+        """ Set up the SoarClient object by copying settings or filling in default values """
+        self.agent_name = self.settings.get("agent_name", "soaragent")
+        self.agent_source = self.settings.get("agent_source", None)
+        self.smem_source = self.settings.get("smem_source", None)
+
+        self.source_output = self.settings.get("source_output", "summary")
+        self.watch_level = int(self.settings.get("watch_level", 1))
+        self.remote_connection = self._parse_bool_setting("remote_connection", False)
+        self.spawn_debugger = self._parse_bool_setting("spawn_debugger", False)
+        self.start_running = self._parse_bool_setting("start_running", False)
+        self.write_to_stdout = self._parse_bool_setting("write_to_stdout", False)
+        self.enable_log = self._parse_bool_setting("enable_log", False)
+        self.log_filename = self.settings.get("log_filename", "agent-log.txt")
+        self.use_time_connector = self._parse_bool_setting("use_time_connector", False)
+
+    def _parse_bool_setting(self, name, default):
+        if name not in self.settings:
+            return default
+        val = self.settings[name]
+        if type(val) == str:
+            return val.lower() == "true"
+        return val
+
+    def _run_thread(self):
+        self.agent.ExecuteCommandLine("run")
+        self.is_running = False
+
+    def _create_soar_agent(self):
+        self.log_writer = None
+        if self.enable_log:
+            try:
+                self.log_writer = open(self.log_filename, 'w')
+            except:
+                self.print_handler("ERROR: Cannot open log file " + self.log_filename)
+
+        if self.remote_connection:
+            self.agent = self.kernel.GetAgentByIndex(0)
+        else:
+            self.agent = self.kernel.CreateAgent(self.agent_name)
+            self._source_agent()
+
+        if self.spawn_debugger:
+            success = self.agent.SpawnDebugger(self.kernel.GetListenerPort())
+
+        self.agent.ExecuteCommandLine("w " + str(self.watch_level))
+
+    def _source_agent(self):
+        self.agent.ExecuteCommandLine("smem --set database memory")
+        self.agent.ExecuteCommandLine("epmem --set database memory")
+
+        if self.smem_source != None:
+            if self.source_output != "none":
+                self.print_handler("------------- SOURCING SMEM ---------------")
+            result = self.agent.ExecuteCommandLine("source " + self.smem_source)
+            if self.source_output == "full":
+                self.print_handler(result)
+            elif self.source_output == "summary":
+                self._summarize_smem_source(result)
+
+        if self.agent_source != None:
+            if self.source_output != "none":
+                self.print_handler("--------- SOURCING PRODUCTIONS ------------")
+            result = self.agent.ExecuteCommandLine("source " + self.agent_source + " -v")
+            if self.source_output == "full":
+                self.print_handler(result)
+            elif self.source_output == "summary":
+                self._summarize_source(result)
+        else:
+            self.print_handler("agent_source not specified, no rules are being sourced")
+
+    # Prints a summary of the smem source command instead of every line (source_output = summary)
+    def _summarize_smem_source(self, printout):
+        summary = []
+        n_added = 0
+        for line in printout.split('\n'):
+            if line == "Knowledge added to semantic memory.":
+                n_added += 1
+            else:
+                summary.append(line)
+        self.print_handler('\n'.join(summary))
+        self.print_handler("Knowledge added to semantic memory. [" + str(n_added) + " times]")
+
+    # Prints a summary of the agent source command instead of every line (source_output = summary)
+    def _summarize_source(self, printout):
+        summary = []
+        for line in printout.split('\n'):
+            if line.startswith("Sourcing"):
+                continue
+            if line.startswith("warnings is now"):
+                continue
+            # Line is only * or # characters
+            if all(c in "#* " for c in line):
+                continue
+            summary.append(line)
+        self.print_handler('\n'.join(summary))
+
+    def _on_init_soar(self):
+        for connector in self.connectors.values():
+            connector.on_init_soar()
+
+    def _destroy_soar_agent(self):
+        self.stop()
+        while self.is_running:
+            sleep(0.01)
+        self._on_init_soar()
+        self.disconnect()
+        if self.spawn_debugger:
+            self.agent.KillDebugger()
+        if not self.remote_connection:
+            self.kernel.DestroyAgent(self.agent)
+        self.agent = None
+        if self.log_writer is not None:
+            self.log_writer.close()
+            self.log_writer = None
+
+    @staticmethod
+    def _init_agent_handler(eventID, self, info):
+        try:
+            self._on_init_soar()
+        except:
+            self.print_handler("ERROR IN INIT AGENT")
+            self.print_handler(traceback.format_exc())
+
+    @staticmethod
+    def _run_event_handler(eventID, self, agent, phase):
+        if eventID == sml.smlEVENT_BEFORE_INPUT_PHASE:
+            self._on_input_phase(agent.GetInputLink())
+
+    def _on_input_phase(self, input_link):
+        try:
+            if self.queue_stop:
+                self.agent.StopSelf()
+                self.queue_stop = False
+
+
+            for connector in self.connectors.values():
+                connector.on_input_phase(input_link)
+
+            if self.agent.IsCommitRequired():
+                self.agent.Commit()
+        except:
+            self.print_handler("ERROR IN RUN HANDLER")
+            self.print_handler(traceback.format_exc())
+
+
+    @staticmethod
+    def _print_event_handler(eventID, self, agent, message):
+        try:
+            if self.write_to_stdout:
+                message = message.strip()
+                self.print_handler(message)
+            if self.log_writer:
+                self.log_writer.write(message)
+                self.log_writer.flush()
+            for ph in self.print_event_handlers:
+                ph(message)
+        except:
+            self.print_handler("ERROR IN PRINT HANDLER")
+            self.print_handler(traceback.format_exc())
+
+

pysoarlib/SoarWME.py

@@ -0,0 +1,87 @@
+"""
+This module defines a utility class called SoarWME 
+which wraps SML code for adding/removing Soar Working Memory Elements (WME)
+"""
+
+from .WMInterface import WMInterface
+
+class SoarWME(WMInterface):
+    """ Wrapper for a single Soar Working Memory Element with a primitive value
+
+        It can wrap an int, float, or string type
+
+        An instance is not directly tied to an SML wme,
+            the user decides how and when soar's working memory is modified
+
+        So you can change the value anytime (asynchronously to soar)
+            And then modify working memory via add_to_wm, update_wm, and remove_from_wm
+            during an agent callback (like BEFORE_INPUT_PHASE)
+    """
+    
+    def __init__(self, att, val):
+        """ Initializes the wme, but does not add to working memory yet
+
+        :param att: The wme's attribute
+        :type att: str
+
+        :param val: The wme's value, any of the 3 main primitive types
+        :type val: int, float, or str
+        """
+        WMInterface.__init__(self)
+        self.att = att
+        self.val = val
+        self.wme = None
+
+        self.changed = False
+
+        if type(val) == int:
+            self.create_wme = self._create_int_wme
+        elif type(val) == float:
+            self.create_wme = self._create_float_wme
+        else:
+            self.create_wme = self._create_string_wme
+
+    def get_attr(self):
+        """ Returns the wme's attribute """
+        return self.att
+
+    def get_value(self):
+        """ Returns the wme's value """
+        return self.val
+
+    def set_value(self, newval):
+        """ Set's the wme's value, but also need to call update_wm to change working memory """
+        if self.val != newval:
+            self.val = newval
+            self.changed = True
+    
+    def __str__(self):
+        return str(self.val)
+
+
+    ### Internal Methods
+
+    def _create_int_wme(self, id, att, val):
+        return id.CreateIntWME(att, val)
+
+    def _create_float_wme(self, id, att, val):
+        return id.CreateFloatWME(att, val)
+
+    def _create_string_wme(self, id, att, val):
+        return id.CreateStringWME(att, str(val))
+
+    def _add_to_wm_impl(self, parent_id):
+        """ Creates a wme in soar's working memory rooted at the given parent_id """
+        self.wme = self.create_wme(parent_id, self.att, self.val)
+
+    def _update_wm_impl(self):
+        """ If the value has changed, will update soar's working memory with the new value """
+        if self.changed:
+            self.wme.Update(self.val)
+            self.changed = False
+
+    def _remove_from_wm_impl(self):
+        """ Will remove the wme from soar's working memory """
+        self.wme.DestroyWME()
+        self.wme = None
+

pysoarlib/TimeConnector.py

@@ -0,0 +1,181 @@
+
+import time
+import datetime
+current_time_ms = lambda: int(round(time.time() * 1000))
+
+from .AgentConnector import AgentConnector
+from .SoarWME import SoarWME
+
+class TimeConnector(AgentConnector):
+    """ An agent connector that will maintain time info on the input-link 
+    
+        The input link will look like:
+        (<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 send the following output-command:
+        (<out> ^set-time <st>) (<st> ^hour <h> ^minute <min> ^second <sec>)
+
+        Settings: 
+            clock_include_ms: bool [default=True]
+                If true, includes milliseconds with both elapsed time and clock time
+            sim_clock: bool [default=False]
+                If true, uses a simulated clock that starts at 8AM and advances a fixed amount every DC
+                If false, will use the local real time
+            clock_step_ms: int [default=5000]
+                If using the simulated clock, this is the number of milliseconds it will increase every DC
+
+    """
+    def __init__(self, client, clock_include_ms=True, sim_clock=False, clock_step_ms=50, **kwargs):
+        """ Initializes the connector with the time info
+
+        clock_include_ms - If True: will include millisecond resolution on clock/elapsed
+            (Setting to false will mean fewer changes to the input-link, slightly faster)
+        sim_clock - If False: clock uses real-time. If True: clock is simulated
+        clock_step_ms - If sim_clock=True, this is how much the clock advances every DC
+        """
+        AgentConnector.__init__(self, client)
+
+        self.include_ms = clock_include_ms
+        self.sim_clock = sim_clock
+        self.clock_step_ms = int(clock_step_ms)
+
+        self.time_id = None
+        self.seconds = SoarWME("seconds", 0) # number of real-time seconds elapsed since start of agent
+        self.milsecs = SoarWME("milliseconds", 0) # number of real-time milliseconds elapsed since start of agent
+        self.steps = SoarWME("steps", 0)     # number of decision cycles the agent has taken
+
+        # Output Link Command: (<out> ^set-time <st>) (<st> ^hour <h> ^minute <min> ^second <sec>)
+        self.add_output_command("set-time")
+
+        # Clock info, hour minute second millisecond
+        self.clock_id = None
+        self.clock_info = [0, 0, 0, 0, 0]
+        self.clock_wmes = [ SoarWME("hour", 0), SoarWME("minute", 0), SoarWME("second", 0), SoarWME("millisecond", 0), SoarWME("epoch", 0) ]
+        self.reset_time()
+
+    def advance_clock(self, num_ms):
+        """ Advances the simulated clock by the given number of milliseconds """
+        self.clock_info[3] += num_ms
+        # MS
+        if self.clock_info[3] >= 1000:
+            self.clock_info[2] += self.clock_info[3] // 1000
+            self.clock_info[4] += self.clock_info[3] // 1000
+            self.clock_info[3] = self.clock_info[3] % 1000
+            # Seconds
+            if self.clock_info[2] >= 60:
+                self.clock_info[1] += self.clock_info[2] // 60
+                self.clock_info[2] = self.clock_info[2] % 60
+                # Minutes
+                if self.clock_info[1] >= 60:
+                    self.clock_info[0] += self.clock_info[1] // 60
+                    self.clock_info[1] = self.clock_info[1] % 60
+                # Hours
+                self.clock_info[0] = self.clock_info[0] % 24
+
+    def update_clock(self):
+        """ Updates the clock with the real time """
+        localtime = time.localtime()
+        self.clock_info[0] = localtime.tm_hour
+        self.clock_info[1] = localtime.tm_min
+        self.clock_info[2] = localtime.tm_sec
+        self.clock_info[3] = current_time_ms() % 1000
+        self.clock_info[4] = int(time.time())
+
+    def reset_time(self):
+        """ Resets the time info """
+        # If simulating clock, default epoch is Jan 1, 2020 at 8 AM
+        default_epoch = int(time.mktime(datetime.datetime(2020, 1, 1, 8, 0, 0, 0).timetuple()))
+        self.clock_info = [8, 0, 0, 0, default_epoch] # [ hour, min, sec, ms, epoch ]
+        self.milsecs.set_value(0)
+        self.seconds.set_value(0)
+        self.steps.set_value(0)
+        self.start_time = current_time_ms()
+
+    def on_init_soar(self):
+        self._remove_from_wm()
+        self.reset_time()
+
+    def set_time(self, hour, min, sec=0, ms=0):
+        if not self.sim_clock:
+            return
+        self.clock_info[0] = hour
+        self.clock_info[1] = (0 if min is None else min)
+        self.clock_info[2] = (0 if sec is None else sec)
+        self.clock_info[3] = ms
+        self.clock_info[4] = int(time.mktime(datetime.datetime(2020, 1, 1, hour, min, sec, ms).timetuple()))
+
+    def on_input_phase(self, input_link):
+        # Update the global timers (time since agent start)
+        self.milsecs.set_value(int(current_time_ms() - self.start_time))
+        self.seconds.set_value(int((current_time_ms() - self.start_time)/1000))
+        self.steps.set_value(self.steps.get_value() + 1)
+
+        # Update the clock, either real-time or simulated
+        if self.sim_clock:
+            self.advance_clock(self.clock_step_ms)
+        else:
+            self.update_clock()
+
+        # Update working memory
+        if self.time_id is None:
+            self._add_to_wm(input_link)
+        else:
+            self._update_wm()
+
+    def on_output_event(self, command_name, root_id):
+        if command_name == "set-time":
+            self.process_set_time_command(root_id)
+    
+    def process_set_time_command(self, time_id):
+        h = time_id.GetChildInt('hour')
+        m = time_id.GetChildInt('minute')
+        s = time_id.GetChildInt('second')
+        self.set_time(h, m, s)
+        time_id.CreateStringWME('status', 'complete')
+
+    ### Internal methods
+
+    def _add_to_wm(self, parent_id):
+        self.time_id = parent_id.CreateIdWME("time")
+        if self.include_ms:
+            self.milsecs.add_to_wm(self.time_id)
+        self.seconds.add_to_wm(self.time_id)
+        self.steps.add_to_wm(self.time_id)
+
+        self.clock_id = self.time_id.CreateIdWME("clock")
+        for i, wme in enumerate(self.clock_wmes):
+            if i == 3 and not self.include_ms:
+                continue
+            wme.set_value(self.clock_info[i])
+            wme.add_to_wm(self.clock_id)
+
+    def _update_wm(self):
+        if self.include_ms:
+            self.milsecs.update_wm()
+        self.seconds.update_wm()
+        self.steps.update_wm()
+        for i, wme in enumerate(self.clock_wmes):
+            wme.set_value(self.clock_info[i])
+            wme.update_wm()
+
+    def _remove_from_wm(self):
+        if self.time_id is None:
+            return
+        for wme in self.clock_wmes:
+            wme.remove_from_wm()
+        self.milsecs.remove_from_wm()
+        self.seconds.remove_from_wm()
+        self.steps.remove_from_wm()
+        self.time_id.DestroyWME()
+        self.time_id = None
+        self.clock_id = None
+

pysoarlib/WMInterface.py

@@ -0,0 +1,53 @@
+"""
+This module defines a utility interface called WMInterface
+which defines a standard interface for adding and removing things from working memory
+"""
+
+class WMInterface(object):
+    """ An interface standardizing how to add/remove items from working memory """
+
+    def __init__(self):
+        self.added = False
+
+    def is_added(self):
+        """ Returns true if the wme is currently in soar's working memory """
+        return self.added
+
+    def add_to_wm(self, parent_id):
+        """ Creates a structure in working memory rooted at the given parent_id """
+        if self.added:
+            self._remove_from_wm_impl()
+        self._add_to_wm_impl(parent_id)
+        self.added = True
+
+    def update_wm(self, parent_id = None):
+        """ Updates the structure in Soar's working memory
+            It will also add it to wm if parent_id is not None """
+        if self.added:
+            self._update_wm_impl()
+        elif parent_id:
+            self._add_to_wm_impl(parent_id)
+            self.added = True
+
+    def remove_from_wm(self):
+        """ Removes the structure from Soar's working memory """
+        if not self.added:
+            return
+        self._remove_from_wm_impl()
+        self.added = False
+
+
+    ### Internal Methods - To be implemented by derived classes
+    
+    def _add_to_wm_impl(self, parent_id):
+        """ Method to implement in derived class - add to working memory """
+        pass
+
+    def _update_wm_impl(self):
+        """ Method to implement in derived class - update working memory """
+        pass
+
+    def _remove_from_wm_impl(self):
+        """ Method to implement in derived class - remove from working memory """
+        pass
+

pysoarlib/__init__.py

@@ -0,0 +1,36 @@
+""" Helper classes and functions for creating a soar agent and working with SML
+
+Depends on the Python_sml_ClientInterface, so make sure that SOAR_HOME is on the PYTHONPATH
+
+SoarClient and AgentConnector are used to create an agent
+WMInterface is a standardized interface for adding/removing structures from working memory
+SoarWME is a wrapper for creating working memory elements
+SVSCommands will generate svs command strings for some common use cases
+
+Also adds helper methods to the Identifier class to access children more easily
+(See IdentifierExtensions)
+
+"""
+import Python_sml_ClientInterface as sml
+
+__all__ = ["WMInterface", "SoarWME", "SVSCommands", "AgentConnector", "SoarClient", "TimeConnector"]
+
+# Extend the sml Identifier class definition with additional utility methods
+from .IdentifierExtensions import *
+sml.Identifier.GetChildString = get_child_str
+sml.Identifier.GetChildInt = get_child_int
+sml.Identifier.GetChildFloat = get_child_float
+sml.Identifier.GetChildId = get_child_id
+sml.Identifier.GetAllChildIds = get_all_child_ids
+sml.Identifier.GetAllChildValues = get_all_child_values
+sml.Identifier.GetAllChildWmes = get_all_child_wmes
+sml.Identifier.__lt__ = lambda self, other: self.GetIdentifierSymbol() < other.GetIdentifierSymbol()
+
+from .WMInterface import WMInterface
+from .SoarWME import SoarWME
+from .SVSCommands import SVSCommands
+from .AgentConnector import AgentConnector
+from .SoarClient import SoarClient
+from .TimeConnector import TimeConnector
+
+

pysoarlib/util/PrintoutIdentifier.py

@@ -0,0 +1,76 @@
+from pysoarlib.util import parse_wm_printout
+
+class PrintoutIdentifier:
+    """ Represents an identifier that was parsed from a soar print command via parse_wm_printout
+        and implements the IdentifierExtensions interface for it """
+
+    def create(client, id, depth):
+        """ Will print the given identifier to the given depth and wrap the result in a PrintoutIdentifier """
+        printout = client.execute_command("p " + id + " -d " + str(depth))
+        if printout.strip().startswith("There is no identifier"):
+            return None
+        wmes = parse_wm_printout(printout)
+        return PrintoutIdentifier(wmes, id) 
+
+    def __init__(self, wmes, root_id):
+        """ wmes is the result of a parse_wm_printout command,
+            root_id is the str id for this identifier """
+        self.wmes = wmes
+        self.root_id = root_id
+
+    def __lt__(self, other):
+        return self.root_id < other.root_id
+
+    def GetIdentifierSymbol(self):
+        return self.root_id
+
+    def GetChildString(self, attr):
+        return self._get_value(attr)
+
+    def GetChildInt(self, attr):
+        val = self._get_value(attr)
+        try:
+            return int(val)
+        except ValueError:
+            return None
+
+    def GetChildFloat(self, attr):
+        val = self._get_value(attr)
+        try:
+            return float(val)
+        except ValueError:
+            return None
+
+    def GetChildId(self, attr):
+        child_id = self._get_value(attr)
+        if child_id is not None:
+            return PrintoutIdentifier(self.wmes, child_id)
+        return None
+
+    def GetAllChildIds(self, attr=None):
+        # Get all children whose values are also identifiers in the wmes dict
+        child_wmes = [ wme for wme in self.wmes.get(self.root_id, []) if wme[2] in self.wmes ]
+        if attr is not None:
+            child_wmes = [ wme for wme in child_wmes if wme[1] == attr ]
+        return [ PrintoutIdentifier(self.wmes, wme[2]) for wme in child_wmes ]
+
+    def GetAllChildValues(self, attr=None):
+        # Get all children whose values are not identifiers in the wmes dict
+        child_wmes = [ wme for wme in self.wmes.get(self.root_id, []) if wme[2] not in self.wmes ]
+        if attr is not None:
+            child_wmes = [ wme for wme in child_wmes if wme[1] == attr ]
+        return [ wme[2] for wme in child_wmes ]
+
+    def GetAllChildWmes(self):
+        child_wmes = []
+        for wme in self.wmes.get(self.root_id, []):
+            if wme[2] in self.wmes:
+                # Identifier
+                child_wmes.append( (wme[1], PrintoutIdentifier(self.wmes, wme[2])) )
+            else:
+                # Value
+                child_wmes.append( (wme[1], wme[2]) )
+        return child_wmes
+
+    def _get_value(self, attr):
+        return next((wme[2] for wme in self.wmes.get(self.root_id, []) if wme[1] == attr), None)

pysoarlib/util/WMNode.py

@@ -0,0 +1,113 @@
+import Python_sml_ClientInterface as sml
+
+### Note: Helper class used by extract_wm_graph
+
+class WMNode:
+    """ Represents a node in the working memory graph wrapping an Identifier and containing links to child wmes
+
+        node.id = root_id (Identifier)
+        node.symbol = string (The root_id symbol e.g. O34)
+        node['attr'] = WMNode   # for identifiers
+        node['attr'] = constant # for string, double, or int value
+        node['attr'] = [ val1, val2, ... ] # for multi-valued attributes (values can be constants or WMNodes)
+    """
+
+    def __init__(self, soar_id):
+        self.id = soar_id
+        self.symbol = soar_id.GetValueAsString()
+        self.children = {}
+
+    def attributes(self):
+        """ Returns a list of all child wme attribute strings """
+        return list(self.children.keys())
+
+    # Supports dictionary syntax (read only)
+    def __getitem__(self, attr):
+        """ Returns the value of the wme (node, attr, val)
+            where a value can be a int, double, string, WMNode,
+            or a list of such values for a multi-valued attribute """
+        return self.children.get(attr, None)
+
+    def __str__(self):
+        """ Returns a nicely formatted string representation of the node and all its children 
+            (Warning: will be a lot of text for large graphs) """
+        return self.__str_helper__("", set())
+
+    def __str_helper__(self, indent, ignore_ids):
+        var = "<" + self.symbol + ">"
+        if self.symbol in ignore_ids or len(self.children) == 0:
+            return var
+
+        ignore_ids.add(self.symbol)
+
+        s = var + " {\n"
+        for a, v in self.children.items():
+            s += indent + "  " + a + ": " + _wm_value_to_str(v, indent + "  ", ignore_ids) + "\n"
+        s += indent + "}"
+        return s
+
+    def _extract_children(self, max_depth, node_map):
+        """ Internal helper method to recursively extract graph structure for a node's children """
+        if max_depth == 0:
+            return
+
+        for index in range(self.id.GetNumberChildren()):
+            wme = self.id.GetChild(index)
+            attr = wme.GetAttribute()
+            if wme.IsIdentifier():
+                child_id = wme.ConvertToIdentifier()
+                child_sym = child_id.GetValueAsString()
+                # First check if the child id is already in the node map
+                if child_sym in node_map:
+                    wme_val = node_map[child_sym]
+                else:
+                    # If not, recursively create and extract the children
+                    wme_val = WMNode(child_id)
+                    node_map[wme_val.symbol] = wme_val
+                    wme_val._extract_children(max_depth-1, node_map)
+
+            elif wme.GetValueType() == "int":
+                wme_val = wme.ConvertToIntElement().GetValue()
+            elif wme.GetValueType() == "double":
+                wme_val = wme.ConvertToFloatElement().GetValue()
+            else:
+                wme_val = wme.GetValueAsString()
+
+            self._add_child_wme(attr, wme_val)
+
+    def _add_child_wme(self, attr, value):
+        """ Adds the child wme to the children dictionary
+            If there are multiple values for a given attr, move them into a list instead of replacing """
+        if attr in self.children:
+            cur_val = self.children[attr]
+            if isinstance(cur_val, list):
+                # Child is already a list, just append
+                cur_val.append(value)
+            else:
+                # This is the second value for the attr, replace current value with a list
+                self.children[attr] = [ cur_val, value ]
+        else:
+            # First time we've seen this attr, just add to dictionary
+            self.children[attr] = value
+
+def _wm_value_to_str(val, indent, ignore_ids):
+    """
+    recursive helper function which returns a string representation of any given value type
+
+    :param val: The value to convert to a string (can be str, int, float, list, WMNode)
+    :param indent: a string of spaces to indent the current level
+    :param ignore_ids: A set of Identifier symbols to not print
+    """
+    if isinstance(val, str):
+        return val
+    if isinstance(val, int):
+        return str(val)
+    if isinstance(val, float):
+        return str(val)
+    if isinstance(val, list):
+        return "[ " + ", ".join(_wm_value_to_str(i, indent, ignore_ids) for i in val) + " ]"
+    if isinstance(val, WMNode):
+        return val.__str_helper__(indent, ignore_ids)
+    return ""
+
+

pysoarlib/util/__init__.py

@@ -0,0 +1,8 @@
+
+__all__ = ["extract_wm_graph", "parse_wm_printout", "PrintoutIdentifier", "update_wm_from_tree", "remove_tree_from_wm" ]
+
+from .extract_wm_graph import extract_wm_graph
+from .parse_wm_printout import parse_wm_printout
+from .update_wm_from_tree import update_wm_from_tree
+from .remove_tree_from_wm import remove_tree_from_wm
+from .PrintoutIdentifier import PrintoutIdentifier

pysoarlib/util/extract_wm_graph.py

@@ -0,0 +1,33 @@
+from .WMNode import WMNode
+
+def extract_wm_graph(root_id, max_depth=-1):
+    """ Given a soar identifier (root_id), crawls over the children and builds a graph rep for them
+        This will handle cycles, where the same node will be used for each reference to an identifier
+
+        :param root_id: The sml identifier of the root of the sub-graph
+        :param max_depth: The maximum depth to extract (defaults to unlimited depth)
+        :return a WMNode containing a recursive enumeration of all children reachable from the given root_id
+
+        Example:
+
+        Given an identifier <obj> with the following wm structure:
+        (<obj> ^id 5 ^volume 23.3 ^predicates <preds>)
+           (<preds> ^predicate red ^predicate cube ^predicate block)
+
+        Will return the following WMNode:
+        WMNode root_node
+            .id = sml Identifier for <obj>
+            .symbol = 'O32'
+            ['id'] = 5
+            ['volume'] = 23.3
+            ['predicates'] = WMNode
+                .id = sml Identifier for <preds>
+                .symbol = 'P53'
+                ['predicate'] = [ 'red', 'cube', 'block' ]
+    """
+    root_node = WMNode(root_id)
+    node_map = dict()
+    node_map[root_node.symbol] = root_node
+    root_node._extract_children(max_depth, node_map)
+    return root_node
+

pysoarlib/util/parse_wm_printout.py

@@ -0,0 +1,75 @@
+
+def parse_wm_printout(text):
+    """ Given a printout of soar's working memory, parses it into a dictionary of wmes, 
+        Where the keys are identifiers, and the values are lists of wme triples rooted at that id
+
+    :param text: The output of a soar print command for working memory
+    :type text: str
+
+    :returns dict{ str, list[ (str, str, str) ] }
+
+    """
+
+    ### First: preprocess the output into a string of tokens
+    tokens = []
+    quote = None
+    for word in text.split():
+        # Handle quoted strings (Between | |)
+        if word[0] == '|':
+            quote = word
+        elif quote is not None:
+            quote += ' ' + word
+        if quote is not None:
+            if len(quote) > 1 and quote.endswith('|'):
+                tokens.append(quote)
+                quote = None
+            elif len(quote) > 1 and quote.endswith('|)'):
+                tokens.append(quote[:-1])
+                quote = None
+            continue
+
+        # Ignore operator preferences
+        if word in [ '+', '>', '<', '!', '=' ]:
+            continue
+        # Ignore activation values [+23.000]
+        if word.startswith("[+") and (word.endswith("]") or word.endswith("])")):
+            continue
+        # Ignore singleton lti's  (@12533)
+        if word.startswith("(@") and word.endswith(")"):
+            continue
+        # Strip opening parens but add $ to indicate identifier
+        if word.startswith("("):
+            word = '$' + word[1:]
+
+        # Don't care about closing parens
+        word = word.replace(")", "")
+        tokens.append(word)
+
+    wmes = dict()
+    cur_id = None
+    cur_att = None
+    cur_wmes = []
+    i = 0
+
+    for token in tokens:
+        if len(token) == 0:
+            continue
+        # Identifier
+        if token[0] == '$':
+            cur_id = token[1:]
+            cur_att = None
+            cur_wmes = []
+            wmes[cur_id] = cur_wmes
+        # Attribute
+        elif token[0] == '^':
+            cur_att = token[1:]
+        # Value
+        elif cur_id is None:
+            print("ERROR: Value " + token + " encountered with no id")
+        elif cur_att is None:
+            print("ERROR: Value " + token + " encountered with no attribute")
+        else:
+            cur_wmes.append( (cur_id, cur_att, token) )
+    
+    return wmes
+

pysoarlib/util/remove_tree_from_wm.py

@@ -0,0 +1,18 @@
+
+def remove_tree_from_wm(wme_table):
+    """
+    Given a wme_table filled by SoarUtils.update_wm_from_tree, removes all wmes from working memory 
+
+    Intermediate nodes are sml.Identifiers, which are removed from the table
+    Leaves are SoarWME's which are kept in the table but .remove_from_wm() is called on them
+    """
+    items_to_remove = set()
+    for path, wme in wme_table.items():
+        if isinstance(wme, sml.Identifier):
+            items_to_remove.add(path)
+        else:
+            wme.remove_from_wm()
+    for path in items_to_remove:
+        del wme_table[path]
+
+

pysoarlib/util/update_wm_from_tree.py

@@ -0,0 +1,35 @@
+from pysoarlib import SoarWME
+
+def update_wm_from_tree(root_id, root_name, input_dict, wme_table):
+    """
+    Recursively update WMEs that have a sub-tree structure rooted at the given identifier.
+
+    We scan through the `input_dict`, which represents the input value getters (or further
+    sub-trees) of the sub-tree root, either adding terminal WMEs as usual or further recursing.
+
+    :param root_id: The sml identifier of the root of the sub-tree
+    :param root_name: The attribute which is the root of this sub-tree
+    :param input_dict: A dict mapping attributes to getter functions
+    :param wme_table: A table to lookup and store wme's and identifiers
+    :return: None
+    """
+    assert isinstance(input_dict, dict), "Should only recurse on dicts!"
+
+    for attribute in input_dict.keys():
+        input_val = input_dict[attribute]
+        child_name = root_name + "." + attribute
+
+        if not callable(input_val):
+            if child_name not in wme_table:
+                wme_table[child_name] = root_id.CreateIdWME(attribute)
+            child_id = wme_table[child_name]
+            SoarUtils.update_wm_from_tree(child_id, child_name, input_val, wme_table)
+            continue
+
+        value = input_val()
+        if child_name not in wme_table:
+            wme_table[child_name] = SoarWME(att=attribute, val=value)
+        wme = wme_table[child_name]
+        wme.set_value(value)
+        wme.update_wm(root_id)
+

requirements.txt

@@ -0,0 +1,2 @@
+gradio
+gcc7

soar_io.py

@@ -0,0 +1,35 @@
+from pysoarlib import *
+
+## DEFINE MAIN CONNECTOR CLASS
+
+class GeneralSoarIOConnector(AgentConnector):
+    def __init__(self, client):
+        AgentConnector.__init__(self, client)
+        client.add_print_event_handler(self.agent_print_collector)
+        # client.execute_command("output callbacks on")
+        # client.execute_command("output console on")
+
+        self.agent_printout = ""
+
+    def on_input_phase(self, input_link):
+        pass
+
+    def on_init_soar(self):
+        self.reset()
+
+    def on_output_event(self, command_name, root_id):
+        pass
+
+
+    def agent_print_collector(self, text):
+        self.agent_printout += text+"\n"
+
+    def get_agent_output(self):
+        return self.agent_printout
+
+    def reset(self):
+        self.agent_printout = ""
+
+
+
+