Python Toolchain: marimo, uv, ty, ruff
Python Toolchain: marimo, uv, ty, ruff
← Back to README | Monorepo Guide
The tools/ directory contains the project’s Python operational tooling — runbooks, diagnostics scripts, and data-analysis notebooks — built on the Astral toolchain (uv, ruff, ty) and marimo reactive notebooks.
Table of Contents
- Stack Overview
- Getting Started
- uv — Package Manager
- marimo — Reactive Notebooks
- ruff — Linter and Formatter
- ty — Type Checker
- Language Server (pylsp + ty)
- AI Integration
- Runtime Configuration
- Task Reference
Stack Overview
| Tool | Version | Role |
|---|---|---|
| marimo | >=0.17.0 with [mcp] extra | Reactive notebook runtime; runbook execution UI |
| uv | any | Package manager; virtual environment; script runner |
| ruff | >=0.9.0 | Linter + formatter (replaces flake8, isort, black) |
| ty | >=0.0.1a0 | Astral next-gen type checker; LSP mode (ty server) |
| pylsp | >=1.12.0 with [websockets] | Marimo inline language server |
| python-lsp-ruff | >=2.2.0 | ruff plugin for pylsp |
| anthropic | >=0.25.0 | AI completions inside the marimo editor |
Python version requirement: >=3.11 (set in tools/pyproject.toml).
Getting Started
All commands are run from the repository root using Deno tasks:
# 1. Install all Python dependenciesdeno task runbook:setupThis is equivalent to running uv sync --directory tools, which:
- Creates
tools/.venv/if it does not exist - Installs all runtime and dev dependencies from
tools/uv.lock - Makes
marimo,ruff,ty, andpylspavailable within the virtual environment
You do not need to activate the virtual environment manually — all deno task runbook:* commands invoke uv run --directory tools ..., which activates the correct environment inline.
uv — Package Manager
uv is configured as the package manager in tools/.marimo.toml:
[package_management]manager = "uv"This means:
- The Add package button inside the marimo editor calls
uv addrather than pip. marimo run --sandboxanduv run marimo runboth use the uv-managed virtual environment.- PEP 723 inline script headers in notebooks are honoured by uv automatically.
Adding a dependency
# Add a runtime dependencycd tools && uv add <package>
# Add a dev-only dependencycd tools && uv add --dev <package>
# Update the lock file after editing pyproject.toml manuallydeno task runbook:setupProject structure
tools/├── pyproject.toml ← Project metadata, deps, ruff/ty/pytest config├── .marimo.toml ← marimo editor/runtime configuration (git-ignored; copy from .marimo.toml.example)├── uv.lock ← Reproducible lock file (commit this)├── .venv/ ← Virtual environment (git-ignored)├── runbooks/│ ├── pipeline.py ← Compilation pipeline runbook│ └── auth-healthcheck.py ← Auth health-check runbook└── tests/ ← pytest suite (conftest.py + test_runbooks.py)marimo — Reactive Notebooks
marimo is a reactive Python notebook framework. Unlike Jupyter, marimo tracks cell dependencies and re-executes only the cells that are actually affected by a change — similar to a spreadsheet.
The minimum version in this project is 0.17.0 because that release introduced the MCP server extra (marimo[mcp]), which exposes runbooks as Model Context Protocol tools.
Running a runbook (read-only UI)
deno task runbook:pipeline# equivalent: uv run --directory tools marimo run runbooks/pipeline.pyThis starts a local HTTP server and opens the notebook in the default browser. The notebook is read-only — cell code cannot be edited in this mode.
Starting the runbook server with a fixed address
deno task runbook:server# equivalent: uv run --directory tools marimo run runbooks/pipeline.py --host 127.0.0.1 --port 2718Editing a runbook
deno task runbook:edit:pipeline# equivalent: uv run --directory tools marimo edit runbooks/pipeline.py
deno task runbook:edit:auth-healthcheck# equivalent: uv run --directory tools marimo edit runbooks/auth-healthcheck.pyEdit mode allows full cell editing. Changes are saved as valid Python files.
Converting Jupyter notebooks
deno task runbook:convert# equivalent: uv run --directory tools marimo convertAutosave and format-on-save
Configured in tools/.marimo.toml:
[save]autosave = "after_delay"autosave_delay = 1000 # millisecondsformat_on_save = true # runs ruff format on each saveruff — Linter and Formatter
ruff is configured in tools/pyproject.toml:
[tool.ruff]line-length = 120target-version = "py311"
[tool.ruff.lint]select = ["E", "F", "I", "UP", "B", "RUF"]ignore = ["E501"]
[tool.ruff.format]quote-style = "double"indent-style = "space"Rule sets enabled
| Code | Rule set |
|---|---|
E | pycodestyle errors |
F | Pyflakes |
I | isort (import sorting) |
UP | pyupgrade (modernise syntax) |
B | flake8-bugbear |
RUF | Ruff-specific rules |
E501 (line-too-long) is ignored because line-length = 120 already enforces the limit at the formatter level.
Lint and format from the root
# Lintdeno task runbook:lint# equivalent: uv run --directory tools ruff check .
# Formatdeno task runbook:fmt# equivalent: uv run --directory tools ruff format .Both commands operate on all files under tools/.
ty — Type Checker
ty (>=0.0.1a0) is the Astral next-generation Python type checker. It is faster than mypy and is used in two ways:
- CLI type-checking via
deno task runbook:typecheck - LSP mode inside the marimo editor via
ty server(see Language Server)
Checking types from the root
deno task runbook:typecheck# equivalent: uv run --directory tools ty check auth-healthcheck.py runbooks/Configured in tools/pyproject.toml:
[tool.ty]# Astral type checker — https://github.com/astral-sh/tyAdditional per-file or per-directory ty configuration can be added under [tool.ty] as the project evolves.
Language Server (pylsp + ty)
marimo embeds a Python language server that powers inline type errors, completions, and hover documentation in the notebook editor without requiring an external IDE.
Configured in tools/.marimo.toml:
[language_servers.pylsp]enabled = true
[language_servers.ty]enabled = trueBoth servers are installed as dev dependencies:
[dependency-groups]dev = [ "ruff>=0.9.0", "ty>=0.0.1a0", "python-lsp-server[websockets]>=1.12.0", "python-lsp-ruff>=2.2.0",]How it works:
pylspis the main LSP server; it provides completions, diagnostics, and hover.python-lsp-ruffreplaces pylsp’s built-in pycodestyle and Pyflakes diagnostics with ruff output, ensuring the language server and the CLI use the same rule set.tyruns in its own LSP mode (ty server) and provides type inference, type errors, and go-to-definition.
AI Integration
The marimo editor includes an AI code assistant powered by Anthropic Claude.
Configured in tools/.marimo.toml:
[ai.anthropic]model = "claude-sonnet-4-5"# api_key = "" # Set via ANTHROPIC_API_KEY env var insteadSetting the API key
export ANTHROPIC_API_KEY="sk-ant-..."# Then start marimo:deno task runbook:edit:pipelineThe key must be exported in the shell before launching marimo — load_env_file() only returns a parsed dict used internally by the runbook cells and does not export variables into the process environment.
Available models (as of 2026):
claude-opus-4-5— most capable; best for complex reasoningclaude-sonnet-4-5— balanced speed and capability (configured default)claude-haiku-3-5— fastest, lowest cost; suitable for completions
Runtime Configuration
Auto-reload is configured in tools/.marimo.toml:
[runtime]auto_instantiate = trueauto_reload = "lazy"auto_reload = "lazy"— when an imported Python module changes on disk, marimo marks dependent cells as stale but does not re-run them automatically. Change to"autorun"for a fully reactive experience.auto_instantiate = true— the notebook runs all cells on load (read-only mode).
Completions:
[completion]activate_on_typing = truecopilot = false # GitHub Copilot disabled; AI handled by Anthropic aboveTask Reference
| Task | Command | Notes |
|---|---|---|
runbook:setup | uv sync --directory tools | First-time setup; updates lock file |
runbook:pipeline | marimo run runbooks/pipeline.py | Run pipeline runbook (read-only) |
runbook:auth-healthcheck | marimo run runbooks/auth-healthcheck.py | Run auth health-check (read-only) |
runbook:server | marimo run ... --host 127.0.0.1 --port 2718 | Fixed-address server |
runbook:edit:pipeline | marimo edit runbooks/pipeline.py | Edit pipeline runbook |
runbook:edit:auth-healthcheck | marimo edit runbooks/auth-healthcheck.py | Edit auth-healthcheck runbook |
runbook:convert | marimo convert | Convert Jupyter → marimo |
runbook:test | pytest tests/ -v | Run pytest suite |
runbook:lint | ruff check . | Lint all Python under tools/ |
runbook:fmt | ruff format . | Format all Python under tools/ |
runbook:typecheck | ty check auth-healthcheck.py runbooks/ | Type-check runbooks |
All tasks are invoked from the repository root as deno task <name>.