Getting Started with IRIS IDP

Welcome to IRIS, the Intelligent Document Processing (IDP) platform designed for automated document understanding. This guide will help you get started with using the IRIS API to extract structured data from your documents. OCR is a core component within the IDP pipeline used for text extraction specialized by document type.

What is IRIS?

IRIS is a comprehensive 6-phase IDP pipeline that transforms document images into structured JSON data:

1. Phase 1: Image preprocessing and geometric correction (unwarping)
2. Phase 2: ML-powered embeddings generation and automatic clustering
3. Phase 3-4: Intelligent document classification using deep learning
4. Phase 5-6: Specialized text extraction (OCR) and JSON structure generation

Quick Start

Prerequisites

• Python 3.8+ for API integration
• Valid image file (JPG, PNG, PDF) of your document
• Network access to the IRIS API endpoints

Your First API Call

The simplest way to use IRIS is through the complete pipeline endpoint:

curl -X POST "http://localhost:8000/process" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@your_document.jpg"

Example Response:

{
  "success": true,
  "pipeline_id": "uuid-123-456-789",
  "processing_time": 8.45,
  "document_type": "ficha_residencia",
  "final_extraction": {
    "personal_info": {
      "nombres": "JUAN CARLOS",
      "apellidos": "RODRIGUEZ MARTINEZ",
      "cedula_numero": "12.345.678-9",
      "fecha_nacimiento": "15/08/1985"
    },
    "contact_info": {
      "direccion": "CALLE 123 #45-67 BARRIO CENTRO",
      "telefono": "+57 300 123 4567"
    },
    "metadata": {
      "overall_confidence": 0.87,
      "quality_level": "excellent"
    }
  }
}

Supported Document Types

IRIS specializes in extracting structured data from:

📄 Identity Documents

• Cédulas de Identidad (Colombian ID cards)
• Pasaportes (Passports)
• Driver's Licenses

🏠 Residence Forms

• Fichas de Residencia (Residence forms)
• Address verification documents
• Utility bills with personal data

🏢 Government Forms

• Immigration documents
• Official registration forms
• Government-issued certificates

Integration Examples

Python Integration

import requests
import json

def process_document_with_iris(image_path):
    """
    Process a document using IRIS OCR API
    """
    url = "http://localhost:8000/process"
    
    with open(image_path, 'rb') as image_file:
        files = {'file': image_file}
        response = requests.post(url, files=files)
    
    if response.status_code == 200:
        result = response.json()
        if result['success']:
            return result['final_extraction']
        else:
            print(f"Processing failed: {result.get('error')}")
    else:
        print(f"API error: {response.status_code}")
    
    return None

# Usage example
extraction = process_document_with_iris("my_document.jpg")
if extraction:
    print(f"Name: {extraction['personal_info']['nombre_completo']}")
    print(f"ID: {extraction['personal_info']['cedula_numero']}")

JavaScript/Node.js Integration

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

async function processDocumentWithIris(imagePath) {
    try {
        const form = new FormData();
        form.append('file', fs.createReadStream(imagePath));
        
        const response = await axios.post(
            'http://localhost:8000/process',
            form,
            {
                headers: {
                    ...form.getHeaders(),
                },
                timeout: 60000 // 60 seconds timeout
            }
        );
        
        if (response.data.success) {
            return response.data.final_extraction;
        } else {
            console.error('Processing failed:', response.data.error);
            return null;
        }
    } catch (error) {
        console.error('API error:', error.message);
        return null;
    }
}

// Usage example
processDocumentWithIris('my_document.jpg')
    .then(extraction => {
        if (extraction) {
            console.log(`Name: ${extraction.personal_info.nombre_completo}`);
            console.log(`ID: ${extraction.personal_info.cedula_numero}`);
        }
    });

cURL Examples

Basic Document Processing

# Process any document with automatic classification
curl -X POST "http://localhost:8000/process" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@document.jpg"

Process with Specific Document Type

# If you know the document type, specify it for better accuracy
curl -X POST "http://localhost:8000/process" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@cedula.jpg" \
     -F "document_type=cedula_identidad"

Process with Custom Configuration

# Custom processing with specific parameters
curl -X POST "http://localhost:8000/process" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@document.jpg" \
     -F "apply_unwarping=true" \
     -F "ocr_confidence=0.2" \
     -F "enhance_quality=true"

Understanding the Response

Response Structure

{
  "success": true,
  "pipeline_id": "unique-identifier",
  "processing_time": 8.45,
  "document_type": "ficha_residencia",
  
  "final_extraction": {
    "personal_info": {
      "nombres": "First names",
      "apellidos": "Last names", 
      "nombre_completo": "Full name",
      "cedula_numero": "ID number",
      "fecha_nacimiento": "Birth date"
    },
    "contact_info": {
      "direccion": "Address",
      "telefono": "Phone number",
      "email": "Email address"
    },
    "additional_info": {
      "estado_civil": "Marital status",
      "ocupacion": "Occupation",
      "nacionalidad": "Nationality"
    },
    "metadata": {
      "overall_confidence": 0.87,
      "quality_level": "excellent",
      "missing_required_fields": []
    }
  },
  
  "pipeline_summary": {
    "phases_completed": 4,
    "total_phases": 4,
    "bottleneck_phase": "phase_5_6"
  }
}

