Skip to content

Development Setup Guide

If you want to contribute to ASTRA-RL, modify it for your needs, or run the examples from the repository, follow these steps.

Prerequisites

We strongly recommend using uv to manage your Python environment. This ensures you have the correct dependencies and versions installed.

Setting Up the Development Environment

  1. Clone the repository:
git clone https://github.com/sisl/astra-rl.git
cd astra-rl
  1. Sync package dependencies:
uv sync --dev

This creates a .venv directory in the project root with all necessary dependencies installed.

  1. Install pre-commit hooks:
uv run pre-commit install

This ensures that the linter (ruff), formatter (ruff), and type checker (mypy) validate your code before each commit.

Running Tests

After setting up your development environment, you can run tests using:

pytest

or with uv:

uv run pytest

Generating Coverage Reports

To generate local coverage reports:

uv run coverage run -m pytest
uv run coverage report  # Generate CLI report
uv run coverage html    # Generate HTML report

The HTML report will be available in the htmlcov directory.

Building Documentation Locally

To build and serve the documentation locally:

uv run mkdocs serve

This will start a local server at http://127.0.0.1:8000 where you can preview documentation changes.

Code Quality Tools

The project uses several tools to maintain code quality:

  • Ruff: For linting and formatting
  • MyPy: For type checking
  • Pre-commit: For running checks before commits

To run these manually:

# Linting and formatting
uv run ruff check .
uv run ruff format .

# Type checking
uv run mypy .

# Run all pre-commit hooks
uv run pre-commit run --all-files

Troubleshooting

Common Issues

  1. Import errors after installation:
  2. Ensure you're using the correct Python environment

  3. Try reinstalling: pip install --upgrade --force-reinstall astra-rl

  4. Development environment issues:

  5. Make sure uv is properly installed

  6. Try removing .venv and running uv sync --dev again

  7. GPU/CUDA issues:

  8. Ensure you have the appropriate PyTorch version for your CUDA installation
  9. Check PyTorch installation: python -c "import torch; print(torch.cuda.is_available())"

Getting Help

If you encounter issues:

  • Check the GitHub Issues for similar problems
  • Open a new issue with details about your environment and the problem
  • Join the discussions on the repository's Discussions tab