Board Review: Form Recognizer

[kristapratico]

The Basics

• Service team responsible for the client library: Azure SDK Team
• Link to documentation describing the service: https://docs.microsoft.com/en-us/azure/cognitive-services/form-recognizer/overview
• Contact email: @mayurid

About this client library

• Name of the client library: Form Recognizer
• Languages for this review: .NET and Python
• Link to the service REST APIs: https://github.com/Azure/azure-rest-api-specs/blob/master/specification/cognitiveservices/data-plane/FormRecognizer/preview/v2.0/FormRecognizer.json and https://westus2.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-preview/operations/AnalyzeWithCustomForm

Artifacts required (per language)

We use an API review tool (apiview) to support .NET and Java API reviews. For Python and TypeScript, use the API extractor tool, then submit the output as a Draft PR to the relevant repository (azure-sdk-for-python or azure-sdk-for-js).

.NET

• Upload DLL to apiview. Link: https://apiview.dev/Assemblies/Review/cf2c57b3d4c44ef08c2e8284f7441a2d/b2661333916f4f86b5b08da0ebce2fae
• Link to samples for champion scenarios: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/formrecognizer/Azure.AI.FormRecognizer/samples

Python

• Upload the api as a Draft PR. Link to PR: https://apiview.dev/Assemblies/Review/36ac7c8c633d4bf6a45ee8672243f195
• Link to samples for champion scenarios: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/formrecognizer/azure-ai-formrecognizer/samples

Champion Scenarios

A champion scenario is a use case that the consumer of the client library is commonly expected to perform. Champion scenarios are used to ensure the developer experience is exemplary for the common cases. You need to show the entire code sample (including error handling, as an example) for the champion scenarios.

Recognize and extract field values from custom forms

• Target audience: LOB developers (~90%)
• Code samples: .NET | Python

Recognize and extract field values from US Receipts

• Target audience: Day 0 developers, LOB developers (~30%)
• Code samples: .NET | Python

Recognize and extract OCR Content and Tables from Forms

• Target audience: LOB developers (~20%)
• Code samples: .NET | Python

Train a model from custom forms

• Target audience: Data Scientists (~50%)
• Code samples: .NET | Python

Manage custom models

• Target audience: Data Scientists (~50%)
• Code samples: .NET | Python

Agenda for the review

A board review is generally split into two parts, with additional meetings as required

Part 1 - Introducing the board to the service:

• Review of the service (no more than 10 minutes).
• Review of the champion scenarios.
• Get feedback on the API patterns used in the champion scenarios.

After part 1, you may schedule additional meetings with architects to refine the API and work on implementation.

Part 2 - the "GA" meeting

• Scheduled at least one week after the APIs have been uploaded for review.
• Will go over controversial feedback from the line-by-line API review.
• Exit meeting with concrete changes necessary to meet quality bar.

Thank you for your submission

[lilyjma]

[Microsoft Internal Only] https://msit.microsoftstream.com/video/0323a1ff-0400-a521-f066-f1eab66cc960

Action items

.Net

CustomFormModel properties

• Remove RequestedOn and rename completedOn (one proposal: trainingCompletedOn, trainingRequestedOn)

• Useful to have createdOn property exposed and training duration

recognizeOptions param

• Understand how will API work in containerized scenario

StartRecognizeContentFromUri(Uri, formUrl)

• Change to formUri

StartRecognizeContent

• Look into overload or different names for StartRecognizeContent and StartRecognizeContentFromUri

Python

• FormField: check to see if there's formfields that aren't texts

• Sample: method ConvertStringField() should throw exception instead of returning null when FieldValueType is not a string