Regenerate Search SDK with retrieval activity models + filename upload helper

- Regen against spec 4bb11e927c (adds 24 KnowledgeBase*ActivityRecord/Arguments models + ImageServingStatistics; resolves audit BUG-1 and BUG-6)

- Add new required `content_disposition` header to `_upload_knowledge_source_file`

- Wrap upload in `_patch.py` (sync + async) with a `filename` shortcut that builds `Content-Disposition: attachment; filename="<filename>"`; raw `content_disposition` still accepted for advanced callers

- Restore inline `# pylint: disable=protected-access` comments dropped by codegen

- Document the `friendly-input wrapper` pattern in the package skill

- Update CHANGELOG and add unit tests for the new upload kwargs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: hizixin

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

@@ -122,7 +122,9 @@ For each new method, pick the exposure path:
 
 5. **List projection wrapper** — for `list_*`. Add a `select` parameter, a name-only projection via `cls` callback (`list_index_names`, `list_indexer_names`, `list_skillset_names`), or convert a generated projection type back to the canonical model via `_convert_index_response`.
 
-6. **Re-export via `__all__`** — any NEW symbol you add or override in `_patch.py` MUST be appended to that file's `__all__`. Otherwise `patch_sdk()` will not surface it.
+6. **Friendly-input wrapper** — when a generated parameter takes a structured string the caller would otherwise assemble by hand, add an optional higher-level kwarg that builds it from simpler inputs. Keep the raw parameter accepted too.
+
+7. **Re-export via `__all__`** — any NEW symbol you add or override in `_patch.py` MUST be appended to that file's `__all__`. Otherwise `patch_sdk()` will not surface it.
 
    ```powershell
    venv python -c "import azure.search.documents as m; print(sorted(m.__all__))"

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

@@ -16,6 +16,33 @@
   - `azure.search.documents.indexes.SearchIndexClient.list_knowledge_source_files`
   - `azure.search.documents.indexes.SearchIndexClient.upload_knowledge_source_file`
 
+- Below models are added for per-source retrieval activity tracking
+  - `azure.search.documents.knowledgebases.models.ImageServingStatistics`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseAzureBlobActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseAzureBlobActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseFabricDataAgentActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseFabricDataAgentActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseFabricOntologyActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseFabricOntologyActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseFileActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseFileActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedOneLakeActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedOneLakeActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSharePointActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSharePointActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSqlActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSqlActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseMcpServerActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseMcpServerActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseRemoteSharePointActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseRemoteSharePointActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseSearchIndexActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseSearchIndexActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseWebActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseWebActivityRecord`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseWorkIQActivityArguments`
+  - `azure.search.documents.knowledgebases.models.KnowledgeBaseWorkIQActivityRecord`
+
 - Below models are added for File, indexed SQL, and MCP server knowledge source support
   - `azure.search.documents.indexes.models.FileKnowledgeSource`
   - `azure.search.documents.indexes.models.FileKnowledgeSourceParameters`

sdk/search/azure-search-documents/apiview-properties.json

@@ -107,6 +107,7 @@
         "azure.search.documents.indexes.models.HnswParameters": "Search.HnswParameters",
         "azure.search.documents.models.HybridSearch": "Search.HybridSearch",
         "azure.search.documents.indexes.models.ImageAnalysisSkill": "Search.ImageAnalysisSkill",
+        "azure.search.documents.knowledgebases.models.ImageServingStatistics": "Search.ImageServingStatistics",
         "azure.search.documents.models.IndexAction": "Search.IndexAction",
         "azure.search.documents.models.IndexDocumentsBatch": "Search.IndexBatch",
         "azure.search.documents.indexes.models.IndexedOneLakeKnowledgeSource": "Search.IndexedOneLakeKnowledgeSource",
@@ -136,19 +137,35 @@
         "azure.search.documents.indexes.models.KnowledgeBase": "Search.KnowledgeBase",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseActivityRecord": "Search.KnowledgeBaseActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseAgenticReasoningActivityRecord": "Search.KnowledgeBaseAgenticReasoningActivityRecord",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseAzureBlobActivityArguments": "Search.KnowledgeBaseAzureBlobActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseAzureBlobActivityRecord": "Search.KnowledgeBaseAzureBlobActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseReference": "Search.KnowledgeBaseReference",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseAzureBlobReference": "Search.KnowledgeBaseAzureBlobReference",
         "azure.search.documents.indexes.models.KnowledgeBaseModel": "Search.KnowledgeBaseModel",
         "azure.search.documents.indexes.models.KnowledgeBaseAzureOpenAIModel": "Search.KnowledgeBaseAzureOpenAIModel",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseErrorAdditionalInfo": "Search.KnowledgeBaseErrorAdditionalInfo",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseErrorDetail": "Search.KnowledgeBaseErrorDetail",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseFabricDataAgentActivityArguments": "Search.KnowledgeBaseFabricDataAgentActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseFabricDataAgentActivityRecord": "Search.KnowledgeBaseFabricDataAgentActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseFabricDataAgentReference": "Search.KnowledgeBaseFabricDataAgentReference",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseFabricOntologyActivityArguments": "Search.KnowledgeBaseFabricOntologyActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseFabricOntologyActivityRecord": "Search.KnowledgeBaseFabricOntologyActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseFabricOntologyReference": "Search.KnowledgeBaseFabricOntologyReference",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseFileActivityArguments": "Search.KnowledgeBaseFileActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseFileActivityRecord": "Search.KnowledgeBaseFileActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseFileReference": "Search.KnowledgeBaseFileReference",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseImageContent": "Search.KnowledgeBaseImageContent",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedOneLakeActivityArguments": "Search.KnowledgeBaseIndexedOneLakeActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedOneLakeActivityRecord": "Search.KnowledgeBaseIndexedOneLakeActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedOneLakeReference": "Search.KnowledgeBaseIndexedOneLakeReference",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSharePointActivityArguments": "Search.KnowledgeBaseIndexedSharePointActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSharePointActivityRecord": "Search.KnowledgeBaseIndexedSharePointActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSharePointReference": "Search.KnowledgeBaseIndexedSharePointReference",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSqlActivityArguments": "Search.KnowledgeBaseIndexedSqlActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSqlActivityRecord": "Search.KnowledgeBaseIndexedSqlActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseIndexedSqlReference": "Search.KnowledgeBaseIndexedSqlReference",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseMcpServerActivityArguments": "Search.KnowledgeBaseMcpServerActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseMcpServerActivityRecord": "Search.KnowledgeBaseMcpServerActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseMcpServerReference": "Search.KnowledgeBaseMcpServerReference",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseMessage": "Search.KnowledgeBaseMessage",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseMessageContent": "Search.KnowledgeBaseMessageContent",
@@ -157,11 +174,19 @@
         "azure.search.documents.knowledgebases.models.KnowledgeBaseModelAnswerSynthesisActivityRecord": "Search.KnowledgeBaseModelAnswerSynthesisActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseModelQueryPlanningActivityRecord": "Search.KnowledgeBaseModelQueryPlanningActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseModelWebSummarizationActivityRecord": "Search.KnowledgeBaseModelWebSummarizationActivityRecord",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseRemoteSharePointActivityArguments": "Search.KnowledgeBaseRemoteSharePointActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseRemoteSharePointActivityRecord": "Search.KnowledgeBaseRemoteSharePointActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseRemoteSharePointReference": "Search.KnowledgeBaseRemoteSharePointReference",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseRetrievalRequest": "Search.KnowledgeBaseRetrievalRequest",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseRetrievalResponse": "Search.KnowledgeBaseRetrievalResponse",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseSearchIndexActivityArguments": "Search.KnowledgeBaseSearchIndexActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseSearchIndexActivityRecord": "Search.KnowledgeBaseSearchIndexActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseSearchIndexReference": "Search.KnowledgeBaseSearchIndexReference",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseWebActivityArguments": "Search.KnowledgeBaseWebActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseWebActivityRecord": "Search.KnowledgeBaseWebActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseWebReference": "Search.KnowledgeBaseWebReference",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseWorkIQActivityArguments": "Search.KnowledgeBaseWorkIQActivityArguments",
+        "azure.search.documents.knowledgebases.models.KnowledgeBaseWorkIQActivityRecord": "Search.KnowledgeBaseWorkIQActivityRecord",
         "azure.search.documents.knowledgebases.models.KnowledgeBaseWorkIQReference": "Search.KnowledgeBaseWorkIQReference",
         "azure.search.documents.knowledgebases.models.KnowledgeRetrievalIntent": "Search.KnowledgeRetrievalIntent",
         "azure.search.documents.knowledgebases.models.KnowledgeRetrievalReasoningEffort": "Search.KnowledgeRetrievalReasoningEffort",

sdk/search/azure-search-documents/azure/search/documents/indexes/_operations/_operations.py

@@ -885,7 +885,7 @@ def build_search_index_get_knowledge_source_status_request(  # pylint: disable=n
 
 
 def build_search_index_upload_knowledge_source_file_request(  # pylint: disable=name-too-long
-    name: str, **kwargs: Any
+    name: str, *, content_disposition: str, **kwargs: Any
 ) -> HttpRequest:
     _headers = case_insensitive_dict(kwargs.pop("headers", {}) or {})
     _params = case_insensitive_dict(kwargs.pop("params", {}) or {})
@@ -907,6 +907,7 @@ def build_search_index_upload_knowledge_source_file_request(  # pylint: disable=
 
     # Construct headers
     _headers["content-type"] = _SERIALIZER.header("content_type", content_type, "str")
+    _headers["Content-Disposition"] = _SERIALIZER.header("content_disposition", content_disposition, "str")
     _headers["Accept"] = _SERIALIZER.header("accept", accept, "str")
 
     return HttpRequest(method="POST", url=_url, params=_params, headers=_headers, **kwargs)
@@ -4417,16 +4418,32 @@ def get_knowledge_source_status(self, name: str, **kwargs: Any) -> _knowledgebas
     @distributed_trace
     @api_version_validation(
         method_added_on="2026-05-01-preview",
-        params_added_on={"2026-05-01-preview": ["api_version", "content_type", "client_request_id", "name", "accept"]},
+        params_added_on={
+            "2026-05-01-preview": [
+                "api_version",
+                "content_type",
+                "content_disposition",
+                "client_request_id",
+                "name",
+                "accept",
+            ]
+        },
         api_versions_list=["2026-05-01-preview"],
     )
-    def _upload_knowledge_source_file(self, name: str, file: bytes, **kwargs: Any) -> _models1.KnowledgeSourceFile:
+    def _upload_knowledge_source_file(
+        self, name: str, file: bytes, *, content_disposition: str, **kwargs: Any
+    ) -> _models1.KnowledgeSourceFile:
         """Uploads a file to a File knowledge source for processing and indexing.
 
         :param name: The name of the knowledge source. Required.
         :type name: str
         :param file: The file content to upload. Required.
         :type file: bytes
+        :keyword content_disposition: The Content-Disposition header specifying the filename of the
+         uploaded file.
+         Must follow the format: ``attachment; filename="<filename>"``.
+         For example: ``attachment; filename="installation-guide.pdf"``. Required.
+        :paramtype content_disposition: str
         :return: KnowledgeSourceFile. The KnowledgeSourceFile is compatible with MutableMapping
         :rtype: ~azure.search.documents.indexes.models.KnowledgeSourceFile
         :raises ~azure.core.exceptions.HttpResponseError:
@@ -4449,6 +4466,7 @@ def _upload_knowledge_source_file(self, name: str, file: bytes, **kwargs: Any) -
 
         _request = build_search_index_upload_knowledge_source_file_request(
             name=name,
+            content_disposition=content_disposition,
             content_type=content_type,
             api_version=self._config.api_version,
             content=_content,

sdk/search/azure-search-documents/azure/search/documents/indexes/_operations/_patch.py

@@ -375,6 +375,9 @@ def upload_knowledge_source_file(
         self,
         name: str,
         file: Union[bytes, IO[bytes]],
+        *,
+        filename: Optional[str] = None,
+        content_disposition: Optional[str] = None,
         **kwargs: Any,
     ) -> _models.KnowledgeSourceFile:
         """Uploads a file to a File knowledge source for processing and indexing.
@@ -383,13 +386,31 @@ def upload_knowledge_source_file(
         :type name: str
         :param file: The file content to upload. Required.
         :type file: bytes or IO[bytes]
+        :keyword filename: The name to associate with the uploaded file. When provided, the
+         ``Content-Disposition`` header is built as ``attachment; filename="<filename>"``. Either
+         ``filename`` or ``content_disposition`` must be provided.
+        :paramtype filename: str
+        :keyword content_disposition: The raw ``Content-Disposition`` header value. Use this to
+         override the default ``attachment; filename="<filename>"`` format produced from
+         ``filename``. Either ``filename`` or ``content_disposition`` must be provided.
+        :paramtype content_disposition: str
         :return: KnowledgeSourceFile
         :rtype: ~azure.search.documents.indexes.models.KnowledgeSourceFile
+        :raises ValueError: If neither ``filename`` nor ``content_disposition`` is provided.
         :raises ~azure.core.exceptions.HttpResponseError:
         """
+        if content_disposition is None:
+            if filename is None:
+                raise ValueError("Either 'filename' or 'content_disposition' must be provided.")
+            content_disposition = f'attachment; filename="{filename}"'
         return cast(
             _models.KnowledgeSourceFile,
-            self._upload_knowledge_source_file(name=name, file=cast(bytes, file), **kwargs),
+            self._upload_knowledge_source_file(
+                name=name,
+                file=cast(bytes, file),
+                content_disposition=content_disposition,
+                **kwargs,
+            ),
         )
 
     @distributed_trace

sdk/search/azure-search-documents/azure/search/documents/indexes/aio/_operations/_operations.py

@@ -2876,18 +2876,32 @@ async def get_knowledge_source_status(
     @distributed_trace_async
     @api_version_validation(
         method_added_on="2026-05-01-preview",
-        params_added_on={"2026-05-01-preview": ["api_version", "content_type", "client_request_id", "name", "accept"]},
+        params_added_on={
+            "2026-05-01-preview": [
+                "api_version",
+                "content_type",
+                "content_disposition",
+                "client_request_id",
+                "name",
+                "accept",
+            ]
+        },
         api_versions_list=["2026-05-01-preview"],
     )
     async def _upload_knowledge_source_file(
-        self, name: str, file: bytes, **kwargs: Any
+        self, name: str, file: bytes, *, content_disposition: str, **kwargs: Any
     ) -> _models2.KnowledgeSourceFile:
         """Uploads a file to a File knowledge source for processing and indexing.
 
         :param name: The name of the knowledge source. Required.
         :type name: str
         :param file: The file content to upload. Required.
         :type file: bytes
+        :keyword content_disposition: The Content-Disposition header specifying the filename of the
+         uploaded file.
+         Must follow the format: ``attachment; filename="<filename>"``.
+         For example: ``attachment; filename="installation-guide.pdf"``. Required.
+        :paramtype content_disposition: str
         :return: KnowledgeSourceFile. The KnowledgeSourceFile is compatible with MutableMapping
         :rtype: ~azure.search.documents.indexes.models.KnowledgeSourceFile
         :raises ~azure.core.exceptions.HttpResponseError:
@@ -2910,6 +2924,7 @@ async def _upload_knowledge_source_file(
 
         _request = build_search_index_upload_knowledge_source_file_request(
             name=name,
+            content_disposition=content_disposition,
             content_type=content_type,
             api_version=self._config.api_version,
             content=_content,