What the agent does
The agent reads how the project pins and checks its dependencies before it moves any. In an app laid out like litestar-org/litestar-fullstack, pyproject.toml lists the runtime dependencies without upper bounds, litestar with the jinja, jwt, structlog, cryptography and pydantic extras, advanced-alchemy with uuid, obstore and pwdlib, litestar-saq, litestar-vite, litestar-granian, litestar-email, psycopg, redis, httpx-oauth, pyotp and qrcode, and three dependency groups, docs, linting and test, folded into dev. uv.lock is lockfile revision 3 with 172 packages resolving litestar to 2.19.0 and advanced-alchemy to 1.8.2, and .github/workflows/ci.yaml sets UV_LOCKED=1, so a lock file that disagrees with pyproject.toml fails CI before a test runs. .github/dependabot.yaml covers only github-actions, which is why the Python side falls behind.
The repository already names the upgrade path. make upgrade runs uv lock --upgrade, then bun update in src/js/web, then uv run pre-commit autoupdate, and docs/usage/development.rst documents those three steps as the way to upgrade everything at once. .pre-commit-config.yaml pins ruff-pre-commit at v0.14.14, codespell at v2.4.1 and sphinx-lint at v1.0.2, and the linting group installs ruff, mypy, pyright, slotscheck and codespell so make lint runs them all. The tests under src/py/tests need Postgres through pytest-databases, run with -n auto and fail under --cov-fail-under=65, and ci.yaml builds the email templates with make build-emails before pytest on Python 3.12 and 3.13.
The agent takes the Python side in groups, one commit each. It runs uv lock --upgrade and splits the result: patch and minor releases of everything in one commit, then each major release of a direct dependency in its own commit, read against that package's changelog for the thing a Litestar app trips on, a renamed plugin config, a SQLAlchemy or advanced-alchemy repository method, a structlog processor signature in app/lib/log.py. Pre-commit hook revisions get their own commit from pre-commit autoupdate, since a new ruff can add rules that the select = ["ALL"] config enables at once; the agent runs ruff check --fix and ruff format and keeps that noise in the hook commit. bun update in src/js/web is left to a separate run unless the prompt asks for it, so the Python pull request stays reviewable.
For every group it runs what CI runs. uv sync --all-groups, uv run pre-commit run --all-files, make build-emails, then the suite: the sandbox has no Docker, so the agent installs it with sudo apt-get install -y docker.io and starts dockerd so pytest-databases can start Postgres, and runs uv run pytest src/py/tests --cov=src/py/app --cov-report=xml. A group that fails lint, type checks or tests is dropped and its first failing output quoted in the pull request; the groups that pass are what the pull request carries, with uv.lock consistent with pyproject.toml so UV_LOCKED=1 is happy.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade this Litestar app's Python dependencies. Read pyproject.toml, uv.lock, Makefile, .pre-commit-config.yaml, .github/workflows/ci.yaml and docs/usage/development.rst first. Run `uv lock --upgrade` and split the result into commits: one for patch and minor releases, one per major release of a direct dependency with the code change its changelog requires, and one for `uv run pre-commit autoupdate` with any ruff fixes it causes. Leave src/js/web alone. After each group run `uv sync --all-groups`, `uv run pre-commit run --all-files`, `make build-emails` and `uv run pytest src/py/tests --cov=src/py/app`; the suite needs Postgres through pytest-databases, so install Docker in the sandbox and start it first. Drop any group that fails and quote the failure. Open one pull request that lists every package's old and new version by commit, the lint and test result per group, and the coverage line. If nothing moved, open no pull request and say so.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is one pull request on its own branch with a commit per group: the uv.lock sweep of patch and minor releases, a commit per major that also changes pyproject.toml and the one or two modules under src/py/app the release required, and a commit for the hook revisions in .pre-commit-config.yaml with the ruff fixes they caused. The description is a table of package, old version, new version and commit, then the packages held back with the failure each produced, the pre-commit and pytest summary per group, and the coverage total.
The session keeps the record: the Docker install, the Postgres container pytest-databases started, every uv and pytest command with its full output, and the changelog pages read for each major. GET /o/{org}/sessions/{id}/messages returns that transcript, and GET /o/{org}/p/{project}/sessions/{id}/changes returns the diff per file.
Before merging, a reviewer reads the code changed under each major, since a renamed method compiles and tests either way but a changed default, such as a JWT library's leeway, only shows in behaviour, and checks the held-back list for the one package that matters to them. A group they do not want is one git revert of its commit, and UV_LOCKED=1 in CI confirms the lock still matches.
Run it on every Monday morning
Create an automation in the Project with this prompt and a schedule trigger (cron 0 9 * * 1 in your timezone). After the first run catches the app up, each week's run opens one pull request with that week's bumps, or none when nothing moved. Because each group is its own commit, dropping a bump before merge is a revert of one commit.
To have the link reach your server, start the weekly run from your own scheduler instead, with POST /o/{org}/sessions and an API key that has a webhook URL: Rush then POSTs run.completed with the session_url when the turn ends, and a handler on your side can post the pull request link where the app's maintainers read. A run that ends with no safe group opens no pull request and says why in its result.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A Python app on uv with a locked CI falls behind in a particular way: uv lock --upgrade is one command, but the new ruff rules, the advanced-alchemy method that moved and the test suite that needs a Postgres each cost a morning, so the lock sits. In a Rush sandbox the agent installs Docker for the test database, runs pre-commit and pytest exactly as ci.yaml does for each group, and keeps only what passes, with nothing on a laptop.
The pull request carries its proof: the per-group lint and test summaries, the coverage line and the transcript of every command. Several Litestar services can be upgraded on the same Monday in separate sandboxes, each with its own Postgres, and a reviewer who disagrees with one bump reverts one commit.
Frequently asked questions
Does it upgrade the frontend too?
Not in this run. make upgrade would also run bun update in src/js/web, but the prompt leaves that directory alone so the Python pull request stays small. A second run with a prompt for the web app, or a follow-up message to the same session, handles the JavaScript side on its own branch.
What about new ruff rules after pre-commit autoupdate?
With select = ["ALL"] in pyproject.toml, a new ruff release can enable rules that fire across the codebase. The agent runs ruff check --fix and ruff format, keeps those edits in the same commit as the hook bump, and lists any rule it had to add to the ignore list rather than fix, so the reviewer can decide.
Why does it need Docker?
The suite's conftest.py loads pytest_databases.docker.postgres, which starts a Postgres container for the integration tests. The sandbox has no Docker, so the agent installs docker.io and starts dockerd before pytest. It does not switch the fixtures to SQLite, since the repository tests against Postgres on purpose.
Will it bump Python itself?
No. requires-python and the 3.12 and 3.13 matrix in ci.yaml stay as they are, and a package that drops support for one of those versions is held back and named rather than upgraded. A Python version change is a separate job with its own prompt.