SHARPIE Gallery

Shared Human-AI Reinforcement Learning Platform for Interactive Experiments Gallery

This repository presents use-cases for SHARPIE.

Quick Start

Prerequisites

Activate your Python environment (conda or venv) with SHARPIE installed:

# Using conda
conda activate sharpie

# Or using venv
source /path/to/venv/bin/activate

# Ensure the database is set up and that there is an admin (superuser)
sharpie-web migrate
sharpie-web createsuperuser

Install all use cases

sharpie-install --all --gallery-dir /path/to/SHARPIE_Gallery

Install specific use case

sharpie-install amaze --gallery-dir /path/to/SHARPIE_Gallery                    # Standard output
sharpie-install amaze --gallery-dir /path/to/SHARPIE_Gallery --quiet              # Minimal output (errors only)
sharpie-install amaze --gallery-dir /path/to/SHARPIE_Gallery --verbose            # Detailed output

Custom installation paths

The --gallery-dir flag specifies the path to the SHARPIE Gallery directory. The --sharpie-dir flag can be used to specify the SHARPIE installation directory (defaults to the sharpie package install location):

sharpie-install amaze --gallery-dir /path/to/SHARPIE_Gallery --sharpie-dir /path/to/SHARPIE

List available use cases

sharpie-install --list --gallery-dir /path/to/SHARPIE_Gallery

Validate without installing

sharpie-install amaze --check --gallery-dir /path/to/SHARPIE_Gallery            # Standard output
sharpie-install amaze --check --gallery-dir /path/to/SHARPIE_Gallery --quiet    # Minimal output
sharpie-install amaze --check --gallery-dir /path/to/SHARPIE_Gallery --verbose  # Detailed output
sharpie-install --all --check --gallery-dir /path/to/SHARPIE_Gallery            # Validate all

Available Use Cases

• amaze - Maze navigation with TAMER
• frozen - Frozen lake with TAMER
• mario - Super Mario Bros behavior cloning
• mountain - Mountain car (human-only)
• mountain_tamer - Mountain car with TAMER
• overcooked - Collaborative cooking
• saycan - Language-conditioned robotic manipulation
• smacv2 - StarCraft II multi-agent challenge
• spread - Multi-agent coordination
• tag - Multi-agent pursuit

Interacting with installed use case

Open a terminal window, activate your environment:

# Using conda
conda activate sharpie

# Or using venv
source /path/to/venv/bin/activate
sharpie-web runserver

Simultaneously open a second terminal window and run:

# Using conda
conda activate sharpie

# Or using venv
source /path/to/venv/bin/activate
sharpie-runner runserver --connection-key secret

Open a browser and visit localhost:8000 to see all installed experiments.

Development

Testing

Run validation on all use cases:

sharpie-install --all --check --gallery-dir /path/to/SHARPIE_Gallery

Adding a New Use Case

1. Create directory: my_use_case/
2. Add config.yaml (see existing examples for schema)
3. Add environment.py (must define environment variable)
4. Add policy.py if needed (must define policy variable with class named Policy)
5. Validate: sharpie-install my_use_case --check --gallery-dir /path/to/SHARPIE_Gallery
6. Install: sharpie-install my_use_case --gallery-dir /path/to/SHARPIE_Gallery

Regenerating READMEs

READMEs are generated from config.yaml files:

python generate_readme.py

Configuration Schema

Each use case's config.yaml contains:

• use_case - Unique identifier
• python_version - (Optional) Required Python version (defaults to '3.13' if not specified)
• dependencies - List of pip packages to install
• installation_notes - (Optional) Installation notes (e.g., "Requires Python >= 3.13")
• environment - Environment configuration (name, description, filepaths)
• policy - (Optional) Policy configuration
• agents - List of agent configurations
• experiment - Experiment configuration

Environment Configuration

The environment section defines the simulation environment:

• name - Display name for the environment
• description - Description of what the environment does
• filepaths - Dictionary containing:
  • environment - Filename of environment.py file (required, e.g. environment.py)

Policy Configuration

The optional policy section defines the agent policy:

• name - Policy name
• description - (Optional) Policy description
• filepaths - Dictionary containing:
  • policy - Filename of policy.py file (required, e.g. policy.py)
  • Additional support files (e.g., tamer, human_expert, rgb_capture) as filenames (optional)
• checkpoint_interval - How often to save model checkpoints (0 = disabled)

Agent Configuration Fields

Each agent in the agents list can include:

• role - Agent identifier (e.g., agent_0, agent_1)
• name - Display name
• description - Agent description
• policy - Policy name (or null for human-only control)
• participant - Whether agent participates in experiments
• keyboard_inputs - Key mapping for actions
• keyboard_input_display - (Optional) Display configuration for keyboard inputs
• multiple_keyboard_inputs - (Optional) Allow multiple simultaneous key presses (default: false)
• inputs_type - (Optional) Input type: "actions", "reward", or "other" (default: "other")
• textual_inputs - (Optional) Accept text input (default: false)

Experiment Configuration

The experiment section defines how the experiment runs:

• link - URL slug/identifier for the experiment
• name - Display name
• short_description - Brief description for listings
• long_description - Detailed description with instructions
• enabled - Whether the experiment is active (boolean)
• number_of_episodes - Number of episodes to run
• target_fps - Target frames per second for rendering
• wait_for_inputs - Whether to pause for human input each step (boolean)

Python Version Compatibility

Different use cases require different Python versions. The python_version field in config.yaml specifies the required version:

Use Case	Python Version	Notes
overcooked	3.10.x only	overcooked_ai requires >=3.10,<3.11
saycan	3.10.x only	JAX and TensorFlow compatibility
smacv2	3.10.x only	SMAC dependencies
mario	>= 3.13	gym-super-mario-bros, nes-py
amaze	>= 3.13	Default
frozen	>= 3.13	Default
mountain	>= 3.13	Default
mountain_tamer	>= 3.13	Default
spread	>= 3.13	Default
tag	>= 3.13	Default

The CI pipeline tests each use case on its required Python version.