insideai

Python client for the InsideAI API.

pip install insideai

Quickstart

import os

from insideai import InsideAI, create_chat, wait_for_chat

iai = InsideAI(api_key=os.environ["INSIDEAI_API_KEY"])

chat = create_chat(iai, "Summarize last quarter's findings.")
print(wait_for_chat(iai, chat["id"])["answer_text"])

InsideAI(...) holds your key, base URL and a pooled HTTP session. Build it once and pass it as the first argument to everything else.

InsideAI answers asynchronously, so create_chat returns straight away. wait_for_chat polls for you; call get_chat yourself if you would rather drive the loop (a job queue, a webhook, a UI that shows progress).

Examples

Complete, runnable scripts ship in the source distribution under examples/, and are the fastest way to see the shape of an integration:

export INSIDEAI_API_KEY=iaiak_…
python examples/ask_a_question.py "What changed this week?"

API keys

Keys never expire and are revoked from the InsideAI admin UI. They come in two kinds:

• Client-wide — acts as your organization's API service account, and may act as any member of your org by passing act_as=<their email>.
• User-specific — always acts as one person. Passing act_as to one of these is an error rather than a silent no-op, so a misconfigured integration fails loudly.

me(iai)  # the service account
me(iai, act_as="alice@example.com")  # Alice, with Alice's permissions

Acting as someone means exactly that: their org, their permissions, their row-level access, and anything created shows up in their own InsideAI history. You can only act as an active member of the key's organization.

Never send a key to a browser. For embedded chat, mint a one-time code server-side with embed_session and hand that to the frontend — see examples/embed_session_endpoint.py and @cpcyber/insideai.

Functions

Every function takes the client first and an optional act_as=.

answer_text is the answer flattened to plain text. answer_blocks is the original display-block list ({display, params}) if you want to render charts and images yourself.

Errors

InsideAIError for anything that isn't a 2xx, carrying .status and .payload. Two subclasses are worth catching on their own: InsideAIAuthError for 401/403 — a rejected key never becomes valid on a retry — and InsideAITimeoutError when wait_for_chat gives up on a chat that is still being answered. GETs retry twice on connection failures and 502/503/504; nothing else is retried, since a 4xx is an answer.

from insideai import InsideAIAuthError, InsideAIError

try:
    chat = create_chat(iai, "hello")
except InsideAIAuthError:
    ...  # key revoked, or acting as someone you may not
except InsideAIError as exc:
    log.warning("InsideAI %s: %s", exc.status, exc.payload)

Other environments

base_url defaults to production. Point it elsewhere if InsideAI gave you a different endpoint:

iai = InsideAI(api_key=..., base_url="https://your-insideai-endpoint/")

Layout

Import everything from the package root — from insideai import create_chat — which is the surface this package keeps stable. Underneath: