hydra-aidirector 1.6.0 → 1.6.2

package/README.md

@@ -1,399 +1,310 @@
-# hydra-aidirector
-
-The official Node.js/TypeScript SDK for [Hydra](https://hydrai.dev) — a high-performance AI API gateway.
-
-[![npm version](https://badge.fury.io/js/hydra-aidirector.svg)](https://www.npmjs.com/package/hydra-aidirector)
-[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://www.typescriptlang.org/)
-
-## Why Hydra?
-
-| Problem | Hydra Solution |
-|---------|----------------|
-| LLM outages break your app | 🔄 **Automatic Failover** – Seamless fallback between providers |
-| High latency & costs | ⚡ **God-Tier Caching** – Hybrid Redis + DB cache with AI-directed scoping |
-| Malformed JSON responses | 🛡️ **Self-Healing AI** – Auto-repair JSON, strip markdown, extract from prose |
-| Schema compliance issues | ✅ **Strict JSON Mode** – Force models to conform to your schema or fail |
-| No visibility into usage | 📊 **Detailed Analytics** – Track tokens, latency, and costs per model |
-
----
-
-## Installation
-
-```bash
-npm install hydra-aidirector
-# or
-pnpm add hydra-aidirector
-# or
-yarn add hydra-aidirector
-```
-
----
-
-## Quick Start
-
-```typescript
-import { Hydra } from 'hydra-aidirector';
-
-const client = new Hydra({
-  secretKey: process.env.HYDRA_SECRET_KEY!, // hyd_sk_...
-  baseUrl: 'https://your-instance.vercel.app',
-});
-
-// Basic generation
-const result = await client.generate({
-  chainId: 'my-chain',
-  prompt: 'Generate 5 user profiles as JSON',
-});
-
-if (result.success) {
-  console.log(result.data.valid); // Parsed, schema-validated objects
-}
-```
-
----
-
-## Core Features
-
-### 🔄 Automatic Failover
-Define fallback chains in your dashboard. If Gemini fails, Hydra automatically tries OpenRouter, Claude, etc.
-
-### 🛡️ Self-Healing JSON
-LLMs sometimes return broken JSON. Hydra extracts and repairs it automatically:
-
-```typescript
-const result = await client.generate({ chainId: 'x', prompt: 'Get user' });
-
-if (result.meta.recovered) {
-  console.log('JSON was malformed but healed!');
-  console.log(result.data.healingReport);
-  // [{ original: "{name: 'foo'", healed: { name: "foo" }, fixes: ["Added closing brace"] }]
-}
-```
-
-### ✅ Strict JSON Mode vs Self-Healing
-
-Hydra's self-healing JSON repair **works in both modes**. The difference is how the model behaves:
-
-| Mode | Model Behavior | Healing Role |
-|------|----------------|--------------|
-| **Strict** (`strictJson: true`) | Model is **forced** to output pure JSON via native API constraints. Output is already clean. | Safety net — rarely needed since output is constrained. |
-| **Non-Strict** (`strictJson: false`) | Model outputs best-effort JSON (may include markdown, prose, or broken syntax). | Primary mechanism — extracts and repairs JSON from messy output. |
-
-```typescript
-// Strict mode - model constrained to pure JSON
-await client.generate({
-  chainId: 'gemini-chain',
-  prompt: 'Extract invoice data',
-  schema: invoiceSchema,
-  strictJson: true, // No markdown, no explanations
-});
-
-// Non-strict mode - flexible output, Hydra heals as needed
-await client.generate({
-  chainId: 'any-chain',
-  prompt: 'Generate a creative story with metadata',
-  schema: storySchema,
-  strictJson: false, // Allow model to be creative, Hydra extracts JSON
-});
-```
-
----
-
-## Streaming (Recommended for Large Responses)
-
-Process JSON objects as they arrive — perfect for UIs that need instant feedback:
-
-```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
-
-Process multiple prompts in parallel with automatic error handling:
-
-```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}`);
-```
-
----
-
-## Caching
-
-### Cache Scope
-Control how responses are cached:
-
-```typescript
-// Global cache (shared across users - default)
-await client.generate({ chainId: 'x', prompt: 'Facts', cacheScope: 'global' });
-
-// User-scoped cache (private to authenticated user)
-await client.generate({ chainId: 'x', prompt: 'My profile', cacheScope: 'user' });
-
-// Skip cache entirely
-await client.generate({ chainId: 'x', prompt: 'Random', cacheScope: 'skip' });
-```
-
-### Cache Quality
-Control the trade-off between cache hit rate and precision:
-
-| Level | Behavior |
-|-------|----------|
-| `STANDARD` | Balanced fuzzy matching. Good for most cases. |
-| `HIGH` | Stricter matching. Higher quality hits, lower hit rate. |
-| `MAX_EFFICIENCY` | Aggressive matching. Maximum cost savings, less precision. |
-
-```typescript
-await client.generate({
-  chainId: 'my-chain',
-  prompt: 'Generate report',
-  cacheQuality: 'MAX_EFFICIENCY', // Maximize cache hits
-});
-```
-
-### AI-Directed Caching
-The AI can override cache scope by including a `_cache` directive in its output:
-
-```json
-{
-  "data": { "...": "..." },
-  "_cache": { "scope": "user" }
-}
-```
-
-The directive is automatically stripped from your final response.
-
----
-
-## File Attachments
-
-Upload documents for analysis. Hydra handles type detection and model compatibility:
-
-```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',
-  }],
-});
-```
-
----
-
-## Request Cancellation
-
-Cancel long-running requests with `AbortSignal`:
-
-```typescript
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 5000); // Cancel after 5s
-
-try {
-  const result = await client.generate({
-    chainId: 'my-chain',
-    prompt: 'Long task',
-    signal: controller.signal,
-  });
-} catch (error) {
-  if (error instanceof TimeoutError) {
-    console.log('Request was cancelled');
-  }
-}
-```
-
----
-
-## Thinking Mode
-
-Enable reasoning models to show their thought process:
-
-```typescript
-const result = await client.generate({
-  chainId: 'reasoning-chain',
-  prompt: 'Solve this complex problem step by step',
-  options: {
-    thinkingMode: true,
-  },
-});
-```
-
----
-
-## Webhooks
-
-Register callbacks for async notifications:
-
-```typescript
-// Register
-await client.registerWebhook({
-  requestId: 'req_123',
-  url: 'https://your-domain.com/webhooks/hydra',
-  secret: 'your-webhook-secret',
-  retryCount: 3,
-});
-
-// Manage
-const webhooks = await client.listWebhooks();
-await client.updateWebhook('webhook_id', { retryCount: 5 });
-await client.unregisterWebhook('webhook_id');
-```
-
----
-
-## Configuration Reference
-
-### Client Options
-
-| 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 in ms (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 sharing behavior |
-| `cacheQuality` | `'STANDARD' \| 'HIGH' \| 'MAX_EFFICIENCY'` | `'STANDARD'` | Cache match precision |
-| `strictJson` | `boolean` | `true` | Force strict JSON mode |
-| `signal` | `AbortSignal` | - | Cancellation signal |
-| `maxRetries` | `number` | Client default | Override retries |
-| `requestId` | `string` | Auto-generated | Custom request ID |
-| `files` | `FileAttachment[]` | - | File attachments |
-| `useOptimized` | `boolean` | `true` | Use 3-step cost-saving flow |
-| `noCache` | `boolean` | `false` | Skip cache entirely |
-
----
-
-## 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,
-  isRetryableError,
-} from 'hydra-aidirector';
-
-try {
-  const result = await client.generate({ chainId: 'x', prompt: 'y' });
-} 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(`Timed out after ${error.timeoutMs}ms`);
-  } else if (error instanceof AuthenticationError) {
-    console.log('Invalid API key');
-  } else if (error instanceof WorkerError) {
-    console.log('Worker failed - will retry');
-  } else if (error instanceof FileProcessingError) {
-    console.log(`File error: ${error.reason} - ${error.filename}`);
-  } else if (isRetryableError(error)) {
-    console.log('Transient error - safe to retry');
-  }
-}
-```
-
----
-
-## Pricing
-
-**BYOK (Bring Your Own Key)** — You pay AI providers directly. Hydra charges only for API access:
-
-| Tier | Price/mo | Requests | Overage |
-|------|----------|----------|---------|
-| Free | $0 | 1,000 | Blocked |
-| Starter | $9 | 25,000 | $0.50/1K |
-| Pro | $29 | 100,000 | $0.40/1K |
-| Scale | $79 | 500,000 | $0.30/1K |
-
----
-
-## TypeScript Support
-
-Full type safety with comprehensive types:
-
-```typescript
-import type {
-  GenerateOptions,
-  GenerateResult,
-  StreamCallbacks,
-  FileAttachment,
-  ChainInfo,
-  ModelInfo,
-} from 'hydra-aidirector';
-```
-
----
-
-## Requirements
-
-- Node.js 18+
-- TypeScript 5+ (optional but recommended)
-
----
-
-## License
-
-MIT © [Hydra](https://hydrai.dev)
+# hydra-aidirector
+
+One client. One secret. One AI gateway.
+
+`hydra-aidirector` is the official TypeScript SDK for [Hydra](https://hydrai.dev/docs). It gives your app one clean path for generation, failover chains, structured output, scoped caching, streaming, usage, health, and webhooks without making you glue providers together by hand.
+
+## Install
+
+```bash
+bun add hydra-aidirector
+```
+
+```bash
+npm install hydra-aidirector
+```
+
+## Quick Start
+
+```ts
+import { Hydra } from 'hydra-aidirector';
+
+const client = new Hydra({
+  secretKey: process.env.HYDRA_SECRET_KEY!, // hyd_sk_...
+  baseUrl: process.env.HYDRA_BASE_URL!,     // https://your-hydra-instance.com
+});
+
+const result = await client.generate({
+  chainId: 'support-replies',
+  prompt: 'Return 3 short onboarding emails as JSON.',
+});
+
+if (result.success) {
+  console.log(result.data.valid);
+} else {
+  console.error(result.error);
+}
+```
+
+## Why Teams Use It
+
+- One typed client for generation, streaming, usage, health, and webhooks.
+- Automatic failover across the models in your chain.
+- Structured output recovery when providers return noisy JSON.
+- Cache controls that let you keep shared prompts fast and sensitive prompts private.
+- One request trail to inspect when latency, cost, or provider behavior starts drifting.
+
+## How Generation Works
+
+Hydra uses the optimized 3-step flow by default for simple requests. That path keeps the fast lane lean by moving the long model call out of the request path that fronts your app.
+
+When a request needs 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 path yourself:
+
+```ts
+await client.generate({
+  chainId: 'support-replies',
+  prompt: 'Return a fresh answer',
+  useOptimized: false,
+});
+```
+
+## Structured Output
+
+Use `schema` when the response shape matters:
+
+```ts
+const result = await client.generate({
+  chainId: 'invoice-parser',
+  prompt: 'Extract the invoice fields.',
+  schema: {
+    invoiceNumber: 'string',
+    amount: 'number',
+    currency: 'string',
+  },
+  strictJson: true,
+});
+```
+
+If the provider comes back with malformed JSON, Hydra will still try to recover the payload before the request fails.
+
+## Cache Control
+
+Use request-level cache controls when freshness or privacy matters:
+
+```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,
+});
+```
+
+Tune cache matching when you want better reuse:
+
+```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);
+```
+
+## File Attachments
+
+Send files as base64 and let Hydra handle the processing path:
+
+```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, health.version);
+```
+
+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('Your 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+
+- Bun 1.0+ or another runtime with `fetch`
+- TypeScript 5+ for typed projects
+
+## Get Started
+
+- Docs: [hydrai.dev/docs](https://hydrai.dev/docs)
+- Dashboard: [hydrai.dev/signin](https://hydrai.dev/signin)
+- Contact: [hydrai.dev/contact](https://hydrai.dev/contact)
+
+## License
+
+MIT