AI Model & Extraction Modes

Choosing an AI Model

The Assistant Config section lets you choose which AI model processes your documents and how it behaves.

Supported AI Providers

Writing Effective Instructions

The Instructions field is the most important configuration in your template. Write clear, specific directions for the AI:

Good example:

You are a Thai tax invoice data extraction assistant.
 
Extract all fields from the invoice exactly as they appear. Follow these rules:
- Dates must be in YYYY-MM-DD format. Thai Buddhist Era (B.E.) dates should be converted to C.E. (subtract 543).
- All monetary values must be numbers without commas or currency symbols.
- If a field is not present in the document, return null for that field.
- For vendor and customer tax IDs, extract the 13-digit Thai tax identification number.
- Line items should include every row in the items table, even if quantities are unclear.

Avoid vague instructions like:

Extract the invoice data.

Instruction Writing Tips

1. State the document type — Tell the AI what kind of document it is processing.
2. Specify output rules — Date formats, number formats, null handling.
3. Handle edge cases — What should the AI do when a field is missing or ambiguous?
4. Language guidance — If documents are in Thai, mention it. Tell the AI whether to translate or preserve original text.
5. Validation rules — "The total_amount must equal subtotal + vat_amount."

Temperature and TopP

These parameters control AI output randomness:

For document extraction, always use a low temperature (0.1 to 0.3). High temperature causes the AI to "hallucinate" field values that are not in the document.

Extraction Modes

Ocriva supports two extraction modes that control how the AI returns results.

Structured Mode

The AI returns a JSON object matching your defined schema exactly. This is the default and recommended mode for most use cases.

When to use Structured Mode:

• You need machine-readable data for a database or API
• You want consistent field names across all processed documents
• You are using JSON, CSV, XML, or DOCX output formats
• You need to compare or aggregate data from multiple documents

How it works: The AI is given your JSON Schema and instructed to fill it with values found in the document. Missing fields return null. The output is always valid JSON matching your schema shape.

Free Text Mode

The AI returns a plain text response without any schema constraints. This is equivalent to asking the AI to summarize or describe the document in natural language.

When to use Free Text Mode:

• You need a human-readable summary
• The document structure is unpredictable
• You are generating narrative descriptions rather than data
• You are using the text or html output format

How it works: The AI processes the document with only your instructions as guidance. The response is unstructured text.

How Result Format Affects Extraction Mode

The output format you select automatically determines the extraction mode. Formats that require a defined schema use Structured Mode; formats that produce free-form output use Free Text Mode.

Structured formats (JSON, CSV) require you to define a schema — a list of fields and their types. The AI reads the document and fills each field with the value it finds. This produces consistent, machine-readable output every time.

Free Text formats (Text, PDF, DOCX, XML, HTML) do not require a schema. You provide instructions, and the AI generates content freely based on what it finds in the document. Even though XML is traditionally considered a structured format, Ocriva uses Free Text mode for XML output because the AI generates the XML markup from your instructions rather than mapping values to a predefined schema.

Choosing Between Modes

Use Structured Mode when you need the same fields extracted from every document — for example, processing invoices where you always need invoice_number, date, and total_amount. The schema enforces consistency and makes downstream processing predictable.

Use Free Text Mode when documents vary too widely for a consistent schema, or when you need the AI to produce summaries, translations, or narrative descriptions rather than filling discrete fields.

Starting recommendation: Begin with JSON format and Structured Mode for most use cases. Switch to Free Text only when your documents are too varied for a consistent schema, or when the output is meant for human reading rather than machine processing.