AGENTS.md — scripts (Python Client)

This directory contains the Deliberate Lab Python client — a pip-installable SDK for the REST API — plus a standalone Node.js diagnostic script.

See also: root AGENTS.md for monorepo-wide conventions.

Package structure

⚠️ types.py is auto-generated

types.py is generated from JSON schemas produced by the utils workspace. The full pipeline:

utils/src/export-schemas.ts  →  docs/assets/api/schemas.json  →  types.py

To regenerate, run from the repository root:

npm run update-schemas

This builds utils, exports JSON schemas, then runs datamodel-codegen to produce Pydantic v2 models. Never edit types.py manually — your changes will be overwritten.

[!NOTE] The pipeline requires utils to be built first. If you have changed utils source, npm run update-schemas will rebuild it automatically via the update_schemas.sh script.

Build & test

Requires Python 3.12+ and uses uv for dependency management:

cd scripts
uv sync                          # Install dependencies
uv run pyright deliberate_lab/   # Type check

Installation (as a user)

pip install git+https://github.com/PAIR-code/deliberate-lab.git#subdirectory=scripts

Usage

import deliberate_lab as dl

client = dl.Client()  # Uses DL_API_KEY environment variable
experiments = client.list_experiments()
data = client.export_experiment("experiment-id")

The Client class supports env="prod" or env="dev" (default) to target production or local emulator endpoints.

REST API connection

The Python client in client.py is the SDK for the REST API implemented in functions/src/dl_api/. When a new REST API endpoint is added, the matching Python method should be added here. The API spec lives in docs/assets/api/openapi.yaml.

functions/src/dl_api/ → docs/assets/api/openapi.yaml → client.py
(implementation)        (API spec)                     (Python SDK)

Testing

There are no automated tests for the Python client. The end-to-end schema sync is validated by the CI schema check (see root AGENTS.md).

Common pitfalls

1. Editing types.py by hand — this file is auto-generated and will be overwritten by npm run update-schemas. Always modify the source types in utils instead.
2. Looking for Python tests — there are no automated tests for the Python client yet. Do not create a pytest configuration expecting existing tests to exist.
3. Running uv from the repo root — unlike npm commands, Python tooling (uv, pyright) must be run from the scripts/ directory where pyproject.toml lives.