Install
npm install @arcgrid/arcrouter-clientThe package lives at packages/arcrouter-client/ in the main repo. It has no runtime dependencies — just TypeScript types and native fetch.
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()
| Option | Default | Description |
|---|---|---|
baseUrl | http://localhost:4000 | ArcRouter base URL |
apiKey | — | Bearer token for auth |
timeout | 120000 | Request timeout in ms |
maxRetries | 2 | Retries 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.
| Constant | Alias | Model | Use | Tier |
|---|---|---|---|---|
COMMUNICATIONS | communications | llama3.1:8b | Chat, classification, quick answers | local |
CODING | coding | qwen2.5-coder:32b | Code gen, JSON, config | local |
ANALYSIS | analysis | qwen3-fast | Reasoning, gap analysis, synthesis | local |
DESIGN | design | qwen3-fast | UI copy, long markdown, content | local |
CLAUDE_CODE_LOCAL | claude-code-local | claude-code-3b-v3p | ArcGrid fine-tune, code tasks | local |
EMBED | embed | nomic-embed-text | 768-dim text embeddings | local |
WHISPER | whisper | faster-whisper-base | Speech-to-text | local |
GRID_BULK_14B | grid-bulk-14b | qwen2.5:14b | Batch / bulk tasks | local |
CLAUDE_SONNET | claude-sonnet-4-6 | Claude Sonnet 4.6 | Frontier quality, judgment | cloud |
CLAUDE_HAIKU | claude-haiku | Claude Haiku 4.5 | Fast tool calls, API billing | cloud |
DMR_ANALYSIS | dmr-analysis | Gemma4 E4B | DMR fallback, analysis | dmr |
DMR_CODING | dmr-coding | qwen3-coder 30B | DMR fallback, coding | dmr |
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.
| Status | Behaviour |
|---|---|
429 | Retry up to maxRetries with exponential backoff |
503 | Retry up to maxRetries with exponential backoff |
401, 403 | Throw immediately — check ARCROUTER_API_KEY |
400 | Throw immediately — malformed request |
timeout | AbortError from native fetch — catch separately |