# WorkOS Python SDK — Agent Context

Most code in this repository is **auto-generated**. It is emitted by the
oagen pipeline from the WorkOS OpenAPI spec. It is not hand-written here,
and most bugs in it cannot be fixed here.

## The generation pipeline

| Repo | Role |
| --- | --- |
| [workos/openapi-spec](https://github.com/workos/openapi-spec) | Source of truth for the API surface (the OpenAPI spec, exported by the WorkOS API) and the orchestration entrypoint for all SDK generation |
| [workos/oagen](https://github.com/workos/oagen) | The generator engine (spec → IR → code) |
| [workos/oagen-emitters](https://github.com/workos/oagen-emitters) | The per-language emitters, including the Python emitter that produces this repo's code |

Regeneration runs from a checkout of `openapi-spec`, never from this repo:

```bash
npm run sdk:generate -- --lang python --output workos-python
```

## Generated vs. hand-maintained code

- Generated files begin with the header `# This file is auto-generated by oagen. Do not edit.` — treat them as build artifacts.
- Hand-maintained code is fenced with `@oagen-ignore-start` / `@oagen-ignore-end` markers, or lives in files marked `@oagen-ignore-file`. Only this code is editable in this repo.

## Where to fix an issue

| Symptom | Fix it in |
| --- | --- |
| Wrong or missing endpoint, field, type, or enum value | [workos/openapi-spec](https://github.com/workos/openapi-spec) (or the WorkOS API that exports the spec) |
| Generated Python code is broken or un-idiomatic | [workos/oagen-emitters](https://github.com/workos/oagen-emitters) |
| Generator behavior: naming, IR, pagination, compat checks | [workos/oagen](https://github.com/workos/oagen) |
| Code inside `@oagen-ignore` fences or ignore-marked files | This repo — edit normally |

Don't hand-edit a file that has the generated header — the next
`sdk:generate` run silently overwrites it. Instead, fix the emitter or the
spec upstream and regenerate. If a requested fix lands in a generated file,
say so and point at the upstream repo rather than patching it here.
