SDKs

AI Setu ships four packages to npm under the @ai-setu scope. Each targets a different surface — pick the one that matches what you're building, not the one you happen to install first.

Two base URLs, two different jobs — don't mix them up:

• https://gateway.aisetu.ai/v1 — the gateway. Inference only: /chat/completions, /embeddings, etc. @ai-setu/client points here.
• https://api.aisetu.ai — the control plane. Workspaces, API keys, billing, PATs, BYOK Connections — GraphQL under /graphql. @ai-setu/admin, @ai-setu/cli, and @ai-setu/mcp all point here.

Every package resolves its base URL itself (env var override, then a production default) — you don't construct these URLs by hand in normal use. All four currently publish at version 0.20.1.

@ai-setu/client — runtime inference

Drop-in replacement for the openai SDK, pointed at the AI Setu gateway. The constructor and the model string are the only differences for the surfaces the gateway serves.

The openai SDK exposes more methods than the gateway routes, so be precise about which ones reach us:

responses reaches only the OpenAI-compatible providers (openai, bedrock-mantle, groq, xai, deepseek, mistral); Anthropic, Gemini, Bedrock and Vertex have no Responses surface and are rejected with a clear error. Note also that the semantic cache and per-tool cache policies do not apply on that route — see Caching.

npm i @ai-setu/client
export AI_SETU_API_KEY=tt_live_…

import { AiSetu } from '@ai-setu/client';

const client = new AiSetu(); // reads AI_SETU_API_KEY from env
const res = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'hi' }],
});
console.log(res.choices[0].message.content);

Auth: a workspace API key (shape tt_live_…, minted via @ai-setu/admin, @ai-setu/cli, or the MCP onboarding flow) in AI_SETU_API_KEY, or new AiSetu({ apiKey }).

Model routing: model carries a provider/model prefix for the platform key (openai/gpt-4o-mini, anthropic/claude-sonnet-4-5) or a @<slug>/model prefix to route through one of your own BYOK Connections (@azure-qdc/gpt-4o-mini). Pin one Connection for the whole client with new AiSetu({ connection: '@azure-qdc' }).

Main surface:

• client.chat.completions.create(...), client.embeddings.create(...) — every OpenAI SDK method, including stream: true + for await.
• client.lastBalance / onBalanceUpdate — the gateway stamps a credit balance on every response; read it synchronously or subscribe.
• client.lastRouting / onRouting — confirms, per response, whether your own BYOK key served (byok: true) or the platform key did.
• client.prompts.render(ref, variables) — render a managed prompt template server-side (no inference call).
• Error tree re-exported from openai (AuthenticationError, RateLimitError, APIError, …) plus AI-Setu-specific type guards — isInsufficientCreditsError(err), isCredentialCapExceededError(err), isProviderError(err) — for branching on wesence.* error codes without waiting on subclasses.
• getSharedDispatcher() / setSharedDispatcher() — the process-wide keep-alive undici pool, shareable with @ai-setu/admin.

Base URL defaults to https://gateway.aisetu.ai/v1; override with AI_SETU_BASE_URL or new AiSetu({ baseUrl }) (normalized to end in /v1).

@ai-setu/admin — control-plane SDK

Agent- and script-friendly TypeScript wrapper over the control-plane GraphQL API. Same env-var-first, one-import ergonomic as @ai-setu/client.

npm i @ai-setu/admin
export AI_SETU_PAT=tt_pat_…

import { AiSetuAdmin } from '@ai-setu/admin';

const admin = new AiSetuAdmin(); // reads AI_SETU_PAT from env
const workspaces = await admin.workspaces.list();
const key = await admin.apiKeys.create({ workspaceId: workspaces[0].id, name: 'CI' });
console.log('secret shown once:', key.secret);

Auth: a Personal Access Token (shape tt_pat_…, scoped admin:read or admin:write) in AI_SETU_PAT, or new AiSetuAdmin({ pat }). This is a different credential from the tt_live_… workspace key @ai-setu/client uses — a PAT cannot call inference, and a workspace key cannot manage workspaces.

Main surface (every method also takes an optional trailing AbortSignal):

• admin.workspaces — listPage({ first, after, search }), iterate(), createMany(items, { createKey }) (bulk backfill, batches of 100, idempotent on slug), get(id), create(input), rename(id, input), delete(id), listMembers(workspaceId); list() is deprecated (capped at 1,000 rows)
• admin.apiKeys — list(workspaceId), create(input), rotate(keyId), revoke(keyId)
• admin.members — invite(...), setRole(...), remove(workspaceId, userId)
• admin.billing — creditBalance(tenantId), createTopUpIntent(tenantId, input), createTopUpCheckoutSession(tenantId, input), createBillingPortalSession(...), topUps(tenantId, limit?)
• admin.usage — projection(tenantId) (avg/day, month-to-date, projected month-end)
• admin.pats — list(), create(input), revoke(patId)
• admin.providerCredentials — availability(), list(), upsert(input), test(id), revoke(id) — the BYOK Connection lifecycle
• admin.cache — purge(...) — gateway response-cache purge
• admin.tenants — provision(input) — authenticated by a separate provisioning key (tt_prov_…), not the PAT; used for agent-native onboarding (see the MCP page)

Errors are AdminHttpError (transport/HTTP) or AdminGraphQLError (GraphQL errors[] envelope, .code set from extensions.code), both extending AdminError.

Base URL defaults to https://api.aisetu.ai; override with AI_SETU_API_BASE_URL or new AiSetuAdmin({ baseUrl }).

@ai-setu/cli — control plane from the shell

The same control-plane operations as @ai-setu/admin, callable from a terminal or CI job — no TypeScript required.

npm i -g @ai-setu/cli
export AI_SETU_PAT=tt_pat_…
export AI_SETU_TENANT_ID=00000000-0000-0000-0000-000000000001
ai-setu balance

Full command-by-command reference — generated from the CLI's own --help output, so it can't drift from what's actually installed — lives on the CLI Reference page.

@ai-setu/mcp — control plane for a builder agent

A Model Context Protocol server that exposes the same control-plane operations as MCP tools, plus an OTP onboarding flow that works with no credentials at all — useful for bootstrapping a brand-new user entirely from chat.

npx -y @ai-setu/mcp

See the MCP page for the full tool list, client configuration, and an end-to-end onboarding walkthrough.

Choosing between @ai-setu/admin, @ai-setu/cli, and @ai-setu/mcp

All three drive the identical control-plane API — the difference is only the calling surface: TypeScript code, a shell command, or a conversational tool call. Use whichever fits the environment you're already in; none of them do inference (that's @ai-setu/client's job only).

Environments

Every package reads AI_SETU_ENV (production default, or staging) as a single switch that retargets its default host — set it once and the gateway and control-plane packages all move together. Set a full URL instead (AI_SETU_BASE_URL for @ai-setu/client, AI_SETU_API_BASE_URL for the other three) to point at a self-hosted deployment.