tessl/pypi-azure-ai-formrecognizer

Microsoft Azure Document Intelligence client library for analyzing text and structured data from documents with machine learning

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Model Management

Name: tessl/pypi-azure-ai-formrecognizer
Author: tessl

Comprehensive model lifecycle management capabilities across both legacy Form Recognizer API and modern Document Intelligence API. This includes building custom models, training classifiers, copying models between resources, model composition, and operation monitoring.

Capabilities

Legacy Model Management (FormTrainingClient)

Traditional model training and management for Form Recognizer API v2.1 and below, focusing on custom form models with supervised and unsupervised training.

Model Training

def begin_training(training_files_url: str, use_training_labels: bool, **kwargs) -> LROPoller[CustomFormModel]:
    """
    Train custom form model from training data.
    
    Parameters:
    - training_files_url: Azure Blob Storage URL containing training documents
    - use_training_labels: Whether to use labeled training data (supervised)
    - model_name: Optional name for the model
    - prefix: Filter training files by prefix
    
    Returns:
    LROPoller that yields CustomFormModel when training completes
    """

Usage Example

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential

training_client = FormTrainingClient(endpoint, AzureKeyCredential("key"))

# Train with labeled data (supervised)
training_files_url = "https://yourstorageaccount.blob.core.windows.net/training-data?sas-token"

poller = training_client.begin_training(
    training_files_url=training_files_url,
    use_training_labels=True,
    model_name="Invoice Model v1"
)

model = poller.result()
print(f"Model ID: {model.model_id}")
print(f"Status: {model.status}")
print(f"Accuracy: {model.training_documents[0].page_count}")

# Use trained model
from azure.ai.formrecognizer import FormRecognizerClient

form_client = FormRecognizerClient(endpoint, AzureKeyCredential("key"))
with open("invoice.pdf", "rb") as invoice:
    poller = form_client.begin_recognize_custom_forms(model.model_id, invoice)
    result = poller.result()

Model Information and Listing

def get_custom_model(model_id: str, **kwargs) -> CustomFormModel:
    """
    Get detailed information about a custom model.
    
    Parameters:
    - model_id: ID of the custom model
    
    Returns:
    CustomFormModel with complete model details
    """

def list_custom_models(**kwargs) -> ItemPaged[CustomFormModelInfo]:
    """
    List all custom models in the resource.
    
    Returns:
    ItemPaged iterator of CustomFormModelInfo objects
    """

def get_account_properties(**kwargs) -> AccountProperties:
    """
    Get account information including model quotas.
    
    Returns:
    AccountProperties with quota and usage information
    """

Model Operations

def delete_model(model_id: str, **kwargs) -> None:
    """
    Delete a custom model.
    
    Parameters:
    - model_id: ID of model to delete
    """

def get_copy_authorization(**kwargs) -> Dict[str, str]:
    """
    Generate authorization for copying model to another resource.
    
    Parameters:
    - resource_id: Target resource ID
    - resource_region: Target resource region
    
    Returns:
    Dictionary with copy authorization details
    """

def begin_copy_model(model_id: str, target: Dict[str, str], **kwargs) -> LROPoller[CustomFormModelInfo]:
    """
    Copy model to another Form Recognizer resource.
    
    Parameters:
    - model_id: Source model ID
    - target: Copy authorization from target resource
    
    Returns:
    LROPoller that yields CustomFormModelInfo for copied model
    """

def begin_create_composed_model(model_ids: List[str], **kwargs) -> LROPoller[CustomFormModel]:
    """
    Create composed model from multiple trained models.
    
    Parameters:
    - model_ids: List of model IDs to compose
    - model_name: Optional name for composed model
    
    Returns:
    LROPoller that yields CustomFormModel for composed model
    """

Modern Model Management (DocumentModelAdministrationClient)

Advanced model management for Document Intelligence API 2022-08-31 and later, supporting neural and template-based training modes with enhanced capabilities.

Model Building

def begin_build_document_model(build_mode: Union[str, ModelBuildMode], **kwargs) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]:
    """
    Build custom document model from training data.
    
    Parameters:
    - build_mode: "template" or "neural" (ModelBuildMode enum)
    - blob_container_url: Azure Blob Storage URL with training documents
    - prefix: Filter training files by prefix
    - model_id: Optional custom model ID
    - description: Model description
    - tags: Dictionary of custom tags
    
    Returns:
    DocumentModelAdministrationLROPoller that yields DocumentModelDetails
    """

def begin_compose_document_model(model_ids: List[str], **kwargs) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]:
    """
    Create composed model from multiple document models.
    
    Parameters:
    - model_ids: List of model IDs to compose (max 100)
    - model_id: Optional custom model ID for composed model
    - description: Model description
    - tags: Dictionary of custom tags
    
    Returns:
    DocumentModelAdministrationLROPoller that yields DocumentModelDetails
    """

Build Modes

class ModelBuildMode(str, Enum):
    """Model building approaches for different use cases."""
    TEMPLATE = "template"  # Fast training, structured forms with consistent layout
    NEURAL = "neural"     # Slower training, better for varied layouts and complex documents

Usage Example

from azure.ai.formrecognizer import DocumentModelAdministrationClient, ModelBuildMode
from azure.core.credentials import AzureKeyCredential

admin_client = DocumentModelAdministrationClient(endpoint, AzureKeyCredential("key"))

# Build neural model for complex documents
blob_container_url = "https://yourstorageaccount.blob.core.windows.net/training?sas-token"

poller = admin_client.begin_build_document_model(
    build_mode=ModelBuildMode.NEURAL,
    blob_container_url=blob_container_url,
    description="Contract Analysis Model",
    tags={"project": "legal-docs", "version": "1.0"}
)

model = poller.result()
print(f"Model ID: {model.model_id}")
print(f"Created: {model.created_date_time}")
print(f"Description: {model.description}")

# Use the model
from azure.ai.formrecognizer import DocumentAnalysisClient

doc_client = DocumentAnalysisClient(endpoint, AzureKeyCredential("key"))
with open("contract.pdf", "rb") as document:
    poller = doc_client.begin_analyze_document(model.model_id, document)
    result = poller.result()

Model Information and Management

def get_document_model(model_id: str, **kwargs) -> DocumentModelDetails:
    """
    Get detailed information about a document model.
    
    Parameters:
    - model_id: Model identifier
    
    Returns:
    DocumentModelDetails with complete model information
    """

def list_document_models(**kwargs) -> ItemPaged[DocumentModelSummary]:
    """
    List all document models in the resource.
    
    Returns:
    ItemPaged iterator of DocumentModelSummary objects
    """

def delete_document_model(model_id: str, **kwargs) -> None:
    """
    Delete a document model.
    
    Parameters:
    - model_id: Model identifier to delete
    """

def get_resource_details(**kwargs) -> ResourceDetails:
    """
    Get resource information including quotas and usage.
    
    Returns:
    ResourceDetails with quota information
    """

Model Copying

def get_copy_authorization(**kwargs) -> TargetAuthorization:
    """
    Generate authorization for copying model to this resource.
    
    Parameters:
    - model_id: Optional target model ID
    - description: Optional description for copied model
    - tags: Optional tags for copied model
    
    Returns:
    TargetAuthorization for model copying
    """

def begin_copy_document_model_to(model_id: str, target: TargetAuthorization, **kwargs) -> DocumentModelAdministrationLROPoller[DocumentModelDetails]:
    """
    Copy document model to another resource.
    
    Parameters:
    - model_id: Source model ID
    - target: TargetAuthorization from destination resource
    
    Returns:
    DocumentModelAdministrationLROPoller that yields DocumentModelDetails
    """

Model Copying Example

# On target resource - generate authorization
target_admin_client = DocumentModelAdministrationClient(target_endpoint, target_credential)
target_auth = target_admin_client.get_copy_authorization(
    model_id="copied-model-id",
    description="Copied invoice model",
    tags={"source": "prod-resource"}
)

# On source resource - perform copy
source_admin_client = DocumentModelAdministrationClient(source_endpoint, source_credential)
copy_poller = source_admin_client.begin_copy_document_model_to(
    "source-model-id", 
    target_auth
)

copied_model = copy_poller.result()
print(f"Model copied to: {copied_model.model_id}")

Document Classification

Building and managing document classifiers for automatic document type detection.

def begin_build_document_classifier(**kwargs) -> DocumentModelAdministrationLROPoller[DocumentClassifierDetails]:
    """
    Build custom document classifier.
    
    Parameters:
    - doc_types: Dictionary mapping document types to training data sources
    - classifier_id: Optional custom classifier ID
    - description: Classifier description
    
    Returns:
    DocumentModelAdministrationLROPoller that yields DocumentClassifierDetails
    """

def get_document_classifier(classifier_id: str, **kwargs) -> DocumentClassifierDetails:
    """
    Get document classifier information.
    
    Parameters:
    - classifier_id: Classifier identifier
    
    Returns:
    DocumentClassifierDetails with classifier information
    """

def list_document_classifiers(**kwargs) -> ItemPaged[DocumentClassifierDetails]:
    """
    List all document classifiers.
    
    Returns:
    ItemPaged iterator of DocumentClassifierDetails
    """

def delete_document_classifier(classifier_id: str, **kwargs) -> None:
    """
    Delete document classifier.
    
    Parameters:
    - classifier_id: Classifier identifier to delete
    """

Classifier Building Example

# Define document types and training data
doc_types = {
    "invoice": {
        "azure_blob_source": {
            "container_url": "https://storage.blob.core.windows.net/invoices?sas",
            "prefix": "training/"
        }
    },
    "receipt": {
        "azure_blob_source": {
            "container_url": "https://storage.blob.core.windows.net/receipts?sas",
            "prefix": "training/"
        }
    },
    "contract": {
        "azure_blob_file_list_source": {
            "container_url": "https://storage.blob.core.windows.net/contracts?sas",
            "file_list": "contract_files.json"
        }
    }
}

# Build classifier
poller = admin_client.begin_build_document_classifier(
    doc_types=doc_types,
    description="Financial Document Classifier",
    classifier_id="financial-docs-v1"
)

classifier = poller.result()
print(f"Classifier ID: {classifier.classifier_id}")
print(f"Document types: {list(classifier.doc_types.keys())}")

Operation Monitoring

Track and monitor long-running operations across the service.

def list_operations(**kwargs) -> ItemPaged[OperationSummary]:
    """
    List all operations for the resource.
    
    Returns:
    ItemPaged iterator of OperationSummary objects
    """

def get_operation(operation_id: str, **kwargs) -> OperationDetails:
    """
    Get detailed information about a specific operation.
    
    Parameters:
    - operation_id: Operation identifier
    
    Returns:
    OperationDetails with complete operation information
    """

Operation Monitoring Example

# List recent operations
operations = admin_client.list_operations()

for operation in operations:
    print(f"Operation: {operation.operation_id}")
    print(f"Kind: {operation.kind}")
    print(f"Status: {operation.status}")
    print(f"Progress: {operation.percent_completed}%")
    print(f"Created: {operation.created_date_time}")
    
    if operation.status == "failed":
        # Get detailed error information
        details = admin_client.get_operation(operation.operation_id)
        if details.error:
            print(f"Error: {details.error.code} - {details.error.message}")

FormTrainingClient

