krisspy-ai 1.1.17

package/README.md

@@ -0,0 +1,432 @@
+# krisspy-ai
+
+Official library for building AI agents on the **Krisspy** platform.
+
+## What is krisspy-ai?
+
+`krisspy-ai` enables you to create **custom agents** using the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk), while making it compatible with many models through an integrated proxy system.
+
+### Key Features
+
+- **Multi-providers**: Anthropic, OpenAI, Gemini, AWS Bedrock, Azure AI, Z.AI
+- **Advanced reasoning**: Extended thinking supported across all providers
+- **Code execution**: Agents can execute code in real-time
+- **Sub-agents**: Build multi-agent architectures
+- **Skills**: Use Anthropic Skills (Office files, etc.)
+- **MCP**: Connect external tools via MCP protocol
+- **GenAI Services**: Image generation, video generation, speech-to-text, text-to-speech
+
+All of this **without worrying about the underlying model** - the proxy automatically translates requests.
+
+## Installation
+
+```bash
+npm install krisspy-ai
+```
+
+## Quick Start
+
+### With Anthropic (direct)
+
+```typescript
+import { query } from 'krisspy-ai';
+
+for await (const event of query({
+  prompt: 'Analyze this code and suggest improvements',
+  options: {
+    provider: 'anthropic',
+    apiKey: 'sk-ant-...',
+    model: 'sonnet'  // haiku, sonnet, opus
+  }
+})) {
+  console.log(event);
+}
+```
+
+### With AWS Bedrock
+
+```typescript
+import { query } from 'krisspy-ai';
+
+for await (const event of query({
+  prompt: 'Create an optimized sorting function',
+  options: {
+    provider: 'bedrock',
+    accessKeyId: 'AKIA...',
+    secretAccessKey: '...',
+    region: 'us-west-2',
+    model: 'sonnet'  // haiku, haiku-4.5, sonnet, sonnet-4, sonnet-4.5, opus, opus-4, opus-4.5
+  }
+})) {
+  console.log(event);
+}
+```
+
+### With OpenAI (via proxy)
+
+```typescript
+import { query } from 'krisspy-ai';
+
+for await (const event of query({
+  prompt: 'Explain design patterns to me',
+  options: {
+    provider: 'openai',
+    apiKey: 'sk-...',
+    model: 'gpt-4o'
+  }
+})) {
+  console.log(event);
+}
+```
+
+## Supported Providers
+
+| Provider | Description | Models |
+|----------|-------------|--------|
+| `anthropic` | Direct Anthropic API | haiku, sonnet, opus |
+| `bedrock` | AWS Bedrock (Claude) | haiku, sonnet, opus + 4/4.5 versions |
+| `azure` | Azure AI Foundry | gpt-4o, gpt-5.2 |
+| `openai` | OpenAI via proxy | gpt-4o, gpt-5.2, o1, o3 |
+| `gemini` | Google Gemini via proxy | gemini-2.5-pro, gemini-2.5-flash |
+| `zai` | Z.AI via proxy | glm-4.7 |
+| `zai_direct` | Z.AI Anthropic endpoint | haiku, sonnet, opus |
+
+## Bedrock Models
+
+| Alias | Bedrock Model ID |
+|-------|------------------|
+| `haiku` | `global.anthropic.claude-haiku-4-5-20251001-v1:0` |
+| `haiku-4.5` | `global.anthropic.claude-haiku-4-5-20251001-v1:0` |
+| `sonnet` | `global.anthropic.claude-sonnet-4-20250514-v1:0` |
+| `sonnet-4` | `global.anthropic.claude-sonnet-4-20250514-v1:0` |
+| `sonnet-4.5` | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |
+| `opus` | `global.anthropic.claude-opus-4-5-20251101-v1:0` |
+| `opus-4` | `global.anthropic.claude-opus-4-20250514-v1:0` |
+| `opus-4.5` | `global.anthropic.claude-opus-4-5-20251101-v1:0` |
+
+---
+
+## GenAI Services
+
+`krisspy-ai` includes generative AI services for image, video, and audio. These services work with both **OpenAI** and **Azure OpenAI**.
+
+### Image Generation
+
+Generate images using GPT-Image-1 (OpenAI) or Azure DALL-E/GPT-Image.
+
+```typescript
+import { generateImage } from 'krisspy-ai';
+
+// With OpenAI
+const result = await generateImage({
+  service: 'openai',
+  apiKey: 'sk-...',
+  deploymentName: 'gpt-image-1',  // or 'dall-e-3'
+  prompt: 'A cute baby polar bear playing in the snow',
+  size: '1024x1024',  // '1024x1024', '1792x1024', '1024x1792'
+});
+
+console.log(result.data[0].url);
+
+// With Azure OpenAI
+const azureResult = await generateImage({
+  service: 'azure',
+  apiKey: 'your-azure-key',
+  baseUrl: 'https://your-resource.openai.azure.com',
+  deploymentName: 'gpt-image-1',
+  apiVersion: '2024-02-15-preview',
+  prompt: 'A futuristic city at sunset',
+  size: '1792x1024',
+  quality: 'hd',
+});
+```
+
+### Video Generation (Sora)
+
+Generate videos using OpenAI Sora or Azure Sora.
+
+```typescript
+import { generateVideo } from 'krisspy-ai';
+
+// Async generator with status updates
+for await (const event of generateVideo({
+  service: 'openai',
+  apiKey: 'sk-...',
+  deploymentName: 'sora',
+  prompt: 'Woolly mammoths walking through a snowy tundra',
+  duration: 5,  // seconds
+  width: 1920,
+  height: 1080,
+})) {
+  if (event.type === 'status') {
+    console.log(`Status: ${event.status.status}, Progress: ${event.status.progress}%`);
+  } else if (event.type === 'result') {
+    console.log(`Video ready: ${event.data.generations[0].url}`);
+  }
+}
+
+// With Azure OpenAI
+for await (const event of generateVideo({
+  service: 'azure',
+  apiKey: 'your-azure-key',
+  baseUrl: 'https://your-resource.openai.azure.com',
+  deploymentName: 'sora-2',
+  prompt: 'A drone flying over mountains at sunrise',
+  duration: 10,
+})) {
+  // Same event handling
+}
+```
+
+### Speech-to-Text (Transcription)
+
+Transcribe audio using Whisper or GPT-4o-transcribe.
+
+```typescript
+import { transcribe } from 'krisspy-ai';
+import fs from 'fs';
+
+const audioBuffer = fs.readFileSync('audio.mp3');
+
+// With OpenAI
+const result = await transcribe({
+  service: 'openai',
+  apiKey: 'sk-...',
+  deploymentName: 'whisper-1',  // or 'gpt-4o-transcribe'
+  audio: audioBuffer,
+  language: 'en',
+  responseFormat: 'verbose_json',
+  timestampGranularities: ['word', 'segment'],
+});
+
+console.log(result.text);
+console.log(result.words);     // Word-level timestamps
+console.log(result.segments);  // Segment-level timestamps
+
+// With Azure OpenAI
+const azureResult = await transcribe({
+  service: 'azure',
+  apiKey: 'your-azure-key',
+  baseUrl: 'https://your-resource.openai.azure.com',
+  deploymentName: 'whisper',
+  apiVersion: '2025-03-01-preview',
+  audio: audioBuffer,
+});
+
+// With speaker diarization (Azure gpt-4o-transcribe-diarize)
+const diarizedResult = await transcribe({
+  service: 'azure',
+  apiKey: 'your-azure-key',
+  baseUrl: 'https://your-resource.openai.azure.com',
+  deploymentName: 'gpt-4o-transcribe-diarize',
+  apiVersion: '2025-03-01-preview',
+  audio: audioBuffer,
+});
+
+console.log(diarizedResult.utterances);  // Speaker-separated segments
+```
+
+### Text-to-Speech (TTS)
+
+Convert text to speech using TTS-1, TTS-1-HD, or GPT-4o-mini-tts.
+
+```typescript
+import { synthesize } from 'krisspy-ai';
+import fs from 'fs';
+
+// With OpenAI
+const result = await synthesize({
+  service: 'openai',
+  apiKey: 'sk-...',
+  deploymentName: 'tts-1',  // 'tts-1', 'tts-1-hd', 'gpt-4o-mini-tts'
+  input: 'Hello! Welcome to krisspy-ai.',
+  voice: 'nova',  // alloy, ash, coral, echo, fable, nova, onyx, sage, shimmer
+  speed: 1.0,     // 0.25 to 4.0
+  responseFormat: 'mp3',
+});
+
+fs.writeFileSync('output.mp3', result.audio);
+
+// With Azure OpenAI (only supports: alloy, echo, fable, nova, onyx, shimmer)
+const azureResult = await synthesize({
+  service: 'azure',
+  apiKey: 'your-azure-key',
+  baseUrl: 'https://your-resource.openai.azure.com',
+  deploymentName: 'tts',
+  apiVersion: '2025-03-01-preview',
+  input: 'Hello from Azure!',
+  voice: 'nova',
+});
+
+// With voice styling (gpt-4o-mini-tts only)
+const styledResult = await synthesize({
+  service: 'openai',
+  apiKey: 'sk-...',
+  deploymentName: 'gpt-4o-mini-tts',
+  input: 'This is exciting news!',
+  voice: 'coral',
+  instructions: 'Speak with enthusiasm and energy',
+});
+```
+
+### GenAI Service Options
+
+#### Image Generation Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `service` | `'openai' \| 'azure'` | Provider to use |
+| `apiKey` | `string` | API key |
+| `baseUrl` | `string` | Base URL (required for Azure) |
+| `deploymentName` | `string` | Model/deployment name |
+| `prompt` | `string` | Image description |
+| `size` | `string` | `'1024x1024'`, `'1792x1024'`, `'1024x1792'` |
+| `quality` | `string` | `'standard'` or `'hd'` |
+| `n` | `number` | Number of images (1-10) |
+
+#### Video Generation Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `service` | `'openai' \| 'azure'` | Provider to use |
+| `apiKey` | `string` | API key |
+| `baseUrl` | `string` | Base URL (required for Azure) |
+| `deploymentName` | `string` | Model/deployment name |
+| `prompt` | `string` | Video description |
+| `duration` | `number` | Duration in seconds |
+| `width` | `number` | Video width (default: 1920) |
+| `height` | `number` | Video height (default: 1080) |
+| `nVariants` | `number` | Number of variants |
+
+#### Transcription Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `service` | `'openai' \| 'azure'` | Provider to use |
+| `apiKey` | `string` | API key |
+| `baseUrl` | `string` | Base URL (required for Azure) |
+| `deploymentName` | `string` | Model/deployment name |
+| `audio` | `Buffer \| string` | Audio data or file path |
+| `language` | `string` | ISO-639-1 language code |
+| `responseFormat` | `string` | `'json'`, `'text'`, `'srt'`, `'vtt'`, `'verbose_json'` |
+| `timestampGranularities` | `string[]` | `['word']`, `['segment']`, or both |
+
+#### TTS Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `service` | `'openai' \| 'azure'` | Provider to use |
+| `apiKey` | `string` | API key |
+| `baseUrl` | `string` | Base URL (required for Azure) |
+| `deploymentName` | `string` | Model/deployment name |
+| `input` | `string` | Text to synthesize (max 4096 chars) |
+| `voice` | `string` | Voice name |
+| `speed` | `number` | Speed (0.25 to 4.0) |
+| `responseFormat` | `string` | `'mp3'`, `'opus'`, `'aac'`, `'flac'`, `'wav'`, `'pcm'` |
+| `instructions` | `string` | Voice styling (gpt-4o-mini-tts only) |
+
+---
+
+## Advanced Options
+
+```typescript
+const options = {
+  // Provider
+  provider: 'anthropic',
+  apiKey: 'sk-ant-...',
+  model: 'sonnet',
+  baseUrl: 'https://api.anthropic.com',
+
+  // Extended Thinking
+  maxThinkingTokens: 10000,
+
+  // MCP Servers
+  mcpServers: {
+    filesystem: {
+      command: 'npx',
+      args: ['-y', '@anthropic-ai/mcp-server-filesystem', '/path']
+    },
+    http_server: {
+      type: 'http',
+      url: 'http://localhost:3001/mcp'
+    }
+  },
+
+  // Skills (Office files)
+  betas: ['skills-2025-10-02'],
+
+  // Attachments
+  attachments: {
+    images: [{ type: 'url', url: 'https://...' }],
+    files: [{ type: 'pdf', media_type: 'application/pdf', data: 'base64...' }]
+  },
+
+  // Execution limits
+  maxTurns: 50,
+  maxBudgetUsd: 5.00,
+
+  // Tools
+  allowedTools: ['Read', 'Edit', 'Bash', 'WebSearch'],
+  permissionMode: 'acceptEdits',
+
+  // AWS Bedrock
+  accessKeyId: 'AKIA...',
+  secretAccessKey: '...',
+  region: 'us-west-2',
+
+  // Azure AI
+  deploymentName: 'my-deployment',
+  apiVersion: '2024-02-15-preview'
+};
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        krisspy-ai                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
+│  │   Anthropic  │    │   Bedrock    │    │    Azure     │  │
+│  │   (direct)   │    │   (native)   │    │   (proxy)    │  │
+│  └──────────────┘    └──────────────┘    └──────────────┘  │
+│                                                             │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
+│  │   OpenAI     │    │   Gemini     │    │    Z.AI      │  │
+│  │   (proxy)    │    │   (proxy)    │    │   (proxy)    │  │
+│  └──────────────┘    └──────────────┘    └──────────────┘  │
+│                                                             │
+│                    ┌──────────────────┐                    │
+│                    │  Claude Agent    │                    │
+│                    │      SDK         │                    │
+│                    └──────────────────┘                    │
+│                            │                               │
+│         ┌──────────────────┼──────────────────┐           │
+│         ▼                  ▼                  ▼           │
+│  ┌────────────┐    ┌────────────┐    ┌────────────┐      │
+│  │ Reasoning  │    │   Code     │    │    MCP     │      │
+│  │            │    │ Execution  │    │   Tools    │      │
+│  └────────────┘    └────────────┘    └────────────┘      │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │              GenAI Services                          │  │
+│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌────────┐  │  │
+│  │  │  Image  │  │  Video  │  │   STT   │  │  TTS   │  │  │
+│  │  │ (DALL-E)│  │ (Sora)  │  │(Whisper)│  │        │  │  │
+│  │  └─────────┘  └─────────┘  └─────────┘  └────────┘  │  │
+│  │         OpenAI  |  Azure OpenAI                      │  │
+│  └─────────────────────────────────────────────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## License
+
+ISC
+
+## Links
+
+- [Krisspy Platform](https://krisspy.ai)
+- [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk)
+- [API Documentation](https://docs.krisspy.ai)