Skip to content

feat(api): generate and migrate Dataset REST resources - #703

Open
Abhijeet Prasad (AbhiPrasad) wants to merge 1 commit into
mainfrom
abhi-openapi-datasets
Open

feat(api): generate and migrate Dataset REST resources#703
Abhijeet Prasad (AbhiPrasad) wants to merge 1 commit into
mainfrom
abhi-openapi-datasets

Conversation

@AbhiPrasad

Copy link
Copy Markdown
Member

AI Summary

Implements the Dataset slice of #683 by publishing all operations tagged Datasets and moving eligible high-level SDK workflows onto the public REST resources. Shared generated models are repartitioned across Projects, Experiments, and Datasets as their reachable schema graph expands.

Migration flow

Before
  init_dataset() -----> APP /api/dataset/register
  Dataset.fetch() ----> API /btql
  Dataset.summarize() -> API /dataset-summary

After
                         +--> POST /v1/project --------+
  init_dataset() -------|                              +--> POST /v1/dataset
                         +--> GET /v1/project/{id} -----+

  Dataset.fetch() ------> POST /v1/dataset/{id}/fetch --> backend BTQL
  Dataset.summarize() --> GET  /v1/dataset/{id}/summarize
SDK workflow Previous wire call Public REST call
Resolve/create project Combined dataset registration POST /v1/project or GET /v1/project/{id}
Resolve/create dataset POST /api/dataset/register POST /v1/dataset
Fetch ordinary records POST /btql POST /v1/dataset/{id}/fetch
Fetch filtered records POST /btql Unchanged for _internal_btql
Summarize GET /dataset-summary GET /v1/dataset/{id}/summarize
Devserver ID lookup Raw GET /v1/dataset/{id} Generated GET /v1/dataset/{id}
Insert/update/delete rows Batched /logs3 ingestion Unchanged
Resolve environments GET /environment-object/... Unchanged
Behavior Result
Dataset name omitted Send logs, matching the legacy registration UDF default
Existing project or dataset Public POST operations preserve get-or-create behavior
Registration atomicity Project and dataset creation are now two requests, matching bt
Ordinary fetch semantics REST builds the same dataset BTQL query with cursor, limit, and version
Custom BTQL semantics Continue through BTQL for filters, sampling, and total limits
Legacy output conversion Continue converting expected to output after REST fetches
Retry behavior Fetch is a safe read; project and dataset creation are idempotent writes

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c131e9bc45

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".

Comment thread py/src/braintrust/api/_generated/models/datasets.py Outdated
Comment thread py/src/braintrust/api/_generated/models/datasets.py
Implements the Dataset slice of #683 by publishing all operations tagged
Datasets and moving eligible high-level SDK workflows onto the public REST
resources. Shared generated models are repartitioned across Projects,
Experiments, and Datasets as their reachable schema graph expands.

### Migration flow

```text
Before
  init_dataset() -----> APP /api/dataset/register
  Dataset.fetch() ----> API /btql
  Dataset.summarize() -> API /dataset-summary

After
                         +--> POST /v1/project --------+
  init_dataset() -------|                              +--> POST /v1/dataset
                         +--> GET /v1/project/{id} -----+

  Dataset.fetch() ------> POST /v1/dataset/{id}/fetch --> backend BTQL
  Dataset.summarize() --> GET  /v1/dataset/{id}/summarize
```

| SDK workflow | Previous wire call | Public REST call |
| --- | --- | --- |
| Resolve/create project | Combined dataset registration | `POST /v1/project` or `GET /v1/project/{id}` |
| Resolve/create dataset | `POST /api/dataset/register` | `POST /v1/dataset` |
| Fetch ordinary records | `POST /btql` | `POST /v1/dataset/{id}/fetch` |
| Fetch filtered records | `POST /btql` | Unchanged for `_internal_btql` |
| Summarize | `GET /dataset-summary` | `GET /v1/dataset/{id}/summarize` |
| Devserver ID lookup | Raw `GET /v1/dataset/{id}` | Generated `GET /v1/dataset/{id}` |
| Insert/update/delete rows | Batched `/logs3` ingestion | Unchanged |
| Resolve environments | `GET /environment-object/...` | Unchanged |

| Behavior | Result |
| --- | --- |
| Dataset name omitted | Send `logs`, matching the legacy registration UDF default |
| Existing project or dataset | Public POST operations preserve get-or-create behavior |
| Registration atomicity | Project and dataset creation are now two requests, matching `bt` |
| Ordinary fetch semantics | REST builds the same dataset BTQL query with cursor, limit, and version |
| Custom BTQL semantics | Continue through BTQL for filters, sampling, and total limits |
| Legacy output conversion | Continue converting `expected` to `output` after REST fetches |
| Summary links | Continue using the SDK-configured `BRAINTRUST_APP_PUBLIC_URL` |
| Event wire keys | Preserve `_is_merge`, `_object_delete`, and other leading-underscore keys exactly |
| Retry behavior | Fetch is a safe read; project and dataset creation are idempotent writes |

The generated Dataset service includes create/list/get/patch/delete, insert,
GET and POST fetch, feedback, and summarize. Public request and response types
are exported from `braintrust.api.types`.

Real-backend VCR coverage exercises the complete generated surface, including
merge paths, array deletion, and row deletion, plus a high-level unnamed `logs`
dataset flow with cleanup. Unit coverage preserves pagination, pinned versions, BTQL routing, devserver lookup, lazy imports, and
package/type exports. Verification includes `test_core`, `test_types`, Pylint,
pre-commit, and API codegen drift checks.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant