@workos/oagen-emitters 0.3.0 → 0.5.0

package/src/php/wrappers.ts

@@ -31,13 +31,14 @@ function emitWrapperMethod(
   // PHPDoc block
   const docParts: string[] = [];
   for (const { paramName, field, isOptional } of wrapperParams) {
-    const docType = field ? mapTypeRefForPHPDoc(field.type) : 'mixed';
+    const docType = field ? mapTypeRefForPHPDoc(field.type) : 'string';
     const nullSuffix = isOptional && !docType.endsWith('|null') ? '|null' : '';
     docParts.push(`@param ${docType}${nullSuffix} $${fieldName(paramName)}`);
   }
   const op2 = resolvedOp.operation;
   const returnDocType = op2.response.kind === 'model' ? `\\${ns}\\Resource\\${className(op2.response.name)}` : 'mixed';
   docParts.push(`@return ${returnDocType}`);
+  docParts.push(`@throws \\${ns}\\Exception\\WorkOSException`);
   lines.push(...phpDocComment(docParts.join('\n'), 4));
 
   lines.push(`    public function ${method}(`);
@@ -56,7 +57,11 @@ function emitWrapperMethod(
         requiredParams.push(`        ${phpType} $${phpName},`);
       }
     } else {
-      optionalParamLines.push(`        mixed $${phpName} = null,`);
+      if (isOptional) {
+        optionalParamLines.push(`        ?string $${phpName} = null,`);
+      } else {
+        requiredParams.push(`        string $${phpName},`);
+      }
     }
   }
   optionalParamLines.push(`        ?\\${ns}\\RequestOptions $options = null,`);

package/src/plugin.ts

@@ -0,0 +1,50 @@
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import type { OagenConfig } from '@workos/oagen';
+import { nodeEmitter } from './node/index.js';
+import { pythonEmitter } from './python/index.js';
+import { phpEmitter } from './php/index.js';
+import { goEmitter } from './go/index.js';
+import { dotnetEmitter } from './dotnet/index.js';
+import { kotlinEmitter } from './kotlin/index.js';
+import { rubyEmitter } from './ruby/index.js';
+import { nodeExtractor } from './compat/extractors/node.js';
+import { rubyExtractor } from './compat/extractors/ruby.js';
+import { pythonExtractor } from './compat/extractors/python.js';
+import { phpExtractor } from './compat/extractors/php.js';
+import { goExtractor } from './compat/extractors/go.js';
+import { rustExtractor } from './compat/extractors/rust.js';
+import { kotlinExtractor } from './compat/extractors/kotlin.js';
+import { dotnetExtractor } from './compat/extractors/dotnet.js';
+import { elixirExtractor } from './compat/extractors/elixir.js';
+
+// Resolve smoke runner paths relative to the package root so they work
+// regardless of which project loads the config (CWD-independent).
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const smokeDir = path.resolve(__dirname, '..', 'smoke');
+
+export const workosEmittersPlugin: Pick<OagenConfig, 'emitters' | 'extractors' | 'smokeRunners'> = {
+  emitters: [nodeEmitter, pythonEmitter, phpEmitter, goEmitter, dotnetEmitter, kotlinEmitter, rubyEmitter],
+  extractors: [
+    nodeExtractor,
+    rubyExtractor,
+    pythonExtractor,
+    phpExtractor,
+    goExtractor,
+    rustExtractor,
+    kotlinExtractor,
+    dotnetExtractor,
+    elixirExtractor,
+  ],
+  smokeRunners: {
+    node: path.join(smokeDir, 'sdk-node.ts'),
+    ruby: path.join(smokeDir, 'sdk-ruby.ts'),
+    python: path.join(smokeDir, 'sdk-python.ts'),
+    php: path.join(smokeDir, 'sdk-php.ts'),
+    go: path.join(smokeDir, 'sdk-go.ts'),
+    rust: path.join(smokeDir, 'sdk-rust.ts'),
+    elixir: path.join(smokeDir, 'sdk-elixir.ts'),
+    kotlin: path.join(smokeDir, 'sdk-kotlin.ts'),
+    dotnet: path.join(smokeDir, 'sdk-dotnet.ts'),
+  },
+};

package/src/python/client.ts

