Automaton

Introduction
============

This program was built to aid in automating tasks and enabling a "smart home".
It began as a single python file that would emulate the effects of a smart phone
through text messages and it grew as I wanted an easy way to add both scripts
and frontends to interface with those scripts.

Links
=====
http://www.youtube.com/user/AutomatonServer

Requirements
============

This application requires CherryPy, nltk, and numpy. These can be installed
through the pip with the base_requirements.pip file, or they may be installed
individually through your favorite package manager.

Python: The server is written in Python. Originally compiled with Python 2.6.5,
but I have since migrated to Python 2.7 and there are some scripts that require
2.7 functionality.



Installation
============

Install the requirements, then execute `python setup.py install` to install
the libraries and two scripts: AutomatonServer and automaton.py.

AutomatonServer is the Python script that starts the server; provide a server
type (eg. cherry) as an argument to start a specific server.

automaton.py is a command line client for Automaton. Run it while the server
is running to communicate with the server. The conversation may be ended with
Control-C.

Running
=======

Find the __init__.py script wherever it was installed (the output of the install
command should list the directory) and open it. Add/remove any command scripts
that are listed in the root of the python module (leaving it as-is will include
most of the scripts, but WARNING - as it's a networked application, make sure
all scripts that are enabled come from a trusted source). If any command scripts
have configuration files (labeled cmd_COMMAND.conf.default in
Automaton/settings), create copies of them and remove the ".default" extension
(so it reads cmd_COMMAND.conf) and edit them with the required information.

Run "AutomatonServer cherry" from the terminal/command line to start the
CherryPy server. If everything is set up correctly, the program should
eventually print "Starting the server...". If a module fails to load for any
reason, it will display a log message with a short description of the error.

Pick a client application from the source directory (such as sampleclient.py
for testing purposes). Run it with "python sampleclient.py" and it should
display a number of messages back to you (as long as the 'echo' script is
loaded from __init__.py)..

Creating A New Script
=====================

Take a look at automaton/plugins/sampleplugin.py for an example of a simple
plugin. To be accessible from the rest of Automaton, a plugin should do a few
things:

* Create a function for each service you want to expose. It can take any
  keyword arguments that you wish, they will be mapped with the grammar.
  It is recommended to use the **kwargs construct just in case the user does
  not include every necessary keyword argument (options for handling that
  situation are described below).
* Register all services using `self.registrar.register_service`.
  * svc_name is the name others will use to indicate your service (eg. 'play'
    for services that play music or movies)
  * svc_func is the method to call to execute the service.
  * grammar defines how the input string is mapped to the necessary arguments.

    The keys to the grammar dict (or other mapping) should be keyword argument
    names and the values are lists of strings containing words in the input
    string to search for. One key is allowed to have an empty list; it will be
    filled with the content between the service's name and the next argument.
    For example, using the grammar `{"what": [], "location": ["near", "at"]}`
    for the service `"find"` will map the input query `find something near here`
    to the keyword arguments `{'what': 'something', 'location': 'here'}`
  * usage is a string containing help text for the service.
  * namespace is a string that, when combined with the service name, uniquely
    identifies your service. That way, multiple plugins can register for the
    service "play" and the correct service will be chosen by comparing the
    query string to values in the grammar.
* If you want to support the option to take _partial_ queries, "conversation"
  support is also an option. If your service function returns a generator
  instead of normal string output, Automaton will cache the generator and
  rather than parsing the next query, it will pass it directly as a value
  in a dictionary to the next "yield" statement in your generator. When the
  generator exits, queries will once again be passed to the interpreter. For
  example, if your service provides directions and the client only provides
  a destination in the query, your service can prompt the user for a starting
  location and fill in that data at a later time.
* Some datasets are provided in automaton.lib.data, such as language code,
  U.S. state, and country abbreviations. They may be useful while implementing
  certain services.