feat(router): smart router for unified LLM provider endpoints

[khoaminh2957]

Closes #286

/claim #286

Summary

Adds a SmartRouter class (inspired by Python's litellm) that exposes a single, provider-agnostic chat-completion API and dispatches requests to the appropriate provider based on the model prefix.

Lives at JS/edgechains/arakoodev/src/ai/src/lib/router/ and is re-exported from @arakoodev/edgechains.js/ai so it sits alongside the existing OpenAI / GeminiAI / LlamaAI clients rather than replacing them.

API

import { SmartRouter } from "@arakoodev/edgechains.js/ai";

const router = new SmartRouter({
  openai: process.env.OPENAI_API_KEY,
  anthropic: process.env.ANTHROPIC_API_KEY,
  google: process.env.GOOGLE_API_KEY,
  cohere: process.env.COHERE_API_KEY,
});

const res = await router.complete({
  model: "gpt-4o", // or "claude-3-5-sonnet-20241022", "gemini-1.5-pro", "command-r-plus"
  messages: [
    { role: "system", content: "You are concise." },
    { role: "user", content: "Say hello." },
  ],
  temperature: 0.2,
  max_tokens: 256,
});

console.log(res.content, res.provider, res.usage);
// → { input_tokens: number, output_tokens: number }

Routing rules

Prefix	Provider
gpt-*, o1-*, o3-*	openai
claude-*	anthropic
gemini-*, models/gemini-*	google
command*	cohere
llama-*, llama3-*	llama (registerable)

Explicit "provider/model" syntax (e.g. "openai/my-finetune") overrides the prefix inference. An optional defaultProvider handles unknown prefixes.

Implementation

• SmartRouter.ts — dispatcher with complete(), register(), supports(), listProviders(), plus a typed RouterError that preserves provider name, HTTP status, and original cause.
• providerResolver.ts — pure prefix/explicit resolution logic.
• adapters/{openai,anthropic,google,cohere}Adapter.ts — per-provider adapters that translate the normalized request to the provider's wire format and normalize the response back. Anthropic's system field, Gemini's systemInstruction, and Cohere's preamble + chat_history are derived automatically from the flat router message list.
• Uses only axios, which is already a dependency of the ai package — no new deps added.
• Custom / local providers (Ollama, vLLM, corporate gateways) can be plugged in via router.register(name, adapter).

Tests

20 vitest cases in src/ai/src/tests/smartRouter.test.ts covering:

• Provider resolution for every prefix family + the explicit provider/model form + unknown handling.
• Each adapter's request shape, header set, and response normalization (with axios.post mocked — no real network calls).
• Router dispatch to the correct adapter, default-provider fallback, and RouterError paths for unknown models, missing adapters, invalid input, and upstream failures.

 Test Files  1 passed (1)
      Tests  20 passed (20)

Scope of this MVP

• Built-in adapters for OpenAI, Anthropic, Google Gemini, Cohere.
• Llama and other providers can be plugged in via register() — built-in adapter intentionally deferred to a follow-up.
• Streaming, tool calling, and embeddings are out of scope for this PR and will land in subsequent PRs to keep the diff reviewable.

Test plan

• npm run build passes (tsc -b clean)
• New tests pass (npx vitest run src/ai/src/tests/smartRouter.test.ts — 20/20)
• No new dependencies added
• No existing files refactored — only new module + a 2-line export addition in src/ai/src/index.ts
• Maintainer review pending

🤖 Generated with Claude Code

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[khoaminh2957]

I have read the Arakoo CLA Document and I hereby sign the CLA

[khoaminh2957]

recheck