@lovrozagar/honey 0.6.8 → 0.7.0

package/src/codegen-python.ts

@@ -1,10 +1,19 @@
-/** Python SDK code generator. Mirrors TS SDK emitter in codegen.ts. */
+/** Python SDK code generator.
+ *
+ * Input is the SDK request model (codegen-sdk-model.ts). Identifiers come from per-scope
+ * NameScopes (module, class, method) and every spec string reaches source through pyString,
+ * docstring or comment writers (codegen-lang.ts).
+ */
 
 import { readFileSync } from "node:fs"
-import { extractOpenApiPathParams, isSSEOperation } from "./codegen.ts"
-import { methodsOf, namespacesOf, toIR } from "./codegen-ir.ts"
-import type { IRNamespace } from "./codegen-ir.ts"
-import { jsonSchemaToPy, pyIdent } from "./python-type-emitter.ts"
+import type { OpenApiSpecInput } from "./codegen.ts"
+import { methodsOf, namespacesOf } from "./codegen-ir.ts"
+import type { IRNamespace, IRSchema } from "./codegen-ir.ts"
+import { NameScope, cmpCodeUnit, pyClassName, pyDocLines, pyIdentifier, pyString } from "./codegen-lang.ts"
+import { buildSdkModel } from "./codegen-sdk-model.ts"
+import type { SdkModel, SdkOp } from "./codegen-sdk-model.ts"
+import { irToPythonNamed, isPyAttributeKey, pyIdent } from "./python-type-emitter.ts"
+import type { PyTypeNames } from "./python-type-emitter.ts"
 
 interface PySDKOptions {
 	name?: string
@@ -25,33 +34,6 @@ interface PySDKResult {
 	serviceMap: Record<string, ServiceMapEntry>
 }
 
-interface OperationInfo {
-	operationId: string
-	method: string
-	path: string
-	summary?: string
-	description?: string
-	pathParams: string[]
-	queryParams: ParamInfo[]
-	bodySchema: Record<string, unknown> | undefined
-	bodyRequired: boolean
-	bodyIsStream: boolean
-	successType: string
-	errorStatuses: number[]
-	isSSE: boolean
-	isWS: boolean
-	isRealtime: boolean
-	isIdempotent: boolean
-	invalidate: string[]
-	parameters: Array<{ in: string; name: string; required: boolean; schema: Record<string, unknown> }>
-}
-
-interface ParamInfo {
-	name: string
-	required: boolean
-	schema: Record<string, unknown>
-}
-
 const PYTHON_FUTURE = "from __future__ import annotations"
 const STATIC_FILE_NAMES = [
 	"_runtime.py",
@@ -63,11 +45,6 @@ const STATIC_FILE_NAMES = [
 	"_realtime.py",
 ] as const
 const RUNTIME_TEMPLATE_CACHE = new Map<string, string>()
-const WS_EXTENSION = "x-websocket"
-const REALTIME_EXTENSION = "x-realtime"
-const INVALIDATE_EXTENSION = "x-invalidate"
-const IDEMPOTENCY_EXTENSION = "x-idempotency-key"
-const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"] as const
 
 const ERROR_NAMES: Record<number, string> = {
 	400: "BadRequestError",
@@ -83,6 +60,69 @@ const ERROR_NAMES: Record<number, string> = {
 	504: "GatewayTimeoutError",
 }
 
+const ERROR_CLASSES = [
+	"APIError",
+	"APIStatusError",
+	"BadGatewayError",
+	"BadRequestError",
+	"ConflictError",
+	"ForbiddenError",
+	"GatewayTimeoutError",
+	"InternalServerError",
+	"NotFoundError",
+	"RateLimitError",
+	"ServiceUnavailableError",
+	"UnauthorizedError",
+	"UnprocessableEntityError",
+]
+
+const TRANSPORT_EXPORTS = [
+	"LongpollAdapter",
+	"SseAdapter",
+	"TransportAdapter",
+	"TransportConn",
+	"TransportKind",
+	"TransportOpts",
+	"WsAdapter",
+]
+
+const REALTIME_EXPORTS = ["ConnectionState", "ResumableConnection"]
+
+/** Names a generated module-level type must not take: package exports, typing and builtins. */
+const PY_MODULE_RESERVED = [
+	"AsyncSDK",
+	"SDK",
+	...ERROR_CLASSES,
+	...TRANSPORT_EXPORTS,
+	...REALTIME_EXPORTS,
+	"ClientConfig",
+	"InvalidationConfig",
+	"SDKResult",
+	"SSEEvent",
+	"PathParamError",
+	"FileInput",
+	"Any",
+	"AsyncIterator",
+	"Literal",
+	"NotRequired",
+	"TypeAlias",
+	"TypedDict",
+	"bool",
+	"bytes",
+	"dict",
+	"float",
+	"int",
+	"list",
+	"object",
+	"str",
+	"tuple",
+	"type",
+	"httpx",
+	"asyncio",
+	"threading",
+	"uuid",
+]
+
 export function loadPythonRuntimeTemplates(): Map<string, string> {
 	if (RUNTIME_TEMPLATE_CACHE.size > 0) return RUNTIME_TEMPLATE_CACHE
 	for (const name of STATIC_FILE_NAMES) {
@@ -93,845 +133,702 @@ export function loadPythonRuntimeTemplates(): Map<string, string> {
 	return RUNTIME_TEMPLATE_CACHE
 }
 
-function resolveSchema(
-	spec: Record<string, unknown>,
-	schema: Record<string, unknown> | undefined,
-): Record<string, unknown> | undefined {
-	if (!schema) return undefined
-	if (!schema.$ref) return schema
-	const ref = schema.$ref as string
-	const parts = ref.replace(/^#\//, "").split("/")
-	let cur: unknown = spec
-	for (const part of parts) {
-		cur = (cur as Record<string, unknown>)[part]
-	}
-	return cur as Record<string, unknown> | undefined
-}
+/* ── types ── */
 
-function getSuccessType(spec: Record<string, unknown>, operation: Record<string, unknown>): string {
-	const responses = operation.responses as Record<string, Record<string, unknown>> | undefined
-	if (!responses) return "None"
-	const successCodes = ["200", "201", "202", "204"]
-	for (const code of successCodes) {
-		const resp = responses[code]
-		if (!resp) continue
-		if (code === "204") return "None"
-		const content = resp.content as Record<string, Record<string, unknown>> | undefined
-		if (!content) continue
-		const jsonContent = content["application/json"]
-		if (!jsonContent) continue
-		const schema = resolveSchema(spec, jsonContent.schema as Record<string, unknown> | undefined)
-		if (!schema) continue
-		const rawRef = (jsonContent.schema as Record<string, unknown> | undefined)?.$ref as string | undefined
-		if (rawRef) {
-			const parts = rawRef.split("/")
-			return parts[parts.length - 1]
-		}
-		return jsonSchemaToPy(schema, 0)
-	}
-	return "None"
+type PyNames = {
+	module: NameScope
+	types: PyTypeNames
+	/** class name → source, for every emitted type (schemas first, then hoisted). */
+	decls: Map<string, string>
+	declOrder: string[]
+	schemaNames: Map<string, string>
 }
 
-function getErrorStatuses(operation: Record<string, unknown>): number[] {
-	const responses = operation.responses as Record<string, Record<string, unknown>> | undefined
-	if (!responses) return []
-	return Object.keys(responses)
-		.map(Number)
-		.filter((n) => n >= 400)
-		.sort()
+function typedDictSource(name: string, ir: Extract<IRSchema, { kind: "object" }>, names: PyTypeNames): string {
+	const fields = ir.fields.slice().sort((a, b) => cmpCodeUnit(a.name, b.name))
+	const rendered = fields.map((f) => {
+		const t = irToPythonNamed(f.schema, names, name, f.name)
+		return { annotation: f.required ? t : `NotRequired[${t}]`, field: f }
+	})
+	if (fields.every((f) => isPyAttributeKey(f.name))) {
+		const l = [`class ${name}(TypedDict, total=False):`]
+		for (const r of rendered) l.push(`    ${r.field.name}: ${r.annotation}`)
+		if (rendered.length === 0) l.push(`    pass`)
+		return l.join("\n")
+	}
+	/* functional syntax: any JSON key is allowed; annotations are strings, so forward refs work */
+	const l = [`${name} = TypedDict(`, `    ${pyString(name)},`, `    {`]
+	for (const r of rendered) l.push(`        ${pyString(r.field.name)}: ${pyString(r.annotation)},`)
+	l.push(`    },`, `    total=False,`, `)`)
+	return l.join("\n")
 }
 
-function collectOperations(spec: Record<string, unknown>): OperationInfo[] {
-	const paths = spec.paths as Record<string, Record<string, unknown>> | undefined
-	if (!paths) return []
-	const ops: OperationInfo[] = []
-
-	for (const [path, pathItem] of Object.entries(paths)) {
-		for (const httpMethod of HTTP_METHODS) {
-			const operation = pathItem[httpMethod] as Record<string, unknown> | undefined
-			if (!operation) continue
-			const operationId = operation.operationId as string | undefined
-			if (!operationId) continue
-
-			const rawParams = (operation.parameters ?? []) as Array<Record<string, unknown>>
-			const pathParams = extractOpenApiPathParams(path)
-			const queryParams: ParamInfo[] = rawParams
-				.filter((p) => p.in === "query")
-				.map((p) => ({
-					name: p.name as string,
-					required: p.required === true,
-					schema: (p.schema ?? {}) as Record<string, unknown>,
-				}))
-
-			const requestBody = operation.requestBody as Record<string, unknown> | undefined
-			let bodySchema: Record<string, unknown> | undefined
-			let bodyIsStream = false
-			const bodyRequired = requestBody?.required === true
-			if (requestBody) {
-				const content = requestBody.content as Record<string, Record<string, unknown>> | undefined
-				const jsonContent = content?.["application/json"]
-				const octetContent = content?.["application/octet-stream"]
-				if (octetContent) {
-					bodyIsStream = true
-				} else if (jsonContent) {
-					const rawSchema = jsonContent.schema as Record<string, unknown> | undefined
-					bodySchema = resolveSchema(spec, rawSchema)
-					if (rawSchema?.$ref) {
-						const refParts = (rawSchema.$ref as string).split("/")
-						bodySchema = { $ref: rawSchema.$ref, _refName: refParts[refParts.length - 1] }
-					}
-				}
-			}
+function buildPyNames(model: SdkModel): PyNames {
+	const module = new NameScope(PY_MODULE_RESERVED)
+	const schemaNames = new Map<string, string>()
+	for (const name of model.schemaNames) {
+		const base = pyClassName(name)
+		schemaNames.set(name, module.has(base) ? module.claim(`${base}Model`) : module.claim(base))
+	}
+	const decls = new Map<string, string>()
+	const declOrder: string[] = []
+	const hoistKeys = new Map<string, string>()
+	const names: PyNames = { declOrder, decls, module, schemaNames, types: undefined as unknown as PyTypeNames }
+	names.types = {
+		hoist: (key, base, schema) => {
+			const hit = hoistKeys.get(key)
+			if (hit) return hit
+			const name = module.claim(pyClassName(base))
+			hoistKeys.set(key, name)
+			decls.set(name, "")
+			declOrder.push(name)
+			decls.set(name, typedDictSource(name, schema, names.types))
+			return name
+		},
+		ref: (name) => schemaNames.get(name) ?? pyClassName(name),
+	}
+	return names
+}
 
-			const isRealtime = operation[REALTIME_EXTENSION] === true
-			ops.push({
-				bodyIsStream,
-				bodyRequired,
-				bodySchema,
-				description: operation.description as string | undefined,
-				errorStatuses: getErrorStatuses(operation),
-				invalidate: (operation[INVALIDATE_EXTENSION] as string[] | undefined) ?? [],
-				isIdempotent: operation[IDEMPOTENCY_EXTENSION] === true,
-				/* realtime wins over SSE / WS when extensions conflict — higher-level protocol */
-				isRealtime,
-				isSSE: !isRealtime && isSSEOperation(operation),
-				isWS: !isRealtime && operation[WS_EXTENSION] === true,
-				method: httpMethod.toUpperCase(),
-				operationId,
-				parameters: rawParams as Array<{
-					in: string
-					name: string
-					required: boolean
-					schema: Record<string, unknown>
-				}>,
-				path,
-				pathParams,
-				queryParams,
-				successType: getSuccessType(spec, operation),
-				summary: operation.summary as string | undefined,
-			})
+function buildPyTypes(model: SdkModel, names: PyNames): string {
+	const body: string[] = []
+	for (const name of model.schemaNames) {
+		const ir = model.ir.schemas[name]
+		const pyName = names.types.ref(name)
+		if (ir.kind === "object" && ir.fields.length > 0) {
+			body.push(typedDictSource(pyName, ir, names.types))
+		} else {
+			/* string alias: lazy, so the order of definitions does not matter */
+			const t = irToPythonNamed(ir, names.types, pyName, "")
+			body.push(`${pyName}: TypeAlias = ${pyString(t)}`)
 		}
+		body.push("")
 	}
-
-	return ops
-}
-
-function nestedClassName(path: string[]): string {
-	const pascal = path
-		.map((seg) => {
-			const safe = pyIdent(seg)
-			return safe.charAt(0).toUpperCase() + safe.slice(1)
-		})
-		.join("")
-	return `_${pascal}Resource`
+	return body.join("\n")
 }
 
-function collectSDKMethods(spec: Record<string, unknown>): {
-	tree: IRNamespace
-	topLevel: OperationInfo[]
-	opsByOpId: Map<string, OperationInfo>
-} {
-	const ops = collectOperations(spec)
-	const ir = toIR(spec as Parameters<typeof toIR>[0])
-	const topLevel: OperationInfo[] = []
-	const opsByOpId = new Map<string, OperationInfo>()
-
-	for (const op of ops) {
-		opsByOpId.set(op.operationId, op)
-		if (!op.operationId.includes(".")) {
-			topLevel.push(op)
-		}
+function typesFile(schemaSource: string, names: PyNames): string {
+	const hoisted = names.declOrder.map((n) => `${names.decls.get(n)}\n`).join("\n")
+	const bodyText = `${schemaSource}\n${hoisted}`
+	const typing = ["Any", "Literal", "NotRequired", "TypeAlias", "TypedDict"].filter((sym) =>
+		new RegExp(`\\b${sym}\\b`).test(bodyText),
+	)
+	const fileInput = /\bFileInput\b/.test(bodyText)
+	/* string aliases mention `Any`/`Literal` only inside quotes; keep them importable for checkers */
+	if (/TypeAlias = /.test(bodyText)) {
+		for (const sym of ["Any", "Literal"]) if (!typing.includes(sym)) typing.push(sym)
 	}
-
-	return { opsByOpId, topLevel, tree: ir.tree }
+	const l: string[] = []
+	l.push("# ruff: noqa: E501")
+	l.push(PYTHON_FUTURE)
+	l.push("")
+	if (typing.length > 0) l.push(`from typing import ${typing.sort(cmpCodeUnit).join(", ")}`)
+	if (fileInput) l.push(`from ._runtime import FileInput`)
+	if (typing.length > 0 || fileInput) l.push("")
+	l.push(bodyText)
+	const exported = [...names.schemaNames.values(), ...names.declOrder]
+	if (exported.length === 0) l.push("__all__: list[str] = []")
+	else l.push(`__all__ = [${exported.map(pyString).join(", ")}]`)
+	l.push("")
+	return l.join("\n")
 }
 
-function pyParamName(name: string): string {
-	const safe = name.replace(/[^a-zA-Z0-9_]/g, "_").replace(/^([0-9])/, "_$1")
-	return pyIdent(safe)
-}
+/* ── client ── */
 
-function bodyTypeName(bodySchema: Record<string, unknown> | undefined): string {
-	if (!bodySchema) return "Any"
-	const refName = bodySchema._refName as string | undefined
-	if (refName) return refName
-	return "Any"
-}
+type PyParam = { local: string; wire: string }
 
-function buildMethodSignature(op: OperationInfo, throwOnError: boolean, isAsync: boolean): string[] {
-	const lines: string[] = []
-	/* WS methods just construct the _TypedWebSocket context-manager — no async
-	 * work happens until __aenter__; emit as sync `def` matching TS / Go / Rust
-	 * surface (caller awaits __aenter__ via `async with`, not the constructor). */
-	let defKw: string
-	if (op.isWS) defKw = "def"
-	else if (isAsync) defKw = "async def"
-	else defKw = "def"
-	const segments = op.operationId.split(".")
-	const actionPart = segments[segments.length - 1] ?? op.operationId
-	/* convert camelCase to snake_case for Python naming convention */
-	const snakeAction = actionPart.replace(/([A-Z])/g, (m) => `_${m.toLowerCase()}`).replace(/^_/, "")
-	const ident = pyIdent(snakeAction)
-	/* realtime method always named `connect<X>` — follow camelCase convention used elsewhere
-	 * in the emitted SDK (connectWs, createUser). If operationId already begins with "connect",
-	 * use verbatim; otherwise prepend "connect" + capitalize first char of action. */
-	const alreadyConnectPrefixed = /^connect([A-Z_]|$)/.test(ident)
-	const realtimeName = alreadyConnectPrefixed ? ident : `connect${ident.charAt(0).toUpperCase()}${ident.slice(1)}`
-	const methodName = op.isRealtime ? realtimeName : ident
-
-	const posArgs: string[] = ["self"]
-
-	for (const pp of op.pathParams) {
-		posArgs.push(`${pyParamName(pp)}: str`)
-	}
+type PyOpPlan = {
+	op: SdkOp
+	methodName: string
+	pathParams: PyParam[]
+	queryParams: Array<PyParam & { required: boolean; type: string }>
+	headerParams: Array<PyParam & { required: boolean; type: string }>
+	body?: { local: string; type: string; required: boolean }
+	multipart?: { files: string[]; listFiles: string[] }
+	returnType: string
+}
 
-	if (op.isRealtime) {
-		const kwArgsRt: string[] = [
-			`reconnect_token: str | None = None`,
-			`last_event_id: str | None = None`,
-			`headers: dict[str, str] | None = None`,
-		]
-		const posLineRt = posArgs.join(", ")
-		/* realtime method is sync — returns ResumableConnection (async-iterable).
-		 * matches TS: `sdk.connectRealtime()` returns object, not a Promise. */
-		lines.push(`    def ${methodName}(${posLineRt},`)
-		lines.push(`        *,`)
-		for (let i = 0; i < kwArgsRt.length; i++) {
-			const comma = i < kwArgsRt.length - 1 ? "," : ""
-			lines.push(`        ${kwArgsRt[i]}${comma}`)
+/** kwargs the generated methods always take; params must not reuse them. */
+/** What client.py may import from the runtime modules; each name only when the bodies use it. */
+const PY_CLIENT_IMPORTS: ReadonlyArray<readonly [string, readonly string[]]> = [
+	[
+		"._runtime",
+		[
+			"ClientConfig",
+			"SDKResult",
+			"_AuthState",
+			"_build_headers",
+			"_build_url",
+			"_do_request_async",
+			"_do_request_sync",
+			"_expand_path",
+			"_form_content",
+			"_format_value",
+			"_has_header",
+			"_multipart_parts",
+			"_open_stream",
+			"_parse_body",
+			"_raise_for_status",
+			"_set_header",
+			"_to_ws_url",
+		],
+	],
+	["._invalidation", ["_StaleTracker", "_StaleTrackerSync"]],
+	["._sse", ["SSEEvent", "parse_sse_stream"]],
+	["._ws", ["_TypedWebSocket"]],
+	["._transport", ["LongpollAdapter", "SseAdapter", "TransportOpts", "WsAdapter"]],
+	["._realtime", ["ResumableConnection"]],
+]
+
+/**
+ * Module-scope names a generated method body evaluates at runtime (calls and attribute access, not
+ * annotations, which `from __future__ import annotations` never evaluates). A parameter local must
+ * never shadow one: a path param named `uuid` would turn `str(uuid.uuid4())` into an
+ * AttributeError. Underscore names cannot collide, since parameter locals never start with `_`.
+ */
+export const PY_BODY_GLOBALS: readonly string[] = [
+	"httpx",
+	"str",
+	"threading",
+	"uuid",
+	...PY_CLIENT_IMPORTS.flatMap(([, syms]) => syms.filter((n) => !n.startsWith("_"))),
+]
+
+const PY_METHOD_RESERVED = [
+	"self",
+	"timeout",
+	"headers",
+	"cancel_token",
+	"idempotency_key",
+	"last_event_id",
+	"protocols",
+	"reconnect_token",
+	...PY_BODY_GLOBALS,
+]
+
+function planPyOp(op: SdkOp, methodName: string, names: PyNames, model: SdkModel): PyOpPlan {
+	const locals = new NameScope(PY_METHOD_RESERVED)
+	const typeParent = pyClassName(op.id)
+	const plan: PyOpPlan = { headerParams: [], methodName, op, pathParams: [], queryParams: [], returnType: "None" }
+	const b = op.body
+	const hasBodyArg = b !== undefined && op.stream !== "ws" && op.stream !== "realtime"
+	const bodyLocal = hasBodyArg ? locals.claim("body") : ""
+	for (const p of op.pathParams) plan.pathParams.push({ local: locals.claim(pyIdentifier(p.name)), wire: p.name })
+	if (op.stream !== "realtime") {
+		for (const q of op.query) {
+			if (op.stream === "sse" && /^last[-_]?event[-_]?id$/i.test(q.name)) continue
+			plan.queryParams.push({
+				local: locals.claim(pyIdentifier(q.name)),
+				required: q.required === true,
+				type: irToPythonNamed(q.schema, names.types, typeParent, q.name),
+				wire: q.name,
+			})
+		}
+		for (const h of op.headers) {
+			plan.headerParams.push({
+				local: locals.claim(pyIdentifier(h.name)),
+				required: h.required === true,
+				type: irToPythonNamed(h.schema, names.types, typeParent, h.name),
+				wire: h.name,
+			})
 		}
-		lines.push(`    ) -> ResumableConnection:`)
-		return lines
 	}
-
-	if (op.bodyIsStream) {
-		posArgs.push(`body: AsyncIterator[bytes] | bytes | bytearray`)
-	} else if (op.bodySchema && op.bodyRequired) {
-		posArgs.push(`body: ${bodyTypeName(op.bodySchema)}`)
+	if (hasBodyArg && b) {
+		let type: string
+		switch (b.kind) {
+			case "json":
+			case "form":
+				type = irToPythonNamed(b.schema, names.types, typeParent, "Body")
+				break
+			case "binary":
+				type = "bytes | AsyncIterator[bytes]"
+				break
+			case "text":
+				type = "str"
+				break
+			case "multipart": {
+				const files: string[] = []
+				const listFiles: string[] = []
+				const fields = b.parts.map((part) => {
+					const schema = part.schema ? model.resolve(part.schema) : ({ kind: "unknown" } as IRSchema)
+					if (part.type === "file") {
+						if (schema.kind === "array") listFiles.push(part.name)
+						else files.push(part.name)
+						return {
+							name: part.name,
+							required: false,
+							schema: { kind: "unknown" } as IRSchema,
+							file: true,
+							list: schema.kind === "array",
+						}
+					}
+					return {
+						file: false,
+						list: false,
+						name: part.name,
+						required: false,
+						schema: part.schema ?? ({ kind: "unknown" } as IRSchema),
+					}
+				})
+				const objectIR: Extract<IRSchema, { kind: "object" }> = {
+					fields: fields.map((f) => ({ name: f.name, required: f.required, schema: f.schema })),
+					kind: "object",
+				}
+				type = names.types.hoist(`${op.id}.multipart`, `${typeParent}Body`, objectIR)
+				/* file parts: re-render with the FileInput alias instead of Any */
+				const decl = names.decls.get(type) ?? ""
+				let patched = decl
+				for (const f of fields.filter((x) => x.file)) {
+					const key = pyString(f.name)
+					const t = f.list ? "list[FileInput]" : "FileInput"
+					patched = patched
+						.replace(`    ${f.name}: NotRequired[Any]`, `    ${f.name}: NotRequired[${t}]`)
+						.replace(`        ${key}: "NotRequired[Any]",`, `        ${key}: ${pyString(`NotRequired[${t}]`)},`)
+				}
+				names.decls.set(type, patched)
+				plan.multipart = { files, listFiles }
+				break
+			}
+		}
+		plan.body = { local: bodyLocal, required: b.required, type }
 	}
-
-	const kwArgs: string[] = []
-
-	if (!op.bodyIsStream && op.bodySchema && !op.bodyRequired) {
-		kwArgs.push(`body: ${bodyTypeName(op.bodySchema)} | None = None`)
+	if (op.stream === null) {
+		const s = op.success
+		if (s.kind === "json")
+			plan.returnType = s.schema ? irToPythonNamed(s.schema, names.types, typeParent, "Response") : "Any"
+		else if (s.kind === "text") plan.returnType = "str"
+		else if (s.kind === "binary") plan.returnType = "bytes"
+		else plan.returnType = "None"
 	}
+	return plan
+}
 
-	if (op.isSSE) {
-		kwArgs.push(`last_event_id: str | None = None`)
-	}
+function signature(plan: PyOpPlan, throwOnError: boolean, isAsync: boolean): string[] {
+	const { op } = plan
+	const defKw = op.stream === "ws" || op.stream === "realtime" || !isAsync ? "def" : "async def"
+	const pos: string[] = ["self", ...plan.pathParams.map((p) => `${p.local}: str`)]
+	const kw: string[] = []
 
-	if (op.isWS) {
-		kwArgs.push(`protocols: list[str] | None = None`)
+	if (op.stream === "realtime") {
+		kw.push(
+			`reconnect_token: str | None = None`,
+			`last_event_id: str | None = None`,
+			`headers: dict[str, str] | None = None`,
+		)
+		return emitSignature(defKw, plan.methodName, pos, kw, "ResumableConnection")
 	}
 
-	for (const qp of op.queryParams) {
-		const pname = pyParamName(qp.name)
-		const pyType = jsonSchemaToPy(qp.schema, 0)
-		if (qp.required) {
-			posArgs.push(`${pname}: ${pyType}`)
-		} else {
-			/* skip last-event-id as already handled above */
-			if (op.isSSE && (qp.name === "last-event-id" || qp.name === "last_event_id")) continue
-			kwArgs.push(`${pname}: ${pyType} | None = None`)
-		}
+	if (plan.body) {
+		if (plan.body.required) pos.push(`${plan.body.local}: ${plan.body.type}`)
+		else kw.push(`${plan.body.local}: ${optional(plan.body.type)} = None`)
 	}
-
-	/* SSE/WS use config-level timeout/headers, not per-call */
-	if (!op.isSSE && !op.isWS) {
-		if (op.isIdempotent) kwArgs.push(`idempotency_key: str | None = None`)
-		kwArgs.push(`timeout: float | None = None`)
-		kwArgs.push(`headers: dict[str, str] | None = None`)
-		kwArgs.push(`cancel_token: "threading.Event | None" = None`)
+	for (const q of [...plan.queryParams, ...plan.headerParams]) {
+		if (q.required) pos.push(`${q.local}: ${q.type}`)
+		else kw.push(`${q.local}: ${optional(q.type)} = None`)
 	}
-
-	let returnType: string
-	if (op.isSSE) {
-		returnType = "AsyncIterator[SSEEvent]"
-	} else if (op.isWS) {
-		returnType = "_TypedWebSocket"
-	} else if (throwOnError) {
-		returnType = op.successType
-	} else {
-		returnType = `SDKResult[${op.successType}]`
+	if (op.stream === "sse") kw.push(`last_event_id: str | None = None`, `headers: dict[str, str] | None = None`)
+	if (op.stream === "ws") {
+		kw.push(
+			`protocols: list[str] | None = None`,
+			`reconnect_token: str | None = None`,
+			`headers: dict[str, str] | None = None`,
+		)
 	}
-
-	if (kwArgs.length === 0) {
-		lines.push(`    ${defKw} ${methodName}(${posArgs.join(", ")}) -> ${returnType}:`)
-	} else {
-		const posLine = posArgs.join(", ")
-		lines.push(`    ${defKw} ${methodName}(${posLine},`)
-		lines.push(`        *,`)
-		for (let i = 0; i < kwArgs.length; i++) {
-			const comma = i < kwArgs.length - 1 ? "," : ""
-			lines.push(`        ${kwArgs[i]}${comma}`)
-		}
-		lines.push(`    ) -> ${returnType}:`)
+	if (op.stream === null) {
+		if (op.idempotent) kw.push(`idempotency_key: str | None = None`)
+		kw.push(`timeout: float | None = None`, `headers: dict[str, str] | None = None`)
+		kw.push(`cancel_token: "threading.Event | None" = None`)
 	}
 
-	return lines
+	let ret: string
+	if (op.stream === "sse") ret = "AsyncIterator[SSEEvent]"
+	else if (op.stream === "ws") ret = "_TypedWebSocket"
+	else if (throwOnError) ret = plan.returnType
+	else ret = `SDKResult[${plan.returnType}]`
+	return emitSignature(defKw, plan.methodName, pos, kw, ret)
 }
 
-function buildMethodDocstring(op: OperationInfo): string[] {
-	const lines: string[] = []
-	const text = op.summary ?? op.description ?? ""
-	if (!text && op.errorStatuses.length === 0) return lines
-
-	if (op.errorStatuses.length === 0) {
-		/* single-line docstring when no Raises section */
-		lines.push(`        """${text}"""`)
-		return lines
-	}
-
-	lines.push(`        """${text}`)
-	lines.push(``)
-	lines.push(`        Raises:`)
-	for (const status of op.errorStatuses) {
-		const name = ERROR_NAMES[status] ?? "APIStatusError"
-		lines.push(`            ${name}: HTTP ${status}`)
-	}
-	lines.push(`        """`)
-	return lines
+function optional(t: string): string {
+	return t.endsWith("| None") ? t : `${t} | None`
 }
 
-function buildUrlLine(op: OperationInfo, isTopLevel: boolean): string {
-	const configRef = isTopLevel ? "self._config" : "self._client._config"
-	if (op.pathParams.length > 0) {
-		const urlExpr = op.path.replace(/\{(\w+)\}/g, (_, p) => `{quote(${pyParamName(p)}, safe='')}`)
-		return `        url = _build_url(${configRef}.base_url, f"${urlExpr}")`
-	}
-	return `        url = _build_url(${configRef}.base_url, "${op.path}")`
+function emitSignature(defKw: string, name: string, pos: string[], kw: string[], ret: string): string[] {
+	if (kw.length === 0) return [`    ${defKw} ${name}(${pos.join(", ")}) -> ${ret}:`]
+	const l = [`    ${defKw} ${name}(${pos.join(", ")},`, `        *,`]
+	kw.forEach((k, i) => l.push(`        ${k}${i < kw.length - 1 ? "," : ""}`))
+	l.push(`    ) -> ${ret}:`)
+	return l
 }
 
-function buildResponseLines(throwOnError: boolean): string[] {
-	if (throwOnError) {
-		return [`        _raise_for_status(_response)`, `        return _parse_body(_response)`]
-	}
-	return [
-		`        _body = _parse_body(_response)`,
-		`        if _response.status_code >= 400:`,
-		`            return SDKResult(data=None, error=_body, status=_response.status_code, response=_response)`,
-		`        return SDKResult(data=_body, error=None, status=_response.status_code, response=_response)`,
-	]
+function docstring(op: SdkOp): string[] {
+	const text = op.summary || op.description
+	const lines = text ? pyDocLines(text) : []
+	if (lines.length === 0 && op.errorStatuses.length === 0) return []
+	const out: string[] = []
+	if (op.errorStatuses.length === 0 && lines.length === 1) return [`        """${lines[0]}"""`]
+	out.push(`        """${lines[0] ?? ""}`)
+	for (const line of lines.slice(1)) out.push(line === "" ? "" : `        ${line}`)
+	if (op.errorStatuses.length > 0) {
+		out.push(``)
+		out.push(`        Raises:`)
+		for (const status of op.errorStatuses)
+			out.push(`            ${ERROR_NAMES[status] ?? "APIStatusError"}: HTTP ${status}`)
+	}
+	out.push(`        """`)
+	return out
 }
 
-/* Build path-params dict literal string used by mark_stale / interpolate_path:
- * { "id": id, "orgId": org_id } — keys are the OpenAPI placeholder names,
- * values are the python-safe local identifiers from the method signature. */
-function buildPathParamsDict(op: OperationInfo): string {
-	if (op.pathParams.length === 0) return "None"
-	const entries = op.pathParams.map((p) => `"${p}": ${pyParamName(p)}`)
-	return `{${entries.join(", ")}}`
+function pathExpr(plan: PyOpPlan): string {
+	if (plan.pathParams.length === 0) return pyString(plan.op.path)
+	const dict = plan.pathParams.map((p) => `${pyString(p.wire)}: ${p.local}`).join(", ")
+	return `_expand_path(${pyString(plan.op.path)}, {${dict}})`
 }
 
-function buildInvalidateListLiteral(op: OperationInfo): string {
-	if (op.invalidate.length === 0) return "[]"
-	return `[${op.invalidate.map((s) => `"${s}"`).join(", ")}]`
+function paramsDict(plan: PyOpPlan): string {
+	const entries = plan.queryParams.map((q) => `${pyString(q.wire)}: ${q.local}`)
+	return `{${entries.join(", ")}}`
 }
 
-/* Emit Idempotency-Key injection block. Precedence:
- * explicit header (any casing) > idempotency_key kwarg > uuid.uuid4().
- * Runs after _headers is built so config.headers + per-call headers merge is visible. */
-function buildIdempotencyLines(op: OperationInfo): string[] {
-	if (!op.isIdempotent || op.isSSE || op.isWS || op.isRealtime) return []
-	return [
-		`        _idem_existing = None`,
-		`        for _k in list(_headers.keys()):`,
-		`            if _k.lower() == "idempotency-key":`,
-		`                _idem_existing = _headers[_k]`,
-		`                break`,
-		`        if _idem_existing is None:`,
-		`            _headers["Idempotency-Key"] = idempotency_key if idempotency_key is not None else str(uuid.uuid4())`,
-	]
+function headerLines(plan: PyOpPlan, configRef: string, authRef: string, base: string): string[] {
+	const l: string[] = []
+	l.push(`        _extra: dict[str, str] = ${base}`)
+	for (const h of plan.headerParams) {
+		l.push(`        if ${h.local} is not None:`)
+		l.push(`            _extra[${pyString(h.wire)}] = _format_value(${h.local})`)
+	}
+	l.push(`        _extra.update(headers or {})`)
+	l.push(`        _headers = _build_headers(${configRef}, extra=_extra, bearer_token=${authRef}.token)`)
+	return l
 }
 
-function buildAsyncMethodBody(op: OperationInfo, throwOnError: boolean, isTopLevel = false): string[] {
-	const lines: string[] = []
-	const configRef = isTopLevel ? "self._config" : "self._client._config"
-	const asyncClientRef = isTopLevel ? "self._async_client" : "self._client._async_client"
-	const trackerRef = isTopLevel ? "self._stale_tracker" : "self._client._stale_tracker"
-
-	if (op.isRealtime) {
-		lines.push(`        _transports = [WsAdapter(), SseAdapter(), LongpollAdapter()]`)
-		lines.push(`        _opts = TransportOpts(`)
-		lines.push(`            reconnect_token=reconnect_token,`)
-		lines.push(`            last_event_id=last_event_id,`)
-		lines.push(`            headers=headers,`)
-		lines.push(`        )`)
-		lines.push(`        _url = _build_url(${configRef}.base_url, "${op.path}")`)
-		lines.push(`        return ResumableConnection(_url, _transports, _opts)`)
-		return lines
+function bodyArgs(plan: PyOpPlan, l: string[]): string {
+	const b = plan.op.body
+	const local = plan.body?.local
+	if (!b || !local) return ""
+	switch (b.kind) {
+		case "json":
+			return `json=${local}`
+		case "form":
+			l.push(`        _headers.setdefault("Content-Type", "application/x-www-form-urlencoded")`)
+			return `content=_form_content(${local})`
+		case "text":
+			l.push(`        _set_header(_headers, "Content-Type", ${pyString(b.contentType)})`)
+			return `content=${local}.encode() if ${local} is not None else None`
+		case "binary":
+			l.push(`        _set_header(_headers, "Content-Type", ${pyString(b.contentType)})`)
+			return `content=${local}`
+		case "multipart": {
+			const files = plan.multipart?.files ?? []
+			const listFiles = plan.multipart?.listFiles ?? []
+			l.push(
+				`        _data, _files = _multipart_parts(${local}, files=[${files.map(pyString).join(", ")}], list_files=[${listFiles.map(pyString).join(", ")}])`,
+			)
+			return `data=_data, files=_files`
+		}
 	}
+}
 
-	lines.push(buildUrlLine(op, isTopLevel))
-
-	if (op.isSSE) {
-		lines.push(`        _headers = _build_headers(${configRef}, extra={"Accept": "text/event-stream"})`)
-		lines.push(`        if last_event_id is not None: _headers["Last-Event-ID"] = last_event_id`)
-	} else if (op.isWS) {
-		lines.push(`        _headers = _build_headers(${configRef}, extra=None)`)
-	} else if (op.bodyIsStream) {
-		lines.push(
-			`        _headers = _build_headers(${configRef}, extra={"Content-Type": "application/octet-stream", **(headers or {})})`,
+function methodBody(plan: PyOpPlan, throwOnError: boolean, isAsync: boolean, isTopLevel: boolean): string[] {
+	const l: string[] = []
+	const { op } = plan
+	const self = isTopLevel ? "self" : "self._client"
+	const configRef = `${self}._config`
+	const authRef = `${self}._auth`
+	const clientRef = isAsync ? `${self}._async_client` : `${self}._sync_client`
+	const trackerRef = `${self}._stale_tracker`
+	const aw = isAsync ? "await " : ""
+
+	if (op.stream === "realtime") {
+		l.push(`        _url = _build_url(${configRef}.base_url, ${pathExpr(plan)})`)
+		l.push(`        _opts = TransportOpts(`)
+		l.push(`            reconnect_token=reconnect_token,`)
+		l.push(`            last_event_id=last_event_id,`)
+		l.push(`            headers=_build_headers(${configRef}, extra=headers, bearer_token=${authRef}.token),`)
+		l.push(`        )`)
+		l.push(`        _transports: list[Any] = [WsAdapter(), SseAdapter(), LongpollAdapter()]`)
+		l.push(`        return ResumableConnection(_url, _transports, _opts)`)
+		return l
+	}
+
+	l.push(`        _path = ${pathExpr(plan)}`)
+
+	if (op.stream === "ws") {
+		l.push(`        _params: dict[str, Any] = ${paramsDict(plan)}`)
+		l.push(`        if reconnect_token is not None:`)
+		l.push(`            _params["reconnect_token"] = reconnect_token`)
+		l.push(...headerLines(plan, configRef, authRef, "{}"))
+		l.push(`        _url = _build_url(${configRef}.base_url, _path, _params)`)
+		l.push(`        _ws_url = _to_ws_url(_url)`)
+		l.push(`        return _TypedWebSocket(_ws_url, protocols=protocols, extra_headers=_headers)`)
+		return l
+	}
+
+	if (op.stream === "sse") {
+		l.push(`        _params: dict[str, Any] = ${paramsDict(plan)}`)
+		l.push(...headerLines(plan, configRef, authRef, `{"Accept": "text/event-stream"}`))
+		l.push(`        if last_event_id is not None:`)
+		l.push(`            _headers["Last-Event-ID"] = last_event_id`)
+		const args = bodyArgs(plan, l)
+		l.push(`        _url = _build_url(${configRef}.base_url, _path, _params)`)
+		l.push(
+			`        async with _open_stream(${clientRef}, ${configRef}, ${pyString(op.method)}, _url, _headers${args ? `, ${args}` : ""}) as _response:`,
+		)
+		l.push(`            async for _event in parse_sse_stream(_response):`)
+		l.push(`                yield _event`)
+		return l
+	}
+
+	l.push(`        _params: dict[str, Any] = ${paramsDict(plan)}`)
+	l.push(...headerLines(plan, configRef, authRef, "{}"))
+	if (op.idempotent) {
+		/* explicit header (any casing) > idempotency_key kwarg > uuid4 */
+		l.push(`        if not _has_header(_headers, "Idempotency-Key"):`)
+		l.push(
+			`            _headers["Idempotency-Key"] = idempotency_key if idempotency_key is not None else str(uuid.uuid4())`,
 		)
-	} else {
-		lines.push(`        _headers = _build_headers(${configRef}, extra=headers)`)
 	}
-	lines.push(...buildIdempotencyLines(op))
-
-	/* SSE skips last-event-id query param — sent as header instead */
-	const qpNames = op.queryParams
-		.filter((qp) => !(op.isSSE && (qp.name === "last-event-id" || qp.name === "last_event_id")))
-		.map((qp) => `"${qp.name}": ${pyParamName(qp.name)}`)
-	if (qpNames.length > 0) {
-		lines.push(`        _params: dict[str, Any] = {${qpNames.join(", ")}}`)
+	const args = bodyArgs(plan, l)
+	const dictEntries = plan.pathParams.map((p) => `${pyString(p.wire)}: ${p.local}`)
+	l.push(
+		`        _path_params: dict[str, str] | None = ${dictEntries.length > 0 ? `{${dictEntries.join(", ")}}` : "None"}`,
+	)
+	l.push(`        _selector = ${pyString(`${op.method} `)} + _path`)
+	l.push(`        _request_meta = ${aw}${trackerRef}.build_request_meta(_selector, _path, ${pyString(op.method)})`)
+	l.push(`        _url = _build_url(${configRef}.base_url, _path, _params)`)
+	l.push(`        _response = ${aw}${isAsync ? "_do_request_async" : "_do_request_sync"}(`)
+	l.push(`            ${clientRef}, ${configRef}, ${pyString(op.method)}, _url,`)
+	l.push(`            headers=_headers,${args ? ` ${args},` : ""} timeout=timeout,`)
+	l.push(`            cancel_token=cancel_token, operation=${pyString(`${op.method} ${op.path}`)},`)
+	l.push(`            request_meta=_request_meta, auth=${authRef},`)
+	l.push(`        )`)
+	l.push(`        if 200 <= _response.status_code < 300:`)
+	const targets = op.invalidates.map(pyString).join(", ")
+	l.push(`            ${aw}${trackerRef}.mark_stale([${targets}], _path_params, _selector)`)
+	l.push(`            if _request_meta is not None and _request_meta.is_stale:`)
+	l.push(
+		`                ${aw}${trackerRef}.clear_stale(_selector, _path, ${pyString(op.method)}, _request_meta.seq_snapshot)`,
+	)
+	const kind = op.success.kind
+	if (throwOnError) {
+		l.push(`        _raise_for_status(_response)`)
+		l.push(`        return _parse_body(_response, ${pyString(kind)})`)
 	} else {
-		lines.push(`        _params: dict[str, Any] = {}`)
-	}
-
-	if (op.isWS) {
-		lines.push(`        ws_url = url.replace("https://", "wss://").replace("http://", "ws://")`)
-		if (op.queryParams.some((qp) => qp.name === "reconnect_token")) {
-			lines.push(`        if reconnect_token is not None:`)
-			lines.push(`            _params["reconnect_token"] = reconnect_token`)
-		}
-		lines.push(`        if _params:`)
-		lines.push(`            from urllib.parse import urlencode`)
-		lines.push(`            ws_url = f"{ws_url}?{urlencode({k: v for k, v in _params.items() if v is not None})}"`)
-		lines.push(`        return _TypedWebSocket(ws_url, protocols=protocols, extra_headers=_headers)`)
-		return lines
-	}
-
-	if (op.isSSE) {
-		lines.push(`        async with ${asyncClientRef}.stream(`)
-		lines.push(`            "${op.method}", url, headers=_headers,`)
-		lines.push(`            params={k: v for k, v in _params.items() if v is not None} or None,`)
-		lines.push(`        ) as _response:`)
-		lines.push(`            _raise_for_status(_response)`)
-		lines.push(`            async for _event in parse_sse_stream(_response):`)
-		lines.push(`                yield _event`)
-		return lines
+		l.push(`        if not 200 <= _response.status_code < 300:`)
+		l.push(
+			`            return SDKResult(data=None, error=_parse_body(_response), status=_response.status_code, response=_response)`,
+		)
+		l.push(
+			`        return SDKResult(data=_parse_body(_response, ${pyString(kind)}), error=None, status=_response.status_code, response=_response)`,
+		)
 	}
-
-	const pathParamsDict = buildPathParamsDict(op)
-	const invalidateLiteral = buildInvalidateListLiteral(op)
-	lines.push(`        _path_params: dict[str, str] | None = ${pathParamsDict}`)
-	lines.push(`        _concrete_path = interpolate_path("${op.path}", _path_params)`)
-	lines.push(`        _concrete_selector = "${op.method} " + _concrete_path`)
-	lines.push(`        _request_meta = await ${trackerRef}.build_request_meta(`)
-	lines.push(`            _concrete_selector, _concrete_path, "${op.method}",`)
-	lines.push(`        )`)
-
-	let bodyArg: string
-	if (op.bodyIsStream) bodyArg = "json=None, content=body"
-	else if (op.bodySchema) bodyArg = "json=body"
-	else bodyArg = "json=None"
-	lines.push(`        _response = await _do_request_async(`)
-	lines.push(`            ${asyncClientRef}, ${configRef}, "${op.method}", url,`)
-	lines.push(`            headers=_headers, ${bodyArg}, params=_params, timeout=timeout,`)
-	lines.push(`            cancel_token=cancel_token, operation="${op.method} ${op.path}",`)
-	lines.push(`            request_meta=_request_meta,`)
-	lines.push(`        )`)
-	lines.push(`        if _response.status_code < 400:`)
-	lines.push(`            await ${trackerRef}.mark_stale(`)
-	lines.push(`                ${invalidateLiteral}, _path_params, _concrete_selector,`)
-	lines.push(`            )`)
-	lines.push(`            if _request_meta is not None and _request_meta.is_stale:`)
-	lines.push(`                await ${trackerRef}.clear_stale(`)
-	lines.push(`                    _concrete_selector, _concrete_path, "${op.method}",`)
-	lines.push(`                    _request_meta.seq_snapshot,`)
-	lines.push(`                )`)
-	lines.push(...buildResponseLines(throwOnError))
-
-	return lines
+	return l
 }
 
-function buildSyncMethodBody(op: OperationInfo, throwOnError: boolean, isTopLevel = false): string[] {
-	const lines: string[] = []
-	const configRef = isTopLevel ? "self._config" : "self._client._config"
-	const syncClientRef = isTopLevel ? "self._sync_client" : "self._client._sync_client"
-	const trackerRef = isTopLevel ? "self._stale_tracker" : "self._client._stale_tracker"
-
-	lines.push(buildUrlLine(op, isTopLevel))
-	lines.push(`        _headers = _build_headers(${configRef}, extra=headers)`)
-	lines.push(...buildIdempotencyLines(op))
-
-	const qpNames = op.queryParams.map((qp) => `"${qp.name}": ${pyParamName(qp.name)}`)
-	if (qpNames.length > 0) {
-		lines.push(`        _params: dict[str, Any] = {${qpNames.join(", ")}}`)
-	} else {
-		lines.push(`        _params: dict[str, Any] = {}`)
-	}
-
-	const pathParamsDict = buildPathParamsDict(op)
-	const invalidateLiteral = buildInvalidateListLiteral(op)
-	lines.push(`        _path_params: dict[str, str] | None = ${pathParamsDict}`)
-	lines.push(`        _concrete_path = interpolate_path("${op.path}", _path_params)`)
-	lines.push(`        _concrete_selector = "${op.method} " + _concrete_path`)
-	lines.push(`        _request_meta = ${trackerRef}.build_request_meta(`)
-	lines.push(`            _concrete_selector, _concrete_path, "${op.method}",`)
-	lines.push(`        )`)
-
-	const jsonArg = op.bodySchema ? "json=body" : "json=None"
-	lines.push(`        _response = _do_request_sync(`)
-	lines.push(`            ${syncClientRef}, ${configRef}, "${op.method}", url,`)
-	lines.push(`            headers=_headers, ${jsonArg}, params=_params, timeout=timeout,`)
-	lines.push(`            cancel_token=cancel_token, operation="${op.method} ${op.path}",`)
-	lines.push(`            request_meta=_request_meta,`)
-	lines.push(`        )`)
-	lines.push(`        if _response.status_code < 400:`)
-	lines.push(`            ${trackerRef}.mark_stale(`)
-	lines.push(`                ${invalidateLiteral}, _path_params, _concrete_selector,`)
-	lines.push(`            )`)
-	lines.push(`            if _request_meta is not None and _request_meta.is_stale:`)
-	lines.push(`                ${trackerRef}.clear_stale(`)
-	lines.push(`                    _concrete_selector, _concrete_path, "${op.method}",`)
-	lines.push(`                    _request_meta.seq_snapshot,`)
-	lines.push(`                )`)
-	lines.push(...buildResponseLines(throwOnError))
-
-	return lines
+type PyClassNode = {
+	asyncName: string
+	syncName?: string
+	path: string[]
+	ns: IRNamespace
+	children: Array<{ attr: string; node: PyClassNode }>
+	plans: PyOpPlan[]
 }
 
-/* ── buildPyTypes ── */
-
-function buildPyTypes(spec: Record<string, unknown>): string {
-	const schemas = (spec.components as Record<string, unknown> | undefined)?.schemas as
-		| Record<string, Record<string, unknown>>
-		| undefined
-
-	const body: string[] = []
-	const allNames: string[] = []
-
-	if (schemas) {
-		for (const [name, schema] of Object.entries(schemas).sort(([a], [b]) => a.localeCompare(b))) {
-			allNames.push(name)
-			const props = schema.properties as Record<string, Record<string, unknown>> | undefined
-			const required = new Set((schema.required as string[] | undefined) ?? [])
-
-			if (props && Object.keys(props).length > 0) {
-				body.push(`class ${name}(TypedDict, total=False):`)
-				for (const [key, val] of Object.entries(props).sort(([a], [b]) => a.localeCompare(b))) {
-					const pyType = jsonSchemaToPy(val, 0)
-					if (required.has(key)) {
-						body.push(`    ${key}: ${pyType}`)
-					} else {
-						body.push(`    ${key}: NotRequired[${pyType}]`)
-					}
-				}
-				body.push("")
-			} else if (schema.type === "string" && schema.format === "uuid") {
-				body.push(`${name} = NewType("${name}", str)`)
-				body.push("")
-			} else {
-				body.push(`${name} = NewType("${name}", Any)  # type: ignore[misc]`)
-				body.push("")
-			}
-		}
-	}
-
-	const bodyText = body.join("\n")
-	const typingImports = new Set<string>(["TypedDict", "Literal", "NotRequired", "NewType"])
-	if (!bodyText.includes("NewType(")) typingImports.delete("NewType")
-	if (!/\bAny\b/.test(bodyText)) typingImports.delete("Any")
-	else typingImports.add("Any")
-	if (!/\bLiteral\b/.test(bodyText)) typingImports.delete("Literal")
-	if (!/\bNotRequired\b/.test(bodyText)) typingImports.delete("NotRequired")
-	if (!/\bTypedDict\b/.test(bodyText)) typingImports.delete("TypedDict")
+function isSyncCapable(op: SdkOp): boolean {
+	return op.stream === null && op.body?.kind !== "binary"
+}
 
-	const l: string[] = []
-	l.push("# ruff: noqa: E501")
-	l.push(PYTHON_FUTURE)
-	l.push("")
-	if (typingImports.size > 0) {
-		const sorted = [...typingImports].sort()
-		l.push(`from typing import ${sorted.join(", ")}`)
-		l.push("")
-	}
-	if (bodyText.length > 0) {
-		l.push(bodyText)
-	}
+function hasSyncContent(node: PyClassNode): boolean {
+	return node.plans.some((p) => isSyncCapable(p.op)) || node.children.some((c) => hasSyncContent(c.node))
+}
 
-	if (allNames.length === 0) {
-		l.push("__all__: list[str] = []")
-	} else {
-		l.push(`__all__ = [${allNames.map((n) => `"${n}"`).join(", ")}]`)
-	}
-	return l.join("\n")
+function trackerInit(cls: string): string[] {
+	return [
+		"        _inv = config.invalidation",
+		`        self._stale_tracker = ${cls}(`,
+		"            stale_time=_inv.stale_time if _inv is not None else 0.0,",
+		"            stale_max_entries=(",
+		"                _inv.stale_max_entries if _inv is not None else 1000",
+		"            ),",
+		"            max_sources_per_target=(",
+		"                _inv.max_sources_per_target if _inv is not None else 16",
+		"            ),",
+		"        )",
+	]
 }
 
 function buildPyClient(
-	spec: Record<string, unknown>,
+	model: SdkModel,
+	names: PyNames,
 	options: PySDKOptions,
 	serviceMap: Record<string, ServiceMapEntry>,
 ): string {
 	const throwOnError = options.throwOnError !== false
-	const { opsByOpId, topLevel, tree } = collectSDKMethods(spec)
-
-	const schemas = (spec.components as Record<string, unknown> | undefined)?.schemas as
-		| Record<string, Record<string, unknown>>
-		| undefined
-	const schemaNames = schemas ? Object.keys(schemas) : []
+	function planNs(ns: IRNamespace, path: string[], reserved: string[]): PyClassNode {
+		const members = new NameScope(reserved)
+		const node: PyClassNode = {
+			asyncName: path.length === 0 ? "AsyncSDK" : names.module.claim(`_${path.map(pyClassName).join("")}Resource`),
+			children: [],
+			ns,
+			path,
+			plans: [],
+		}
+		if (path.length > 0) node.syncName = names.module.claim(`_Sync${path.map(pyClassName).join("")}Resource`)
+		for (const [seg, childNs] of namespacesOf(ns)) {
+			const attr = members.claim(pyIdent(seg))
+			node.children.push({ attr, node: planNs(childNs, [...path, seg], ["_client"]) })
+		}
+		for (const [seg, irOp] of methodsOf(ns)) {
+			const op = model.opsById.get(irOp.id)
+			if (!op) continue
+			let base = pyIdentifier(seg)
+			if (op.stream === "realtime") {
+				/* realtime methods keep the `connectX` name they always had */
+				const ident = pyIdentifier(seg)
+				base = /^connect(_|$)/.test(ident) ? ident : `connect${ident.charAt(0).toUpperCase()}${ident.slice(1)}`
+			}
+			node.plans.push(planPyOp(op, members.claim(base), names, model))
+		}
+		return node
+	}
+	const root = planNs(
+		model.ir.tree,
+		[],
+		["_config", "_auth", "_async_client", "_sync_client", "_stale_tracker", "is_stale", "aclose", "close"],
+	)
 
 	const body: string[] = []
-
 	const invEntries = Object.entries(serviceMap).filter(([, v]) => v.invalidate && v.invalidate.length > 0)
-
 	body.push("_INVALIDATION_MAP: dict[str, dict[str, Any]] = {")
 	for (const [opId, entry] of invEntries) {
-		const invItems = (entry.invalidate ?? []).map((s) => `"${s}"`).join(", ")
-		body.push(`    "${opId}": {`)
-		body.push(`        "method": "${entry.method}",`)
-		body.push(`        "path": "${entry.path}",`)
-		body.push(`        "invalidate": [${invItems}],`)
+		body.push(`    ${pyString(opId)}: {`)
+		body.push(`        "method": ${pyString(entry.method)},`)
+		body.push(`        "path": ${pyString(entry.path)},`)
+		body.push(`        "invalidate": [${(entry.invalidate ?? []).map(pyString).join(", ")}],`)
 		body.push(`    },`)
 	}
 	body.push("}")
 	body.push("")
 
-	/* emit async resource classes in post-order (children before parents) */
-	function emitAsyncResourceClasses(ns: IRNamespace, path: string[]): void {
-		/* recurse into sub-namespaces first (post-order so children declared before parents) */
-		for (const [seg, childNs] of namespacesOf(ns)) {
-			emitAsyncResourceClasses(childNs, [...path, seg])
-		}
-
-		if (path.length === 0) return
-
-		const className = nestedClassName(path)
-		const parentType = path.length === 1 ? '"AsyncSDK"' : nestedClassName(path.slice(0, -1))
-		body.push(`class ${className}:`)
-		body.push(`    def __init__(self, _client: ${parentType}) -> None:`)
+	/* children before parents so class names resolve at definition time */
+	/* every resource holds the root SDK: nested resources reach config and clients directly */
+	function emitAsync(node: PyClassNode): void {
+		for (const c of node.children) emitAsync(c.node)
+		if (node.path.length === 0) return
+		body.push(`class ${node.asyncName}:`)
+		body.push(`    def __init__(self, _client: "AsyncSDK") -> None:`)
 		body.push(`        self._client = _client`)
-
-		for (const [seg] of namespacesOf(ns)) {
-			const childClass = nestedClassName([...path, seg])
-			body.push(`        self.${pyIdent(seg)} = ${childClass}(self)`)
-		}
+		for (const c of node.children) body.push(`        self.${c.attr} = ${c.node.asyncName}(_client)`)
 		body.push("")
-
-		for (const [, op] of methodsOf(ns)) {
-			const opInfo = opsByOpId.get(op.id)
-			if (!opInfo) continue
-			body.push(...buildMethodSignature(opInfo, throwOnError, true))
-			body.push(...buildMethodDocstring(opInfo))
-			body.push(...buildAsyncMethodBody(opInfo, throwOnError))
+		for (const plan of node.plans) {
+			body.push(...signature(plan, throwOnError, true))
+			body.push(...docstring(plan.op))
+			body.push(...methodBody(plan, throwOnError, true, false))
 			body.push("")
 		}
 		body.push("")
 	}
 
-	/* emit sync resource classes in post-order */
-	function emitSyncResourceClasses(ns: IRNamespace, path: string[]): void {
-		for (const [seg, childNs] of namespacesOf(ns)) {
-			emitSyncResourceClasses(childNs, [...path, seg])
-		}
-
-		if (path.length === 0) return
-
-		const syncMethods = methodsOf(ns).filter(([, op]) => {
-			const opInfo = opsByOpId.get(op.id)
-			return opInfo && !opInfo.isSSE && !opInfo.isWS && !opInfo.isRealtime && !opInfo.bodyIsStream
-		})
-		/* check if any sub-namespace has sync methods */
-		const hasAnySyncContent = syncMethods.length > 0 || namespacesOf(ns).length > 0
-		if (!hasAnySyncContent) return
-
-		const className = nestedClassName(path)
-		const syncClassName = `_Sync${className.slice(1)}`
-		const parentType = path.length === 1 ? '"SDK"' : `_Sync${nestedClassName(path.slice(0, -1)).slice(1)}`
-		body.push(`class ${syncClassName}:`)
-		body.push(`    def __init__(self, _client: ${parentType}) -> None:`)
+	function emitSync(node: PyClassNode): void {
+		for (const c of node.children) emitSync(c.node)
+		if (node.path.length === 0 || !hasSyncContent(node)) return
+		body.push(`class ${node.syncName}:`)
+		body.push(`    def __init__(self, _client: "SDK") -> None:`)
 		body.push(`        self._client = _client`)
-
-		for (const [seg, childNs] of namespacesOf(ns)) {
-			const childClass = `_Sync${nestedClassName([...path, seg]).slice(1)}`
-			const childSyncMethods = methodsOf(childNs).filter(([, op]) => {
-				const opInfo = opsByOpId.get(op.id)
-				return opInfo && !opInfo.isSSE && !opInfo.isWS && !opInfo.isRealtime && !opInfo.bodyIsStream
-			})
-			if (childSyncMethods.length > 0 || namespacesOf(childNs).length > 0) {
-				body.push(`        self.${pyIdent(seg)} = ${childClass}(self)`)
-			}
+		for (const c of node.children) {
+			if (hasSyncContent(c.node)) body.push(`        self.${c.attr} = ${c.node.syncName}(_client)`)
 		}
 		body.push("")
-
-		for (const [, op] of syncMethods) {
-			const opInfo = opsByOpId.get(op.id)
-			if (!opInfo) continue
-			body.push(...buildMethodSignature(opInfo, throwOnError, false))
-			body.push(...buildMethodDocstring(opInfo))
-			body.push(...buildSyncMethodBody(opInfo, throwOnError))
+		for (const plan of node.plans.filter((p) => isSyncCapable(p.op))) {
+			body.push(...signature(plan, throwOnError, false))
+			body.push(...docstring(plan.op))
+			body.push(...methodBody(plan, throwOnError, false, false))
 			body.push("")
 		}
 		body.push("")
 	}
 
-	emitAsyncResourceClasses(tree, [])
-	emitSyncResourceClasses(tree, [])
+	emitAsync(root)
+	emitSync(root)
 
 	body.push("class SDK:")
 	body.push("    def __init__(self, config: ClientConfig) -> None:")
 	body.push("        self._config = config")
+	body.push("        self._auth = _AuthState(config.bearer_token)")
 	body.push("        self._sync_client = httpx.Client(")
 	body.push("            transport=config.sync_transport,")
 	body.push("        )")
-	body.push("        _inv = config.invalidation")
-	body.push("        self._stale_tracker = _StaleTrackerSync(")
-	body.push("            stale_time=_inv.stale_time if _inv is not None else 0.0,")
-	body.push("            stale_max_entries=(")
-	body.push("                _inv.stale_max_entries if _inv is not None else 1000")
-	body.push("            ),")
-	body.push("            max_sources_per_target=(")
-	body.push("                _inv.max_sources_per_target if _inv is not None else 16")
-	body.push("            ),")
-	body.push("        )")
-	for (const [seg] of namespacesOf(tree)) {
-		const className = `_Sync${nestedClassName([seg]).slice(1)}`
-		body.push(`        self.${pyIdent(seg)} = ${className}(self)`)
+	body.push(...trackerInit("_StaleTrackerSync"))
+	for (const c of root.children) {
+		if (hasSyncContent(c.node)) body.push(`        self.${c.attr} = ${c.node.syncName}(self)`)
 	}
 	body.push("")
+	body.push("    def close(self) -> None:")
+	body.push('        """Closes the underlying HTTP client."""')
+	body.push("        self._sync_client.close()")
+	body.push("")
 	body.push("    def is_stale(self, method: str, path: str) -> bool:")
 	body.push('        """Returns True when (method, path) sits inside an active stale window."""')
 	body.push("        return self._stale_tracker.is_stale(method, path)")
 	body.push("")
-
-	const syncTopLevel = topLevel.filter((op) => !op.isSSE && !op.isWS && !op.isRealtime && !op.bodyIsStream)
-	for (const op of syncTopLevel.sort((a, b) => a.operationId.localeCompare(b.operationId))) {
-		body.push(...buildMethodSignature(op, throwOnError, false))
-		body.push(...buildMethodDocstring(op))
-		const bodyLines = buildSyncMethodBody(op, throwOnError, true)
-		body.push(...bodyLines)
+	for (const plan of root.plans.filter((p) => isSyncCapable(p.op))) {
+		body.push(...signature(plan, throwOnError, false))
+		body.push(...docstring(plan.op))
+		body.push(...methodBody(plan, throwOnError, false, true))
 		body.push("")
 	}
-
 	body.push("")
 
 	body.push("class AsyncSDK:")
 	body.push("    def __init__(self, config: ClientConfig) -> None:")
 	body.push("        self._config = config")
+	body.push("        self._auth = _AuthState(config.bearer_token)")
 	body.push("        self._async_client = httpx.AsyncClient(")
 	body.push("            transport=config.transport,")
 	body.push("        )")
-	body.push("        _inv = config.invalidation")
-	body.push("        self._stale_tracker = _StaleTracker(")
-	body.push("            stale_time=_inv.stale_time if _inv is not None else 0.0,")
-	body.push("            stale_max_entries=(")
-	body.push("                _inv.stale_max_entries if _inv is not None else 1000")
-	body.push("            ),")
-	body.push("            max_sources_per_target=(")
-	body.push("                _inv.max_sources_per_target if _inv is not None else 16")
-	body.push("            ),")
-	body.push("        )")
-	for (const [seg] of namespacesOf(tree)) {
-		const className = nestedClassName([seg])
-		body.push(`        self.${pyIdent(seg)} = ${className}(self)`)
-	}
+	body.push(...trackerInit("_StaleTracker"))
+	for (const c of root.children) body.push(`        self.${c.attr} = ${c.node.asyncName}(self)`)
+	body.push("")
+	body.push("    async def aclose(self) -> None:")
+	body.push('        """Closes the underlying HTTP client."""')
+	body.push("        await self._async_client.aclose()")
 	body.push("")
 	body.push("    async def is_stale(self, method: str, path: str) -> bool:")
 	body.push('        """Returns True when (method, path) sits inside an active stale window."""')
 	body.push("        return await self._stale_tracker.is_stale(method, path)")
 	body.push("")
-
-	for (const op of topLevel.sort((a, b) => a.operationId.localeCompare(b.operationId))) {
-		body.push(...buildMethodSignature(op, throwOnError, true))
-		body.push(...buildMethodDocstring(op))
-		const bodyLines = buildAsyncMethodBody(op, throwOnError, true)
-		body.push(...bodyLines)
+	for (const plan of root.plans) {
+		body.push(...signature(plan, throwOnError, true))
+		body.push(...docstring(plan.op))
+		body.push(...methodBody(plan, throwOnError, true, true))
 		body.push("")
 	}
 
-	const bodyText = body.join("\n")
+	return body.join("\n")
+}
+
+function clientFile(bodyText: string, names: PyNames): string {
+	const uses = (sym: string) => new RegExp(`(?<![\\w.])${sym.replace(/[.]/g, "\\.")}\\b`).test(bodyText)
 	const imports: string[] = []
-	if (/\basyncio\b/.test(bodyText)) imports.push("import asyncio")
 	if (/\bthreading\b/.test(bodyText)) imports.push("import threading")
 	if (/\buuid\.uuid4\b/.test(bodyText)) imports.push("import uuid")
 	imports.push("import httpx")
-	if (/\bquote\b/.test(bodyText)) imports.push("from urllib.parse import quote")
-
-	const typingUsed: string[] = []
-	if (/\bAny\b/.test(bodyText)) typingUsed.push("Any")
-	if (/\bAsyncIterator\b/.test(bodyText)) typingUsed.push("AsyncIterator")
-	if (/\bLiteral\b/.test(bodyText)) typingUsed.push("Literal")
-	if (/\bNotRequired\b/.test(bodyText)) typingUsed.push("NotRequired")
-	if (/\bTypedDict\b/.test(bodyText)) typingUsed.push("TypedDict")
-	if (typingUsed.length > 0) imports.push(`from typing import ${typingUsed.join(", ")}`)
-
-	const runtimeUsed: string[] = []
-	for (const sym of [
-		"ClientConfig",
-		"InvalidationConfig",
-		"SDKResult",
-		"_build_headers",
-		"_build_url",
-		"_do_request_async",
-		"_do_request_sync",
-		"_parse_body",
-		"_raise_for_status",
-	]) {
-		if (new RegExp(`\\b${sym}\\b`).test(bodyText)) runtimeUsed.push(sym)
-	}
-	if (runtimeUsed.length > 0) {
-		const line = `from ._runtime import ${runtimeUsed.join(", ")}`
-		if (line.length <= 88) {
-			imports.push(line)
-		} else {
-			imports.push("from ._runtime import (")
-			for (const sym of runtimeUsed) imports.push(`    ${sym},`)
-			imports.push(")")
-		}
-	}
-
-	const invalidationUsed: string[] = []
-	for (const sym of ["_StaleTracker", "_StaleTrackerSync", "interpolate_path"]) {
-		if (new RegExp(`\\b${sym}\\b`).test(bodyText)) invalidationUsed.push(sym)
-	}
-	if (invalidationUsed.length > 0) {
-		imports.push(`from ._invalidation import ${invalidationUsed.join(", ")}`)
-	}
-
-	/* APIStatusError only appears in docstring Raises sections, never as a code symbol */
-	const errorsUsed: string[] = []
-	for (const sym of ["APIError", "_STATUS_ERROR_MAP"]) {
-		if (new RegExp(`\\b${sym}\\b`).test(bodyText)) errorsUsed.push(sym)
-	}
-	if (errorsUsed.length > 0) {
-		imports.push(`from ._errors import ${errorsUsed.join(", ")}`)
-	}
-
-	const sseUsed: string[] = []
-	for (const sym of ["SSEEvent", "parse_sse_stream"]) {
-		if (new RegExp(`\\b${sym}\\b`).test(bodyText)) sseUsed.push(sym)
-	}
-	if (sseUsed.length > 0) {
-		imports.push(`from ._sse import ${sseUsed.join(", ")}`)
-	}
 
-	if (/\b_TypedWebSocket\b/.test(bodyText)) {
-		imports.push("from ._ws import _TypedWebSocket")
-	}
-
-	const transportUsed: string[] = []
-	for (const sym of ["LongpollAdapter", "SseAdapter", "TransportOpts", "WsAdapter"]) {
-		if (new RegExp(`\\b${sym}\\b`).test(bodyText)) transportUsed.push(sym)
-	}
-	if (transportUsed.length > 0) {
-		imports.push(`from ._transport import ${transportUsed.join(", ")}`)
-	}
+	const typingUsed = ["Any", "AsyncIterator", "Literal", "NotRequired", "TypedDict"].filter(uses)
+	if (typingUsed.length > 0) imports.push(`from typing import ${typingUsed.join(", ")}`)
 
-	if (/\bResumableConnection\b/.test(bodyText)) {
-		imports.push("from ._realtime import ResumableConnection")
+	for (const [mod, syms] of PY_CLIENT_IMPORTS) {
+		const used = syms.filter(uses)
+		if (used.length === 0) continue
+		imports.push(`from ${mod} import (`)
+		for (const s of used) imports.push(`    ${s},`)
+		imports.push(")")
 	}
 
-	const usedSchemas = schemaNames.filter((n) => new RegExp(`\\b${n}\\b`).test(bodyText))
-	if (usedSchemas.length > 0) {
-		const typesLine = `from .types import ${usedSchemas.join(", ")}`
-		if (typesLine.length <= 88) {
-			imports.push(typesLine)
-		} else {
-			imports.push("from .types import (")
-			for (const name of usedSchemas) imports.push(`    ${name},`)
-			imports.push(")")
-		}
+	const typeNames = [...names.schemaNames.values(), ...names.declOrder].filter(uses).sort(cmpCodeUnit)
+	if (typeNames.length > 0) {
+		imports.push("from .types import (")
+		for (const n of typeNames) imports.push(`    ${n},`)
+		imports.push(")")
 	}
 
 	const out: string[] = []
@@ -941,89 +838,59 @@ function buildPyClient(
 	out.push(...imports)
 	out.push("")
 	out.push(bodyText)
+	out.push("")
 	return out.join("\n")
 }
 
-function buildPyInit(spec: Record<string, unknown>): string {
-	const errorClasses = [
-		"APIError",
-		"APIStatusError",
-		"BadGatewayError",
-		"BadRequestError",
-		"ConflictError",
-		"ForbiddenError",
-		"GatewayTimeoutError",
-		"InternalServerError",
-		"NotFoundError",
-		"RateLimitError",
-		"ServiceUnavailableError",
-		"UnauthorizedError",
-		"UnprocessableEntityError",
-	]
-
-	const transportExports = [
-		"LongpollAdapter",
-		"SseAdapter",
-		"TransportAdapter",
-		"TransportConn",
-		"TransportKind",
-		"TransportOpts",
-		"WsAdapter",
-	]
-
-	const realtimeExports = ["ConnectionState", "ResumableConnection"]
+function buildPyInit(names: PyNames): string {
+	const typeNames = [...names.schemaNames.values()].sort(cmpCodeUnit)
 
 	const l: string[] = []
 	l.push(PYTHON_FUTURE)
 	l.push("")
 	l.push("from .client import AsyncSDK, SDK")
 	l.push("from ._errors import (")
-	for (const name of errorClasses) {
-		l.push(`    ${name},`)
-	}
+	for (const name of ERROR_CLASSES) l.push(`    ${name},`)
 	l.push(")")
+	l.push("from ._runtime import ClientConfig, InvalidationConfig, PathParamError")
 	l.push("from ._transport import (")
-	for (const name of transportExports) {
-		l.push(`    ${name},`)
-	}
+	for (const name of TRANSPORT_EXPORTS) l.push(`    ${name},`)
 	l.push(")")
 	l.push("from ._realtime import (")
-	for (const name of realtimeExports) {
-		l.push(`    ${name},`)
-	}
+	for (const name of REALTIME_EXPORTS) l.push(`    ${name},`)
 	l.push(")")
-
-	const schemas = (spec.components as Record<string, unknown> | undefined)?.schemas as
-		| Record<string, Record<string, unknown>>
-		| undefined
-	const schemaNames = schemas ? Object.keys(schemas).sort() : []
-	if (schemaNames.length > 0) {
+	if (typeNames.length > 0) {
 		l.push("from .types import (")
-		for (const name of schemaNames) {
-			l.push(`    ${name},`)
-		}
+		for (const name of typeNames) l.push(`    ${name},`)
 		l.push(")")
 	}
 
 	l.push("")
-	const allExports = ["AsyncSDK", "SDK", ...errorClasses, ...transportExports, ...realtimeExports, ...schemaNames]
+	const allExports = [
+		"AsyncSDK",
+		"SDK",
+		...ERROR_CLASSES,
+		"ClientConfig",
+		"InvalidationConfig",
+		"PathParamError",
+		...TRANSPORT_EXPORTS,
+		...REALTIME_EXPORTS,
+		...typeNames,
+	]
 	l.push("__all__ = [")
-	for (const name of allExports) {
-		l.push(`    "${name}",`)
-	}
+	for (const name of allExports) l.push(`    ${pyString(name)},`)
 	l.push("]")
-
+	l.push("")
 	return l.join("\n")
 }
 
-function buildServiceMap(spec: Record<string, unknown>): Record<string, ServiceMapEntry> {
-	const ops = collectOperations(spec)
-	const result: Record<string, ServiceMapEntry> = {}
-	for (const op of ops) {
-		result[op.operationId] = {
-			invalidate: op.invalidate.length > 0 ? op.invalidate : undefined,
+function buildServiceMap(model: SdkModel): Record<string, ServiceMapEntry> {
+	const result: Record<string, ServiceMapEntry> = Object.create(null)
+	for (const op of model.ops) {
+		result[op.id] = {
+			invalidate: op.invalidates.length > 0 ? op.invalidates : undefined,
 			method: op.method,
-			operationId: op.operationId,
+			operationId: op.id,
 			path: op.path,
 		}
 	}
@@ -1032,17 +899,18 @@ function buildServiceMap(spec: Record<string, unknown>): Record<string, ServiceM
 
 export function generatePythonSDK(spec: Record<string, unknown>, options: PySDKOptions = {}): PySDKResult {
 	const templates = loadPythonRuntimeTemplates()
-	const serviceMap = buildServiceMap(spec)
+	const model = buildSdkModel(spec as unknown as OpenApiSpecInput)
+	const serviceMap = buildServiceMap(model)
+	const names = buildPyNames(model)
 
 	const files: Record<string, string> = {}
+	for (const [name, content] of templates) files[name] = content
 
-	for (const [name, content] of templates) {
-		files[name] = content
-	}
-
-	files["types.py"] = buildPyTypes(spec)
-	files["client.py"] = buildPyClient(spec, options, serviceMap)
-	files["__init__.py"] = buildPyInit(spec)
+	/* schema types claim their names first; the client then hoists into the same table */
+	const schemaSource = buildPyTypes(model, names)
+	files["client.py"] = clientFile(buildPyClient(model, names, options, serviceMap), names)
+	files["types.py"] = typesFile(schemaSource, names)
+	files["__init__.py"] = buildPyInit(names)
 
 	return { files, serviceMap }
 }