groundskeeping is a reusable Textual shell for operator tools that inspect, configure, and care for a working environment. It provides page and workbench contracts, safe actions and in-process jobs, setup wizards, oa-configurator inspection and write-flow mechanics, and normalized telemetry primitives.
Consuming applications own their production pages, domain services, safety policy, persistence, and environment-specific help. Groundskeeping owns the consistent interaction around them.
| You want to… | Read… |
|---|---|
| Use an application built with Groundskeeping | Using a Groundskeeping app |
| Integrate Groundskeeping into an application | Developer quickstart |
| Add configuration inspection or a write flow | Configuration guide |
| Understand package boundaries | What belongs where |
| Browse public contracts | API reference |
Groundskeeping requires Python 3.12 or newer.
uv add groundskeepingRun the self-contained demo:
uv run groundskeepingThe Configuration page uses a deterministic fake provider, so you can try branching, review, and apply behavior without writing a file.
A Groundskeeping application starts with an OperatorAppSpec. The application wires its own services into its own page factories, then gives the resulting pages to the shell.
from groundskeeping.app import OperatorApp, OperatorAppSpec
from groundskeeping.contracts import PageRegistration, PageRoute
setup_route = PageRoute(
key="setup",
label="Setup",
purpose="Check whether this environment is ready.",
)
spec = OperatorAppSpec(
app_id="my-tool",
title="My Tool",
subtitle="environment setup",
pages=(
PageRegistration(
route=setup_route,
factory=lambda context: SetupPage(setup_service),
),
),
)
OperatorApp(spec).run()SetupPage and setup_service stay in the consuming application. Groundskeeping supplies the frame around them.
uv sync --all-extras --dev
uv run pytest -q
uv run ruff check .
uv run ty check src/The full documentation is at AustralianCancerDataNetwork.github.io/groundskeeping.