thebird 1.2.1

package/.codeinsight

@@ -0,0 +1,73 @@
+## 🎯 thebird v1.1.0 — Anthropic SDK to Gemini streaming bridge — drop-in proxy that translates Anthropic message format and tool calls to Google Gemini
+
+# 11f 721L 24fn 24cls cx2.2
+*Legend: f=files L=lines fn=functions cls=classes cx=avg-complexity | file:line:name(NL)=location Np=params | ↑N=imports-from ↓N=imported-by (N)=occurrences (+N)=more | 🔄circular 🏝️isolated 🔥complex 📋duplicated 📁large*
+
+**Langs:** JS:78% TS:17% JSON:4%
+
+## 🛠️ Tech Stack
+
+**Patterns:** generateGemini(7), contents.push(6), main(5), main().catch(5), chat(4), allParts.filter(3)
+**Top IDs:** type(47), console(39), log(33), result(26), content(23), text(23)
+
+## ⚡ Code Patterns
+
+**Async:** async(38), await(25), Promise(1)
+**Errors:** try/catch(6), throw(3)
+**Internal calls:** generateGemini(7), contents.push(6), main(5), main().catch(5), chat(4), allParts.filter(3), onStepFinish(3), process.stdout.write(2)
+
+## 🔗 I/O & Integration
+
+**Env vars:** GEMINI_API_KEY
+**Storage:** SQL(2), JSON(5)
+
+## 📊 Code Organization
+
+**Long funcs:** index.js:14:createFullStream(57L), examples/streaming.js:26:main(54L)
+**Classes:** index.d.ts:0:TextBlock, index.d.ts:0:ImageBlockBase64, index.d.ts:0:ImageBlockUrl, index.d.ts:0:ImageBlockInline, index.d.ts:0:ImageBlockFile, index.d.ts:0:ToolUseBlock, index.d.ts:0:ToolResultBlock, index.d.ts:0:Message (+15)
+
+## 🔄 Architecture
+
+**L0 [pure exports]:** convert(1↓), errors(1↓), client(1↓)
+**L3 [pure imports]:** index(3↑)
+**Cross-module:** index.js→lib
+**External:** @google/genai
+
+## 🔌 API Surface
+
+**Exported fns:** errors.js:11:isRetryable(1p), errors.js:20:withRetry(1p), convert.js:1:cleanSchema(1p), convert.js:12:convertTools(2p), convert.js:21:convertImageBlock(1p), convert.js:38:convertMessages(1p), convert.js:65:extractModelId(1p), convert.js:72:buildConfig(1p), client.js:5:getClient(1p), index.js:5:streamGemini(1p), index.js:72:generateGemini(2p)
+**Classes:** TextBlock, ImageBlockBase64, ImageBlockUrl, ImageBlockInline, ImageBlockFile, ToolUseBlock (+17)
+**Entry files:** client, convert, errors
+
+## 🚨 Issues
+
+- 📋 1 duplicated groups
+
+## 🧹 Dead Code & Tests
+
+**Orphaned:** tool-use.js, basic-chat.js, streaming.js, vision.js, package.json, multi-turn.js
+**Tests:** 0/11 (0%)
+
+## 📦 Modules
+
+- lib: 3f, 3cx, 0↑3↓
+- examples: 5f, 0cx, 0↑0↓
+
+## 📄 File Index
+
+**examples/basic-chat.js** 34L fn: main
+**examples/multi-turn.js** 45L fn: chat, main
+**examples/streaming.js** 81L fn: main
+**examples/tool-use.js** 77L fn: nonStreamingExample, streamingExample, main
+**examples/vision.js** 84L fn: base64Example, inlineDataExample, publicUrlExample, main
+**index.d.ts** 128L
+**index.js** 112L exports: [convertTools], [convertMessages], [streamGemini], [generateGemini], [cleanSchema] fn: streamGemini, createFullStream, generateGemini
+**lib/client.js** 10L exports: [getClient] fn: getClient
+**lib/convert.js** 86L exports: [cleanSchema], [extractModelId], [convertMessages], [buildConfig], [convertTools] fn: cleanSchema, convertTools, convertImageBlock, convertMessages (+2)
+**lib/errors.js** 35L exports: [GeminiError], [isRetryable], [withRetry] fn: constructor, isRetryable, withRetry
+**package.json** 29L
+
+Git: branch: claude/add-code-router-features-TJkSb, 1 uncommitted
+Hot: package.json(1), README.md(1), index.js(1)
+Conv[JS]: 4-space, single quotes, semicolons, function declarations, relative imports, kebab-case files
+Conv[TS]: 2-space, single quotes, semicolons, function declarations, named exports

