hydra-aidirector 1.4.2 → 1.6.1

package/README.md

@@ -1,302 +1,304 @@
-# hydra-aidirector - Client SDK
-# hydra-aidirector
-
-The official Node.js/TypeScript client for [Hydra](https://hydrai.dev).
-
-Hydra is a high-performance AI API gateway that provides:
-- 🔄 **Automatic Failover**: Never let an LLM outage break your app
-- ⚡ **God-Tier Caching**: Reduce costs and latency with smart response caching
-- 🛡️ **Self-Healing AI**: Auto-extract JSON, strip markdown, and repair malformed responses with `healingReport`
-- 🧠 **Thinking Mode**: Support for reasoning models like Gemini 2.0 Flash Thinking
-- 📊 **Detailed Usage**: Track token usage, latency, and costs per model
-
-## Installation
-
-```bash
-npm install hydra-aidirector
-# or
-pnpm add hydra-aidirector
-```
-
-## Quick Start
-
-```typescript
-import { Hydra } from 'hydra-aidirector';
-
-const ai = new Hydra({
-  secretKey: process.env.HYDRA_SECRET_KEY!,
-  baseUrl: 'https://your-instance.vercel.app',
-});
-
-// Generate content
-const result = await ai.generate({
-  chainId: 'my-chain',
-  prompt: 'Generate 5 user profiles',
-});
-
-if (result.success) {
-  console.log(result.data.valid);
-}
-```
-
-## Features
-
-- 🔐 **HMAC Authentication** - Secure request signing
-- ⚡ **3-Step Architecture** - Token → Worker → Complete (minimizes costs)
-- 📎 **File Attachments** - Upload and process documents
-- 🔄 **Automatic Retries** - Exponential backoff on failures
-- 💾 **Smart Caching** - Two-tier (user/global) cache with AI-directed scoping
-- 🎯 **TypeScript** - Full type safety with comprehensive types
-- 🛑 **Request Cancellation** - Support for AbortSignal
-- 🪝 **Webhooks** - Async notification callbacks
-
-## Streaming (Recommended for Large Responses)
-
-```typescript
-await client.generateStream(
-  {
-    chainId: 'my-chain',
-    prompt: 'Generate 100 product descriptions',
-  },
-  {
-    onObject: (obj, index) => {
-      console.log(`Object ${index}:`, obj);
-      renderToUI(obj); // Render immediately!
-    },
-    onComplete: (result) => {
-      console.log(`Done! ${result.objectCount} objects`);
-    },
-    onError: (error) => {
-      console.error('Stream failed:', error);
-    },
-  }
-);
-```
-
-## Batch Generation
-
-```typescript
-const result = await client.generateBatch('my-chain', [
-  { id: 'item1', prompt: 'Describe product A' },
-  { id: 'item2', prompt: 'Describe product B' },
-  { id: 'item3', prompt: 'Describe product C' },
-]);
-
-console.log(`Processed ${result.summary.succeeded}/${result.summary.total}`);
-```
-
-## Request Cancellation
-
-```typescript
-const controller = new AbortController();
-
-// Cancel after 5 seconds
-setTimeout(() => controller.abort(), 5000);
-
-try {
-  const result = await client.generate({
-    chainId: 'my-chain',
-    prompt: 'Long running prompt',
-    signal: controller.signal,
-  });
-} catch (error) {
-  if (error instanceof TimeoutError) {
-    console.log('Request was cancelled');
-  }
-}
-```
-
-## Cache Control
-
-```typescript
-// Global cache (shared across users - default)
-const result = await client.generate({
-  chainId: 'my-chain',
-  prompt: 'Static content',
-  cacheScope: 'global',
-});
-
-// User-scoped cache (private to user)
-const userResult = await client.generate({
-  chainId: 'my-chain',
-  prompt: 'Personalized content',
-  cacheScope: 'user',
-});
-
-// Skip cache entirely
-const freshResult = await client.generate({
-  chainId: 'my-chain',
-  prompt: 'Always fresh',
-  cacheScope: 'skip',
-});
-```
-
-## File Attachments
-
-```typescript
-import fs from 'fs';
-
-const fileBuffer = fs.readFileSync('report.pdf');
-
-const result = await client.generate({
-  chainId: 'document-analysis',
-  prompt: 'Summarize this document',
-  files: [{
-    data: fileBuffer.toString('base64'),
-    filename: 'report.pdf',
-    mimeType: 'application/pdf',
-  }],
-});
-```
-
-## Webhooks
-
-```typescript
-// Register a webhook
-await client.registerWebhook({
-  requestId: 'req_123',
-  url: 'https://your-domain.com/webhooks/hydra',
-  secret: 'your-webhook-secret',
-  retryCount: 3,
-});
-
-// List webhooks
-const webhooks = await client.listWebhooks();
-
-// Update webhook
-await client.updateWebhook('webhook_id', { retryCount: 5 });
-
-// Unregister webhook
-await client.unregisterWebhook('webhook_id');
-```
-
-## Thinking Mode (Reasoning Models)
-
-```typescript
-const result = await client.generate({
-  chainId: 'reasoning-chain',
-  prompt: 'Solve this complex problem step by step',
-  options: {
-    thinkingMode: true, // Shows model reasoning process
-  },
-});
-```
-
-## Configuration
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `secretKey` | `string` | **required** | Your API key (`hyd_sk_...`) |
-| `baseUrl` | `string` | `http://localhost:3000` | API base URL |
-| `timeout` | `number` | `600000` | Request timeout (10 min) |
-| `maxRetries` | `number` | `3` | Max retry attempts |
-| `debug` | `boolean` | `false` | Enable debug logging |
-
-## Generate Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `chainId` | `string` | **required** | Fallback chain ID |
-| `prompt` | `string` | **required** | The prompt to send |
-| `schema` | `object` | - | JSON schema for validation |
-| `cacheScope` | `'global' \| 'user' \| 'skip'` | `'global'` | Cache behavior |
-| `signal` | `AbortSignal` | - | Cancellation signal |
-| `maxRetries` | `number` | Client setting | Override retries |
-| `requestId` | `string` | Auto-generated | Custom request ID |
-| `files` | `FileAttachment[]` | - | File attachments |
-| `useOptimized` | `boolean` | `true` | Use 3-step flow |
-
-## API Methods
-
-| Method | Description |
-|--------|-------------|
-| `generate(options)` | Generate content with fallback chain |
-| `generateStream(options, callbacks)` | Stream JSON objects in real-time |
-| `generateBatch(chainId, items)` | Process multiple prompts |
-| `listModels()` | List available AI models |
-| `listChains()` | List your fallback chains |
-| `getUsage(options)` | Get usage statistics |
-| `health()` | Check API health |
-| `healthDetailed()` | Get detailed component health |
-| `registerWebhook(config)` | Register async webhook |
-| `unregisterWebhook(id)` | Remove a webhook |
-| `listWebhooks()` | List all webhooks |
-| `updateWebhook(id, updates)` | Modify webhook config |
-
-## Error Handling
-
-```typescript
-import { 
-  RateLimitError,
-  TimeoutError,
-  AuthenticationError,
-  QuotaExceededError,
-  WorkerError,
-  FileProcessingError,
-} from 'hydra-aidirector';
-
-try {
-  const result = await client.generate({ ... });
-} catch (error) {
-  if (error instanceof RateLimitError) {
-    console.log(`Retry after ${error.retryAfterMs}ms`);
-  } else if (error instanceof QuotaExceededError) {
-    console.log(`Quota exceeded: ${error.used}/${error.limit} (${error.tier})`);
-  } else if (error instanceof TimeoutError) {
-    console.log(`Request timed out after ${error.timeoutMs}ms`);
-  } else if (error instanceof AuthenticationError) {
-    console.log('Invalid API key');
-  } else if (error instanceof WorkerError) {
-    console.log('Worker processing failed - will retry');
-  } else if (error instanceof FileProcessingError) {
-    console.log(`File error: ${error.reason} - ${error.filename}`);
-  }
-}
-```
-
-## Self-Healing Reports
-
-When `hydra-aidirector` fixes a malformed JSON response, it includes a `healingReport` in the data object:
-
-```typescript
-const result = await client.generate({ ... });
-
-if (result.success && result.meta.recovered) {
-  console.log('JSON was malformed but healed!');
-  console.log(result.data.healingReport); 
-  // [{ original: "{name: 'foo'", healed: {name: "foo"}, fixes: ["Added missing brace"] }]
-}
-```
-
-## AI-Directed Caching
-
-The AI can control caching by including a `_cache` directive in its JSON output:
-
-```json
-{
-  "data": { ... },
-  "_cache": { "scope": "user" }
-}
-```
-
-Scopes:
-- `global` - Share response across all users (default)
-- `user` - Cache per-user only
-- `skip` - Do not cache this response
-
-The directive is automatically stripped from the final response.
-
-## Pricing
-
-BYOK (Bring Your Own Key) - You pay for AI costs directly to providers.
-
-| Tier | Price | Requests | Overage |
-|------|-------|----------|---------|
-| Free | $0 | 1K | Blocked |
-| Starter | $9 | 25K | $0.50/1K |
-| Pro | $29 | 100K | $0.40/1K |
-| Scale | $79 | 500K | $0.30/1K |
-
-## License
-
-MIT
+# hydra-aidirector
+
+The official TypeScript SDK for [Hydra](https://hydrai.dev).
+
+Hydra gives your app one stable AI gateway instead of a pile of provider glue. You send one request. Hydra handles routing, failover, cache behavior, JSON recovery, and operational visibility behind the same API.
+
+## Install
+
+```bash
+bun add hydra-aidirector
+# or
+npm install hydra-aidirector
+# or
+pnpm add hydra-aidirector
+# or
+yarn add hydra-aidirector
+```
+
+## Quick Start
+
+```ts
+import { Hydra } from 'hydra-aidirector';
+
+const client = new Hydra({
+  secretKey: process.env.HYDRA_SECRET_KEY!, // hyd_sk_...
+  baseUrl: 'https://your-hydra-instance.com',
+});
+
+const result = await client.generate({
+  chainId: 'support-replies',
+  prompt: 'Write 3 concise onboarding emails as JSON',
+});
+
+if (result.success) {
+  console.log(result.data.valid);
+}
+```
+
+## What You Get
+
+- Automatic failover across the models in your chain.
+- JSON extraction and repair when providers return noisy output.
+- User-safe caching with request-level cache controls.
+- Streaming for long responses.
+- Batch generation for parallel prompt execution.
+- Usage, health, and webhook management from the same client.
+
+## Generation Modes
+
+Hydra uses the optimized 3-step flow by default for simple requests. That keeps the fast path cheap and responsive.
+
+When you ask for features that require the full server pipeline, the SDK automatically falls back to the legacy endpoint. That includes:
+
+- `schema`
+- `noCache`
+- `cacheScope`
+- `cacheQuality`
+- `strictJson`
+- `maxRetries`
+
+You can also force the legacy endpoint yourself:
+
+```ts
+await client.generate({
+  chainId: 'support-replies',
+  prompt: 'Return a fresh answer',
+  useOptimized: false,
+});
+```
+
+## Structured Output
+
+Use `schema` when you want validated JSON back:
+
+```ts
+const result = await client.generate({
+  chainId: 'invoice-parser',
+  prompt: 'Extract invoice fields',
+  schema: {
+    invoiceNumber: 'string',
+    amount: 'number',
+    currency: 'string',
+  },
+  strictJson: true,
+});
+```
+
+If the provider returns malformed JSON, Hydra will still try to recover it before the request fails.
+
+## Cache Control
+
+Use request-level cache controls when the prompt should behave differently from the default path:
+
+```ts
+await client.generate({
+  chainId: 'account-summary',
+  prompt: 'Summarize this customer account',
+  cacheScope: 'user',
+});
+
+await client.generate({
+  chainId: 'pricing-faq',
+  prompt: 'Return the current pricing summary',
+  cacheScope: 'global',
+});
+
+await client.generate({
+  chainId: 'one-off',
+  prompt: 'Generate a fresh variant',
+  noCache: true,
+});
+```
+
+You can also tune cache matching:
+
+```ts
+await client.generate({
+  chainId: 'reporting',
+  prompt: 'Generate the weekly report',
+  cacheQuality: 'HIGH',
+});
+```
+
+## Streaming
+
+Stream parsed objects as they arrive:
+
+```ts
+await client.generateStream(
+  {
+    chainId: 'catalog-generator',
+    prompt: 'Generate 50 product blurbs as JSON',
+  },
+  {
+    onObject: (object, index) => {
+      console.log(index, object);
+    },
+    onComplete: (result) => {
+      console.log(result.objectCount);
+    },
+    onError: (error) => {
+      console.error(error);
+    },
+  }
+);
+```
+
+## Batch Generation
+
+Run multiple prompts in one call:
+
+```ts
+const batch = await client.generateBatch('catalog-generator', [
+  { id: 'a', prompt: 'Describe product A' },
+  { id: 'b', prompt: 'Describe product B' },
+  { id: 'c', prompt: 'Describe product C' },
+]);
+
+console.log(batch.summary);
+```
+
+## Files
+
+Send file attachments as base64:
+
+```ts
+import fs from 'node:fs';
+
+const file = fs.readFileSync('report.pdf');
+
+const result = await client.generate({
+  chainId: 'document-analysis',
+  prompt: 'Summarize this report',
+  files: [
+    {
+      data: file.toString('base64'),
+      filename: 'report.pdf',
+      mimeType: 'application/pdf',
+    },
+  ],
+});
+```
+
+## Usage and Health
+
+Get normalized usage metrics:
+
+```ts
+const usage = await client.getUsage({
+  startDate: new Date('2026-03-01T00:00:00.000Z'),
+  endDate: new Date('2026-04-01T00:00:00.000Z'),
+});
+
+console.log(usage.totalRequests);
+console.log(usage.cachedRequests);
+console.log(usage.byModelList);
+```
+
+Basic health:
+
+```ts
+const health = await client.health();
+console.log(health.ok, health.latencyMs);
+```
+
+Detailed health requires an admin key:
+
+```ts
+const detailed = await client.healthDetailed();
+console.log(detailed.status);
+```
+
+## Webhooks
+
+Register, list, update, and remove webhooks from the SDK:
+
+```ts
+await client.registerWebhook({
+  requestId: 'req_123',
+  url: 'https://example.com/webhooks/hydra',
+  secret: 'super-secret-webhook-key',
+  retryCount: 3,
+});
+
+const webhooks = await client.listWebhooks();
+
+await client.updateWebhook(webhooks[0].id, {
+  retryCount: 5,
+});
+
+await client.unregisterWebhook(webhooks[0].id);
+```
+
+## Cancellation
+
+Cancel long-running requests with `AbortController`:
+
+```ts
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5000);
+
+await client.generate({
+  chainId: 'long-job',
+  prompt: 'Generate a long report',
+  signal: controller.signal,
+});
+```
+
+## Error Handling
+
+```ts
+import {
+  AuthenticationError,
+  QuotaExceededError,
+  RateLimitError,
+  TimeoutError,
+  isRetryableError,
+} from 'hydra-aidirector';
+
+try {
+  await client.generate({
+    chainId: 'support-replies',
+    prompt: 'Write a response',
+  });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('The Hydra secret key is invalid.');
+  } else if (error instanceof QuotaExceededError) {
+    console.error(error.tier, error.used, error.limit);
+  } else if (error instanceof RateLimitError) {
+    console.error(error.retryAfterMs);
+  } else if (error instanceof TimeoutError) {
+    console.error(error.timeoutMs);
+  } else if (isRetryableError(error)) {
+    console.error('Safe to retry.');
+  }
+}
+```
+
+## API Surface
+
+- `generate(options)`
+- `generateStream(options, callbacks)`
+- `generateBatch(chainId, items, options?)`
+- `listModels()`
+- `listChains()`
+- `getUsage(options?)`
+- `health()`
+- `healthDetailed()`
+- `registerWebhook(config)`
+- `listWebhooks()`
+- `updateWebhook(id, updates)`
+- `unregisterWebhook(id)`
+- `withConfig(overrides)`
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5+ for typed projects
+
+## License
+
+MIT