@krutai/ai-provider 0.1.0

package/AI_REFERENCE.md

@@ -0,0 +1,170 @@
+# @krutai/ai-provider — AI Assistant Reference Guide
+
+## 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
+- **Entry**: `src/index.ts` → `dist/index.{js,mjs,d.ts}`
+- **Build**: `tsup` (CJS + ESM, all deps external)
+
+## Dependency Architecture
+
+```
+@krutai/ai-provider@0.1.0
+├── dependency: @openrouter/sdk  ← Official OpenRouter TypeScript SDK (external in tsup)
+└── peerDep:    krutai           ← Core utilities
+```
+
+> **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
+│   ├── types.ts      # KrutAIProviderConfig, GenerateOptions, ChatMessage, DEFAULT_MODEL
+│   └── validator.ts  # OpenRouter key format + service validation
+├── package.json
+├── tsconfig.json
+└── tsup.config.ts
+```
+
+## Default Model
+
+```
+qwen/qwen3-235b-a22b-thinking-2507
+```
+
+Exported as `DEFAULT_MODEL` constant. Users override via `config.model` or per-call `options.model`.
+
+## Main Exports
+
+### `krutAI(config?)` ← PRIMARY API
+
+Drop-in factory. Mirrors `krutAuth` from `@krutai/auth`.
+
+```typescript
+import { krutAI } from '@krutai/ai-provider';
+
+const ai = krutAI(); // OPENROUTER_API_KEY from env, default model
+await ai.initialize();
+
+const text = await ai.generate('Hello!');
+```
+
+### `KrutAIProvider` class ← FULL CLASS API
+
+```typescript
+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
+});
+
+await ai.initialize();
+```
+
+**Methods:**
+- `initialize(): Promise<void>` — validates key + sets up OpenRouter client
+- `generate(prompt, opts?): Promise<string>` — single response (non-streaming)
+- `stream(prompt, opts?)` — async iterable of SSE chunks (`chunk.choices[0].delta.content`)
+- `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)
+}
+```
+
+### `ChatMessage`
+
+```typescript
+interface ChatMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+```
+
+### `GenerateOptions`
+
+```typescript
+interface GenerateOptions {
+  model?: string;        // override model for this call
+  system?: string;       // system prompt
+  maxTokens?: number;
+  temperature?: number;
+}
+```
+
+## Validator
+
+Defined in `src/validator.ts` (NOT imported from `krutai` — OpenRouter-specific).
+
+```typescript
+export { validateOpenRouterKeyFormat, validateOpenRouterKeyWithService, OpenRouterKeyValidationError };
+```
+
+### 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`
+
+## tsup Configuration Notes
+
+- `@openrouter/sdk` → **external** (real dependency, NOT bundled)
+- `krutai` → **external** (peer dep, NOT bundled)
+
+## 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
+
+## Related Packages
+
+- `krutai` — Core utilities and API validation
+- `@krutai/auth` — Authentication (wraps better-auth)
+- `@krutai/rbac` — Role-Based Access Control
+
+## 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

@@ -0,0 +1,163 @@
+# @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`.
+
+## 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
+
+---
+
+## Installation
+
+```bash
+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 text = await ai.generate('Write a haiku about coding');
+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.
+
+### Change the model
+
+```typescript
+const ai = krutAI({ model: 'openai/gpt-4o-mini' });
+await ai.initialize();
+
+const text = await ai.generate('Hello!');
+```
+
+### Streaming
+
+```typescript
+const ai = krutAI();
+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 ?? '');
+}
+```
+
+### Multi-turn conversation
+
+```typescript
+const reply = await ai.chat([
+  { role: 'user', content: 'Hi!' },
+  { role: 'assistant', content: 'Hello! How can I help?' },
+  { role: 'user', content: 'What is TypeScript?' },
+]);
+```
+
+### Override model per call
+
+```typescript
+const text = await ai.generate('Summarise this', {
+  model: 'anthropic/claude-3.5-sonnet',
+  maxTokens: 512,
+  temperature: 0.7,
+});
+```
+
+### Using the class directly
+
+```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
+});
+
+await ai.initialize();
+const text = await ai.generate('Hi!');
+```
+
+---
+
+## 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
+
+| 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 |
+
+---
+
+## Default Model
+
+```
+qwen/qwen3-235b-a22b-thinking-2507
+```
+
+Pass `model` in the constructor or per-call to override.  
+Browse all available models at https://openrouter.ai/models.
+
+---
+
+## Validation
+
+The OpenRouter key is validated for format (`sk-or-v1-` prefix) on construction.
+
+When a `validationEndpoint` is provided, `initialize()` sends a `POST` request:
+```json
+{ "apiKey": "sk-or-v1-..." }
+```
+Expected response: `{ "valid": true }` (or any `2xx` without `valid: false`).
+
+> The live endpoint will be wired in once you deploy the POST route.
+
+---
+
+## Related Packages
+
+- [`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
+
+---
+
+## Links
+
+- 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

