Merge pull request #119 from fetchai/katharine/docs

Updates to TAC, AEA, adding gym example docs

docs/architecture.md

@@ -2,25 +2,7 @@
 !!!	Note	
 	Work in progress.
 
-## File structure
-
-An agent is structured in a directory with a configuration file, a directory with skills, a directory with protocols, a directory with connections and a main logic file that is used when running aea run.
 
-agentName/                                     | The root of the agent
----------------------------------------------- | -----------------------------------------------------------------
-agent.yml                                      | YAML configuration of the agent
-connections/                                   | Directory containing all the supported connections
-  connection1/                                 | Connection 1
-  ...                                          | ...
-  connectionN/                                 | Connection N
-protocols/                                     | Directory containing all supported protocols
-  protocol1/                                   | Protocol 1
-  ...                                          | ...
-  protocolK/                                   | Protocol K
-skills/                                        | Directory containing all the skill components
-  skill1/                                      | Skill 1
-  ...                                          | ...
-  skillN/                                      | Skill L
 
 ## Core components
 
@@ -47,4 +29,25 @@ A connection allows the AEA to connect to an external service which has a Python
 A skill can encapsulate any code and ideally delivers economic value to the AEA. Each skill has at most a single Handler and potentially multiple Behaviours and Tasks. The Handler is responsible for dealing with messages of the protocol type for which this skill is registered, as such it encapsulates `reactions`. A Behaviour encapsulates `actions`, that is sequences of interactions with other agents initiated by the AEA. Finally, a Task encapsulates background work which is internal to the AEA.
 
 
+## File structure
+
+An agent is structured in a directory with a configuration file, a directory with skills, a directory with protocols, a directory with connections and a main logic file that is used when running aea run.
+
+``` bash
+agentName/
+  agent.yml       YAML configuration of the agent
+  connections/    Directory containing all the supported connections
+    connection1/  First connection
+    ...           ...
+    connectionN/  nth connection
+  protocols/      Directory containing all supported protocols
+    protocol1/    First protocol
+    ...           ...
+    protocolK/    kth protocol 
+  skills/         Directory containing all the skill components
+    skill1/       First skill
+    ...           ...
+    skillN/       nth skill
+```
+
 <br />

docs/cli_overview.md

@@ -1,4 +1,4 @@
-# Commands
+# CLI commands
 
 
 Command  | Description

docs/css/my-styles.css

@@ -0,0 +1,27 @@
+pre {
+  background-color: #f8f8f7;
+}
+
+code {
+  background-color: #0083fb;
+}
+
+/* this doesn't work now
+.md-nav__link {
+  text-transform: uppercase;
+  color: #0083fb;
+}
+*/
+
+/* Katharine's css additions */
+.md-header, .md-tabs, .md-footer-meta, .md-footer-nav, .md-footer-nav__inner {
+	background-color:  #172b6e; 
+}
+
+.md-nav__title {
+	color:  #172b6e;
+}
+
+.md-icon {
+	./assets/images/favicon.ico
+}

docs/gym-plugin.md

@@ -0,0 +1,58 @@
+The `gym_ex` example demonstrates to Reinforcement Learning developers the AEA framework's flexibility.
+
+There is no immediate use case for this example as you can train an RL agent without the AEA proxy layer just fine (and faster). 
+
+However, the example decouples the RL agent from the `gym.Env` allowing them to run in separate environments, potentially owned by different entities.
+
+
+## Quick start
+
+### Dependencies
+
+``` bash
+pip install numpy gym
+```
+
+### Files
+
+You will have already downloaded the `examples` directory during the AEA <a href="../quickstart" target=_blank>quick start demo</a>.
+
+``` bash
+cd examples/gym_ex
+```
+
+### Run the example
+
+``` bash
+python train.py
+```
+
+Notice the usual RL setup, i.e. the fit method of the RL agent has the typical signature and a familiar implementation. 
+
+Note how `train.py` demonstrates how easy it is to use an AEA agent as a proxy layer between an OpenAI `gym.Env` and a standard RL agent.
+
+It is just one line of code!
+
+``` python
+from gyms.env import BanditNArmedRandom
+from proxy.env import ProxyEnv
+from rl.agent import RLAgent
+
+
+if __name__ == "__main__":
+    NB_GOODS = 10
+    NB_PRICES_PER_GOOD = 100
+    NB_STEPS = 4000
+
+    # Use any gym.Env compatible environment:
+    gym_env = BanditNArmedRandom(nb_bandits=NB_GOODS, nb_prices_per_bandit=NB_PRICES_PER_GOOD)
+
+    # Pass the gym environment to a proxy environment:
+    proxy_env = ProxyEnv(gym_env)
+
+    # Use any RL agent compatible with the gym environment and call the fit method:
+    rl_agent = RLAgent(nb_goods=NB_GOODS)
+    rl_agent.fit(env=proxy_env, nb_steps=NB_STEPS)
+```
+
+<br />

docs/gym-skill.md

@@ -0,0 +1,85 @@
+The AEA gym skill demonstrates how a custom Reinforcement Learning agent may be embedded into an Autonomous Economic Agent.
+
+
+## Demo instructions
+
+Follow the Preliminaries and Installation instructions <a href="../quickstart" target=_blank>here</a>.
+
+Create and launch a virtual environment.
+
+``` bash
+pipenv --python 3.7 && pipenv shell
+```
+
+Install the gym library.
+
+``` bash
+pip install gym
+```
+
+Then, download the examples and channels directory.
+``` bash
+svn export https://github.com/fetchai/agents-aea.git/trunk/examples
+```
+
+
+
+
+### Create the agent
+In the root directory, create the gym agent.
+``` bash
+aea create my_gym_agent
+```
+
+
+### Add the gym skill 
+``` bash
+cd my_gym_agent
+aea add skill gym 
+```
+
+
+### Copy the gym environment to the agent directory
+``` bash
+mkdir gyms
+cp -a ../examples/gym_ex/gyms/. gyms/
+```
+
+
+### Add a gym connection
+``` bash
+aea add connection gym
+```
+
+
+### Update the connection config
+``` bash
+nano connections/gym/connection.yaml
+env: gyms.env.BanditNArmedRandom
+```
+
+
+
+### Run the agent with the gym connection
+
+``` bash
+aea run --connection gym
+```
+
+<!--
+You will see...
+
+<center>![AEA Visdom UI](assets/***.png)</center>
+-->
+
+
+### Delete the agent
+
+When you're done, you can delete the agent.
+
+``` bash
+aea delete my_first_agent
+```
+
+
+<br/>

docs/index.md

@@ -1,17 +1,36 @@
 The AEA is a framework for autonomous economic agent (AEA) development. It gives developers a quick and efficient way to build autonomous economic agents. 
 
-The framework is super modular, easily extensible, and highly composable. 
+The framework is super modular, easily extensible, and highly composable. It is ideal for Reinforcement Learning scenarios. 
 
-An autonomous economic agent (AEA) is an intelligent agent whose goal is to generate economic value for its owner.
 
-AEAs achieve their goals with the help of the OEF and the Fetch.AI Ledger. Third party systems, such as Ethereum, may also allow AEA integration.
+## Our vision
+
+Fetch.AI intends the AEA framework to have two focused commercial roles.
+
+### Open source company
+
+We want to build infrastructure with which external parties build their own solutions.
+
+### Platform for start ups
+
+By operating as a platform for start ups, we hope to solve the chicken-or-egg problem through incentive schemes.
+
+
+
+## Agents
+
+An autonomous economic agent (AEA) is an intelligent agent whose goal is to generate economic value for its owner. Their super powers lie in their ability to autonomously acquire new skills.
+
+AEAs achieve their goals with the help of the OEF and the Fetch.AI Ledger. 
+
+Third party systems, such as Ethereum, may also allow AEA integration.
+
 
-Their super power lies in the ability to autonomously acquire new skills.
 
 !!!	Note
 	Work in progress.
 
 
-
+<br />
 
 

docs/integration.md

@@ -0,0 +1,22 @@
+In this section, we show you how to integrate the AEA with third party ledgers.
+
+
+## Fetch.AI Ledger
+
+!!!	Note
+	Coming soon.
+
+
+## Ethereum
+
+!!!	Note
+	Coming soon.
+
+
+## Etc.
+
+!!!	Note
+	Coming soon.
+
+
+<br />

docs/protocol.md

@@ -0,0 +1,8 @@
+## Envelope
+
+!!!	Todo
+
+
+## Sending stuff around
+
+!!!	Todo