SDKs

Official Python and Node.js libraries for the Aivana API.

Aivana has two official SDKs, one for Python and one for Node.js. They are convenience layers over the same Aivana API: they call the same endpoint and send the same request for the same call, so choose by language. Both are small, typed clients with streaming, conversations and clear errors built in.

The Python SDK needs Python 3.10 or newer. The Node.js SDK needs Node.js 18 or newer, has no dependencies, and also runs on Deno, Bun and edge runtimes.

Your API key is the only required setting. Read it from the environment rather than writing it into your code.

import os
import aivana

aivana.api_key = os.environ["AIVANA_API_KEY"]

res = aivana.generate("Should we enter the EU market in 2027?")
print(res.answer)

The response also carries usage and a finish_reason; Responses & Usage describes every field.

It also carries notices, which you can show to your user as they are. See Responses & Usage.

Streaming shows the answer as it's written. It matters most for long answers, because the non-streaming call waits for the complete response.

for chunk in aivana.generate("Explain the CAP theorem", stream=True):
    print(chunk.delta, end="", flush=True)

If you stop reading a stream before it ends, the request is charged for its prompt and the part of the answer you received. If we cut an answer short on our side, for example because it ran out of time, the request isn't charged and you keep the part you received; its finish reason is length. The done event that ends a stream carries the same notices as a response.

The Generate API is stateless. For multi-turn experiences, send prior messages with each request or use the SDK's Chat helper to manage conversation history in your application. A chat keeps the history for you and sends it with each new question, and the options you give it apply to every turn.

chat = aivana.Chat(system="You are a support lead. Three bullets maximum.")
chat.send("A customer wants a refund after 40 days.")
chat.send("They're now threatening a chargeback.")  # remembers the above

Every option is optional, and Python spells them in snake_case, Node.js in camelCase. The options are the API's own, defined once on Parameters: effort, web_search, system, max_tokens, temperature, stop_sequences, output_shape, response_format, attachments and intelligence_trace. For files, Files & Documents lists what the API accepts and shows how to attach a file with each SDK.

Every failure raises (Python) or throws (Node.js) a subclass of AivanaError, carrying a code, a message and the request id. Quote the request id when you contact support. Errors & Retries lists the API's status codes and how to retry.

• AuthError: a missing, invalid or expired API key (401).
• ForbiddenError: the key isn't allowed to do this (403).
• RateLimitError: too many requests; wait, then retry (429).
• InvalidRequestError: something in the request is wrong (400 or 422). Its details say which field.
• UpstreamError: Aivana couldn't complete the answer; it's safe to retry, and you aren't charged for it (502).
• An empty credit balance arrives as an AivanaError with the code insufficient_credit (402).

from aivana import RateLimitError

try:
    res = aivana.generate("Summarize our Q3 churn drivers.")
except RateLimitError as err:
    print("Slow down:", err.message, err.request_id)

Each package's page on PyPI and npm has the complete reference. Prefer the terminal? The Command Line is built on these SDKs and needs no code.