AI Activities

Version: 1.0.0  ·  ID: zoan-packages-ai  ·  Author: Zoan Software

The AI package calls a large language model (LLM) from a playbook. Use it for what fixed rules can’t cover: reading a document whose layout changes from one supplier to the next, classifying an email by intent, summarising a long text, or extracting specific fields from a document without writing one regular expression per template.

How this package works

• No session: each activity takes the credential and makes its call. There is nothing to open or close.
• The credential holds the provider’s API key, like any other Zoan Cloud credential. Never write the key into the playbook.
• The provider is chosen per activity with the provider parameter. Anthropic (Claude) is available today; the package is built so others can be added without touching existing playbooks.
• You pay per token, not per call: cost grows with the size of the document you send and the answer you ask for.

Which activity to use

The difference between the two activities is not the model — it is the shape of the answer.

Activity	Type	Output	Use it when
AI Complete	ai-complete	string	You want text: a summary, a draft, an answer to a question.
AI Extract	ai-extract	object	You want fields: serial number, date, amount, brand. The answer arrives as an object.

If you are about to run regular expressions over the answer to pull data out of it, the activity you want is AI Extract.

Schema-guaranteed extraction

AI Extract does not ask for the format in the prompt: it takes a JSON Schema and the model is required to answer in exactly that shape. That changes two things in production:

• Nothing to parse and nothing to validate: the answer comes back as an object with its fields.
• No retries for malformed JSON, which is the usual failure when the format is requested in the prompt and the model ignores it one time in a hundred.

The description of each field in the schema is part of the prompt: the model reads it to decide what belongs there. A field described as “the equipment’s serial number” is filled far more reliably than one simply named serial.

Scanned documents

Both activities accept images as well as text. For a scanned PDF you have two routes:

• Text first (recommended for large batches): run the scan through the OCR package and send the resulting text. It costs fewer tokens and the result traces back to what the OCR actually read.
• Image directly: render the pages with PDF To Images and pass them in images. It costs more tokens but does not depend on OCR quality.

If the PDF does have a text layer, use PDF Get Text and skip both.

A typical flow

Read an invoice and extract its data as fields:

PDF Get Text   path = = invoicePath   → output: text
AI Extract     credential = anthropic-key   prompt = = text   schema = {…}   → output: invoice
Log            message = = "Invoice " + invoice["number"] + " for " + invoice["total"]

Next steps

• AI Extract — extract fields from a document (the common case).
• AI Complete — free-form text answers.
• OCR — read scanned documents before extracting.