Quality Assessment

IRIS provides quality indicators to help you understand the reliability of extracted data:

• overall_confidence: Float between 0.0-1.0 indicating extraction reliability
• quality_level: String classification: "excellent", "good", "fair", or "poor"
• missing_required_fields: Array of required fields that couldn't be extracted
• field_confidence: Individual confidence scores for each extracted field

Quality Level Interpretation

Quality Level	Confidence Range	Recommendation
Excellent	0.8 - 1.0	✅ Use data directly with high confidence
Good	0.6 - 0.8	✅ Use data with minor validation
Fair	0.4 - 0.6	⚠️ Review and validate manually
Poor	0.0 - 0.4	❌ Reprocess or manual entry recommended

Error Handling

Common Error Responses

{
  "success": false,
  "error": {
    "code": "IMAGE_PROCESSING_FAILED",
    "message": "Failed to process image",
    "details": "Image format not supported",
    "retryable": true
  },
  "pipeline_id": "uuid-123-456-789"
}

HTTP Status Codes

• 200 OK: Successful processing
• 400 Bad Request: Invalid input (malformed file, missing parameters)
• 413 Payload Too Large: Image file too large (>10MB limit)
• 422 Unprocessable Entity: Valid request but processing failed
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side processing error
• 503 Service Unavailable: One or more services temporarily down

Error Recovery Strategies

import time
import requests

def process_with_retry(image_path, max_retries=3):
    """
    Process document with automatic retry for transient errors
    """
    for attempt in range(max_retries):
        try:
            with open(image_path, 'rb') as image_file:
                files = {'file': image_file}
                response = requests.post(
                    "http://localhost:8000/process",
                    files=files,
                    timeout=60
                )
            
            if response.status_code == 200:
                result = response.json()
                if result['success']:
                    return result
                elif result.get('error', {}).get('retryable'):
                    print(f"Retryable error, attempt {attempt + 1}: {result['error']['message']}")
                    if attempt < max_retries - 1:
                        time.sleep(2 ** attempt)  # Exponential backoff
                        continue
                else:
                    print(f"Non-retryable error: {result['error']['message']}")
                    return result
            elif response.status_code == 503:
                print(f"Service unavailable, attempt {attempt + 1}")
                if attempt < max_retries - 1:
                    time.sleep(5)
                    continue
            else:
                print(f"HTTP error {response.status_code}")
                return None
                
        except requests.RequestException as e:
            print(f"Request failed, attempt {attempt + 1}: {str(e)}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
    
    print("All retry attempts failed")
    return None

Performance Optimization

Image Preparation Tips

1. Resolution: Optimal range is 1500-3000px on the longer side
2. Format: JPG or PNG recommended (PDF supported but slower)
3. Quality: Avoid over-compressed images (>80% quality)
4. Orientation: Ensure document is right-side up
5. Lighting: Even illumination without shadows or glare

Processing Time Expectations

Document Type	Typical Processing Time	Factors
Simple ID Cards	3-6 seconds	Small text, clear structure
Complex Forms	6-12 seconds	Multiple fields, mixed text
Poor Quality Images	10-20 seconds	Additional preprocessing needed

Batch Processing

For multiple documents, process them individually rather than in batch to optimize memory usage:

import concurrent.futures
import requests

def process_document_batch(image_paths, max_workers=3):
    """
    Process multiple documents concurrently
    """
    results = {}
    
    def process_single(path):
        with open(path, 'rb') as f:
            files = {'file': f}
            response = requests.post("http://localhost:8000/process", files=files)
            return path, response.json() if response.status_code == 200 else None
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = {executor.submit(process_single, path): path for path in image_paths}
        
        for future in concurrent.futures.as_completed(futures):
            try:
                path, result = future.result()
                results[path] = result
            except Exception as e:
                path = futures[future]
                results[path] = {"error": str(e)}
    
    return results

Next Steps

Now that you understand the basics of IRIS IDP:

1. Explore Advanced Features: Learn about phase-by-phase processing for more control
2. Set Up Development Environment: Follow our development setup guide
3. Integrate with Your Application: Check out our API integration examples
4. Optimize for Your Use Case: Review performance optimization techniques

Support and Community

• Documentation: Complete API reference and guides available in this documentation
• GitHub Issues: Report bugs and request features on our GitHub repository
• Community: Join our Discord server for community support and discussions

Ready to start extracting structured data from your documents? Try your first API call now!