odoo_ocr/.agents/skills/odoo-xml-import/SKILL.md

name, description

name	description
odoo-xml-import	Use this skill when generating, validating, or modifying Odoo Enterprise XML import files from extracted invoice data in the odoo_ocr project.

Odoo XML Import Skill

Use this skill whenever you need to produce Odoo XML from the ExtractedInvoice schema.

Target Format

Generate standard Odoo data-import XML:

<?xml version="1.0" encoding="UTF-8"?>
<odoo>
  <data>
    <record id="vendor_x" model="res.partner">
      <field name="name">...</field>
      <field name="supplier_rank">1</field>
    </record>

    <record id="invoice_123" model="account.move">
      <field name="move_type">in_invoice</field>
      <field name="partner_id" ref="vendor_x"/>
      <field name="invoice_date">2024-05-01</field>
      <field name="date">2024-05-01</field>
      <field name="invoice_date_due">2024-06-01</field>
      <field name="ref">INV-123</field>
      <field name="currency_id" ref="base.USD"/>
      <field name="narration">...</field>
    </record>

    <record id="invoice_123_line_1" model="account.move.line">
      <field name="move_id" ref="invoice_123"/>
      <field name="name">Product A</field>
      <field name="quantity">2</field>
      <field name="price_unit">100.00</field>
      <field name="tax_ids" eval="[(6, 0, [ref('tax_15')])]"/>
    </record>

    <record id="tax_15" model="account.tax">
      <field name="name">VAT 15%</field>
      <field name="amount">15</field>
      <field name="amount_type">percent</field>
      <field name="type_tax_use">purchase</field>
    </record>
  </data>
</odoo>

See templates/invoice_import.xml for a full template.

Required Records

Every XML file must create or reference:

1. Vendor (res.partner)

   • name (required)
   • supplier_rank = 1
   • optional: vat, street, city, zip, country_id

2. Vendor Bill (account.move)

   • move_type = in_invoice
   • partner_id ref to vendor record
   • invoice_date (required)
   • date (defaults to invoice_date)
   • invoice_date_due (optional)
   • ref = invoice number
   • currency_id (defaults from settings; map common ISO codes to base.* refs)
   • narration = summary / payment terms (optional)

3. Invoice Lines (account.move.line)

   • One record per line_items entry.
   • move_id ref to vendor bill.
   • name = line description.
   • quantity, price_unit (decimal strings).
   • tax_ids eval with refs to existing or newly created tax records.
   • Do not set debit/credit directly; Odoo will compute them from price_unit × quantity.

4. Taxes (account.tax)

   • Create only if the tax does not already exist.
   • Use deterministic external ID based on rate and type, e.g., purchase_vat_15.
   • name, amount, amount_type='percent', type_tax_use='purchase'.

External ID Rules

• Sanitize IDs: lowercase, replace non-alphanumeric with _, strip leading digits.
• Vendor ID: vendor_<sanitized_name>_<hash> or use VAT if present.
• Invoice ID: invoice_<sanitized_number>_<date> with hash if needed for uniqueness.
• Tax ID: purchase_vat_<rate>.

Validation Rules

1. Parse generated XML with lxml.etree.
2. Ensure required fields are present and non-empty.
3. Warn if sum(line totals) + tax != total beyond rounding tolerance (0.01).
4. If human_review_required flag is set, add an XML comment or metadata record documenting this.

Implementation Location

All XML logic lives in src/odoo_ocr/pipeline/xml_builder.py and src/odoo_ocr/schemas/odoo_xml.py.

Currency Mapping

Maintain a hardcoded fallback map from ISO code to base.<code> for common currencies (EUR, USD, GBP, CHF). If a currency is not in the map, create a res.currency record or default to settings.

Testing

• Test XML generation against a known-good sample in tests/fixtures/expected_invoice.xml.
• Validate that generated XML is parseable and contains the required records.