Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Abhijeet Prasad (AbhiPrasad) merged 1 commit into from
Aug 17, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
py/src/braintrust/api/_generated/** linguist-generated=true
9 changes: 5 additions & 4 deletions .github/actions/setup-python-env/action.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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"
Expand All@@ -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
16 changes: 15 additions & 1 deletion .github/workflows/checks.yaml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -142,7 +153,8 @@ jobs:
shell: bash
run: |
mise exec python@${{ matrix.python-version }} -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 6 \
--exclude-static-checks
--exclude-static-checks \
--exclude-session test_api_codegen

adk-py:
uses: ./.github/workflows/adk-py-test.yaml
Expand DownExpand Up@@ -178,6 +190,7 @@ jobs:
needs:
- lint
- ensure-pinned-actions
- api-codegen
- static_checks
- smoke
- nox
Expand All@@ -204,6 +217,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 }}"
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/update-session-weights.yaml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,7 @@ exclude: >
(?x)^(
py/src/braintrust/_generated_types\.py
|py/src/braintrust/generated_types\.py
|py/src/braintrust/api/_generated/.*
)$

repos:
Expand Down
33 changes: 33 additions & 0 deletions openapi/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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.
59 changes: 59 additions & 0 deletions openapi/config.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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"
]
}
}
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
feat(api): generate REST models from pinned OpenAPI spec by AbhiPrasad · Pull Request #690 · braintrustdata/braintrust-sdk-python · GitHub
Skip to content
feat(api): generate REST models from pinned OpenAPI spec#690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Abhijeet Prasad (AbhiPrasad)
merged 1 commit into

from

Aug 17, 2026
 Merged


feat(api): generate REST models from pinned OpenAPI spec
#690
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
py/src/braintrust/api/_generated/** linguist-generated=true

9 changes: 5 additions & 4 deletions
.github/actions/setup-python-env/action.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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"
Expand All@@ -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

16 changes: 15 additions & 1 deletion
.github/workflows/checks.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -142,7 +153,8 @@ jobs:
 shell: bash
 run: |
 mise exec python@${{ matrix.python-version }} -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 6 \
 --exclude-static-checks
 --exclude-static-checks \
 --exclude-session test_api_codegen

 adk-py:
 uses: ./.github/workflows/adk-py-test.yaml
Expand DownExpand Up@@ -178,6 +190,7 @@ jobs:
 needs:
 - lint
 - ensure-pinned-actions
 - api-codegen
 - static_checks
 - smoke
 - nox
Expand All@@ -204,6 +217,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 }}"
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/update-session-weights.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down

1 change: 1 addition & 0 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,7 @@ exclude: >
 (?x)^(
 py/src/braintrust/_generated_types\.py
 |py/src/braintrust/generated_types\.py
 |py/src/braintrust/api/_generated/.*
 )$

repos:
Expand Down

33 changes: 33 additions & 0 deletions
openapi/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

59 changes: 59 additions & 0 deletions
openapi/config.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"
 ]
 }
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
feat(api): generate REST models from pinned OpenAPI spec by AbhiPrasad · Pull Request #690 · braintrustdata/braintrust-sdk-python · GitHub
Skip to content
feat(api): generate REST models from pinned OpenAPI spec#690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Abhijeet Prasad (AbhiPrasad)
merged 1 commit into

from

Aug 17, 2026
 Merged


feat(api): generate REST models from pinned OpenAPI spec
#690
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
py/src/braintrust/api/_generated/** linguist-generated=true

9 changes: 5 additions & 4 deletions
.github/actions/setup-python-env/action.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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"
Expand All@@ -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

16 changes: 15 additions & 1 deletion
.github/workflows/checks.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -142,7 +153,8 @@ jobs:
 shell: bash
 run: |
 mise exec python@${{ matrix.python-version }} -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 6 \
 --exclude-static-checks
 --exclude-static-checks \
 --exclude-session test_api_codegen

 adk-py:
 uses: ./.github/workflows/adk-py-test.yaml
Expand DownExpand Up@@ -178,6 +190,7 @@ jobs:
 needs:
 - lint
 - ensure-pinned-actions
 - api-codegen
 - static_checks
 - smoke
 - nox
Expand All@@ -204,6 +217,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 }}"
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/update-session-weights.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down

1 change: 1 addition & 0 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,7 @@ exclude: >
 (?x)^(
 py/src/braintrust/_generated_types\.py
 |py/src/braintrust/generated_types\.py
 |py/src/braintrust/api/_generated/.*
 )$

repos:
Expand Down

33 changes: 33 additions & 0 deletions
openapi/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

59 changes: 59 additions & 0 deletions
openapi/config.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"
 ]
 }
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
feat(api): generate REST models from pinned OpenAPI spec by AbhiPrasad · Pull Request #690 · braintrustdata/braintrust-sdk-python · GitHub
Skip to content
feat(api): generate REST models from pinned OpenAPI spec#690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Abhijeet Prasad (AbhiPrasad)
merged 1 commit into

from

Aug 17, 2026
 Merged


feat(api): generate REST models from pinned OpenAPI spec
#690
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
py/src/braintrust/api/_generated/** linguist-generated=true

9 changes: 5 additions & 4 deletions
.github/actions/setup-python-env/action.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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"
Expand All@@ -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

16 changes: 15 additions & 1 deletion
.github/workflows/checks.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -142,7 +153,8 @@ jobs:
 shell: bash
 run: |
 mise exec python@${{ matrix.python-version }} -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 6 \
 --exclude-static-checks
 --exclude-static-checks \
 --exclude-session test_api_codegen

 adk-py:
 uses: ./.github/workflows/adk-py-test.yaml
Expand DownExpand Up@@ -178,6 +190,7 @@ jobs:
 needs:
 - lint
 - ensure-pinned-actions
 - api-codegen
 - static_checks
 - smoke
 - nox
Expand All@@ -204,6 +217,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 }}"
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/update-session-weights.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down

1 change: 1 addition & 0 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,7 @@ exclude: >
 (?x)^(
 py/src/braintrust/_generated_types\.py
 |py/src/braintrust/generated_types\.py
 |py/src/braintrust/api/_generated/.*
 )$

repos:
Expand Down

33 changes: 33 additions & 0 deletions
openapi/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

59 changes: 59 additions & 0 deletions
openapi/config.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"
 ]
 }
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
feat(api): generate REST models from pinned OpenAPI spec by AbhiPrasad · Pull Request #690 · braintrustdata/braintrust-sdk-python · GitHub
Skip to content
feat(api): generate REST models from pinned OpenAPI spec#690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Abhijeet Prasad (AbhiPrasad)
merged 1 commit into

from

Aug 17, 2026
 Merged


feat(api): generate REST models from pinned OpenAPI spec
#690
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
py/src/braintrust/api/_generated/** linguist-generated=true

9 changes: 5 additions & 4 deletions
.github/actions/setup-python-env/action.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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"
Expand All@@ -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

16 changes: 15 additions & 1 deletion
.github/workflows/checks.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -142,7 +153,8 @@ jobs:
 shell: bash
 run: |
 mise exec python@${{ matrix.python-version }} -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 6 \
 --exclude-static-checks
 --exclude-static-checks \
 --exclude-session test_api_codegen

 adk-py:
 uses: ./.github/workflows/adk-py-test.yaml
Expand DownExpand Up@@ -178,6 +190,7 @@ jobs:
 needs:
 - lint
 - ensure-pinned-actions
 - api-codegen
 - static_checks
 - smoke
 - nox
Expand All@@ -204,6 +217,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 }}"
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/update-session-weights.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down

1 change: 1 addition & 0 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,7 @@ exclude: >
 (?x)^(
 py/src/braintrust/_generated_types\.py
 |py/src/braintrust/generated_types\.py
 |py/src/braintrust/api/_generated/.*
 )$

repos:
Expand Down

33 changes: 33 additions & 0 deletions
openapi/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

59 changes: 59 additions & 0 deletions
openapi/config.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"
 ]
 }
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
feat(api): generate REST models from pinned OpenAPI spec by AbhiPrasad · Pull Request #690 · braintrustdata/braintrust-sdk-python · GitHub
Skip to content
feat(api): generate REST models from pinned OpenAPI spec#690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Abhijeet Prasad (AbhiPrasad)
merged 1 commit into

from

Aug 17, 2026
 Merged


feat(api): generate REST models from pinned OpenAPI spec
#690
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
py/src/braintrust/api/_generated/** linguist-generated=true

9 changes: 5 additions & 4 deletions
.github/actions/setup-python-env/action.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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"
Expand All@@ -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

16 changes: 15 additions & 1 deletion
.github/workflows/checks.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -142,7 +153,8 @@ jobs:
 shell: bash
 run: |
 mise exec python@${{ matrix.python-version }} -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 6 \
 --exclude-static-checks
 --exclude-static-checks \
 --exclude-session test_api_codegen

 adk-py:
 uses: ./.github/workflows/adk-py-test.yaml
Expand DownExpand Up@@ -178,6 +190,7 @@ jobs:
 needs:
 - lint
 - ensure-pinned-actions
 - api-codegen
 - static_checks
 - smoke
 - nox
Expand All@@ -204,6 +217,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 }}"
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/update-session-weights.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down

1 change: 1 addition & 0 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,7 @@ exclude: >
 (?x)^(
 py/src/braintrust/_generated_types\.py
 |py/src/braintrust/generated_types\.py
 |py/src/braintrust/api/_generated/.*
 )$

repos:
Expand Down

33 changes: 33 additions & 0 deletions
openapi/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

59 changes: 59 additions & 0 deletions
openapi/config.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"
 ]
 }
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
})();
feat(api): generate REST models from pinned OpenAPI spec by AbhiPrasad · Pull Request #690 · braintrustdata/braintrust-sdk-python · GitHub
Skip to content
feat(api): generate REST models from pinned OpenAPI spec#690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Abhijeet Prasad (AbhiPrasad)
merged 1 commit into

from

Aug 17, 2026
 Merged


feat(api): generate REST models from pinned OpenAPI spec
#690
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
.gitattributes

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
py/src/braintrust/api/_generated/** linguist-generated=true

9 changes: 5 additions & 4 deletions
.github/actions/setup-python-env/action.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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"
Expand All@@ -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

16 changes: 15 additions & 1 deletion
.github/workflows/checks.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -142,7 +153,8 @@ jobs:
 shell: bash
 run: |
 mise exec python@${{ matrix.python-version }} -- python ./py/scripts/nox-matrix.py ${{ matrix.shard }} 6 \
 --exclude-static-checks
 --exclude-static-checks \
 --exclude-session test_api_codegen

 adk-py:
 uses: ./.github/workflows/adk-py-test.yaml
Expand DownExpand Up@@ -178,6 +190,7 @@ jobs:
 needs:
 - lint
 - ensure-pinned-actions
 - api-codegen
 - static_checks
 - smoke
 - nox
Expand All@@ -204,6 +217,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 }}"
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/update-session-weights.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down

1 change: 1 addition & 0 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,6 +2,7 @@ exclude: >
 (?x)^(
 py/src/braintrust/_generated_types\.py
 |py/src/braintrust/generated_types\.py
 |py/src/braintrust/api/_generated/.*
 )$

repos:
Expand Down

33 changes: 33 additions & 0 deletions
openapi/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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.

59 changes: 59 additions & 0 deletions
openapi/config.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -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"
 ]
 }
}
Loading
Loading