class FormTrainingClient:
    """
    Client for training and managing custom models using Form Recognizer API v2.1 and below.
    """
    
    def __init__(
        self,
        endpoint: str,
        credential: Union[AzureKeyCredential, TokenCredential],
        **kwargs
    ):
        """
        Initialize FormTrainingClient.
        
        Parameters:
        - endpoint: Cognitive Services endpoint URL
        - credential: Authentication credential
        - api_version: API version (default: FormRecognizerApiVersion.V2_1)
        """
    
    def get_form_recognizer_client(self, **kwargs) -> FormRecognizerClient:
        """
        Get FormRecognizerClient using same configuration.
        
        Returns:
        FormRecognizerClient instance
        """
    
    def close(self) -> None:
        """Close client and release resources."""

# Async version
class AsyncFormTrainingClient:
    """
    Async client for training and managing custom models using Form Recognizer API v2.1 and below.
    
    Provides the same methods as FormTrainingClient but with async/await support.
    """
    
    def __init__(
        self,
        endpoint: str,
        credential: Union[AzureKeyCredential, AsyncTokenCredential],
        **kwargs
    ):
        """
        Initialize AsyncFormTrainingClient.
        
        Parameters:
        - endpoint: Cognitive Services endpoint URL
        - credential: Authentication credential (must support async operations)
        - api_version: API version (default: FormRecognizerApiVersion.V2_1)
        """
    
    async def begin_training(self, training_files_url: str, use_training_labels: bool, **kwargs) -> AsyncLROPoller[CustomFormModel]: ...
    async def delete_model(self, model_id: str, **kwargs) -> None: ...
    async def list_custom_models(self, **kwargs) -> AsyncItemPaged[CustomFormModelInfo]: ...
    async def get_account_properties(self, **kwargs) -> AccountProperties: ...
    async def get_custom_model(self, model_id: str, **kwargs) -> CustomFormModel: ...
    async def get_copy_authorization(self, **kwargs) -> Dict[str, str]: ...
    async def begin_copy_model(self, model_id: str, target: Dict[str, str], **kwargs) -> AsyncLROPoller[CustomFormModelInfo]: ...
    async def begin_create_composed_model(self, model_ids: List[str], **kwargs) -> AsyncLROPoller[CustomFormModel]: ...
    
    def get_form_recognizer_client(self, **kwargs) -> AsyncFormRecognizerClient:
        """
        Get AsyncFormRecognizerClient using same configuration.
        
        Returns:
        AsyncFormRecognizerClient instance
        """
    
    async def close(self) -> None:
        """Close client and release resources."""

DocumentModelAdministrationClient

class DocumentModelAdministrationClient:
    """
    Client for building and managing models using Document Intelligence API 2022-08-31 and later.
    """
    
    def __init__(
        self,
        endpoint: str,
        credential: Union[AzureKeyCredential, TokenCredential],
        **kwargs
    ):
        """
        Initialize DocumentModelAdministrationClient.
        
        Parameters:
        - endpoint: Cognitive Services endpoint URL
        - credential: Authentication credential
        - api_version: API version (default: DocumentAnalysisApiVersion.V2023_07_31)
        """
    
    def get_document_analysis_client(self, **kwargs) -> DocumentAnalysisClient:
        """
        Get DocumentAnalysisClient using same configuration.
        
        Returns:
        DocumentAnalysisClient instance
        """
    
    def close(self) -> None:
        """Close client and release resources."""