package/dist/index.d.mts

@@ -0,0 +1,248 @@
+import * as _openrouter_sdk_lib_event_streams_js from '@openrouter/sdk/lib/event-streams.js';
+import * as _openrouter_sdk_models from '@openrouter/sdk/models';
+import { OpenRouter } from '@openrouter/sdk';
+
+/**
+ * Types for @krutai/ai-provider
+ */
+/**
+ * Default model used when no model is specified
+ */
+declare const DEFAULT_MODEL: "qwen/qwen3-235b-a22b-thinking-2507";
+/**
+ * Configuration options for KrutAIProvider
+ */
+interface KrutAIProviderConfig {
+    /**
+     * KrutAI API key for service validation.
+     * @required
+     */
+    apiKey: string;
+    /**
+     * OpenRouter API key.
+     * Falls back to process.env.OPENROUTER_API_KEY if not provided.
+     */
+    openRouterApiKey?: string;
+    /**
+     * The AI model to use.
+     * @default "qwen/qwen3-235b-a22b-thinking-2507"
+     * @see https://openrouter.ai/models
+     */
+    model?: string;
+    /**
+     * Whether to validate the OpenRouter API key on initialization.
+     * @default true
+     */
+    validateOnInit?: boolean;
+    /**
+     * Custom POST endpoint for OpenRouter API key validation.
+     * Will be wired in once you deploy the route.
+     */
+    validationEndpoint?: string;
+}
+/**
+ * A single chat message (OpenRouter format)
+ */
+interface ChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+/**
+ * Options for a single generate / stream call
+ */
+interface GenerateOptions {
+    /**
+     * Override the model for this specific call.
+     */
+    model?: string;
+    /**
+     * System prompt (prepended as a system message).
+     */
+    system?: string;
+    /**
+     * Maximum tokens to generate.
+     */
+    maxTokens?: number;
+    /**
+     * Temperature (0–2).
+     */
+    temperature?: number;
+}
+
+/**
+ * OpenRouter API Key Validator
+ *
+ * Validates the OpenRouter API key format and (optionally) its validity
+ * via a configurable POST endpoint.
+ *
+ * The user will later provide a live POST route; until then the
+ * service-level check is a placeholder that accepts any well-formed key.
+ */
+declare class OpenRouterKeyValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates the format of an OpenRouter API key.
+ * @throws {OpenRouterKeyValidationError}
+ */
+declare function validateOpenRouterKeyFormat(apiKey: string): void;
+/**
+ * Validates the OpenRouter API key with the KrutAI validation service.
+ *
+ * The user will provide a live POST route later. Until then this is a
+ * placeholder that accepts any key that passes format validation.
+ *
+ * @param apiKey - OpenRouter API key to validate
+ * @param validationEndpoint - Optional POST URL to validate against
+ */
+declare function validateOpenRouterKeyWithService(apiKey: string, validationEndpoint?: string): Promise<boolean>;
+
+/**
+ * KrutAIProvider — AI provider for KrutAI
+ *
+ * Wraps `@openrouter/sdk` and adds:
+ *  - OpenRouter API key format validation
+ *  - Configurable default model (defaults to qwen/qwen3-235b-a22b-thinking-2507)
+ *  - Optional pluggable validation endpoint
+ *
+ * @example
+ * ```typescript
+ * import { KrutAIProvider } from '@krutai/ai-provider';
+ *
+ * const ai = new KrutAIProvider({
+ *   apiKey: process.env.KRUTAI_API_KEY!,
+ *   openRouterApiKey: process.env.OPENROUTER_API_KEY!, // or set in env
+ * });
+ *
+ * await ai.initialize();
+ *
+ * const text = await ai.generate('Tell me a joke');
+ * console.log(text);
+ * ```
+ */
+declare class KrutAIProvider {
+    private readonly resolvedOpenRouterKey;
+    private readonly resolvedModel;
+    private readonly config;
+    private openRouterClient;
+    private initialized;
+    constructor(config: KrutAIProviderConfig);
+    /**
+     * Initialize the provider.
+     * Validates the OpenRouter API key (optionally against a service endpoint)
+     * and sets up the underlying OpenRouter client.
+     *
+     * @throws {OpenRouterKeyValidationError}
+     */
+    initialize(): Promise<void>;
+    /** @private */
+    private setupClient;
+    /**
+     * Get the raw OpenRouter SDK client instance.
+     * @throws {Error} If not initialized
+     */
+    getClient(): OpenRouter;
+    /**
+     * Get the currently configured default model.
+     */
+    getModel(): string;
+    /**
+     * Check whether the provider has been initialized.
+     */
+    isInitialized(): boolean;
+    /**
+     * Generate a response for a prompt (non-streaming).
+     *
+     * @param prompt - The user prompt string
+     * @param options - Optional overrides (model, system, maxTokens, temperature)
+     * @returns The assistant's response text
+     */
+    generate(prompt: string, options?: GenerateOptions): Promise<string>;
+    /**
+     * Generate a streaming response for a prompt.
+     *
+     * @param prompt - The user prompt string
+     * @param options - Optional overrides (model, system, maxTokens, temperature)
+     * @returns An async iterable of server-sent event chunks
+     *
+     * @example
+     * ```typescript
+     * const stream = await ai.stream('Tell me a story');
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk.choices?.[0]?.delta?.content ?? '');
+     * }
+     * ```
+     */
+    stream(prompt: string, options?: GenerateOptions): Promise<_openrouter_sdk_lib_event_streams_js.EventStream<_openrouter_sdk_models.ChatStreamingResponseChunkData>>;
+    /**
+     * Multi-turn conversation: pass a full message history.
+     *
+     * @param messages - Full conversation history
+     * @param options - Optional overrides (model, maxTokens, temperature)
+     */
+    chat(messages: ChatMessage[], options?: GenerateOptions): Promise<string>;
+}
+
+/**
+ * @krutai/ai-provider — AI Provider package for KrutAI
+ *
+ * A thin wrapper around `@openrouter/sdk`, mirroring the patterns from `@krutai/auth`.
+ *
+ * Default model: `qwen/qwen3-235b-a22b-thinking-2507`
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { krutAI } from '@krutai/ai-provider';
+ *
+ * const ai = krutAI(); // uses OPENROUTER_API_KEY env var
+ * await ai.initialize();
+ *
+ * const text = await ai.generate('Write a poem about TypeScript');
+ * console.log(text);
+ * ```
+ *
+ * @example With custom model
+ * ```typescript
+ * const ai = krutAI({ model: 'openai/gpt-4o' });
+ * await ai.initialize();
+ * const text = await ai.generate('Hello!');
+ * ```
+ *
+ * @example Streaming
+ * ```typescript
+ * const ai = krutAI();
+ * 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 ?? '');
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * krutAI — convenience factory (mirrors `krutAuth` in @krutai/auth).
+ *
+ * Creates a `KrutAIProvider` instance. OpenRouter API key is read from
+ * `config.openRouterApiKey` or falls back to `process.env.OPENROUTER_API_KEY`.
+ *
+ * @param config - Provider configuration (all fields optional except apiKey)
+ * @returns A `KrutAIProvider` instance (call `.initialize()` before use)
+ *
+ * @example
+ * ```typescript
+ * import { krutAI } from '@krutai/ai-provider';
+ *
+ * const ai = krutAI(); // env OPENROUTER_API_KEY + default model
+ * await ai.initialize();
+ * const text = await ai.generate('Hello!');
+ * ```
+ */
+declare function krutAI(config?: Partial<KrutAIProviderConfig> & {
+    apiKey?: string;
+}): KrutAIProvider;
+declare const VERSION = "0.1.0";
+
+export { type ChatMessage, DEFAULT_MODEL, type GenerateOptions, KrutAIProvider, type KrutAIProviderConfig, OpenRouterKeyValidationError, VERSION, krutAI, validateOpenRouterKeyFormat, validateOpenRouterKeyWithService };