Skip to content

feat: generate OpenAPI clients with per-module API versions #580

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
jhamon merged 4 commits into from
Jan 28, 2026
Merged

feat: generate OpenAPI clients with per-module API versions #580

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
18c7593
feat: generate OpenAPI clients with per-module API versions
jhamon Jan 28, 2026
ca2ebf6
ci: skip linting and unit tests for PRs targeting fts branch
jhamon Jan 28, 2026
711cadf
refactor: simplify build-oas.sh branch handling
jhamon Jan 28, 2026
6a28437
refactor: simplify build-oas.sh by moving checkout before loop
jhamon Jan 28, 2026
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
4 changes: 4 additions & 0 deletions .github/workflows/on-pr.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,13 @@ concurrency:

jobs:
linting:
# Skip linting for PRs targeting fts branch until SDK compatibility work is complete
if: github.base_ref != 'fts'
uses: './.github/workflows/testing-lint.yaml'

unit-tests:
# Skip unit tests for PRs targeting fts branch until SDK compatibility work is complete
if: github.base_ref != 'fts'
uses: './.github/workflows/testing-unit.yaml'
secrets: inherit
with:
Expand Down
121 changes: 80 additions & 41 deletions codegen/build-oas.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,22 @@
#!/bin/bash

set -eux -o pipefail

version=$1 # e.g. 2025-01
set -ex -o pipefail

# Functions to get version and branch for each module
get_module_version() {
local module=$1
case "$module" in
db_control) echo "2026-01.alpha" ;;
db_data) echo "2026-01.alpha" ;;
inference) echo "2025-10" ;;
oauth) echo "2025-10" ;;
admin) echo "2025-10" ;;
*) echo "Unknown module: $module" >&2; exit 1 ;;
esac
}

# All modules use the fts branch since it contains both alpha and stable specs
APIS_BRANCH="jhamon/fts"

destination="pinecone/core/openapi"
modules=("db_control" "db_data" "inference" "oauth" "admin")
Expand All @@ -12,12 +25,14 @@ template_dir="codegen/python-oas-templates/templates5.2.0"

build_dir="build"

