[DO NOT REVIEW] In Progress: API Experiment 1

[annelo-msft]

First experiment on simplifying the Form Recognizer API.

Intention is to:

• Make two clients, training and prediction/analysis
• Make client method names more specific, so samples read clearly
• Split out supervised and unsupervised
• Have one return type per analysis method
• Have shallower type hierarchies

More Notes
Outstanding design questions:

• Is there a way to encapsulate values that have a confidence score associated with them? (e.g. in ExtractedReceipt); FieldAccuracies may have the same pattern - a number with a float associated with it.
• Redesign for where I'm using dynamic? More generally, how to represent types in custom supervised models where predefined/labeled fields aren't known until training time?
• How to map non-OCR fields to OCR-extracted raw values. Using References in v2.0 API … is this the right way to do it? Can we postpone deciding until we understand customer need for this feature?

Things I tried to do:

• Split clients into Training and Prediction/Analysis - Look cross-cognitive at this.
• Make return types easy to understand based on the methods, and contain only the data returned by the method
• Make form field values look the same for supervised/unsupervised custom models

Name Mappings:

• Layout -> FormInsets (because it extracts tables and other form insets, and that's all)
• SourceFilter -> TrainingFileFilter (conflicted with a type name in System.Diagnostics)
• TrainingRequest -> properties became method parameters
• TrainingOperation -> TrainUnsupervisedModelOperation, TrainSupervisedModelOperation
• AnalysisResult -> ReceiptAnalysisResult, FormInsetAnalysisResult, CustomSupervisedAnalysisResult, CustomUnsupervisedAnalysisResult
• DataTable -> ExtractedTable (unsupervised things were prefixed by Extracted)
• DataTableCell -> ExtractedTableCell
• ReadResult -> OcrExtractedPage
• DocumentResult -> ExtractedForm
• FieldValue -> PredefinedFieldValue
• KeyValueElement -> Removed until I understand the feature better
• KeyValuePair -> ExtractedField (Unsupervised; similar to PredefinedField for Supervised)
• Language -> FormTextLanguage (but should be unified cross-cognitive)
• Model -> SupervisedTrainingResult, UnsupervisedTrainingResult
• ModelInfo -> Moved into SupervisedTrainingResult, UnsupervisedTrainingResult
• PageResult -> ExtractedPage
• ReadResult -> OcrExtractedPage
• ReferencingTextElement -> Removed until I understand the feature better
• TextElement -> Removed; properties moved to inheriting types
• TextLine -> OcrExtractedLine
• TextWord -> OcrExtractedWord
• TrainingDocument -> DocumentTrainingResult
• TrainingField -> FieldAccuracy
• TrainingResult -> SupervisedTrainingResult, UnsupervisedTrainingResult
• ModelStatus -> Removed until I understand the feature better
• OperationStatus -> Removed until I understand the feature better
• TrainingStatus -> DocumentTrainingStatus
• Unit -> FormGeometryUnit
• AnalyzeClient -> FormRecognizerAnalysisClient
• AnalyzeOperation -> ReceiptAnalysisOperation, FormInsetAnalysisOperation, CustomSupervisedAnalysisOperation, CustomUnsupervisedAnalysisOperation

Still need to do:

• Understand how customers will use output from training operations to improve these return types
• Understand error model across the API (how errors are used, and when we will throw exceptions on errors)
• Add back in models summary and list models endpoints