Schema: ai_invoice_processor

Technical Truth - Models, API endpoints, and data structures

Module Overview

Models

ai.invoice.config (Primary Model)

Purpose: Stores configuration for AI invoice processing including OpenAI API settings, email server credentials, and processing preferences.

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| test_openai_connection() | Test OpenAI API connectivity | Notification action |
| test_email_connection() | Test IMAP email connection | Notification action |
| update_statistics() | Update processing stats | None |
| get_active_config() | Get first active config | ai.invoice.config record |
| cron_reset_daily_stats() | Reset daily counters, cleanup old logs | None |
| cron_health_check() | Check API and config health | None |

Relationships:
- default_expense_account_id → account.account (Many2one)
- default_currency_id → res.currency (Many2one)
- processing_log_ids → ai.processing.log (One2many)

ai.processing.log

Purpose: Tracks each invoice processing attempt with status, extracted data, errors, and created records.

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| reprocess_invoice() | Retry failed extraction | Notification action |

Relationships:
- config_id → ai.invoice.config (Many2one)
- created_invoice_id → account.move (Many2one)
- supplier_id → res.partner (Many2one)

invoice.extractor

Purpose: AI-powered invoice data extraction engine using GPT-4 Vision. Handles universal extraction without supplier-specific templates.

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| extract_invoice_data(pdf_content, supplier_id) | Universal AI extraction | dict of invoice data |
| create_supplier_invoice(extracted_data, pdf_attachment) | Create Odoo invoice | account.move record |
| _extract_with_gpt4_vision() | GPT-4 Vision extraction | dict or None |
| _extract_with_ocr_llm() | Fallback OCR + LLM | dict or None |
| _pdf_to_image() | Convert PDF to base64 image | string |
| _build_universal_prompt() | Generate AI extraction prompt | string |
| _standardize_extracted_data() | Normalize extracted data | dict |
| _find_or_create_supplier() | Match or create partner | res.partner record |

supplier.invoice.processor

Purpose: Main orchestrator that ties email monitoring and invoice creation together. Called by scheduled actions.

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| process_email_invoices() | Main processing loop (called by cron) | None |
| cron_manual_test() | Manual test runner | bool |
| _fetch_invoice_emails() | Get emails with PDF attachments | list of dicts |

Scheduled Actions (Cron Jobs)

Data Relationships Diagram

┌─────────────────────────────┐
│   ai.invoice.config         │
│                             │
│  - name                     │
│  - openai_api_key           │
│  - email_server/credentials │
│  - processing settings      │
│  - statistics               │
└──────────┬──────────────────┘
           │
           │ One2many (processing_log_ids)
           ▼
┌─────────────────────────────┐
│   ai.processing.log         │
│                             │
│  - config_id (M2O)          │◄────────────────┐
│  - email_subject            │                 │
│  - status                   │                 │
│  - extracted_data (JSON)    │                 │
│  - error_message            │                 │
└──────────┬──────────────────┘                 │
           │                                    │
           │ Many2one                           │
           ▼                                    │
┌─────────────────────────────┐    ┌───────────┴───────┐
│   account.move              │    │   res.partner     │
│   (Odoo Invoice)            │    │   (Supplier)      │
│                             │    │                   │
│  - created_invoice_id       │    │  - supplier_id    │
└─────────────────────────────┘    └───────────────────┘

Security Rules

res.config.settings (Transient - Inherits)

Purpose: Adds quick setup fields to Odoo Settings for AI Invoice configuration.

File: models/ai_invoice_config.py

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| get_values() | Load values from active ai.invoice.config | dict |
| set_values() | Save values to ai.invoice.config (creates if needed) | None |

EmailInvoiceMonitor (Standalone Python Class - NOT an Odoo Model)

Purpose: Standalone email monitoring daemon that runs outside Odoo's ORM. Monitors inbox and creates invoices via XML-RPC.

File: models/email_monitor_processor.py

Usage: Run as standalone script or import the class.

Orphan Security Rules (Models Don't Exist)

The following models are defined in ir.model.access.csv but do not exist in the codebase:

Database Tables

External API Integration

OpenAI GPT-4 Vision API

Endpoint: https://api.openai.com/v1/chat/completions

Request:

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "<extraction prompt>"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "data:image/jpeg;base64,<image_data>"
                    }
                }
            ]
        }
    ],
    "max_tokens": 2000,
    "temperature": 0.1
}

Response (extracted data):

{
    "vendor_name": "ACME Corp",
    "vendor_vat": "US123456789",
    "invoice_number": "INV-2025-001",
    "invoice_date": "2025-01-15",
    "due_date": "2025-02-15",
    "currency": "USD",
    "total_amount": 1500.00,
    "total_untaxed": 1250.00,
    "total_tax": 250.00,
    "line_items": [
        {
            "description": "Consulting Services",
            "quantity": 10,
            "unit_price": 125.00,
            "total": 1250.00
        }
    ]
}

Change History