py-openrouter

Production-ready OpenRouter client for Node.js FREE models by default • Zero-cost dev • Smart fallbacks • Framework-ready

November 04, 2025 – v2.0.0 released ✅ All new requests are FREE by default ✅ DeepSeek & Qwen 2.5 auto-selected ✅ 100 % test coverage

🎯 FREE-First in Action

import { OpenRouterClient } from 'py-openrouter';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY!,
  appName: 'My Awesome App', // Shows in OpenRouter dashboard
});

// ← No model specified → FREE model picked
const res = await client.sendMessage('Hello, world!');

console.log('Model:', res.model);
// → deepseek/deepseek-chat

console.log('Cost:', res.cost);
// → 0

📱 App Dashboard Tracking: To see your app in OpenRouter's dashboard:

1. Visit openrouter.ai/dashboard
2. Create an app with the same appName as your config
3. Your requests will show under that app instead of "unknown"

✨ Features

• 300+ models (GPT-4o, Claude 3.5, Gemini, Llama, DeepSeek, Qwen…)
• FREE-by-default routing (deepseek/deepseek-chat or qwen/qwen-2.5-72b-instruct)
• 4 smart strategies: cost • balanced • performance • capability
• Zero-cost dev mode – never pay while testing
• Streaming (SSE) with live token chunks
• Cost tracker + budget alerts
• Express / Fastify / NestJS adapters
• Full TypeScript + 42 .d.ts files

📦 Install

npm i py-openrouter
# pnpm / yarn
pnpm add py-openrouter

🚀 Quick Start (100 % FREE)

import { OpenRouterClient } from 'py-openrouter';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY!,
});

// 1. Auto FREE
const r1 = await client.sendMessage('What is AI?');
console.log(r1.choices[0].message.content);

// 2. Pin a FREE coding model
const r2 = await client.sendMessage('Write a binary search', {
  model: 'deepseek/deepseek-chat', // FREE
});

// 3. Pin a FREE multilingual model
const r3 = await client.sendMessage('Translate to Japanese', {
  model: 'qwen/qwen-2.5-72b-instruct', // FREE
});

// 4. Production (paid) with FREE fallback
const r4 = await client.sendMessage('Critical report', {
  model: 'anthropic/claude-3.5-sonnet',
  modelSelection: { strategy: 'balanced', fallbackEnabled: true },
});

📊 Model Selection Strategies

| Strategy | Code | Result | Reason | | ---------------------- | -------------------------------- | ------------------------ | ---------------------------------------- | | cost (cheapest) | strategy: 'cost' | deepseek/deepseek-chat | "FREE model: DeepSeek Chat" | | balanced (default) | strategy: 'balanced' | deepseek or qwen | "Best FREE balanced model: score 100.50" | | performance | strategy: 'performance' | fastest FREE | low latency | | capability | capabilities: { vision: true } | vision model | auto-detect |

await client.sendMessage('Describe this image', {
  modelSelection: {
    strategy: 'capability',
    capabilities: { vision: true },
  },
});

💡 Best Practices

// Dev / Playground → $0
new OpenRouterClient({ apiKey })

// Coding tasks
model: 'deepseek/deepseek-chat'

// Multilingual
model: 'qwen/qwen-2.5-72b-instruct'

// Production (quality + safety)
model: 'anthropic/claude-3.5-sonnet',
fallbackEnabled: true   // drops to FREE on outage

📈 FREE Model Leaderboard (Nov 2025)

| Model | Cost | Speed | Quality | Best For | | ------------------------- | ---- | --------- | ------- | ----------------------- | | DeepSeek Chat | FREE | Fast | 8.8/10 | Coding, logic | | Qwen 2.5 72B Instruct | FREE | Medium | 8.9/10 | Multilingual, reasoning | | Llama 3.1 8B | FREE | Very Fast | 8.2/10 | Simple tasks | | Claude 3.5 Sonnet | $3/M | Fast | 9.5/10 | Best overall | | GPT-4o | $5/M | Fast | 9.4/10 | Complex tasks |

🔥 Streaming (FREE)

for await (const chunk of client.streamMessage('Tell a 3-chapter story')) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

💰 Cost Tracker & Budgets

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY!,
  budgets: { daily: 5, monthly: 100, alertThreshold: 0.8 },
});

client.on('budget:warning', (used, limit) => console.log(`⚠️  ${used.toFixed(2)} / ${limit}`));

const summary = client.getCostTracker().getSummary();
console.log(summary);
// → { totalCost: 0, totalRequests: 127, byModel: { ... } }

🔌 Framework Adapters

Express

import express from 'express';
import { createExpressAdapter } from 'py-openrouter';

const app = express();
const adapter = createExpressAdapter(client);

app.post('/ai/chat', adapter.chatMiddleware());
app.post('/ai/stream', adapter.streamMiddleware());
app.get('/ai/costs', adapter.costsMiddleware());

app.listen(3000);

Fastify

fastify.register(createFastifyPlugin(client), { prefix: '/ai' });

NestJS

@Module({
  providers: [{ provide: 'AI', useFactory: () => createNestJSService(client) }],
})
export class AiModule {}

🧪 Tests (all green – Nov 04 2025)

✅ TypeScript compilation: SUCCESS
✅ CJS build: 10 files
✅ ESM build: 10 files
✅ DTS build: 42 declaration files
✅ Default → deepseek/deepseek-chat (FREE)
✅ balanced → score 100.50
✅ cost → "FREE model: DeepSeek Chat"
✅ 8 examples working

📚 Documentation

• docs/FREE_MODE.md – new default behavior
• docs/MODEL_SELECTION.md
• docs/COST_OPTIMIZATION.md
• docs/FRAMEWORK_INTEGRATION.md
• docs/API_REFERENCE.md

🔑 Full Config

interface OpenRouterConfig {
  apiKey: string;
  baseURL?: string; // default: OpenRouter
  appName?: string; // Shows in OpenRouter dashboard (requires app registration)
  defaultModel?: string; // overridden by FREE default
  timeout?: number; // 30s
  maxRetries?: number; // 3
  modelSelection?: {
    strategy?: 'cost' | 'balanced' | 'performance' | 'capability';
    fallbackEnabled?: boolean; // true
    autoSelect?: boolean; // true
  };
  budgets?: {
    daily?: number;
    monthly?: number;
    alertThreshold?: number; // 0.8
  };
  cache?: { enabled?: boolean; ttl?: number };
  logging?: { level?: 'debug' | 'info' | 'warn' | 'error' };
}

🎯 Use Cases

• Chatbots – auto-FREE + paid fallback
• Code assistants – DeepSeek FREE
• Translation APIs – Qwen FREE
• Enterprise back-ends – Claude with FREE safety net

🚀 Zero-Cost Playground

// 3 lines → fully functional AI endpoint
const client = new OpenRouterClient({ apiKey: process.env.OPENROUTER_API_KEY! });
const ans = await client.sendMessage('Explain recursion in JS');
console.log(ans.choices[0].message.content);

📄 License

MIT © Payaar Team

🤝 Contributing

git clone https://github.com/3bd0-shaban/payaar-core
pnpm install
pnpm test

See CONTRIBUTING.md

🔗 Links

• npm: https://www.npmjs.com/package/py-openrouter
• GitHub: https://github.com/3bd0-shaban/payaar-core
• Issues: https://github.com/3bd0-shaban/payaar-core/issues
• OpenRouter FREE models: https://openrouter.ai/models?max_price=0

Start building AI for $0 today.

await client.sendMessage('Your idea here');