inkling guide structure changes and examples page (rouge-ruby#34)

* inkling guide structure changes and examples page

* add find-the-center-examaple

* updating simulator after linting

* Keen's comments

* update simulator

* python 2.7 support

* fix linting error

source/ai-engine-guide.html.md

@@ -0,0 +1,16 @@
+---
+title: AI Engine Guide - Bonsai
+
+language_tabs:
+
+toc_footers:
+  - <a href='https://bons.ai/sign-up'>Sign Up for our Private Beta!</a>
+  - <a href='.'>Return home</a>
+  - <a href='https://github.com/lord/slate'>Documentation Powered by Slate</a>
+
+includes:
+
+- under-the-hood.html.md
+
+search: true
+---

source/examples.html.md

@@ -0,0 +1,18 @@
+---
+title: Examples - Bonsai
+
+language_tabs:
+
+toc_footers:
+  - <a href='https://bons.ai/sign-up'>Sign Up for our Private Beta!</a>
+  - <a href='.'>Return home</a>
+  - <a href='https://github.com/lord/slate'>Documentation Powered by Slate</a>
+
+includes:
+
+- examples/cart-pole.html.md
+- examples/find-the-center.html.md
+- examples/mountain-car.html.md
+
+search: true
+---

source/includes/inkling-guide/_4-under-the-hood.html.md → source/includes/_under-the-hood.html.md

@@ -1,8 +1,4 @@
-## Under the Hood
-
-This section describes some of how Bonsai AI's engine works under the hood using Inkling to teach BRAINs.
-
-###### Major components
+# Major Components
 
 Bonsai's AI Engine has several major components.
 
@@ -31,11 +27,7 @@ The transformer carries out any streaming data transformations that do not requi
 
 After an algorithm is trained, it is hosted in a 'prediction mode'. This mode holds a neural network for use as an HTTP API endpoint.  The programmer can then send input data to the predictor and get back a prediction.
 
-## Versioning
-
-The Bonsai AI Engine keeps versions of BRAINs. Each load operation and training session generates a new version. This way you can compare the latest version of a BRAIN with previous versions.
-
-###### The Architect
+# The Architect
 
 The architect component is responsible for creating and optimizing learning topologies (e.g. neural networks) based on mental models. In this section, we outline techniques used by the architect to determine reasonable architectures.
 
@@ -59,14 +51,18 @@ Meta learning is an advanced technique used by the architect.  It is, as the nam
 
 For advanced users, low level details of a learning topology can be explicitly specified in part or in completely.  The architect treats any such pinning of parameters as an override on its default behavior.  In this way, specific algorithms can be provided, or a generated model can be pinned for manual refinement.
 
-###### The Instructor
+# The Instructor
 
 The instructor component is responsible for carrying out the training plan codified in the pedagogy.  In this section, we outline techniques used by the instructor.
 
 ### The Execution Plan
 
 When starting a training operation, the instructor first generates an execution plan. It uses this ordering when teaching the concepts, and for each concept which lessons it intends to teach in what order. While the execution plan is executing, the instructor may jump back and forth between concepts and lessons to optimize training. The major techniques used to determine when to switch between lessons and concepts for training are reinforcement learning and adaptive learning.
 
-###### The IDK and learning engines
+# The IDK and Learning Engines
 
 The learning engine encodes the underlying detail needed to work with a particular artificial intelligence or machine learning algorithm. The BRAIN server provides many standard learning engines such as those used for deep learning. However, learning algorithm authors can provide their own backends if so desired. By architecting the BRAIN server in this way, Inkling code gains another level of abstraction from a particular approach. If a new learning algorithm is created that has superior performance to existing algorithms, all that need be added is a new backend. The architect will immediately start using the backend to build systems, and existing Inkling programs can be recompiled without modification to take advantage of the improved algorithms.
+
+# Versioning
+
+The Bonsai AI Engine keeps versions of BRAINs. Each load operation and training session generates a new version. This way you can compare the latest version of a BRAIN with previous versions.

source/includes/inkling-guide/_31-cart-pole.html.md → source/includes/examples/_cart-pole.html.md

@@ -1,14 +1,12 @@
-## Example: Cart Pole
+# Cart Pole Example
 
-In this example, we'll walk you through the various statements that are part of the cart pole Inkling file. Each statement is followed by an explanation of the statement.
-
-###### What is Cart Pole?
+In this example, we'll walk you through the various statements that are part of the Cart Pole Inkling file. Each statement is followed by an explanation of the statement.
 
 Cart Pole is a classic control problem. [OpenAI Gym][1] describes it as:
 
 _A pole is attached by an un-actuated joint to a cart, which moves along a frictionless track. The system is controlled by applying a force of +1 or -1 to the cart. The pendulum starts upright, and the goal is to prevent it from falling over. A reward of +1 is provided for every timestep that the pole remains upright. The episode ends when the pole is more than 15 degrees from vertical, or the cart moves more than 2.4 units from the center._
 
-###### Schema: `GameState`, `Action`, and `CartPoleConfig`
+## Schema: `GameState`, `Action`, and `CartPoleConfig`
 
 ```inkling
 schema GameState
@@ -39,7 +37,7 @@ end
 
  The schema `CartPoleConfig` names three records — `episode_length`, `num_episodes`, and `deque_size` — and assigns each of them a type.
 
-###### Concept: `balance`
+## Concept: `balance`
 
 ```inkling
 concept balance
@@ -52,7 +50,7 @@ end
 
 The concept is named `balance`, and it takes input from the simulator. That input is the records in the schema `GameState`. The balance concept outputs the move the AI should make in the simulator. This output is the record in the `Action` schema.
 
-###### Curriculum: `balance_curriculum`
+## Curriculum: `balance_curriculum`
 
 ```inkling
 simulator cartpole_simulator(CartPoleConfig)

source/includes/examples/_find-the-center.html.md

@@ -0,0 +1,178 @@
+# Find the Center Example
+
+In this example, we'll walk you through the various statements that are part of the *Find the Center* game, including the simulator file and the Inkling file. This is a very basic example of Inkling and how to connect to a simulator.
+
+*Find the Center* is a simple game where the AI seeks the average value between two numbers. In this game, the AI begins at a random value of 0, 1, or 2. The AI then can move to a lower number by outputing -1, a higher number by outputing +1, or staying on the same number by outputing 0. The goal of *Find the Center* is to remain in the center of 0 and 2 (the number 1).
+
+## Inkling File
+
+###### Schema
+
+```inkling
+schema GameState
+    Int32 value
+end
+```
+
+The `GameState` schema has one field, `value`, with type `Int32`.
+
+```inkling
+schema PlayerMove
+    Int32{-1, 0, 1} delta
+end
+```
+
+The `PlayerMove` schema has one field, `delta`, with type `Int32`. The `Int32` type is constrained to three possible values: -1, 0, and 1.
+
+```inkling
+schema SimConfig
+    Int32 dummy
+end
+```
+
+The `SimConfig` schema has one field, `dummy`, because there is no configuration needed in this particular example.
+
+###### Concept
+
+```inkling
+concept find_the_center
+    is classifier
+    predicts (PlayerMove)
+    follows input(GameState)
+    feeds output
+end
+```
+
+This concept is named `find_the_center`. `find_the_center` expects input about the state of the game (defined by the `GameState` schema) and replies with output defined by the `PlayerMove` schema. This is the AI's next move in the simulation.
+
+###### Simulator
+
+```inkling
+simulator find_the_center_sim(SimConfig)
+    action (PlayerMove)
+    state (GameState)
+end
+```
+
+The `simulator` is called `find_the_center_sim` (shown in #simulator-file) and takes the schema input of `SimConfig` (even though it isn't configuring anything, it's required by the simulator). The `find_the_center` concept will be trained using the `find_the_center_sim` simulator. To define the training relationship between the simulator and the concept we must begin by defining the simulator. `find_the_center_sim` expects an action defined in the `PlayerMove` schema as input and replies with a state defined in the `GameState` schema as output.
+
+###### Curriculum
+
+```inkling
+curriculum find_the_center_curriculum
+    train find_the_center
+    with simulator find_the_center_sim
+    objective time_at_goal
+        lesson seek_center
+            configure
+                constrain dummy with Int32{-1}
+            until
+                maximize time_at_goal
+end
+```
+
+The curriculum is named `find_the_center_curriculum`, and it trains the `find_the_center` concept using the `find_the_center_sim`. This curriculum contains one lesson, called `seek_center`. It configures the simulation, by setting a number of constraints for the state of the simulator.
+
+The lesson trains until the AI has maximized the objective `time_at_goal`.
+
+
+## Simulator File
+
+```python
+from __future__ import print_function
+import bonsai
+import sys
+from bonsai.simulator import SimState
+from random import randint
+
+""" If you would like to debug your code add this back in.
+def debug(*args):
+    print(*args, file=sys.stderr)
+"""
+
+
+class BasicSimulator(bonsai.Simulator):
+    """ A basic simulator class that takes in a move from the inkling file,
+    and returns the state as a result of that move.
+    """
+
+    min = 0
+    max = 2
+    goal = 1
+
+    def __init__(self):
+        super(BasicSimulator, self).__init__()
+        self.goal_count = 0
+        self.value = randint(self.min, self.max)
+        self.old_value = self.min
+
+    def get_terminal(self):
+        """ Restarts the simulation if the AI moved out of bounds.
+        """
+        if (self.value < self.min or self.value > self.max):
+            # (self.value == self.goal and self.old_value == self.goal)):
+
+            # debug("terminal")
+            self.reset()
+            return True
+        else:
+            return False
+
+    def start(self):
+        """ Start the episode by initializing value to a random number
+        between the min and max.
+        """
+        # debug("start")
+        self.goal_count = 0
+        self.old_value = self.min
+        self.value = randint(self.min, self.max)
+
+    def stop(self):
+        """ Stop is called after a training session is complete.
+        This simple game requires no cleanup after training.
+        """
+        # debug("stop")
+        pass
+
+    def reset(self):
+        """ Reset is called to reset simulator state before the next training session.
+        """
+        # debug("reset")
+        self.goal_count = 0
+        self.old_value = self.min
+        self.value = randint(self.min, self.max)
+
+    def advance(self, actions):
+        """ Function to make a move based on output from the BRAIN as
+        defined in the Inkling file.
+        """
+        # debug("advance", actions["delta"])
+        self.value += actions["delta"]
+        if self.value == self.goal:
+            self.goal_count += 1
+
+    def get_state(self):
+        """ Gets the state of the simulator, whether it be a valid value or
+        terminal ("game over") state.
+        """
+        # debug("get_state")
+        # debug("state", self.value)
+        self.old_value = self.value
+        return SimState(state={"value": self.value},
+                        is_terminal=self.get_terminal())
+
+    def time_at_goal(self):
+        """ Function to return how long the simulation has maintained the goal.
+        """
+        return self.goal_count
+
+if __name__ == "__main__":
+    base_args = bonsai.parse_base_arguments()
+    sim = BasicSimulator()
+    bonsai.run_with_url('find_the_center_sim', sim,
+                        base_args.brain_url, base_args.access_key)
+```
+
+This is a Basic simulator for learning the simulator interface. In this case it is used to find the center between two numbers, 0 and 2. The goal, as outlined in the Inkling file, is to reach 1. The moves that the simulator is able to make are sent from the Inkling file to the simulator and the state of the simulator is sent back to Inkling.
+
+[1]: https://gym.openai.com/envs/MountainCar-v0

source/includes/inkling-guide/_32-mountain-car-example.html.md → source/includes/examples/_mountain-car.html.md

@@ -1,12 +1,12 @@
-## Example: Mountain Car
+# Mountain Car Example
 
-We've used pieces of code from this example in several places, but here we'll walk you through all the various statements that are part of the mountain car Inkling file. Each statement is followed by an explanation of the statement.
+We've used pieces of code from this example in several places, but here we'll walk you through all the various statements that are part of the Mountain Car Inkling file. Each statement is followed by an explanation of the statement.
 
 Mountain car is a classic control problem. [OpenAI Gym][1] describes it as:
 
 _A car is on a one-dimensional track, positioned between two "mountains". The goal is to drive up the mountain on the right; however, the car's engine is not strong enough to scale the mountain in a single pass. Therefore, the only way to succeed is to drive back and forth to build up momentum._
 
-###### Schema: `GameState`, `Action`, `MountainCarConfig`
+## Schema: `GameState`, `Action`, `MountainCarConfig`
 
 ```inkling
 schema GameState
@@ -35,7 +35,7 @@ end
 
 The `MountainCarConfig` schema names three records — `episode_length`, `num_episodes`, and `deque_size` — and assigns types to them.
 
-###### Concept `high_score`
+## Concept `high_score`
 
 ```inkling
 concept high_score
@@ -48,7 +48,7 @@ end
 
 The concept is named `high_score`, and it takes input from the simulator about the state of the game (`GameState` schema). It outputs to the `Action` schema. This is the AI's next move in the game.
 
-###### Curriculum: `high_score_curriculum`
+## Curriculum: `high_score_curriculum`
 
 ```inkling
 simulator mountaincar_simulator(MountainCarConfig)

source/includes/getting-started/_next-steps.html.md

@@ -17,7 +17,7 @@ And we have these other resources that will enable you to maximize your AI devel
 * [Bonsai Blog][4]
 * [Bonsai Forums][5]
 
-[1]: ./inkling.html
+[1]: ./inkling-guide.html
 [2]: ./cli-reference.html
 [3]: ./api-reference.html
 [4]: https://bons.ai/blog

source/includes/getting-started/_overview-and-faq.html.md

@@ -106,9 +106,9 @@ Your BRAIN Dashboard contains all of your BRAINs. The BRAIN Dashboard is also wh
 There is a BRAIN Details page for each of your BRAINs. Each page shows that BRAIN's status, training graph, and commands you can use in the CLI specifically for this BRAIN.
 
 [1]: ../images/bonsai_infographic_1024.png
-[2]: ./inkling.html
+[2]: ./inkling-guide.html
 [3]: ./cli-reference.html
 [4]: https://beta.bons.ai
 [5]: http://yann.lecun.com/exdb/mnist/
 [6]: #install-prerequisites
-[7]: ./inkling.html#example-cart-pole
+[7]: ./examples.html