# Async version
class AsyncDocumentModelAdministrationClient:
    """
    Async client for building and managing models using Document Intelligence API 2022-08-31 and later.
    
    Provides the same methods as DocumentModelAdministrationClient but with async/await support.
    """
    
    def __init__(
        self,
        endpoint: str,
        credential: Union[AzureKeyCredential, AsyncTokenCredential],
        **kwargs
    ):
        """
        Initialize AsyncDocumentModelAdministrationClient.
        
        Parameters:
        - endpoint: Cognitive Services endpoint URL
        - credential: Authentication credential (must support async operations)
        - api_version: API version (default: DocumentAnalysisApiVersion.V2023_07_31)
        """
    
    async def begin_build_document_model(self, build_mode: Union[str, ModelBuildMode], **kwargs) -> AsyncDocumentModelAdministrationLROPoller[DocumentModelDetails]: ...
    async def begin_compose_document_model(self, model_ids: List[str], **kwargs) -> AsyncDocumentModelAdministrationLROPoller[DocumentModelDetails]: ...
    async def get_copy_authorization(self, **kwargs) -> TargetAuthorization: ...
    async def begin_copy_document_model_to(self, model_id: str, target: TargetAuthorization, **kwargs) -> AsyncDocumentModelAdministrationLROPoller[DocumentModelDetails]: ...
    async def delete_document_model(self, model_id: str, **kwargs) -> None: ...
    async def list_document_models(self, **kwargs) -> AsyncItemPaged[DocumentModelSummary]: ...
    async def get_resource_details(self, **kwargs) -> ResourceDetails: ...
    async def get_document_model(self, model_id: str, **kwargs) -> DocumentModelDetails: ...
    async def list_operations(self, **kwargs) -> AsyncItemPaged[OperationSummary]: ...
    async def get_operation(self, operation_id: str, **kwargs) -> OperationDetails: ...
    async def begin_build_document_classifier(self, **kwargs) -> AsyncDocumentModelAdministrationLROPoller[DocumentClassifierDetails]: ...
    async def get_document_classifier(self, classifier_id: str, **kwargs) -> DocumentClassifierDetails: ...
    async def list_document_classifiers(self, **kwargs) -> AsyncItemPaged[DocumentClassifierDetails]: ...
    async def delete_document_classifier(self, classifier_id: str, **kwargs) -> None: ...
    
    def get_document_analysis_client(self, **kwargs) -> AsyncDocumentAnalysisClient:
        """
        Get AsyncDocumentAnalysisClient using same configuration.
        
        Returns:
        AsyncDocumentAnalysisClient instance
        """
    
    async def close(self) -> None:
        """Close client and release resources."""

Training Data Requirements

Blob Storage Structure

container/
├── training/
│   ├── document1.pdf
│   ├── document2.pdf
│   ├── document3.pdf
│   └── ...
└── labels/  # For supervised training
    ├── document1.pdf.labels.json
    ├── document2.pdf.labels.json
    └── ...

Label Format (Legacy API)

{
    "document": "document1.pdf",
    "labels": [
        {
            "label": "VendorName",
            "key": null,
            "value": [
                {
                    "page": 1,
                    "text": "Contoso Inc",
                    "boundingBoxes": [
                        [100, 200, 300, 200, 300, 250, 100, 250]
                    ]
                }
            ]
        }
    ]
}

Modern API Training Data

{
    "fields": {
        "VendorName": {
            "type": "string",
            "valueString": "Contoso Inc"
        },
        "InvoiceTotal": {
            "type": "number",
            "valueNumber": 1234.56
        }
    },
    "boundingRegions": [
        {
            "pageNumber": 1,
            "polygon": [100, 200, 300, 200, 300, 250, 100, 250]
        }
    ]
}

Error Handling

from azure.ai.formrecognizer import FormRecognizerError, DocumentAnalysisError

# Legacy API errors
try:
    poller = training_client.begin_training(training_url, True)
    model = poller.result()
except FormRecognizerError as e:
    print(f"Training failed: {e.error_code} - {e.message}")

# Modern API errors
try:
    poller = admin_client.begin_build_document_model(ModelBuildMode.NEURAL, blob_container_url=training_url)
    model = poller.result()
except DocumentAnalysisError as e:
    print(f"Model building failed: {e.code} - {e.message}")
    if e.innererror:
        print(f"Inner error: {e.innererror.code}")

Install with Tessl CLI

npx tessl i tessl/pypi-azure-ai-formrecognizer

docs

tessl/pypi-azure-ai-formrecognizer