AI Conductor

Orchestrate any AI provider through one API.

AI Conductor connects multiple OpenAI-compatible AI providers and routes chat requests through a single entry point. Prefer cheaper/free tiers with the cheapest strategy, spread load with round-robin, or fail over when a provider is rate-limited.

• Author: XXanderWP

Install

npm install @xxanderwp/ai-conductor

Quick start

import { Conductor } from '@xxanderwp/ai-conductor';

const conductor = new Conductor({
  configPath: './config.yml',
});

const response = await conductor.chat([
  { role: 'user', content: 'Summarize this ticket for support.' },
]);

console.log(response.content, response.provider, response.strategy);

Or configure entirely in code:

const conductor = new Conductor({
  providers: [
    { id: 'gemini', priority: 100, dailyLimit: 1000, apiKey: process.env.GEMINI_API_KEY },
    { id: 'groq', priority: 90, apiKey: process.env.GROQ_API_KEY },
  ],
  routing: { strategy: 'cheapest' },
  fallback: ['gemini', 'groq', 'openrouter'],
  apiKeys: {
    openrouter: process.env.OPENROUTER_API_KEY!,
  },
});

YAML configuration

See examples/config.yml:

providers:
  - id: gemini
    priority: 100
    dailyLimit: 1000
    apiKey: ${GEMINI_API_KEY}
    model: gemini-flash-latest

  - id: groq
    priority: 90
    apiKey: ${GROQ_API_KEY}

routing:
  strategy: cheapest

fallback:
  - gemini
  - groq
  - openrouter

${ENV_VAR} placeholders are expanded from the environment. Keys can also come from apiKeys in the constructor or common env vars (GEMINI_API_KEY, GROQ_API_KEY, OPENAI_API_KEY, AI_CONDUCTOR_<ID>_API_KEY, …).

Built-in providers

Built-in OpenAI-compatible providers:

ollama, gemini, groq, cerebras, mistral, nvidia, github, zai, puter, opencode, huggingface, openrouter, cohere, openai, openai_compatible

Routing strategies

| Strategy | Behavior | | -------------------- | ------------------------------------------------------------- | | cheapest (default) | Prefer free-tier / likely-free models, then higher priority | | priority | Highest priority first | | failover | Try providers in config order until one succeeds | | round-robin | Rotate eligible providers | | first-available | Always use the first eligible provider |

fallback appends extra providers after the primary ordered list. dailyLimit soft-skips a provider for the rest of the UTC day once the cap is reached.

Providers, models, and probes

// Built-in registry vs current config
conductor.getAvailableProviders();
conductor.getConfiguredProviders();

// Parse OpenAI-compatible model catalogs
const geminiModels = await conductor.listModels('gemini');
const allModels = await conductor.listModels();

// Connectivity (API key + /models) vs real chat
await conductor.testProvider('gemini'); // real omitted → connectivity
await conductor.testProvider('gemini', { real: true });
await conductor.testProviders({ real: true });

Compress dialog context

const { messages } = await conductor.compressContext(history, {
  keepLast: 4, // keep the last 4 user/assistant messages
});
// messages[0] is a system note about earlier turns; the rest is the recent tail

Development

npm install
npm run typecheck
npm run lint
npm test
npm run build
npm run docs:sync

Playground (CLI TUI)

cp config.yml.example config.yml   # gitignored — add your keys
npm run playground

Commands inside the chat: /status, /clear, /provider <id|auto>, /test-all (confirm), /quit (Tab completes commands and provider ids).

LLM agents

• AGENTS.md — how agents should navigate this project
• skills/ — focused skill files (each includes a self-update instruction)

Package

| Field | Value | | ------- | ------------------------- | | Name | @xxanderwp/ai-conductor | | Version | 0.1.4 | | Author | XXanderWP | | License | MIT | | Node | >=18 |

Repository layout

.github/
.github/workflows/
.github/workflows/ci.yml
.github/workflows/publish.yml
scripts/
scripts/playground.mts
scripts/sync-docs.mjs
skills/
skills/api.md
skills/docs.md
skills/tech.md
src/
src/conductor.ts
src/config/
src/config/load.ts
src/config/types.ts
src/index.ts
src/providers/
src/providers/mock.ts
src/providers/openai-client.ts
src/providers/registry.ts
src/routing/
src/routing/order.ts
src/routing/usage.ts
src/types.ts
src/utils/
src/utils/suggest.ts
src/utils.ts
tests/
tests/conductor.test.ts
tests/suggest.test.ts

Skills for LLM agents

• skills/api.md
• skills/docs.md
• skills/tech.md

npm scripts

| Script | Purpose | | ----------------------- | ----------------------------------------------------- | | npm run build | Compile TypeScript to dist/ (CJS + ESM + typings) | | npm test | Run Jest unit tests | | npm run test:coverage | Run tests with coverage report | | npm run lint | ESLint check | | npm run format | Format with Prettier | | npm run typecheck | TypeScript --noEmit check | | npm run playground | Interactive CLI chat against root config.yml | | npm run docs:sync | Refresh generated README / AGENTS sections | | npm run docs:check | Fail if generated docs are stale | | npm run release | Publish to npm (prepublishOnly runs checks + build) |