@xxanderwp/ai-conductor
v0.1.5
Published
Orchestrate any AI provider through one API.
Maintainers
Readme
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-conductorQuick 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);Streaming
const { result, cancel } = conductor.chatStream(
'Write a short poem',
(text) => process.stdout.write(text), // delta chunks by default
);
// Or cumulative text so far:
// conductor.chatStream(prompt, onChunk, { chunkMode: 'cumulative' });
const response = await result;
// cancel() aborts the in-flight streamOr 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 tailImage recognition (vision)
// Describe / analyze images: URL, data: URL, local file path, or { data, mimeType }
const { content, provider, model } = await conductor.recognizeImage('./receipt.jpg', {
prompt: 'Extract the total amount.',
detail: 'high', // optional OpenAI-style hint
});
// Several images in one request
await conductor.recognizeImage([
'https://example.com/a.png',
{ data: pngBytes, mimeType: 'image/png' },
]);
// Images also work in regular chat via OpenAI-compatible content parts
await conductor.chat([
{
role: 'user',
content: [
{ type: 'text', text: 'What is on this picture?' },
{ type: 'image_url', image_url: { url: 'https://example.com/cat.jpg' } },
],
},
]);recognizeImage follows the routing strategy but skips providers without image input. Per provider it uses options.model, else the configured model if it supports vision, else the first registry visionModels entry.
Which provider / model supports images:
conductor.getVisionCapabilities(); // every built-in provider
conductor.getVisionCapabilities({ configuredOnly: true });
// → [{ provider: 'groq', supportsVision: true, visionModels: [...], configured: true,
// model: 'llama-3.1-8b-instant', modelSupportsVision: false,
// recognitionModel: 'meta-llama/llama-4-scout-17b-16e-instruct' }, ...]
conductor.supportsVision('cerebras'); // false
conductor.supportsVision('openai', 'gpt-4o-mini'); // true (heuristic)
// Live catalog filtered to image-capable models (uses catalog modalities when reported,
// e.g. OpenRouter; name heuristics otherwise). listModels() also sets `supportsVision`.
await conductor.listVisionModels('openrouter');
await conductor.listVisionModels();Static metadata is also on PROVIDERS[id].supportsVision / visionModels, and isLikelyVisionModel(provider, model) is exported.
Development
npm install
npm run typecheck
npm run lint
npm test
npm run build
npm run docs:syncPlayground (CLI TUI)
cp config.yml.example config.yml # gitignored — add your keys
npm run playgroundCommands 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 projectskills/— focused skill files (each includes a self-update instruction)
Package
| Field | Value |
| ------- | ------------------------- |
| Name | @xxanderwp/ai-conductor |
| Version | 0.1.5 |
| 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
src/vision.ts
tests/
tests/conductor.test.ts
tests/suggest.test.tsSkills for LLM agents
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) |
