Development environment

We begin by installing UV (very nice utility for managing packages and Python version):

# On MacOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Using UV, installing the packages and virtual environment is as simple as typing the following (inside the root directory of this repository):

uv sync

Local LLM

To run a LLM locally download https://lmstudio.ai When installing select developer mode, download a model (it will already suggest one) and run it (see developer window, status: running)

copy the url at the top right and replace local_llm_url with it + v1/chat/completions. This + part might differ based on what model you choose.

copy the model name in the module loaded and replace local_llm_modelL. In settings.

Running

To run the project (development server), execute the following command (while inside the root repository):

uv run fastapi dev src/control_backend/main.py

Environment Variables

You can use environment variables to change settings. Make a copy of the .env.example file, name it .env and put it in the root directory. The file itself describes how to do the configuration.

For an exhaustive list of environment options, see the control_backend.core.config module in the docs.

Testing

Testing happens automatically when opening a merge request to any branch. If you want to manually run the test suite, you can do so by running the following for unit tests:

uv run --only-group test pytest test/unit

Or for integration tests:

uv run --group integration-test pytest test/integration

Git Hooks

To activate automatic linting, formatting, branch name checks and commit message checks, run:

uv run pre-commit install
uv run pre-commit install --hook-type commit-msg

You might get an error along the lines of Can't install pre-commit with core.hooksPath set. To fix this, simply unset the hooksPath by running:

git config --local --unset core.hooksPath

Then run the pre-commit install commands again.

Documentation

Generate documentation web pages using:

Linux & macOS

PYTHONPATH=src sphinx-apidoc -F -o docs src/control_backend

Windows

$env:PYTHONPATH="src"; sphinx-apidoc -F -o docs src/control_backend

Optionally, in the conf.py file in the docs folder, change preferences.

In the docs folder:

Linux & macOS

make html

Windows

.\make.bat html