Projects provide a systematic way to test and validate your extraction schemas against known ground truth data. Think of it as unit testing for document AI—you can measure accuracy, compare different models, and optimize your extraction pipelines with confidence. A project consists of documents with annotations (your test data), iterations (test runs with different settings), and a schema (what you want to extract). This structure lets you run A/B tests between models and systematically improve your document processing accuracy.

​
How it works

  1. Create an project with your extraction schema
  2. Upload test documents with manually verified ground truth annotations
  3. Run iterations with different model settings (GPT-4o vs GPT-4o-mini, consensus, etc.)
  4. Compare results to find the optimal configuration for your use case
Retab automatically calculates accuracy metrics by comparing each iteration’s output against your ground truth annotations, giving you objective performance measurements.

​
Schema Optimization Through Projects

One of the most powerful features of projects is schema refinement. When you see poor accuracy on specific fields, you can:
  • Improve descriptions: Make field descriptions more specific and unambiguous
  • Add reasoning prompts: Use X-ReasoningPrompt for complex calculations or logic
  • Refine field types: Adjust data types based on extraction patterns
{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "description": "The amount"
    },
    "date": {
      "type": "string", 
      "description": "The date"
    }
  }
}
The project workflow for schema optimization:
  1. Run initial project → identify low-accuracy fields
  2. Refine descriptions and add reasoning prompts → re-run project
  3. Compare accuracy improvements → iterate until satisfied
  4. Deploy optimized schema to production

​
Quick Start

While you can create projects programmatically with the SDK, we recommend using the Retab platform for project management. The web interface provides powerful schema editing tools, visual result comparisons, and collaborative features that make optimization much easier.
Let’s create an project for invoice processing: 
from retab import Retab

client = Retab()

# Define what you want to extract
invoice_schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "total_amount": {"type": "number"},
        "vendor_name": {"type": "string"},
        "invoice_date": {"type": "string"}
    },
    "required": ["invoice_number", "total_amount", "vendor_name"]
}

project = client.projects.create(
    name="Invoice Processing Test",
    json_schema=invoice_schema
)

​
Key Benefits

  1. Objective Measurement: Get precise accuracy scores instead of subjective assessments
  2. Model Comparison: Test GPT-4o vs GPT-4o-mini vs consensus to find the best fit
  3. Schema Validation: Identify which fields are hardest to extract accurately
  4. Cost Optimization: Balance accuracy against processing costs for your use case

​
Best Practices

  • Diverse Test Data: Include various document formats, qualities, and edge cases
  • Sufficient Volume: Use at least 10-20 test documents for reliable metrics
  • Regular Testing: Re-run projects when updating schemas or switching models
  • Ground Truth Quality: Double-check your annotations—bad ground truth leads to misleading results

​
Integration

Projects work seamlessly with other Retab features:
  • Test Reasoning prompts to improve calculation accuracy
  • Validate Processor configurations before production deployment
  • Use Consensus in iterations for higher reliability
Please check the API Reference for complete method documentation.