README.org 14.1 KB
Newer Older
Uwe Köckemann's avatar
Uwe Köckemann committed
1 2 3 4 5 6 7
#+TITLE: The AIDDL Framework

The Artificial Intelligence Domain Definition Language (AIDDL) allows to model
AI problems, data and how AI methods are connected in order to solve
problems. This allows to create complex integrated AI systems by combining
robust and well-studied components.

8 9
You can find the most recent version under [[http:www.aiddl.org][aiddl.org]].

Uwe Köckemann's avatar
Uwe Köckemann committed
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
* Overview

#+CAPTION: Overview of AIDDL components and interactions.
#+NAME:   fig:overview
[[./material/figures/overview.png]]

AIDDL files represent modules containing type definitions (e.g., defining states
or goal for planning, instance for machine learning), data (e.g., concrete state
or goal for planning), functionality definitions (define computation based on
input and output types), as well as function compositions that implemented the
actual integrated system (functionality + control flow).

The [[file:core/README.org][Core Library]] implements AIDDL support for a programming language (parser,
data structures, evaluator). The [[file:common/README.org][Common library]] is a collection of AI type
definitions and algorithms that can be used for rapid prototyping of integrated
AI systems. The [[file:example/README.org][Example Library]] is a collection of example project that
demonstrate how AIDDL is used to create integrated AI systems. Examples use
implementations from the Common Library.

* Installation & Quick Start

Below you find (links to) instructions on how to:
1) Set the two environment variables AIDDL_PATH and AIDDL_WORK
2) Install the Core and Common libraries
3) Run the examples included in this repository

We use <AIDDL-ROOT> to refer to the folder containing this README file.

** Setting AIDDL_PATH and AIDDL_WORK

Modules in AIDDL_PATH can be imported by using their module name or filename
relative to path entries. AIDDL_WORK is the default working folder and is
used by some of our examples.

The following examples show how to add the aiddl path of org.aiddl.core and
org.aiddl.common to the AIDDL_PATH. 

*** Linux

Add the following lines to the end of the ~/.profile file:

 AIDDL_PATH="<AIDDL-ROOT>/common/aiddl/:<AIDDL-ROOT>/core/aiddl/"
 AIDDL_WORK="<AIDDL-ROOT>/tmp/"
    
*** Windows

1) Navigate to: Computer -> Settings -> Advanced Settings -> Environment Variables
2) Add a new variable named AIDDL_PATH
3) Change the value of AIDDL_PATH to include the following folders:
  - <AIDDL-ROOT>/core/aiddl
  - <AIDDL-ROOT>/common/aiddl

You may have to restart applications to make sure they can use the newly set variable.
** Build & Install Core and Common Libraries

To install the Java version, follow the instructions in the following files:
- [[file:core/java/README.org][Java Core Library]]
- [[file:common/java/README.org][Java Common Library]]

** Run Examples

Follow the instructions in your example of choice:
- Example: [[file:example/learning-agent/README.org][Planning and Learning]]
- Example: [[file:example/planning-and-goal-inference/][Planning and Goal Inference]]

* AIDDL Files

An AIDDL file contains a module entry followed by any number of entries.  There
are a few entries with a special meaning (as indicated by their types) and some
expressions can be evaluated. In the following we will go though each of these
in turn.