@@ -1,23 +1,17 @@
 import type { ApiSpec, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
 import { toPascalCase } from '@workos/oagen';
 import { className, resolveServiceDir, servicePropertyName, buildMountDirMap, dirToModule } from './naming.js';
-import { resolveResourceClassName } from './resources.js';
-import { getMountTarget } from '../shared/resolved-ops.js';
+import { resolveResourceClassName, collectParameterGroupClassNames } from './resources.js';
+import { getMountTarget, groupByMount } from '../shared/resolved-ops.js';
 import { NON_SPEC_SERVICES } from '../shared/non-spec-services.js';
 
 /** Python-specific wiring for each non-spec service. */
 interface PythonNonSpecWiring {
-  /** Python import line (e.g. "from .vault import Vault, AsyncVault") */
   importLine: string;
-  /** Property name on the client class */
   prop: string;
-  /** Sync class name */
   syncClass: string;
-  /** Async class name, or null if no async variant */
   asyncClass: string | null;
-  /** Constructor expression — 'self' if the class takes the client, '' if stateless */
   ctorArg: 'self' | '';
-  /** One-line docstring for the client property */
   docstring?: string;
 }
 
@@ -159,13 +153,25 @@ function generateWorkOSClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     const resolvedName = resolveResourceClassName(service, ctx);
     const clsName = className(resolvedName);
     const dirName = serviceDirMap.get(service.name) ?? resolveServiceDir(resolvedName);
-    lines.push(`from .${dirToModule(dirName)}._resource import ${clsName}, Async${clsName}`);
+    const importLine = `from .${dirToModule(dirName)}._resource import ${clsName}, Async${clsName}`;
+    if (importLine.length > 88) {
+      lines.push(`from .${dirToModule(dirName)}._resource import (`);
+      lines.push(`    ${clsName},`);
+      lines.push(`    Async${clsName},`);
+      lines.push(')');
+    } else {
+      lines.push(importLine);
+    }
   }
-  // Non-spec service imports (driven by shared/non-spec-services.ts)
+  // Non-spec service imports — wrapped in ignore markers so the merger
+  // matches them positionally and doesn't displace them.
+  lines.push('');
+  lines.push('# @oagen-ignore-start — non-spec service imports (hand-maintained)');
   for (const s of NON_SPEC_SERVICES) {
     const w = PYTHON_NON_SPEC_WIRING[s.id];
     if (w) lines.push(w.importLine);
   }
+  lines.push('# @oagen-ignore-end');
   lines.push('');
   lines.push('');
 
@@ -188,7 +194,7 @@ function generateWorkOSClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     generatedProps.add(prop);
   }
   emitCompatClientPropertyAliases(lines, generatedProps, false);
-  emitCompatClientAccessors(lines, false);
+  emitNonSpecClientAccessors(lines, false);
 
   lines.push('');
   lines.push('');
@@ -211,29 +217,59 @@ function generateWorkOSClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     asyncGeneratedProps.add(prop);
   }
   emitCompatClientPropertyAliases(lines, asyncGeneratedProps, true);
-  emitCompatClientAccessors(lines, true);
+  emitNonSpecClientAccessors(lines, true);
 
   return [
     {
       path: `src/${ctx.namespace}/_client.py`,
       content: lines.join('\n'),
-      integrateTarget: true,
       overwriteExisting: true,
     },
   ];
 }
 
