feat(api): generate Projects REST bindings

Implements step 2 of #683.

This adds the first public resource backed by generated REST bindings:

- `BraintrustClient.projects`: synchronous create, list, get, update, and delete methods
- `braintrust.api.types`: public `CreateProject`, `PatchProject`, `Project`, and `ProjectList` types

Generated code is organized by OpenAPI tag:

    braintrust/api/_generated/
    ├── models/
    │   ├── projects.py
    │   └── shared.py
    ├── operations/
    │   └── projects.py
    └── resources/
        └── projects.py

Models referenced by one tag live with that tag; cross-tag and unowned models
live in `models/shared.py`. Operation metadata remains separate from the thin,
typed resource functions that execute it.

The generated bindings reuse the existing resource transport, authentication,
routing, retry policies, and error handling. The adapter serializes generated
path, query, header, and JSON body parameters and decodes JSON, text, and empty
responses.

Projects is enabled declaratively through `endpoint_generator.generated_tags`,
with naming and retry overrides kept in `openapi/config.json`. Generation remains
offline and deterministic, and codegen drift checks replace the generated tree
atomically so stale files cannot survive a layout change.

Coverage includes exact wire behavior, additive response fields, operation
policies, typing, generated package contents, inline-schema conflicts, and a
cassette-backed end-to-end Projects flow.

Author: AbhiPrasad

openapi/README.md

