OpenAPI SDK Strategy & Ownership

June 1, 2026 · View on GitHub

Purpose

This document outlines the long-term strategy, ownership, and maintenance plan for the ogx-open-client Python SDK.

Why Two Python SDKs?

OGX maintains two Python client SDKs with different generation approaches:

1. ogx_client (Official, Stainless-generated)

2. ogx-open-client (Alternative, OpenAPI Generator)

  • Repository: Distributed from main ogx repo
  • Package: ogx_open_client on PyPI
  • Generated by: OpenAPI Generator
  • Status: Alternative for OpenAPI tooling users

Strategic Rationale

Why maintain both?

  1. Risk mitigation: Following Stainless's acquisition (May 2026), maintaining an OpenAPI Generator alternative provides:

    • Independence from third-party tooling decisions
    • Fallback option if Stainless changes direction
    • Community control over SDK generation

  2. Ecosystem compatibility: Some organizations have:

    • Existing OpenAPI Generator toolchains
    • Internal policies requiring OpenAPI-spec-driven clients
    • Custom code generation workflows built on OpenAPI tools

  3. Transparency: OpenAPI Generator is:

    • Fully open source (Apache 2.0)
    • Community-driven
    • Widely adopted standard

When to Use Which SDK?

Use ogx_client (Stainless) if

  • ✅ You want the officially supported SDK
  • ✅ You prefer IDE autocomplete and type hints optimized by Stainless
  • ✅ You don't have specific OpenAPI tooling requirements

Use ogx-open-client (OpenAPI Generator) if

  • ✅ Your organization uses OpenAPI Generator for all SDKs
  • ✅ You need full control over the generation toolchain
  • ✅ You want SDK generation transparency and reproducibility
  • ✅ You integrate with OpenAPI-spec-driven testing/mocking tools

Versioning Strategy

Version Alignment

  • SDK versions track OGX server versions (semantic versioning)
  • Example: Server v1.0.3 → SDK v1.0.3
  • Pre-release versions use standard suffixes: -rc1, -alpha.1, -beta.2

Release Process

  1. Automated: Tag push openapi-sdk-v{VERSION} triggers publish
  2. Stable releases (e.g., v1.0.0) → Published to TestPyPI initially
  3. Production PyPI → Manual workflow_dispatch with approval gate
  4. Pre-releases (e.g., v1.0.0-rc1) → Built for validation, not published

Breaking Changes

  • Major version bumps (v1.x.x → v2.0.0) for breaking API changes
  • Minor version bumps (v1.0.x → v1.1.0) for new features (backward compatible)
  • Patch version bumps (v1.0.0 → v1.0.1) for bug fixes only

Ownership & Maintenance

Primary Maintainers

  • Team: OGX Core Contributors
  • Owner: Same governance as main OGX project
  • Contact: contributors@ogx.dev

PyPI Package Ownership

  • Package name: ogx-open-client
  • PyPI Organization: ogx-ai (if available) or individual maintainer accounts with 2FA
  • Trusted Publishing: Configured via GitHub Actions OIDC (no API keys in secrets)

Maintenance Commitment

  • Status: Active - Maintained in parallel with official SDK
  • CI/CD: Automated validation on every PR, automated publish on tags
  • Updates: SDK regenerated when OpenAPI spec changes
  • Support: Bug reports tracked in main ogx repo issues

Deprecation Policy

If this SDK is ever deprecated:

  1. 6 months notice minimum via GitHub discussions, blog post, and PyPI description
  2. Clear migration guide to official SDK
  3. Final LTS release with security updates only
  4. Archive notice on PyPI package page

Long-Term Vision

Current Status (2026)

  • Both SDKs maintained actively
  • OpenAPI Generator SDK provides strategic independence
  • Users choose based on tooling preferences

Potential Future Scenarios

Scenario A: Stainless remains viable

  • Continue dual-SDK approach indefinitely
  • Both SDKs maintained, users choose based on needs
  • No deprecation planned

Scenario B: Stainless becomes unavailable

  • ogx-open-client becomes primary SDK
  • Rename/promote to ogx_client (v2.0.0)
  • Seamless transition for users

Scenario C: Community prefers OpenAPI

  • Usage metrics drive decision
  • Could promote OpenAPI SDK to primary over time
  • Gradual transition with long deprecation period

Decision Criteria

Re-evaluate strategy annually based on:

  • User adoption metrics (download counts, GitHub stars)
  • Maintenance burden vs. value
  • Stainless product direction and licensing
  • Community feedback and feature requests

Incident Response

Rollback Plan

If a bad version is published to PyPI:

  1. Yank the release (doesn't delete, marks as unavailable):

    uv publish --yank ogx-open-client=={VERSION}

  2. Publish hotfix with patch version bump:

    git tag openapi-sdk-v1.0.1  # Assuming bad version was 1.0.0
git push origin openapi-sdk-v1.0.1

  3. Notify users:

    • GitHub release notes with migration instructions
    • Discord announcement in #announcements
    • Update PyPI description with warning (if critical)

Breaking Change Released Accidentally

  1. Yank the breaking release immediately
  2. Publish non-breaking version as next patch
  3. Reserve the breaking changes for next major version
  4. Post-mortem in GitHub Discussions to prevent recurrence

Contact for Emergencies

  • GitHub: @ogx-ai/core-team (mention in issue)
  • Discord: #dev-chat channel for urgent issues
  • Email: contributors@ogx.dev

Questions or Feedback?

Last updated: 2026-05-31