@krutai/ai-provider 0.2.12 → 0.2.15

package/AI_REFERENCE.md

@@ -3,7 +3,7 @@
 ## Package Overview
 
 - **Name**: `@krutai/ai-provider`
-- **Version**: `0.2.2`
+- **Version**: `0.2.14`
 - **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, no external SDK deps)
@@ -11,7 +11,7 @@
 ## Architecture
 
 ```
-@krutai/ai-provider@0.2.2
+@krutai/ai-provider@0.2.14
  └── peerDep: krutai  (core utilities)
 
 AI Flow:
@@ -19,7 +19,6 @@ AI Flow:
            → POST {serverUrl}/validate   (key validation)
            → POST {serverUrl}/generate   (single response)
            → POST {serverUrl}/stream     (SSE streaming)
-           → POST {serverUrl}/chat       (multi-turn)
            → Your deployed LangChain server
 ```
 
@@ -42,9 +41,8 @@ packages/ai-provider/
 | 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 }` |
+| `/generate` | POST | `{ prompt, model, system?, maxTokens?, temperature?, isStructure?, output_structure?, history?, attachments? }` | `{ text/content/message: string }` or `any` (if structured) |
+| `/stream` | POST | `{ messages, model, system?, maxTokens?, temperature? }` | SSE stream `data: <chunk>` |
 
 All AI endpoints receive `Authorization: Bearer <apiKey>` and `x-api-key: <apiKey>` headers.
 
@@ -62,8 +60,49 @@ const ai = krutAI({
 });
 
 await ai.initialize(); // validates key with server
+```
+
+### 1. `chat(prompt: string)` — Simple String Prompts
+Used to get a single, non-streaming text response from a string prompt.
+
+```typescript
+const text = await ai.chat('Write a poem about TypeScript');
+console.log(text);
+
+// Example: Structured Output
+interface UserProfile {
+  name: string;
+  age: number;
+}
+const profile = await ai.chat<UserProfile>('Generate a profile for John Doe', {
+  isStructure: true,
+  output_structure: ['name', 'age'] // or a JSON Schema
+});
+console.log(profile.name, profile.age);
+```
+
+### 2. `streamChatResponse(messages: ChatMessage[])` — Multi-Turn & Streaming
+Used for multi-turn conversations and streaming responses. It takes an array of `ChatMessage` objects instead of a single string. It returns a raw fetch `Response` containing the `text/event-stream` body.
+
+Ideal for proxying streams (e.g., Next.js API routes) down to your backend component or manually reading the `ReadableStream`.
+
+```typescript
+// Example: Proxying in a Next.js route
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  
+  // ai.streamChatResponse accepts an array of messages:
+  // [{ role: 'user', content: '...' }, ...]
+  return await ai.streamChatResponse(messages);
+}
 
-const text = await ai.generate('Hello!');
+// Example: Manual Node environment stream reading
+const response = await ai.streamChatResponse([
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'Tell me a story' }
+]);
+const reader = response.body?.getReader();
+// Use a TextDecoder to parse value chunks...
 ```
 
 ### `KrutAIProvider` class ← FULL CLASS API
@@ -74,7 +113,7 @@ import { KrutAIProvider } from '@krutai/ai-provider';
 const ai = new KrutAIProvider({
   apiKey: process.env.KRUTAI_API_KEY!,
   // serverUrl: 'https://krut.ai', // Optional: defaults to localhost:8000
-  model: 'gpt-4o',         // optional, default: 'default'
+  model: 'gemini-3.1-pro-preview',         // optional, default: 'default'
   validateOnInit: true,     // default: true
 });
 
@@ -83,12 +122,8 @@ await ai.initialize();
 
 **Methods:**
 - `initialize(): Promise<void>` — validates key against server, marks provider ready
-- `generate(prompt, opts?): Promise<string>` — single response (non-streaming)
-- `stream(prompt, opts?)` — `AsyncGenerator<string>` — SSE-based streaming
-- `streamResponse(prompt, opts?)` — `Promise<Response>` — returns the raw fetch Response for proxying
-- `streamChat(messages, opts?)` — `AsyncGenerator<string>` — SSE multi-turn streaming
-- `streamChatResponse(messages, opts?)` — `Promise<Response>` — returns the raw fetch Response for proxying
-- `chat(messages, opts?): Promise<string>` — multi-turn conversation
+- `chat(prompt, opts?): Promise<string>` — single response (non-streaming)
+- `streamChatResponse(messages, opts?)` — `Promise<Response>` — returns the raw fetch Response for proxying (SSE multi-turn streaming)
 - `getModel(): string` — active model name
 - `isInitialized(): boolean`
 
