Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document Intelligence changelog updates #43401

Merged
merged 4 commits into from
Dec 16, 2024
Merged

Document Intelligence changelog updates #43401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a45dc3d
add changelog and renames
samvaity Dec 13, 2024
5922a0b
docs update
samvaity Dec 13, 2024
29de001
renames
samvaity Dec 13, 2024
374c739
fix build
samvaity Dec 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 39 additions & 3 deletions sdk/documentintelligence/azure-ai-documentintelligence/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,50 @@
# Release History

## 1.0.0 (Unreleased)
## 1.0.0 (2024-12-16)

### Features Added
- Added methods `getAnalyzeBatchResult`, `listAnalyzeBatchResults`, `deleteAnalyzeBatchResult`, and `deleteAnalyzeResult` to `DocumentIntelligenceClient` and `DocumentIntelligenceAsyncClient`.
samvaity marked this conversation as resolved.
Show resolved Hide resolved
- Added class `AnalyzeBatchOperation` as output model for `getAnalyzeBatchResult` and `listAnalyzeBatchResults` methods.
- Added constructor overloads for the `AnalyzeBatchDocumentsOptions` model that take required parameters.
- Added constructor overloads for the `AnalyzeDocumentsOptions` model that take required parameters and BinaryData.
- Added constructor overloads for the `ClassifyDocumentOptions` model that take required parameters and BinaryData.
- Added property `modifiedOn` to `DocumentModelDetails` and to `DocumentClassifierDetails`.
- Added enum value `SKIPPED` to `DocumentIntelligenceOperationStatus` (former `OperationStatus`).

### Breaking Changes

### Bugs Fixed
- Replaced the following `Request` classes with new corresponding `Options` classes:
- `AnalyzeBatchDocumentsRequest` to `AnalyzeBatchDocumentsOptions`.
- `AnalyzeDocumentRequest` to `AnalyzeDocumentOptions`.
- `AuthorizeClassifierCopyRequest` to `AuthorizeClassifierCopyOptions`.
- `AuthorizeCopyRequest` to `AuthorizeModelCopyOptions`.
- `BuildDocumentClassifierRequest` to `BuildClassifierOptions`.
- `BuildDocumentModelRequest` to `BuildDocumentModelOptions`.
- `ClassifyDocumentRequest` to `ClassifyDocumentOptions`.
- `ComposeDocumentModelRequest` to `ComposeModelOptions`.
- Parameters of the `AnalyzeBatchDocuments`, `AnalyzeDocument`, and `ClassifyDocument` methods have been moved into their corresponding `Options` class.
- Renamed all occurrences of properties `docType` and `docTypes` to `documentType` and `documentTypes`, respectively.
- Removed enum value `Generative` from `DocumentBuildMode`.
- Renamed enum value `StyleFonts` to `FontStyling` in `DocumentAnalysisFeature`.
- Renamed class `AnalyzeBatchOperationDetail` to `AnalyzeBatchResultDetails`.
- Renamed class `AnalyzeBatchOperation` to `AnalyzeBatchOperationDetails`.
- Renamed class `AnalyzeOperation` to `AnalyzeOperationDetails`.
- Renamed all occurrences of property `expirationDateTime` to `expiresOn`.
- Renamed method `getResourceInfo` to `getResourceDetails` in `DocumentIntelligenceAdministrationClient` and `DocumentIntelligenceAdministrationAsyncClient`.
- Renamed class `ResourceDetails` to `DocumentIntelligenceResourceDetails`.
- Renamed type `ContentFormat` to `DocumentContentFormat`.
- Renamed class `OperationDetails` to `DocumentIntelligenceOperationDetails`.
- Renamed class `InnerError` to `DocumentIntelligenceInnerError`.
- Renamed class `CopyAuthorization` to `ModelCopyAuthorization`.
- Renamed type `OperationStatus` to `DocumentIntelligenceOperationStatus`.
- Renamed property `Innererror` to `innerError` in `DocumentIntelligenceError`.
- Renamed property `InnerErrorObject` to `innerError` in `DocumentIntelligenceInnerError` (former class `InnerError`).
- Removed enum value `COMPLETED` from `DocumentIntelligenceOperationStatus` (former `OperationStatus`).

### Other Changes
#### Dependency Updates

- Upgraded `azure-core-http-netty` to version`1.15.7`.
- Upgraded `azure-core` to version `1.54.1`.

## 1.0.0-beta.4 (2024-08-14)

