What the agent does
The agent starts by reading what the app already is. In a project laid out like litestar-org/litestar-hello-world, app.py is the whole application: two route handlers, async_hello_world on /async and sync_hello_world on /sync with sync_to_thread=False, both returning {"hello": "world"}, and app = Litestar(route_handlers=[sync_hello_world, async_hello_world]) with no configuration objects at all. pyproject.toml depends on litestar[standard]>=2.4.1, pdm.lock pins Litestar 2.4.1, and the dev groups hold ruff with select = ["ALL"], mypy in strict mode, pyright and pytest with asyncio_mode = "auto". tests/test_app.py has two tests that open TestClient(app=app) and compare the JSON body. .github/workflows/ci.yaml runs pre-commit, then calls test.yaml for Python 3.8 through 3.11, where pdm install and pdm run pytest run, with coverage on 3.11 only.
Compression in Litestar is a configuration object, not a package. The agent imports CompressionConfig from litestar.config.compression and passes compression_config=CompressionConfig(backend="gzip") to the Litestar constructor. The gzip backend needs nothing beyond the standard library; the Brotli backend needs the brotli package, which Litestar ships as the extra litestar[brotli], and keeps brotli_gzip_fallback=True so a client that sends only Accept-Encoding: gzip still gets a compressed body. The agent picks gzip for a project that lists litestar[standard] alone, and switches to Brotli only when the prompt asks for it, adding the extra to pyproject.toml and refreshing pdm.lock with pdm lock so the pdm-lock-check pre-commit hook keeps passing.
The detail that trips people up is minimum_size. Its default is 500 bytes, and the hello-world bodies are far smaller, so a naive test that asserts a content-encoding header on /sync fails even though the middleware is wired correctly. The agent adds a third handler, or reuses an existing one that returns a list, whose JSON body crosses the threshold, and writes the test against that: send Accept-Encoding: gzip, assert response.headers["content-encoding"] == "gzip", and assert the decoded JSON is unchanged, which TestClient handles because it decodes the body for you. A second test sends no Accept-Encoding header and asserts the response is left alone. If the prompt sets minimum_size lower, the test documents why.
Before opening the pull request, the agent runs what CI runs: pdm install, pdm run pytest, and pre-commit run --all-files, which covers ruff, mypy, codespell and the lock check. Because ruff selects every rule, the new handler needs a docstring and a return annotation that matches the existing style (Dict[str, Any] with the noqa: UP006 the file already uses), otherwise the lint step, not the test step, is what fails. The branch carries the app.py change, the new test, and the dependency change if Brotli was chosen, and nothing else.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add response compression to this Litestar app. Read app.py, pyproject.toml, pdm.lock, tests/test_app.py and the workflows under .github/workflows first. Pass a CompressionConfig from litestar.config.compression to the Litestar constructor with the gzip backend, keeping the default minimum_size of 500 bytes unless a comment in the code says otherwise. Add a test in tests/test_app.py that requests a response larger than minimum_size with Accept-Encoding: gzip and asserts the content-encoding header and an unchanged JSON body, and a second test that a request without Accept-Encoding is not compressed. Run pdm install, pdm run pytest and pre-commit run --all-files, fix anything they report, and open a pull request that quotes the test output and explains the minimum_size threshold.",
"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
The pull request changes app.py (the import, the compression_config argument and, where needed, one handler that returns a body over the threshold) and tests/test_app.py (two new tests), plus pyproject.toml and pdm.lock only when Brotli was requested. Its description quotes the pytest and pre-commit output from the sandbox and states the minimum_size in effect, so a reviewer knows that small bodies pass through uncompressed by design rather than by mistake.
A reviewer checks three things: that the middleware is on the app rather than on one route, that the test asserts the header on a body that is actually large enough, and that the Python 3.8 leg of the matrix still passes, since litestar[standard] on 3.8 is the oldest combination the project supports. The CI workflow needs no change; the existing matrix exercises the new tests on every version.
After merge, any client that sends Accept-Encoding gets gzip bodies for responses over the threshold and identical bytes for the rest. Nothing about routing, status codes or the OpenAPI schema changes.
Run it on every new Litestar service repository
A platform team that wants every Litestar service to compress by default keeps a list of repositories and starts one run per entry. A handler on the reader's own server sends this body to POST /o/{org}/sessions for each, naming the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried loop returns the run it already started instead of opening a second pull request. Each run reads its own app.py and finds the constructor, whether the app is one file or a package with an asgi.py.
For an existing fleet, an automation on each Project with a github trigger on pull_request.opened and pull_request.synchronize can check that a change to the app constructor keeps the compression_config argument. An automation's run is read-only, so it posts a review comment when the argument disappears; the fix itself comes from a run started by hand or from the handler above.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The work is small and the proof is what matters: the pull request shows the header assertion passing under the same pdm run pytest that CI runs, and the pre-commit output, including the strict mypy and ruff configuration this project carries, is kept with the run. A reviewer reads a diff and a log rather than reproducing the environment on a laptop.
Running the same change across several services at once gives each one its own sandbox, its own lockfile refresh and its own test output. A Brotli choice in one repository, where the extra and the lock change, does not leak into another that only needs gzip.
Frequently asked questions
Why does the hello-world response come back uncompressed?
Because CompressionConfig only compresses bodies at or above minimum_size, which defaults to 500 bytes, and {"hello": "world"} is far smaller. The agent tests against a body that crosses the threshold and says so in the pull request, so nobody mistakes the default for a bug.
Gzip or Brotli?
Gzip needs no extra dependency and works with the litestar[standard] extra the project already has. Brotli needs litestar[brotli], a change to pyproject.toml and pdm.lock, and keeps brotli_gzip_fallback=True so clients without Brotli support still get gzip. The agent uses gzip unless the prompt asks for Brotli.
Will the strict linting in this project reject the change?
Ruff is configured with select = ["ALL"] and mypy with strict = true, so a new handler without a docstring or a return annotation fails pre-commit. The agent runs pre-commit run --all-files in the sandbox before pushing and matches the annotations the file already uses.
Can one route opt out of compression?
Yes. CompressionConfig takes exclude, a path pattern or list of patterns the middleware skips, and exclude_opt_key, a route option key that disables it per handler. The agent only adds these when the prompt names a route that must stay uncompressed.