@@ -127,6 +162,10 @@ interface GenerateOptions {
   images?: string[];     // Array of image URLs or base64 data URIs
   documents?: string[];  // Array of document URLs or base64 data URIs
   pdf?: string[];        // Array of PDF URLs or base64 data URIs
+  history?: ChatMessage[]; // Optional: conversation history
+  attachments?: any[];    // Optional: multimodal attachments
+  isStructure?: boolean;   // Whether to return structured output
+  output_structure?: any;  // The schema (JSON Schema or field array) for structured output
 }
 ```
 

package/README.md

@@ -1,6 +1,6 @@
 # @krutai/ai-provider
 
-AI provider package for KrutAI — fetch-based client for your deployed LangChain server.
+AI provider package for KrutAI — fetch-based client form our deployed server.
 
 ## Features
 
@@ -30,24 +30,24 @@ const ai = krutAI({
 await ai.initialize(); // validates key with your server
 
 // Single response
-const text = await ai.generate('Write a poem about TypeScript');
+const text = await ai.chat('Write a poem about TypeScript');
 console.log(text);
 ```
 
 ## Usage
 
-### Generate (single response)
+### Chat (single response)
 
 ```typescript
 const ai = krutAI({
   apiKey: process.env.KRUTAI_API_KEY!,
   serverUrl: 'https://krut.ai', // Override default for production
-  model: 'gpt-4o', // optional — server's default is used if omitted
+  model: 'gemini-3.1-pro-preview', // optional — server's default is used if omitted
 });
 
 await ai.initialize();
 
-const text = await ai.generate('Explain async/await in JavaScript', {
+const text = await ai.chat('Explain async/await in JavaScript', {
   system: 'You are a helpful coding tutor.',
   maxTokens: 500,
   temperature: 0.7,
@@ -56,21 +56,6 @@ const text = await ai.generate('Explain async/await in JavaScript', {
 console.log(text);
 ```
 
-### Streaming
-
-```typescript
-const ai = krutAI({
-  apiKey: process.env.KRUTAI_API_KEY!,
-  // uses http://localhost:8000 by default
-});
-
-await ai.initialize();
-
-// stream() is an async generator
-for await (const chunk of ai.stream('Tell me a short story')) {
-  process.stdout.write(chunk);
-}
-```
 
 ### Multi-turn Chat
 
@@ -108,7 +93,7 @@ const response = await ai.chat([
     ]
   }
 ], { 
-  model: 'gpt-4o',
+  model: 'gemini-3.1-pro-preview',
   // You can also pass images, documents, or pdfs via GenerateOptions
   images: ['https://example.com/photo.jpg'],
   documents: ['https://example.com/doc.docx'],
@@ -116,29 +101,11 @@ const response = await ai.chat([
 });
 ```
 
-### Streaming Multi-turn Chat
-
-```typescript
-const ai = krutAI({
-  apiKey: process.env.KRUTAI_API_KEY!,
-});
+### Streaming (Proxying SSE Streams)
 
-await ai.initialize();
+If you are building an API route (e.g., in Next.js) and want to pipe the true Server-Sent Events (SSE) stream down to your backend component, use `streamChatResponse`.
 
-const stream = ai.streamChat([
-  { role: 'user', content: 'What is the capital of France?' },
-  { role: 'assistant', content: 'Paris.' },
-  { role: 'user', content: 'What is it famous for?' },
-]);
-
-for await (const chunk of stream) {
-  process.stdout.write(chunk);
-}
-```
-
-### Proxying Streams to the Frontend (Next.js / API Routes)
-
-If you are building an API route (e.g., in Next.js) and want to pipe the true Server-Sent Events (SSE) stream down to your frontend component, use the `Response` variants:
+`streamChatResponse` returns the raw fetch `Response` object containing the `text/event-stream` body from deployed LangChain server.
 
 ```typescript
 // app/api/chat/route.ts
@@ -148,11 +115,50 @@ export async function POST(req: Request) {
   // Returns the native fetch Response (with text/event-stream headers and body)
   const response = await ai.streamChatResponse(messages);
   
-  // Proxy it directly to the frontend!
+  // Proxy it directly to the backend!
   return response;
 }
 ```
 
+If you need to consume the stream in a Node environment rather than proxying it, you can read from the response body directly:
+
+```typescript
+const response = await ai.streamChatResponse([
+  { role: 'user', content: 'Tell me a short story' }
+]);
+
+const reader = response.body?.getReader();
+const decoder = new TextDecoder();
+
+if (reader) {
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    process.stdout.write(decoder.decode(value, { stream: true }));
+  }
+}
+```
+
+### Structured Output
+
+You can request the AI to return data in a specific JSON structure (e.g. for generating models, summaries, or profiles).
+
+```typescript
+interface Profile {
+  name: string;
+  age: number;
+}
+
+const profile = await ai.chat<Profile>('Generate a profile for John Doe', {
+  isStructure: true,
+  // Pass an array of field names for simple string objects...
+  output_structure: ['name', 'age'], 
+  // ...or pass a full JSON Schema for complex objects
+});
+
+console.log(profile.name, profile.age);
+```
+
 ### Skip validation (useful for tests)
 
 ```typescript
