[DocumentIntelligence] Documentations + Samples updates (#37854)

Azure · Dec 7, 2023 · 8ff149d · 8ff149d
1 parent 1691f99
commit 8ff149d
Show file tree

Hide file tree

Showing 23 changed files with 1,723 additions and 9 deletions.
diff --git a/sdk/documentintelligence/azure-ai-documentintelligence/CHANGELOG.md b/sdk/documentintelligence/azure-ai-documentintelligence/CHANGELOG.md
@@ -12,16 +12,134 @@
 
 ## 1.0.0-beta.1 (2023-11-16)
 
-Version 1.0.0-beta.1 is a preview of our efforts in creating an Azure AI Document Intelligence client library that is developer-friendly
-and idiomatic to the Java ecosystem. The principles that guide
-our efforts can be found in the [Azure SDK Design Guidelines for Java](https://azure.github.io/azure-sdk/java_introduction.html).
+_**Note: Form Recognizer has been rebranded to Document Intelligence**_
 
+This marks the first preview of `azure-ai-documentintelligence` client library for the `Azure AI Document
+Intelligence` service (formerly known as Form Recognizer), targeting service API version `"2023-10-31-preview"`.
+
+It is developer-friendly and idiomatic to the Java ecosystem. The principles that guide our efforts can be found in the
+[Azure SDK Design Guidelines for Java](https://azure.github.io/azure-sdk/java_introduction.html).
 For more information about this, and preview releases of other Azure SDK libraries, please visit
 https://azure.github.io/azure-sdk/releases/latest/java.html.
 
-- It uses the Document Intelligence service `2023-10-31-preview` API.
-- Two client design:
-    - `DocumentIntelligenceClient` to analyze fields/values on custom documents, receipts, and document layout
-    - `DocumentIntelligenceAdministrationClient` to build custom models, manage the custom models on your account and build classifiers
-- Authentication with API key supported using `AzureKeyCredential("<api_key>")` from `com.azure.core.credential`
-- Reactive streams support using [Project Reactor](https://projectreactor.io/).
+### Features Added
+
+- [azure-ai-documentintelligence](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/documentintelligence/azure-ai-documentintelligence) 
+  is the new package, replacing [azure-ai-formrecognizer](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/formrecognizer/azure-ai-formrecognizer)
+  package. The new package is not compatible with the previous `azure-ai-formrecognizer` package without necessary 
+  changes to your code.
+- The new `"2023-10-31-preview"` service version comes with some new features
+  and a few breaking changes
+  when compared to the API versions supported by the `azure-ai-formrecognizer` library.
+  - **Markdown content format**
+
+    Supports output with Markdown content format along with the default plain _text_. For now, this is only supported for 
+    "prebuilt-layout". Markdown content format is deemed a more friendly format for LLM consumption in a chat or 
+    automation use scenario. Service follows the GFM spec ([GitHub Flavored Markdown](https://github.github.com/gfm/))
+    for the Markdown format. Also introduces a new _contentFormat_ property with value "text" or "markdown" to indicate 
+    the result content format.
+
+    ```java
+    File document = new File("{your-file-to-analyze}");
+    SyncPoller<AnalyzeResultOperation, AnalyzeResultOperation> analyzeLayoutResultPoller =
+            client.beginAnalyzeDocument("prebuilt-layout", null,
+                    null,
+                    null,
+                    null,
+                    null,
+                    ContentFormat.MARKDOWN,
+                    new AnalyzeDocumentRequest().setBase64Source(Files.readAllBytes(document.toPath())));
+    ```
+    For the complete sample, see [Sample: Markdown](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeLayoutMarkdownOutput.java).
+
+  - **Query Fields**
+
+    When this feature flag is specified, the service will further extract the values of the fields specified via the 
+    `queryFields` query parameter to supplement any existing fields defined by the model as fallback.
+
+    ```java
+    File document = new File("{your-file-to-analyze}");
+    SyncPoller<AnalyzeResultOperation, AnalyzeResultOperation> analyzeLayoutResultPoller =
+            client.beginAnalyzeDocument("prebuilt-layout", null,
+                    null,
+                    null,
+                    Arrays.asList(DocumentAnalysisFeature.QUERY_FIELDS),
+                    Arrays.asList("Address", "InvoiceNumber"),
+                    null,
+                    new AnalyzeDocumentRequest().setBase64Source(Files.readAllBytes(document.toPath())));
+    ```
+    For the complete sample, see [Sample: Query Fields](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnQueryFields.java).
+
+  - **Split Options**
+
+    In the previous API versions supported by the older `azure-ai-formrecognizer` library, document splitting and 
+    classification operation (`"/documentClassifiers/{classifierId}:analyze"`) always tried to split the input file 
+    into multiple documents.
+
+    To enable a wider set of scenarios, service introduces a "split" query parameter with the new "2023-10-31-preview" 
+    service version. The following values are supported:
+
+    - `split: "auto"`
+
+      Let service determine where to split.
+
+    - `split: "none"`
+
+      The entire file is treated as a single document. No splitting is performed.
+
+    - `split: "perPage"`
+
+      Each page is treated as a separate document. Each empty page is kept as its own document.
+
+### Breaking Changes
+
+- The SDKs targeting service API version `2023-10-31-preview` have renamed the clients to
+    - `DocumentIntelligenceAdministrationClient`/`DocumentIntelligenceAdministrationAsyncClient`
+    - `DocumentIntelligenceClient`/`DocumentIntelligenceAsyncClient`
+  which is different from older `azure-ai-formrecognizer` SDKs which targeting service API version `2023-07-31` and `2022-08-31`.
+    - `DocumentAnalysisClient`/`DocumentAnalysisAsyncClient`
+    - `DocumentModelAdministrationClient`/`DocumentModelAdministrationAsyncClient`
+
+- **prebuilt-receipt** - Currency related fields have been updated. Currency symbol ("$") and code ("USD") are returned along with the amount as shown below.
+
+  ```json
+  {
+    "content": "$123.45",
+    "confidence": 0.995,
+    "type": "currency",
+    "valueCurrency": {
+      "amount": 123.45,
+      "currencySymbol": "$",
+      "currencyCode": "USD"
+    }
+  }
+  ...
+  ```
+- API shapes have been designed from scratch to support new SDK client for the Document Intelligence service.
+  Please refer to the [README](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/README.md)
+  and [Samples](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/README.md) 
+  for more understanding.
+
+### Other Changes
+
+#### Retirements/Deprecations
+
+- `"prebuilt-businessCard"` model is retired.
+- `"prebuilt-document"` model is retired, this model is essentially `"prebuilt-layout"` with `DocumentAnalysisFeature.FORMULAS` specified.
+  _(This is only supported as an optional feature for "prebuilt-layout" and "prebuilt-invoice".)_.
+
+  ```java
+  File document = new File("{your-file-to-analyze}");
+  SyncPoller<AnalyzeResultOperation, AnalyzeResultOperation> analyzeLayoutResultPoller =
+          client.beginAnalyzeDocument("prebuilt-layout", null,
+                  null,
+                  null,
+                  Arrays.asList(DocumentAnalysisFeature.FORMULAS),
+                  null,
+                  null,
+                  new AnalyzeDocumentRequest().setBase64Source(Files.readAllBytes(document.toPath())));
+    ```
+
+  For the complete sample, see [Sample: KeyValuePair](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnKeyValuePair.java).
+
+- If you wish to still use these models, please rely on the older `azure-ai-formrecognizer` library through the older service API versions.
diff --git a/sdk/documentintelligence/azure-ai-documentintelligence/README.md b/sdk/documentintelligence/azure-ai-documentintelligence/README.md
@@ -32,6 +32,23 @@ It includes the following main features:
 ```
 [//]: # ({x-version-update-end})
 
+> Note: This version of the client library defaults to the `"2023-10-31-preview"` version of the service.
+
+This table shows the relationship between SDK versions and supported API versions of the service:
+
+| SDK version  |Supported API version of service
+|--------------|-
+| 1.0.0-beta.1 | 2023-10-31-preview
+
+> Note: Please rely on the older `azure-ai-formrecognizer` library through the older service API versions for retired
+> models, such as `"prebuilt-businessCard"` and `"prebuilt-document"`. For more information, see [Changelog][changelog].
+> The below table describes the relationship of each client and its supported API version(s):
+
+| API version        |Supported clients
+|--------------------|-
+| 2023-10-31-preview | DocumentIntelligenceClient and DocumentIntelligenceAsyncClient
+| 2023-07-31         | DocumentAnalysisClient and DocumentModelAdministrationClient in `azure-ai-formrecognizer` SDK
+
 ### Authentication
 
 In order to interact with the Azure Document Intelligence Service you'll need to create an instance of client class,

diff --git a/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/README.md b/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/README.md
@@ -27,8 +27,16 @@ All of these samples need the endpoint to your Document Intelligence resource ([
 
 | **File Name**                                                                                                                                    | **Description**                                                                                                                  |
 |--------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
+| [AnalyzeAddOnBarcodes][analyze_addon_barcodes] and [AnalyzeAddOnBarcodesAsync][analyze_addon_barcodes_async]                                     | Analyze add-on barcode layout                                                                                                    |
+| [AnalyzeAddOnFonts][analyze_addon_fonts] and [AnalyzeAddOnFontsAsync][analyze_addon_fonts_async]                                                 | Analyze add-on fonts layout                                                                                                      |
+| [AnalyzeAddOnFormulas][analyze_addon_formulas] and [AnalyzeAddOnFormulasAsync][analyze_addon_formulas_async]                                     | Analyze add-on formulas layout                                                                                                   |
+| [AnalyzeAddOnHighRes][analyze_addon_high_res] and [AnalyzeAddOnHighResAsync][analyze_addon_high_res_async]                                       | Analyze add-on OCR high resolution layout                                                                                        |
+| [AnalyzeAddOnKeyValuePairs][analyze_addon_kv] and [AnalyzeAddOnKeyValuePairsAsync][analyze_addon_kv_async]                                       | Analyze add-on key value pairs layout                                                                                            |
+| [AnalyzeAddOnLanguages][analyze_addon_languages] and [AnalyzeAddOnLanguagesAsync][analyze_addon_languages_async]                                 | Analyze add-on languages layout                                                                                                  |
+| [AnalyzeAddOnQueryFields][analyze_addon_query_fields] and [AnalyzeAddOnQueryFieldsAsync][analyze_addon_query_fields_async]                       | Analyze add-on query fields layout                                                                                               |
 | [AnalyzeLayout][analyze_layout] and [AnalyzeLayoutAsync][analyze_layout_async]                                                                   | Analyze document layout, such as tables, lines, words, and selection marks like radio buttons and check boxes from a file stream |
 | [AnalyzeLayoutFromUrl][analyze_layout_from_url] and [AnalyzeLayoutFromUrlAsync][analyze_layout_from_url_async]                                   | Analyze document layout such as tables, lines, words, and selection marks like radio buttons and check boxes from a URL          |
+| [AnalyzeLayoutMarkdown][analyze_layout_markdown] and [AnalyzeLayoutMarkdownAsync][analyze_layout_markdown_async]                                 | Analyze document layout in markdown output                                                                                       |
 | [AnalyzeIdentityDocuments][analyze_id_documents] and [AnalyzeIdentityDocumentsAsync][analyze_id_documents_async]                                 | Analyze data from an identity document like a passport or a US drivers license using a prebuilt model                            |
 | [AnalyzeIdentityDocumentsFromUrl][analyze_id_documents_from_url] and [AnalyzeIdentityDocumentsFromUrlAsync][analyze_id_documents_from_url_async] | Analyze data from a URL of a passport or a US drivers license using a prebuilt model                                             |
 | [AnalyzeInvoices][analyze_invoices] and [AnalyzeInvoiceAsync][analyze_invoices_async]                                                            | Analyze invoices from an input stream                                                                                            |
@@ -74,8 +82,24 @@ Guidelines][SDK_README_CONTRIBUTING] for more information.
 [copy_model_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/administration/CopyDocumentModelAsync.java
 [manage_custom_models]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/administration/ManageCustomModels.java
 [manage_custom_models_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/administration/ManageCustomModelsAsync.java
+[analyze_addon_barcodes]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnBarcodes.java
+[analyze_addon_barcodes_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnBarcodesAsync.java
+[analyze_addon_fonts]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnFonts.java
+[analyze_addon_fonts_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnFontsAsync.java
+[analyze_addon_formulas]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnFormulas.java
+[analyze_addon_formulas_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnFormulasAsync.java
+[analyze_addon_high_res]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnHighRes.java
+[analyze_addon_high_res_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnHighResAsync.java
+[analyze_addon_languages]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnLanguages.java
+[analyze_addon_languages_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnLanguagesAsync.java
+[analyze_addon_kv]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnKeyValuePair.java
+[analyze_addon_kv_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnKeyValuePairAsync.java
+[analyze_addon_query_fields]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnQueryFields.java
+[analyze_addon_query_fields_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnQueryFieldsAsync.java
 [analyze_layout]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeLayout.java
 [analyze_layout_async]:https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeLayoutAsync.java
+[analyze_layout_markdown]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeLayoutMarkdownOutput.java
+[analyze_layout_markdown_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeLayoutMarkdownOutputAsync.java
 [analyze_layout_from_url]:https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeLayoutFromUrl.java
 [analyze_layout_from_url_async]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeLayoutFromUrlAsync.java
 [analyze_custom_documents]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeCustomDocumentFromUrl.java