npm package: @imenam/global-llm-interface
Description: A unified interface for multiple LLM providers (OpenAI, Gemini, Anthropic, Qwen) with tool-calling, streaming, and audio support
Author: imenam
Latest version: 1.2.0
Deprecated: Renamed to @imenam/unified-llm-client

# @imenam/global-llm-interface

A unified interface for multiple LLM providers — OpenAI, Gemini, Anthropic, and Qwen — with built-in support for tool-calling, streaming, multimodal inputs, and audio generation.

## Features

- **Unified API** — one interface, four providers
- **Tool-calling** — automatic execution loop with structured results
- **Streaming** — chunk-by-chunk responses via callbacks
- **Multimodal** — image and audio file inputs
- **Audio generation** — Text-to-Speech (Gemini)
- **Usage tracking** — token counts and estimated costs
- **Full TypeScript support** — exported types and `.d.ts` declarations

## Installation

```bash
npm install @imenam/global-llm-interface
```

## Supported Providers

| Provider  | Chat | Streaming | Tool-calling | Multimodal | Audio TTS |
|-----------|:----:|:---------:|:------------:|:----------:|:---------:|
| OpenAI    | ✅   | ✅        | ✅           | ✅         | ❌        |
| Gemini    | ✅   | ✅        | ✅           | ✅         | ✅        |
| Anthropic | ✅   | ✅        | ✅           | ✅         | ❌        |
| Qwen      | ✅   | ✅        | ✅           | ✅         | ❌        |

## Quick Start

Set your API keys in a `.env` file:

```env
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-...
DASHSCOPE_API_KEY=...   # for Qwen
```

```typescript
import { UnifiedLLMClient, MODELS } from "@imenam/global-llm-interface";

const client = new UnifiedLLMClient(MODELS.GPT_4O_MINI);

const response = await client.chat({
  message: "What is the capital of France?",
});

console.log(response.content); // "The capital of France is Paris."
```

## Available Models

```typescript
import { MODELS } from "@imenam/global-llm-interface";

// OpenAI
MODELS.GPT_4O_MINI
MODELS.GPT_5

// Gemini
MODELS.GEMINI_FLASH_2_5
MODELS.GEMINI_2_5_PRO
MODELS.GEMINI_3_FLASH
MODELS.GEMINI_3_PRO
MODELS.GEMINI_3_1_PRO

// Anthropic
MODELS.CLAUDE_SONNET_4_6
MODELS.CLAUDE_OPUS_4_6

// Qwen
MODELS.QWEN_VL_3
MODELS.QWEN_VL_FLASH
```

You can also pass a custom model:

```typescript
const client = new UnifiedLLMClient({
  provider: "openai",
  modelName: "gpt-4o",
});
```

## Tool-calling

Define tools with an `executor` function — the client will call them automatically and loop until the LLM produces a final text response.

```typescript
import { UnifiedLLMClient, MODELS } from "@imenam/global-llm-interface";
import type { ToolDefinition } from "@imenam/global-llm-interface";

const tools: ToolDefinition[] = [
  {
    name: "get_weather",
    description: "Get the current weather for a city",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string", description: "City name" },
      },
      required: ["city"],
    },
    executor: async ({ city }) => {
      return `The weather in ${city} is sunny and 22°C.`;
    },
  },
];

const client = new UnifiedLLMClient(MODELS.GEMINI_FLASH_2_5);

const response = await client.chat({
  message: "What's the weather like in Paris?",
  tools,
});

console.log(response.content);
```

## Streaming

```typescript
const client = new UnifiedLLMClient(MODELS.GPT_4O_MINI);

const response = await client.chat({
  message: "Tell me a short story.",
  stream: true,
  onChunk: (chunk) => {
    process.stdout.write(chunk.content ?? "");
  },
  onFinalResponse: (final) => {
    console.log("\n\nTotal tokens:", final.usage?.totalTokens);
  },
});
```

## Conversation History

The client maintains conversation history internally. Use `getHistory()` and `setHistory()` to persist or restore it:

```typescript
const client = new UnifiedLLMClient(MODELS.CLAUDE_SONNET_4_6);

await client.chat({ message: "My name is Alice." });
await client.chat({ message: "What's my name?" });
// → "Your name is Alice."

const history = client.getHistory();
// Save and restore later:
const newClient = new UnifiedLLMClient(MODELS.CLAUDE_SONNET_4_6);
newClient.setHistory(history);
```

## Multimodal Inputs

Attach images or audio files directly to a message:

```typescript
const response = await client.chat({
  message: {
    role: "user",
    content: "What do you see in this image?",
    attachedFile: "./photo.jpg",
  },
});
```

## Audio Generation (Gemini)

```typescript
import { UnifiedLLMClient, MODELS } from "@imenam/global-llm-interface";

const client = new UnifiedLLMClient(MODELS.GEMINI_FLASH_2_5);

const audio = await client.generateAudio({
  text: "Hello, this is a test of text-to-speech.",
  outputPath: "./output.wav",
  voiceConfig: { voiceName: "Kore" },
});
```

## Logging

Pass a `logger` callback to capture structured logs for every request:

```typescript
const client = new UnifiedLLMClient(MODELS.GPT_4O_MINI, {
  logger: (log) => {
    console.log(`[${log.provider}] ${log.model} — ${log.totalTokens} tokens`);
  },
});
```

## API Reference

### `new UnifiedLLMClient(model, options?)`

| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | `Model` | Model object from `MODELS` or a custom `{ provider, modelName }` |
| `options.logger` | `(log: UnifiedLog) => void` | Optional logging callback |

### `client.chat(options)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `message` | `string \| ChatMessage \| ChatMessage[]` | — | User message or history |
| `tools` | `ToolDefinition[]` | `[]` | Tools available to the LLM |
| `toolChoice` | `"auto" \| "none" \| string` | `"auto"` | Tool selection strategy |
| `stream` | `boolean` | `false` | Enable streaming |
| `onChunk` | `(chunk: StreamedChatChunk) => void` | — | Streaming chunk callback |
| `onFinalResponse` | `(res: ChatResponse) => void` | — | Final response callback |

### `ChatResponse`

```typescript
interface ChatResponse {
  content: string | null;
  toolCalls?: ToolCall[];
  usage?: {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
  raw: unknown;
}
```

## License

MIT