update_apis_repo() {
echo "Updating apis repo"
checkout_and_build_apis() {
local branch=$1

echo "Checking out and building apis repo on branch: $branch"
pushd codegen/apis
git fetch
git checkout main
git pull
git fetch origin
git checkout "$branch"
git pull origin "$branch"
just clean
just build
popd
Expand Down Expand Up @@ -61,6 +76,7 @@ verify_directory_exists() {

generate_client() {
local module_name=$1
local version=$2

oas_file="codegen/apis/_build/${version}/${module_name}_${version}.oas.yaml"
package_name="pinecone.${py_module_name}.openapi.${module_name}"
Expand Down Expand Up @@ -242,54 +258,77 @@ clean_oas_underscore_manipulation() {

db_data_destination="${destination}/db_data"

# echo "Cleaning up upsert_record.py"
sed -i '' \
-e "s/'id'/'_id'/g" \
-e 's/self.id/self._id/g' \
-e 's/id (/_id (/g' \
-e 's/= id/= _id/g' \
-e 's/id,/_id,/g' \
-e "s/'vector\'/'_vector'/g" \
-e "s/'embed\'/'_embed'/g" \
-e 's/vector (/_vector (/g' \
-e 's/embed (/_embed (/g' \
"${db_data_destination}/model/upsert_record.py"

# echo "Cleaning up hit.py"
sed -i '' \
-e "s/'id'/'_id'/g" \
-e "s/'score'/'_score'/g" \
-e 's/ id, score,/ _id, _score,/g' \
-e 's/id (/_id (/g' \
-e 's/score (/_score (/g' \
-e 's/self.id/self._id/g' \
-e 's/self.score/self._score/g' \
-e 's/= id/= _id/g' \
-e 's/= score/= _score/g' \
"${db_data_destination}/model/hit.py"
# Only run if the files exist (they may not in alpha spec)
if [ -f "${db_data_destination}/model/upsert_record.py" ]; then
sed -i '' \
-e "s/'id'/'_id'/g" \
-e 's/self.id/self._id/g' \
-e 's/id (/_id (/g' \
-e 's/= id/= _id/g' \
-e 's/id,/_id,/g' \
-e "s/'vector\'/'_vector'/g" \
-e "s/'embed\'/'_embed'/g" \
-e 's/vector (/_vector (/g' \
-e 's/embed (/_embed (/g' \
"${db_data_destination}/model/upsert_record.py"
fi

if [ -f "${db_data_destination}/model/hit.py" ]; then
sed -i '' \
-e "s/'id'/'_id'/g" \
-e "s/'score'/'_score'/g" \
-e 's/ id, score,/ _id, _score,/g' \
-e 's/id (/_id (/g' \
-e 's/score (/_score (/g' \
-e 's/self.id/self._id/g' \
-e 's/self.score/self._score/g' \
-e 's/= id/= _id/g' \
-e 's/= score/= _score/g' \
"${db_data_destination}/model/hit.py"
fi
}

update_apis_repo
# Update templates repo (same for all modules)
update_templates_repo
verify_spec_version $version

rm -rf "${destination}"
# Checkout and build apis repo (same branch for all modules)
checkout_and_build_apis "$APIS_BRANCH"

# Create destination directory if it doesn't exist
mkdir -p "${destination}"

# Track which versions have been verified
processed_versions=""

for module in "${modules[@]}"; do
generate_client $module
version=$(get_module_version "$module")

# Verify spec version exists if we haven't already
case "$processed_versions" in
*"$version"*) ;; # Already verified
*)
verify_spec_version "$version"
processed_versions="$processed_versions $version"
;;
esac

# Generate client for this module
generate_client "$module" "$version"
done

clean_oas_underscore_manipulation

# This also exists in the generated module code, but we need to reference it
# in the pinecone.openapi_support package as well without creating a circular
# dependency.
# Write api_version.py using db_data version (for gRPC compatibility)
# The db_data version is used since gRPC is data plane only
db_data_version=$(get_module_version "db_data")
version_file="pinecone/openapi_support/api_version.py"
echo "# This file is generated by codegen/build-oas.sh" > $version_file
echo "# Do not edit this file manually." >> $version_file
echo "# For REST APIs, use the API_VERSION from each module's __init__.py" >> $version_file
echo "# This version is used by gRPC clients (data plane only)" >> $version_file
echo "" >> $version_file

echo "API_VERSION = '${version}'" >> $version_file
echo "API_VERSION = '${db_data_version}'" >> $version_file
echo "APIS_REPO_SHA = '$(git rev-parse :codegen/apis)'" >> $version_file

# Even though we want to generate multiple packages, we
Expand Down
27 changes: 11 additions & 16 deletions pinecone/core/openapi/admin/api/api_keys_api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

from __future__ import annotations

from typing import TYPE_CHECKING, Any, Dict, cast
from typing import TYPE_CHECKING
Copy link

@cursor cursor bot Jan 28, 2026

Choose a reason for hiding this comment

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

Unused TYPE_CHECKING import in generated API files

Low Severity

The TYPE_CHECKING constant is imported from typing but is never used in these files. There is no if TYPE_CHECKING: block anywhere in the file - TYPE_CHECKING only appears in the import statement itself. This affects api_keys_api.py, organizations_api.py, projects_api.py, manage_indexes_api.py, and bulk_operations_api.py. The PR changed the import from from typing import TYPE_CHECKING, Any, Dict, cast to from typing import TYPE_CHECKING, removing cast usage but leaving the unused TYPE_CHECKING.

Additional Locations (2)

Fix in Cursor Fix in Web

from multiprocessing.pool import ApplyResult

from pinecone.openapi_support import ApiClient, AsyncioApiClient
Expand Down Expand Up @@ -95,9 +95,7 @@ def __create_api_key(
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["project_id"] = project_id
kwargs["create_api_key_request"] = create_api_key_request
return cast(
APIKeyWithSecret | ApplyResult[APIKeyWithSecret], self.call_with_http_info(**kwargs)
)
return self.call_with_http_info(**kwargs)

self.create_api_key = _Endpoint(
settings={
Expand Down Expand Up @@ -184,7 +182,7 @@ def __delete_api_key(
kwargs = self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["api_key_id"] = api_key_id
return cast(None, self.call_with_http_info(**kwargs))
return self.call_with_http_info(**kwargs)

self.delete_api_key = _Endpoint(
settings={
Expand Down Expand Up @@ -263,7 +261,7 @@ def __fetch_api_key(
kwargs = self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["api_key_id"] = api_key_id
return cast(APIKey | ApplyResult[APIKey], self.call_with_http_info(**kwargs))
return self.call_with_http_info(**kwargs)

self.fetch_api_key = _Endpoint(
settings={
Expand Down Expand Up @@ -342,10 +340,7 @@ def __list_project_api_keys(
kwargs = self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["project_id"] = project_id
return cast(
ListApiKeysResponse | ApplyResult[ListApiKeysResponse],
self.call_with_http_info(**kwargs),
)
return self.call_with_http_info(**kwargs)

self.list_project_api_keys = _Endpoint(
settings={
Expand Down Expand Up @@ -427,7 +422,7 @@ def __update_api_key(
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["api_key_id"] = api_key_id
kwargs["update_api_key_request"] = update_api_key_request
return cast(APIKey | ApplyResult[APIKey], self.call_with_http_info(**kwargs))
return self.call_with_http_info(**kwargs)

self.update_api_key = _Endpoint(
settings={
Expand Down Expand Up @@ -518,7 +513,7 @@ async def __create_api_key(
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["project_id"] = project_id
kwargs["create_api_key_request"] = create_api_key_request
return cast(APIKeyWithSecret, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.create_api_key = _AsyncioEndpoint(
settings={
Expand Down Expand Up @@ -595,7 +590,7 @@ async def __delete_api_key(
self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["api_key_id"] = api_key_id
return cast(None, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.delete_api_key = _AsyncioEndpoint(
settings={
Expand Down Expand Up @@ -664,7 +659,7 @@ async def __fetch_api_key(
self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["api_key_id"] = api_key_id
return cast(APIKey, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.fetch_api_key = _AsyncioEndpoint(
settings={
Expand Down Expand Up @@ -733,7 +728,7 @@ async def __list_project_api_keys(
self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["project_id"] = project_id
return cast(ListApiKeysResponse, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.list_project_api_keys = _AsyncioEndpoint(
settings={
Expand Down Expand Up @@ -804,7 +799,7 @@ async def __update_api_key(
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["api_key_id"] = api_key_id
kwargs["update_api_key_request"] = update_api_key_request
return cast(APIKey, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.update_api_key = _AsyncioEndpoint(
settings={
Expand Down
24 changes: 9 additions & 15 deletions pinecone/core/openapi/admin/api/organizations_api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

from __future__ import annotations

from typing import TYPE_CHECKING, Any, Dict, cast
from typing import TYPE_CHECKING
from multiprocessing.pool import ApplyResult

from pinecone.openapi_support import ApiClient, AsyncioApiClient
Expand Down Expand Up @@ -90,7 +90,7 @@ def __delete_organization(
kwargs = self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["organization_id"] = organization_id
return cast(None, self.call_with_http_info(**kwargs))
return self.call_with_http_info(**kwargs)

self.delete_organization = _Endpoint(
settings={
Expand Down Expand Up @@ -169,9 +169,7 @@ def __fetch_organization(
kwargs = self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["organization_id"] = organization_id
return cast(
Organization | ApplyResult[Organization], self.call_with_http_info(**kwargs)
)
return self.call_with_http_info(**kwargs)

self.fetch_organization = _Endpoint(
settings={
Expand Down Expand Up @@ -245,9 +243,7 @@ def __list_organizations(
"""
kwargs = self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
return cast(
OrganizationList | ApplyResult[OrganizationList], self.call_with_http_info(**kwargs)
)
return self.call_with_http_info(**kwargs)

self.list_organizations = _Endpoint(
settings={
Expand Down Expand Up @@ -326,9 +322,7 @@ def __update_organization(
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["organization_id"] = organization_id
kwargs["update_organization_request"] = update_organization_request
return cast(
Organization | ApplyResult[Organization], self.call_with_http_info(**kwargs)
)
return self.call_with_http_info(**kwargs)

self.update_organization = _Endpoint(
settings={
Expand Down Expand Up @@ -421,7 +415,7 @@ async def __delete_organization(
self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["organization_id"] = organization_id
return cast(None, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.delete_organization = _AsyncioEndpoint(
settings={
Expand Down Expand Up @@ -490,7 +484,7 @@ async def __fetch_organization(
self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["organization_id"] = organization_id
return cast(Organization, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.fetch_organization = _AsyncioEndpoint(
settings={
Expand Down Expand Up @@ -557,7 +551,7 @@ async def __list_organizations(
"""
self._process_openapi_kwargs(kwargs)
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
return cast(OrganizationList, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.list_organizations = _AsyncioEndpoint(
settings={
Expand Down Expand Up @@ -629,7 +623,7 @@ async def __update_organization(
kwargs["x_pinecone_api_version"] = x_pinecone_api_version
kwargs["organization_id"] = organization_id
kwargs["update_organization_request"] = update_organization_request
return cast(Organization, await self.call_with_http_info(**kwargs))
return await self.call_with_http_info(**kwargs)

self.update_organization = _AsyncioEndpoint(
settings={
Expand Down
Loading