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.16.1.

@ai-setu/client — runtime inference

Drop-in replacement for the openai SDK, pointed at the AI Setu gateway. Every method the openai SDK exposes (chat.completions, embeddings, responses, files, batches, …) works unchanged — only the constructor and the model string differ.

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 — list(), get(id), create(input), rename(id, input), delete(id), listMembers(workspaceId)
• 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.