AI

mash.ai · AI

mash.ai is for scripts that call a language model or work with text on its way to one. Most automations never need it. Reach for it to summarise a document, pull structured data out of free text, or prepare text for a model. It reaches AI services you name, so it needs a key for the provider you use, and every call is checked like any other outside request.

How it works

Four parts.

Part	What it’s for
`mash.ai.lll`	chat with a model, make embeddings, build questions-and-answers over your own documents
`mash.ai.splitters`	cut long text into pieces a model can take (by characters, by Markdown or HTML headings, or JSON)
`mash.ai.ocr`	turn Captur’s word-position data (miniOCR) into plain text, or into a layout a model reads well
`mash.ai.tokeniser`	count tokens, to stay inside a model’s limit

mash.ai.client() builds a client for any OpenAI-compatible service.

A provider needs a configuration. mash.ai.lll.config("anthropic", {apiKey: ..., model: ...}) describes the provider. mash.ai.lll.chat(config) turns it into a chat client, and chat.generateText("your prompt") returns the model’s reply as text. Keep the key in the script’s config (mash.config.get), never in the script text.

Destinations are checked. The address of every service a script names is validated as for mash.http, so a script can’t point a model client at your internal network.

AI use is metered. On Foldr Cloud, calls from scripts draw on the tenant’s AI credits.

Common tasks

Ask a model a question about some text:

set config to mash.ai.lll.config("anthropic", {
    apiKey: mash.config.get("ANTHROPIC_KEY"),
    model: mash.config.get("MODEL")
})
set chat to mash.ai.lll.chat(config)
set reply to chat.generateText("Summarise in one sentence: " ~ mash.files.get("Contracts", "note.txt").contents)
printline reply

Cut a long document into pieces:

set splitter to mash.ai.splitters.recursiveCharacter(1000, 100)
set pieces to splitter.splitText(mash.files.get("Contracts", "long-note.txt").contents)
printline "{{count(pieces)}} pieces"

Get plain text out of a scanned page’s search result:

set hit to mash.search.execute("Scans", "invoice").results.first()
printline mash.ai.ocr.text(hit.hocr)

Watch out for

Keys belong in config. A key typed into a script is visible to everyone who can open the script.
A model’s answer is text, not fact. Check anything a script will act on, such as a total or a date, before it writes a field.
Long inputs cost more and can fail. Split long text, and count tokens with the tokeniser.
Save the cost where you can. Don’t call a model on every event when a field or a filter would do the job.
Check a provider works before you build on it. Run one trial call and read the reply.

Properties

Name	Type	Description
`lll`		Library for interacting with Large Language Models
`ocr`		OCR processing and miniOCR format conversion
`splitters`		Split text for AI processing
`tokeniser`

Methods

client

ai.client() → OpenAIFactory

The OpenAI client builder. Its base URI and every request the client sends go through the destination guard; see OpenAIFactory.

AI