@krutai/ai-provider 0.1.0 → 0.2.2

package/AI_REFERENCE.md

@@ -3,54 +3,65 @@
 ## Package Overview
 
 - **Name**: `@krutai/ai-provider`
-- **Version**: `0.1.0`
-- **Purpose**: AI provider for KrutAI — wraps `@openrouter/sdk` with a `krutAI()` factory, key validation, and a configurable default model
+- **Version**: `0.2.2`
+- **Purpose**: AI provider for KrutAI — fetch-based client for your deployed LangChain server with API key validation
 - **Entry**: `src/index.ts` → `dist/index.{js,mjs,d.ts}`
-- **Build**: `tsup` (CJS + ESM, all deps external)
+- **Build**: `tsup` (CJS + ESM, no external SDK deps)
 
-## Dependency Architecture
+## Architecture
 
 ```
-@krutai/ai-provider@0.1.0
-├── dependency: @openrouter/sdk  ← Official OpenRouter TypeScript SDK (external in tsup)
-└── peerDep:    krutai           ← Core utilities
+@krutai/ai-provider@0.2.2
+ └── peerDep: krutai  (core utilities)
+
+AI Flow:
+  User App → krutAI() / KrutAIProvider
+           → POST {serverUrl}/validate   (key validation)
+           → POST {serverUrl}/generate   (single response)
+           → POST {serverUrl}/stream     (SSE streaming)
+           → POST {serverUrl}/chat       (multi-turn)
+           → Your deployed LangChain server
 ```
 
-> **Important for AI**: Do NOT bundle `@openrouter/sdk` inline. It must stay external in tsup.
-
 ## File Structure
 
 ```
 packages/ai-provider/
 ├── src/
 │   ├── index.ts      # krutAI() factory + all exports
-│   ├── client.ts     # KrutAIProvider class
+│   ├── client.ts     # KrutAIProvider class (fetch-based)
 │   ├── types.ts      # KrutAIProviderConfig, GenerateOptions, ChatMessage, DEFAULT_MODEL
-│   └── validator.ts  # OpenRouter key format + service validation
+│   └── validator.ts  # API key format check + server validation
 ├── package.json
 ├── tsconfig.json
 └── tsup.config.ts
 ```
 
-## Default Model
+## Server Endpoints (Expected by This Package)
 
-```
-qwen/qwen3-235b-a22b-thinking-2507
-```
+| Endpoint | Method | Body | Response |
+|---|---|---|---|
+| `/validate` | POST | `{ apiKey }` | `{ valid: true/false, message? }` |
+| `/generate` | POST | `{ prompt, model, system?, maxTokens?, temperature? }` | `{ text/content/message: string }` |
+| `/stream` | POST | `{ prompt, model, system?, maxTokens?, temperature? }` | SSE stream `data: <chunk>` |
+| `/chat` | POST | `{ messages, model, maxTokens?, temperature? }` | `{ text/content/message: string }` |
 
-Exported as `DEFAULT_MODEL` constant. Users override via `config.model` or per-call `options.model`.
+All AI endpoints receive `Authorization: Bearer <apiKey>` and `x-api-key: <apiKey>` headers.
 
 ## Main Exports
 
-### `krutAI(config?)` ← PRIMARY API
-
-Drop-in factory. Mirrors `krutAuth` from `@krutai/auth`.
+### `krutAI(config)` ← PRIMARY API
 
 ```typescript
 import { krutAI } from '@krutai/ai-provider';
 
-const ai = krutAI(); // OPENROUTER_API_KEY from env, default model
-await ai.initialize();
+const ai = krutAI({
+  apiKey: process.env.KRUTAI_API_KEY!,
+  // uses http://localhost:8000 by default for local development
+  // serverUrl: 'https://ai.yourapp.com',
+});
+
+await ai.initialize(); // validates key with server
 
 const text = await ai.generate('Hello!');
 ```
@@ -62,51 +73,32 @@ import { KrutAIProvider } from '@krutai/ai-provider';
 
 const ai = new KrutAIProvider({
   apiKey: process.env.KRUTAI_API_KEY!,
-  openRouterApiKey: process.env.OPENROUTER_API_KEY!,
-  model: 'openai/gpt-4o',       // optional
-  validateOnInit: true,          // default
-  validationEndpoint: undefined, // TODO: wire up POST route
+  // serverUrl: 'https://ai.yourapp.com', // Optional: defaults to localhost:8000
+  model: 'gpt-4o',         // optional, default: 'default'
+  validateOnInit: true,     // default: true
 });
 
 await ai.initialize();
 ```
 
 **Methods:**
-- `initialize(): Promise<void>` — validates key + sets up OpenRouter client
+- `initialize(): Promise<void>` — validates key against server, marks provider ready
 - `generate(prompt, opts?): Promise<string>` — single response (non-streaming)
-- `stream(prompt, opts?)` — async iterable of SSE chunks (`chunk.choices[0].delta.content`)
+- `stream(prompt, opts?)` — `AsyncGenerator<string>` — SSE-based streaming
 - `chat(messages, opts?): Promise<string>` — multi-turn conversation
 - `getModel(): string` — active model name
-- `getClient(): OpenRouter` — raw `@openrouter/sdk` client (advanced)
 - `isInitialized(): boolean`
 
-## Underlying SDK Call
-
-The package calls `@openrouter/sdk` using the following structure:
-
-```typescript
-// Non-streaming
-client.chat.send({
-  chatGenerationParams: { model, messages, stream: false, maxTokens?, temperature? }
-});
-
-// Streaming
-client.chat.send({
-  chatGenerationParams: { model, messages, stream: true, maxTokens?, temperature? }
-});
-```
-
 ## Types
 
 ### `KrutAIProviderConfig`
 
 ```typescript
 interface KrutAIProviderConfig {
-  apiKey: string;                // KrutAI API key (required)
-  openRouterApiKey?: string;     // falls back to process.env.OPENROUTER_API_KEY
-  model?: string;                // default: DEFAULT_MODEL
-  validateOnInit?: boolean;      // default: true
-  validationEndpoint?: string;   // POST URL for key validation (future)
+  apiKey: string;         // KrutAI API key — validated with server (required)
+  serverUrl?: string;     // Base URL of deployed LangChain server (default: 'http://localhost:8000')
+  model?: string;         // default: 'default'
+  validateOnInit?: boolean; // default: true
 }
 ```
 
@@ -132,29 +124,29 @@ interface GenerateOptions {
 
 ## Validator
 
-Defined in `src/validator.ts` (NOT imported from `krutai` — OpenRouter-specific).
+Defined in `src/validator.ts`.
 
 ```typescript
-export { validateOpenRouterKeyFormat, validateOpenRouterKeyWithService, OpenRouterKeyValidationError };
+export { validateApiKey, validateApiKeyFormat, KrutAIKeyValidationError };
 ```
 
 ### Validation Flow
 
-1. **Format check** (sync, on construction): key must start with `sk-or-v1-` and be ≥ 20 chars
-2. **Service check** (async, on `initialize()`): if `validationEndpoint` is set, sends `POST { apiKey }` and checks response; otherwise placeholder returns `true`
+1. **Format check** (sync, on construction): key must be a non-empty string
+2. **Server check** (async, on `initialize()`): sends `POST {serverUrl}/validate` with the key; expects `{ valid: true }`
 
 ## tsup Configuration Notes
 
-- `@openrouter/sdk` → **external** (real dependency, NOT bundled)
-- `krutai` → **external** (peer dep, NOT bundled)
+- Only `krutai` is external (peer dep, NOT bundled)
+- No third-party AI SDK — pure native `fetch`
 
 ## Important Notes
 
-1. **`krutAI()` is the primary API** — prefer it over `new KrutAIProvider()` for simple setups
-2. **Default model is `qwen/qwen3-235b-a22b-thinking-2507`** — override via `config.model` or `opts.model`
-3. **OpenRouter key from env** — set `OPENROUTER_API_KEY` and omit `openRouterApiKey` in config
-4. **Validation endpoint is a placeholder** — wire up the POST route when deployed
-5. **Do NOT bundle `@openrouter/sdk`** — must stay external in tsup
+1. **`serverUrl` defaults to `http://localhost:8000`** — make sure to override this with your deployed LangChain backend in production
+2. **`apiKey` is validated server-side** — the server controls what keys are valid
+3. **Streaming uses SSE** — server must respond with `Content-Type: text/event-stream`
+4. **No external SDK needed** — uses native `fetch` only (Node 18+, browser, edge runtimes)
+5. **Response field fallback** — tries `text → content → message` from server JSON response
 
 ## Related Packages
 