+function emitNonSpecClientAccessors(lines: string[], isAsync: boolean): void {
+  lines.push('');
+  lines.push('    # @oagen-ignore-start — non-spec service accessors (hand-maintained)');
+  for (const s of NON_SPEC_SERVICES) {
+    const w = PYTHON_NON_SPEC_WIRING[s.id];
+    if (!w) continue;
+    const typeName = isAsync ? (w.asyncClass ?? w.syncClass) : w.syncClass;
+    const arg = w.ctorArg === 'self' ? 'self' : '';
+
+    lines.push('');
+    lines.push('    @functools.cached_property');
+    lines.push(`    def ${w.prop}(self) -> ${typeName}:`);
+    if (w.docstring) {
+      lines.push(`        """${w.docstring}"""`);
+    }
+    lines.push(`        return ${typeName}(${arg})`);
+  }
+  lines.push('');
+  lines.push('    # @oagen-ignore-end');
+}
+
 function generateServiceInits(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
   const topLevel = deduplicateByMount(spec.services, ctx);
   const serviceDirMap = buildMountDirMap(ctx);
 
+  // Build a map from mount target -> operations so we can discover parameter
+  // group dataclasses that need re-exporting from __init__.py.
+  const mountGroups = groupByMount(ctx);
+
   for (const service of topLevel) {
     const resolvedName = resolveResourceClassName(service, ctx);
     const dirName = serviceDirMap.get(service.name) ?? resolveServiceDir(resolvedName);
     const lines: string[] = [];
 
-    lines.push(`from ._resource import ${resolvedName}, Async${resolvedName}`);
+    // Collect parameter group class names from all operations in this mount group
+    const mountTarget = getMountTarget(service, ctx);
+    const ops = mountGroups.get(mountTarget)?.operations ?? service.operations;
+    const groupClassNames = collectParameterGroupClassNames(ops);
+
+    const resourceImports = [resolvedName, `Async${resolvedName}`, ...groupClassNames];
+    lines.push(`from ._resource import ${resourceImports.join(', ')}`);
     lines.push('from .models import *');
 
     files.push({
@@ -274,24 +310,6 @@ function emitCompatClientPropertyAliases(lines: string[], generatedProps: Set<st
   }
 }
 
-function emitCompatClientAccessors(lines: string[], isAsync: boolean): void {
-  for (const s of NON_SPEC_SERVICES) {
-    const w = PYTHON_NON_SPEC_WIRING[s.id];
-    if (!w) continue;
-    // Skip async-only services when emitting the sync client, and vice versa
-    const typeName = isAsync ? (w.asyncClass ?? w.syncClass) : w.syncClass;
-    const arg = w.ctorArg === 'self' ? 'self' : '';
-
-    lines.push('');
-    lines.push('    @functools.cached_property');
-    lines.push(`    def ${w.prop}(self) -> ${typeName}:`);
-    if (w.docstring) {
-      lines.push(`        """${w.docstring}"""`);
-    }
-    lines.push(`        return ${typeName}(${arg})`);
-  }
-}
-
 /**
  * Generate types/<service>/__init__.py re-export barrels so that
  * `from workos.types.<service> import Model` continues to work.

package/src/python/enums.ts

@@ -37,12 +37,14 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
     // If this enum is an alias for a canonical enum, generate a type alias file
     const canonicalName = aliasOf.get(enumDef.name);
     if (canonicalName) {
+      // Skip when alias and canonical produce the same file name (self-import)
+      if (fileName(enumDef.name) === fileName(canonicalName)) continue;
       const canonicalService = enumToService.get(canonicalName);
       const canonicalDir = resolveDir(canonicalService);
       const canonicalCls = className(canonicalName);
       const aliasCls = className(enumDef.name);
       const lines: string[] = [];
-      lines.push('from typing_extensions import TypeAlias');
+      lines.push('from typing import TypeAlias');
       // Use explicit __all__ to prevent ruff F401 from stripping the re-export
       // Always use direct file import to avoid barrel dependency on the canonical
       if (canonicalDir === dirName) {
@@ -71,7 +73,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
         files.push({
           path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
           content: [
-            'from typing_extensions import TypeAlias',
+            'from typing import TypeAlias',
             importLine,
             '',
             `${aliasName}: TypeAlias = ${canonicalCls}`,
@@ -96,7 +98,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
 
     if (enumDef.values.length === 0) {
       lines.push('from typing import Union');
-      lines.push('from typing_extensions import TypeAlias');
+      lines.push('from typing import TypeAlias');
       lines.push('');
       lines.push(`${cls}: TypeAlias = str`);
     } else {
@@ -118,7 +120,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       if (allStrings) {
         lines.push('from enum import Enum');
         lines.push('from typing import Optional');
-        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('from typing import Literal, TypeAlias');
         lines.push('');
         lines.push('');
         lines.push(`class ${cls}(str, Enum):`);
@@ -126,7 +128,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
         lines.push('');
       } else if (allIntegers) {
         lines.push('from enum import IntEnum');
-        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('from typing import Literal, TypeAlias');
         lines.push('');
         lines.push('');
         lines.push(`class ${cls}(IntEnum):`);
@@ -135,9 +137,17 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       } else {
         // Mixed types — fall back to Union[Literal[...], str]
         lines.push('from typing import Union');
-        lines.push('from typing_extensions import Literal, TypeAlias');
+        lines.push('from typing import Literal, TypeAlias');
         lines.push('');
-        const literals = uniqueValues.map((v) => (typeof v.value === 'string' ? `"${v.value}"` : String(v.value)));
+        const literals = uniqueValues.map((v) =>
+          typeof v.value === 'string'
+            ? `"${v.value}"`
+            : typeof v.value === 'boolean'
+              ? v.value
+                ? 'True'
+                : 'False'
+              : String(v.value),
+        );
         lines.push(`${cls}: TypeAlias = Union[Literal[${literals.join(', ')}], str]`);
         files.push({
           path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
@@ -157,7 +167,14 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
           memberName = `${memberName}_${suffix}`;
         }
         usedNames.add(memberName);
-        const valueStr = typeof v.value === 'string' ? `"${v.value}"` : String(v.value);
+        const valueStr =
+          typeof v.value === 'string'
+            ? `"${v.value}"`
+            : typeof v.value === 'boolean'
+              ? v.value
+                ? 'True'
+                : 'False'
+              : String(v.value);
         lines.push(`    ${memberName} = ${valueStr}`);
         if (v.description || v.deprecated) {
           const parts: string[] = [];
@@ -180,7 +197,15 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       lines.push('');
       lines.push(
         `${cls}Literal: TypeAlias = Literal[${uniqueValues
-          .map((v) => (typeof v.value === 'string' ? `"${v.value}"` : String(v.value)))
+          .map((v) =>
+            typeof v.value === 'string'
+              ? `"${v.value}"`
+              : typeof v.value === 'boolean'
+                ? v.value
+                  ? 'True'
+                  : 'False'
+                : String(v.value),
+          )
           .join(', ')}]`,
       );
     }
@@ -196,7 +221,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       files.push({
         path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
         content: [
-          'from typing_extensions import TypeAlias',
+          'from typing import TypeAlias',
           `from .${fileName(enumDef.name)} import ${cls}`,
           '',
           `${aliasName}: TypeAlias = ${cls}`,

package/src/python/index.ts

@@ -8,10 +8,9 @@ import type {
   Enum,
   Service,
 } from '@workos/oagen';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 
 import { generateModels } from './models.js';
+import { detectDiscriminators } from '../shared/model-utils.js';
 import { generateEnums } from './enums.js';
 import { generateResources } from './resources.js';
 import { generateClient } from './client.js';
@@ -27,11 +26,23 @@ function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
   return files;
 }
 
+/**
+ * Annotate models with implicit discriminator info (without full oneOf
+ * field flattening which can break existing model structures/fixtures).
+ */
+function withDiscriminators(ctx: EmitterContext): EmitterContext {
+  const annotated = detectDiscriminators(ctx.spec.models);
+  if (annotated === ctx.spec.models) return ctx;
+  const spec: ApiSpec = { ...ctx.spec, models: annotated };
+  return { ...ctx, spec };
+}
+
 export const pythonEmitter: Emitter = {
   language: 'python',
 
   generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateModels(models, ctx));
+    const annotated = detectDiscriminators(models);
+    return ensureTrailingNewlines(generateModels(annotated, ctx));
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
@@ -39,11 +50,11 @@ export const pythonEmitter: Emitter = {
   },
 
   generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateResources(services, ctx));
+    return ensureTrailingNewlines(generateResources(services, withDiscriminators(ctx)));
   },
 
   generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateClient(spec, ctx));
