Diff of /doc/source/using_pyke/index.txt [000000] .. [4dca5a] Maximize Restore

  Switch to side-by-side view

--- a
+++ b/doc/source/using_pyke/index.txt
@@ -0,0 +1,172 @@
+.. $Id$
+.. 
+.. Copyright Š 2007-2010 Bruce Frederiksen
+.. 
+.. 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.
+
+restindex
+    crumb: Using Pyke
+    page-description:
+        How your Python program calls Pyke.
+    /description
+    section-pages: , creating_engine, adding_facts, proving_goals, other_functions
+    format: rest
+    encoding: utf8
+    output-encoding: utf8
+    include: yes
+    initialheaderlevel: 2
+/restindex
+
+uservalues
+    filedate: $Id$
+/uservalues
+
+==========
+Using Pyke
+==========
+
+This describes how to call Pyke from your Python program.
+
+Getting Started
+===============
+
+.. this code is hidden and will set __file__ to the doc/examples directory.
+   >>> import os
+   >>> __file__ = \
+   ...   os.path.join(os.path.dirname(os.path.dirname(os.getcwd())),
+   ...                'examples')
+
+The simplest use of Pyke involves three steps:
+
+`Create an engine`_ object.
+
+    >>> from pyke import knowledge_engine
+
+    >>> my_engine = knowledge_engine.engine(__file__)
+
+    This step compiles the Pyke source files, if out of date, and loads the
+    `knowledge bases`_.
+
+    There are three kinds of Pyke source files:
+
+    #.  `.kfb files`_ define `fact bases`_, which are compiled into .fbc pickle
+        files.
+    #.  `.krb files`_ define `rule bases`_, which are compiled into 1 to 3 .py
+        Python source files.
+    #.  `.kqb files`_ define `question bases`_, which are compiled into .qbc
+        pickle files.
+
+    See `Creating an Inference Engine`_ to control where the compiled files
+    are written, load knowledge bases from multiple directories, distribute
+    your application without your knowledge base files, or distribute using
+    egg files.
+
+Activate `rule bases`_.
+
+    >>> my_engine.activate('bc_related')
+
+    You may activate one rule base for each `rule base category`_.  Simply
+    pass multiple arguments to ``activate``.
+
+    .. note::
+
+       Even if you only have one rule base, you must still activate it.
+
+    This is when the `forward-chaining rules`_ are run.
+
+Prove_ goal_.
+
+    >>> my_engine.prove_1_goal('bc_related.father_son(bruce, $son, ())')
+    ({'son': 'david'}, None)
+
+    The goal might be met by simply matching an already known fact_, or
+    through the use of `backward-chaining rules`_.
+
+    Then if you want to prove another goal, you can just repeat the last step.
+    In this case, the `forward-chaining rules`_ are only run once and all goals
+    operate against the same set of known facts.
+
+    >>> my_engine.prove_1_goal('bc_related.father_son(thomas, $grandson, (grand))')
+    ({'grandson': 'david'}, None)
+
+    See `Proving Goals`_ to pass different arguments into goals, compile the
+    goal statements once in advance, and to retrieve multiple answers for a
+    goal.
+
+Dynamically Asserting Facts
+===========================
+
+To dynamically assert_ facts_ within your Python program, a new step is
+added:
+
+    Create the engine object:
+
+    >>> my_engine = knowledge_engine.engine(__file__)
+
+Assert_ facts_.
+
+>>> my_engine.assert_('family2', 'son_of', ('spike_the_dog', 'david'))
+
+These facts must be asserted prior to activating the rule bases so that they
+are available to the `forward-chaining rules`_.  This example shows asserting
+case specific facts that are deleted before running the next case (as shown
+in the next section, below).  But you can also assert universal facts that
+apply to all cases.  See `Asserting New Facts`_ for more information.
+
+    After asserting your facts, activate your rule bases and prove your goal
+    as before:
+
+    >>> my_engine.activate('bc_related')
+    >>> my_engine.prove_1_goal('bc_related.father_son(bruce, $grandson, (grand))')
+    ({'grandson': 'spike_the_dog'}, None)
+
+Using Different Facts for Different Cases
+=========================================
+
+But if you want to prove goals against different sets of facts or using
+different rule bases, you need to reset_ the Pyke engine:
+
+    Only need this once:
+
+    >>> my_engine = knowledge_engine.engine(__file__)
+
+    First case, as before:
+
+    >>> my_engine.assert_('family2', 'son_of', ('spike_the_dog', 'david'))
+    >>> my_engine.activate('bc_related')
+    >>> my_engine.prove_1_goal('bc_related.father_son(bruce, $grandson, (grand))')
+    ({'grandson': 'spike_the_dog'}, None)
+
+Reset the Pyke engine.
+
+>>> my_engine.reset()
+
+This erases all of the case specific facts that you asserted in step 2, as
+well as all of the facts asserted by the `forward-chaining rules`_.
+
+It also deactivates all of the `rule bases`_, so you'll need to call
+activate again after asserting your facts.
+
+    Second case:
+
+    >>> my_engine.assert_('family2', 'son_of', ('felix_the_cat', 'david'))
+    >>> my_engine.activate('bc_related')
+    >>> my_engine.prove_1_goal('bc_related.father_son(bruce, $grandson, (grand))')
+    ({'grandson': 'felix_the_cat'}, None)
+