[Search 2026-08-01-preview] python SDK codegen

sdk/search/azure-search-documents/.github/skills/azure-search-documents/SKILL.md

@@ -34,6 +34,10 @@ cd sdk/search/azure-search-documents
 tsp-client update
 # or: azsdk_package_generate_code
 
+# Reapply temporary Python emitter workarounds, then verify they are present:
+python .github/skills/azure-search-documents/scripts/apply_generator_workarounds.py
+python .github/skills/azure-search-documents/scripts/apply_generator_workarounds.py --check
+
 # If the API version changed, _metadata.json updates automatically;
 # reconcile the hand-maintained ApiVersion enum in Step 3.
 ```

sdk/search/azure-search-documents/.github/skills/azure-search-documents/references/customizations.md

@@ -2,6 +2,21 @@
 
 File-by-file inventory of every non-empty `_patch.py` in `azure-search-documents`. Use this after running `tsp-client update` to verify each customization still holds.
 
+## Temporary Python emitter workarounds
+
+ Until the emitter issues encoded in the package-owned rewriter are fixed upstream, run it after
+
+```bash
+python .github/skills/azure-search-documents/scripts/apply_generator_workarounds.py
+python .github/skills/azure-search-documents/scripts/apply_generator_workarounds.py --check
+```
+
+The script is idempotent and applies exact replacements only. It exits with an error before writing
+files if the emitter output no longer matches either the known generated or patched form. Remove the
+script and these instructions after the emitter produces all four corrected type surfaces and the
+package passes MyPy without the rewriter.
+Note: Occasionally, types.py might import packages incorrectly. Verify that the imports are valid and actually reference something valid.
+
 ---
 
 ## File: `azure/search/documents/_patch.py`

sdk/search/azure-search-documents/.github/skills/azure-search-documents/scripts/Set-LiveTestEnvironment.sample.ps1

@@ -12,9 +12,19 @@ $env:SEARCH_SERVICE_ENDPOINT = "https://<search-service-name>.search.windows.net
 $env:SEARCH_SERVICE_NAME = "<search-service-name>"
 $env:SEARCH_STORAGE_CONNECTION_STRING = "<storage-connection-string>"
 $env:SEARCH_STORAGE_CONTAINER_NAME = "<storage-container-name>"
+$env:SEARCH_AZURE_OPENAI_ENDPOINT = "https://<azure-openai-resource>.openai.azure.com"
+$env:SEARCH_AZURE_OPENAI_EMBEDDING_DEPLOYMENT = "<embedding-deployment>"
+$env:SEARCH_AZURE_OPENAI_EMBEDDING_MODEL = "<embedding-model>"
 
 # Uncomment when recording live tests.
 # $env:AZURE_TEST_RUN_LIVE = "true"
 
-# Uncomment if you need to authenticate before live tests.
+# Option 1: authenticate with Azure CLI and uncomment the auth selector.
 # az login --tenant "<tenant-id>"
+# $env:AZURE_TEST_USE_CLI_AUTH = "true"
+
+# Option 2: configure a test service principal. Keep these values only in the
+# untracked Set-LiveTestEnvironment.ps1 file.
+# $env:AZURE_TENANT_ID = "<tenant-id>"
+# $env:AZURE_CLIENT_ID = "<client-id>"
+# $env:AZURE_CLIENT_SECRET = "<client-secret>"

sdk/search/azure-search-documents/.github/skills/azure-search-documents/scripts/apply_generator_workarounds.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Apply temporary azure-search-documents Python emitter workarounds. Delete when emitter fixes the issues."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[4]
+
+
+@dataclass(frozen=True)
+class Replacement:
+    path: str
+    description: str
+    generated: str
+    patched: str
+    applies_when: str | None = None
+
+
+REPLACEMENTS = (
+    Replacement(
+        "azure/search/documents/models/__init__.py",
+        "export SemanticQueryRewritesResultType",
+        """    SemanticFieldState,
+    SemanticSearchResultsType,
+""",
+        """    SemanticFieldState,
+    SemanticQueryRewritesResultType,
+    SemanticSearchResultsType,
+""",
+    ),
+    Replacement(
+        "azure/search/documents/models/__init__.py",
+        "include SemanticQueryRewritesResultType in __all__",
+        """    "SemanticFieldState",
+    "SemanticSearchResultsType",
+""",
+        """    "SemanticFieldState",
+    "SemanticQueryRewritesResultType",
+    "SemanticSearchResultsType",
+""",
+    ),
+    Replacement(
+        "azure/search/documents/types.py",
+        "use the imported SemanticQueryRewritesResultType enum",
+        '"@search.semanticQueryRewritesResultType": Union[str, "_enums.SemanticQueryRewritesResultType"],',
+        '"@search.semanticQueryRewritesResultType": Union[str, "SemanticQueryRewritesResultType"],',
+        applies_when="@search.semanticQueryRewritesResultType",
+    ),
+    Replacement(
+        "azure/search/documents/knowledgebases/types.py",
+        "remove the duplicate KnowledgeSourceKind type-only import",
+        """        KnowledgeSourceIngestionPermissionOption,
+        KnowledgeSourceKind,
+        KnowledgeSourceResultsProcessing,
+""",
+        """        KnowledgeSourceIngestionPermissionOption,
+        KnowledgeSourceResultsProcessing,
+""",
+        applies_when="KnowledgeSourceIngestionPermissionOption",
+    ),
+    Replacement(
+        "azure/search/documents/indexes/types.py",
+        "avoid overriding TypedDict field requiredness",
+        """class SearchIndexerKnowledgeStoreTableProjectionSelector(
+    SearchIndexerKnowledgeStoreProjectionSelector
+):  # pylint: disable=name-too-long
+    \"\"\"Description for what data to store in Azure Tables.
+
+    :ivar referenceKeyName: Name of reference key to different projection.
+    :vartype referenceKeyName: str
+    :ivar source: Source data to project.
+    :vartype source: str
+    :ivar sourceContext: Source context for complex projections.
+    :vartype sourceContext: str
+    :ivar inputs: Nested inputs for complex projections.
+    :vartype inputs: list[\"InputFieldMappingEntry\"]
+    :ivar generatedKeyName: Name of generated key to store projection under. Required.
+    :vartype generatedKeyName: str
+    :ivar tableName: Name of the Azure table to store projected data in. Required.
+    :vartype tableName: str
+    \"\"\"
+
+    generatedKeyName: Required[str]
+    \"\"\"Name of generated key to store projection under. Required.\"\"\"
+    tableName: Required[str]
+    \"\"\"Name of the Azure table to store projected data in. Required.\"\"\"
+""",
+        (
+            "class SearchIndexerKnowledgeStoreTableProjectionSelector(TypedDict, total=False):  "
+            "# pylint: disable=name-too-long\n"
+                """    \"\"\"Description for what data to store in Azure Tables.
+
+    :ivar referenceKeyName: Name of reference key to different projection.
+    :vartype referenceKeyName: str
+    :ivar source: Source data to project.
+    :vartype source: str
+    :ivar sourceContext: Source context for complex projections.
+    :vartype sourceContext: str
+    :ivar inputs: Nested inputs for complex projections.
+    :vartype inputs: list[\"InputFieldMappingEntry\"]
+    :ivar generatedKeyName: Name of generated key to store projection under. Required.
+    :vartype generatedKeyName: str
+    :ivar tableName: Name of the Azure table to store projected data in. Required.
+    :vartype tableName: str
+    \"\"\"
+
+    referenceKeyName: str
+    \"\"\"Name of reference key to different projection.\"\"\"
+    source: str
+    \"\"\"Source data to project.\"\"\"
+    sourceContext: str
+    \"\"\"Source context for complex projections.\"\"\"
+    inputs: list[\"InputFieldMappingEntry\"]
+    \"\"\"Nested inputs for complex projections.\"\"\"
+    generatedKeyName: Required[str]
+    \"\"\"Name of generated key to store projection under. Required.\"\"\"
+    tableName: Required[str]
+    \"\"\"Name of the Azure table to store projected data in. Required.\"\"\"
+"""
+        ),
+    ),
+    Replacement(
+        "azure/search/documents/indexes/types.py",
+        "import KnowledgeSourceIngestionParameters from the public models namespace",
+        "    from ..knowledgebases.types import KnowledgeRetrievalReasoningEffort, KnowledgeSourceIngestionParameters\n",
+        "    from ..knowledgebases.models import KnowledgeSourceIngestionParameters\n"
+        "    from ..knowledgebases.types import KnowledgeRetrievalReasoningEffort\n",
+    ),
+    Replacement(
+        "azure/search/documents/indexes/_operations/_operations.py",
+        "suppress protected access for the generated SearchIndexResponse type",
+        "                list[_models1._models.SearchIndexResponse],\n"
+        '                deserialized.get("value", []),\n'
+        "            )",
+        "                list[_models1._models.SearchIndexResponse],  # pylint: disable=protected-access\n"
+        '                deserialized.get("value", []),\n'
+        "            )",
+    ),
+    Replacement(
+        "azure/search/documents/indexes/aio/_operations/_operations.py",
+        "suppress protected access for the generated async SearchIndexResponse type",
+        "                list[_models2._models.SearchIndexResponse],\n"
+        '                deserialized.get("value", []),\n'
+        "            )",
+        "                list[_models2._models.SearchIndexResponse],  # pylint: disable=protected-access\n"
+        '                deserialized.get("value", []),\n'
+        "            )",
+    ),
+)
+
+
+def update_sources(*, check: bool) -> int:
+    sources: dict[Path, str] = {}
+    pending: list[str] = []
+
+    for replacement in REPLACEMENTS:
+        path = PACKAGE_ROOT / replacement.path
+        source = sources.setdefault(path, path.read_text(encoding="utf-8"))
+        generated_count = source.count(replacement.generated)
+        patched_count = source.count(replacement.patched)
+
+        if generated_count == 1 and patched_count == 0:
+            sources[path] = source.replace(replacement.generated, replacement.patched, 1)
+            pending.append(replacement.description)
+        elif generated_count == 0 and patched_count == 1:
+            continue
+        elif replacement.applies_when is not None and replacement.applies_when not in source:
+            continue
+        else:
+            raise RuntimeError(
+                f"Unexpected emitter output in {replacement.path} while attempting to "
+                f"{replacement.description}; expected exactly one generated or patched snippet"
+            )
+
+    if check:
+        if pending:
+            print("Generator workarounds are required:")
+            for description in pending:
+                print(f"- {description}")
+            return 1
+        print("Generator workarounds are applied.")
+        return 0
+
+    for path, source in sources.items():
+        path.write_text(source, encoding="utf-8")
+
+    if pending:
+        print("Applied generator workarounds:")
+        for description in pending:
+            print(f"- {description}")
+    else:
+        print("Generator workarounds were already applied.")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="verify that all workarounds are applied without changing files",
+    )
+    args = parser.parse_args()
+    return update_sources(check=args.check)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sdk/search/azure-search-documents/CHANGELOG.md

@@ -1,15 +1,87 @@
 # Release History
 
-## 12.1.0b2 (Unreleased)
+## 12.1.0b2 (2026-08-27)
 
 ### Features Added
 
+- Added `ApiVersion.V2026_08_01_PREVIEW` so the `2026-08-01-preview` Search API version can be
+  selected via the `api_version` keyword on the clients.
+- Added filtered and paged resource listing with `search`, `page_size`, and `search_type` parameters.
+  File listings also support `prefix`.
+- Added multipart File knowledge source operations and models:
+  - `azure.search.documents.indexes.SearchIndexClient.update_knowledge_source_file`
+  - `azure.search.documents.indexes.SearchIndexClient.upload_knowledge_source_file_multipart`
+  - `azure.search.documents.indexes.models.FileUploadMetadata`
+  - `azure.search.documents.indexes.models.UpdateKnowledgeSourceFileRequest`
+  - `azure.search.documents.indexes.models.UploadKnowledgeSourceFileMultipartRequest`
+- Added knowledge source query-hint and result-processing models:
+  - `azure.search.documents.indexes.models.KnowledgeSourceResultsProcessing`
+  - `azure.search.documents.indexes.models.SearchIndexKnowledgeSourceBoost`
+  - `azure.search.documents.indexes.models.SearchIndexKnowledgeSourceBoostKind`
+  - `azure.search.documents.indexes.models.SearchIndexKnowledgeSourceFieldValueBoost`
+  - `azure.search.documents.indexes.models.SearchIndexKnowledgeSourceFilterHint`
+  - `azure.search.documents.indexes.models.SearchIndexKnowledgeSourceMultiWordExpressionBoost`
+  - `azure.search.documents.indexes.models.SearchIndexKnowledgeSourceQueryHints`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseQueryHintProcessing`
+- Added knowledge base retrieval streaming through
+  `azure.search.documents.knowledgebases.KnowledgeBaseRetrievalClient.retrieve_stream` and its
+  asynchronous equivalent. The methods return closeable streams of typed
+  `KnowledgeBaseRetrievalEvent` instances. New stream payload models include:
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseActivityStartedEvent`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseAnswerCompletedEvent`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseResponseCompletedEvent`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseRetrievalStartedEvent`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseStreamErrorEvent`
+- Added knowledge base configuration and retrieval features:
+  - Knowledge base `tags` and persisted `retrieve_defaults`.
+  - Per-source `never_query_source`, `results_processing`, and `query_hint_overrides`.
+  - `KnowledgeRetrievalAutoReasoningEffort` for automatic reasoning-effort selection.
+  - Activity start/completion timestamps, model metadata, query-hint processing details, and
+    served-image metadata.
+  - Citation URLs on index-backed knowledge base references.
+  - Private ingestion networking through `KnowledgeSourceNetworkAccessMode`.
+- Added Work IQ configuration through `EntraAppAuthentication` and
+  `WorkIQKnowledgeSourceParameters`, plus the `query_work_iq_source_authorization` retrieval
+  parameter.
+- Added File knowledge source CORS, metadata, prefix, parsing-mode, and extraction-mode support.
+- Added GPT-5.5, GPT-5.6 Luna, GPT-5.6 Sol, and GPT-5.6 Terra model names.
+- Added `SearchServiceLimits.max_vector_index_size_per_index_in_bytes`.
+
 ### Breaking Changes
 
+> These changes do not impact the API of stable versions such as 11.6.0.
+> Only code written against a beta version such as 12.1.0b1 may be affected.
+
+- Replaced `ApiVersion.V2026_05_01_PREVIEW` with `ApiVersion.V2026_08_01_PREVIEW` and made the new
+  version the default.
+- Replaced `top`, `skip`, and `count` with `search`, `page_size`, and `search_type` on
+  `SearchIndexClient.list_indexes`, `SearchIndexClient.list_index_names`, and their asynchronous
+  equivalents. `list_index_stats_summary` uses the same new parameters.
+- Replaced `McpServerTool.inclusion_mode` and `McpServerToolInclusionMode` with
+  `McpServerTool.results_processing` and `KnowledgeSourceResultsProcessing`.
+- Replaced `model_name` with `model` on model query-planning, answer-synthesis, and web-summarization
+  activity records. The new value is a `KnowledgeBaseActivityRecordModel`.
+- Replaced `KnowledgeBaseWorkIQReference.attributions` and `WorkIQAttribution` with
+  `search_sensitivity_label_info`.
+- Renamed the Python enum members `GPT_5_MINI`, `GPT_5_NANO`, `GPT_5_4_MINI`, and `GPT_5_4_NANO`
+  to `GPT5_MINI`, `GPT5_NANO`, `GPT5_4_MINI`, and `GPT5_4_NANO`, respectively. Wire values are
+  unchanged.
+- Dropped Python 3.9 support. Python 3.10 or later is now required.
+
 ### Bugs Fixed
 
+- Normalized `SearchIndexClient.update_knowledge_source_file` and its asynchronous equivalent to
+  use the name-first signature `(name, file_id, body)`, consistent with the other File knowledge
+  source operations.
+- Published the synchronous and asynchronous knowledge base retrieval stream classes from their
+  respective public namespaces.
+
 ### Other Changes
 
+- Updated `tsp-location.yaml` to target spec commit
+  `c195a3fe73b28cd90bf8a302944b2c0ec3d80def` (`2026-08-01-preview`).
+- Added Python 3.14 support.
+
 ## 12.1.0b1 (2026-05-28)
 
 ### Features Added

sdk/search/azure-search-documents/MANIFEST.in

@@ -1,6 +1,7 @@
 include *.md
 include LICENSE
 include azure/search/documents/py.typed
+recursive-include doc *.rst
 recursive-include tests *.py
 recursive-include samples *.py *.md
 include azure/__init__.py