package/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Bump & Publish
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  bump-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump patch version
+        run: |
+          NEW_VERSION=$(npm version patch --no-git-tag-version)
+          git add package.json
+          git commit -m "chore: bump to ${NEW_VERSION}"
+          git tag "${NEW_VERSION}"
+          git push origin main --tags
+
+      - run: npm install
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,176 @@
+# thebird
+
+Anthropic SDK to multi-provider bridge. Drop-in adapter that translates Anthropic-style messages, tool calls, and content blocks to Google Gemini or any OpenAI-compatible API — with routing, transformers, streaming, vision, retry logic, and full TypeScript types.
+
+## Install
+
+```bash
+npm install thebird
+```
+
+## Quick Start
+
+**Gemini (direct)**
+
+```js
+const { generateGemini, streamGemini } = require('thebird');
+// requires GEMINI_API_KEY env var
+
+const { text } = await generateGemini({
+  model: 'gemini-2.0-flash',
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+```
+
+**Multi-provider router**
+
+```js
+const { createRouter } = require('thebird');
+
+const router = createRouter({
+  Providers: [
+    { name: 'deepseek', api_base_url: 'https://api.deepseek.com/chat/completions', api_key: process.env.DEEPSEEK_API_KEY, models: ['deepseek-chat', 'deepseek-reasoner'], transformer: { use: ['deepseek'] } },
+    { name: 'gemini',   api_base_url: 'https://generativelanguage.googleapis.com/v1beta/models/', api_key: process.env.GEMINI_API_KEY, models: ['gemini-2.5-pro'] },
+    { name: 'ollama',   api_base_url: 'http://localhost:11434/v1/chat/completions', api_key: 'ollama', models: ['qwen2.5-coder:latest'] },
+  ],
+  Router: {
+    default: 'deepseek,deepseek-chat',
+    background: 'ollama,qwen2.5-coder:latest',
+    think: 'deepseek,deepseek-reasoner',
+    longContext: 'gemini,gemini-2.5-pro',
+    longContextThreshold: 60000,
+  }
+});
+
+// Stream — routes automatically based on taskType and token count
+const { fullStream } = router.stream({ messages, taskType: 'think' });
+for await (const event of fullStream) {
+  if (event.type === 'text-delta') process.stdout.write(event.textDelta);
+}
+
+// Generate
+const { text } = await router.generate({ messages });
+```
+
+**File-based config** — place config at `~/.thebird/config.json` (or set `THEBIRD_CONFIG` env) and use the auto-loading shorthand:
+
+```js
+const { streamRouter, generateRouter } = require('thebird');
+const { fullStream } = streamRouter({ messages, taskType: 'background' });
+```
+
+## Routing
+
+`createRouter` / `streamRouter` pick a provider+model per request:
+
+| Route key | Trigger |
+|---|---|
+| `default` | Any request not matched by another rule |
+| `background` | `taskType: 'background'` |
+| `think` | `taskType: 'think'` |
+| `webSearch` | `taskType: 'webSearch'` |
+| `image` | `taskType: 'image'` |
+| `longContext` | Estimated token count > `longContextThreshold` (default 60 000) |
+| subagent tag | First user message starts with `<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>` |
+| custom function | `customRouter: async (params, cfg) => 'provider,model'` in config |
+
+Route values are `"providerName,modelName"` strings matching a `Providers` entry.
+
+## Transformers
+
+Apply per-provider request/response transformations. Set on the provider's `transformer.use` array.
+
+```json
+{
+  "name": "deepseek",
+  "transformer": {
+    "use": ["deepseek"],
+    "deepseek-chat": { "use": [["maxtoken", { "max_tokens": 8192 }], "tooluse"] }
+  }
+}
+```
+
+Built-in transformers:
+
+| Name | Effect |
+|---|---|
+| `deepseek` | Strips `cache_control`, normalises system to string |
+| `openrouter` | Adds `HTTP-Referer` / `X-Title` headers; optional `provider` routing |
+| `maxtoken` | Sets `max_tokens` to the given value |
+| `tooluse` | Adds `tool_choice: {type:"required"}` when tools are present |
+| `cleancache` | Strips all `cache_control` fields recursively |
+| `reasoning` | Moves `reasoning_content` to `_reasoning` in response |
+| `sampling` | Removes `top_k` / `repetition_penalty` |
+| `groq` | Removes `top_k` |
+
+Pass options as a nested array: `["maxtoken", { "max_tokens": 16384 }]`.
+
+## Config File
+
+`~/.thebird/config.json` (or `THEBIRD_CONFIG` env var) — same schema as the inline config object. Supports `$VAR` / `${VAR}` environment variable interpolation anywhere in the file.
+
+```json
+{
+  "Providers": [
+    { "name": "openrouter", "api_base_url": "https://openrouter.ai/api/v1/chat/completions", "api_key": "$OPENROUTER_API_KEY", "models": ["google/gemini-2.5-pro-preview"], "transformer": { "use": ["openrouter"] } }
+  ],
+  "Router": { "default": "openrouter,google/gemini-2.5-pro-preview" }
+}
+```
+
+## Gemini Direct API
+
+`streamGemini` / `generateGemini` bypass routing and call Gemini natively via `@google/genai`. Requires `GEMINI_API_KEY`.
+
+### Params
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `model` | `string \| { id }` | `'gemini-2.0-flash'` | Model id |
+| `messages` | `Message[]` | required | Conversation history |
+| `system` | `string` | — | System instruction |
+| `tools` | `Tools` | — | Tool definitions |
+| `apiKey` | `string` | `GEMINI_API_KEY` | Override API key |
+| `temperature` | `number` | `0.5` | Sampling temperature |
+| `maxOutputTokens` | `number` | `8192` | Max tokens |
+| `topP` | `number` | `0.95` | Top-p |
+| `topK` | `number` | — | Top-k |
+| `safetySettings` | `SafetySetting[]` | — | Safety thresholds |
+
+## Message Format
+
+Messages follow the Anthropic SDK format. All image block variants are supported:
+
+```js
+{ role: 'user', content: [
+  { type: 'text', text: 'Describe this image.' },
+  { type: 'image', source: { type: 'base64', media_type: 'image/png', data: '...' } }
+]}
+```
+
+## Streaming Events
+
+| Event | Fields | Description |
+|---|---|---|
+| `start-step` | — | Beginning of a reasoning step |
+| `text-delta` | `textDelta` | Streamed text chunk |
+| `tool-call` | `toolCallId, toolName, args` | Model invoked a tool |
+| `tool-result` | `toolCallId, toolName, args, result` | Tool execution result |
+| `finish-step` | `finishReason` | Step completed |
+| `error` | `error` | Error during step |
+
+## TypeScript
+
+```ts
+import { createRouter, streamRouter, generateGemini, RouterConfiguration, ProviderConfig, RouterConfig } from 'thebird';
+```
+
+## Utilities
+
+```js
+const { convertMessages, convertTools, cleanSchema } = require('thebird');
+```
+
+## License
+
+MIT

