feat: add Python types publishing workflow for type-safe API consumption

[rainer-friederich]

Summary

• Add docs:bundle script using existing @redocly/cli to produce a single-file openapi.json
• Add publish-types CD workflow that triggers on GitHub releases, bundles the spec, runs datamodel-codegen to generate Pydantic v2 models, and publishes to a types-py orphan branch with version tags
• Add Python package skeleton (clients/python/) for the spacecat-api-types package

Follows the same orphan-branch pattern as mysticat-data-service (cd.yml publish-types job). No existing code, tests, or CI workflows are modified — all changes are additive.

Why

DRS calls the SpaceCat API via spacecat_client.py (~1900 lines) with all responses typed as Dict[str, Any] — no type safety. Bugs like adobe-rnd/llmo-data-retrieval-service#1155 (sending {"prompts": prompts} instead of the raw prompts array) only surface at runtime during live onboarding. With generated Pydantic models and mypy coverage, these shape mismatches get caught at PR time instead.

This PR is the API service's contribution: publish the spec as installable Python types so DRS can consume them. The DRS side (replacing Dict[str, Any] with typed models, extending mypy scope) is tracked in adobe-rnd/llmo-data-retrieval-service#1164.

How it works

On each GitHub release (created by semantic-release):

1. Bundle the multi-file OpenAPI spec into a single JSON
2. Run datamodel-codegen --snake-case-field to generate Pydantic v2 models
3. Push to types-py orphan branch + create version tag

DRS installs via:

spacecat-api-types @ git+https://github.com/adobe/spacecat-api-service.git@types-py-v1.393.0

Generated models use snake_case fields with camelCase aliases:

site.base_url          # Python access (snake_case)
Field(alias='baseURL') # Matches API response (camelCase)

Changes

File	Change
package.json	Add docs:bundle script
.gitignore	Add docs/openapi/dist/ and generated models.py
clients/python/	New — package skeleton (pyproject.toml, init.py, README)
.github/workflows/publish-types.yaml	New — CD workflow

Test plan

• npm run docs:lint — passes
• npm run docs:bundle — produces valid bundled openapi.json
• datamodel-codegen on bundled spec — generates valid Python with correct field names/aliases
• npm test — all 7005 tests pass, no regressions
• Verify publish-types.yaml workflow runs on next release

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a minor release when merged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!