Manual · API

# `ai`

A model answers — Apple Intelligence on the Mac by default, or a provider you configure. Synchronous like everything else.

Every command on this page carries a worked example.

###
use function

`ai.use(provider, { key, model })`

Chooses the model: `"apple"` (on the Mac, the default), `"anthropic"`, `"openai"` or `"custom"`.

Worked example

    const state = language.canTranslate("de", system.language);
    if (state === "needsDownload") {
        messages.alert("macOS will download the language once — the first translation "
                       + "takes a moment.");
    }

###
isAvailable function

`ai.isAvailable()`

Whether the chosen model can answer right now — ask before promising a feature.

Worked example

    // Apple on the Mac is the default; a provider is one line:
    ai.use("anthropic", { key: security.loadSecret("apiKey") });

###
availability function

`ai.availability()`

The reason, as text, when it cannot.

Worked example

    form.suggestButton.enabled = ai.isAvailable();

###
ask function

`ai.ask(question, { instructions }) → text`

One question, one text back.

Guard with `ai.isAvailable()` and fall back gracefully — a feature that needs a model should degrade, not dialog-error. For fields, prefer `extract`: shapes beat prose.
Worked example

    if (!ai.isAvailable()) {
        form.stateLabel.value = ai.availability();   // says why, in words
    }

###
extract function

`ai.extract(text, shape) → object`

Structured answers: name the fields and their kinds, get an object.

Name the shape tightly — three fields you need beat ten you might. What comes back fits the fields of a record assignment directly.
Worked example

    // Turn a pasted mail into a record's fields:
    const parsed = ai.extract(pastedText, {
        company: "text",
        amount: "number",
        dueDate: "date"
    });
    form.record.company = parsed.company;

###
classify function

`ai.classify(text, [labels]) → one label`

Which of your labels fits the text best.

Worked example

    const label = ai.classify(form.record.note,
                              ["complaint", "order", "question", "praise"]);
    form.record.category = label;