Put Ana Inside Your Own Product with the TextQL SDK

TextQL's intelligence lives on TextQL — a separate screen your users have to leave your product to reach. The SDK puts Ana, TextQL's analyst, inside your own product instead.

You could build against TextQL's API yourself, but then you own the hard parts: keeping your API key out of the browser, streaming, access control. The SDK is those parts, already solved.

What you can do with it

Embedding takes Ana and places it directly inside a page of your own product, instead of linking users out to TextQL. It runs as part of your app, under your branding and access control, so a support widget, an admin panel, or a customer dashboard can have a real analyst living inside it. It's two pieces. On your server, one route holds your API key and checks who's allowed in:

// server: app/api/textql/[...path]/route.ts
import { createEmbedHandler } from '@textql/sdk/embed';

export const { GET, POST } = createEmbedHandler({
  authorize: async (request) => (await getSession(request)) !== null,
});

// frontend
import { TextqlApp } from '@textql/sdk/embed/react';

export default function Page() {
  return <TextqlApp style={{ height: '80vh' }} />;
}

Streaming is useful for when you want to build your own chat interface instead of using the prebuilt embed. You call Ana from your backend and render the results yourself. When streaming, Ana's answers shows result cells and text as they're produced.

const created = await client.chats.createChat({
  body: {
    /* model, paradigm */
  },
});
const chatId = created.chat!.id!;

await client.chats.send({ body: { chatId, message: 'What drove churn last quarter?' } });

for await (const event of streaming.chats.watchChat({ chatId })) {
  if (event.payload.case === 'cell') render(event.payload.value);
  if (event.payload.case === 'runComplete') break;
}

Self-hosting is used for customers whose data legally can't leave their own infrastructure like banks, healthcare, government. Point the SDK at a TextQL instance running on their servers, and nothing touches a TextQL origin.

TEXTQL_SERVER_URL=https://textql.internal.example.com

Getting started

Install one package:

npm install @textql/sdk      # TypeScript — embedding & streaming
pip install textql-sdk       # Python — backend scripting

Reach for the TypeScript SDK to embed or stream, and the Python client for backend scripting. (You may find an older textql package on PyPI. It's Alpha and largely inactive — use textql-sdk.)

From there the docs take each path in turn. Embedding is the most common, and the shortest: two values on your server, one route, one tag.

Full reference: TypeScript SDK docs, Python SDK docs.