KEPLIN Docs

Using AI in scripts

Asking the app's AI models for text, JSON with a set shape and embeddings, sending files, handling errors and knowing what each provider does.

The app's scripts call AI through the SDK's ai module. The script picks the model by the alias name, and the request leaves the platform's server with the provider's credentials. The script never sees the keys.

from api_manager import ai


def main(input):
    r = ai.chat("Resume em três frases: " + input["args"]["texto"])
    return {"resumo": r["text"]}

Before you start

  • The tenant needs an active AI provider with authorised models. See AI providers.
  • The app needs an alias for each use the script asks for. Without model=, the script uses that use's default alias. See App AI models.

What each provider does

Provider Text, JSON and tools Embeddings Images Transcription Speech Batches
OpenAI Yes Yes Yes Yes Yes Yes
Anthropic Yes No No No No Yes
Microsoft Foundry Yes Yes Yes Yes Yes No
Amazon Bedrock Yes Titan and Cohere Nova Canvas, Titan and Stability No No No
Google Cloud Yes Yes Yes Yes Yes Gemini API only
OpenRouter Yes Yes Yes No No No
OpenAI-compatible Yes Depends on the server Depends on the server Depends on the server Depends on the server No

A call to a provider that does not do an operation gives the not_supported error. With any provider, the operation only works with a model that does it: a text model does not generate images.

Tools and batches are in Tools and batches, and images, transcription and speech in Images and audio.

Asking for text

ai.chat sends a request and returns the model's answer:

from api_manager import ai, log


def main(input):
    r = ai.chat(
        "Classifica este pedido de suporte: " + input["args"]["pedido"],
        system="És um assistente de apoio ao cliente. Respondes numa palavra: urgente, normal ou baixo.",
        model="texto",
        max_tokens=10,
        temperature=0,
    )
    log("classificação:", r["text"], r["usage"])
    return {"prioridade": r["text"].strip().lower()}
Parameter What it does
prompt The question.
system The system instruction: the model's role and rules.
messages A conversation, instead of prompt (see A conversation).
model The alias name. Without it, the default text alias applies.
max_tokens The maximum size of the answer. Without it, the alias's value applies, and then the platform's.
temperature From 0 to 2. A low value gives more predictable answers. Without it, the model's value applies.
files Files that go with the question (see Sending files).
stream A name, so that the text appears on the screen of whoever called while the model writes it (see Live answers on screen).

The result is a dict:

Key What it holds
text The text of the answer.
stop_reason Why the model stopped: end, max_tokens, tool_use, refusal or other.
usage The tokens used, in input_tokens and output_tokens.
model, provider, alias Who answered.

A stop_reason of max_tokens means the answer was cut off. Raise max_tokens or ask for a shorter answer.

A conversation

To continue a conversation, pass the history in messages, with the user and assistant roles alternating:

from api_manager import ai


def main(input):
    r = ai.chat(
        messages=[
            {"role": "user", "content": "O meu nome é Ana."},
            {"role": "assistant", "content": "Olá, Ana!"},
            {"role": "user", "content": "Como me chamo?"},
        ],
    )
    return {"resposta": r["text"]}

With both messages and prompt, the prompt goes in as the last user message. The list can also go as the first argument, without messages=: ai.chat([...]).

Asking for JSON with a set shape

ai.json asks for the answer in JSON, validates it against a JSON Schema and returns the JSON already parsed:

from api_manager import ai

ESQUEMA = {
    "type": "object",
    "properties": {
        "nif": {"type": "string", "description": "NIF do cliente, 9 algarismos"},
        "total": {"type": "number", "description": "Total com IVA, em euros"},
    },
    "required": ["nif", "total"],
}


def main(input):
    factura = ai.json(
        "Extrai o NIF do cliente e o total desta factura.",
        schema=ESQUEMA,
        files=[input["args"]["factura"]],
    )
    return factura  # {"nif": "...", "total": 123.45}
  • The schema describes the shape: the types, the required fields and a description for each field. The better the description, the better the answer.
  • An answer that does not match the schema gives the invalid_output error. The script never receives data with the wrong shape.
  • Providers that support structured output receive the schema in the request. The others receive it in the system instruction, and the answer is validated all the same.

Sending files

files= sends app files with the request, in ai.chat and in ai.json. It accepts Upload arguments as they arrive in input["args"], or what files.store returns:

from api_manager import ai, files


def main(input):
    # an Upload argument of an API
    foto = input["args"]["foto"]
    estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])

    # a file the script itself creates
    vendas = files.store(b"produto;quantidade\nCadeira;12\nMesa;30\n", "vendas.csv", "text/csv")
    melhor = ai.chat("Que produto vendeu mais? Responde só com o nome.", files=[vendas])

    return {"estado": estado["text"], "mais_vendido": melhor["text"]}
Type How it goes
PNG, JPEG, GIF and WebP images As an image, for models that see images.
PDF As a document, for models that read PDF.
Text (txt, csv, json, md, xml and yaml) As text, before the question.

Each file can be up to 20 MB, and a request up to 40 MB. A text-only model refuses images and PDF with the invalid_request error.

Embeddings

ai.embed turns text into vectors, to search by meaning and not only by matching words:

from api_manager import ai


def semelhanca(a, b):
    produto = sum(x * y for x, y in zip(a, b))
    normas = (sum(x * x for x in a) ** 0.5) * (sum(y * y for y in b) ** 0.5)
    return produto / normas


def main(input):
    pergunta = ai.embed(input["args"]["pergunta"])  # one vector
    artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
    vectores = ai.embed(artigos)  # one vector por texto
    melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
    return {"artigo": artigos[melhor]}

One text returns one vector. A list returns a list of vectors, in the same order, up to 2048 texts per call. Without model=, the default embeddings alias applies.

The app's aliases

ai.models() returns the app's aliases, each with its name, use, default mark, provider and model. A script can use it to choose the model while it runs, or to explain why an alias is missing.

Errors

A call that fails raises ai.Error. The code attribute is the same for every provider, and the message says what happened:

from api_manager import ai, log


def main(input):
    try:
        r = ai.chat(input["args"]["pergunta"])
    except ai.Error as e:
        log("IA:", e.code, str(e))
        if e.code in ("rate_limited", "unavailable", "timeout", "connection"):
            return {"tentar_mais_tarde": True}
        raise
    return {"resposta": r["text"]}
Code What it means
not_configured The alias is missing, the provider is disabled or the model is no longer authorised.
rate_limited The provider refused because of too many requests.
timeout The provider did not answer within the maximum time.
unavailable, connection The provider is down or could not be reached.
auth, permission The key was refused or does not have permission.
invalid_request The request is not valid for this provider or model.
invalid_output The answer's JSON does not match the schema.
refused The model refused to answer.
not_supported The provider does not do this operation, or the file is of a type that cannot be sent.
cancelled The run ended before the answer.
max_steps ai.run reached the maximum number of steps without a final answer.
not_found, unknown The model or the address does not exist, or another error happened.

Time limit and logs

  • An answer can take tens of seconds. The script's Time limit has to be enough for all the calls: in a script with several, raise it.
  • When the run ends, because of the time limit or a cancellation, the requests still waiting are cancelled at the provider.
  • Each call writes a line in the run's logs, with the alias, the model and the duration, for example [ai] texto (local/qwen2.5:0.5b): 1840 ms.
  • The platform does not store the text of the requests or the answers, unless the app turns on debugging (see App AI models). The request goes to the app's AI provider, so do not send it personal data without need.

Frequently asked questions

Can I use AI from a widget or from the browser? No. AI exists only in scripts, which run on the server, so the keys never reach the browser. A screen that needs AI calls an API that runs a script.

The script says not_configured and the alias exists. Check that the alias is for the right use (an embeddings alias does not work for ai.chat), that the provider is active and that the model is still authorised in it.

Can I use the OpenAI or Anthropic library directly? You can install it through the pip panel, but the key would have to live in an app secret, and the script would lose the aliases and the common error codes. The ai module exists for that.