Everything in an AIDDL file is an entry. Below we discussed a few entries with
special types (~#mod~, ~#req~, ~#nms~, ~#def~).

A regular entry is a tuple with the form:

#+BEGIN_EXAMPLE
(t n v)
#+END_EXAMPLE

Here, the type ~t~ can be either a basic type (e.g., org.aiddl.type.integer), or a
type defined as described below. The name ~n~ is the name of the entry. Names are not
allowed to contain references. The value ~v~ can be any term.

** Basic Type Hierarchy

Everything written in AIDDL is a term. This section shows the basic type
hierarchy, gives a few examples, and provides the AIDDL reference name for each
type.

|--------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------|
| Name               | Reference                         | Description                                                                                                | Examples                                                                               |
|--------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------|
| Term               | ~org.aiddl.term~                    | Every AIDDL expression is a term.                                                                          | see below                                                                              |
| Symbolic           | ~org.aiddl.term.symbolic~           | Non-numerical constants.                                                                                   | ~a~ ~e1~ ~+~ ~#integer~                                                                        |
| Boolean            | ~org.aiddl.term.symbolic.boolean~   | Boolean constants                                                                                          | ~true~  ~false~                                                                            |
| Variable           | ~org.aiddl.term.variable~           | Named variables beginning with ~?~ or anonymous variables ~_~                                                  | ~?x ~?e1 ~_~                                                                               |
| String             | ~org.aiddl.term.string~             | Any string of characters in quotes.                                                                        | ~"a"~ ~"abc"~ ~"1 2 3"~                                                                      |
| Numerical          | ~org.aiddl.term.numerical~          | Different types of numerical values. All numerical types can be compared and used in the same computation. | see below                                                                              |
| Integer            | ~org.aiddl.term.numerical.integer~  | Positive or negative integers.                                                                             | ~0~ ~-3~ ~11~                                                                                |
| Rational           | ~org.aiddl.term.numerical.rational~ | Positive or negative rational numbers.                                                                     | ~0/1~ ~-1/3~ ~110/13~                                                                        |
| Real               | ~org.aiddl.term.numerical.real~     | Positive or negative real numbers.                                                                         | ~0.0~ ~-1.3~ ~1.1~                                                                           |
| Infinity           | ~org.aiddl.term.numerical.inf~      | Positive or negative infinity.                                                                             | ~INF~ ~+INF~ ~-INF~                                                                          |
| Collection         | ~org.aiddl.term.collection~         | Collections of terms.                                                                                      | see below                                                                              |
| Set                | ~org.aiddl.term.collection.set~     | A set of terms. Cannot be matched to other terms.                                                          | ~{}~ ~{e1 e2 e3}~ ~{1 1 2}~                                                                  |
| List               | ~org.aiddl.term.collection.list~    | A list of terms.                                                                                           | ~[]~ ~[e1 e2 e3]~ ~[1 1 2]~                                                                  |
| Tuple              | ~org.aiddl.term.tuple~              | A tuple of terms. Unlike lists, we assume tuples will not be extended.                                     | ~() ~(e1 e2 e3)~ ~(1 1 2)~                                                                  |
| Reference          | ~org.aiddl.term.reference~          | A reference to an entry in a specific module.                                                              | ~e@m~ references entry named ~e~ in module ~m~                                               |
|                    |                                   |                                                                                                            | ~$e~ references entry named ~e~ in module where the reference appears (aka self reference) |
| Function Reference | ~org.aiddl.term.fun-ref~            | Reference to a function. Allows using functions as data.                                                   | ~^org.aiddl.eval.add~ ~^(lambda (?x ?y) (* ?x ?y))~                                        |
| Key-Value Pair     | ~org.aiddl.term.key-value~          | A key and a value term.                                                                                    | ~x:10~ symbolic key ~x~ with integer value ~10~                                              |
|                    |                                   |                                                                                                            | ~?x:?y~ variable key ~?x~ with variable value ~?y~                                           |
|                    |                                   |                                                                                                            | ~x:y:z~ symbolic key ~x~ with key value pair ~y:z~ as a value                                |

** Grammar
The following grammar defines the AIDDL file format.

 #+BEGIN_EXAMPLE
<AiddlFile>  :: <Module> (<Entry>)*
<Module>     :: "(#mod" <Symbolic> <Symolic> ")"
<Entry>      :: "("<Term> <Term> <Term>")"
<Term>       :: <Numerical> | <Collection> | <Tuple> | <Symbolic> | <String>
              | <Variable>  | <Reference> | <KeyValue>
<Numerical>  :: <Integer> | <Rational> | <Real> | <Infinity>
<Collection> :: <List> | <Set>
<List>       ::  "[" <Term>* "]"
<Set>        ::  "{" <Term>* "}"
<Tuple>      ::  "(" <Term>* ")"
<Reference>  :: <Term>"@"<Term> | "$"<Term>
<FunRef>     :: "^"<Term>
<KeyValue>   :: <Term>":"<Term>
<Symbolic>   :: (("a"-"z"|"A"-"Z"|"#")("a"-"z"|"A"-"Z"|"0"-"9"|"_"|"."|"-"|"'")*)
           |"+"|"-"|"/"|"*"|"&"|"|"|"!"|"="|"<"|">"|"=>"|"<=>"|"^"|"!="|"<="|">="
<String>        :: "\"" [~\"]* "\""                     
<Variable>      :: <NamedVariable> | "_"
<NamedVariable> :: ?(("a"-"z"|"A"-"Z")("a"-"z"|"A"-"Z"|"0"-"9"|"_"|"."|"-"|"'")*)
<Integer> :: ["-"]("0"|"1"-"9")("0"-"9"]*
<Rational> :: ["-"]("0"|"1"-"9")("0"-"9")* "/" ("1"-"9"("0"-"9")*)
<Real> :: ["-"] ("0"|"1"-"9")("0"-"9")* "." ("0"-"9")+
<Infinity> :: ["+"|"-"]"INF"
 #+END_EXAMPLE

** Modules (#mod)
Modules are used to distinguish  sets of entries based on their purpose. 
Entry names may be reused across different modules but must be unique 
in each module. Each AIDDL file is associated to a single module which is 
indicated by its module entry. The module entry is always the first entry
in an AIDDL file. The entry

#+BEGIN_EXAMPLE
(#mod self org.aiddl.module)
#+END_EXAMPLE

has type ~#mod~, name ~self~, and value ~org.aiddl.module~.  Here, the name
refers to the way in which the module refers to itself (usually we use the
symbolic term ~self~). The value is the way in which other modules refer to this
module (i.e. the global name of the module).

** Requirements (#req)
Requirements are used to allow AIDDL files to make local references to 
other modules. 
A requirement is an entry of type ~#req~:

#+BEGIN_EXAMPLE
(#req A "required.aiddl")
#+END_EXAMPLE

The name ~A~ of a requirement creates a local alias for the module found in the
required file. This alias can then be used in references instead of the full
name. Given the requirement above, the term ~e@A~ refers to an entry named ~e~
in the module stated in file ~required.aiddl~.

** Name Spaces (#nms)

Name spaces allow to avoid extensive usage of references. A name space is of
type ~#nms~.  Applying a name space will substitute every occurrence of a name
with its value for each entry in the name space module. 

A name space is an entry of type ~#nms~:

#+BEGIN_EXAMPLE
(#nms A "namespace.aiddl")
#+END_EXAMPLE

Including a name space will substitute all entries in the current module with
the values of the entries found in ~namespace.aiddl~.

Example:

Assuming ~namespace.aiddl~ contains the entry

#+BEGIN_EXAMPLE
(org.aiddl.term.symbolic + org.aiddl.eval.add)
#+END_EXAMPLE

and the current module has the entry

#+BEGIN_EXAMPLE
(org.aiddl.term.list L [+])
#+END_EXAMPLE

it will be replaced by

#+BEGIN_EXAMPLE
(org.aiddl.term.list L [org.aiddl.eval.add])
#+END_EXAMPLE

when the name space is applied.

Standard name spaces commonly used in our AIDDL examples are:

- [[file:definitions/eval.aiddl][eval.aiddl]] :: short names for predefined functions
- [[file:definitions/eval-ht.aiddl][eval-ht.aiddl]] :: same as eval.aiddl but uses names prefaced by a hashtag
- [[file:definitions/type.aiddl][type.aiddl]] :: short names for basic types
- [[file:definitions/type-ht.aiddl][type-ht.aiddl]] :: same as types.aiddl but uses names prefaced by a hashtag
 
** Definitions (#def)

A definition is an entry of type ~#def~. The name of a definition entry is
the name of the type it defines and its value is a function that can be evaluated to
determine if a term is an instance of the type. Functions may refer to their
argument by using the special term ~#self~.

The following type definition is satisfied by all integers between 0 and 10 (for
readability we assume name spaces ~eval.aiddl~ and ~type.aiddl~ are used):

#+BEGIN_EXAMPLE
(#def SmallInteger 
  (and
    (type #self integer)
    (>= #self 0)
    (<= #self 10)))
#+END_EXAMPLE
    
* Support
Contact Uwe Köckemann (uwe.kockemann_at_oru.se) in case of questions,
suggestions, feature requests, bug reports.
* Acknowledgments
This work was supported by European Union H2020 Project [[https:www.ai4eu.eu][AI4EU]] under grant
agreement ID 825619 as part of Task 7.4 on Integrative AI.