AGENTS.md · openai/openai-python

Sections

1. Generated SDK
2. Custom-code budget
3. Security requirements for coding agents
4. Python version policy
5. Changing the minimum Python version
6. Automation map
7. Validation
8. Large-payload compatibility

First lines (shown under the repo's Apache-2.0 license)

# Repository Guidance

## Generated SDK

Most SDK source is generated from the OpenAI API schema. Follow `CONTRIBUTING.md` before
changing generated files. Handwritten policy, automation, tests, and examples
should remain small and should not alter exported SDK APIs unless the change
explicitly requires it.

## Generated-file ownership

Never hand-edit generated SDK files, including generated tests, documentation,
workflows, or the generated-file inventory. Change the authoritative API schema,
configuration, or compiler, then regenerate. Put SDK-specific behavior in
separately owned handwritten helpers and extension points.

Regeneration replaces generator-owned files and deletes retired generated paths.
Handwritten edits to generated files are overwritten; they are never replayed or
merged into new output. Preserve separately owned handwritten files and resolve
ownership collisions explicitly. Follow this AGENTS.md rule and review generated output and inventory changes
together. Generated-file ownership currently relies on contributor guidance and
code review; there is no dedicated generated-file edit check or required gate.
Fix violations in the inputs/compiler and regenerate; never update inventory
hashes to accept a handwritten patch.

## Security requirements for coding agents

- Never commit real API or admin keys, bearer tokens, webhook secrets, cloud
  credentials, X.509 private keys, release credentials, or `.env` files. Read
  `OPENAI_API_KEY`, `OPENAI_ADMIN_KEY`, `OPENAI_WEBHOOK_SECRET`, and other
  credentials from the environment; use clearly fake examples and fixtures.
- Redact credentials, `Authorization` and `api-key` headers, customer data, and
  sensitive request or response bodies from logs, exceptions, snapshots, and
  test output. Clearly fake or sanitized fixtures and safe `APIError.body`
  diagnostics may remain. Preserve existing sensitive-header filtering,
  including debug logging.
- Review direct and transitive dependency changes in `pyproject.toml`, optional
  extras, dependency groups, and `uv.lock`. Check
  package provenance, build backends, and install scripts before accepting or
  running them.
- Pin third-party GitHub Actions to reviewed full commit SHAs. Minimize
  job-level token permissions and never expose secrets or write-capable tokens
  to untrusted pull-request code.
- Preserve separate build and publish jobs, protected release credentials, and
  PyPI Trusted Publishing. Grant `id-token: write` only to the trusted,
  upload-only publishing job; do not introduce long-lived PyPI tokens.
- Obtain SDK CODEOWNER review and add focused synchronous and asynchronous
  security regression tests, as applicable, for changes to authentication,
  X.509 or webhook verification, HTTP destinations, redirects, proxies, TLS,
  cloud metadata, file uploads, serialization, dependencies, GitHub Actions,
  or release workflows.
- Report suspected vulnerabilities privately as described in `SECURITY.md`;
  never disclose them in public issues, pull requests, or logs.

## Python version policy

- `requires-python` in `pyproject.toml` is the authoritative technical minimum.
- `PYTHON_VERSION_POLICY.md` is the human-readable support and release policy.
- Support every fully released, non-EOL CPython line. A documented grace period
  may temporarily add the most recently retired line.
- Keep `requires-python`, classifiers, dependency markers, README requirements,
  static-analysis targets, `.python-version`, and CI synchronized.
- Do not combine a minimum-Python change with unrelated SDK or dependency
  upgrades.

## Changing the minimum Python version

1. Update `pyproject.toml`, `.python-version`, the lock files, README,
   `CONTRIBUTING.md`, and `PYTHON_VERSION_POLICY.md`.
2. Remove dependency branches that only served the retired runtime.
3. Update minimum/current and full-matrix CI coverage.
4. Build both distributions and validate their `Requires-Python` metadata and
   old-interpreter rejection behavior.
5. Add a `## Release note` section to the pull request description naming the
   new minimum and final compatible SDK release. Do not promise security
   backports for the old release.
6. Obtain SDK CODEOWNER approval.

The deterministic Python policy check proves repository surfaces agree. It
does not decide whether an EOL grace period or floor increase is appropriate.

## Automation map

- `.github/workflows/ci.yml`
  - On pull requests and branch pushes: lint, build, metadata validation, and
    tests on the minimum and current stable Python releases.
  - Nightly and manually: smoke-tests every supported Python release and the
    allowed-failure prerelease.
- `.github/workflows/python-version-review.yml`
  - Monthly on the default branch: snapshots official CPython lifecycle data
    plus the public PyPI Python-minor distribution and asks Codex for a policy
    review.
  - Runs a pinned Codex runtime as an unprivileged user with no command network
    access and read-only repository permissions.
  - Codex cannot edit the repository or call GitHub. A separate job with no
    OpenAI credential opens or refreshes one issue only when action is needed.
  - Never changes the Python floor or merges code automatically.

## Validation

Before publishing a Python-version change, run:

```sh
uv lock
uv lock --check
./scripts/build
uv run --locked --all-extras python scripts/check-python-version-policy.py
uv run --locked --all-extras python scripts/utils/validate-python-version-wheel.py
python3.9 scripts/utils/validate-python-version-wheel.py --check-python-39
uv run --locked --all-extras python scripts/utils/validate-bedrock-wheel.py
uv run --locked --all-extras python scripts/utils/validate-httpx2-wheel.py
./scripts/lint
./scripts/test
```

Also run the scheduled compatibility matrix before release.

## Large-payload compatibility

Treat large payloads as a normal API contract, not evidence of malformed or
hostile input. Responses, Chat Completions, and other APIs can legitimately
return large `application/json` bodies and streaming events. Do not introduce
arbitrary fixed limits on bodies, events, or lines as a security or efficiency
fix. Prefer incremental processing, amortized-linear buffering, timely cleanup,
and caller cancellation. Any new rejection limit needs an explicit,
owner-approved API contract and a review of existing supported payloads and
transports.

Protect this behavior with focused, deterministic public-entrypoint tests using
large synthetic payloads generated in memory, not committed captures or live
image generation. Their high memory use is intentional: do not shrink the
payloads or raise client limits to make the tests pass. Keep coverage to the main
JSON and streaming categories, and run large cases sequentially to keep peak
memory reasonable. The fixture size is a regression probe, not a new API maximum.