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/

Start by reviewing the repository's current local-running instructions, package setup, and formatting or linting configuration. Compare the needed installation and run guidance with uv and the formatting/linting approach described by Ruff; done means the chosen setup is documented and the requested packaging and code-quality improvements are addressed.

Written by the indexing model from the issue text.