+    return ensureTrailingNewlines(generateClient(spec, withDiscriminators(ctx)));
   },
 
   generateErrors(): GeneratedFile[] {
@@ -59,7 +70,15 @@ export const pythonEmitter: Emitter = {
   },
 
   generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateTests(spec, ctx));
+    // Use original spec for model filtering (requestOnlyModelNames etc.) but
+    // annotate discriminator models so dispatch tests are generated.
+    const annotated = detectDiscriminators(spec.models);
+    // Only replace discriminator-annotated models, keep the rest unchanged
+    // so request-only filtering and field-based logic work correctly.
+    const annotatedByName = new Map(annotated.filter((m: any) => m.discriminator).map((m) => [m.name, m]));
+    const testModels = spec.models.map((m) => annotatedByName.get(m.name) ?? m);
+    const testSpec: ApiSpec = { ...spec, models: testModels };
+    return ensureTrailingNewlines(generateTests(testSpec, { ...ctx, spec: testSpec }));
   },
 
   generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
@@ -70,26 +89,15 @@ export const pythonEmitter: Emitter = {
     return '# This file is auto-generated by oagen. Do not edit.';
   },
 
-  formatCommand(targetDir: string): FormatCommand | null {
-    const hasRuff =
-      fs.existsSync(path.join(targetDir, 'ruff.toml')) || fs.existsSync(path.join(targetDir, '.ruff.toml'));
-    // Also check pyproject.toml for [tool.ruff] section
-    const pyproject = path.join(targetDir, 'pyproject.toml');
-    const hasRuffInPyproject = fs.existsSync(pyproject) && fs.readFileSync(pyproject, 'utf8').includes('[tool.ruff]');
-    // Check for noxfile that uses ruff
-    const noxfile = path.join(targetDir, 'noxfile.py');
-    const hasRuffInNox = fs.existsSync(noxfile) && fs.readFileSync(noxfile, 'utf8').includes('ruff');
-
-    if (hasRuff || hasRuffInPyproject || hasRuffInNox) {
-      return {
-        cmd: 'bash',
-        args: [
-          '-c',
-          'PY_FILES=$(printf "%s\\n" "$@" | grep "\\.py$"); [ -n "$PY_FILES" ] && echo "$PY_FILES" | xargs ruff check --fix --quiet 2>/dev/null; [ -n "$PY_FILES" ] && echo "$PY_FILES" | xargs ruff format --quiet',
-          '--',
-        ],
-      };
-    }
-    return null;
+  formatCommand(_targetDir: string): FormatCommand | null {
+    return {
+      cmd: 'bash',
+      args: [
+        '-c',
+        'PY_FILES=$(printf "%s\\n" "$@" | grep "\\.py$" || true); if [ -n "$PY_FILES" ]; then echo "$PY_FILES" | xargs ruff check --fix --quiet 2>/dev/null; echo "$PY_FILES" | xargs ruff format --quiet; fi',
+        '--',
+      ],
+      batchSize: 1000,
+    };
   },
 };

