Qiniu AI SDK

# Qiniu AI SDK

<div align="center">

[![npm version](https://img.shields.io/npm/v/@bowenqt/qiniu-ai-sdk.svg?style=flat-square)](https://www.npmjs.com/package/@bowenqt/qiniu-ai-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org/)

**TypeScript SDK for Qiniu Cloud AI Services**

[English](./README.md) | [中文](./README.zh-CN.md) | [COOKBOOK](./COOKBOOK.md)

</div>

---

## ✨ Features

### Core AI Modules
- 🚀 **Chat Completions** — OpenAI-compatible interface with streaming support
- 🖼️ **Image Generation** — Kling, Gemini models with unified sync/async API
- 🎥 **Video Generation** — Kling, Sora, Veo models with first/last frame control
- 🔍 **Web Search** — Real-time web search integration
- 📝 **OCR** — High-precision text recognition for images and PDFs
- 🎤 **ASR** — Multi-language speech recognition (95%+ accuracy in noisy environments)
- 🔊 **TTS** — Text-to-speech synthesis with multiple voice options
- 🛡️ **Content Moderation** — Image and video censorship with scene-based detection

### Agentic Layer
- 🤖 **generateText** — Multi-step tool execution with Zod schema support
- 📊 **generateObject/streamObject** — Structured JSON output with streaming
- 🧠 **AgentGraph** — State machine-based graph execution
- 🏭 **createAgent** — Reusable agent factory with configurable behaviors

### Advanced Capabilities
- 📋 **Skills Injection** — Markdown-based agent knowledge (Claude Skills compatible)
- 🔗 **MCP Client** — Model Context Protocol with stdio + HTTP + OAuth 2.0 support
- 🖥️ **MCP Server** — Built-in Qiniu MCP server for OCR/Censor/Vframe tools
- 💾 **Checkpointer** — State persistence (Memory, Redis, PostgreSQL, Kodo)
- 🧠 **Memory Manager** — Short-term + long-term memory with LLM summarization
- ✅ **Tool Approval (HITL)** — Human-in-the-loop for sensitive operations
- ⏸️ **Interrupt/Resume** — Resumable execution with checkpoint-based restore
- 📊 **OpenTelemetry Tracing** — Distributed tracing with per-node spans
- 🔌 **Vercel AI SDK Adapter** — Drop-in replacement for Vercel AI SDK

---

## 📦 Installation

```bash
npm install @bowenqt/qiniu-ai-sdk
```

### Optional Peer Dependencies

```bash
# For Vercel AI SDK integration
npm install @ai-sdk/provider ai

# For Zod schema validation
npm install zod

# For Redis checkpointer
npm install ioredis

# For PostgreSQL checkpointer
npm install pg
```

---

## 🚀 Quick Start

```typescript
import { QiniuAI } from '@bowenqt/qiniu-ai-sdk';

const client = new QiniuAI({
  apiKey: 'Sk-xxxxxxxxxxxxxxxx',
});

// Chat completion
const chat = await client.chat.create({
  model: 'gemini-2.5-flash',
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(chat.choices[0].message.content);

// Streaming chat
const stream = await client.chat.createStream({
  model: 'gemini-2.5-flash',
  messages: [{ role: 'user', content: 'Explain AI briefly' }],
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
```

---

## 🤖 Agentic Usage

### Tool Execution with generateText

```typescript
import { QiniuAI, generateText } from '@bowenqt/qiniu-ai-sdk';
import { z } from 'zod';

const client = new QiniuAI({ apiKey: process.env.QINIU_API_KEY || '' });

const result = await generateText({
  client,
  model: 'gemini-2.5-flash',
  prompt: 'What is 42 * 17?',
  tools: {
    calculate: {
      description: 'Perform calculation',
      parameters: z.object({
        operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
        a: z.number(),
        b: z.number(),
      }),
      execute: async ({ operation, a, b }) => {
        const ops = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b };
        return ops[operation];
      },
    },
  },
  maxSteps: 3,
});

console.log(result.text);       // Final answer
console.log(result.toolCalls);  // Tool calls made
```

### Structured Output

```typescript
import { generateObject } from '@bowenqt/qiniu-ai-sdk';
import { z } from 'zod';

const result = await generateObject({
  client,
  model: 'gemini-2.5-flash',
  prompt: 'Generate a product listing',
  schema: z.object({
    name: z.string(),
    price: z.number(),
    category: z.string(),
  }),
});

console.log(result.object); // Typed object
```

---

## 🖼️ Image & Video Generation

```typescript
// Image generation (async task)
const imageResult = await client.image.generate({
  model: 'kling-v2',
  prompt: 'A futuristic city at sunset',
});
const finalImage = await client.image.waitForResult(imageResult);
console.log(finalImage.data?.[0].url);

// Video generation with first/last frame
const videoTask = await client.video.create({
  model: 'kling-video-o1',
  prompt: 'A cat jumps from one ledge to another',
  frames: {
    first: { url: 'https://example.com/start.jpg' },
    last: { url: 'https://example.c

... (truncated)