fix(python): deduplicate stream condition properties in discriminated union variants (#14874)

* feat(seed): augment server-sent-events-openapi fixture with x-fern-streaming test cases

Add endpoints 8-14 covering x-fern-streaming extension patterns that have
been the source of multiple regressions:

- Endpoint 8: basic stream-condition with $ref request body (#13568)
- Endpoint 9: stream-condition with x-fern-type-name (#14256)
- Endpoints 10-11: shared request schema across streaming/non-streaming (#14291)
- Endpoint 12: discriminated union request with allOf-inherited stream
  condition field, reproducing the Vectara regression (FER-9556, #14730)
- Endpoint 13: nullable stream condition field (#13605)
- Endpoint 14: x-fern-streaming with SSE format only (no stream-condition)

* chore(seed): add debug script for SSE pipeline stage inspection

Runs the locally-built Fern CLI against the server-sent-events-openapi
fixture through each transformation stage (openapi-ir, write-definition,
ir), collecting outputs in .local/results/ for inspection. Continues
past failures so all stages produce output even when earlier ones error.

Usage: pnpm tsx scripts/debug-sse-pipeline.ts

* chore(seed): comment out endpoint 9 (x-fern-type-name collision)

Endpoint 9's ChatCompletionRequest name collision blocks IR generation
for the entire fixture. Comment it out so the remaining endpoints can
be tested end-to-end. Uncomment when investigating the x-fern-type-name
disambiguation fix (PR #14256) in isolation.

* fix: deduplicate stream condition properties in discriminated union variants

When a discriminated union's variants inherit the stream condition field
from a base schema via extends, the property appeared twice in generated
Python code — once from the union's base properties (pinned as a literal)
and once from the variant's extended properties (as boolean). This caused
SyntaxError: Duplicate keyword argument in generated wire tests and
pydantic model definitions.

Two fixes:
1. DynamicTypeLiteralMapper.ts: filter objectEntries that overlap with
   baseFields when building samePropertiesAsObject variant constructor args
2. simple_discriminated_union_generator.py: skip variant properties whose
   wire_value matches any union base property

Fixes FER-9556

Co-Authored-By: bot_apk <apk@cognition.ai>

* chore: update ir-to-jsonschema snapshots for server-sent-events-openapi fixture

Co-Authored-By: bot_apk <apk@cognition.ai>

* chore: add server-sent-events-openapi to go-sdk allowed failures

Co-Authored-By: bot_apk <apk@cognition.ai>

* fix: preserve AST references for streaming endpoint imports in wire tests

Co-Authored-By: bot_apk <apk@cognition.ai>

* style: fix biome formatting in WireTestGenerator.ts

Co-Authored-By: bot_apk <apk@cognition.ai>

* fix: escape triple quotes in docstrings and suppress mypy overload errors in exported client wrapper

Co-Authored-By: judah <jsklan.development@gmail.com>

* chore: update seed snapshot for exported client type ignore comment

Co-Authored-By: judah <jsklan.development@gmail.com>

* fix: use actual stream condition property name in WireMock body patterns

Instead of hardcoding 'stream' in the matchesJsonPath body pattern,
extract the actual stream condition property name from the SSE endpoint's
example request body. This fixes WireMock stub routing for APIs that use
a different property name (e.g. 'stream_response' in the Vectara API).

Co-Authored-By: judah <jsklan.development@gmail.com>

* fix: use explicit None check for mypy type narrowing in wrapper class

Co-Authored-By: judah <jsklan.development@gmail.com>

* fix: update CLI changelog version ordering and regenerate IR test snapshots

Co-Authored-By: judah <jsklan.development@gmail.com>

* nit

* fix(python): replace type: ignore with proper @overload signatures in exported client wrapper

Mirror the base client's @overload signatures on the wrapper class and
use **kwargs pass-through for super().__init__(), so mypy is satisfied
without suppressing the error.

---------

Co-authored-by: jsklan <jsklan.development@gmail.com>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: bot_apk <apk@cognition.ai>
Co-authored-by: jsklan <100491078+jsklan@users.noreply.github.com>

Author: 3 people

generators/python-v2/dynamic-snippets/src/context/DynamicTypeLiteralMapper.ts

@@ -271,7 +271,12 @@ export class DynamicTypeLiteralMapper {
                     object_: named,
                     value: discriminatedUnionTypeInstance.value
                 });
-                return [...baseFields, ...objectEntries];
+                // Skip object entries that overlap with base fields to avoid
+                // duplicate keyword arguments (e.g. stream condition properties
+                // inherited via extends that are already pinned as literals).
+                const baseFieldNames = new Set(baseFields.map((f) => f.name));
+                const filteredObjectEntries = objectEntries.filter((entry) => !baseFieldNames.has(entry.name));
+                return [...baseFields, ...filteredObjectEntries];
             }
             case "singleProperty": {
                 try {

generators/python-v2/sdk/src/wire-tests/WireTestGenerator.ts

@@ -368,22 +368,32 @@ export class WireTestGenerator {
             if (isErrorResponse) {
                 // For streaming endpoints, we need to consume the iterator inside pytest.raises
                 if (this.isStreamingEndpoint(endpoint)) {
-                    statements.push(
-                        python.codeBlock(
-                            `with pytest.raises(ApiError):\n        for _ in ${apiCallAst.toString()}:\n            pass`
-                        )
+                    const block = python.codeBlock(
+                        `with pytest.raises(ApiError):\n        for _ in ${apiCallAst.toString()}:\n            pass`
                     );
+                    // Preserve import references from the AST that are lost during toString()
+                    for (const ref of apiCallAst.getReferences()) {
+                        block.addReference(ref);
+                    }
+                    statements.push(block);
                 } else {
-                    statements.push(
-                        python.codeBlock(`with pytest.raises(ApiError):\n        ${apiCallAst.toString()}`)
-                    );
+                    const block = python.codeBlock(`with pytest.raises(ApiError):\n        ${apiCallAst.toString()}`);
+                    for (const ref of apiCallAst.getReferences()) {
+                        block.addReference(ref);
+                    }
+                    statements.push(block);
                 }
             } else {
                 // For streaming endpoints, wrap the call in a for loop to consume the iterator
                 // This is necessary because streaming methods return lazy generators that don't
                 // execute the HTTP request until iterated
                 if (this.isStreamingEndpoint(endpoint)) {
-                    statements.push(python.codeBlock(`for _ in ${apiCallAst.toString()}:`));
+                    const block = python.codeBlock(`for _ in ${apiCallAst.toString()}:`);
+                    // Preserve import references from the AST that are lost during toString()
+                    for (const ref of apiCallAst.getReferences()) {
+                        block.addReference(ref);
+                    }
+                    statements.push(block);
                     statements.push(python.codeBlock("    pass"));
                 } else {
                     statements.push(apiCallAst);

generators/python/sdk/versions.yml

@@ -1,5 +1,26 @@
 # yaml-language-server: $schema=../../../fern-versions-yml.schema.json
 # For unreleased changes, use unreleased.yml
+- version: 5.3.11
+  changelogEntry:
+    - summary: |
+        Fix duplicate keyword arguments in generated code for discriminated union
+        request bodies with stream condition properties. When a union variant inherits
+        the stream condition field from a base schema via extends, the property was
+        emitted twice — once from the union's base properties and once from the
+        variant's extended properties — causing SyntaxError in generated Python code.
+      type: fix
+    - summary: |
+        Escape triple quotes in docstrings to prevent premature docstring termination
+        when OpenAPI descriptions contain Python code examples with triple-quoted strings.
+      type: fix
+    - summary: |
+        Fix mypy call-overload errors in exported client wrapper by mirroring the
+        base client's @overload signatures and using **kwargs pass-through, instead
+        of suppressing the error with a type: ignore comment.
+      type: fix
+  createdAt: "2026-04-10"
+  irVersion: 65
+
 - version: 5.3.10
   changelogEntry:
     - summary: |

generators/python/src/fern_python/codegen/ast/nodes/docstring/docstring.py

@@ -8,11 +8,14 @@
 
 def escape_docstring(text: str) -> str:
     """
-    Escape backslashes in docstrings to avoid SyntaxWarning for invalid escape sequences.
-    This is needed when docstrings contain backslashes in source text (e.g., FOO\\_BAR)
-    that would otherwise produce invalid escape sequences.
+    Escape special characters in docstrings to avoid syntax errors.
+    - Backslashes are escaped to prevent invalid escape sequences (e.g., FOO\\_BAR).
+    - Triple quotes are escaped to prevent premature docstring termination when
+      descriptions contain code examples with triple-quoted strings.
     """
-    return text.replace("\\", "\\\\")
+    result = text.replace("\\", "\\\\")
+    result = result.replace('"""', '\\"""')
+    return result
 
 
 class Docstring(CodeWriter):

generators/python/src/fern_python/generators/pydantic_model/type_declaration_handler/discriminated_union/simple_discriminated_union_generator.py

@@ -138,11 +138,15 @@ def generate(self) -> None:
                     )
                 ]
                 discriminant_wire_value = self._union.discriminant.wire_value
+                base_property_wire_values = {bp.name.wire_value for bp in self._union.base_properties}
                 object_properties = self._context.get_all_properties_including_extensions(shape.type_id)
                 for object_property in object_properties:
                     # Skip properties that match the discriminant field to avoid duplicate fields
                     if object_property.name.wire_value == discriminant_wire_value:
                         continue
+                    # Skip properties already declared in the union's base properties
+                    if object_property.name.wire_value in base_property_wire_values:
+                        continue
                     self._all_referenced_types.append(object_property.value_type)
                     same_properties_as_object_property_fields.append(
                         FernAwarePydanticField(

generators/python/src/fern_python/generators/sdk/client_generator/generated_root_client.py

@@ -12,6 +12,7 @@ class RootClient:
     class_reference: AST.ClassReference
     parameters: List[ConstructorParameter]
     init_parameters: Optional[List[ConstructorParameter]] = field(default=None)
+    constructor_overloads: Optional[List[AST.FunctionSignature]] = field(default=None)
 
 
 @dataclass

generators/python/src/fern_python/generators/sdk/client_generator/root_client_generator.py

@@ -184,6 +184,8 @@ def __init__(
             base_url_example_value=base_url_example_value,
             sync_init_parameters=self._get_constructor_parameters(is_async=False),
             async_init_parameters=self._get_constructor_parameters(is_async=True),
+            sync_constructor_overloads=self._get_constructor_overloads(is_async=False),
+            async_constructor_overloads=self._get_constructor_overloads(is_async=True),
         )
         self._generated_root_client = root_client_builder.build()
 
@@ -1650,6 +1652,8 @@ def __init__(
             base_url_example_value: Optional[AST.Expression] = None,
             sync_init_parameters: Optional[Sequence[ConstructorParameter]] = None,
             async_init_parameters: Optional[Sequence[ConstructorParameter]] = None,
+            sync_constructor_overloads: Optional[List[AST.FunctionSignature]] = None,
+            async_constructor_overloads: Optional[List[AST.FunctionSignature]] = None,
         ):
             self._module_path = module_path
             self._class_name = class_name
@@ -1664,6 +1668,8 @@ def __init__(
             self._oauth_token_override = oauth_token_override
             self._use_kwargs_snippets = use_kwargs_snippets
             self._base_url_example_value = base_url_example_value
+            self._sync_constructor_overloads = sync_constructor_overloads
+            self._async_constructor_overloads = async_constructor_overloads
 
         def build(self) -> GeneratedRootClient:
             def create_class_reference(class_name: str) -> AST.ClassReference:
@@ -1831,11 +1837,13 @@ def build_default_snippet_kwargs() -> List[typing.Tuple[str, AST.Expression]]:
                     class_reference=async_class_reference,
                     parameters=self._constructor_parameters,
                     init_parameters=self._async_init_parameters,
+                    constructor_overloads=self._async_constructor_overloads,
                 ),
                 sync_instantiations=sync_instantiations,
                 sync_client=RootClient(
                     class_reference=sync_class_reference,
                     parameters=self._constructor_parameters,
                     init_parameters=self._sync_init_parameters,
+                    constructor_overloads=self._sync_constructor_overloads,
                 ),
             )

generators/python/src/fern_python/generators/sdk/sdk_generator.py

@@ -606,6 +606,23 @@ def _create_wrapper_class_declaration(
     ) -> AST.ClassDeclaration:
         params = root_client.init_parameters if root_client.init_parameters is not None else root_client.parameters
 
+        if root_client.constructor_overloads is not None:
+            # When the base class has overloaded __init__ (e.g. OAuth + token),
+            # mirror the overloads on the wrapper and use **kwargs pass-through
+            # so the call to super().__init__() satisfies mypy without type: ignore.
+            def write_kwargs_super_init(writer: AST.NodeWriter) -> None:
+                writer.write_line("super().__init__(**kwargs)")
+
+            return AST.ClassDeclaration(
+                name=class_name,
+                extends=[base_class_ref],
+                constructor=AST.ClassConstructor(
+                    signature=AST.FunctionSignature(include_kwargs=True),
+                    body=AST.CodeWriter(write_kwargs_super_init),
+                    overloads=root_client.constructor_overloads,
+                ),
+            )
+
         named_params = [
             AST.NamedFunctionParameter(
                 name=param.constructor_parameter_name,

packages/cli/fern-definition/ir-to-jsonschema/src/__test__/__snapshots__/server-sent-events-openapi/type__CompletionFullResponse.json

@@ -0,0 +1,36 @@
+{
+  "type": "object",
+  "properties": {
+    "answer": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "finishReason": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/CompletionFullResponseFinishReason"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "CompletionFullResponseFinishReason": {
+      "type": "string",
+      "enum": [
+        "complete",
+        "length",
+        "error"
+      ]
+    }
+  }
+}

packages/cli/fern-definition/ir-to-jsonschema/src/__test__/__snapshots__/server-sent-events-openapi/type__CompletionFullResponseFinishReason.json

@@ -0,0 +1,9 @@
+{
+  "type": "string",
+  "enum": [
+    "complete",
+    "length",
+    "error"
+  ],
+  "definitions": {}
+}