@@ -164,7 +156,5 @@ export { validateOpenRouterKeyFormat, validateOpenRouterKeyWithService, OpenRout
 
 ## Links
 
-- OpenRouter SDK Docs: https://openrouter.ai/docs/sdks/typescript
-- OpenRouter Models: https://openrouter.ai/models
 - GitHub: https://github.com/AccountantAIOrg/krut_packages
 - npm: https://www.npmjs.com/package/@krutai/ai-provider

package/README.md

@@ -1,16 +1,14 @@
 # @krutai/ai-provider
 
-AI Provider package for KrutAI — a thin wrapper around [`@openrouter/sdk`](https://www.npmjs.com/package/@openrouter/sdk), following the same patterns as `@krutai/auth`.
+AI provider package for KrutAI — fetch-based client for your deployed LangChain server.
 
 ## Features
 
-- **Default model**: `qwen/qwen3-235b-a22b-thinking-2507` (change any time)
-- **OpenRouter key validation**: format check (`sk-or-v1-` prefix) on construction, optional service validation
-- **Pluggable validation endpoint**: set your own POST route once it's ready
-- **Text generation & streaming**: `generate()`, `stream()`, and `chat()` built on `@openrouter/sdk`
-- **Mirrors `@krutai/auth` patterns**: `krutAI()` factory + `KrutAIProvider` class
-
----
+- 🔑 **API Key validation** — validates your key against the server before use
+- 🚀 **Zero SDK dependencies** — uses native `fetch` only
+- 📡 **Streaming** — SSE-based streaming via async generator
+- 💬 **Multi-turn chat** — full conversation history support
+- ⚙️ **Configurable** — pass any model name to the server
 
 ## Installation
 
@@ -18,146 +16,137 @@ AI Provider package for KrutAI — a thin wrapper around [`@openrouter/sdk`](htt
 npm install @krutai/ai-provider
 ```
 
----
-
 ## Quick Start
 
-### Simplest usage (no setup needed)
-
-The OpenRouter API key is built-in by default — just install and call:
-
 ```typescript
 import { krutAI } from '@krutai/ai-provider';
 
-const ai = krutAI();
-await ai.initialize();
+const ai = krutAI({
+  apiKey: 'your-krutai-api-key',
+  // Optional: omitted to use the default local dev server ('http://localhost:8000')
+  // serverUrl: 'https://ai.yourapp.com',
+});
 
-const text = await ai.generate('Write a haiku about coding');
+await ai.initialize(); // validates key with your server
+
+// Single response
+const text = await ai.generate('Write a poem about TypeScript');
 console.log(text);
 ```
 
-> **Note:** The built-in key is temporary. It will be removed once the validation endpoint is live, at which point you will need to provide your own key via `OPENROUTER_API_KEY` env var or `openRouterApiKey` config.
+## Usage
 
-### Change the model
+### Generate (single response)
 
 ```typescript
-const ai = krutAI({ model: 'openai/gpt-4o-mini' });
+const ai = krutAI({
+  apiKey: process.env.KRUTAI_API_KEY!,
+  serverUrl: 'https://ai.yourapp.com', // Override default for production
+  model: 'gpt-4o', // optional — server's default is used if omitted
+});
+
 await ai.initialize();
 
-const text = await ai.generate('Hello!');
+const text = await ai.generate('Explain async/await in JavaScript', {
+  system: 'You are a helpful coding tutor.',
+  maxTokens: 500,
+  temperature: 0.7,
+});
+
+console.log(text);
 ```
 
 ### Streaming
 
 ```typescript
-const ai = krutAI();
+const ai = krutAI({
+  apiKey: process.env.KRUTAI_API_KEY!,
+  // uses http://localhost:8000 by default
+});
+
 await ai.initialize();
 
-const stream = await ai.stream('Tell me a story');
-for await (const chunk of stream) {
-  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? '');
+// stream() is an async generator
+for await (const chunk of ai.stream('Tell me a short story')) {
+  process.stdout.write(chunk);
 }
 ```
 
-### Multi-turn conversation
+### Multi-turn Chat
 
 ```typescript
-const reply = await ai.chat([
-  { role: 'user', content: 'Hi!' },
-  { role: 'assistant', content: 'Hello! How can I help?' },
-  { role: 'user', content: 'What is TypeScript?' },
-]);
-```
+const ai = krutAI({
+  apiKey: process.env.KRUTAI_API_KEY!,
+});
 
-### Override model per call
+await ai.initialize();
 
-```typescript
-const text = await ai.generate('Summarise this', {
-  model: 'anthropic/claude-3.5-sonnet',
-  maxTokens: 512,
-  temperature: 0.7,
-});
+const response = await ai.chat([
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'What is the capital of France?' },
+  { role: 'assistant', content: 'Paris.' },
+  { role: 'user', content: 'What is it famous for?' },
+]);
+
+console.log(response);
 ```
 
-### Using the class directly
+### Skip validation (useful for tests)
 
 ```typescript
-import { KrutAIProvider } from '@krutai/ai-provider';
-
-const ai = new KrutAIProvider({
-  apiKey: process.env.KRUTAI_API_KEY!,
-  openRouterApiKey: process.env.OPENROUTER_API_KEY!,
-  model: 'google/gemini-flash-1.5',  // optional override
-  validateOnInit: true,               // default
+const ai = krutAI({
+  apiKey: 'test-key',
+  serverUrl: 'http://localhost:3000',
+  validateOnInit: false, // skips the /validate round-trip
 });
 
-await ai.initialize();
-const text = await ai.generate('Hi!');
+// No need to call initialize() when validateOnInit is false
+const text = await ai.generate('Hello!');
 ```
 
----
-
-## API Reference
-
-### `krutAI(config?)` — factory function
-
-| Field | Type | Default |
-|---|---|---|
-| `openRouterApiKey` | `string` | `process.env.OPENROUTER_API_KEY` |
-| `model` | `string` | `"qwen/qwen3-235b-a22b-thinking-2507"` |
-| `validateOnInit` | `boolean` | `true` |
-| `validationEndpoint` | `string` | `undefined` (placeholder) |
-
-### `KrutAIProvider` class
+## Server API Contract
 
-| Method | Returns | Description |
-|---|---|---|
-| `initialize()` | `Promise<void>` | Validates key + sets up OpenRouter client |
-| `generate(prompt, opts?)` | `Promise<string>` | Single response |
-| `stream(prompt, opts?)` | async iterable | Streaming response |
-| `chat(messages, opts?)` | `Promise<string>` | Multi-turn conversation |
-| `getModel()` | `string` | Active model name |
-| `getClient()` | `OpenRouter` | Raw `@openrouter/sdk` client (advanced) |
-| `isInitialized()` | `boolean` | Ready check |
+Your LangChain server must expose these endpoints:
 
----
+| Endpoint | Method | Auth | Body |
+|---|---|---|---|
+| `/validate` | POST | `x-api-key` header | `{ "apiKey": "..." }` |
+| `/generate` | POST | `Authorization: Bearer <key>` | `{ "prompt": "...", "model": "...", ... }` |
+| `/stream` | POST | `Authorization: Bearer <key>` | `{ "prompt": "...", "model": "...", ... }` |
+| `/chat` | POST | `Authorization: Bearer <key>` | `{ "messages": [...], "model": "...", ... }` |
 
-## Default Model
+**Validation response:** `{ "valid": true }` or `{ "valid": false, "message": "reason" }`
 
-```
-qwen/qwen3-235b-a22b-thinking-2507
-```
+**AI response:** `{ "text": "..." }` or `{ "content": "..." }` or `{ "message": "..." }`
 
-Pass `model` in the constructor or per-call to override.  
-Browse all available models at https://openrouter.ai/models.
+**Stream:** `text/event-stream` with `data: <chunk>` lines, ending with `data: [DONE]`
 
----
+## API Reference
 
-## Validation
+### `krutAI(config)`
 
-The OpenRouter key is validated for format (`sk-or-v1-` prefix) on construction.
+Factory function — preferred way to create a provider.
 
-When a `validationEndpoint` is provided, `initialize()` sends a `POST` request:
-```json
-{ "apiKey": "sk-or-v1-..." }
+```typescript
+const ai = krutAI({
+  apiKey: string;           // required — KrutAI API key
+  serverUrl?: string;       // optional — defaults to 'http://localhost:8000'
+  model?: string;           // optional — passed to server (default: 'default')
+  validateOnInit?: boolean; // optional — default: true
+});
 ```
-Expected response: `{ "valid": true }` (or any `2xx` without `valid: false`).
-
-> The live endpoint will be wired in once you deploy the POST route.
 
----
+### `KrutAIProvider`
 
-## Related Packages
+Full class API with the same methods as above. Use when you need the class directly.
 
-- [`krutai`](https://www.npmjs.com/package/krutai) — Core utilities & API validation
-- [`@krutai/auth`](https://www.npmjs.com/package/@krutai/auth) — Authentication (wraps better-auth)
-- [`@krutai/rbac`](https://www.npmjs.com/package/@krutai/rbac) — Role-Based Access Control
+### Exports
 
----
+```typescript
+export { krutAI, KrutAIProvider, KrutAIKeyValidationError, validateApiKey, validateApiKeyFormat, DEFAULT_MODEL };
+export type { KrutAIProviderConfig, GenerateOptions, ChatMessage };
+```
 
-## Links
+## License
 
-- OpenRouter SDK: https://openrouter.ai/docs/sdks/typescript
-- Available Models: https://openrouter.ai/models
-- GitHub: https://github.com/AccountantAIOrg/krut_packages
-- npm: https://www.npmjs.com/package/@krutai/ai-provider
+MIT