Fix/installation and eval

README.md

@@ -220,27 +220,34 @@ We want to provide a framework for RL algorithms that is at the same time simple
 
 Moreover, in many RL repositories, the RL algorithm is tightly coupled with the environment, making it harder to extend them beyond the gym interface. We want to provide a framework that allows to easily decouple the RL algorithm from the environment, so that it can be used with any environment.
 
-## How to use
+## How to use it
 
-Two options exist for using SheepRL. One can either clone the repo and install the local version, or one can pip install the framework using the GitHub clone URL. Instructions for both methods are shown below.
+### Installation
+
+Three options exist for installing SheepRL
+
+1. Install the latest version directly from the [PyPi index](https://pypi.org/project/sheeprl/)
+2. Clone the repo and install the local version
+3. pip-install the framework using the GitHub clone URL
+
+Instructions for the three methods are shown below.
+
+#### Install SheepRL from PyPi
 
-<details>
-  <summary>Cloning and installing the lastest version from PyPi</summary>
 
 You can install the latest version of SheepRL with
 
 ```bash
 pip install sheeprl
 ```
 
+> [!NOTE]
+> 
 > To install optional dependencies one can run for example `pip install sheeprl[atari,box2d,dev,mujoco,test]`
 
 For a detailed information about all the optional dependencies you can install please have a look at the [What](#what) section
 
-</details>
-
-<details>
-  <summary>Cloning and installing a local version</summary>
+#### Cloning and installing a local version
 
 First, clone the repo with:
 
@@ -255,12 +262,11 @@ From inside the newly created folder run
 pip install .
 ```
 
-> To install all the optional dependencies one can run `pip install .[atari,mujoco,dev,test]`
-
-</details>
+> [!NOTE]
+> 
+> To install optional dependencies one can run for example `pip install .[atari,box2d,dev,mujoco,test]`
 
-<details>
-  <summary>Installing the framework from the GitHub repo</summary>
+#### Installing the framework from the GitHub repo
 
 If you haven't already done so, create an environment with your choice of venv or conda.
 
@@ -269,33 +275,41 @@ If you haven't already done so, create an environment with your choice of venv o
 ```sh
 # create a virtual environment
 python3 -m venv .venv
+
 # activate the environment
 source .venv/bin/activate
+
 # if you do not wish to install extras such as mujuco, atari do
 pip install "sheeprl @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
+
 # or, to install with atari and mujuco environment support, do
 pip install "sheeprl[atari,mujoco,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
+
 # or, to install with box2d environment support, do
 pip install swig
 pip install "sheeprl[box2d] @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
+
 # or, to install with minedojo environment support, do
 pip install "sheeprl[minedojo,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
+
 # or, to install with minerl environment support, do
 pip install "sheeprl[minerl,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
+
 # or, to install with diambra environment support, do
 pip install "sheeprl[diambra,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
+
 # or, to install with super mario bros environment support, do
 pip install "sheeprl[supermario,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
+
 # or, to install all extras, do
 pip install swig
 pip install "sheeprl[box2d,atari,mujoco,minerl,supermario,dev,test] @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
 ```
 
-</details>
-
-<details>
-  <summary>Installing on an M-series Mac</summary>
+#### Additional: installing on an M-series Mac
 
+> [!CAUTION]
+> 
 > If you are on an M-series Mac and encounter an error attributed box2dpy during installation, you need to install SWIG using the instructions shown below.
 
 
@@ -304,37 +318,54 @@ It is recommended to use [homebrew](https://brew.sh/) to install [SWIG](https://
 ```sh
 # if needed install homebrew
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
 # then, do
 brew install swig
+
 # then attempt to pip install with the preferred method, such as
 pip install "sheeprl[atari,box2d,mujoco,dev,test] @ git+https://github.com/Eclectic-Sheep/sheeprl.git"
 ```
 
-</details>
-
-<details>
-  <summary>MineRL and MineDojo</summary>
+#### Additional: MineRL and MineDojo
 
+> [!NOTE]
+> 
 > If you want to install the *minedojo* or *minerl* environment support, Java JDK 8 is required: you can install it by following the instructions at this [link](https://docs.minedojo.org/sections/getting_started/install.html#on-ubuntu-20-04).
+
+> [!CAUTION]
 >
-> **MineRL** and **MineDojo** environments have **conflicting requirements**, so **DO NOT install them together** with the `pip install -e .[minerl,minedojo]` command, but instead **install them individually** with either the command `pip install -e .[minerl]` or `pip install -e .[minedojo]` before running an experiment with the MineRL or MineDojo environment, respectively.
+> **MineRL** and **MineDojo** environments have **conflicting requirements**, so **DO NOT install them together** with the `pip install sheeprl[minerl,minedojo]` command, but instead **install them individually** with either the command `pip install sheeprl[minerl]` or `pip install sheeprl[minedojo]` before running an experiment with the MineRL or MineDojo environment, respectively. 
 
-</details>  
+### Run an experiment with SheepRL
 
 Now you can use one of the already available algorithms, or create your own.
-
 For example, to train a PPO agent on the CartPole environment with only vector-like observations, just run
 
 ```bash
 python sheeprl.py exp=ppo env=gym env.id=CartPole-v1
 ```
 
-You check all the available algorithms with
+if you have installed from a cloned repo, or
+
+```bash
+sheeprl exp=ppo env=gym env.id=CartPole-v1
+```
+
+if you have installed SheepRL from PyPi.
+
+Similarly, you check all the available algorithms with
 
 ```bash
 python sheeprl/available_agents.py
 ```
 
+if you have installed from a cloned repo, or
+
+```bash
+sheeprl-agents
+```
+if you have installed SheepRL from PyPi.
+
 That's all it takes to train an agent with SheepRL! 🎉
 
 > Before you start using the SheepRL framework, it is **highly recommended** that you read the following instructional documents:
@@ -363,7 +394,7 @@ What you run is the PPO algorithm with the default configuration. But you can al
 For example, in the default configuration, the number of parallel environments is 4. Let's try to change it to 8 by passing the `--num_envs` argument:
 
 ```bash
-python sheeprl.py exp=ppo env=gym env.id=CartPole-v1 env.num_envs=8
+sheeprl exp=ppo env=gym env.id=CartPole-v1 env.num_envs=8
 ```
 
 All the available arguments, with their descriptions, are listed in the `sheeprl/config` directory. You can find more information about the hierarchy of configs [here](./howto/run_experiments.md).
@@ -373,7 +404,7 @@ All the available arguments, with their descriptions, are listed in the `sheeprl
 To run the algorithm with Lightning Fabric, you need to specify the Fabric parameters through the CLI. For example, to run the PPO algorithm with 4 parallel environments on 2 nodes, you can run:
 
 ```bash
-python sheeprl.py fabric.accelerator=cpu fabric.strategy=ddp fabric.devices=2 exp=ppo env=gym env.id=CartPole-v1
+sheeprl fabric.accelerator=cpu fabric.strategy=ddp fabric.devices=2 exp=ppo env=gym env.id=CartPole-v1
 ```
 
 You can check the available parameters for Lightning Fabric [here](https://lightning.ai/docs/fabric/stable/api/fabric_args.html).
@@ -383,7 +414,7 @@ You can check the available parameters for Lightning Fabric [here](https://light
 You can easily evaluate your trained agents from checkpoints: training configurations are retrieved automatically.
 
 ```bash
-python sheeprl_eval.py checkpoint_path=/path/to/checkpoint.ckpt fabric.accelerator=gpu env.capture_video=True
+sheeprl-eval checkpoint_path=/path/to/checkpoint.ckpt fabric.accelerator=gpu env.capture_video=True
 ```
 
 For more information, check the corresponding [howto](./howto/eval_your_agent.md).

howto/model_manager.md

@@ -56,8 +56,9 @@ If you do not want to log some models, then, you just need to remove it from the
 > Make sure that the models specified in the configuration file are a subset of the models defined by the `MODELS_TO_REGISTER` variable.
 
 ## Register models from checkpoints
-Another possibility is to register the models after the training, by manually selecting the checkpoint where to retrieve the agent. To do this, it is possible to run the `sheeprl_model_manager.py` script by properly specifying the `checkpoint_path`, the `model_manager`, and the MLFlow-related configurations.
+Another possibility is to register the models after the training, by manually selecting the checkpoint where to retrieve the agent. To do this, it is possible to run the `sheeprl_model_manager.py` script (or directly `sheeprl-registration`) by properly specifying the `checkpoint_path`, the `model_manager`, and the MLFlow-related configurations.
 The default configurations are defined in the `./sheeprl/configs/model_manager_config.yaml` file, that is reported below:
+
 ```yaml
 # ./sheeprl/configs/model_manager_config.yaml
 
@@ -98,6 +99,14 @@ For instance, you can register the DreamerV3 models from a checkpoint with the f
 python sheeprl_model_manager.py model_manager=dreamer_v3 checkpoint_path=/path/to/checkpoint.ckpt
 ```
 
+if you have installed SheepRL from a cloned repo, or
+
+```bash
+sheeprl-registration model_manager=dreamer_v3 checkpoint_path=/path/to/checkpoint.ckpt
+```
+
+if you have installed SheepRL from PyPi.
+
 ## Delete, Transition and Download Models
 The MLFlow model manager enables the deletion of the registered models, moving them from one stage to another or downloading them.
 [This notebook](../examples/model_manager.ipynb) contains a tutorial on how to use the MLFlow model manager. We recommend taking a look to see what APIs the model manager makes available.

pyproject.toml

@@ -55,6 +55,9 @@ readme = {file = ["docs/README.md"], content-type = "text/markdown"}
 
 [project.scripts]
 sheeprl = "sheeprl.cli:run"
+sheeprl-eval = "sheeprl.cli:evaluation"
+sheeprl-agents = "sheeprl.available_agents:available_agents"
+sheeprl-registration = "sheeprl.cli:registration"
 
 [project.urls]
 homepage = "https://eclecticsheep.ai"

sheeprl/available_agents.py

@@ -1,18 +1,17 @@
-if __name__ == "__main__":
-    from rich.console import Console
-    from rich.table import Table
+from rich.console import Console
+from rich.table import Table
+
+from sheeprl.utils.registry import algorithm_registry, evaluation_registry
 
-    from sheeprl.utils.registry import algorithm_registry, evaluation_registry
 
+def available_agents():
     table = Table(title="SheepRL Agents")
     table.add_column("Module")
     table.add_column("Algorithm")
     table.add_column("Entrypoint")
     table.add_column("Decoupled")
     table.add_column("Evaluated by")
 
-    # print(evaluation_registry)
-
     for module, implementations in algorithm_registry.items():
         for algo in implementations:
             evaluated_by = "Undefined"
@@ -33,3 +32,7 @@
 
     console = Console()
     console.print(table)
+
+
+if __name__ == "__main__":
+    available_agents()

sheeprl/cli.py

@@ -325,7 +325,7 @@ def run(cfg: DictConfig):
 @hydra.main(version_base="1.3", config_path="configs", config_name="eval_config")
 def evaluation(cfg: DictConfig):
     # Load the checkpoint configuration
-    checkpoint_path = Path(cfg.checkpoint_path)
+    checkpoint_path = Path(os.path.abspath(cfg.checkpoint_path))
     ckpt_cfg = OmegaConf.load(checkpoint_path.parent.parent / "config.yaml")
     ckpt_cfg.pop("seed", None)
 
@@ -341,6 +341,7 @@ def evaluation(cfg: DictConfig):
             "strategy": "auto",
             "accelerator": getattr(cfg.fabric, "accelerator", "auto"),
         }
+        cfg.root_dir = str(checkpoint_path.parent.parent.parent.parent)
 
         # Merge configs
         ckpt_cfg.merge_with(cfg)