Expand Down
178 changes: 76 additions & 102 deletions sdk/documentintelligence/azure-ai-documentintelligence/MIGRATION_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,101 +23,36 @@ please refer to the SDK README for [azure-ai-documentintelligence][README] direc
A natural question to ask when considering whether to adopt a new version of the library is what the benefits of
doing so would be. As Azure Form Recognizer has matured and been embraced by a more diverse group of developers,
we have been focused on learning the patterns and practices to best support developer productivity and add value to our
customers. So We're rebranding the package name to Azure `Document Intelligence`.
customers. So we are rebranding the package name to Azure `Document Intelligence`.

## Features Added
There are many benefits to using the new `azure-ai-documentintelligence` library. This new library introduces two new clients: `DocumentIntelligenceClient` and `DocumentIntelligenceAdministrationClient`, providing support for the new features added by the service in API version `2024-11-30` and higher.

### 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. Custom models should continue to use the default "text" content format for generating .ocr.json results.

Service follows the GFM spec ([GitHub Flavored Markdown](https://github.github.com/gfm/)) for the Markdown format. This
SDK introduces a new enum _ContentFormat_ with value "text" or "markdown" to indicate the result content format.

```java
File document = new File("{your-file-to-analyze}");
SyncPoller<AnalyzeOperation, AnalyzeResult> analyzeLayoutResultPoller =
client.beginAnalyzeDocument("prebuilt-layout", null,
null,
null,
null,
null,
DocumentContentFormat.MARKDOWN,
new AnalyzeDocumentOptions().setBytesSource(Files.readAllBytes(document.toPath())));
```
For the complete sample, see [Sample: Markdown][Sample-AnalyzeLayoutMarkdownOutput].

### Query Fields

We reintroduce query fields as a premium add-on feature. When the keyword argument `features` is specified, the service
will further extract the values of the fields specified via the keyword argument `queryFields` to supplement any
existing fields defined by the model as fallback.

```java
File document = new File("{your-file-to-analyze}");
SyncPoller<AnalyzeOperation, AnalyzeResult> analyzeLayoutResultPoller =
client.beginAnalyzeDocument("prebuilt-layout", null,
null,
null,
Arrays.asList(DocumentAnalysisFeature.QUERY_FIELDS),
Arrays.asList("Address", "InvoiceNumber"),
null,
new AnalyzeDocumentOptions().setBytesSource(Files.readAllBytes(document.toPath())));
```
For the complete sample, see [Sample: Query Fields][Sample-AnalyzeAddOnQueryFields].

### 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, this SDK introduces a keyword argument "split" to specify the document splitting
mode with the new "2023-10-31-preview" service API 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.

New features provided by the `azure-ai-documentintelligence` library include:
- **Markdown content format:** support to output with Markdown content format along with the default plain text. This is only supported for the "prebuilt-layout" model. Markdown content format is deemed a more friendly format for LLM consumption in a chat or automation use scenario.
- **Query fields:** query fields are reintroduced as a premium add-on feature. When the `DocumentAnalysisFeature.queryFields` argument is passed to a document analysis request, the service will further extract the values of the fields specified via the parameter `queryFields` to supplement any existing fields defined by the model as fallback.
- **Split options:** in previous API versions, the document splitting and classification operation always tried to split the input file into multiple documents. To enable a wider set of scenarios, `ClassifyDocument` now supports a `split` parameter. The following values are supported:
- `AUTO`: let the service determine where to split.
- `NONE`: the entire file is treated as a single document. No splitting is performed.
- `PER_PAGE`: each page is treated as a separate document. Each empty page is kept as its own document.

## Breaking Changes

### Clients names updates
To improve the development experience and address the consistent feedback across the Document Intelligence SDK, this new
version of the library introduces two new clients
`DocumentIntelligenceClient` and the `DocumentIntelligenceAdministrationClient` that provide unified methods for
analyzing documents and provide support for the new features added by the service in
API version `2023-10-31-preview` and later.

This below table describes the relationship between SDK versions and supported API versions of the service:

| SDK version | Supported API version of service |
|-----------------------------|----------------------------------|
| 1.0.0-beta.x | 2023-10-31-preview (default) |
| 3.3.X (Form Recognizer SDK) | 2.0, 2.1, 2022-08-31, 2023-07-31 |
| 3.2.X (Form Recognizer SDK) | 2.0, 2.1, 2022-08-31 |
| 3.1.X (Form Recognizer SDK) | 2.0, 2.1 |
| 3.0.0 (Form Recognizer SDK) | 2.0 |
analyzing documents and support for the new features added by the service in API version `2023-10-31-preview` and later.

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 DocumentIntelligenceAdministrationClient |
| 2023-07-31 (Use Form Recognizer SDK) | DocumentAnalysisClient and DocumentModelAdministrationClient |
| 2022-08-31 (Use Form Recognizer SDK) | DocumentAnalysisClient and DocumentModelAdministrationClient |
| 2.1 (Use Form Recognizer SDK) | FormRecognizerClient and FormTrainingClient |
| 2.0 (Use Form Recognizer SDK) | FormRecognizerClient and FormTrainingClient |
| Package | API version | Supported clients |
|-------------------------------|--------------------------------------|-------------------------------------------------------------------------|
| azure-ai-documentintelligence | 2024-11-30 | DocumentIntelligenceClient and DocumentIntelligenceAdministrationClient |
| azure-ai-formrecognizer | 2023-07-31 (Use Form Recognizer SDK) | DocumentAnalysisClient and DocumentModelAdministrationClient |
| azure-ai-formrecognizer | 2022-08-31 (Use Form Recognizer SDK) | DocumentAnalysisClient and DocumentModelAdministrationClient |
| azure-ai-formrecognizer | 2.1 (Use Form Recognizer SDK) | FormRecognizerClient and FormTrainingClient |
| azure-ai-formrecognizer | 2.0 (Use Form Recognizer SDK) | FormRecognizerClient and FormTrainingClient |

Please refer to the [README][README] for more information on these new clients.

Expand Down Expand Up @@ -167,27 +102,68 @@ the _Currency_ field in result has been removed.
- `"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<AnalyzeOperation, AnalyzeResult> analyzeLayoutResultPoller =
client.beginAnalyzeDocument("prebuilt-layout", null,
null,
null,
Arrays.asList(DocumentAnalysisFeature.FORMULAS),
null,
null,
new AnalyzeDocumentOptions().setBytesSource(Files.readAllBytes(document.toPath())));
```

For the complete sample, see [Sample: KeyValuePair][Sample-AnalyzeAddOnKeyValuePair].

- All prebuilt models can be seen [here][service_supported_models]. If you wish to still use these models, please rely on the older
- All prebuilt models can be seen [here][service_supported_models]. If you wish to still use these models, please rely on the older
`azure-ai-formrecognizer` library through the older service API versions.

For the complete sample, see [Sample: AnalyzeAddOnFormulas][Sample-AnalyzeAddOnFormulas].

### Analyzing documents

Differences between the versions:
- The former `AnalyzeDocument` method taking `bytes` as the input document is not supported in `azure-ai-documentintelligence` 1.0.0. As a workaround you will need to use a URL input or the bytes/BinaryData input option, as shown in the example below.
- `beginAnalyzeDocumentFromUrl` has been renamed to `beginAnalyzeDocument` and its input arguments have been reorganized:
- The `documentUrl` parameter has been removed. Instead, an `AnalyzeDocumentOptions` object must be passed to the method to select the desired input type: URl or bytes/binary data.
- The property `DocumentField.value` has been removed. A field's value can now be extracted from one of the value properties, depending on the type of the field: `valueAddress` for type `Address`, `valueBoolean` for type `Boolean`, and so on.

```java com.azure.ai.documentintelligence.readme.analyzeLayout
File layoutDocument = new File("local/file_path/filename.png");
Path filePath = layoutDocument.toPath();
BinaryData layoutDocumentData = BinaryData.fromFile(filePath, (int) layoutDocument.length());

SyncPoller<AnalyzeOperationDetails, AnalyzeResult> analyzeLayoutResultPoller =
documentIntelligenceClient.beginAnalyzeDocument("prebuilt-layout",
new AnalyzeDocumentOptions(layoutDocumentData));

AnalyzeResult analyzeLayoutResult = analyzeLayoutResultPoller.getFinalResult();

// pages
analyzeLayoutResult.getPages().forEach(documentPage -> {
System.out.printf("Page has width: %.2f and height: %.2f, measured with unit: %s%n",
documentPage.getWidth(),
documentPage.getHeight(),
documentPage.getUnit());

// lines
documentPage.getLines().forEach(documentLine ->
System.out.printf("Line '%s' is within a bounding box %s.%n",
documentLine.getContent(),
documentLine.getPolygon().toString()));

// selection marks
documentPage.getSelectionMarks().forEach(documentSelectionMark ->
System.out.printf("Selection mark is '%s' and is within a bounding box %s with confidence %.2f.%n",
documentSelectionMark.getState().toString(),
documentSelectionMark.getPolygon().toString(),
documentSelectionMark.getConfidence()));
});

// tables
List<DocumentTable> tables = analyzeLayoutResult.getTables();
for (int i = 0; i < tables.size(); i++) {
DocumentTable documentTable = tables.get(i);
System.out.printf("Table %d has %d rows and %d columns.%n", i, documentTable.getRowCount(),
documentTable.getColumnCount());
documentTable.getCells().forEach(documentTableCell -> {
System.out.printf("Cell '%s', has row index %d and column index %d.%n", documentTableCell.getContent(),
documentTableCell.getRowIndex(), documentTableCell.getColumnIndex());
});
System.out.println();
}
```

## Additional samples

For additional samples please take a look at the [Document Intelligence Samples][README-Samples]
For additional samples please take a look at the [Document Intelligence Samples][README-Samples] for more guidance.

<!-- Links -->
[DocumentIntelligenceClientBuilder]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/main/java/com/azure/ai/documentintelligence/documentanalysis/DocumentIntelligenceClientBuilder.java
Expand All @@ -201,9 +177,7 @@ For additional samples please take a look at the [Document Intelligence Samples]
[GuidelinesJavaDesign]: https://azure.github.io/azure-sdk/java_introduction.html#namespaces
[README-Samples]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/README.md
[README]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/README.md
[Sample-AnalyzeAddOnKeyValuePair]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnKeyValuePair.java
[Sample-AnalyzeAddOnQueryFields]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnQueryFields.java
[Sample-AnalyzeLayoutMarkdownOutput]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeLayoutMarkdownOutput.java
[Sample-AnalyzeAddOnFormulas]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/src/samples/java/com/azure/ai/documentintelligence/AnalyzeAddOnFormulas.java
[service_supported_models]: https://aka.ms/azsdk/documentintelligence/models

![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fdocumentintelligence%2Fazure-ai-documentintelligence%2Fmigration-guide.png)
6 changes: 3 additions & 3 deletions sdk/documentintelligence/azure-ai-documentintelligence/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ File layoutDocument = new File("local/file_path/filename.png");
Path filePath = layoutDocument.toPath();
BinaryData layoutDocumentData = BinaryData.fromFile(filePath, (int) layoutDocument.length());

SyncPoller<AnalyzeOperation, AnalyzeResult> analyzeLayoutResultPoller =
SyncPoller<AnalyzeOperationDetails, AnalyzeResult> analyzeLayoutResultPoller =
documentIntelligenceClient.beginAnalyzeDocument("prebuilt-layout",
new AnalyzeDocumentOptions(layoutDocumentData));

Expand Down Expand Up @@ -219,7 +219,7 @@ For example, to analyze fields from a sales receipt, into the `beginAnalyzeDocum
File sourceFile = new File("../documentintelligence/azure-ai-documentintelligence/src/samples/resources/"
+ "sample-forms/receipts/contoso-allinone.jpg");

SyncPoller<AnalyzeOperation, AnalyzeResult> analyzeReceiptPoller =
SyncPoller<AnalyzeOperationDetails, AnalyzeResult> analyzeReceiptPoller =
documentIntelligenceClient.beginAnalyzeDocument("prebuilt-receipt",
new AnalyzeDocumentOptions(Files.readAllBytes(sourceFile.toPath())));

Expand Down Expand Up @@ -314,7 +314,7 @@ was built on.
```java com.azure.ai.documentintelligence.readme.analyzeCustomModel
String documentUrl = "{document-url}";
String modelId = "{custom-built-model-ID}";
SyncPoller<AnalyzeOperation, AnalyzeResult> analyzeDocumentPoller = documentIntelligenceClient.beginAnalyzeDocument(modelId,
SyncPoller<AnalyzeOperationDetails, AnalyzeResult> analyzeDocumentPoller = documentIntelligenceClient.beginAnalyzeDocument(modelId,
new AnalyzeDocumentOptions(documentUrl).setPages(Collections.singletonList("1")).setLocale("en-US")
.setStringIndexType(StringIndexType.TEXT_ELEMENTS).setDocumentAnalysisFeatures(Arrays.asList(DocumentAnalysisFeature.LANGUAGES))
.setOutputContentFormat(DocumentContentFormat.TEXT));
Expand Down
Loading
Loading