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:

Phase 1: Image preprocessing and geometric correction (unwarping)
Phase 2: ML-powered embeddings generation and automatic clustering
Phase 3-4: Intelligent document classification using deep learning
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

Resolution: Optimal range is 1500-3000px on the longer side
Format: JPG or PNG recommended (PDF supported but slower)
Quality: Avoid over-compressed images (>80% quality)
Orientation: Ensure document is right-side up
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:

Explore Advanced Features: Learn about phase-by-phase processing for more control
Set Up Development Environment: Follow our development setup guide
Integrate with Your Application: Check out our API integration examples
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!

What is IRIS?​

Quick Start​

Prerequisites​

Your First API Call​

Supported Document Types​

📄 Identity Documents​

🏠 Residence Forms​

🏢 Government Forms​

Integration Examples​

Python Integration​

JavaScript/Node.js Integration​

cURL Examples​

Basic Document Processing​

Process with Specific Document Type​

Process with Custom Configuration​

Understanding the Response​

Response Structure​

Quality Assessment​

Quality Level Interpretation​

Error Handling​

Common Error Responses​

HTTP Status Codes​

Error Recovery Strategies​

Performance Optimization​

Image Preparation Tips​

Processing Time Expectations​

Batch Processing​

Next Steps​

Support and Community​