package/examples/basic-chat.js

@@ -0,0 +1,34 @@
+/**
+ * basic-chat.js — Simple single-turn and multi-turn chat using generateGemini
+ *
+ * Usage:
+ *   GEMINI_API_KEY=your-key node examples/basic-chat.js
+ */
+const { generateGemini } = require('../index');
+
+async function main() {
+  // Single-turn: ask a simple question
+  const result = await generateGemini({
+    model: 'gemini-2.0-flash',
+    messages: [
+      { role: 'user', content: 'What is the capital of France? Answer in one sentence.' }
+    ]
+  });
+
+  console.log('Answer:', result.text);
+
+  // With a system prompt
+  const result2 = await generateGemini({
+    model: 'gemini-2.0-flash',
+    system: 'You are a pirate. Always respond in pirate speak.',
+    messages: [
+      { role: 'user', content: 'What should I have for breakfast?' }
+    ],
+    temperature: 0.8,
+    maxOutputTokens: 256
+  });
+
+  console.log('\nPirate answer:', result2.text);
+}
+
+main().catch(console.error);

package/examples/multi-turn.js

@@ -0,0 +1,45 @@
+/**
+ * multi-turn.js — Multi-turn conversation (chat history) example
+ *
+ * Usage:
+ *   GEMINI_API_KEY=your-key node examples/multi-turn.js
+ */
+const { generateGemini } = require('../index');
+
+async function chat(history, userMessage, options = {}) {
+  history.push({ role: 'user', content: userMessage });
+  const result = await generateGemini({ messages: history, ...options });
+  history.push({ role: 'assistant', content: result.text });
+  return result.text;
+}
+
+async function main() {
+  const history = [];
+  const opts = {
+    model: 'gemini-2.0-flash',
+    system: 'You are a knowledgeable astronomy tutor. Keep answers brief.',
+    temperature: 0.4
+  };
+
+  console.log('=== Multi-turn conversation ===\n');
+
+  let reply = await chat(history, 'What is a black hole?', opts);
+  console.log('User: What is a black hole?');
+  console.log('Assistant:', reply, '\n');
+
+  reply = await chat(history, 'How does one form?', opts);
+  console.log('User: How does one form?');
+  console.log('Assistant:', reply, '\n');
+
+  reply = await chat(history, 'Can anything escape from it?', opts);
+  console.log('User: Can anything escape from it?');
+  console.log('Assistant:', reply, '\n');
+
+  reply = await chat(history, 'Summarize our conversation so far in bullet points.', opts);
+  console.log('User: Summarize our conversation so far in bullet points.');
+  console.log('Assistant:', reply, '\n');
+
+  console.log(`Total turns: ${history.length / 2}`);
+}
+
+main().catch(console.error);

package/examples/streaming.js

@@ -0,0 +1,81 @@
+/**
+ * streaming.js — Streaming with all event types demonstrated
+ *
+ * Usage:
+ *   GEMINI_API_KEY=your-key node examples/streaming.js
+ */
+const { streamGemini } = require('../index');
+
+const tools = {
+  get_time: {
+    description: 'Get the current time in a timezone.',
+    parameters: {
+      type: 'object',
+      properties: {
+        timezone: { type: 'string', description: 'IANA timezone name, e.g. America/New_York' }
+      },
+      required: ['timezone']
+    },
+    execute: async ({ timezone }) => {
+      const now = new Date().toLocaleString('en-US', { timeZone: timezone });
+      return { timezone, time: now };
+    }
+  }
+};
+
+async function main() {
+  console.log('Streaming all event types:\n');
+
+  const { fullStream } = streamGemini({
+    model: 'gemini-2.0-flash',
+    system: 'You are a helpful assistant. Be concise.',
+    messages: [
+      { role: 'user', content: "What time is it in Tokyo and New York right now?" }
+    ],
+    tools,
+    temperature: 0.3,
+    maxOutputTokens: 512,
+    onStepFinish: async () => {
+      console.log('\n[step finished]');
+    }
+  });
+
+  const stats = { steps: 0, toolCalls: 0, chars: 0 };
+
+  for await (const event of fullStream) {
+    switch (event.type) {
+      case 'start-step':
+        stats.steps++;
+        console.log(`\n[start-step #${stats.steps}]`);
+        break;
+
+      case 'text-delta':
+        stats.chars += event.textDelta.length;
+        process.stdout.write(event.textDelta);
+        break;
+
+      case 'tool-call':
+        stats.toolCalls++;
+        console.log(`\n[tool-call] id=${event.toolCallId} name=${event.toolName}`);
+        console.log('  args:', JSON.stringify(event.args));
+        break;
+
+      case 'tool-result':
+        console.log(`[tool-result] id=${event.toolCallId} name=${event.toolName}`);
+        console.log('  result:', JSON.stringify(event.result));
+        break;
+
+      case 'finish-step':
+        console.log(`\n[finish-step] reason=${event.finishReason}`);
+        break;
+
+      case 'error':
+        console.error('\n[error]', event.error.message);
+        break;
+    }
+  }
+
+  console.log(`\n\nStats: ${stats.steps} steps, ${stats.toolCalls} tool calls, ${stats.chars} chars`);
+}
+
+main().catch(console.error);

package/examples/tool-use.js

