[Document Intelligence] Update changelog to include service changes (#…

…27874) As requested by La Januari, updating the changelog for `1.0.0-beta.1` version to also convey the service updates and breaking changes as we move from - "2023-07-31" service API version(and older versions) to "2023-10-31-preview" service API version - And from `@azure/ai-form-recognizer` to `@azure-rest/ai-document-intelligence` - And the rebranding --------- Co-authored-by: Paul Hsu <bojunehsu@gmail.com>
Azure · Dec 13, 2023 · f7d5a0b · f7d5a0b
1 parent cc969de
commit f7d5a0b
Show file tree

Hide file tree

Showing 7 changed files with 523 additions and 34 deletions.
diff --git a/sdk/documentintelligence/ai-document-intelligence-rest/CHANGELOG.md b/sdk/documentintelligence/ai-document-intelligence-rest/CHANGELOG.md
@@ -14,5 +14,100 @@
 
 ### Features Added
 
-This marks the first preview of `@azure-rest/ai-document-intelligence` Rest Level Client Library for the Azure AI Document Intelligence service (formerly known as Form Recognizer).
-Please refer to the [Readme](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/documentintelligence/ai-document-intelligence-rest/README.md) and samples for more details.
+This marks the first preview of `@azure-rest/ai-document-intelligence` Rest Level Client Library for the Azure AI Document Intelligence service (formerly known as Form Recognizer), targeting service API version `"2023-10-31-preview"`.
+
+_**Note: Form Recognizer has been rebranded to Document Intelligence.**_
+
+- Updates all REST API operation paths from `{endpoint}/formrecognizer` to `{endpoint}/documentintelligence`. SDK would handle this change automatically, users would not have to do additional work to support this.
+- `@azure-rest/ai-document-intelligence` is the new package, replacing `@azure/ai-form-recognizer` package. The new package supports a Rest Level Client, which is part of the new generation of Azure SDKs to simplify the development experience. The new package is not compatible with the previous `@azure/ai-form-recognizer` package without necessary changes to your code.
+- **Breaking Changes (with the `@azure/ai-form-recognizer` SDK)** - API shapes have been designed from scratch to support the new Rest Level Client for the Document Intelligence service. Please refer to the [Readme](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/documentintelligence/ai-document-intelligence-rest/README.md) and [Samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/documentintelligence/ai-document-intelligence-rest/samples) for more understanding.
+
+### `"2023-10-31-preview"` Service API version
+
+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-form-recognizer` library.
+
+**New Features**
+
+- **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.
+
+  ```ts
+  import DocumentIntelligence from "@azure-rest/ai-document-intelligence";
+  const client = DocumentIntelligence(process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"], {
+    key: process.env["DOCUMENT_INTELLIGENCE_API_KEY"],
+  });
+
+  const initialResponse = await client
+    .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
+    .post({
+      contentType: "application/json",
+      body: {
+        urlSource:
+          "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
+      },
+      queryParameters: { outputContentFormat: "markdown" }, // <-- new query parameter
+    });
+  ```
+
+- **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.
+
+  ```ts
+  await client.path("/documentModels/{modelId}:analyze", "prebuilt-layout").post({
+    contentType: "application/json",
+    body: { urlSource: "..." },
+    queryParameters: {
+      features: ["queryFields"],
+      queryFields: ["NumberOfGuests", "StoreNumber"],
+    }, // <-- new query parameter
+  });
+  ```
+
+- **Split Options**
+
+  In the previous API versions supported by the older `@azure/ai-form-recognizer` 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**
+
+- **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"
+    },
+    ...
+  }
+  ```
+
+**Retirements/Deprecations**
+
+- `"prebuilt-businessCard"` model is retired.
+- `"prebuilt-document"` model is retired, this model is essentially `"prebuilt-layout"` with `features: ["keyValuePairs"]` specified. _(This is only supported as an optional feature for "prebuilt-layout" and "prebuilt-invoice".)_
+
+If you wish to still use these models, please rely on the older `@azure/ai-form-recognizer` library through the older service API versions.
+
+If you were using the old `@azure/ai-form-recognizer` package, please refer [MIGRATION_GUIDE.MD](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/documentintelligence/ai-document-intelligence-rest/MIGRATION-FR_v4-DI_v1.md) for more details.