{"_id":"aiplug","_rev":"5-c2b5faa666211efe4f9c1069ac1f75fe","name":"aiplug","dist-tags":{"latest":"0.2.0"},"versions":{"0.0.1":{"name":"aiplug","version":"0.0.1","_id":"aiplug@0.0.1","maintainers":[{"name":"mgks","email":"hello@mgks.dev"}],"dist":{"shasum":"09b2bbff2700ad06ff8c8d800358d7fdf6c95ac9","tarball":"https://registry.npmjs.org/aiplug/-/aiplug-0.0.1.tgz","fileCount":1,"integrity":"sha512-EL/oL4wg/Ec6gIqVNrUxk54t3iRDqq6SU1ysz4Ku+48uRn/L3MFUa/UwB70qMJCozvWp/UjlnIH49sqaEMQy9w==","signatures":[{"sig":"MEUCIEa8Uwh4oag8ymF77C3+kWLCYIfRJ8TohTwxdT4WDz8kAiEA029gHXBIeeLS6S/8DK+HJg4SrdEBsgvZUKhr0vwCKpg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":115},"_npmUser":{"name":"mgks","email":"hello@mgks.dev"},"_npmVersion":"11.16.0","description":"AI Plugin for managing and connecting to AI models","directories":{},"_nodeVersion":"25.2.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/aiplug_0.0.1_1782820887010_0.9858633551243381","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"aiplug","version":"0.1.0","keywords":["memoryblock","mblk","ai-agent","assistants","agents","automation","multi-agent","agentic-framework","core","cli","framework","interface","channels","adapters","tools","skills","local-ai","local-llm","openai","anthropic","gemini","groq","chatgpt","deepseek","ollama"],"author":{"url":"https://mgks.dev","name":"Ghazi"},"license":"MIT","_id":"aiplug@0.1.0","maintainers":[{"name":"mgks","email":"hello@mgks.dev"}],"homepage":"https://mgks.dev","bugs":{"url":"https://github.com/mgks/aiplug/issues"},"bin":{"aiplug":"dist/cli/index.js"},"dist":{"shasum":"ea246762e3ed2fa1caa93d13b0f41f2133677bd1","tarball":"https://registry.npmjs.org/aiplug/-/aiplug-0.1.0.tgz","fileCount":673,"integrity":"sha512-rPC+ZIXEW7OHHhAn4kI65ht2KEvztm7iaiEZkqcVVN9EZqvANcmxGmyMB/6FOi3HZ666b1Ft0ULz90Y4ZweiCA==","signatures":[{"sig":"MEUCIEw4Ttx0L2b9lUu53yXd8GuYMVDg0xrw8HHEC27LILmYAiEAt3D99DfGx/wrnbuHpK2lLOliWPp6Hr5ODfVgfmopQXs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/aiplug@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1292627},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.17.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./package.json":"./package.json","./data/registry.json":"./data/registry.json"},"funding":"https://github.com/sponsors/mgks","gitHead":"d0b44289d53b050cf32ddf5085737cb5f1df256d","scripts":{"dev":"npm run build:registry && tsc -p tsconfig.json --watch","lint":"tsc --noEmit","test":"tsx --test src/__tests__/**/*.test.ts","build":"tsc -p tsconfig.json","smoke":"tsx scripts/smoke.ts","smoke:e2e":"tsx scripts/smoke-e2e.ts","typecheck":"tsc --noEmit","build:registry":"tsx scripts/build-registry.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c1dec0fc-17fa-4b4e-890f-28847232a9cf"}},"repository":{"url":"git+https://github.com/mgks/aiplug.git","type":"git"},"_npmVersion":"11.12.1","description":"A lightweight runtime that unifies 110+ AI providers behind a single, OpenAI-compatible API.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"yaml":"^2.9.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.5","typescript":"^5.9.3","@types/node":"^22.20.0"},"_npmOperationalInternal":{"tmp":"tmp/aiplug_0.1.0_1783083874045_0.5673803252173313","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"aiplug","version":"0.1.1","keywords":["memoryblock","mblk","ai-agent","assistants","agents","automation","multi-agent","agentic-framework","core","cli","framework","interface","channels","adapters","tools","skills","local-ai","local-llm","openai","anthropic","gemini","groq","chatgpt","deepseek","ollama"],"author":{"url":"https://mgks.dev","name":"Ghazi"},"license":"MIT","_id":"aiplug@0.1.1","maintainers":[{"name":"mgks","email":"hello@mgks.dev"}],"homepage":"https://mgks.dev","bugs":{"url":"https://github.com/mgks/aiplug/issues"},"bin":{"aiplug":"dist/cli/index.js"},"dist":{"shasum":"ca0459d402b2c10a1bd61089f1d58102fc66e850","tarball":"https://registry.npmjs.org/aiplug/-/aiplug-0.1.1.tgz","fileCount":673,"integrity":"sha512-Irz4jbbNJdII8QdXjEBdKoajHe3X9RFvR2LGIgQu7tRJL97ujCgrXwOoLlRzxiHSM43rpnC4kGq4EM6D//9wMg==","signatures":[{"sig":"MEYCIQD83UjYeruwU2YM0+UhcrlmuqVguGqfVotdKeZb1En5PgIhALifSXV3X+IDQBb5PanNQ9pMVMLWpV74SbBhmknpv7eR","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/aiplug@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1294858},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.17.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./package.json":"./package.json","./data/registry.json":"./data/registry.json"},"funding":"https://github.com/sponsors/mgks","gitHead":"287ed814ec306e9fa8c7eb048e8ab3c276a1290e","scripts":{"dev":"npm run build:registry && tsc -p tsconfig.json --watch","lint":"tsc --noEmit","test":"tsx --test src/__tests__/**/*.test.ts","build":"tsc -p tsconfig.json","smoke":"tsx scripts/smoke.ts","smoke:e2e":"tsx scripts/smoke-e2e.ts","typecheck":"tsc --noEmit","build:registry":"tsx scripts/build-registry.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c1dec0fc-17fa-4b4e-890f-28847232a9cf"}},"repository":{"url":"git+https://github.com/mgks/aiplug.git","type":"git"},"_npmVersion":"11.12.1","description":"A lightweight runtime that unifies 110+ AI providers behind a single, OpenAI-compatible API.","directories":{},"_nodeVersion":"20.20.2","allowScripts":{"esbuild":true,"fsevents":true},"dependencies":{"yaml":"^2.9.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.5","typescript":"^5.9.3","@types/node":"^22.20.0"},"_npmOperationalInternal":{"tmp":"tmp/aiplug_0.1.1_1785108246165_0.3383658817640729","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"aiplug","version":"0.1.2","keywords":["memoryblock","mblk","ai-agent","assistants","agents","automation","multi-agent","agentic-framework","core","cli","framework","interface","channels","adapters","tools","skills","local-ai","local-llm","openai","anthropic","gemini","groq","chatgpt","deepseek","ollama"],"author":{"url":"https://mgks.dev","name":"Ghazi"},"license":"MIT","_id":"aiplug@0.1.2","maintainers":[{"name":"mgks","email":"hello@mgks.dev"}],"homepage":"https://mgks.dev","bugs":{"url":"https://github.com/mgks/aiplug/issues"},"bin":{"aiplug":"dist/cli/index.js"},"dist":{"shasum":"3156d5d9a9b4ebd87db94e46e7aa8e9c5bfb26e6","tarball":"https://registry.npmjs.org/aiplug/-/aiplug-0.1.2.tgz","fileCount":673,"integrity":"sha512-NYYRuCewtIACs2Vbxw8l0EOBZMsyV/uWGq5zh+3f9rj1DBMheycCj031eudZmRJIwPUgsx/LzXY4/JkyP7owhQ==","signatures":[{"sig":"MEUCIHlRvnglAS901uZ0F/XE1YDXg2zl/z0XpFfpyUupd/fUAiEA25L2L3BFhhaXzZg4hcQwO0pZkbgU6FfDR1+e7X5s0E8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/aiplug@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1302518},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.17.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./package.json":"./package.json","./data/registry.json":"./data/registry.json"},"funding":"https://github.com/sponsors/mgks","gitHead":"bf1249771140f46ad3d4512aaccb54537bca0c05","scripts":{"dev":"npm run build:registry && tsc -p tsconfig.json --watch","lint":"tsc --noEmit","test":"tsx --test src/__tests__/**/*.test.ts","build":"tsc -p tsconfig.json","smoke":"tsx scripts/smoke.ts","smoke:e2e":"tsx scripts/smoke-e2e.ts","typecheck":"tsc --noEmit","build:registry":"tsx scripts/build-registry.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c1dec0fc-17fa-4b4e-890f-28847232a9cf"}},"repository":{"url":"git+https://github.com/mgks/aiplug.git","type":"git"},"_npmVersion":"11.12.1","description":"A lightweight runtime that unifies 110+ AI providers behind a single, OpenAI-compatible API.","directories":{},"_nodeVersion":"20.20.2","allowScripts":{"esbuild":true,"fsevents":true},"dependencies":{"yaml":"^2.9.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.5","typescript":"^5.9.3","@types/node":"^22.20.0"},"_npmOperationalInternal":{"tmp":"tmp/aiplug_0.1.2_1785543223162_0.06379919387192845","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"aiplug@0.2.0","bin":{"aiplug":"dist/cli/index.js"},"bugs":{"url":"https://github.com/mgks/aiplug/issues"},"dist":{"shasum":"8ac574f8dabc9a423cd60ff2525160c2fd1c9393","tarball":"https://registry.npmjs.org/aiplug/-/aiplug-0.2.0.tgz","fileCount":2190,"integrity":"sha512-L1hhuHYUxzoEwvHzTyknGSExFKo/BTYTg1R+QwhQEaONwqArjRRgG6GI6/wPh9t9Pmof2LZ0huKzXof+ue89zQ==","signatures":[{"sig":"MEYCIQDQzr02i1UPwFu+EmCtq0nJ/EH1UGLXCC1EEHZJz0FPwQIhAI7pHO8mSAcsQHOFdBlYYnr5S7LAZ9Lal4RtQVdS0Xiu","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGaBBMGjIITw05hKfB9+aRPImzN9IXDeeCqQ0FP/ig58AiEA5wEUqWJM/ktehtOnkgo9w5hq+TMyMqENitCBURRSDas="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/aiplug@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":3519050},"main":"dist/index.js","name":"aiplug","type":"module","types":"dist/index.d.ts","author":{"url":"https://mgks.dev","name":"Ghazi"},"engines":{"node":">=18.17.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./package.json":"./package.json","./data/registry.json":"./data/registry.json"},"funding":"https://github.com/sponsors/mgks","gitHead":"45fdef4f9d08fe21e9e800fee2e12aab0bf3a80a","license":"MIT","scripts":{"dev":"npm run build:registry && tsc -p tsconfig.json --watch","lint":"tsc --noEmit","test":"tsx --test src/__tests__/**/*.test.ts","build":"tsc -p tsconfig.json","smoke":"tsx scripts/smoke.ts","smoke:e2e":"tsx scripts/smoke-e2e.ts","typecheck":"tsc --noEmit","build:registry":"tsx scripts/build-registry.ts","docs:providers":"tsx scripts/generate-providers-doc.ts"},"version":"0.2.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"c1dec0fc-17fa-4b4e-890f-28847232a9cf"}},"homepage":"https://mgks.dev","keywords":["aiplug","llm","llm-providers","ai-providers","ai-agent","assistants","agents","automation","multi-agent","agentic-framework","universal-ai","core","cli","framework","interface","channels","adapters","tools","skills","local-ai","local-llm","openai","anthropic","gemini","groq","chatgpt","deepseek","ollama"],"repository":{"url":"git+https://github.com/mgks/aiplug.git","type":"git"},"_npmVersion":"11.12.1","description":"A lightweight runtime that unifies 490+ AI providers behind a single, OpenAI-compatible API.","directories":{},"maintainers":[{"name":"mgks","email":"hello@mgks.dev"}],"_nodeVersion":"20.20.2","allowScripts":{"esbuild":true,"fsevents":true},"dependencies":{"yaml":"^2.9.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.5","typescript":"^5.9.3","@types/node":"^22.20.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aiplug_0.2.0_1792883506251_0.2603993036556327"}}},"time":{"created":"2026-06-30T12:01:26.843Z","modified":"2026-10-24T23:11:46.697Z","0.0.1":"2026-06-30T12:01:27.131Z","0.1.0":"2026-07-03T13:04:34.252Z","0.1.1":"2026-07-26T23:24:06.313Z","0.1.2":"2026-08-01T00:13:43.364Z","0.2.0":"2026-10-24T23:11:46.339Z"},"bugs":{"url":"https://github.com/mgks/aiplug/issues"},"author":{"url":"https://mgks.dev","name":"Ghazi"},"license":"MIT","homepage":"https://mgks.dev","keywords":["aiplug","llm","llm-providers","ai-providers","ai-agent","assistants","agents","automation","multi-agent","agentic-framework","universal-ai","core","cli","framework","interface","channels","adapters","tools","skills","local-ai","local-llm","openai","anthropic","gemini","groq","chatgpt","deepseek","ollama"],"repository":{"url":"git+https://github.com/mgks/aiplug.git","type":"git"},"description":"A lightweight runtime that unifies 490+ AI providers behind a single, OpenAI-compatible API.","maintainers":[{"name":"mgks","email":"hello@mgks.dev"}],"readme":"<div align=\"center\">\n<h1>AIPlug</h1>\n\n[![npm version](https://img.shields.io/npm/v/aiplug?color=blue)](https://www.npmjs.com/package/aiplug)\n[![license](https://img.shields.io/github/license/mgks/aiplug)](LICENSE)\n[![tests](https://img.shields.io/badge/tests-27%20passing-brightgreen)](package.json)\n[![providers](https://img.shields.io/badge/providers-490%2B-blueviolet)](PROVIDERS.md)\n\n[**Quick Start**](#quick-start) •\n[**CLI**](#cli) •\n[**API**](#programmatic-api) •\n[**Providers List**](PROVIDERS.md) •\n[**Streaming & Fallback**](#features--capabilities) •\n[**HTTP Gateway**](#http-gateway-server) •\n[**Sponsors**](#sponsors--support)\n\n<p>A lightweight, dependency-free TypeScript runtime that gives every AI backend one identical face. AIPlug is a <b>universal transport layer</b> - point any OpenAI-compatible SDK at AIPlug and switch the underlying provider with one config line.</p>\n</div>\n\n```ts\nimport OpenAI from 'openai';\n\nconst client = new OpenAI({\n  baseURL: 'http://localhost:3711/v1',\n  apiKey: 'whatever',        // AIPlug handles real auth\n});\n\n// Now this hits Anthropic, or Ollama, or Groq, or any of 490+ providers\n// depending on what you set with `aiplug transport use anthropic`.\n```\n\nBuilt on four principles:\n\n- **Zero runtime dependencies** beyond `yaml` (≈ 80 kB).\n- **Zero artificial limits.** No turn limits, no tool caps, no autonomous loops — your application controls the conversation budget.\n- **No hidden retries, no hidden routing, no automatic model selection.** You say what you want, AIPlug sends it.\n- **One folder per provider.** Adding a new provider is a five-minute copy-paste.\n\n## Quick start\n\n```bash\nnpm install\nnpm run build\n\n# Configure providers\n./dist/cli/index.js init\n./dist/cli/index.js transport add anthropic              # interactive\n./dist/cli/index.js transport add ollama  --base-url=http://localhost:11434 --model=llama3.2 --force --yes\n./dist/cli/index.js transport add openai   --api-key=$OPENAI_API_KEY --model=gpt-4o --force --yes\n\n# Use one\n./dist/cli/index.js transport use anthropic\n\n# Boot the OpenAI-compatible HTTP server\n./dist/cli/index.js serve\n```\n\nThen point any OpenAI SDK at `http://localhost:3711/v1`.\n\n**The application code doesn't change** when you switch providers — only the `aiplug transport use` line.\n\n## CLI\n\n| Command | What it does |\n|---------|--------------|\n| `aiplug init` | Create `~/.config/aiplug/` and seed empty config |\n| `aiplug transport add <slug>` | Interactively add a provider. `--api-key`, `--base-url`, `--model`, `--force`, `--yes` available |\n| `aiplug transport remove <slug>` | Remove a configured provider (`--force`) |\n| `aiplug transport list` | Show configured providers + which is active |\n| `aiplug transport test <slug>` | Live health-check against the provider's endpoint |\n| `aiplug transport use <slug>` | Mark which provider serves the HTTP server |\n| `aiplug models` | List models from the active provider's `/models` endpoint |\n| `aiplug config` | Print the resolved effective config (CLI > env > file > defaults) |\n| `aiplug status [--live]` | Table of providers, optionally with live health probes |\n| `aiplug serve [--port=3711] [--host=127.0.0.1]` | Start the OpenAI-compatible HTTP server |\n| `aiplug health` | Health-check the active provider |\n| `aiplug chat [model]` | Minimal streaming REPL against the active transport |\n| `aiplug --json` | Machine-readable output (works on every command) |\n| `aiplug --help` | Built-in help |\n\n## Chat REPL\n\n`aiplug chat` opens a minimal streaming REPL against whichever provider you made active with `aiplug transport use <name>`. No banners, no onboarding, no colour noise. Direct prompt → streamed reply → next prompt.\n\n```bash\n$ aiplug transport use anthropic\n$ aiplug chat claude-3-5-sonnet-latest\naiplug chat — anthropic / claude-3-5-sonnet-latest\nType /help for commands, Ctrl+D to exit.\n\nyou> What's the capital of France?\nParis.\n\nyou> And its population?\nAbout 2.1 million in the city proper (roughly 12 million in the metro area).\n\nyou> /model claude-3-opus-latest\n(model: claude-3-opus-latest)\n\nyou> /exit\n```\n\n### In-session commands\n\n| Command | Effect |\n|---------|--------|\n| `/help` | Show available commands |\n| `/model <name>` | Switch model mid-session |\n| `/provider` | Show active transport + model |\n| `/clear` | Clear conversation history |\n| `/exit`, `/quit`, `/q` | End the session |\n\n### Signals\n\n| Key | Effect |\n|-----|--------|\n| `Ctrl+C` during a stream | Aborts the current request, stays in REPL |\n| `Ctrl+C` idle | Exits |\n| `Ctrl+D` | Exits |\n\n## Programmatic API\n\n```ts\nimport { AIPlug, loadConfig } from 'aiplug';\n\n// Pick a provider in three ways:\n//   1. Explicit config\nconst ai = new AIPlug({\n  transport: 'anthropic',\n  apiKey:    process.env.ANTHROPIC_API_KEY!,\n  model:     'claude-3-5-sonnet-latest',\n});\n\n//   2. Unified \"provider/model\" specifier string\nconst fast = AIPlug.fromModel('groq/llama-3.3-70b-versatile', {\n  apiKey: process.env.GROQ_API_KEY,\n});\n\n//   3. From a profile in aiplug.config.json (CLI > env > file > defaults)\nconst { config } = loadConfig({}, 'work');\nconst configuredAi = new AIPlug(config);\n\n// All methods accept an AbortSignal\nconst ctrl = new AbortController();\nsetTimeout(() => ctrl.abort(), 5000);\n\nconst reply = await ai.chat(\n  {\n    model: 'claude-3-5-sonnet-latest',\n    messages: [{ role: 'user', content: 'Hello!' }],\n  },\n  { signal: ctrl.signal },\n);\nconsole.log(reply.message.content);\n\n// Live text streaming — yields string text deltas directly\nfor await (const text of ai.streamText({\n  model: 'claude-3-5-sonnet-latest',\n  messages: [{ role: 'user', content: 'Tell me a story.' }],\n})) {\n  process.stdout.write(text);\n}\n\n// Or full stream chunk inspection (reasoning, tool calls, cache, usage)\nfor await (const chunk of ai.stream({\n  model: 'claude-3-5-sonnet-latest',\n  messages: [{ role: 'user', content: 'Design a system.' }],\n})) {\n  if (chunk.type === 'text-delta') process.stdout.write(chunk.delta);\n  if (chunk.type === 'reasoning-delta') console.log('[thinking]', chunk.delta);\n  if (chunk.type === 'finish') console.log('\\n[done]', chunk.reason);\n}\n\n// Other capabilities — same shape across providers\nawait ai.embeddings({ model: 'text-embedding-3-small', input: 'hello world' });\nawait ai.images({ model: 'dall-e-3', prompt: 'a robot cat' });\nawait ai.audio({ model: 'tts-1', input: 'hello world', voice: 'alloy' });\nawait ai.transcription({ model: 'whisper-1', audio: audioBytes });\nawait ai.models();               // → ModelInfo[] (queries live endpoint)\nawait ai.searchModels('llama');  // → ModelInfo[] filtered by query\nawait ai.health();               // → { ok, latencyMs? }\nai.capabilities();               // → TransportMetadata (sync)\n\n// Fast in-memory provider search across 490+ providers\nconst providers = AIPlug.searchProviders('groq', { capability: 'vision' });\n```\n\n### Multi-provider resilience & fallback\n\nChain multiple providers together with automatic failover upon HTTP 429 rate-limits, timeouts, or service outages:\n\n```ts\nconst resilient = AIPlug.fallback(\n  [\n    { transport: 'groq', apiKey: process.env.GROQ_API_KEY, model: 'llama-3.3-70b-versatile' },\n    { transport: 'deepseek', apiKey: process.env.DEEPSEEK_API_KEY, model: 'deepseek-chat' },\n    { transport: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o-mini' },\n  ],\n  {\n    onFailover: (from, to, err) => {\n      console.warn(`[aiplug] Failover from ${from} to ${to}: ${err.message}`);\n    },\n  },\n);\n\n// If Groq is rate-limited, this seamlessly executes on DeepSeek:\nconst res = await resilient.chat({ messages: [{ role: 'user', content: 'Run query' }] });\n```\n\n### Pluggable middleware pipeline\n\nIntercept requests and responses without subclassing or wrapping transports:\n\n```ts\nai.use(async (req, next, ctx) => {\n  const start = Date.now();\n  console.log(`[aiplug] Calling ${ctx.transportName} with model ${ctx.model}`);\n  const res = await next(req);\n  console.log(`[aiplug] Completed in ${Date.now() - start}ms`);\n  return res;\n});\n```\n\n### Offline & CI testing with MockTransport\n\n```ts\nconst testClient = new AIPlug({\n  transport: 'mock',\n  model: 'mock-model-1',\n  providerOptions: {\n    mockResponse: 'Deterministic response for tests',\n  },\n});\n```\n\n## HTTP server\n\n`aiplug serve` exposes an OpenAI-compatible API on `127.0.0.1:3711` by default:\n\n```\nPOST /v1/chat/completions          # OpenAI Chat Completions; SSE when stream=true\nPOST /v1/responses                 # alias for /v1/chat/completions\nPOST /v1/embeddings\nPOST /v1/images/generations\nPOST /v1/audio/speech\nPOST /v1/audio/transcriptions      # multipart\nGET  /v1/models                    # models for active transport (or ?provider=...)\nGET  /v1/providers                 # list all 490+ registered providers\nGET  /v1/providers/search?q=...    # in-memory fast provider search\nGET  /v1/providers/:slug/models    # dynamic live model discovery from source provider\nGET  /healthz\n```\n\n**Works with every OpenAI client SDK on the planet** (Python `openai`, JS `openai`, Go `openai-go`, etc.) by setting `baseURL: http://localhost:3711/v1`.\n\nUse `--port=0` for ephemeral ports (useful in tests).\n\n## Embedding AIPlug in another project\n\n`AIPlug` and the typed public surface (`AIPlug`, `Transport`, `ChatMessage`, `ToolCall`, …) are the canonical types an embedding project should consume. The package has zero third-party runtime dependencies, ships as ESM, and exposes its full shape via `import { … } from 'aiplug'`. Embedding applications and host frameworks can treat aiplug as the single source of truth for all provider transports.\n\n### `LLMAdapter` compatibility façade\n\nFor host projects or agent architectures that follow the classic `LLMAdapter` interface (`converse`, `converseStream`), aiplug ships an exact-match façade:\n\n````typescript\nimport { createLLMAdapter, type LLMMessage } from 'aiplug';\n\nconst adapter = createLLMAdapter({\n  provider: 'openai',\n  model: 'gpt-4o-mini',\n  apiKey: process.env.OPENAI_API_KEY,\n});\nconst reply = await adapter.converse([\n  { role: 'user', content: 'hi' } satisfies LLMMessage,\n]);\nconsole.log(reply.message.content, reply.stopReason, reply.usage);\n````\n\n`createLLMAdapter` returns an `LLMAdapter` whose `converse` and `converseStream` methods match the canonical contract (`LLMMessage`, `TokenUsage`, `StopReason`). The re-exported types `LLMMessage`, `LLMResponse`, `LLMAdapterToolDefinition`, `TokenUsage`, `StopReason` are pure aliases so existing agent code runs unchanged.\n\n## Stream protocol\n\n`AIPlug.stream()` yields a discriminated union of `StreamChunk` variants. Downstream consumers (agents, orchestrators, chat UIs, scripts) consume this uniform shape regardless of the underlying provider. The wire format is provider-specific; the chunk shape is uniform.\n\n### Chunk variants\n\n| Variant | When it fires | Provider examples |\n|---------|--------------|-------------------|\n| `text-delta` | Plain response text streams | All |\n| `reasoning-delta` | Model emits thinking that should not be shown to the user verbatim | MiniMax-M3 (`reasoning_split: true`), Anthropic Claude, DeepSeek-V4 (reasoning mode) |\n| `tool-call-delta` | Tool-call arguments stream in incrementally (partial JSON) | OpenAI, Bedrock ConverseStream, Anthropic |\n| `tool-call` | The final assembled tool call, ready for execution | All |\n| `cache-read` | The provider reports cached prompt tokens were hit | Anthropic, Bedrock, MiniMax |\n| `cache-write` | The provider reports new prompt tokens were cached | Anthropic, Bedrock |\n| `usage` | Token accounting chunk (prompt, completion, total, cache deltas) | All |\n| `finish` | Stream completed; carries the stop reason | All |\n| `error` | Mid-stream failure that the transport decided to surface as a chunk | All |\n\n`Usage` carries the cache deltas:\n\n```typescript\nconst usage = chunk.usage;\n// {\n//   promptTokens: 100,\n//   completionTokens: 50,\n//   totalTokens: 150,\n//   cacheReadTokens: 80,    // optional\n//   cacheWriteTokens: 20,   // optional\n//   reasoningTokens: 10,   // optional\n// }\n```\n\nProvider-specific fields land through the index signature (e.g. Anthropic's `cache_creation_input_tokens`).\n\n### Multimodal content & rich media\n\n`ChatMessage.content` is `string | ContentPart[]`. AIPlug transparently maps rich media across OpenAI-compatible, Anthropic, Gemini, and custom providers:\n\n- **Images**: `{ type: 'image_url', imageUrl: { url, detail?: 'auto' | 'low' | 'high' } }` or base64 `{ type: 'image_base64', mediaType: 'image/png', data }`\n- **Videos**: `{ type: 'video_url', videoUrl: { url } }` or base64 `{ type: 'video_base64', mediaType: 'video/mp4', data }`\n- **Audio**: `{ type: 'audio', mediaType: 'audio/mp3', data }` or `{ type: 'audio_url', audioUrl: { url } }`\n- **Documents & PDFs**: `{ type: 'document', mediaType: 'application/pdf', data, name?: 'doc.pdf' }` or `{ type: 'file_url', fileUrl: { url } }`\n\n```typescript\nawait ai.chat({\n  model: 'gpt-4o',\n  messages: [{\n    role: 'user',\n    content: [\n      { type: 'text', text: 'Analyze this chart, document, and video recording.' },\n      { type: 'image_url', imageUrl: { url: 'https://example.com/chart.png', detail: 'high' } },\n      { type: 'document', mediaType: 'application/pdf', name: 'report.pdf', data: pdfBase64 },\n      { type: 'video_url', videoUrl: { url: 'https://example.com/demo.mp4' } },\n    ],\n  }],\n});\n```\n\nThe transport normalises content parts into each provider's native wire format (data URLs for OpenAI-compatible, content blocks for Anthropic Messages, `inlineData` / `fileData` for Gemini). Providers that do not support a given part type silently drop it from the text view via the `extractText` helper; to gate multimodal inputs before sending, inspect `transport.capabilities()` or `AIPlug.describeProvider(slug).capabilities`.\n\n### Provider-specific body overrides\n\n`request.providerOptions` is forwarded into the body verbatim after the standard OpenAI-shaped fields, so provider-native toggles pass through without losing the rest of the request:\n\n```typescript\nawait ai.stream({\n  model: 'MiniMax-M3',\n  messages: [{ role: 'user', content: 'ping' }],\n  providerOptions: {\n    thinking: { type: 'disabled' },   // MiniMax native toggle\n    reasoning_split: false,           // keep reasoning inline\n  },\n});\n```\n\nFor convenience, the MiniMax transport injects `thinking: { type: 'adaptive' }` + `reasoning_split: true` by default for reasoning-capable model IDs, so callers do not need to remember the wire format.\n\n## Integrating with Host Applications & Frameworks\n\n`aiplug` is completely self-contained and framework-agnostic. Host applications, multi-agent frameworks, and autonomous systems can embed `aiplug` as their universal transport engine.\n\n### Generic Adapter Pattern\n\nInstead of maintaining separate HTTP/SSE drivers for every provider, host applications can wrap `aiplug` behind a unified interface:\n\n```typescript\nimport { createLLMAdapter, type LLMAdapter, type LLMMessage } from 'aiplug';\n\nexport class AgentProviderAdapter {\n  private inner: LLMAdapter;\n\n  constructor(provider: string, model: string, apiKey?: string) {\n    this.inner = createLLMAdapter({\n      provider,\n      model,\n      apiKey,\n    });\n  }\n\n  get provider() { return this.inner.provider; }\n  get model() { return this.inner.model; }\n\n  converse = (messages: LLMMessage[], tools?: any[]) => \n    this.inner.converse(messages, tools);\n\n  converseStream = (messages: LLMMessage[], tools: any[], onChunk: (text: string) => void) =>\n    this.inner.converseStream?.(messages, tools, onChunk);\n}\n```\n\n### Capability-Gated Execution\n\nHost applications can query `transport.capabilities()` at runtime before dispatching requests to dynamically determine if vision, tool calling, embeddings, or streaming is supported:\n\n```typescript\nconst caps = await ai.capabilities();\n\nif (caps.includes('tools')) {\n  // Safe to pass function declarations to the model\n}\nif (caps.includes('image-input') || caps.includes('video-input')) {\n  // Safe to attach multimodal buffers/URLs\n}\n```\n\n## Supported providers (490+ providers, 930+ routes)\n\nThe complete, unabridged catalog of all 490+ providers, external API base URLs, default environment variables, and wire formats is maintained in:\n\n👉 **[Complete Supported Providers Directory (PROVIDERS.md)](PROVIDERS.md)**\n\n### Category Breakdown\n\n| Category | Providers | Highlights & Key Examples |\n|:---|:---:|:---|\n| **[Frontier Labs & Flagships](PROVIDERS.md#frontier-labs--flagship-apis-74)** | 74 | OpenAI, Anthropic, Gemini, DeepSeek, xAI, Mistral, MiniMax, Qwen, Baidu Qianfan |\n| **[API Gateways & Proxies](PROVIDERS.md#api-gateways--unified-proxies-130)** | 130 | OpenRouter, LiteLLM, Portkey, Vercel AI, Helicone, Cloudflare Gateway, BetterToken |\n| **[Multi-Provider Routers](PROVIDERS.md#aggregators--multi-provider-routers-20)** | 20 | AIPlug Fallback Router, 302.AI, AIMLAPI, LinkAGI, ModelRush, ZenMux |\n| **[IaaS & GPU Clouds](PROVIDERS.md#iaas-bare-metal--gpu-clouds-63)** | 63 | Groq, Cerebras, SambaNova, Together, Fireworks, DeepInfra, Nebius, Vultr |\n| **[Enterprise Cloud & Sovereign](PROVIDERS.md#enterprise-cloud--sovereign-infrastructure-43)** | 43 | AWS Bedrock (SigV4), Azure OpenAI, Google Vertex AI, Cloudflare Workers AI |\n| **[Local & Offline Runtimes](PROVIDERS.md#local-runtimes--offline-servers-28)** | 28 | AIPlug Mock Transport, Ollama, LM Studio, vLLM, llama.cpp, LocalAI, Jan |\n| **[Search & Web Retrieval](PROVIDERS.md#search--web-retrieval-apis-19)** | 19 | Perplexity, Exa Search, Tavily, Jina Reader, Serper, Firecrawl |\n| **[Audio, STT & TTS](PROVIDERS.md#audio-speech-to-text--text-to-speech-15)** | 15 | ElevenLabs, Gladia, PlayHT, Speechmatics, Fish Audio, Rev.ai |\n| **[Image & Video Generation](PROVIDERS.md#image--video-generation-20)** | 20 | RunwayML, Luma, Ideogram, Leonardo, Recraft, Haiper, Fal.ai |\n| **[Dedicated Embeddings & Vector](PROVIDERS.md#dedicated-embeddings--vector-providers-5)** | 5 | Pinecone, Voyage AI, Mixedbread, Nomic |\n| **[OAuth & Cloud Platforms](PROVIDERS.md#oauth--developer-platforms-22)** | 22 | GitHub Copilot, Databricks, Vertex Partner, Watsonx |\n| **[Free & Community Endpoints](PROVIDERS.md#free--no-auth-endpoints-10)** | 10 | Pollinations, FreeInference, DuckDuckGo, FreeAI |\n\n### Searching Providers Dynamically\n\nYou don't need to manually cross-reference base URLs or env vars. AIPlug includes instant in-memory provider search across the entire registry:\n\n```typescript\nimport { AIPlug, searchProviders } from 'aiplug';\n\n// Search in-memory by name, keyword, or category\nconst results = searchProviders('groq');\n// => [{ slug: 'groq', name: 'Groq', category: 'IaaS', defaultBaseURL: 'https://api.groq.com/openai/v1', ... }]\n```\n\nVia the CLI:\n```bash\naiplug transport list            # browse configured + active providers\naiplug models                    # list live models from the upstream provider\n```\n\nVia the HTTP API Gateway:\n```bash\ncurl http://localhost:3711/v1/providers/search?q=cerebras\n```\n\n## How it works\n\n### Custom adapters (native wire format)\n\n- **`anthropic`** — Anthropic Messages API + SSE streaming, `x-api-key` header, system message hoisting, `max_tokens` required, `tool_use` blocks mapped to `ToolCall`.\n- **`gemini`** — Google AI Studio native API + SSE, `contents[].parts[]` blocks, `systemInstruction` field, function calling via `tools[].functionDeclarations`, embeddings via `models/embedContent` (not yet wired).\n- **`ollama`** — Ollama native `/api/chat` (NDJSON streaming), `/api/embeddings`, `/api/tags`. No auth header.\n\n### OpenAI-compatible adapter (480+ providers)\n\nEvery provider marked ✓ in the [PROVIDERS.md](PROVIDERS.md) directory uses the `openai-compatible` adapter, which speaks the OpenAI Chat Completions wire format (`/v1/chat/completions`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/models`). Adding a new one is just an entry in `data/registry.json`.\n\n### Lazy loading\n\nEvery transport is dynamically `import()`-ed on first use. Nothing is bundled into the core. Add a new entry to `data/registry.json`, drop a folder at `src/providers/<slug>/`, and it works.\n\n## Design principles\n\n`aiplug` is a thin pass-through. The runtime adds **no measurable overhead** to a model request beyond the underlying HTTP call and JSON parsing — no token counting, no retries, no per-request logging, no redaction on the success path, no per-request config re-resolution.\n\nThe codebase will not introduce any of the following without a major version bump:\n\n- **Turn or message limits**: You can pass as many turns or messages as the upstream model's context window accepts.\n- **Tool call limits or caps**: No limits on the number of tool definitions or emitted tool calls (including parallel tool calls).\n- **Autonomous agent loops or recursive retries**: `aiplug` never auto-executes tools or loops on itself. Turn iteration and tool execution loops live entirely in your application.\n- **Per-request token counting or rate limiting**\n- **Per-request retries** (deliberate — use middleware or wrap the client if needed)\n- **Per-request capability re-detection**\n- **Per-request logging or telemetry hooks**\n- **Per-request redaction or sanitisation of the request body**\n- **Per-request config re-resolution**\n\nIf you need higher-level orchestration, wrap the client with a higher-level abstraction. They live \"one layer up\" by design.\n\n<details>\n<summary><strong>What runs on the request path</strong> (7 cheap operations, no I/O)</summary>\n\nFor a single `ai.chat({ ... })` call:\n\n| Step | Operation | Cost |\n|------|-----------|------|\n| 1 | `AIPlug.ready()` returns the cached transport instance | 1 truthy check + 1 map lookup |\n| 2 | Transport `chat(req, signal)` | one method call |\n| 3 | `requireModel(config)` (sync, throws if missing) | 1 string truthy check |\n| 4 | `buildBody(req)` builds the request JSON | object literal + `JSON.stringify` |\n| 5 | `fetch(url, init)` | the network call (unavoidable) |\n| 6 | `await res.json()` | parses the upstream response (unavoidable) |\n| 7 | Map response to `ChatResponse` | small object construction |\n\nFor streaming, each chunk is decoded once in the transport, then yielded. The `AIPlug.stream` wrapper does a single string comparison per chunk (`chunk.type === 'finish' \\|\\| chunk.type === 'error'`) to short-circuit on terminal chunks.\n\n**What does NOT run on the hot path** (these exist but never execute on success):\n\n- **Redaction** (`redactString`, `redactSecrets`, `redactHeaders`): only invoked from `makeError` → `AIPlugError` constructor → `buildError`. Triggers only on errors.\n- **Capability detection** (`detect()`, `probeCapabilities()`): runs once per transport+baseURL on first call, then cached in-memory.\n- **Config loading** (`load()` in `src/config.ts`): runs once at process start. The merged `AiplugConfig` is frozen in `freezeConfig()` and held by the `AIPlug` instance for its lifetime.\n- **Registry parsing** (`getRegistry()`, `validateRegistry()`): reads and parses `data/registry.json` once. Cached at module level.\n- **Dynamic `import()` of transport modules**: Node's loader caches the resolved module. After the first import for a given URL, it's a single map lookup.\n\n</details>\n\n<details>\n<summary><strong>Adding new code that touches the hot path</strong> (contributor checklist)</summary>\n\nIf you need to add logic to `Transport.chat()`, `Transport.stream()`, or any provider's request builder:\n\n1. State the cost in the PR description (e.g. \"adds ~50 ns of regex matching per request\").\n2. Avoid regex that compiles on every call. Hoist patterns to module scope.\n3. Avoid logging on the success path. Errors get full logging; success is silent.\n4. Avoid synchronous I/O. The hot path must not touch the filesystem, network (other than the upstream call), or env vars.\n5. Keep allocations small. A single object literal per request is fine; allocating per chunk in a stream is not.\n\nA test that asserts request shape (`vi.stubGlobal('fetch', stub)`) is required for any new transport method.\n\n</details>\n\n## Configuration\n\nPrecedence (highest wins):\n\n1. **CLI flags** — `--transport=openai --model=gpt-4o --api-key=xyz`\n2. **Env vars** — `AIPLUG_TRANSPORT`, `AIPLUG_API_KEY`, `AIPLUG_MODEL`, `AIPLUG_BASE_URL`, `AIPLUG_PROFILE`, `AIPLUG_CAPABILITIES`, `AIPLUG_TIMEOUT_MS`\n3. **Project file** — `./aiplug.config.json` (or `.yaml`)\n4. **Global file** — `~/.config/aiplug/config.json` (or `.yaml`)\n5. **Hardcoded defaults**\n\nExample config file:\n\n```jsonc\n{\n  \"active\": \"anthropic\",\n  \"transports\": {\n    \"anthropic\": { \"apiKey\": \"${ANTHROPIC_API_KEY}\", \"model\": \"claude-3-5-sonnet-latest\" },\n    \"openai\":    { \"apiKey\": \"${OPENAI_API_KEY}\",    \"model\": \"gpt-4o\" },\n    \"ollama\":    { \"baseURL\": \"http://localhost:11434\", \"model\": \"llama3.2\" }\n  },\n  \"profiles\": {\n    \"fast\":    { \"transport\": \"openai\",    \"model\": \"gpt-4o-mini\" },\n    \"private\": { \"transport\": \"ollama\",    \"model\": \"llama3.2\" }\n  }\n}\n```\n\n`${ENV_VAR}` substitution happens at load time. Secrets never appear in error messages or logs.\n\n## Error model\n\n```ts\nclass AIPlugError extends Error {\n  code: 'AUTH_INVALID' | 'AUTH_MISSING' | 'MODEL_NOT_FOUND' | 'RATE_LIMITED'\n       | 'NETWORK_TIMEOUT' | 'REQUEST_ABORTED' | 'INVALID_CONFIGURATION'\n       | 'TRANSPORT_UNAVAILABLE' | 'UNSUPPORTED_CAPABILITY' | 'INVALID_RESPONSE'\n       | 'STREAM_ERROR';\n  transport: string;\n  status?: number;\n  retryable: boolean;\n  details?: unknown;\n  cause?: unknown;\n}\n```\n\n`makeError({...})` maps HTTP status to code when no explicit `code` is given. Every API key, bearer token, and cookie is stripped from `message` and `details` before the error is constructed.\n\n## Adding a new provider\n\n```bash\ncp -r src/providers/_template src/providers/myprovider\n```\n\nThen edit:\n- `src/providers/myprovider/capabilities.ts` — capability list + auth scheme\n- `src/providers/myprovider/index.ts` — implement the 9 Transport methods\n- `src/providers/myprovider/README.md` — auth + sync notes\n\nAdd an entry to `data/registry.json` (or run `python3 scripts/build-registry.py` after editing `data/providers.json`):\n\n```json\n\"myprovider\": {\n  \"module\": \"./myprovider/index.js\",\n  \"class\": \"MyProviderTransport\",\n  \"defaultBaseURL\": \"https://api.myprovider.com/v1\",\n  \"auth\": \"bearer\",\n  \"authHeader\": \"Authorization\",\n  \"displayName\": \"My Provider\"\n}\n```\n\nRun `npm test` and you're done. The next `aiplug transport add myprovider` works.\n\n## Repository layout\n\n```\nsrc/\n  types.ts              # every public type\n  errors.ts             # AIPlugError + factory + secret redaction\n  transport.ts          # abstract Transport + helpers\n  client.ts             # public AIPlug client\n  config.ts             # precedence loader + profile resolution\n  streaming.ts          # SSE + NDJSON normalisers\n  capabilities.ts       # capability detector with caching\n  registry.ts           # lazy transport loader\n  index.ts              # public barrel\n  providers/            # one folder per provider\n    _template/          # boilerplate new providers copy from\n    openai/             # OpenAI Chat Completions + embeddings + images + audio\n    openai-compatible/  # any server speaking OpenAI wire format\n    anthropic/          # Anthropic Messages API + SSE\n    gemini/             # Google AI Studio native API + SSE\n    ollama/             # local-first HTTP + NDJSON streaming\n  cli/                  # CLI entrypoint + per-command files\n  server/               # OpenAI-compatible HTTP server\n\ndata/\n  registry.json         # generated, versioned transport metadata (930+ routes)\n  registry.meta.json    # UI labels, popular models, categories, websites\n  providers.json        # canonical catalog of 490+ AI providers\n\ntests/                  # Node test runner regression tests\nscripts/                # smoke + e2e + build-registry scripts\n```\n\n## Testing\n\n```bash\nnpm run typecheck   # tsc --noEmit, strict + exactOptionalPropertyTypes\nnpm run smoke       # import smoke\nnpm test            # 27 unit tests (transports, streamText, fallback, mock, introspection)\nnpm run smoke:e2e   # boot the server, hit every endpoint, verify shapes\n```\n\n## Runtime requirements\n\n- Node.js ≥ 18.17 (native `fetch`, native `Web Streams`).\n- TypeScript ≥ 5.7 with `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`.\n- One runtime dependency: `yaml` (≈ 80 kB).\n\n## Sponsors & Support\n\n`aiplug` is open-source software built to eliminate vendor lock-in and keep LLM tooling lightweight, transparent, and blazingly fast.\n\nIf you find `aiplug` useful for your projects or organization, please consider:\n- ⭐ **Starring the repository** on GitHub.\n- 💖 **Sponsoring the project** to support ongoing maintenance and new provider adapters.\n- 📢 **Sharing your experience** and letting us know what integrations you'd like to see.\n\n## Contributing\n\nContributions are warmly welcomed!\n\n- **Adding a provider:** Follow the [Adding a new provider](#adding-a-new-provider) guide.\n- **Reporting issues & bugs:** Open an issue on GitHub with reproduction steps.\n- **Submitting pull requests:** Ensure `npm run typecheck` and `npm test` pass with 0 errors before opening a PR.\n\n## License\n\nMIT License","readmeFilename":"README.md"}