Skip to content

Commit b4b8159

Browse files
ahall-msftdanieljurek
ahall-msft
and
danieljurek
authored
[Discovery] azure-ai-discovery 1.0.0b1 preview release for API version 2026-02-01-preview (#46940)
* [Discovery] Initial release of azure-ai-discovery 1.0.0b1 Introduces the Azure AI Discovery client library for Python. Provides two clients under the `azure.ai.discovery` namespace: - `WorkspaceClient` for managing investigations, conversations, tasks, and tools within a Discovery workspace. - `BookshelfClient` for managing knowledge bases and knowledge base versions. Generated from TypeSpec at: - specification/discovery/Discovery.Workspace - specification/discovery/Discovery.Bookshelf in Azure/azure-rest-api-specs at commit df74858bfda6128d16c98265db2a6f42e89b20ff. Spec PR: Azure/azure-rest-api-specs#39746 Release plan: 2032 (https://dev.azure.com/azure-sdk/internal/_workitems/edit/29679) * [Discovery] Reduce cspell ignoreWords to 'milli' and ignore generated samples/tests * [Discovery] Align test constants with sanitized recording values * [Discovery] Add test-only abbreviations (wkspc, invst, delv, sdktestdelv) to cspell ignoreWords * [Discovery] Fix broken product_docs link in README * [Discovery] Fix README verifier failures: align section headers and remove generated stub READMEs * [Discovery] Expose explicit transport kwarg on all clients (APIView MustFix) Adds explicit `transport: Optional[HttpTransport] = None` keyword-only parameter to WorkspaceClient and BookshelfClient (sync + async) via _patch.py overrides, per the Azure SDK Python design guideline: https://azure.github.io/azure-sdk/python_design.html#python-client-constructor-transport-argument Also adds the azure.ai.discovery.aio facade module so async clients are reachable at a documented import path (`from azure.ai.discovery.aio import WorkspaceClient, BookshelfClient`), making the async transport fix visible to consumers. Includes 6 new unit tests in tests/test_unit_client.py verifying: - transport is exposed as an explicit kw-only parameter (all 4 clients) - sync clients accept HttpTransport instances - async clients accept AsyncHttpTransport instances Addresses APIView MustFix comment from azure-sdk bot on PR #46940. * [Discovery] Fix CI Analyze regressions on PR #46940 Pylint C4748 (api_version keyword) — primary fix: The transport-kwarg patch in bb0f633 dropped api_version from the patched client constructors. Add explicit kw-only api_version param on all 4 patched clients (sync + async WorkspaceClient / BookshelfClient) and document it with ':keyword api_version:' in the __init__ docstring so azure-pylint-guidelines-checker C4748 is satisfied. APIView ivar discovery (apistub): Restored the class-level ':ivar' / ':vartype' entries for every operation group (investigations, conversations, tools, tasks, knowledge_bases, knowledge_base_versions) so apistub once again surfaces the operations on the patched WorkspaceClient and BookshelfClient. Without these, APIView showed only __init__, close, and send_request on each client. Sphinx: Collapsed multi-line ':vartype:' continuations to single lines to avoid 'Unexpected indentation' from docutils on the patched class docstrings. azpysdk black formatting: Apply the formatting that the CI Run Black gate (azpysdk black in --check --diff mode) requires across the test and sample modules that drifted: test_unit_client, test_conversations, test_investigations, test_knowledge_bases, test_knowledge_base_versions, test_tasks, test_tools, sample_knowledge_bases. Unit tests: Extend tests/test_unit_client.py with a parametrized TestExplicitApiVersionKwarg class covering all 4 client classes (sync + async, Workspace + Bookshelf) and verify api_version is exposed as an explicit keyword-only parameter with default None. Local verification on this branch (HEAD bb0f633) with the exact CI toolchain: azpysdk pylint . exit 0 azpysdk mypy . exit 0 azpysdk pyright . exit 0 azpysdk sphinx . exit 0 azpysdk black . exit 0 (no further changes) azpysdk bandit . exit 0 azpysdk verify_keywords exit 0 azpysdk verifysdist . exit 0 azpysdk verifywhl . exit 0 azpysdk breaking . exit 0 azpysdk import_all . exit 0 pytest tests/test_unit_client.py 16/16 pass Refs: CI build 6359032 (Build Analyze failure) * Add newline at end of ci.yml Co-authored-by: Daniel Jurek <djurek@microsoft.com> --------- Co-authored-by: Daniel Jurek <djurek@microsoft.com>
1 parent a568d15 commit b4b8159

202 files changed

Lines changed: 32408 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎sdk/discovery/azure-ai-discovery/CHANGELOG.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Release History
2+
3+
## 1.0.0b1 (2026-05-16)
4+
5+
Initial beta release of the Azure AI Discovery client library for Python.
6+
7+
### Features Added
8+
9+
- Added `WorkspaceClient` for managing Discovery workspace resources, with operation groups for:
10+
- `investigations` — create, list, get, and delete investigations, and start/stop/get/update the per-investigation Discovery Engine.
11+
- `conversations` — create, list, get, update, and delete conversations that interact with the Discovery Engine.
12+
- `tasks` — create, list (with `$filter` support), get, update, comment on, start, and delete tasks; record execution history.
13+
- `tools` — run tools on supercomputer node pools, monitor run status with log retrieval, cancel runs, and query compute usage.
14+
- Added `BookshelfClient` for managing knowledge bases, with operation groups for:
15+
- `knowledge_bases` — list available knowledge bases.
16+
- `knowledge_base_versions` — create or update, get, list, delete, and retrieve the latest version of a knowledge base; start, cancel, and monitor indexing.
17+
- Added shared model types under `azure.ai.discovery.models` covering investigations, conversations, tasks, tools, knowledge bases, and the Discovery Engine.

‎sdk/discovery/azure-ai-discovery/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Copyright (c) Microsoft Corporation.
2+
3+
MIT License
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎sdk/discovery/azure-ai-discovery/MANIFEST.in‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
include *.md
2+
include LICENSE
3+
include azure/ai/discovery/py.typed
4+
recursive-include tests *.py
5+
recursive-include samples *.py *.md
6+
include azure/__init__.py
7+
include azure/ai/__init__.py

‎sdk/discovery/azure-ai-discovery/README.md‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
# Azure AI Discovery client library for Python
2+
3+
The Azure AI Discovery client library for Python provides two clients for interacting with Azure AI Discovery services:
4+
5+
- **WorkspaceClient** — manage investigations, conversations, tasks, and tools in a Discovery workspace.
6+
- **BookshelfClient** — manage knowledge bases and knowledge base versions.
7+
8+
[Source code][source_code] | [Package (PyPI)][pypi] | [Samples][samples]
9+
10+
## Getting started
11+
12+
### Install the Package
13+
14+
```bash
15+
python -m pip install azure-ai-discovery
16+
```
17+
18+
### Prerequisites
19+
20+
- Python 3.9 or later is required to use this package.
21+
- You need an [Azure subscription][azure_sub] to use this package.
22+
- An existing Azure AI Discovery workspace or bookshelf instance.
23+
24+
### Authenticate the Client
25+
26+
Both clients use Azure Active Directory (AAD) token authentication. Use the [azure-identity][azure_identity] library to obtain credentials:
27+
28+
```bash
29+
pip install azure-identity
30+
```
31+
32+
```python
33+
from azure.ai.discovery import WorkspaceClient, BookshelfClient
34+
from azure.identity import DefaultAzureCredential
35+
36+
workspace_client = WorkspaceClient(
37+
endpoint="https://<workspaceName>.workspace.discovery.azure.com",
38+
credential=DefaultAzureCredential(),
39+
)
40+
41+
bookshelf_client = BookshelfClient(
42+
endpoint="https://<bookshelfName>.bookshelf.discovery.azure.com",
43+
credential=DefaultAzureCredential(),
44+
)
45+
```
46+
47+
## Key concepts
48+
49+
### WorkspaceClient
50+
51+
The `WorkspaceClient` provides access to Discovery workspace operations, organized into four operation groups:
52+
53+
- **Investigations** — create and manage research investigations within a project. Each investigation can have a Discovery Engine that autonomously explores data and generates insights.
54+
- **Conversations** — interact with the Discovery Engine through conversational sessions tied to an investigation.
55+
- **Tasks** — create, assign, and track units of work within an investigation, such as research steps or follow-up actions.
56+
- **Tools** — run compute jobs on supercomputer node pools and monitor their status and resource usage.
57+
58+
### BookshelfClient
59+
60+
The `BookshelfClient` provides access to knowledge base management:
61+
62+
- **Knowledge Bases** — list available knowledge bases.
63+
- **Knowledge Base Versions** — create, update, index, and manage versions of knowledge bases backed by storage assets.
64+
65+
## Examples
66+
67+
The following sections provide code snippets covering common scenarios. For complete runnable samples, see the [Samples][samples] directory.
68+
69+
### Create and Manage an Investigation
70+
71+
```python
72+
from azure.ai.discovery import WorkspaceClient
73+
from azure.ai.discovery.models import Investigation
74+
from azure.identity import DefaultAzureCredential
75+
76+
client = WorkspaceClient(
77+
endpoint="https://<workspaceName>.workspace.discovery.azure.com",
78+
credential=DefaultAzureCredential(),
79+
)
80+
81+
# Create an investigation
82+
investigation = client.investigations.create_or_replace(
83+
project_name="my-project",
84+
investigation_name="sample-investigation",
85+
resource=Investigation(
86+
description="Investigating anomalies in dataset X",
87+
display_name="Sample Investigation",
88+
),
89+
)
90+
print(f"Created investigation: {investigation.name}")
91+
92+
# Start the Discovery Engine
93+
engine = client.investigations.start_discovery_engine(
94+
project_name="my-project",
95+
investigation_name="sample-investigation",
96+
)
97+
print(f"Discovery Engine status: {engine.discovery_engine_status}")
98+
```
99+
100+
### Create and Manage Tasks
101+
102+
```python
103+
from azure.ai.discovery import WorkspaceClient
104+
from azure.ai.discovery.models import Task, TaskAssignee, TaskComment
105+
from azure.identity import DefaultAzureCredential
106+
107+
client = WorkspaceClient(
108+
endpoint="https://<workspaceName>.workspace.discovery.azure.com",
109+
credential=DefaultAzureCredential(),
110+
)
111+
112+
# Create a task
113+
task = client.tasks.create(
114+
project_name="my-project",
115+
investigation_name="sample-investigation",
116+
body=Task(
117+
title="Analyze compound interactions",
118+
priority="High",
119+
description="Review the interaction data for compounds A and B",
120+
assigned_to=TaskAssignee(id="researcher-agent", type="Application"),
121+
investigation_id="/projects/my-project/investigations/sample-investigation",
122+
),
123+
)
124+
print(f"Created task: {task.title} ({task.status})")
125+
126+
# Add a comment
127+
client.tasks.add_comment(
128+
project_name="my-project",
129+
investigation_name="sample-investigation",
130+
task_name=task.name,
131+
body=TaskComment(
132+
created_by="sample-user",
133+
created_by_type="User",
134+
text="Initial analysis shows promising results.",
135+
),
136+
)
137+
```
138+
139+
### Run a Tool on Compute
140+
141+
```python
142+
from azure.ai.discovery import WorkspaceClient
143+
from azure.identity import DefaultAzureCredential
144+
145+
client = WorkspaceClient(
146+
endpoint="https://<workspaceName>.workspace.discovery.azure.com",
147+
credential=DefaultAzureCredential(),
148+
)
149+
150+
poller = client.tools.begin_run(
151+
project_name="my-project",
152+
tool_id="/subscriptions/.../tools/my-tool",
153+
node_pool_ids=["/subscriptions/.../nodePools/my-pool"],
154+
command='echo "Hello from Discovery"',
155+
)
156+
result = poller.result()
157+
print(f"Run completed: {result.status}")
158+
```
159+
160+
### Manage Knowledge Bases
161+
162+
```python
163+
from azure.ai.discovery import BookshelfClient
164+
from azure.ai.discovery.models import KnowledgeBaseVersion, StorageAssetReference
165+
from azure.identity import DefaultAzureCredential
166+
167+
client = BookshelfClient(
168+
endpoint="https://<bookshelfName>.bookshelf.discovery.azure.com",
169+
credential=DefaultAzureCredential(),
170+
)
171+
172+
# List knowledge bases
173+
for kb in client.knowledge_bases.list():
174+
print(f"Knowledge base: {kb.name}")
175+
176+
# Create a knowledge base version
177+
version = client.knowledge_base_versions.create_or_update(
178+
knowledge_base_name="my-kb",
179+
version_name="v1",
180+
resource=KnowledgeBaseVersion(
181+
description="Research data for compound analysis",
182+
copilot_instruction="Use this to query information about compound interactions.",
183+
storage_asset_references=[
184+
StorageAssetReference(
185+
id="/subscriptions/.../storageAssets/my-asset",
186+
user_assigned_identity="/subscriptions/.../userAssignedIdentities/my-id",
187+
),
188+
],
189+
),
190+
)
191+
print(f"Created version: {version.name}")
192+
```
193+
194+
## Troubleshooting
195+
196+
### Logging
197+
198+
This library uses the standard [logging][python_logging] library for logging. HTTP session information (URLs, headers, etc.) is logged at the `DEBUG` level.
199+
200+
Detailed `DEBUG` level logging, including request/response bodies and unredacted headers, can be enabled on a client with the `logging_enable` argument:
201+
202+
```python
203+
client = WorkspaceClient(
204+
endpoint="https://<workspaceName>.workspace.discovery.azure.com",
205+
credential=DefaultAzureCredential(),
206+
logging_enable=True,
207+
)
208+
```
209+
210+
Or on a single operation:
211+
212+
```python
213+
investigation = client.investigations.get(
214+
project_name="my-project",
215+
investigation_name="my-investigation",
216+
logging_enable=True,
217+
)
218+
```
219+
220+
### General
221+
222+
Azure AI Discovery clients raise exceptions defined in [azure-core][azure_core_exceptions]. For example, if you try to get an investigation that does not exist, `ResourceNotFoundError` is raised:
223+
224+
```python
225+
from azure.core.exceptions import ResourceNotFoundError
226+
227+
try:
228+
client.investigations.get(
229+
project_name="my-project",
230+
investigation_name="nonexistent",
231+
)
232+
except ResourceNotFoundError as e:
233+
print(f"Investigation not found: {e.message}")
234+
```
235+
236+
## Next steps
237+
238+
- [Samples][samples] — runnable code examples for common scenarios.
239+
- [Azure AI Discovery documentation][product_docs]
240+
241+
## Contributing
242+
243+
This project welcomes contributions and suggestions. Most contributions require
244+
you to agree to a Contributor License Agreement (CLA) declaring that you have
245+
the right to, and actually do, grant us the rights to use your contribution.
246+
For details, visit https://cla.microsoft.com.
247+
248+
When you submit a pull request, a CLA-bot will automatically determine whether
249+
you need to provide a CLA and decorate the PR appropriately (e.g., label,
250+
comment). Simply follow the instructions provided by the bot. You will only
251+
need to do this once across all repos using our CLA.
252+
253+
This project has adopted the
254+
[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
255+
For more information, see the
256+
[Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
257+
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com)
258+
with any additional questions or comments.
259+
260+
<!-- LINKS -->
261+
[azure_sub]: https://azure.microsoft.com/free/
262+
[azure_identity]: https://learn.microsoft.com/python/api/overview/azure/identity-readme
263+
[azure_core_exceptions]: https://learn.microsoft.com/python/api/azure-core/azure.core.exceptions
264+
[python_logging]: https://docs.python.org/3/library/logging.html
265+
[source_code]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/discovery/azure-ai-discovery
266+
[pypi]: https://pypi.org/project/azure-ai-discovery/
267+
[samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/discovery/azure-ai-discovery/samples
268+
[product_docs]: https://learn.microsoft.com/azure/microsoft-discovery/

‎sdk/discovery/azure-ai-discovery/azure/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
__path__ = __import__("pkgutil").extend_path(__path__, __name__) # type: ignore

‎sdk/discovery/azure-ai-discovery/azure/ai/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
__path__ = __import__("pkgutil").extend_path(__path__, __name__) # type: ignore

‎sdk/discovery/azure-ai-discovery/azure/ai/discovery/__init__.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# coding=utf-8
2+
# --------------------------------------------------------------------------
3+
# Copyright (c) Microsoft Corporation. All rights reserved.
4+
# Licensed under the MIT License. See License.txt in the project root for license information.
5+
# --------------------------------------------------------------------------
6+
7+
"""Azure AI Discovery client library for Python.
8+
9+
This package exposes both the WorkspaceClient and BookshelfClient from a single
10+
unified ``azure-ai-discovery`` package.
11+
"""
12+
13+
from ._workspace import WorkspaceClient # type: ignore
14+
from ._bookshelf import BookshelfClient # type: ignore
15+
from ._version import VERSION
16+
17+
__version__ = VERSION
18+
19+
__all__ = [
20+
"BookshelfClient",
21+
"WorkspaceClient",
22+
]

‎sdk/discovery/azure-ai-discovery/azure/ai/discovery/_bookshelf/CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Release History
2+
3+
## 1.0.0b1 (1970-01-01)
4+
5+
### Other Changes
6+
7+
- Initial version

‎sdk/discovery/azure-ai-discovery/azure/ai/discovery/_bookshelf/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Copyright (c) Microsoft Corporation.
2+
3+
MIT License
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎sdk/discovery/azure-ai-discovery/azure/ai/discovery/_bookshelf/MANIFEST.in‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
include *.md
2+
include LICENSE
3+
include azure/ai/discovery/py.typed
4+
recursive-include tests *.py
5+
recursive-include samples *.py *.md
6+
include azure/__init__.py
7+
include azure/ai/__init__.py

0 commit comments

Comments
 (0)