Skip to content

Commit acbf01f

Browse files
AmichelangeloQi-2077sarkar-rajarshi
authored
[SDK Release] (Python) CQA authoring 2025-05-15-preview (#43117)
* generated code * feat(authoring): initialize standalone azure-ai-language-questionanswering-authoring package (packaging, samples, tests, migration guide) Summary: Packaging & metadata: Added sdk_packaging.toml (python_min=3.9; deps: azure-core, isodate, conditional typing-extensions) Added setup.py aligned with sdk_packaging.toml Preserved/added pyproject.toml (generator structure) Added initial CHANGELOG.md (1.0.0b1 draft) Rewrote README.md to focus exclusively on authoring features Added migration_guide_authoring.md (split rationale & upgrade steps) Added dev_requirements.txt (devtools_testutils, pytest, pytest-asyncio, aiohttp) Samples: Added sync samples: sample_create_and_deploy_project.py, sample_export_import_project.py, sample_update_knowledge_sources.py Added async counterparts under samples/authoring/async_samples/ Added README.md (authoring-only guidance) Tests: Added trimmed conftest.py (reduced env vars + essential sanitizers) Added testcase.py (QuestionAnsweringAuthoringTestCase with playback polling_interval=0) Added helpers.py (AuthoringTestHelper + AuthoringAsyncTestHelper) Added sync tests: test_create_and_deploy_project.py, test_export_import_project.py, test_update_knowledge_sources.py Added async tests: test_create_and_deploy_project_async.py, test_export_import_project_async.py, test_update_knowledge_sources_async.py Consistency & cleanup: Client renamed to QuestionAnsweringAuthoringClient (+ aio variant) Unified project name spelling to IsaacNewton Removed runtime query samples/tests (authoring-only scope) Simplified helper logic and removed unused parameters Deferred assets.json (not required until live resource orchestration is needed) Future follow-ups (not included in this commit): TypeSpec recompile & regeneration validation Optional AAD TokenCredential test coverage Potential runtime package split / publication Live test infra (assets.json) if/when enabled BREAKING CHANGE: Users of authoring functionality must install the new package and replace AuthoringClient with QuestionAnsweringAuthoringClient (import namespace remains in the authoring subtree). * update setup file * update import path in test files * update tests, samples, readme * migrating test recordings out of the azure-sdk-for-python repository * update cspell * fix host mismatch * update readme and remove generated code * update sample readme * 1. QuestionAnsweringProjectMetadate -> QuestionAnsweringProject 2. import -> begin_import_assets 3. format -> file_format * rename begin_import_method in samples * update * fix comments, get-> list, add overload * apiview changes * fix circle import issue * fix broken link * add type ignore * analyze iuuse * update get_[operation]_status to private add dependency on azure-ai-language-questionanswering * update * update * update assest * update the dependencies * fix cspell * add azure-ai-language-questionanswering to shared_requirements.txt * move down the pylint tag * move down the pylint tag --------- Co-authored-by: Qi Yin <[email protected]> Co-authored-by: Rajarshi Sarkar <[email protected]>
1 parent 8f58e9c commit acbf01f

Some content is hidden

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

59 files changed

+14308
-2
lines changed

‎.vscode/cspell.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@
155155
"sdk/ai/azure-ai-voicelive/samples/**"
156156
],
157157
"words": [
158+
"qnas",
158159
"msedge",
159160
"spinup",
160161
"cibuildwheel",
@@ -530,7 +531,7 @@
530531
"logprobs",
531532
"pyaudio",
532533
"PyAudio",
533-
"libasound",
534+
"libasound",
534535
"ingraph"
535536
],
536537
"overrides": [

‎sdk/cognitivelanguage/azure-ai-language-questionanswering-authoring/CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Release History
2+
3+
## 1.0.0b1
4+
5+
### Features Added
6+
- Initial preview release of `azure-ai-language-questionanswering-authoring` separated from the combined `azure-ai-language-questionanswering` package.
7+
- Supports project listing, creation, update, deletion, import/export, deployments, synonym/source/QnA management operations aligned with the TypeSpec service definition (includes preview API version 2025-05-15-preview where applicable).
8+
9+
### Other Changes
10+
- Generated from TypeSpec definitions in `specification\cognitiveservices\data-plane\LanguageQuestionAnsweringAuthoring`.

‎sdk/cognitivelanguage/azure-ai-language-questionanswering-authoring/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/cognitivelanguage/azure-ai-language-questionanswering-authoring/MANIFEST.in‎

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

‎sdk/cognitivelanguage/azure-ai-language-questionanswering-authoring/README.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Azure AI Language Question Answering Authoring client library for Python
2+
3+
The `azure-ai-language-questionanswering-authoring` package provides **authoring / management capabilities** for Azure AI Language Question Answering: create and configure projects, add knowledge sources, manage QnA pairs and synonyms, and deploy versions. Runtime (query) operations live in the separate `azure-ai-language-questionanswering` package.
4+
5+
> NOTE: This is a preview (`1.0.0b1`) targeting a preview service API version (`2025-05-15-preview`). APIs, models, and LRO result payloads may change before GA.
6+
7+
[Product documentation][product_docs]
8+
9+
## Getting started
10+
11+
### Prerequisites
12+
13+
- Python 3.9+ (preview requires 3.9 or later)
14+
- An Azure subscription
15+
- An Azure AI Language resource with Question Answering enabled (custom subdomain endpoint recommended for AAD)
16+
17+
### Install the package
18+
19+
```bash
20+
pip install --pre azure-ai-language-questionanswering-authoring
21+
```
22+
23+
Optional (for Azure Active Directory auth):
24+
25+
```bash
26+
pip install azure-identity
27+
```
28+
29+
### Authenticate the client
30+
31+
You can authenticate with:
32+
33+
1. Azure Active Directory via `DefaultAzureCredential` (recommended)
34+
2. A resource key via `AzureKeyCredential` (quick start / local experimentation)
35+
36+
AAD example:
37+
```python
38+
from azure.identity import DefaultAzureCredential
39+
from azure.ai.language.questionanswering.authoring import QuestionAnsweringAuthoringClient
40+
41+
endpoint = "https://<resource-name>.cognitiveservices.azure.com"
42+
credential = DefaultAzureCredential()
43+
client = QuestionAnsweringAuthoringClient(endpoint, credential)
44+
```
45+
46+
Key credential example:
47+
```python
48+
from azure.core.credentials import AzureKeyCredential
49+
from azure.ai.language.questionanswering.authoring import QuestionAnsweringAuthoringClient
50+
51+
client = QuestionAnsweringAuthoringClient(
52+
endpoint="https://<resource-name>.cognitiveservices.azure.com",
53+
credential=AzureKeyCredential("<api-key>")
54+
)
55+
```
56+
57+
## Key concepts
58+
59+
- **Project**: A logical container for your knowledge sources, QnA pairs, synonyms, and deployments.
60+
- **Knowledge Source**: A URL/file describing content from which QnA pairs can be extracted.
61+
- **QnA Record**: A question and its answer plus metadata/alternative questions.
62+
- **Synonyms**: Word alteration groups to normalize variations in user questions.
63+
- **Deployment**: A named (e.g., `production`) deployed snapshot of your project used by runtime clients.
64+
- **Long‑running operation (LRO)**: Certain operations (update sources/QnAs, import, export, deploy) return an `LROPoller`. In the current preview these resolve to `None`—treat `.result()` strictly as a completion signal.
65+
66+
## Examples
67+
68+
Below are minimal synchronous examples. More complete samples (including async equivalents) are in the samples directory. Environment variables used by samples: `AZURE_QUESTIONANSWERING_ENDPOINT`, `AZURE_QUESTIONANSWERING_KEY`.
69+
70+
### Create a project
71+
```python
72+
metadata = {
73+
"language": "en",
74+
"description": "FAQ project",
75+
"settings": {"defaultAnswer": "no answer"},
76+
"multilingualResource": True,
77+
}
78+
client.create_project(project_name="FAQ", body=metadata)
79+
```
80+
81+
### List projects
82+
```python
83+
for proj in client.list_projects():
84+
print(proj.get("projectName"), proj.get("lastModifiedDateTime"))
85+
```
86+
87+
### Add / update a knowledge source
88+
```python
89+
from azure.ai.language.questionanswering.authoring.models import UpdateSourceRecord,UpdateQnaSourceRecord
90+
91+
poller = client.begin_update_sources(
92+
project_name="FAQ",
93+
body=[
94+
UpdateSourceRecord(
95+
op="add",
96+
value=UpdateQnaSourceRecord(
97+
display_name="ContosoFAQ",
98+
source="https://contoso.com/faq",
99+
source_uri="https://contoso.com/faq",
100+
source_kind="url",
101+
content_structure_kind="unstructured",
102+
refresh=False,
103+
),
104+
)
105+
],
106+
)
107+
poller.result()
108+
```
109+
110+
### Add a QnA pair
111+
```python
112+
from azure.ai.language.questionanswering.authoring.models import UpdateQnaRecord,QnaRecord
113+
114+
poller = client.begin_update_qnas(
115+
project_name="FAQ",
116+
body=[
117+
UpdateQnaRecord(
118+
op="add",
119+
value=QnaRecord(
120+
id=1,
121+
answer="Use the Azure SDKs.",
122+
source="manual",
123+
questions=["How do I use Azure services in .NET?"],
124+
),
125+
)
126+
],
127+
)
128+
poller.result()
129+
```
130+
131+
### Set synonyms
132+
```python
133+
from azure.ai.language.questionanswering.authoring.models import SynonymAssets,WordAlterations
134+
135+
client.update_synonyms(
136+
project_name="FAQ",
137+
body=SynonymAssets(
138+
value=[
139+
WordAlterations(alterations=["qnamaker", "qna maker"]),
140+
WordAlterations(alterations=["qna", "question and answer"]),
141+
]
142+
),
143+
)
144+
```
145+
146+
### Deploy
147+
```python
148+
client.begin_deploy_project(project_name="FAQ", deployment_name="production").result()
149+
```
150+
151+
### Export / Import
152+
```python
153+
export_poller = client.begin_export(project_name="FAQ", format="json")
154+
export_poller.result() # current preview returns None
155+
156+
from azure.ai.language.questionanswering.authoring.models import ImportJobOptions,Assets,ImportQnaRecord
157+
assets = ImportJobOptions(
158+
assets=Assets(
159+
qnas=[
160+
ImportQnaRecord(
161+
id=1,
162+
answer="Example answer",
163+
source="https://contoso.com/faq",
164+
questions=["Example question?"],
165+
)
166+
]
167+
)
168+
)
169+
client.begin_import_assets(project_name="FAQ", body=assets, format="json").result()
170+
```
171+
172+
## Troubleshooting
173+
174+
### Errors
175+
Service errors raise `HttpResponseError` (or subclasses) from `azure-core`. Check the `.status_code` / `.message` for details.
176+
177+
```python
178+
from azure.core.exceptions import HttpResponseError
179+
180+
try:
181+
client.list_projects()
182+
except HttpResponseError as e:
183+
print("Request failed:", e.message)
184+
```
185+
186+
### Logging
187+
Enable basic logging:
188+
```python
189+
import logging
190+
logging.basicConfig(level=logging.INFO)
191+
```
192+
For request/response details set environment variable `AZURE_LOG_LEVEL=info` or pass `logging_enable=True` per operation.
193+
194+
## Next steps
195+
196+
- Explore the full samples
197+
- Learn about Question Answering concepts in [product documentation][product_docs]
198+
199+
## Contributing
200+
201+
See [CONTRIBUTING.md][contributing] for instructions on building, testing, and contributing.
202+
203+
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <https://cla.microsoft.com>.
204+
205+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
206+
207+
This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact <mailto:[email protected]> with any additional questions or comments.
208+
209+
<!-- LINKS -->
210+
[product_docs]: https://learn.microsoft.com/azure/ai-services/language-service/question-answering/overview
211+
[contributing]: https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md
212+
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
213+
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/

‎sdk/cognitivelanguage/azure-ai-language-questionanswering-authoring/_metadata.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"apiVersion": "2025-05-15-preview"
3+
}

0 commit comments

Comments
 (0)