#369 - Make it easy to deploy manage multiple predictoor bots

.gitignore

@@ -173,3 +173,7 @@ parquet_data/
 
 # pdr_backend accuracy output
 pdr_backend/accuracy/output/*.json
+
+# agent deployer
+.keys.json
+.deployments/

READMEs/agent-deployer.md

@@ -0,0 +1,180 @@
+# Agent Deployment Tool
+
+`deployer` is a streamlined command-line utility designed for efficiently generating and managing Predictoor agent deployments.
+
+## Usage
+
+### Agent Configurations
+Firstly, you need to set up your agents configuration. This is done by creating a config entry under `deployment_configs` in `ppss.yaml` file. 
+
+Here is an example structure for your reference:
+
+```yaml
+deployment_configs:
+  testnet_predictoor_deployment:
+    cpu: '1'
+    memory: '512Mi'
+    source: "binance"
+    type: "predictoor"
+    approach: 3
+    network: "sapphire-testnet"
+    s_until_epoch_end: 20
+    pdr_backend_image_source: "oceanprotocol/pdr-backend:latest"
+    agents:
+      - pair: 'BTC/USDT'
+        stake_amt: 15
+        timeframe: 5m
+        approach: 1
+      - pair: 'ETH/USDT'
+        stake_amt: 20
+        timeframe: 1h
+        s_until_epoch_end: 60
+```
+
+*Tip: Specific agent settings (like source, timeframe) will override general settings if provided.*
+
+### Private Keys
+
+Create a `.keys.json` file and format it as follows:
+```
+{
+    "config_name": ["pk1", "pk2"...]
+}
+```
+
+*Note: If you have fewer private keys than number of agents, the tool will create new wallets and update the .keys.json file.*
+
+### Generate Templates
+
+The `generate` command is used to create deployment template files based on a configuration file.
+
+```
+pdr deployer generate <config_path> <config_name> <deployment_method> <output_dir>
+```
+
+- `<config_path>`: Path to the yaml config file.
+- `<config_name>`: Name of the config.
+- `<deployment_method>`: Method of deployment (choices: "k8s").
+- `<output_dir>`: Output directory for the generated files.
+
+Take a note of the `config_name`, you will need it later!
+
+### Deploy Config
+
+The `deploy` command is used to deploy agents based on a specified config name.
+
+```
+pdr deployer deploy <config_name> [-p PROVIDER] [-r REGION] [--project_id PROJECT_ID] [--resource_group RESOURCE_GROUP] [--subscription_id SUBSCRIPTION_ID]
+```
+
+- `<config_name>`: Name of the config.
+- -p, --provider: Cloud provider (optional, choices: "aws", "azure", "gcp"). (optional)
+- -r, --region: Deployment zone/region (optional).
+- --project_id: Google Cloud project id (optional).
+- --resource_group: Azure resource group (optional).
+- --subscription_id: Azure subscription id (optional).
+
+### Destroy Config
+
+The `destroy` command is used to destroy agents deployed based on a specified configuration.
+
+```
+pdr deployer destroy <config_name> [-p PROVIDER]
+```
+
+- `<config_name>`: Name of the config.
+- -p, --provider: Cloud provider (optional, choices: "aws", "azure", "gcp"). (optional)
+
+### Logs
+
+The `logs` command is used to retrieve logs from deployed agents.
+
+```
+pdr deployer logs <config_name> [-p PROVIDER]
+```
+
+- `<config_name>`: Name of the config.
+- -p, --provider: Cloud provider (optional, choices: "aws", "azure", "gcp"). (optional)
+
+
+### Remote Container Registry
+
+The `registry` command is used to manage remote registries for agent deployment.
+
+```
+pdr deployer registry <action> <registry_name> [-p PROVIDER] [-r REGION] [--project_id PROJECT_ID] [--resource_group RESOURCE_GROUP]
+```
+
+- `<action>`: Action (choices: "deploy", "destroy", "auth", "url").
+- `<registry_name>`: Registry name.
+- -p, --provider: Cloud provider (optional, choices: "aws", "azure", "gcp").
+- -r, --region: Deployment zone/region (optional).
+- --project_id: Google Cloud project id (optional).
+- --resource_group: Azure resource group (optional).
+
+
+### Build
+
+The build command is used to build a container image.
+
+```
+pdr deployer build <image_name> <image_tag>
+```
+
+- `<image_name>`: Image name (default: "pdr_backend").
+- `<image_tag>`: Image tag (default: "deployer").
+
+
+#### Push
+
+The `push` command is used to push container images to a remote registry.
+
+```
+pdr deployer push <registry_name> [<image_name>] [<image_tag>]
+```
+
+- `<registry_name>`: Registry name.
+- `<image_name>`: Image name (default: "pdr_backend").
+- `<image_tag>`: Image tag (default: "deployer").
+
+
+## Examples
+
+### K8S with GCP
+
+Outputs are truncated for brevity.
+
+```shell
+$ pdr deployer generate ppss.yaml predictoors_cluster k8s ./predictoors_approach3
+Generated k8s templates for predictoors_cluster
+  Output path: ./predictoor_approach3
+  Config name: predictoors_cluster
+  Deployment method: k8s
+  Number of agents: 2
+To deploy: pdr deployer deploy predictoors_cluster
+```
+
+```shell
+$ pdr deployer deploy predictoors_cluster -p gcp -r europe-west2 --project_id id_goes_here
+Deploying predictoors_cluster...
+Authenticating to Kubernetes cluster...
+Fetching cluster endpoint and auth data.
+kubeconfig entry generated for predictoors_cluster.
+Cluster is ready, deploying the agents...
+namespace/predictoors_cluster created
+deployment.apps/pdr-predictoor1-3-btc-usdt-5m-binance created
+deployment.apps/pdr-predictoor2-3-eth-usdt-5m-binance created
+```
+
+```shell
+$ pdr deployer logs predictoors_cluster
+Getting logs for predictoors_cluster...
+Getting cluster logs...
+NAME                                                     READY   STATUS    RESTARTS   AGE
+pdr-predictoor1-3-btc-usdt-5m-binance-1294c5aa3-fjc65    1/1     Running   0          91s
+pdr-predictoor2-3-eth-usdt-5m-binance-21dfcf3bc4-b6nnk   1/1     Running   0          91s
+-> Submit predict tx result: success.
+====================================================================================================================================================================================
+cur_epoch=5688716, cur_block_number=4658908, cur_timestamp=1706615099, next_slot=1706615100, target_slot=1706615400. 295 s left in epoch (predict if <= 30 s left). s_per_epoch=300
+...
+```

READMEs/predictoor.md

@@ -7,17 +7,28 @@ SPDX-License-Identifier: Apache-2.0
 
 This README shows how to earn $ by running a predictoor bot on mainnet.
 
-1. **[Install](#install-pdr-backend-repo)**
-1. **[Simulate modeling & trading](#simulate-modeling-and-trading)**
-1. **[Run bot on testnet](#run-predictoor-bot-on-sapphire-testnet)**
-1. **[Run bot on mainnet](#run-predictoor-bot-on-sapphire-mainnet)**
-1. **[Claim payout](#claim-payout)**
-1. **[Check performance](#check-performance)**
+
+
+1. **[Install](#1-install-pdr-backend-repo)**
+1. **[Simulate modeling & trading](#2-simulate-modeling-and-trading)**
+1. **[Run bot on testnet](#3-run-predictoor-bot-on-sapphire-testnet)**
+1. **[Run bot on mainnet](#4-run-predictoor-bot-on-sapphire-mainnet)**
+1. **[Claim payout](#5-claim-payout)**
+1. **[Go Beyond](#6-go-beyond)**
+    1. [Optimize Model](#61-optimize-model)
+    1. [Run Many Bots at Once](#62-run-many-bots-at-once)
+          1. [Private Keys](#621-private-keys)
+          1. [Generate Deployment Templates](#622-generate-deployment-templates)
+          1. [Deploy](#623-deploy)
+          1. [Monitoring logs](#624-monitoring-logs)
+          1. [Destroy](#625-destroy)
+    1. [Run Local Network](#63-run-local-network)
+    1. [Other READMEs](#64-other-readmes)
 
 Then, you can [go beyond](#go-beyond): [optimize model](#optimize-model), [run >1 bots](#run-many-bots-at-once), and more.
 
 
-## Install pdr-backend Repo
+## 1. Install pdr-backend Repo
 
 In a new console:
 
@@ -42,7 +53,7 @@ If you're running MacOS, then in console:
 codesign --force --deep --sign - venv/sapphirepy_bin/sapphirewrapper-arm64.dylib
 ```
 
-## Simulate Modeling and Trading
+## 2. Simulate Modeling and Trading
 
 Simulation allows us to quickly build intuition, and assess the performance of the data / predicting / trading strategy (backtest).
 
@@ -70,7 +81,7 @@ The baseline settings use a linear model inputting prices of the previous 10 epo
 
 Profit isn't guaranteed: fees, slippage and more eats into them. Model accuracy makes a big difference too.
 
-## Run Predictoor Bot on Sapphire Testnet
+## 3. Run Predictoor Bot on Sapphire Testnet
 
 Predictoor contracts run on [Oasis Sapphire](https://docs.oasis.io/dapp/sapphire/) testnet and mainnet. Sapphire is a privacy-preserving EVM-compatible L1 chain.
 
@@ -99,7 +110,7 @@ The CLI has a tool to track performance. Type `pdr get_predictoor_info -h` for d
 You can track behavior at finer resolution by writing more logs to the [code](../pdr_backend/predictoor/approach3/predictoor_agent3.py), or [querying Predictoor subgraph](subgraph.md).
 
 
-## Run Predictoor Bot on Sapphire Mainnet
+## 4. Run Predictoor Bot on Sapphire Mainnet
 
 Time to make it real: let's get our bot running on Sapphire _mainnet_.
 
@@ -121,36 +132,127 @@ This is where there's real $ at stake. Good luck!
 
 Track performance, as in testnet.
 
-## Claim Payout
+## 5. Claim Payout
 
 When running predictoors on mainnet, you have the potential to earn $.
 
 **[Here](payout.md)** are instructions to claim your earnings.
 
 
-# Go Beyond
+# 6. Go Beyond
 
 You've gone through all the essential steps to earn $ by running a predictoor bot on mainnet.
 
 The next sections describe how to go beyond, by optimizing the model and more.
 
-## Optimize Model
+## 6.1 Optimize Model
 
 Once you're familiar with the above, you can make your own model and optimize it for $. Here's how:
 1. Fork `pdr-backend` repo.
 1. Change predictoor approach3 modeling code as you wish, while iterating with simulation.
 1. Bring your model as a Predictoor bot to testnet then mainnet.
 
 
-## Run Bots Remotely
+## 6.2 Run Many Bots at Once
+
+`deployer` is a streamlined command-line utility designed for efficiently generating and managing agent deployments.
+
+This section shows how to use `deployer` to deploy bots on testnet.
+
+The config that will be deployed can be found in `ppss.yaml` under `deployment_configs` section. You can create your own config by copying the existing one and modifying it as you wish. For the sake of this example, the existing config will be used.
+
+`ppss.yaml`:
+```yaml
+deployment_configs:
+  testnet_predictoor_deployment:
+    cpu: '1'
+    memory: '512Mi'
+    source: "binance"
+    type: "predictoor"
+    approach: 3
+    network: "sapphire-testnet"
+    s_until_epoch_end: 20
+    pdr_backend_image_source: "oceanprotocol/pdr-backend:latest"
+    agents:
+      - pair: 'BTC/USDT'
+        stake_amt: 0.1
+        timeframe: 5m
+        approach: 1
+      - pair: 'ETH/USDT'
+        stake_amt: 1
+        timeframe: 1h
+        s_until_epoch_end: 100
+```
+
+### 6.2.1. Private Keys
+Create a `.keys.json` file and add the following:
+```
+{
+    "testnet_predictoor_deployment": ["pk1", "pk2"]
+}
+```
+
+Each agent requires a private key. If you have fewer private keys than number of agents, the tool will create new wallets and update the `.keys.json` file. Make sure the wallets have enough ROSE and OCEAN to pay for gas and stake.
+
+
+### 6.2.2. Generate Deployment Templates
+
+The `generate` command is used to create deployment template files based on a configuration file.
+
+Execute the following command to generate the deployment templates:
+```
+pdr deployer generate ppss.yaml testnet_predictoor_deployment k8s testnet_deployments
+```
+
+Where `ppss.yaml` is the config file, `testnet_predictoor_deployment` is the config name, `k8s` is the deployment method, and `testnet_deployments` is the output directory for the generated files.
+
+Available deployment methods are `k8s`.
+
+### 6.2.3. Deploy
+
+The `deploy` command is used to deploy the generated templates.
+
+Execute the following command to deploy the generated config:
+```
+pdr deployer deploy testnet_predictoor_deployment -p gcp -r europe-west2 --project-id
+```
+
+Where `testnet_predictoor_deployment` is the config name.
+
+Since k8s is used as the deployment method, the following additional parameters are required:
+- `-p` or `--provider`: The cloud provider to use. Available options are `gcp`, `aws`, and `azure`.
+- `-r` or `--region`: The region to deploy to.
+- `--project-id`: The cloud provider project id. Only required for GCP.
+- `--resource-group`: The cloud provider resource group. Only required Azure.
+- `--subscription-id`: The cloud provider subscription id. Only required for Azure.
+
+### 6.2.4 Monitoring logs
+
+The `logs` command is used to retrieve logs from deployed agents.
+
+Execute the following command to retrieve logs from the deployed agents:
+```
+pdr deployer logs testnet_predictoor_deployment
+```
+
+Where `testnet_predictoor_deployment` is the config name.
+
+### 6.2.5 Destroy
+
+The `destroy` command is used to destroy agents deployed based on a specified configuration.
+
+Execute the following command to destroy the deployed agents:
+```
+pdr deployer destroy testnet_predictoor_deployment
+```
 
-To scale up compute or run without tying up your local machine, you can run bots remotely. Get started [here](remotebot.md).
+Where `testnet_predictoor_deployment` is the config name.
 
-## Run Local Network
+## 6.3 Run Local Network
 
 To get extra-fast block iterations, you can run a local test network (with local bots). It does take a bit more up-front setup. Get started [here](barge.md).
 
-## Other READMEs
+## 6.4 Other READMEs
 
 - [Root README](../README.md)