Review Python codebase

Review the current status of the repository to:

- write proper "running locally" instructions
- potentially make it into a proper python package with easier install/run instructions e.g. see https://docs.astral.sh/uv/
- format code /introduce linting e.g. see https://docs.astral.sh/ruff/