feat(api): generate REST models from pinned OpenAPI spec

.gitattributes

@@ -0,0 +1 @@
+py/src/braintrust/api/_generated/** linguist-generated=true

.github/actions/setup-python-env/action.yml

@@ -3,8 +3,9 @@ description: "Checkout, configure mise, and install dev dependencies for a given
 
 inputs:
   python-version:
-    description: "Python version to install (e.g. 3.12)"
-    required: true
+    description: "Python version to install (e.g. 3.12). Defaults to the .tool-versions pin."
+    required: false
+    default: ""
 
 runs:
   using: "composite"
@@ -20,8 +21,8 @@ runs:
       with:
         cache: true
         experimental: true
-        install_args: python@${{ inputs.python-version }}
+        install_args: ${{ inputs.python-version && format('python@{0}', inputs.python-version) || '' }}
     - name: Install dependencies
       shell: bash
       run: |
-        mise exec python@${{ inputs.python-version }} -- make -C py install-dev
+        mise exec ${{ inputs.python-version && format('python@{0}', inputs.python-version) || '' }} -- make -C py install-dev

.github/workflows/checks.yaml

@@ -32,6 +32,17 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - run: bash scripts/ensure-pinned-actions.sh
 
+  api-codegen:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Setup Python environment
+        uses: ./.github/actions/setup-python-env
+      - name: Test generator and check committed output
+        run: |
+          mise exec -- make -C py test-api-codegen check-api-client-codegen
+
   static_checks:
     runs-on: ubuntu-24.04
     timeout-minutes: 20
@@ -136,6 +147,7 @@ jobs:
         run: |
           mise exec python@${{ matrix.python-version }} -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 6 \
             --exclude-static-checks \
+            --exclude-session test_api_codegen \
             --exclude-session-prefix test_transformers
 
   transformers-py:
@@ -200,6 +212,7 @@ jobs:
     needs:
       - lint
       - ensure-pinned-actions
+      - api-codegen
       - static_checks
       - smoke
       - nox
@@ -227,6 +240,7 @@ jobs:
 
           check_result "lint" "${{ needs.lint.result }}"
           check_result "ensure-pinned-actions" "${{ needs['ensure-pinned-actions'].result }}"
+          check_result "api-codegen" "${{ needs['api-codegen'].result }}"
           check_result "static_checks" "${{ needs.static_checks.result }}"
           check_result "smoke" "${{ needs.smoke.result }}"
           check_result "nox" "${{ needs.nox.result }}"

.github/workflows/update-session-weights.yaml

@@ -31,6 +31,7 @@ jobs:
         run: |
           mise exec python@3.10 -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 4 \
             --exclude-static-checks \
+            --exclude-session test_api_codegen \
             --output-durations measured-durations-${{ matrix.shard }}.json
       - name: Upload measured durations
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1

.pre-commit-config.yaml

@@ -2,6 +2,7 @@ exclude: >
   (?x)^(
       py/src/braintrust/_generated_types\.py
       |py/src/braintrust/generated_types\.py
+      |py/src/braintrust/api/_generated/.*
   )$
 
 repos:

openapi/README.md

@@ -0,0 +1,33 @@
+# Pinned Braintrust OpenAPI specification
+
+`spec.json` is a committed snapshot of the public specification from
+[`braintrustdata/braintrust-openapi`](https://github.com/braintrustdata/braintrust-openapi).
+`config.json` pins the full upstream commit, snapshot SHA-256, generator tools, generator flags, and
+explicit endpoint exclusions. The generator scripts live in `py/scripts/`. Builds and package installation use the committed generated source and never fetch or run
+code generation.
+
+From `py/`, validate and regenerate the private models offline with:
+
+```bash
+make generate-api-client
+make check-api-client-codegen
+```
+
+The check regenerates into a temporary directory and does not modify the worktree.
+
+To fetch the configured upstream commit explicitly:
+
+```bash
+make fetch-openapi-spec
+```
+
+For an existing local checkout, set `BRAINTRUST_OPENAPI_ROOT` to its root. The checkout must be at the
+commit pinned in `config.json`, and its specification must have the pinned hash:
+
+```bash
+BRAINTRUST_OPENAPI_ROOT=../../braintrust-openapi make fetch-openapi-spec
+```
+
+To update the snapshot, first update the commit and SHA-256 in `config.json`, then fetch, regenerate,
+and review both the upstream spec diff and generated model diff. Fix specification defects upstream
+rather than adding Python-side normalization beyond CORS `OPTIONS` removal and configured exclusions.

openapi/config.json

@@ -0,0 +1,59 @@
+{
+  "schema_version": 1,
+  "spec": {
+    "repository": "braintrustdata/braintrust-openapi",
+    "path": "openapi/spec.json",
+    "commit": "9daf27f19d9e0340304d7a3e7d0edb28380b94c6",
+    "sha256": "5ec753c0263c0c44cd04f741edfc7e8bad491cc25a2113d029e84edc076520f0"
+  },
+  "tools": {
+    "datamodel-code-generator": "0.72.4",
+    "ruff": "0.15.21",
+    "python": "3.14"
+  },
+  "model_generator": {
+    "flags": [
+      "--input-file-type=openapi",
+      "--output-model-type=typing.TypedDict",
+      "--target-python-version=3.10",
+      "--use-union-operator",
+      "--enum-field-as-literal=all",
+      "--use-generic-container-types",
+      "--use-field-description",
+      "--strict-nullable",
+      "--parent-scoped-naming",
+      "--no-use-closed-typed-dict",
+      "--disable-future-imports",
+      "--formatters=ruff-format"
+    ]
+  },
+  "endpoint_generator": {
+    "schema_version": 1,
+    "skip_tags": {
+      "Proxy": {
+        "reason": "Proxy endpoints stream provider-specific payloads and remain on the specialized proxy path.",
+        "operation_ids": [
+          "proxychatCompletions",
+          "proxycompletions",
+          "proxyauto",
+          "proxyembeddings",
+          "proxycredentials",
+          "proxy{path+}"
+        ]
+      }
+    },
+    "supported_success_statuses": [
+      "200",
+      "201",
+      "202",
+      "204"
+    ],
+    "supported_request_media_types": [
+      "application/json"
+    ],
+    "supported_response_media_types": [
+      "application/json",
+      "text/plain"
+    ]
+  }
+}