0
# Azure AI Form Recognizer
1

2
Azure AI Form Recognizer is a comprehensive Python client library for Azure Document Intelligence (previously known as Form Recognizer), a cloud service that uses machine learning to analyze text and structured data from documents. It provides capabilities for layout extraction, document analysis, prebuilt models for common document types, custom model building, document classification, and advanced OCR features.
3

4
## Package Information
5

6
- **Package Name**: azure-ai-formrecognizer
7
- **Language**: Python  
8
- **Installation**: `pip install azure-ai-formrecognizer`
9
- **Latest Version**: 3.3.3
10

11
## Core Imports
12

13
```python
14
from azure.ai.formrecognizer import (
15
    DocumentAnalysisClient,
16
    DocumentModelAdministrationClient,
17
    FormRecognizerClient,
18
    FormTrainingClient
19
)
20
```
21

22
For async operations:
23

24
```python
25
from azure.ai.formrecognizer.aio import (
26
    DocumentAnalysisClient as AsyncDocumentAnalysisClient,
27
    DocumentModelAdministrationClient as AsyncDocumentModelAdministrationClient,
28
    FormRecognizerClient as AsyncFormRecognizerClient,
29
    FormTrainingClient as AsyncFormTrainingClient
30
)
31
```
32

33
Authentication:
34

35
```python
36
from azure.core.credentials import AzureKeyCredential
37
from azure.identity import DefaultAzureCredential
38
```
39

40
## Basic Usage
41

42
### Modern Document Analysis (Recommended)
43

44
```python
45
from azure.ai.formrecognizer import DocumentAnalysisClient
46
from azure.core.credentials import AzureKeyCredential
47

48
# Initialize client
49
endpoint = "https://your-resource.cognitiveservices.azure.com/"
50
credential = AzureKeyCredential("your-api-key")
51
client = DocumentAnalysisClient(endpoint, credential)
52

53
# Analyze document with prebuilt model
54
with open("receipt.jpg", "rb") as file:
55
    poller = client.begin_analyze_document("prebuilt-receipt", file)
56
    result = poller.result()
57

58
# Access extracted data
59
for document in result.documents:
60
    print(f"Document type: {document.doc_type}")
61
    for field_name, field in document.fields.items():
62
        print(f"{field_name}: {field.value} (confidence: {field.confidence})")
63
```
64

65
### Legacy Form Recognition
66

67
```python
68
from azure.ai.formrecognizer import FormRecognizerClient
69
from azure.core.credentials import AzureKeyCredential
70

71
# Initialize client for legacy API
72
client = FormRecognizerClient(endpoint, credential)
73

74
# Recognize receipt using legacy API
75
with open("receipt.jpg", "rb") as file:
76
    poller = client.begin_recognize_receipts(file)
77
    receipts = poller.result()
78

79
# Access extracted fields
80
for receipt in receipts:
81
    for field_name, field in receipt.fields.items():
82
        print(f"{field_name}: {field.value}")
83
```
84

85
## Architecture
86

87
The package provides two API generations to support different use cases:
88

89
### Legacy Form Recognizer API (v2.0, v2.1)
90
- **Purpose**: Original form processing capabilities with prebuilt models
91
- **Clients**: FormRecognizerClient, FormTrainingClient
92
- **Use Cases**: Receipts, business cards, invoices, identity documents, basic custom forms
93

94
### Modern Document Intelligence API (2022-08-31, 2023-07-31)
95
- **Purpose**: Advanced document analysis with enhanced AI capabilities
96
- **Clients**: DocumentAnalysisClient, DocumentModelAdministrationClient  
97
- **Use Cases**: General document analysis, advanced custom models, document classification, enhanced OCR features
98

99
### Client Architecture
100
Each API generation provides both synchronous and asynchronous clients:
101
- **Analysis Clients**: Process documents and extract data
102
- **Administration Clients**: Build, train, and manage custom models
103
- **Unified Authentication**: Both generations use Azure Key Credential or Azure AD authentication
104
- **Long-Running Operations**: All analysis and training operations return pollers for tracking progress
105

106
## Capabilities
107

108
### Form Recognition (Legacy API)
109

110
Traditional form processing capabilities for structured document types with prebuilt models and basic custom form training.
111

112
```python { .api }
113
class FormRecognizerClient:
114
    def begin_recognize_receipts(self, receipt, **kwargs) -> LROPoller[List[RecognizedForm]]: ...
115
    def begin_recognize_business_cards(self, business_card, **kwargs) -> LROPoller[List[RecognizedForm]]: ...
116
    def begin_recognize_invoices(self, invoice, **kwargs) -> LROPoller[List[RecognizedForm]]: ...
117
    def begin_recognize_identity_documents(self, identity_document, **kwargs) -> LROPoller[List[RecognizedForm]]: ...
118
    def begin_recognize_custom_forms(self, model_id: str, form, **kwargs) -> LROPoller[List[RecognizedForm]]: ...
119

120
class FormTrainingClient:
121
    def begin_training(self, training_files_url: str, use_training_labels: bool, **kwargs) -> LROPoller[CustomFormModel]: ...
122
    def get_custom_model(self, model_id: str, **kwargs) -> CustomFormModel: ...
123
    def list_custom_models(self, **kwargs) -> ItemPaged[CustomFormModelInfo]: ...
124
```
125

126
[Form Recognition](./form-recognition.md)
127

128
### Document Analysis (Modern API)
129

130
Advanced document analysis capabilities with enhanced AI models, supporting general document processing and sophisticated custom model building.
131

132
```python { .api }
133
class DocumentAnalysisClient:
134
    def begin_analyze_document(self, model_id: str, document, **kwargs) -> LROPoller[AnalyzeResult]: ...
135
    def begin_classify_document(self, classifier_id: str, document, **kwargs) -> LROPoller[AnalyzeResult]: ...
136

137
class DocumentModelAdministrationClient:
138
    def begin_build_document_model(self, build_mode: ModelBuildMode, **kwargs) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]: ...
139
    def begin_compose_document_model(self, model_ids: List[str], **kwargs) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]: ...
140
    def begin_build_document_classifier(self, **kwargs) -> DocumentModelAdministrationLROPoller[DocumentClassifierDetails]: ...
141
```
142

143
[Document Analysis](./document-analysis.md)
144

145
### Model Management
146

147
Comprehensive model lifecycle management including building, training, copying, composition, and monitoring across both API generations.
148

149
```python { .api }
150
# Legacy model management
151
class FormTrainingClient:
152
    def begin_copy_model(self, model_id: str, target: Dict[str, str], **kwargs) -> LROPoller[CustomFormModelInfo]: ...
153
    def begin_create_composed_model(self, model_ids: List[str], **kwargs) -> LROPoller[CustomFormModel]: ...
154

155
# Modern model management  
156
class DocumentModelAdministrationClient:
157
    def begin_copy_document_model_to(self, model_id: str, target: TargetAuthorization, **kwargs) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]: ...
158
    def get_resource_details(self, **kwargs) -> ResourceDetails: ...
159
    def list_operations(self, **kwargs) -> ItemPaged[OperationSummary]: ...
160
```
161

162
[Model Management](./model-management.md)
163

164
### Data Models and Types
165

166
Comprehensive data structures for representing extracted document content, model metadata, and operation results across both API generations.
167

168
```python { .api }
169
# Legacy form models
170
class RecognizedForm:
171
    form_type: str
172
    fields: Dict[str, FormField]
173
    pages: List[FormPage]
174

175
# Modern document models
176
class AnalyzeResult:
177
    api_version: str
178
    model_id: str
179
    content: str
180
    documents: List[AnalyzedDocument]
181
    pages: List[DocumentPage]
182
    
183
class AnalyzedDocument:
184
    doc_type: str
185
    fields: Dict[str, DocumentField]
186
    spans: List[DocumentSpan]
187
```
188

189
[Data Models](./data-models.md)
190

191
## API Versions
192

193
### FormRecognizerApiVersion
194
```python { .api }
195
class FormRecognizerApiVersion(str, Enum):
196
    V2_1 = "2.1"  # Default for legacy clients
197
    V2_0 = "2.0"
198
```
199

200
### DocumentAnalysisApiVersion  
201
```python { .api }
202
class DocumentAnalysisApiVersion(str, Enum):
203
    V2023_07_31 = "2023-07-31"  # Default for modern clients - includes enhanced features
204
    V2022_08_31 = "2022-08-31"
205
```
206

207
## Authentication
208

209
```python { .api }
210
# Azure Key Credential (recommended for development)
211
credential = AzureKeyCredential("your-api-key")
212

213
# Azure AD authentication (recommended for production)
214
credential = DefaultAzureCredential()
215

216
# Initialize any client
217
client = DocumentAnalysisClient(endpoint, credential)
218
```
219

220
## Error Handling
221

222
```python { .api }
223
from azure.ai.formrecognizer import FormRecognizerError, DocumentAnalysisError
224

225
try:
226
    # Legacy API errors
227
    poller = form_client.begin_recognize_receipts(document)
228
    result = poller.result()
229
except FormRecognizerError as e:
230
    print(f"Form recognition error: {e.error_code} - {e.message}")
231

232
try:
233
    # Modern API errors  
234
    poller = doc_client.begin_analyze_document("prebuilt-receipt", document)
235
    result = poller.result()
236
except DocumentAnalysisError as e:
237
    print(f"Document analysis error: {e.code} - {e.message}")
238
```
239

240
## Advanced Features (API v2023-07-31)
241

242
The latest API version provides enhanced capabilities:
243

244
- **High-Resolution OCR**: Improved text extraction accuracy
245
- **Barcode Detection**: Automatic barcode and QR code recognition  
246
- **Formula Recognition**: Mathematical formula extraction
247
- **Enhanced Language Support**: Multi-language document processing
248
- **Font Style Detection**: Text appearance and styling analysis
249
- **Key-Value Pair Enhancement**: Improved relationship detection
250

251
```python { .api }
252
from azure.ai.formrecognizer import AnalysisFeature
253

254
# Enable advanced features
255
features = [
256
    AnalysisFeature.OCR_HIGH_RESOLUTION,
257
    AnalysisFeature.BARCODES,
258
    AnalysisFeature.FORMULAS,
259
    AnalysisFeature.LANGUAGES
260
]
261

262
poller = client.begin_analyze_document(
263
    "prebuilt-layout",
264
    document,
265
    features=features
266
)
267
```