Skip to content

AGENTS.md

Latest commit

 

History

History
48 lines (33 loc) · 2.2 KB

AGENTS.md

File metadata and controls

48 lines (33 loc) · 2.2 KB
Raw

Agent Guidelines for airbyte-api-python-sdk

For the full contributor guide (code generation lineage, build commands, release process, and debugging generation drift), see CONTRIBUTING.md.

Key Principle: This Is a Generated Codebase

Most code under src/airbyte_api/ is generated by Speakeasy. Do not hand-edit generated files. To make durable changes, work at the correct layer (overlay, post-generation script, or upstream spec). See CONTRIBUTING.md — Code Generation Lineage.

Generation Drift

When a drift CI check fails, download the generated artifacts and compare. See CONTRIBUTING.md — Debugging Generation Drift Failures.

Do not guess or iterate blindly. Download the artifact first.

Files You Can Safely Edit

  • overlays/python_speakeasy.yaml — Speakeasy overlay
  • scripts/post_generate.uv — Post-generation patch script (standalone uv script)
  • poe_tasks.toml — Build task definitions
  • .github/workflows/ — CI workflows
  • .github/dependabot.yml — Dependabot configuration
  • .github/speakeasy/dummy-compose.yml — Speakeasy CLI version pin
  • .speakeasy/workflow.yaml — Speakeasy workflow configuration
  • gen.yaml — Speakeasy generator configuration
  • pyproject.toml — Human-managed (excluded from Speakeasy via .genignore)
  • CONTRIBUTING.md, AGENTS.md, README.md — Documentation

Files You Must NOT Edit By Hand

  • src/airbyte_api/ — Generated by Speakeasy
  • py.typed — Generated by Speakeasy

Build Commands

uv run poe generate-full    # Full pipeline (generate + readme + patches)
uv run poe build            # Build the Python package
uv run poe lint             # Lint checks
uv run poe fix              # Auto-fix lint/format
uv run poe test             # Run tests
uv run poe typecheck        # Type checking

Regenerating the SDK

Use the /generate slash command on a PR, or trigger manually from Actions > Generate SDK.

Do not attempt to run speakeasy run locally — the SPEAKEASY_API_KEY is only available in CI.