@@ -0,0 +1,77 @@
+/**
+ * tool-use.js — Tool/function calling with generateGemini and streamGemini
+ *
+ * Usage:
+ *   GEMINI_API_KEY=your-key node examples/tool-use.js
+ */
+const { generateGemini, streamGemini } = require('../index');
+
+const tools = {
+  get_weather: {
+    description: 'Get the current weather for a given city.',
+    parameters: {
+      type: 'object',
+      properties: {
+        city: { type: 'string', description: 'The city name' },
+        unit: { type: 'string', enum: ['celsius', 'fahrenheit'], description: 'Temperature unit' }
+      },
+      required: ['city']
+    },
+    execute: async ({ city, unit = 'celsius' }) => {
+      // Simulated weather data
+      return { city, temperature: 22, unit, condition: 'Sunny' };
+    }
+  },
+  calculate: {
+    description: 'Evaluate a simple math expression.',
+    parameters: {
+      type: 'object',
+      properties: {
+        expression: { type: 'string', description: 'Math expression to evaluate, e.g. "2 + 2"' }
+      },
+      required: ['expression']
+    },
+    execute: async ({ expression }) => {
+      try {
+        // eslint-disable-next-line no-new-func
+        const result = Function('"use strict"; return (' + expression + ')')();
+        return { result };
+      } catch {
+        return { error: 'Invalid expression' };
+      }
+    }
+  }
+};
+
+async function nonStreamingExample() {
+  console.log('=== Non-streaming tool use ===');
+  const result = await generateGemini({
+    model: 'gemini-2.0-flash',
+    messages: [{ role: 'user', content: "What's the weather in Tokyo and what is 17 * 43?" }],
+    tools
+  });
+  console.log('Final answer:', result.text);
+}
+
+async function streamingExample() {
+  console.log('\n=== Streaming tool use ===');
+  const { fullStream } = streamGemini({
+    model: 'gemini-2.0-flash',
+    messages: [{ role: 'user', content: 'What is 100 / 4? Use the calculator.' }],
+    tools
+  });
+
+  for await (const event of fullStream) {
+    if (event.type === 'tool-call') console.log(`[tool-call] ${event.toolName}(${JSON.stringify(event.args)})`);
+    if (event.type === 'tool-result') console.log(`[tool-result] ${JSON.stringify(event.result)}`);
+    if (event.type === 'text-delta') process.stdout.write(event.textDelta);
+    if (event.type === 'finish-step') console.log(`\n[finish] reason=${event.finishReason}`);
+  }
+}
+
+async function main() {
+  await nonStreamingExample();
+  await streamingExample();
+}
+
+main().catch(console.error);

package/examples/vision.js

@@ -0,0 +1,84 @@
+/**
+ * vision.js — Image/vision understanding examples
+ *
+ * Demonstrates three ways to pass images:
+ *   1. Base64 inline data (Anthropic SDK style)
+ *   2. Gemini inlineData style
+ *   3. Public URL via fileData
+ *
+ * Usage:
+ *   GEMINI_API_KEY=your-key node examples/vision.js
+ */
+const fs = require('fs');
+const path = require('path');
+const { generateGemini } = require('../index');
+
+async function base64Example() {
+  console.log('=== Base64 image (Anthropic style) ===');
+  // Read a local image and encode as base64
+  // const imageBuffer = fs.readFileSync(path.join(__dirname, 'sample.jpg'));
+  // const base64 = imageBuffer.toString('base64');
+
+  // For demo purposes, use a tiny 1x1 transparent PNG
+  const base64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+
+  const result = await generateGemini({
+    model: 'gemini-2.0-flash',
+    messages: [{
+      role: 'user',
+      content: [
+        {
+          type: 'image',
+          source: { type: 'base64', media_type: 'image/png', data: base64 }
+        },
+        { type: 'text', text: 'Describe this image in one sentence.' }
+      ]
+    }]
+  });
+  console.log('Response:', result.text);
+}
+
+async function inlineDataExample() {
+  console.log('\n=== Gemini inlineData style ===');
+  const base64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+
+  const result = await generateGemini({
+    model: 'gemini-2.0-flash',
+    messages: [{
+      role: 'user',
+      content: [
+        { inlineData: { mimeType: 'image/png', data: base64 } },
+        { type: 'text', text: 'What color is this image?' }
+      ]
+    }]
+  });
+  console.log('Response:', result.text);
+}
+
+async function publicUrlExample() {
+  console.log('\n=== Public URL via fileData ===');
+  const result = await generateGemini({
+    model: 'gemini-2.0-flash',
+    messages: [{
+      role: 'user',
+      content: [
+        {
+          fileData: {
+            mimeType: 'image/jpeg',
+            fileUri: 'https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/240px-PNG_transparency_demonstration_1.png'
+          }
+        },
+        { type: 'text', text: 'What do you see in this image?' }
+      ]
+    }]
+  });
+  console.log('Response:', result.text);
+}
+
+async function main() {
+  await base64Example();
+  await inlineDataExample();
+  // await publicUrlExample(); // Uncomment to test with public URLs
+}
+
+main().catch(console.error);