@@ -163,7 +169,7 @@ const ai = krutAI({
 });
 
 // No need to call initialize() when validateOnInit is false
-const text = await ai.generate('Hello!');
+const text = await ai.chat('Hello!');
 ```
 
 ## Server API Contract
@@ -173,9 +179,8 @@ 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": "...", ... }` |
+| `/generate` | POST | `Authorization: Bearer <key>` | `{ "prompt": "...", "isStructure": boolean, "output_structure": any, ... }` |
+| `/stream` | POST | `Authorization: Bearer <key>` | `{ "messages": [...], "model": "...", ... }` |
 
 **Validation response:** `{ "valid": true }` or `{ "valid": false, "message": "reason" }`
 

package/dist/index.d.mts

@@ -7,7 +7,7 @@ export { ApiKeyValidationError as KrutAIKeyValidationError, validateApiKeyWithSe
  * Default model identifier sent to the LangChain server when no model is specified.
  * Your server can use this value to route to its own default model.
  */
-declare const DEFAULT_MODEL: "default";
+declare const DEFAULT_MODEL: "gemini-3.1-pro-preview";
 /**
  * Configuration options for KrutAIProvider
  */
@@ -92,6 +92,23 @@ interface GenerateOptions {
      * Array of PDF URLs or base64 data URIs to include with the request.
      */
     pdf?: string[];
+    /**
+     * Optional conversation history.
+     */
+    history?: ChatMessage[];
+    /**
+     * Optional attachments.
+     */
+    attachments?: any[];
+    /**
+     * Whether to return structured output.
+     */
+    isStructure?: boolean;
+    /**
+     * The schema for structured output.
+     * Can be a JSON Schema object or an array of field names.
+     */
+    output_structure?: any;
 }
 
 /**
@@ -146,57 +163,6 @@ declare class KrutAIProvider {
     private assertInitialized;
     /** Common request headers sent to the server on every AI call. */
     private authHeaders;
-    /**
-     * Generate a response for a prompt (non-streaming).
-     *
-     * Calls: POST {serverUrl}/generate
-     * Body:  { prompt, model, system?, maxTokens?, temperature? }
-     * Expected response: { text: string } or { content: string } or { message: string }
-     *
-     * @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 via Server-Sent Events (SSE).
-     *
-     * Calls: POST {serverUrl}/stream
-     * Body:  { prompt, model, system?, maxTokens?, temperature? }
-     * Expected response: `text/event-stream` with `data: <chunk>` lines.
-     *
-     * @param prompt - The user prompt string
-     * @param options - Optional overrides (model, system, maxTokens, temperature)
-     * @returns An async generator yielding string chunks from the server
-     *
-     * @example
-     * ```typescript
-     * const stream = ai.stream('Tell me a story');
-     * for await (const chunk of stream) {
-     *   process.stdout.write(chunk);
-     * }
-     * ```
-     */
-    stream(prompt: string, options?: GenerateOptions): AsyncGenerator<string>;
-    /**
-     * Similar to stream() but returns the raw fetch Response object.
-     * Useful when you want to proxy the Server-Sent Events stream directly to a frontend client
-     * (e.g., returning this directly from a Next.js API route).
-     *
-     * @param prompt - The user prompt string
-     * @param options - Optional overrides (model, system, maxTokens, temperature)
-     * @returns A Promise resolving to the native fetch Response
-     */
-    streamResponse(prompt: string, options?: GenerateOptions): Promise<Response>;
-    /**
-     * Multi-turn conversation streaming: pass a full message history.
-     * Calls POST /stream with the full { messages } payload.
-     *
-     * @param messages - Full conversation history
-     * @param options - Optional overrides (model, maxTokens, temperature)
-     * @returns An async generator yielding string chunks from the server
-     */
-    streamChat(messages: ChatMessage[], options?: GenerateOptions): AsyncGenerator<string>;
     /**
      * Similar to streamChat() but returns the raw fetch Response object.
      * Useful for proxying the Server-Sent Events stream directly to a frontend client.
@@ -207,17 +173,17 @@ declare class KrutAIProvider {
      */
     streamChatResponse(messages: ChatMessage[], options?: GenerateOptions): Promise<Response>;
     /**
-     * Multi-turn conversation: pass a full message history.
+     * Generate a response for a prompt (non-streaming).
      *
-     * Calls: POST {serverUrl}/chat
-     * Body:  { messages, model, maxTokens?, temperature? }
+     * Calls: POST {serverUrl}/generate
+     * Body:  { prompt, model, system?, maxTokens?, temperature? }
      * Expected response: { text: string } or { content: string } or { message: string }
      *
-     * @param messages - Full conversation history
-     * @param options - Optional overrides (model, maxTokens, temperature)
-     * @returns The assistant's response text
+     * @param prompt - The user prompt string
+     * @param options - Optional overrides (model, system, maxTokens, temperature)
+     * @returns The assistant's response text (or an object if structured)
      */
-    chat(messages: ChatMessage[], options?: GenerateOptions): Promise<string>;
+    chat<T = any>(prompt: string, options?: GenerateOptions): Promise<T>;
 }
 
 /**
@@ -237,7 +203,7 @@ declare class KrutAIProvider {
  *
  * await ai.initialize(); // validates key with server
  *
- * const text = await ai.generate('Write a poem about TypeScript');
+ * const text = await ai.chat('Write a poem about TypeScript');
  * console.log(text);
  * ```
  *
@@ -246,10 +212,10 @@ declare class KrutAIProvider {
  * const ai = krutAI({
  *   apiKey: process.env.KRUTAI_API_KEY!,
  *   serverUrl: 'https://krut.ai',
- *   model: 'gpt-4o',
+ *   model: 'gemini-3.1-pro-preview',
  * });
  * await ai.initialize();
- * const text = await ai.generate('Hello!');
+ * const text = await ai.chat('Hello!');
  * ```
  *
  * @example Streaming
@@ -260,10 +226,8 @@ declare class KrutAIProvider {
  * });
  * await ai.initialize();
  *
- * const stream = ai.stream('Tell me a story');
- * for await (const chunk of stream) {
- *   process.stdout.write(chunk);
- * }
+ * const response = await ai.streamChatResponse([{ role: 'user', content: 'Tell me a story' }]);
+ * // Example assumes you handle the SSE stream from the response body
  * ```
  *
  * @packageDocumentation
@@ -287,12 +251,12 @@ declare class KrutAIProvider {
  * });
  *
  * await ai.initialize();
- * const text = await ai.generate('Hello!');
+ * const text = await ai.chat('Hello!');
  * ```
  */
 declare function krutAI(config: KrutAIProviderConfig & {
     model?: string;
 }): KrutAIProvider;
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.2.15";
 
 export { type ChatMessage, DEFAULT_MODEL, type GenerateOptions, KrutAIProvider, type KrutAIProviderConfig, VERSION, krutAI };

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { ApiKeyValidationError as KrutAIKeyValidationError, validateApiKeyWithSe
  * Default model identifier sent to the LangChain server when no model is specified.
  * Your server can use this value to route to its own default model.
  */
-declare const DEFAULT_MODEL: "default";
+declare const DEFAULT_MODEL: "gemini-3.1-pro-preview";
 /**
  * Configuration options for KrutAIProvider
  */
@@ -92,6 +92,23 @@ interface GenerateOptions {
      * Array of PDF URLs or base64 data URIs to include with the request.
      */
     pdf?: string[];
+    /**
+     * Optional conversation history.
+     */
+    history?: ChatMessage[];
+    /**
+     * Optional attachments.
+     */
+    attachments?: any[];
+    /**
+     * Whether to return structured output.
+     */
+    isStructure?: boolean;
+    /**
+     * The schema for structured output.
+     * Can be a JSON Schema object or an array of field names.
+     */
+    output_structure?: any;
 }
 
 /**
@@ -146,57 +163,6 @@ declare class KrutAIProvider {
     private assertInitialized;
     /** Common request headers sent to the server on every AI call. */
     private authHeaders;
-    /**
-     * Generate a response for a prompt (non-streaming).
-     *
-     * Calls: POST {serverUrl}/generate
-     * Body:  { prompt, model, system?, maxTokens?, temperature? }
-     * Expected response: { text: string } or { content: string } or { message: string }
-     *
-     * @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 via Server-Sent Events (SSE).
-     *
-     * Calls: POST {serverUrl}/stream
-     * Body:  { prompt, model, system?, maxTokens?, temperature? }
-     * Expected response: `text/event-stream` with `data: <chunk>` lines.
-     *
-     * @param prompt - The user prompt string
-     * @param options - Optional overrides (model, system, maxTokens, temperature)
-     * @returns An async generator yielding string chunks from the server
-     *
-     * @example
-     * ```typescript
-     * const stream = ai.stream('Tell me a story');
-     * for await (const chunk of stream) {
-     *   process.stdout.write(chunk);
-     * }
-     * ```
-     */
-    stream(prompt: string, options?: GenerateOptions): AsyncGenerator<string>;
-    /**
-     * Similar to stream() but returns the raw fetch Response object.
-     * Useful when you want to proxy the Server-Sent Events stream directly to a frontend client
-     * (e.g., returning this directly from a Next.js API route).
-     *
-     * @param prompt - The user prompt string
-     * @param options - Optional overrides (model, system, maxTokens, temperature)
-     * @returns A Promise resolving to the native fetch Response
-     */
-    streamResponse(prompt: string, options?: GenerateOptions): Promise<Response>;
-    /**
-     * Multi-turn conversation streaming: pass a full message history.
-     * Calls POST /stream with the full { messages } payload.
-     *
-     * @param messages - Full conversation history
-     * @param options - Optional overrides (model, maxTokens, temperature)
-     * @returns An async generator yielding string chunks from the server
-     */
-    streamChat(messages: ChatMessage[], options?: GenerateOptions): AsyncGenerator<string>;
     /**
      * Similar to streamChat() but returns the raw fetch Response object.
      * Useful for proxying the Server-Sent Events stream directly to a frontend client.
@@ -207,17 +173,17 @@ declare class KrutAIProvider {
      */
     streamChatResponse(messages: ChatMessage[], options?: GenerateOptions): Promise<Response>;
     /**
-     * Multi-turn conversation: pass a full message history.
+     * Generate a response for a prompt (non-streaming).
      *
-     * Calls: POST {serverUrl}/chat
-     * Body:  { messages, model, maxTokens?, temperature? }
+     * Calls: POST {serverUrl}/generate
+     * Body:  { prompt, model, system?, maxTokens?, temperature? }
      * Expected response: { text: string } or { content: string } or { message: string }
      *
-     * @param messages - Full conversation history
-     * @param options - Optional overrides (model, maxTokens, temperature)
-     * @returns The assistant's response text
+     * @param prompt - The user prompt string
+     * @param options - Optional overrides (model, system, maxTokens, temperature)
+     * @returns The assistant's response text (or an object if structured)
      */
-    chat(messages: ChatMessage[], options?: GenerateOptions): Promise<string>;
+    chat<T = any>(prompt: string, options?: GenerateOptions): Promise<T>;
 }
 
 /**
@@ -237,7 +203,7 @@ declare class KrutAIProvider {
  *
  * await ai.initialize(); // validates key with server
  *
- * const text = await ai.generate('Write a poem about TypeScript');
+ * const text = await ai.chat('Write a poem about TypeScript');
  * console.log(text);
  * ```
  *
@@ -246,10 +212,10 @@ declare class KrutAIProvider {
  * const ai = krutAI({
  *   apiKey: process.env.KRUTAI_API_KEY!,
  *   serverUrl: 'https://krut.ai',
- *   model: 'gpt-4o',
+ *   model: 'gemini-3.1-pro-preview',
  * });
  * await ai.initialize();
- * const text = await ai.generate('Hello!');
+ * const text = await ai.chat('Hello!');
  * ```
  *
  * @example Streaming
@@ -260,10 +226,8 @@ declare class KrutAIProvider {
  * });
  * await ai.initialize();
  *
- * const stream = ai.stream('Tell me a story');
- * for await (const chunk of stream) {
- *   process.stdout.write(chunk);
- * }
+ * const response = await ai.streamChatResponse([{ role: 'user', content: 'Tell me a story' }]);
+ * // Example assumes you handle the SSE stream from the response body
  * ```
  *
  * @packageDocumentation
@@ -287,12 +251,12 @@ declare class KrutAIProvider {
  * });
  *
  * await ai.initialize();
- * const text = await ai.generate('Hello!');
+ * const text = await ai.chat('Hello!');
  * ```
  */
 declare function krutAI(config: KrutAIProviderConfig & {
     model?: string;
 }): KrutAIProvider;
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.2.15";
 
 export { type ChatMessage, DEFAULT_MODEL, type GenerateOptions, KrutAIProvider, type KrutAIProviderConfig, VERSION, krutAI };