package/src/python/models.ts

@@ -18,6 +18,9 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     irService ? (mountDirMap.get(irService) ?? 'common') : 'common';
   const files: GeneratedFile[] = [];
   const emittedModelSymbolsByDir = new Map<string, string[]>();
+  // Overrides fileName() for symbols that live in a differently-named file.
+  // Used for variant type aliases (e.g. EventSchemaVariant → event_schema).
+  const symbolToFile = new Map<string, string>();
   const modelUsage = collectModelUsage(ctx.spec);
 
   // Build recursive structural hashes for deduplication.
@@ -45,6 +48,10 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     }
   }
 
+  // Track emitted file paths to prevent duplicates when synthetic models from
+  // oneOf enrichment collide with existing IR models in snake_case.
+  const emittedFilePaths = new Set<string>();
+
   for (const model of models) {
     // Skip list wrapper models (e.g., OrganizationList) — SyncPage handles envelopes
     if (isListWrapperModel(model)) continue;
@@ -55,14 +62,140 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     const dirName = resolveDir(service);
     const modelClassName = className(model.name);
 
+    // Skip models whose file path was already emitted (name collision after snake_case)
+    const modelFilePath = `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`;
+    if (emittedFilePaths.has(modelFilePath)) continue;
+    emittedFilePaths.add(modelFilePath);
+
+    // If this model is a discriminated union dispatcher, generate a factory class
+    // instead of a regular dataclass (e.g. EventSchema where each variant has
+    // event: const: "..."). The dispatcher owns a Union type alias and a from_dict
+    // method that routes to the correct concrete variant at runtime.
+    if ((model as any).discriminator) {
+      const disc = (model as any).discriminator as { property: string; mapping: Record<string, string> };
+      const variantNames = Object.values(disc.mapping); // model names, e.g. ["ActionAuthenticationDenied", ...]
+      const variantTypeName = `${modelClassName}Variant`; // e.g. "EventSchemaVariant"
+
+      const dispLines: string[] = [];
+      dispLines.push('from __future__ import annotations');
+      dispLines.push('');
+      dispLines.push('from dataclasses import dataclass');
+      dispLines.push('from typing import Any, ClassVar, Dict, Union, cast');
+      dispLines.push(`from ${ctx.namespace}._types import _raise_deserialize_error`);
+      dispLines.push('');
+
+      // Import each variant model from its resolved location
+      const sortedVariants = [...new Set(variantNames)].sort();
+      for (const variantModelName of sortedVariants) {
+        const variantService = modelToService.get(variantModelName);
+        const variantDir = resolveDir(variantService);
+        if (variantDir === dirName) {
+          dispLines.push(`from .${fileName(variantModelName)} import ${className(variantModelName)}`);
+        } else {
+          dispLines.push(
+            `from ${ctx.namespace}.${dirToModule(variantDir)}.models.${fileName(variantModelName)} import ${className(variantModelName)}`,
+          );
+        }
+      }
+
+      // Unknown variant for forward-compatible unknown discriminator values
+      const unknownClassName = `${modelClassName}Unknown`;
+      dispLines.push('');
+      dispLines.push('');
+      dispLines.push('@dataclass(slots=True)');
+      dispLines.push(`class ${unknownClassName}:`);
+      dispLines.push(`    """Unknown variant of ${modelClassName} not yet recognized by this SDK version."""`);
+      dispLines.push('');
+      dispLines.push('    raw_data: Dict[str, Any]');
+      dispLines.push('    """The raw payload, preserved so callers can still inspect the data."""');
+      dispLines.push('');
+      dispLines.push('    @classmethod');
+      dispLines.push(`    def from_dict(cls, data: Dict[str, Any]) -> "${unknownClassName}":`);
+      dispLines.push('        """Wrap raw data in an unknown variant."""');
+      dispLines.push('        return cls(raw_data=data)');
+      dispLines.push('');
+      dispLines.push('    def to_dict(self) -> Dict[str, Any]:');
+      dispLines.push('        """Return the original raw data."""');
+      dispLines.push('        return dict(self.raw_data)');
+
+      dispLines.push('');
+      dispLines.push('');
+
+      // Union type alias — includes unknown variant for forward compatibility
+      dispLines.push(`${variantTypeName} = Union[`);
+      for (const variantModelName of sortedVariants) {
+        dispLines.push(`    ${className(variantModelName)},`);
+      }
+      dispLines.push(`    ${unknownClassName},`);
+      dispLines.push(']');
+
+      dispLines.push('');
+      dispLines.push('');
+
+      // Dispatcher class
+      if (model.description) {
+        dispLines.push(`class ${modelClassName}:`);
+        dispLines.push(`    """${model.description}"""`);
+      } else {
+        dispLines.push(`class ${modelClassName}:`);
+        dispLines.push(`    """Discriminated union dispatcher (discriminated by '${disc.property}')."""`);
+      }
+      dispLines.push('');
+      dispLines.push(`    _DISPATCH: ClassVar[Dict[str, type]] = {`);
+      for (const [value, variantModelName] of Object.entries(disc.mapping).sort(([a], [b]) => a.localeCompare(b))) {
+        dispLines.push(`        "${value}": ${className(variantModelName)},`);
+      }
+      dispLines.push('    }');
+      dispLines.push('');
+      dispLines.push('    @classmethod');
+      dispLines.push(`    def from_dict(cls, data: Dict[str, Any]) -> "${variantTypeName}":`);
+      dispLines.push('        """Deserialize from a dictionary, dispatching to the correct variant."""');
+      dispLines.push(`        if "${disc.property}" not in data:`);
+      dispLines.push(
+        `            _raise_deserialize_error("${modelClassName}", ValueError("Missing required field '${disc.property}'"))`,
+      );
+      dispLines.push(`        disc_value = data["${disc.property}"]`);
+      dispLines.push('        if disc_value is None:');
+      dispLines.push(
+        `            _raise_deserialize_error("${modelClassName}", ValueError("${disc.property} must not be None"))`,
+      );
+      dispLines.push('        dispatch_cls = cls._DISPATCH.get(disc_value)');
+      dispLines.push('        if dispatch_cls is not None:');
+      dispLines.push(`            return cast("${variantTypeName}", dispatch_cls.from_dict(data))`);
+      dispLines.push(`        return ${unknownClassName}.from_dict(data)`);
+
+      files.push({
+        path: `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`,
+        content: dispLines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+
+      if (!emittedModelSymbolsByDir.has(dirName)) emittedModelSymbolsByDir.set(dirName, []);
+      emittedModelSymbolsByDir.get(dirName)!.push(model.name);
+      // Also register the variant type alias and unknown variant in the barrel,
+      // pointing to the same file as the dispatcher.
+      emittedModelSymbolsByDir.get(dirName)!.push(variantTypeName);
+      symbolToFile.set(variantTypeName, fileName(model.name));
+      emittedModelSymbolsByDir.get(dirName)!.push(unknownClassName);
+      symbolToFile.set(unknownClassName, fileName(model.name));
+      continue;
+    }
+
     // If this model is an alias for a canonical model, generate a type alias file
     const canonicalName = aliasOf.get(model.name);
     if (canonicalName) {
+      // Skip when alias and canonical produce the same file name (self-import).
+      // This happens when synthetic models from oneOf enrichment collide with
+      // existing IR models in snake_case (e.g., Foo_bar vs FooBar).
+      if (fileName(model.name) === fileName(canonicalName)) {
+        continue;
+      }
       const canonicalService = modelToService.get(canonicalName);
       const canonicalDir = resolveDir(canonicalService);
       const canonicalClassName = className(canonicalName);
       const lines: string[] = [];
-      lines.push('from typing_extensions import TypeAlias');
+      lines.push('from typing import TypeAlias');
       // Always use direct file import to avoid barrel dependency on the canonical
       if (canonicalDir === dirName) {
         lines.push(`from .${fileName(canonicalName)} import ${canonicalClassName}`);
@@ -312,7 +445,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     const uniqueNames = [...new Set(names)].sort();
     const importLines: string[] = [];
     for (const name of uniqueNames) {
-      importLines.push(`from .${fileName(name)} import ${className(name)} as ${className(name)}`);
+      const fileNameForSymbol = symbolToFile.get(name) ?? fileName(name);
+      importLines.push(`from .${fileNameForSymbol} import ${className(name)} as ${className(name)}`);
     }
     const imports = importLines.join('\n');
     files.push({
@@ -473,6 +607,9 @@ function compareAliasPriority(left: string, right: string, usage: ReturnType<typ
 }
 
 function canAliasModels(canonical: string, alias: string, usage: ReturnType<typeof collectModelUsage>): boolean {
+  // Don't alias when both models produce the same file name — the TypeAlias
+  // file would import from itself (e.g., FooBar aliased to Foo_bar).
+  if (fileName(canonical) === fileName(alias)) return false;
   // Don't alias across request/response boundaries — a request-only model
   // and a response-only model may look identical today but evolve independently.
   if (

package/src/python/naming.ts

@@ -1,24 +1,7 @@
 import type { Operation, Service, EmitterContext } from '@workos/oagen';
 import { toPascalCase, toSnakeCase } from '@workos/oagen';
 import { buildResolvedLookup, lookupMethodName, getMountTarget } from '../shared/resolved-ops.js';
-import { stripUrnPrefix } from '../shared/naming-utils.js';
-
-/**
- * Map of lowercase acronym forms to their correct casing.
- * Applied as a post-processing step after toPascalCase.
- */
-const ACRONYM_FIXES: [RegExp, string][] = [
-  [/Workos/g, 'WorkOS'],
-  [/Sso/g, 'SSO'],
-  [/Mfa/g, 'MFA'],
-  [/Jwt/g, 'JWT'],
-  [/Cors/g, 'CORS'],
-  [/Saml/g, 'SAML'],
-  [/Scim/g, 'SCIM'],
-  [/Rbac/g, 'RBAC'],
-  [/Oauth/g, 'OAuth'],
-  [/Oidc/g, 'OIDC'],
-];
+import { stripUrnPrefix, applyAcronymFixes } from '../shared/naming-utils.js';
 
 /**
  * Python class names that collide with builtins or typing imports.
@@ -41,10 +24,7 @@ const PYTHON_RESERVED_CLASS_NAMES = new Set([
 
 /** PascalCase class name with acronym preservation. */
 export function className(name: string): string {
-  let result = toPascalCase(stripUrnPrefix(name));
-  for (const [pattern, replacement] of ACRONYM_FIXES) {
-    result = result.replace(pattern, replacement);
-  }
+  let result = applyAcronymFixes(toPascalCase(stripUrnPrefix(name)));
   if (PYTHON_RESERVED_CLASS_NAMES.has(result)) {
     result += 'Model';
   }