SDKs

ArcRouter SDK

TypeScript client for the ArcGrid ArcRouter gateway. Sovereign model routing with alias constants, streaming, tool calls, and embeddings. All traffic through ArcRouter — no direct provider imports.

SDK TypeScript ArcRouter Streaming

Install

npm install @arcgrid/arcrouter-client

The package lives at packages/arcrouter-client/ in the main repo. It has no runtime dependencies — just TypeScript types and native fetch.

Sovereignty rule

Never import the Anthropic SDK or OpenAI SDK directly in agent code. All model traffic goes through ArcRouterClient. Cloud aliases (CLAUDE_SONNET, CLAUDE_HAIKU) route through ArcRouter, which handles auth, metering, and failover.

Initialization

import { ArcRouterClient } from '@arcgrid/arcrouter-client'

// Internal — ArcHelm on the GRID network
const client = new ArcRouterClient({
  baseUrl: 'http://10.20.10.29:4000',
  apiKey: process.env.ARCROUTER_API_KEY,
})

// Defaults (localhost, no auth — for local dev with ArcRouter running)
const client = new ArcRouterClient()
OptionDefaultDescription
baseUrlhttp://localhost:4000ArcRouter base URL
apiKey—Bearer token for auth
timeout120000Request timeout in ms
maxRetries2Retries on 429 / 503

Model aliases

Import constants rather than raw strings. The constants match the aliases in brain/arcrouter/config/routing-table.json — changing the underlying model only requires a config edit, not a code change.

ConstantAliasModelUseTier
COMMUNICATIONScommunicationsllama3.1:8bChat, classification, quick answerslocal
CODINGcodingqwen2.5-coder:32bCode gen, JSON, configlocal
ANALYSISanalysisqwen3-fastReasoning, gap analysis, synthesislocal
DESIGNdesignqwen3-fastUI copy, long markdown, contentlocal
CLAUDE_CODE_LOCALclaude-code-localclaude-code-3b-v3pArcGrid fine-tune, code taskslocal
EMBEDembednomic-embed-text768-dim text embeddingslocal
WHISPERwhisperfaster-whisper-baseSpeech-to-textlocal
GRID_BULK_14Bgrid-bulk-14bqwen2.5:14bBatch / bulk taskslocal
CLAUDE_SONNETclaude-sonnet-4-6Claude Sonnet 4.6Frontier quality, judgmentcloud
CLAUDE_HAIKUclaude-haikuClaude Haiku 4.5Fast tool calls, API billingcloud
DMR_ANALYSISdmr-analysisGemma4 E4BDMR fallback, analysisdmr
DMR_CODINGdmr-codingqwen3-coder 30BDMR fallback, codingdmr

Chat completions

import { ArcRouterClient, CODING } from '@arcgrid/arcrouter-client'

const client = new ArcRouterClient({ baseUrl: 'http://10.20.10.29:4000' })

const response = await client.chat.complete({
  model: CODING,
  messages: [
    { role: 'system', content: 'You are a senior TypeScript engineer.' },
    { role: 'user', content: 'Write a Zod schema for a Supabase user row.' },
  ],
  temperature: 0.2,
  max_tokens: 2048,
})

const text = response.choices[0].message.content
console.log(text)

Streaming

import { ArcRouterClient, ANALYSIS } from '@arcgrid/arcrouter-client'

const client = new ArcRouterClient({ baseUrl: 'http://10.20.10.29:4000' })

// Iterate chunks
const stream = await client.chat.stream({
  model: ANALYSIS,
  messages: [{ role: 'user', content: 'Summarise Q3 pipeline gaps.' }],
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}

// Or collect all at once
const stream2 = await client.chat.stream({ model: ANALYSIS, messages: [...] })
const fullText = await stream2.text()

The ArcRouterStream class is an AsyncIterable<ChatCompletionChunk>. Each chunk follows the OpenAI SSE format. The stream ends when the server sends data: [DONE].

Tool calls

import { ArcRouterClient, CODING, type Tool } from '@arcgrid/arcrouter-client'

const tools: Tool[] = [{
  type: 'function',
  function: {
    name: 'get_migration_status',
    description: 'Check which Supabase migrations have been applied',
    parameters: {
      type: 'object',
      properties: {
        project_ref: { type: 'string', description: 'Supabase project reference' },
      },
      required: ['project_ref'],
    },
  },
}]

const response = await client.chat.complete({
  model: CODING,
  messages: [{ role: 'user', content: 'Which migrations are missing on ahemsgoiidpbbcmihqgw?' }],
  tools,
  tool_choice: 'auto',
})

const toolCalls = response.choices[0].message.tool_calls ?? []
for (const tc of toolCalls) {
  const args = JSON.parse(tc.function.arguments)
  // execute tool, then send result back as role: 'tool' message
}

Embeddings

import { ArcRouterClient } from '@arcgrid/arcrouter-client'

const client = new ArcRouterClient({ baseUrl: 'http://10.20.10.29:4000' })

const result = await client.embeddings.create({
  input: 'ArcRouter sovereign gateway entitlement enforcement',
})

const vector = result.data[0].embedding  // number[], 768 dimensions (nomic-embed-text)
console.log(`Dimensions: ${vector.length}`)  // 768

Embeddings use the embed alias by default (nomic-embed-text on ArcRig3). Pass a custom model field to override. The vector is suitable for cosine similarity search in the Brain graph or any pgvector column.

Error handling

import { ArcRouterClient, ArcRouterError, CODING } from '@arcgrid/arcrouter-client'

const client = new ArcRouterClient({ baseUrl: 'http://10.20.10.29:4000' })

try {
  const response = await client.chat.complete({
    model: CODING,
    messages: [{ role: 'user', content: 'Hello' }],
  })
} catch (err) {
  if (err instanceof ArcRouterError) {
    console.error(`ArcRouter ${err.status}: ${err.message}`)
    // err.status — HTTP status code
    // err.code   — provider error code if available
  }
}

The client retries automatically on 429 Too Many Requests and 503 Service Unavailable with exponential backoff. Configure maxRetries to disable retries (0) or increase them. Authentication errors (401, 403) are not retried.

StatusBehaviour
429Retry up to maxRetries with exponential backoff
503Retry up to maxRetries with exponential backoff
401, 403Throw immediately — check ARCROUTER_API_KEY
400Throw immediately — malformed request
timeoutAbortError from native fetch — catch separately