develop to main (releasing new docs structure)

DEVELOPING.md

@@ -38,6 +38,10 @@
 
    This will create a new virtual environment using poetry with the project and all the development dependencies installed.
 
+   > We use <a href="https://python-poetry.org" target="_blank">poetry</a> to manage dependencies. All python specific dependencies are specified in `pyproject.toml` and installed with the framework. 
+   > 
+   > You can have more control on the installed dependencies by leveraging poetry's features.
+
 3. ``` shell
    poetry shell
    ```

docs/aeas.md

@@ -0,0 +1,31 @@
+# Autonomous Economic Agents (AEAs)
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/xpJA4IT5X88" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+## What is an AEA?
+
+!!! info "Definition"
+    An Autonomous Economic Agent (AEA) is an intelligent agent that acts on its owner's behalf, with limited or no interference, and whose goal is to generate economic value for its owner.
+
+Let's break down the term **Autonomous Economic Agent (AEA)**: 
+
+* **Agent**: An AEA is first and foremost an _agent_, representing an individual, organisation or object (a.k.a. its "owner") in the digital world. An AEA looks after its owner's interests and has their preferences in mind when acting on their behalf.
+* **Autonomous**: AEAs operate independently of constant input from their owners and act autonomously to achieve their goals.
+* **Economic**: AEAs have a narrow and specific focus: creating economic value for their owner.
+
+Some of the other characteristics AEAs typically have:
+
+* **Proactive**: AEAs are proactive; they take the initiative and perform actions that take them closer to their goals. 
+* **Reactive**: AEAs are also reactive; they are aware of the environment they are in, perceive changes in the environment, and react to these changes in accordance to their goals.
+* **Self-interested**: An AEA primarily looks after its own interests (which is aligned with those of its owner) and not necessarily the interests of other agents or the larger system.
+
+### What is NOT an AEA?
+
+* **Any agent**: AEAs are NOT meant to address _any_ needs their owners might have. They have a clear and well-defined focus, which is generating economic value for their owner and this is manifested in a variety of different ways in their design.
+* **Digital twins**: An AEA is NOT it's owner's twin in the digital world; i.e. mirroring their preferences, values, and priorities. An AEA can be given whatever preference, value, and priority its owner wants them to have.
+* **APIs or Sensors**: These do NOT have any agency, nor proactiveness. They just "sit there" and respond to requests or changes in the environment.
+* **Smart contracts**: Similar to APIs and sensors, smart contracts do NOT display any proactiveness; they are purely reactive to external requests (in their case, contract calls and transactions).
+* An agent with **Artificial General Intelligence (AGI)**: AEAs have a well-defined, narrow, and goal directed focus that involves some economic gain. 
+
+!!! info "Agents and AEAs"
+    In the rest of the documentation, unless specified, we use the terms **AEA** and **Agent** interchangeably to mean AEA as defined above description.

docs/application.md

@@ -0,0 +1,46 @@
+# Application Areas
+
+## Environments
+
+AEAs are most suited for environments which are:
+
+- **Decentralized**: there isn't a central authority that controls, manages, or makes decisions.
+- **Multi-Stakeholder**: the domain, problem, or solutions involve multiple distinct stakeholders.
+- **Peer-to-Peer**: interactions are (or could be made) direct and peer-to-peer.
+- **Complex, Incomplete, and Uncertain**: to the point that off-loading tasks to computational entities becomes valuable.
+
+## Applications
+
+We identify a number of application areas for AEA-based solutions. This list is by no means comprehensive. In fact, we are most excited about applications which we have not thought of before.
+
+**Automation**
+
+:   AEAs can automate well-defined processes in different domains, such as supply chain, mobility, finance, ...
+
+**Micro-transactions**
+
+:   AEAs make it economically viable to execute trade involving small values. An example is use-cases with many small sellers (e.g. of data) on the supply side.
+
+**Wallet**
+
+:   AEAs can simplify interactions with blockchains. By acting as "smart wallets", they can hide away the majority of the complexities involved in using blockchains for end users.
+
+**IoT**
+
+:   Agents representing objects in the IoT (Internet of Things) space. For example, AEAs paired with hardware devices such as drones, laptops, heat sensors, etc., providing control and receiving data from the device. An example is a <a href="../thermometer-skills"> thermometer agent</a>.
+
+**Web 2.0 <--> Web 3.0 interface**
+
+:   Agents that interface and bridge the gap between existing (Web 2.0) and new (Web 3.0) economic models. An example is an <a href="../http-connection-and-skill"> AEA that communicates with HTTP clients/servers</a>.
+
+**Digital data sales**
+
+:   Agents with access to some data sources that sell the data, access to the data, or access to the usage of the data. An example is an <a href="../ml-skills">AEA that continuously sells data to another AEA</a>, who in turn uses it to improve their reinforcement learning model.
+
+## Multi-Agent System VS Agent-Based Modelling
+
+The AEA framework enables the creation of multi-agent systems as technological solutions to real world problems. 
+
+Although there are some overlap, the framework is not designed from the outset as an agent-based modelling software, where the goal is scientific behavioural observation rather than practical economic gain.
+
+Moreover, there is no restriction to _multi_; single-agent applications are also supported.

docs/build-aea-step-by-step.md

@@ -10,4 +10,4 @@ Building an AEA step by step (ensure you have followed the <a href="../quickstar
 1. Where required, scaffold any of the above resources with the <a href="../scaffolding/">scaffolding tool</a> or generate a protocol with the <a href="../protocol-generator/">protocol generator</a>.
 1. Now, run your AEA: `aea run --connections [public_id]`
 
-See information on the CLI tool <a href="../cli-how-to/" target="_blank">here</a> for all the available commands.
+See information on the CLI tool <a href="../cli-commands/" target="_blank">here</a> for all the available commands.

docs/core-components.md

@@ -0,0 +1,48 @@
+# Core Components
+
+AEAs can be made from various components, much like legos, and these components can be of differing types. Below are some of the more important types of components an agent can have.   
+
+## Skill
+
+A **Skill** is an isolated, self-contained, (and preferably atomic) functionality that AEAs can take on board to expand their capability. Skills contain the proactive and reactive behaviour that ultimately makes it possible for an AEA to deliver economic value to its owner.  
+
+A Skill encapsulates implementations of three base classes `Handler`, `Behaviour`, `Model`, and is closely related with `Task`:
+
+- Handler: Handlers implement AEAs' **reactive** behaviour. If an AEA understands a protocol referenced in a received `Envelope`, this envelope is sent to the corresponding handler which executes the AEA's reaction to this message.
+- Behaviour: Behaviours implement AEAs' **proactiveness**, encapsulating actions which further an AEA's goals, and are initiated by internals of the AEA rather than external events. 
+- Model: Encapsulate arbitrary objects and is made available to all components of the skill.
+- Task: Tasks encapsulate background work internal to the AEA. 
+
+A skill can read (parts of) an AEA's state and propose actions to the AEA according to its specific logic. As such, more than one skill could exist per protocol, competing with each other in suggesting to the AEA the best course of actions to take. 
+
+For instance, an AEA which is trading goods, could subscribe to more than one skill, where each corresponds to a different trading strategy.
+
+The framework places no limits on the complexity of `Skills`. They can implement simple (e.g. if-this-then-that) logic or be complex (e.g. a deep learning model or reinforcement learning agent).
+
+The framework provides one default `error` skill. Additional `Skills` can be added as packages. For more details on skills, head over to the <a href="../skill"> `Skill` guide </a>.
+
+## Protocol
+
+A **Protocol** defines the structure and nature of an interaction that can happen between agents, or between components of an agent. You can think of a protocol as the language that two agents speak and a skill for this protocol as a particular way of speaking this language. From a game-theoretic viewpoint, a protocol defines the rules of a game and a skill for this protocol defines a particular strategy for playing this game. 
+
+Protocols define agent-to-agent as well as component-to-component interactions within AEAs. As such, they include:
+
+- `Messages`: defining the syntax of messages.
+- `Serialization`: defining how a message is encoded for transport.
+- `Dialogues`: defines rules over sequences of messages.
+
+The framework provides one `default` protocol. This protocol provides a bare-bones implementation which includes a <a href="../api/protocols/default/message#packages.fetchai.protocols.default.message">`DefaultMessage`</a>  class and associated <a href="../api/protocols/default/serialization#packages.fetchai.protocols.default.serialization">`DefaultSerializer`</a> and <a href="../api/protocols/default/dialogues#packages.fetchai.protocols.default.dialogues">`DefaultDialogue`</a> classes.
+
+Additional protocols for new types of interactions, can be added as packages. For more details on protocols, you can read the <a href="../protocol">protocol guide</a>. To learn how you can easily automate protocol definition, head to the guide for the <a href="../protocol-generator">protocol generator</a>.
+
+Protocol specific messages, wrapped in `Envelopes`, are sent and received to other agents, agent components and services via **Connections**.
+
+## Connection
+
+**Connections** act as interfaces between an agent and the outside world. As such, a connection allows the agent to communicate with some entity outside of it, for example, another agent, a traditional HTTP server, a database, a reinforcement learning training environment, a blockchain, etc.
+
+Where necessary, a Connection is responsible for translating between the framework specific `Envelope` with its contained message and the external service or third-party protocol (e.g. HTTP).
+
+The framework provides one default `stub` connection. It implements an I/O reader and writer to send messages to the agent from a local file.
+
+Additional connections can be added as packages. For more details on `Connections` read the <a href="../connection">`Connection` guide</a>.

docs/css/admonitions.css

@@ -0,0 +1,18 @@
+:root {
+  --md-admonition-icon--target: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M11 2v2.07A8.002 8.002 0 0 0 4.07 11H2v2h2.07A8.002 8.002 0 0 0 11 19.93V22h2v-2.07A8.002 8.002 0 0 0 19.93 13H22v-2h-2.07A8.002 8.002 0 0 0 13 4.07V2m-2 4.08V8h2V6.09c2.5.41 4.5 2.41 4.92 4.91H16v2h1.91c-.41 2.5-2.41 4.5-4.91 4.92V16h-2v1.91C8.5 17.5 6.5 15.5 6.08 13H8v-2H6.09C6.5 8.5 8.5 6.5 11 6.08M12 11a1 1 0 0 0-1 1 1 1 0 0 0 1 1 1 1 0 0 0 1-1 1 1 0 0 0-1-1Z"/></svg>')
+}
+
+.md-typeset .admonition.target,
+.md-typeset details.target {
+  border-color: rgb(255, 225, 0);
+}
+.md-typeset .target > .admonition-title,
+.md-typeset .target > summary {
+  background-color: rgba(255, 225, 0, 0.1);
+}
+.md-typeset .target > .admonition-title::before,
+.md-typeset .target > summary::before {
+  background-color: rgb(255, 225, 0);
+  -webkit-mask-image: var(--md-admonition-icon--target);
+          mask-image: var(--md-admonition-icon--target);
+}

docs/ecosystem.md

@@ -0,0 +1,39 @@
+# Agent Ecosystem
+
+AEAs are situated within a larger ecosystem comprised of various other systems and technology layers.
+
+<img src="../assets/oef-ledger.jpg" alt="The AEA, OEF, and Ledger systems" class="center">
+
+## Agent Communication Network (ACN)
+
+ACN is a <a href="../acn">peer-to-peer communication network</a> for agents. It allows AEAs to send and receive envelopes between each other.
+
+The implementation builds on the open-source <a href="https://libp2p.io/" target="_blank">libp2p</a> library. A distributed hash table is used by all participating peers to maintain a mapping between agents' cryptographic addresses and their network addresses.
+
+Agents can receive messages from other agents if they are both connected to the ACN (see <a href="../p2p-connection">here</a> for an example).
+
+## Search and Discovery
+
+An <a href="../simple-oef">sOEF node</a> allows agents to discover each other. In particular, agents can register themselves and the services they offer, and can search for agents who offer specific services.
+
+For two agents to be able to find each other, at least one must register itself on the sOEF and the other must query the sOEF node for it. Detailed documentation is provided <a href="../simple-oef">here</a>.
+
+## Ledgers
+
+Ledgers enable AEAs to store transactions, for example involving the transfer of funds to each other, or the execution of smart contracts. They optionally ensure the truth and integrity of agent to agent interactions.
+
+Although a ledger can, in principle, be used to store structured data (e.g. training data in a machine learning model), in most cases the resulting costs and privacy implications do not make this sustainable. Instead, usually only references to structured data - often in the form of hashes - are stored on a ledger, and the actual data is stored off-chain.
+
+The Python implementation of the AEA Framework currently integrates with three ledgers:
+
+- <a href="https://docs.fetch.ai/ledger_v2/" target="_blank">Fetch.ai ledger</a>
+- <a href="https://ethereum.org/en/developers/learning-tools/" target="_blank">Ethereum ledger</a>
+- <a href="https://v1.cosmos.network/sdk" target="_blank">Cosmos ledger</a>
+
+Furthermore, the framework makes it straightforward for any developer to create a ledger plugin, adding support for another ledger.
+
+### AEAs as Second Layer Technology
+
+The following presentation discusses how AEAs can be seen as second layer technology to ledgers.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/gvzYX7CYk-A" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>