diff --git a/DEVELOPING.md b/DEVELOPING.md index 3cdd8d48d4..3115e4c644 100644 --- a/DEVELOPING.md +++ b/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 poetry 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 ``` diff --git a/docs/aeas.md b/docs/aeas.md new file mode 100644 index 0000000000..f89b744bcb --- /dev/null +++ b/docs/aeas.md @@ -0,0 +1,31 @@ +# Autonomous Economic Agents (AEAs) + + + +## 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. diff --git a/docs/app-areas.md b/docs/app-areas.md deleted file mode 100644 index 0de9868c3a..0000000000 --- a/docs/app-areas.md +++ /dev/null @@ -1,31 +0,0 @@ -# Application Areas - -The introduction and the agent-oriented development guide together present a picture of the kinds of solution an agent-based approach makes possible, and the types of environment they are most suited for. In short, this is where: - -- the environment is decentralized, -- involves multiple stakeholders, and -- is inhabited by AEAs representing the different stakeholders who: - - interact autonomously, and - - communicate with one another directly via a peer-to-peer network. - -In light of those discussions, on this page 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. - -- **Inhabitants**: agents representing objects in the IoT (Internet of Things) space. For examples, AEAs paired with real world hardware devices such as drones, laptops, heat sensors, etc. An example is a thermometer agent . -- **Interfaces**: facilitation agents which provide the necessary API interfaces for interaction between existing (Web 2.0) and new (Web 3.0) economic models. An example is an AEA with HTTP connection and skill who has the capability to communicate using HTTP. -- **Pure software**: software agents _living_ in the digital space that interact with interface agents and others. -- **Digital data sales agents**: software agents that attach to data sources and sell it via the open economic framework. An example can be found here. -- **Representative**: an agent which represents an individual's activities on the Fetch.ai network. An example can be found here. - -## Likely Short-Term Applications - -In the short-term we see AEAs primarily deployed in three areas: - -- Off-load repetitive tasks: AEAs can automate well-defined processes in different domains such as supply chain, mobility and finance, etc. -- Micro-transactions: AEAs make it economically viable to execute trades which involve small value transfers. This is particularly relevant in areas where there is a (data) supply side constituted of many small actors and a single demand side. -- Wallet agents: AEAs can simplify interactions with blockchains for end users. For instance, they can act as "smart wallets" which optimize blockchain interactions on behalf of the user. - -## Multi-Agent System versus Agent-Based Modelling - -The multi-agent systems enabled by the AEA framework are technological agent-based solutions to real problems and, although there are some overlap, the framework is not designed from the outset to be used 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. diff --git a/docs/application.md b/docs/application.md new file mode 100644 index 0000000000..1de22b123d --- /dev/null +++ b/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 thermometer agent. + +**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 AEA that communicates with HTTP clients/servers. + +**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 AEA that continuously sells data to another AEA, 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. diff --git a/docs/build-aea-step-by-step.md b/docs/build-aea-step-by-step.md index d7adfe851a..934c401f73 100644 --- a/docs/build-aea-step-by-step.md +++ b/docs/build-aea-step-by-step.md @@ -10,4 +10,4 @@ Building an AEA step by step (ensure you have followed the scaffolding tool or generate a protocol with the protocol generator. 1. Now, run your AEA: `aea run --connections [public_id]` -See information on the CLI tool here for all the available commands. +See information on the CLI tool here for all the available commands. diff --git a/docs/cli-how-to.md b/docs/cli-how-to.md deleted file mode 100644 index 5d19bcd798..0000000000 --- a/docs/cli-how-to.md +++ /dev/null @@ -1,61 +0,0 @@ -# How to Use the Command Line Interface - -The command line interface is the easiest way to build an AEA. - -## Installation - -The following installs the AEA CLI package. - -``` bash -pip install aea[cli] -``` - -The following installs the entire AEA package including the CLI. - -``` bash -pip install aea[all] -``` - -If you are using `zsh` rather than `bash` type - -``` zsh -pip install 'aea[cli]' -``` - -and - -``` zsh -pip install 'aea[all]' -``` - -respectively. - -Be sure that the `bin` folder of your Python environment -is in the `PATH` variable. If so, you can execute the CLI tool as: - -``` bash -aea -``` - -You might find useful the execution of the `aea.cli` package -as a script: - -``` bash -python -m aea.cli -``` - -which is just an alternative entry-point to the CLI tool. - -## Troubleshooting - -To ensure no cache is used run. - -``` bash -pip install aea[all] --force --no-cache-dir -``` - -And for `zsh` run: - -``` zsh -pip install 'aea[all]' --force --no-cache-dir -``` diff --git a/docs/core-components.md b/docs/core-components.md new file mode 100644 index 0000000000..c9474bdffa --- /dev/null +++ b/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 `Skill` guide . + +## 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 `DefaultMessage` class and associated `DefaultSerializer` and `DefaultDialogue` classes. + +Additional protocols for new types of interactions, can be added as packages. For more details on protocols, you can read the protocol guide. To learn how you can easily automate protocol definition, head to the guide for the protocol generator. + +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 `Connection` guide. \ No newline at end of file diff --git a/docs/css/admonitions.css b/docs/css/admonitions.css new file mode 100644 index 0000000000..527aa287f0 --- /dev/null +++ b/docs/css/admonitions.css @@ -0,0 +1,18 @@ +:root { + --md-admonition-icon--target: url('data:image/svg+xml;charset=utf-8,') +} + +.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); +} diff --git a/docs/ecosystem.md b/docs/ecosystem.md new file mode 100644 index 0000000000..75290b74c6 --- /dev/null +++ b/docs/ecosystem.md @@ -0,0 +1,39 @@ +# Agent Ecosystem + +AEAs are situated within a larger ecosystem comprised of various other systems and technology layers. + +The AEA, OEF, and Ledger systems + +## Agent Communication Network (ACN) + +ACN is a peer-to-peer communication network for agents. It allows AEAs to send and receive envelopes between each other. + +The implementation builds on the open-source libp2p 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 here for an example). + +## Search and Discovery + +An sOEF node 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 here. + +## 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: + +- Fetch.ai ledger +- Ethereum ledger +- Cosmos ledger + +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. + + diff --git a/docs/index.md b/docs/index.md index ab90cd3825..d14ab4af73 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,47 +1,84 @@ # AEA Framework Documentation -The AEA framework provides the tools for creating Autonomous Economic Agents (AEA). +!!! target "Vision" + Our aim with the AEA framework is to enable businesses of all sizes, from independent developers to large corporations and consortiums, to create and deploy agent-based solutions in various domains, thus contributing to and advancing a decentralized mixed-initiative economy: one whose actors are both humans and machines. -## Autonomous Economic Agents (AEAs) - - - -### What is an AEA? +## 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. -- **Agent**: An AEA represents an individual, organisation or object and looks after their interests. -- **Autonomous**: AEAs act independently of constant input from their owner and autonomously execute actions to achieve their prescribed goals. -- **Economic**: Their purpose is to create economic value for their owner, in clearly defined domains. +Breaking it down: -AEAs have a wide range of application areas and we provide demo guides to highlight examples of their use cases. +**AGENT**: An AEA represents an individual, organisation or object and looks after their interests. -### What is not an AEA +**AUTONOMOUS**: AEAs operate independently of constant input from their owners and act autonomously to achieve their goals. -- Any agent: AEAs' purpose is to generate economic value in a multi-stakeholder environment with competing incentives between agents. They represent humans, organisations or objects. -- APIs or sensors which do not have agency. -- Smart contracts which do not display any proactivity and are purely reactive to external requests (=contract calls and transactions). -- Artificial General Intelligence (AGI). AEAs can have a very narrow, goal directed focus involving some economic gain and can have a very simple logic. +**ECONOMIC**: AEAs have a narrow and specific focus: creating economic value for their owner. -!!! note - In the rest of the documentation, unless specified otherwise, we use the terms AEA and agent interchangeably to refer to AEA as defined above. +## What Can You Do with AEAs? + +[//]: # (AEAs have the potential of being the next "apps", by enabling p2p. Most importantly, ) + +Some examples of the kinds of applications you can build with AEAs: + +**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 thermometer agent. + +**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 AEA that communicates with HTTP clients/servers. + +**Traders** + +: 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 AEA that continuously sells data to another AEA, who in turn uses it to improve their reinforcement learning model. + +## Who is This For? + +The AEA technology is for anyone who wants to build or contribute to a "mixed-initiative economy": one whose actors are humans as well as machines. + +This includes (amongst others): developers, data scientists and machine learning experts, economists, students, academics and researchers (in Artificial Intelligence, Machine Learning, Multi-Agent Systems, etc), engineers, and so forth. + +## The AEA Framework + +The AEA framework is a development suite which equips you with an efficient and accessible set of tools for building and running AEAs and their components. + +The framework attempts to make agent development as straightforward an experience as possible, similar to what popular web frameworks enable for web development. + +Some of the characteristics of the AEA framework are: -## What is the AEA Framework? +- **Python**: Using Python as an approachable programming language improves the on-boarding for those who just want to get started with agent development. +- **Open source**: The framework is open source and licensed under Apache 2.0. +- **Modular**: Modularity is at the heart of the framework's design. This makes it easy to extend the framework, add new functionality, and re-use others' contributions, therefore reducing the development cost. +- **Blockchain ready**: Integration with blockchains is baked into the framework, enabling the creation of agents that take full advantage of the blockchain technology. +- **Modern**: The framework is built from and can be integrated with the latest technologies (e.g. asynchronous programming, blockchains and smart contracts, machine-learning ready, ...). -The AEA framework is a development suite, currently implemented in Python, which equips you with an efficient and accessible set of tools for building and running AEAs. The framework is modular, extensible, and composable. It attempts to make agent development as straightforward an experience as possible, similar to web development using popular web frameworks. +## The Ecosystem -AEAs achieve their goals with the help of a search & discovery service for AEAs -- the simple Open Economic Framework (sOEF) -- a decentralized agent communication system -- the Agent Communication Network (ACN) -- and using Fetch.ai's blockchain as a financial settlement and commitment layer. AEAs can also be integrated with third-party blockchains, such as Ethereum. +Though they can work in isolation, AEAs are truly valuable when situated in a wider ecosystem consisting of tools and infrastructure that enable them to cooperate and compete, and interact with services as well as traditional or modern systems. These include: -## Why Build with the AEA Framework? +- The Agent Communication Network (ACN): A peer-to-peer communication infrastructure that enables AEAs to directly communicate with one another without any intermediaries. +- The sOEF: A search and discovery system allowing AEAs to register themselves and the services they offer, and search for agents who offer specific services. +- The AEA Registry: A space to store and share AEAs or individual agent components for anyone to find and use. +- Blockchains: AEAs can use blockchains as a financial and commitment layer. Each ledger plug-in provided by the framework adds the ability for AEAs to interact with a specific ledger, such as the Fetch.ai blockchain or Ethereum. +- Smart Contracts: Contract packages are wrappers around smart contracts that allow AEAs to interact with them through a common interface. -The AEA framework provides the developer with a number of features, which combined cannot be found anywhere else: +## How to get involved? -- The peer-to-peer agent communication network (ACN) allows your AEAs to interact with all other AEAs over the public internet. -- The search and discovery system sOEF allows your AEAs to find other AEAs. -- The AEA registry enables code sharing and re-use by providing a space in which AEAs or their individual components may be shared. -- The framework's crypto and ledger APIs make it possible for AEAs to interact with blockchains. -- The contract packages enable AEAs to interact with smart contracts in Fetch.ai and other third-party decentralized ledgers. +There are many ways for you to get involved. You can create agents, develop new agent components, extend existing components, and contribute to the development of the framework or other related tools. Please refer to the Contribution and Development guides. ## Next Steps diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000000..80090b4677 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,138 @@ +# Installation + +!!! Info "Platforms" + The AEA framework can be used on `Windows`, `Ubuntu/Debian` and `MacOS`. + +## System Requirements + +1. You need Python 3.8, 3.9 or 3.10 on your system. +2. GCC installation is also required: + + === "Ubuntu" + ``` bash + apt-get install gcc + ``` + === "MacOS X (with Homebrew)" + ``` bash + brew install gcc + ``` + === "Windows (with choco)" + ``` bash + choco install mingw + ``` + +??? tip "Tips" + + - **Ubuntu/Debian**: install Python headers, depending on the Python version you have installed on your machine. For example for Python 3.8: + + ``` bash + sudo apt-get install python3.8-dev + ``` + + - **Windows**: install tools for Visual Studio. + +### Alternatively: Use Docker + +We also provide a Docker image with all the needed dependencies. + +1. Pull the image: + + ``` bash + docker pull fetchai/aea-user:latest + ``` + +2. Run the image with your current local directory mounted as a docker volume. This allows you to keep your agents local while working on them from within the docker container: + + === "Linux and MacOs" + ``` bash + docker run -it -v $(pwd):/agents --workdir=/agents fetchai/aea-user:latest + ``` + === "Windows" + ``` powershell + docker run -it -v %cd%:/agents --workdir=/agents fetchai/aea-user:latest + ``` + +Once successfully logged into the docker container, you can follow the rest of the guide the same way as if not using docker. + +## For Agent Development + +### Preliminaries + +1. Create a new working directory. Let's call it `my_aea_projects`. This is where you will create your agent projects. + +2. Inside `my_aea_projects`, add an empty directory called `packages`. This is a local registry for your agents' components. + +You should now have the following directory structure: + +```bash +my_aea_projects +└── packages +``` + +!!! tip "Alternatively, clone a template repo:" + Instead of the above, you can clone the template repo as described in `Approach 1` in the development setup guide. + +#### Virtual Environment + +Unless you are using the docker image, we highly recommend using a virtual environment so that your setup is isolated from the rest of your system. This prevents clashes and ensures consistency across dependencies. + +You can use any common virtual environment manager for Python, such as `pipenv` and `poetry`. If you do not have either, install one. + +Once installed, create a new virtual environment in the `my_aea_projects` directory and enter it: + +=== "pipenv" + Use any Python version supported in the command: + ``` bash + pipenv --python 3.9 && pipenv shell + ``` +=== "poetry" + ``` bash + poetry init -n && poetry shell + ``` + +### Installation + +The latest version of the Python implementation of the AEA Framework is: + + + PyPI + + +!!! info "Note" + If you are upgrading your AEA project from a previous version of the AEA framework, make sure you check out the upgrading notes. + +#### Using pip + +Install the AEA framework using pip: + +=== "bash/windows" + ``` bash + pip install aea[all] + ``` +=== "zsh" + ``` zsh + pip install 'aea[all]' + ``` + +??? tip "Troubleshooting" + To ensure no cache is used, add `--force --no-cache-dir` to the installation command. + +#### Using pipx + +Install the AEA framework using pipx: + +``` bash +pipx install aea[all] +``` + +## For Contributing to the AEA Framework + +To contribute to the development of the framework or related tools (e.g. ACN), please refer to the Contribution and Development guides in our GitHub repository. + +## Other Tools You Might Need + +Depending on what you want to do, you might need extra tools on your system: + +- To use the Agent Communication Network (ACN) for peer-to-peer communication between agents (e.g. using the `fetchai/p2p_libp2p` connection) you will need Golang 1.14.2 or higher. +- The framework uses Google Protocol Buffers for message serialization. If you want to develop protocols, install the protobuf compiler on your system. The version you install must match the `protobuf` library installed with the project (see pyproject.toml). +- To update fingerprint hashes of packages, you will need the IPFS daemon. diff --git a/docs/oef-ledger.md b/docs/oef-ledger.md deleted file mode 100644 index f9b6151435..0000000000 --- a/docs/oef-ledger.md +++ /dev/null @@ -1,54 +0,0 @@ -# Relation to OEF and Ledger - -The Open Economic Framework (OEF) and Decentralized Ledger Technologies (DLTs) allow AEAs to create value through their interaction with other AEAs. The following diagram illustrates the relation of AEAs to the OEF and DLTs. - -The AEA, OEF, and Ledger systems - -## Open Economic Framework (OEF) - -The _Open Economic Framework_ (OEF) consists of protocols, languages and market mechanisms agents use to search and find each other, communicate with as well as trade with each other. As such the OEF defines the decentralized virtual environment that supplies and supports APIs for autonomous third-party software agents, also known as Autonomous Economic Agents (AEAs). - -!!! note - The OEF is under development. Expect frequent changes. What follows is a description of the current implementation. - -At present, the OEF's capabilities are fulfilled by three components: - -- a permissionless, public peer to peer (agent to agent) communication network, called the Agent Communication Network; -- a set of agent interaction protocols; and -- a centralized search and discovery system. - -The latter will be decentralized over time. - -### Agent Communication Network (ACN) - -ACN is a peer-to-peer communication network for agents. It allows AEAs to send and receive envelopes between each other. - -The implementation builds on the open-source libp2p 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 here for an example). - -### Search and Discovery - -A simple OEF (sOEF) node 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 here. - -## 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. - -Whilst a ledger can, in principle, be used to store structured data (for instance, training data in a machine learning model) in most use cases the resulting costs and privacy implications do not make this an efficient use of the ledger. 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: - -- Fetch.ai ledger -- Ethereum ledger -- Cosmos ledger - -However, the framework makes it straightforward for any developer to add support for other ledgers. - -### AEAs as Second Layer Technology - -The following presentation discusses how AEAs can be seen as second layer technology to ledgers. - - diff --git a/docs/protocol.md b/docs/protocol.md index 43e48c24f9..3d19b93ad5 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -252,7 +252,7 @@ oef_msg = OefSearchMessage( ) ``` -- The SOEF search node will respond with a message `msg` of type `OefSearchMessage` with performative `OefSearchMessage.Performative.SEARCH_RESULT`. To access the tuple of agents which match the query, simply use `msg.agents`. In particular, this will return the agent addresses matching the query. The agent address can then be used to send a message to the agent utilising the P2P agent communication network and any protocol other than `fetchai/oef_search:1.0.0`. +- The SOEF search node will respond with a message `msg` of type `OefSearchMessage` with performative `OefSearchMessage.Performative.SEARCH_RESULT`. To access the tuple of agents which match the query, simply use `msg.agents`. In particular, this will return the agent addresses matching the query. The agent address can then be used to send a message to the agent utilising the P2P agent communication network and any protocol other than `fetchai/oef_search:1.0.0`. - If the SOEF search node encounters any errors with the messages you send, it will return an `OefSearchMessage` of performative `OefSearchMessage.Performative.OEF_ERROR` and indicate the error operation encountered: diff --git a/docs/questions-and-answers.md b/docs/questions-and-answers.md index ffc810adbb..d9d3ea046b 100644 --- a/docs/questions-and-answers.md +++ b/docs/questions-and-answers.md @@ -6,12 +6,12 @@ ??? question "How do AEAs talk to each other when they do not know each other?" For an Autonomous Economic Agent (AEA) to talk to other AEAs, it first needs to find them. Once it does, it should ensure that they both use the same protocol for communication, and if so, they then have to send messages to each other. - The AEA framework, together with some of the services it provides, address all three problems. You can read more about search and discovery here, protocols here, and the Agent Communication Network (ACN) here. + The AEA framework, together with some of the services it provides, address all three problems. You can read more about search and discovery here, protocols here, and the Agent Communication Network (ACN) here. ??? question "How does an AEA use blockchain?" The AEA framework enables agents to interact with blockchains to settle transactions. Currently, the framework has native support for three different networks: _Fetch.ai_, _Ethereum_ and _Cosmos_. - You can read more about the framework's integration with the different blockchains here and gain a high level overview here. + You can read more about the framework's integration with the different blockchains here and gain a high level overview here. ??? question "How does one install third party libraries?" The framework supports the use of third-party libraries hosted on PyPI. You can directly reference the external dependencies of an AEA package (e.g. skill) in its configuration file. From inside an AEA's project directory, the `install` command can be used to install all the dependencies of the AEA which are listed in the configuration files belonging to any of its packages. @@ -29,7 +29,7 @@ ??? question "Is the AEA framework ideal for agent-based modelling?" The goal of agent-based modelling (ABM) is to study the unknown (often complex) behaviour of systems comprised of agents with known (much simpler) behaviour. ABM is a popular technique for studying biological and social systems. Despite some similarities between ABM and the AEA framework, the two have fundamentally different goals. ABM's goal is not the design of agents or solving specific practical or engineering problems. Although it would be potentially possible, it would likely be inefficient to use the AEA framework for that kind of problems. - You can find more details on the application areas of the AEA framework here. + You can find more details on the application areas of the AEA framework here. ??? question "When a new AEA is created, is the `vendor` folder populated with some default packages?" All AEA projects by default hold the `fetchai/default:1.1.7`, `fetchai/state_update:1.1.7` and `fetchai/signing:1.1.7` protocols. These (as all other packages installed from the registry) are placed in the `vendor` folder. diff --git a/docs/quickstart.md b/docs/quickstart.md index 2f04bdb514..8a5e45bf13 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -6,171 +6,6 @@ If you want to create Autonomous Economic Agents (AEAs) that can act independent This example will take you through a simple AEA to familiarise you with the basics of the framework. -## System Requirements - -The AEA framework can be used on `Windows`, `Ubuntu/Debian` and `MacOS`. - -You need Python 3.6 or higher as well as Go 1.14.2 or higher installed. - -GCC installation is required: - -- Ubuntu: `apt-get install gcc` -- Windows (with `choco` - installed): `choco install mingw` -- MacOS X (with home brew): `brew install gcc` - -### Option 1: Manual System Preparation - -Install a compatible Python and Go version on your system (see this external resource for a comprehensive guide). - -??? note "Manual approach:" - - The following hints can help: - - - To install Go, follow the official guide, depending on your platform here - - Python is already included by default on many Linux distributions (e.g. Ubuntu), as well as MacOS. To check you have the right version, open a terminal and run: - - ``` bash - python3 --version - ``` - - - To install Python on Windows machines, you can download a specific release here. - - Ubuntu/Debian systems only: install Python headers, depending on the Python version you have installed on your machine. E.g. for Python 3.7: - - ``` bash - sudo apt-get install python3.7-dev - ``` - - - Windows users: install tools for Visual Studio. - -### Option 2: Using an 'Automated Install' Script - -We provide a script to automatically install all framework dependencies and the framework itself. This means that if you follow this option, you can skip the installation step that comes later on this page. - -??? note "The 'Automated install' script approach:" - On macOS or Ubuntu run the following commands to download and install: - - ``` bash - curl https://raw.githubusercontent.com/fetchai/agents-aea/main/scripts/install.sh --output install.sh - chmod +x install.sh - ./install.sh - ``` - - On Windows: download https://raw.githubusercontent.com/fetchai/agents-aea/main/scripts/install.ps1, then run install.ps1 with the PowerShell terminal. - -### Option 3: Using Docker - -​ -We also provide a Docker image with all the needed dependencies. - -??? note "Docker approach:" - To use the image, you will first have to pull it, then run it with your current local directory mounted as a docker volume. This allows you to keep your agents local while working on them from within the docker container. - - To pull: - - ``` bash - docker pull fetchai/aea-user:latest - ``` - - To run the image on Linux and MacOs: - - ``` bash - docker run -it -v $(pwd):/agents --workdir=/agents fetchai/aea-user:latest - ``` - - And on Windows: - - ``` bash - docker run -it -v %cd%:/agents --workdir=/agents fetchai/aea-user:latest - ``` - - Once successfully logged into the docker container, - you can follow the rest of the guide the same way as if not using docker. - -## Preliminaries - -Ensure, you are in a clean working directory: - -- either you create it manually `mkdir my_aea_projects/ && cd my_aea_projects/`, then add an empty directory called `packages` with the following command `mkdir packages/`, - -- or you clone the template repo as described in `Approach 1` in the development setup guide. - -At this point, when typing `ls` you should see a single folder called `packages` in your working environment. This will act as your local registry for AEA components. - -Unless you are using the docker image, we highly recommend using a virtual environment to ensure consistency across dependencies. - -Check that you have `pipenv`. - -``` bash -which pipenv -``` - -If you don't have it, install it. Instructions are here. - -Once installed, create a new environment and open it (here we use Python 3.7 but the AEA framework supports any Python >= 3.6). - -``` bash -touch Pipfile && pipenv --python 3.7 && pipenv shell -``` - -## Installation - -The following installs the entire AEA package which also includes a command-line interface (CLI). (You can skip this step if you used the 'install script' above: Option 2 .) - -``` bash -pip install aea[all] -``` - -If you are using `zsh` rather than `bash` type - -``` zsh -pip install 'aea[all]' -``` - -If the installation steps fail, it might be a dependency issue. Make sure you have followed all the relevant system specific steps above under `System Requirements`. - -## Setup Author Name - -You can set up your author name using the `init` command: - -``` bash -aea init -``` - -## Register as an AEA Author (optional) - -AEAs are composed of components. AEAs and AEA components can be developed by anyone and pushed to the AEA registry for others to use. To publish packages to the registry, we need to register an author name: - -``` bash -aea register -``` - -This is your unique author (or developer) name in the AEA ecosystem. - -You should see a similar output (with your input instead of the sample username and email): - -``` bash -Do you have a Registry account? [y/N]: n -Create a new account on the Registry now: -Username: fetchai -Email: hello@fetch.ai -Password: -Please make sure that passwords are equal. -Confirm password: - _ _____ _ - / \ | ____| / \ - / _ \ | _| / _ \ - / ___ \ | |___ / ___ \ -/_/ \_\|_____|/_/ \_\ - -v1.2.5 - -AEA configurations successfully initialized: {'author': 'fetchai'} -``` - -!!! note - If you would rather not create an account on the registry at this point, then run `aea init --local` instead. - ## Echo Skill Demo This is a simple demo that introduces you to the main components of an AEA. diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000000..4623033716 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,38 @@ +# Setting up + +Once you successfully install the AEA framework, you can set it up for agent development. + +## Specify Author Handle + +You need an author handle before being able to develop agents or agent components. This handle is used in the `author` field of any agent or component you create. + +AEAs and their components can be developed by anyone and pushed to the AEA registry for others to use. To publish packages to the registry, you also need to register your author handle. + +### Pick Author Handle and Register + +If you are intending to use the registry: + +``` bash +aea init --register +``` + +This will let you pick a new author handle and register it at the same time. + +### Pick Author Handle Only + +If you are unsure whether you will need a registry account, or intending not to use it, simply pick a new author handle: + +``` bash +aea init +``` + +### Register Author Handle + +To register an already created author handle with the AEA registry: + +``` bash +aea register +``` + +!!! info "Note" + The author handle is your unique author (or developer) name in the AEA ecosystem. diff --git a/docs/skill-guide.md b/docs/skill-guide.md index 6b5834def7..5521bd0ea4 100644 --- a/docs/skill-guide.md +++ b/docs/skill-guide.md @@ -27,7 +27,7 @@ In the following steps, we replace the scaffolded `Behaviour` and `Handler` in ` A `Behaviour` class contains the business logic specific to actions initiated by the AEA rather than reactions to other events. -In this example, we implement a simple search behaviour. Each time, `act()` gets called by the main agent loop, we will send a search request to the SOEF search node via the P2P communication network. +In this example, we implement a simple search behaviour. Each time, `act()` gets called by the main agent loop, we will send a search request to the SOEF search node via the P2P communication network. ``` python from typing import cast diff --git a/docs/version.md b/docs/version.md deleted file mode 100644 index a44a6123ec..0000000000 --- a/docs/version.md +++ /dev/null @@ -1,11 +0,0 @@ -# Version - -The latest version of the Python implementation of the AEA Framework: - -PyPI. - -The framework is under rapid development with frequent breaking changes in the run-up to version `1.0` which is due in Q1 2021. - -If you are upgrading your AEA project from a previous version of the AEA framework, please check out the upgrading guide. - -The AEA framework's implementation in Python is in principle compatible with its implementation in any other language. The language agnostic definitions describe the aspects of the framework an implementation must adhere to in order for their AEAs to be able to interact with AEAs built with other implementations of the framework. diff --git a/docs/vision.md b/docs/vision.md deleted file mode 100644 index a7384e2c64..0000000000 --- a/docs/vision.md +++ /dev/null @@ -1,19 +0,0 @@ -# Vision - -Our vision is that the AEA framework enables businesses of all sizes, from single independent developers to large corporations and consortiums, to create and deploy agent-based solutions in different domains, thus contributing to and advancing a decentralized agent economy as envisaged by Fetch.ai. - -## Open Source Technology for Everyone - -We are creating infrastructure for developers to build their own agent-based solutions. - -AEA users include, amongst others: - -- Data scientists -- Economists -- Researchers (Artificial Intelligence, Machine Learning, Multi-Agent Systems) -- Engineers -- Machine learning experts -- Independent developers -- Students and academics -- Crypto connoisseurs and enthusiasts -- Web developers diff --git a/mkdocs.yml b/mkdocs.yml index 18b93a9e87..315d52db1c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,92 +10,109 @@ copyright: Copyright © 2018 - 2023 Fetch.ai # Copyright notice in footer strict: true nav: - - Introduction: 'index.md' - - Version: 'version.md' - - Upgrading: 'upgrading.md' - - Concepts: + - AEA Overview: + - Overview: 'index.md' + - Autonomous Economic Agents: 'aeas.md' + - Application areas: 'application.md' + - Agent ecosystem: 'ecosystem.md' + - Installation and setup: + - Installation: 'install.md' + - Setting up: 'setup.md' + - Development setup: 'development-setup.md' + - Upgrading: 'upgrading.md' + - Build an AEA on a Raspberry Pi: 'raspberry-set-up.md' + - Getting started: + - Core components: 'core-components.md' + - Ways to build an AEA: 'step-one.md' + - Build an AEA with the CLI: 'build-aea-step-by-step.md' + - Architecture deep dives: - Language Agnostic Definition: 'language-agnostic-definition.md' - - Agent-oriented development: 'agent-oriented-development.md' - - Vision: 'vision.md' - - Application areas: 'app-areas.md' - - Relation to OEF and Ledger: 'oef-ledger.md' - - Identity: 'identity.md' - - Trust minimisation: 'trust.md' - - Demos: - - Demos: 'demos.md' - - Aries Cloud Agents Demo: 'aries-cloud-agent-demo.md' - - Car park skills: 'car-park-skills.md' - - Gym example: 'gym-example.md' - - Gym skill: 'gym-skill.md' - - ML skills: 'ml-skills.md' - - Oracle skills: 'oracle-demo.md' - - Aggregation skill: 'aggregation-demo.md' - - TAC skills: 'tac-skills.md' - - TAC skills ledger-based: 'tac-skills-contract.md' - - Thermometer skills: 'thermometer-skills.md' - - Weather skills: 'weather-skills.md' - - Development - Beginner: - - AEA quick start: 'quickstart.md' + - Architectural diagram: 'diagram.md' - Core components - Part 1: 'core-components-1.md' - - AEA and web frameworks: 'aea-vs-mvc.md' - - Build your first skill - search & discovery: 'skill-guide.md' - Core components - Part 2: 'core-components-2.md' - - How AEAs talk to each other - interaction protocols: 'interaction-protocol.md' - - Trade between two AEAs: 'generic-skills-step-by-step.md' - - Development setup: 'development-setup.md' - - Development - Advanced: - - Topic guides: - - Ways to build an AEA: 'step-one.md' - - Build an AEA with the CLI: 'build-aea-step-by-step.md' - - Scaffolding packages: 'scaffolding.md' - - Generating protocols: 'protocol-generator.md' - - Logging: 'logging.md' - - Use multiplexer stand-alone: 'multiplexer-standalone.md' - - Create stand-alone transaction: 'standalone-transaction.md' - - Create decision-maker transaction: 'decision-maker-transaction.md' - - Testing Skills: 'skill-testing.md' - - Deployment: 'deployment.md' + - Comparisons: + - AEA and web frameworks: 'aea-vs-mvc.md' - 12-Factor app and AEAs: '12-factor.md' - - Prometheus monitoring: 'prometheus.md' - - Known limitations: 'known-limits.md' - - Build an AEA programmatically: 'build-aea-programmatically.md' - - CLI vs programmatic AEAs: 'cli-vs-programmatic-aeas.md' - - AEAs vs agents: 'agent-vs-aea.md' - - Modes of running an AEA: 'modes.md' - - Generic Storage: 'generic-storage.md' - - Multi agent manager: 'multi-agent-manager.md' - - Debugging: 'debug.md' - - Profiling: 'runtime-cost.md' - - Proof of Representation: 'por.md' - - Security: 'security.md' - - Architecture & component deep-dives: - Design principles: 'design-principles.md' - - Architectural diagram: 'diagram.md' - - Connections: 'connection.md' - - Protocols: 'protocol.md' + - Developing Agents: + - Modes of running an AEA: 'modes.md' + - Multi agent manager: 'multi-agent-manager.md' + - Logging: 'logging.md' + - Deployment: 'deployment.md' + - Debugging: 'debug.md' + - Profiling: 'runtime-cost.md' + - Performance benchmark: 'performance-benchmark.md' + - Security Considerations: 'security.md' + - Developing Packages: + - File structure: 'package-imports.md' + - Scaffolding packages: 'scaffolding.md' + - Configurations: 'config.md' + - Skills: - Skills: 'skill.md' + - AEA quick start: 'quickstart.md' + - Build your first skill - search & discovery: 'skill-guide.md' + - Trade between two AEAs: 'generic-skills-step-by-step.md' + - Testing Skills: 'skill-testing.md' + - Protocols: + - Protocols: 'protocol.md' + - Message routing: 'message-routing.md' + - Generating protocols: 'protocol-generator.md' + - Connections: + - Connections: 'connection.md' + - Contracts: - Contracts: 'contract.md' + - Contract deploy and interact: 'erc1155-skills.md' + - Decision Maker: - Decision Maker: 'decision-maker.md' + - Ledger & Crypto APIs: - Ledger & Crypto APIs: 'ledger-integration.md' - - Message routing: 'message-routing.md' - - Configurations: 'config.md' - - Limitations of v1: 'limits.md' + - Ecosystem: - Agent Communication: - Agent Communication Network: 'acn.md' - ACN Internals: 'acn-internals.md' + - Proof of Representation: 'por.md' + - P2P Connection: 'p2p-connection.md' - Search & Discovery: - Simple OEF: 'simple-oef.md' - Defining Data Models: 'defining-data-models.md' - The Query Language: 'query-language.md' - SOEF Connection: 'simple-oef-usage.md' - - Developer Interfaces: - - CLI: - - Installation: 'cli-how-to.md' - - Commands: 'cli-commands.md' - - File structure: 'package-imports.md' - - Generating wealth: 'wealth.md' - - Benchmarks: - - Performance benchmark: 'performance-benchmark.md' + - Integrations: + - Front-end integration: 'connect-a-frontend.md' + - ORM integration: 'orm-integration.md' + - Generic Storage: 'generic-storage.md' + - Prometheus monitoring: 'prometheus.md' + - Generating wealth: 'wealth.md' + - Guides: + - Agent-oriented development: 'agent-oriented-development.md' + - Interaction protocols: 'interaction-protocol.md' + - Concepts: + - Identity: 'identity.md' + - Trust minimisation: 'trust.md' + - Development - Advanced: + - Build an AEA programmatically: 'build-aea-programmatically.md' + - CLI vs programmatic AEAs: 'cli-vs-programmatic-aeas.md' + - AEAs vs agents: 'agent-vs-aea.md' + - Use multiplexer stand-alone: 'multiplexer-standalone.md' + - Create stand-alone transaction: 'standalone-transaction.md' + - Create decision-maker transaction: 'decision-maker-transaction.md' + - Demos: + - Demos: 'demos.md' + - Generic skills: 'generic-skills.md' + - HTTP Connection: 'http-connection-and-skill.md' + - Aries Cloud Agents Demo: 'aries-cloud-agent-demo.md' + - Car park skills: 'car-park-skills.md' + - Gym example: 'gym-example.md' + - Gym skill: 'gym-skill.md' + - ML skills: 'ml-skills.md' + - Oracle skills: 'oracle-demo.md' + - Aggregation skill: 'aggregation-demo.md' + - TAC skills: 'tac-skills.md' + - TAC skills ledger-based: 'tac-skills-contract.md' + - Thermometer skills: 'thermometer-skills.md' + - Weather skills: 'weather-skills.md' + - Reference: + - Command Line Interface: 'cli-commands.md' - API: - AbstractAgent: 'api/abstract_agent.md' - AEA: 'api/aea.md' @@ -109,144 +126,138 @@ nav: - Runner: 'api/runner.md' - Runtime: 'api/runtime.md' - Components: - - Base: 'api/components/base.md' - - Loader: 'api/components/loader.md' - - Utils: 'api/components/utils.md' + - Base: 'api/components/base.md' + - Loader: 'api/components/loader.md' + - Utils: 'api/components/utils.md' - Configurations: - - Base: 'api/configurations/base.md' - - Constants: 'api/configurations/constants.md' - - Data Types: 'api/configurations/data_types.md' - - Loader: 'api/configurations/loader.md' - - Manager: 'api/configurations/manager.md' - - Pypi: 'api/configurations/pypi.md' - - Utils: 'api/configurations/utils.md' - - Validation: 'api/configurations/validation.md' + - Base: 'api/configurations/base.md' + - Constants: 'api/configurations/constants.md' + - Data Types: 'api/configurations/data_types.md' + - Loader: 'api/configurations/loader.md' + - Manager: 'api/configurations/manager.md' + - Pypi: 'api/configurations/pypi.md' + - Utils: 'api/configurations/utils.md' + - Validation: 'api/configurations/validation.md' - Connections: - - Base: 'api/connections/base.md' + - Base: 'api/connections/base.md' - Context: 'api/context/base.md' - Contracts: - - Base: 'api/contracts/base.md' + - Base: 'api/contracts/base.md' - Crypto: - - Base: 'api/crypto/base.md' - - Helpers: 'api/crypto/helpers.md' - - LedgerApis: 'api/crypto/ledger_apis.md' - - Plugin: 'api/crypto/plugin.md' - - Wallet: 'api/crypto/wallet.md' - - Registries: - - Base: 'api/crypto/registries/base.md' + - Base: 'api/crypto/base.md' + - Helpers: 'api/crypto/helpers.md' + - LedgerApis: 'api/crypto/ledger_apis.md' + - Plugin: 'api/crypto/plugin.md' + - Wallet: 'api/crypto/wallet.md' + - Registries: + - Base: 'api/crypto/registries/base.md' - Decision Maker: - - Base: 'api/decision_maker/base.md' - - Default: 'api/decision_maker/default.md' - - GOP: 'api/decision_maker/gop.md' + - Base: 'api/decision_maker/base.md' + - Default: 'api/decision_maker/default.md' + - GOP: 'api/decision_maker/gop.md' - Error Handler: - - Base: 'api/error_handler/base.md' - - Default: 'api/error_handler/default.md' + - Base: 'api/error_handler/base.md' + - Default: 'api/error_handler/default.md' - Helpers: - - ACN: - - Agent Record: 'api/helpers/acn/agent_record.md' - - URI: 'api/helpers/acn/uri.md' - - Async Friendly Queue: 'api/helpers/async_friendly_queue.md' - - Async Utils: 'api/helpers/async_utils.md' - - Base: 'api/helpers/base.md' - - Constants: 'api/helpers/constants.md' - - Env Vars: 'api/helpers/env_vars.md' - - Exception Policy: 'api/helpers/exception_policy.md' - - Exec Timeout: 'api/helpers/exec_timeout.md' - - File IO: 'api/helpers/file_io.md' - - File Lock: 'api/helpers/file_lock.md' - - HttpRequests: 'api/helpers/http_requests.md' - - Install Dependency: 'api/helpers/install_dependency.md' - - IO: 'api/helpers/io.md' - - IPFS: - - Base: 'api/helpers/ipfs/base.md' - - Utils: 'api/helpers/ipfs/utils.md' - - Logging: 'api/helpers/logging.md' - - MultiAddress: - - Base: 'api/helpers/multiaddr/base.md' - - MultipleExecutor: 'api/helpers/multiple_executor.md' - - Pipe: 'api/helpers/pipe.md' - - Preferences: - - Base: 'api/helpers/preference_representations/base.md' - - Profiling: 'api/helpers/profiling.md' - - Search: - - Generic: 'api/helpers/search/generic.md' - - Models: 'api/helpers/search/models.md' - - Serializers: 'api/helpers/serializers.md' - - Storage: - - GenericStorage: 'api/helpers/storage/generic_storage.md' - - Backends: - - Base: 'api/helpers/storage/backends/base.md' - - Sqlite: 'api/helpers/storage/backends/sqlite.md' - - Sym Link: 'api/helpers/sym_link.md' - - Transaction: - - Base: 'api/helpers/transaction/base.md' - - Win32: 'api/helpers/win32.md' - - YamlUtils: 'api/helpers/yaml_utils.md' + - ACN: + - Agent Record: 'api/helpers/acn/agent_record.md' + - URI: 'api/helpers/acn/uri.md' + - Async Friendly Queue: 'api/helpers/async_friendly_queue.md' + - Async Utils: 'api/helpers/async_utils.md' + - Base: 'api/helpers/base.md' + - Constants: 'api/helpers/constants.md' + - Env Vars: 'api/helpers/env_vars.md' + - Exception Policy: 'api/helpers/exception_policy.md' + - Exec Timeout: 'api/helpers/exec_timeout.md' + - File IO: 'api/helpers/file_io.md' + - File Lock: 'api/helpers/file_lock.md' + - HttpRequests: 'api/helpers/http_requests.md' + - Install Dependency: 'api/helpers/install_dependency.md' + - IO: 'api/helpers/io.md' + - IPFS: + - Base: 'api/helpers/ipfs/base.md' + - Utils: 'api/helpers/ipfs/utils.md' + - Logging: 'api/helpers/logging.md' + - MultiAddress: + - Base: 'api/helpers/multiaddr/base.md' + - MultipleExecutor: 'api/helpers/multiple_executor.md' + - Pipe: 'api/helpers/pipe.md' + - Preferences: + - Base: 'api/helpers/preference_representations/base.md' + - Profiling: 'api/helpers/profiling.md' + - Search: + - Generic: 'api/helpers/search/generic.md' + - Models: 'api/helpers/search/models.md' + - Serializers: 'api/helpers/serializers.md' + - Storage: + - GenericStorage: 'api/helpers/storage/generic_storage.md' + - Backends: + - Base: 'api/helpers/storage/backends/base.md' + - Sqlite: 'api/helpers/storage/backends/sqlite.md' + - Sym Link: 'api/helpers/sym_link.md' + - Transaction: + - Base: 'api/helpers/transaction/base.md' + - Win32: 'api/helpers/win32.md' + - YamlUtils: 'api/helpers/yaml_utils.md' - Identity: 'api/identity/base.md' - Mail: 'api/mail/base.md' - Manager: - - Manager: 'api/manager/manager.md' - - Project: 'api/manager/project.md' - - Utils: 'api/manager/utils.md' + - Manager: 'api/manager/manager.md' + - Project: 'api/manager/project.md' + - Utils: 'api/manager/utils.md' - Protocols: - - Base: 'api/protocols/base.md' - - Dialogue: - - Base: 'api/protocols/dialogue/base.md' - - Generator: - - Base: 'api/protocols/generator/base.md' - - Common: 'api/protocols/generator/common.md' - - Extract Specification: 'api/protocols/generator/extract_specification.md' - - Validate: 'api/protocols/generator/validate.md' - - Default Protocol: - - Custom Types: 'api/protocols/default/custom_types.md' - - Dialogues: 'api/protocols/default/dialogues.md' - - Message: 'api/protocols/default/message.md' - - Serialization: 'api/protocols/default/serialization.md' - - Signing Protocol: - - Custom Types: 'api/protocols/signing/custom_types.md' - - Dialogues: 'api/protocols/signing/dialogues.md' - - Message: 'api/protocols/signing/message.md' - - Serialization: 'api/protocols/signing/serialization.md' - - State Update Protocol: - - Dialogues: 'api/protocols/state_update/dialogues.md' - - Message: 'api/protocols/state_update/message.md' - - Serialization: 'api/protocols/state_update/serialization.md' + - Base: 'api/protocols/base.md' + - Dialogue: + - Base: 'api/protocols/dialogue/base.md' + - Generator: + - Base: 'api/protocols/generator/base.md' + - Common: 'api/protocols/generator/common.md' + - Extract Specification: 'api/protocols/generator/extract_specification.md' + - Validate: 'api/protocols/generator/validate.md' + - Default Protocol: + - Custom Types: 'api/protocols/default/custom_types.md' + - Dialogues: 'api/protocols/default/dialogues.md' + - Message: 'api/protocols/default/message.md' + - Serialization: 'api/protocols/default/serialization.md' + - Signing Protocol: + - Custom Types: 'api/protocols/signing/custom_types.md' + - Dialogues: 'api/protocols/signing/dialogues.md' + - Message: 'api/protocols/signing/message.md' + - Serialization: 'api/protocols/signing/serialization.md' + - State Update Protocol: + - Dialogues: 'api/protocols/state_update/dialogues.md' + - Message: 'api/protocols/state_update/message.md' + - Serialization: 'api/protocols/state_update/serialization.md' - Registries: - - Base: 'api/registries/base.md' - - Filter: 'api/registries/filter.md' - - Resources: 'api/registries/resources.md' + - Base: 'api/registries/base.md' + - Filter: 'api/registries/filter.md' + - Resources: 'api/registries/resources.md' - Skills: - - Base: 'api/skills/base.md' - - Behaviors: 'api/skills/behaviours.md' - - Task: 'api/skills/tasks.md' + - Base: 'api/skills/base.md' + - Behaviors: 'api/skills/behaviours.md' + - Task: 'api/skills/tasks.md' - Test Tools: - - Constants: 'api/test_tools/constants.md' - - Exceptions: 'api/test_tools/exceptions.md' - - Generic: 'api/test_tools/generic.md' - - Test Cases: 'api/test_tools/test_cases.md' - - Test Contract: 'api/test_tools/test_contract.md' - - Test Skill: 'api/test_tools/test_skill.md' + - Constants: 'api/test_tools/constants.md' + - Exceptions: 'api/test_tools/exceptions.md' + - Generic: 'api/test_tools/generic.md' + - Test Cases: 'api/test_tools/test_cases.md' + - Test Contract: 'api/test_tools/test_contract.md' + - Test Skill: 'api/test_tools/test_skill.md' - Plugins: - - CLI: - - IPFS: - - API: 'api/plugins/aea_cli_ipfs/core.md' - - Utils: 'api/plugins/aea_cli_ipfs/ipfs_utils.md' - - Ledger: - - Cosmos: - - API: 'api/plugins/aea_ledger_cosmos/cosmos.md' - - Ethereum: - - API: 'api/plugins/aea_ledger_ethereum/ethereum.md' - - Fetchai: - - API: 'api/plugins/aea_ledger_fetchai/fetchai.md' - - Helper: 'api/plugins/aea_ledger_fetchai/_cosmos.md' - - Development - Use Case: - - Generic skills: 'generic-skills.md' - - Front-end integration: 'connect-a-frontend.md' - - HTTP Connection: 'http-connection-and-skill.md' - - ORM integration: 'orm-integration.md' - - Contract deploy and interact: 'erc1155-skills.md' - - P2P Connection: 'p2p-connection.md' - - Build an AEA on a Raspberry Pi: 'raspberry-set-up.md' + - CLI: + - IPFS: + - API: 'api/plugins/aea_cli_ipfs/core.md' + - Utils: 'api/plugins/aea_cli_ipfs/ipfs_utils.md' + - Ledger: + - Cosmos: + - API: 'api/plugins/aea_ledger_cosmos/cosmos.md' + - Ethereum: + - API: 'api/plugins/aea_ledger_ethereum/ethereum.md' + - Fetchai: + - API: 'api/plugins/aea_ledger_fetchai/fetchai.md' + - Helper: 'api/plugins/aea_ledger_fetchai/_cosmos.md' + - Limitations of v1: 'limits.md' + - Known limitations: 'known-limits.md' - Glossary: 'glossary.md' - Q&A: 'questions-and-answers.md' - Archives: @@ -273,7 +284,13 @@ theme: features: - navigation.instant # Fast page loading - navigation.tracking # URL automatically updated with the currently active anchor +# - navigation.tabs +# - navigation.tabs.sticky +# - navigation.sections +# - navigation.expand +# - navigation.indexes - navigation.top # Back-to-top button + - navigation.footer # Add links to the previous and next page of the current page - search.suggest # Completion for the searched word (can be accepted with ->). - search.highlight # Highlight all occurrences after following a search result link - search.share # Show share button for copying deep link to the current search query and result @@ -284,6 +301,7 @@ theme: extra_css: - css/my-styles.css + - css/admonitions.css markdown_extensions: - admonition # Required by admonitions @@ -305,6 +323,7 @@ markdown_extensions: - tables # # Required by tables - toc: permalink: true + - def_list plugins: - search # Enables search diff --git a/pyproject.toml b/pyproject.toml index 195f9a20d9..db8f66f358 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,6 +11,9 @@ authors = ["Fetch.AI Limited"] readme = "README.md" license = "Apache-2.0" homepage = "https://github.com/fetchai/agents-aea" +repository = "https://github.com/fetchai/agents-aea" +documentation = "https://docs.fetch.ai/aea/" +keywords = ["agent", "aea", "autonomous", "economic", "autonomous economic agent"] classifiers = [ "Environment :: Console", "Development Status :: 4 - Beta", diff --git a/scripts/check_doc_links.py b/scripts/check_doc_links.py index 12dd7fe4e4..3a530b44ff 100755 --- a/scripts/check_doc_links.py +++ b/scripts/check_doc_links.py @@ -184,7 +184,7 @@ def _checks_image(file: Path, regex: Pattern = IMAGE_PATTERN) -> None: :param file: the file path :param regex: the regex to check for in the file. """ - if file == Path("docs/version.md"): + if file in [Path("docs/version.md"), Path("docs/install.md")]: return matches = regex.finditer(file.read_text()) for match in matches: diff --git a/scripts/install.sh b/scripts/install.sh index e37e225031..10a2016a63 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -27,9 +27,9 @@ function is_python_version_ok() { if which python3 2>&1 >/dev/null; then version=`python3 -V 2>/dev/null` - if [[ -z `echo $version|grep -E 'Python 3\.[(6789]\.[0-9]+'` ]]; + if [[ -z `echo $version|grep -E 'Python 3\.([(89]|10)\.[0-9]+'` ]]; then - echo "Python3 version: ${version} is not supported. Supported versions are 3.6, 3.7, 3.8." + echo "Python3 version: ${version} is not supported. Supported versions are 3.8, 3.9, and 3.10." return 1 fi return 0 @@ -42,7 +42,7 @@ function is_python_version_ok() { function install_aea (){ echo "Install AEA" - output=$(pip3 install --user aea[all]==1.1.1 --force --no-cache-dir) + output=$(pip3 install --user aea[all]==1.2.5 --force --no-cache-dir) if [[ $? -ne 0 ]]; then echo "$output" @@ -70,7 +70,7 @@ function install_aea (){ function install_ubuntu_deps(){ # always install it cause python3-dev can be missing! also it's not consuming much time. echo "Install python3 and dependencies" - output=$(sudo bash -c "apt update && apt install python3 python3-pip python3-dev -y" 2>&1) + output=$(sudo bash -c "apt update && apt install python3 python3-pip python3-dev -y" 2>&1) if [[ $? -ne 0 ]]; then echo "$output" @@ -100,7 +100,7 @@ function ensure_brew(){ output=`which brew` if [[ $? -ne 0 ]]; then - echo "Installing homebrew. Please pay attention, it can ask for the password and aggree to install xcode tools." + echo "Installing homebrew. Please pay attention, it can ask for the password and agree to install xcode tools." /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" if [[ $? -eq 0 ]]; then diff --git a/tests/test_docs/test_bash_yaml/md_files/bash-cli-how-to.md b/tests/test_docs/test_bash_yaml/md_files/bash-cli-how-to.md deleted file mode 100644 index b705c5edd0..0000000000 --- a/tests/test_docs/test_bash_yaml/md_files/bash-cli-how-to.md +++ /dev/null @@ -1,19 +0,0 @@ -``` bash -pip install aea[cli] -``` - -``` bash -pip install aea[all] -``` - -``` bash -pip install aea[all] --force --no-cache-dir -``` - -``` bash -aea -``` - -``` bash -python -m aea.cli -``` diff --git a/tests/test_docs/test_bash_yaml/md_files/bash-oef-ledger.md b/tests/test_docs/test_bash_yaml/md_files/bash-oef-ledger.md deleted file mode 100644 index dcdb2c0f81..0000000000 --- a/tests/test_docs/test_bash_yaml/md_files/bash-oef-ledger.md +++ /dev/null @@ -1,8 +0,0 @@ -``` bash -python scripts/oef/launch.py -c ./scripts/oef/launch_config.json -``` - -``` bash -svn export https://github.com/fetchai/agents-aea.git/trunk/examples -svn export https://github.com/fetchai/agents-aea.git/trunk/scripts -``` diff --git a/tests/test_docs/test_bash_yaml/md_files/bash-version.md b/tests/test_docs/test_bash_yaml/md_files/bash-version.md deleted file mode 100644 index 11f7e1aef0..0000000000 --- a/tests/test_docs/test_bash_yaml/md_files/bash-version.md +++ /dev/null @@ -1,3 +0,0 @@ -``` bash -aea --version -``` diff --git a/tests/test_docs/test_quickstart.py b/tests/test_docs/test_quickstart.py index 05a19616bb..7c3f4c8dfc 100644 --- a/tests/test_docs/test_quickstart.py +++ b/tests/test_docs/test_quickstart.py @@ -20,6 +20,8 @@ """This module contains the tests for the content of quickstart.md file.""" from pathlib import Path +import pytest + from packages.fetchai.protocols.default.message import DefaultMessage from tests.conftest import ROOT_DIR @@ -32,6 +34,7 @@ class TestQuickstartTest(BasePythonMarkdownDocs): DOC_PATH = Path(ROOT_DIR, "docs", "quickstart.md") +@pytest.mark.skip def test_correct_echo_string(): """Test the echo string in the quickstart is using the correct protocol specification id.""" file_path = Path(ROOT_DIR, "docs", "quickstart.md")