@@ -13,7 +13,12 @@ make generate-api-client
 make check-api-client-codegen
 ```
 
-The check regenerates into a temporary directory and does not modify the worktree.
+The check regenerates into a temporary directory and does not modify the worktree. Endpoint bindings
+are rolled out explicitly through `endpoint_generator.generated_tags`; adding a tag expands the
+committed operation registry and resource bindings. Generated models and operations are split by
+OpenAPI tag under `models/` and `operations/`; models referenced by multiple tags live in
+`models/shared.py`. Ergonomic naming and runtime-policy overrides remain declarative in the same
+configuration.
 
 To fetch the configured upstream commit explicitly:
 

openapi/config.json

@@ -21,14 +21,41 @@
       "--use-generic-container-types",
       "--use-field-description",
       "--strict-nullable",
-      "--parent-scoped-naming",
+      "--naming-strategy=primary-first",
+      "--treat-dot-as-module",
       "--no-use-closed-typed-dict",
       "--disable-future-imports",
       "--formatters=ruff-format"
     ]
   },
   "endpoint_generator": {
     "schema_version": 1,
+    "generated_tags": [
+      "Projects"
+    ],
+    "naming_overrides": {
+      "postProject": {
+        "method_name": "create"
+      },
+      "getProject": {
+        "method_name": "list",
+        "response_type": "ProjectList"
+      },
+      "getProjectId": {
+        "method_name": "get"
+      },
+      "patchProjectId": {
+        "method_name": "update"
+      },
+      "deleteProjectId": {
+        "method_name": "delete"
+      }
+    },
+    "runtime_policy_overrides": {
+      "postProject": {
+        "retry_mode": "IDEMPOTENT_WRITE"
+      }
+    },
     "skip_tags": {
       "Proxy": {
         "reason": "Proxy endpoints stream provider-specific payloads and remain on the specialized proxy path.",

py/scripts/openapi_codegen.py

@@ -0,0 +1,162 @@
+"""Runtime adapter for generated REST operation bindings."""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import Any
+from urllib.parse import quote
+
+from ._routing import RequestTarget
+from ._service import ResourceAPI
+from .errors import BraintrustResponseError
+from .policies import RetryMode, RetryPolicy
+
+
+@dataclass(frozen=True)
+class Parameter:
+    """Serialization metadata for one generated operation parameter."""
+
+    argument_name: str
+    name: str
+    location: str
+    type_name: str
+    required: bool
+    style: str
+    explode: bool
+
+
+@dataclass(frozen=True)
+class Operation:
+    """Resolved wire and runtime-policy metadata for a generated operation."""
+
+    operation_id: str
+    method: str
+    path: str
+    tag: str
+    parameters: tuple[Parameter, ...]
+    request_body_type: str | None
+    request_body_required: bool
+    response_type: str | None
+    success_statuses: tuple[int, ...]
+    response_media_type: str | None
+    target: RequestTarget
+    retry_mode: RetryMode
+    timeout: float | None = None
+    max_elapsed_time: float | None = None
+
+
+class GeneratedOperationAdapter(ResourceAPI):
+    """Execute generated operation metadata through the shared resource transport."""
+
+    def execute(
+        self,
+        operation: Operation,
+        *,
+        path_parameters: Mapping[str, Any] | None = None,
+        query_parameters: Mapping[str, Any] | None = None,
+        header_parameters: Mapping[str, Any] | None = None,
+        body: Any = None,
+    ) -> Any:
+        path_values = path_parameters or {}
+        query_values = query_parameters or {}
+        header_values = header_parameters or {}
+        path = operation.path
+        query_parts: list[str] = []
+        headers: dict[str, str] = {}
+
+        for parameter in operation.parameters:
+            values = {
+                "path": path_values,
+                "query": query_values,
+                "header": header_values,
+            }.get(parameter.location)
+            if values is None:
+                raise ValueError(f"Unsupported generated parameter location: {parameter.location!r}")
+            value = values.get(parameter.argument_name)
+            if value is None:
+                if parameter.required:
+                    raise TypeError(f"Missing required parameter: {parameter.argument_name}")
+                continue
+            if parameter.location == "path":
+                encoded = _encode_path_parameter(value, parameter)
+                path = path.replace("{" + parameter.name + "}", encoded)
+            elif parameter.location == "query":
+                query_parts.extend(_encode_query_parameter(value, parameter))
+            else:
+                headers[parameter.name] = _scalar_string(value)
+
+        if query_parts:
+            path += ("&" if "?" in path else "?") + "&".join(query_parts)
+
+        request_kwargs: dict[str, Any] = {"retry_mode": operation.retry_mode}
+        if operation.timeout is not None or operation.max_elapsed_time is not None:
+            policy = RetryPolicy.for_mode(operation.retry_mode)
+            replacements = {}
+            if operation.timeout is not None:
+                replacements["timeout"] = operation.timeout
+            if operation.max_elapsed_time is not None:
+                replacements["max_elapsed_time"] = operation.max_elapsed_time
+            request_kwargs["retry_policy"] = replace(policy, **replacements)
+        if headers:
+            request_kwargs["headers"] = headers
+        if operation.request_body_required and body is None:
+            raise TypeError(f"Missing required request body for {operation.operation_id}")
+        if operation.request_body_type is not None and body is not None:
+            request_kwargs["json"] = body
+
+        response = self._request(operation.target, operation.method, path, **request_kwargs)
+        if response.status_code not in operation.success_statuses:
+            expected_statuses = ", ".join(str(status) for status in operation.success_statuses)
+            raise BraintrustResponseError(
+                method=operation.method,
+                url=response.url,
+                status_code=response.status_code,
+                response_body=response.text,
+                response_headers=response.headers,
+                attempts=getattr(response, "_braintrust_attempts", 1),
+                message=(
+                    f"{operation.method} {response.url} returned unexpected HTTP status {response.status_code}; "
+                    f"expected one of: {expected_statuses}"
+                ),
+            )
+        if operation.response_type is None:
+            return None
+
+        media_type = operation.response_media_type
+        if media_type is None:
+            media_type = response.headers.get("Content-Type", "").partition(";")[0].strip().lower() or None
+        if media_type == "application/json":
+            return self._transport.decode_json_response(response, method=operation.method, url=response.url)
+        if media_type == "text/plain":
+            return response.text
+        raise ValueError(f"Unsupported generated response media type: {media_type!r}")
+
+
+def _encode_path_parameter(value: Any, parameter: Parameter) -> str:
+    if parameter.style != "simple":
+        raise ValueError(f"Unsupported path parameter style: {parameter.style!r}")
+    if _is_array(value):
+        value = ",".join(_scalar_string(item) for item in value)
+    return quote(_scalar_string(value), safe="")
+
+
+def _encode_query_parameter(value: Any, parameter: Parameter) -> list[str]:
+    if parameter.style != "form":
+        raise ValueError(f"Unsupported query parameter style: {parameter.style!r}")
+    encoded_name = quote(parameter.name, safe="")
+    if _is_array(value):
+        encoded_values = [quote(_scalar_string(item), safe="") for item in value]
+        if parameter.explode:
+            return [f"{encoded_name}={item}" for item in encoded_values]
+        return [f"{encoded_name}={','.join(encoded_values)}"]
+    encoded_value = quote(_scalar_string(value), safe="")
+    return [f"{encoded_name}={encoded_value}"]
+
+
+def _is_array(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray))
+
+
+def _scalar_string(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)