@krutai/ai-provider 0.2.11 → 0.2.13

package/AI_REFERENCE.md

@@ -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
 ```
 
@@ -43,8 +42,7 @@ packages/ai-provider/
 |---|---|---|---|
 | `/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 }` |
+| `/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,38 @@ 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);
+```
+
+### 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
@@ -83,12 +111,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`
 
@@ -124,6 +148,9 @@ interface GenerateOptions {
   system?: string;       // system prompt
   maxTokens?: number;
   temperature?: number;
+  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
 }
 ```
 

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,13 +30,13 @@ 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({
@@ -47,7 +47,7 @@ const ai = krutAI({
 
 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
 
@@ -107,32 +92,20 @@ const response = await ai.chat([
       }
     ]
   }
-], { model: 'gpt-4o' });
-```
-
-### Streaming Multi-turn Chat
-
-```typescript
-const ai = krutAI({
-  apiKey: process.env.KRUTAI_API_KEY!,
+], { 
+  model: 'gpt-4o',
+  // You can also pass images, documents, or pdfs via GenerateOptions
+  images: ['https://example.com/photo.jpg'],
+  documents: ['https://example.com/doc.docx'],
+  pdf: ['https://example.com/report.pdf']
 });
-
-await ai.initialize();
-
-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)
+### Streaming (Proxying SSE Streams)
 
-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:
+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`.
+
+`streamChatResponse` returns the raw fetch `Response` object containing the `text/event-stream` body from deployed LangChain server.
 
 ```typescript
 // app/api/chat/route.ts
@@ -142,11 +115,30 @@ 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 }));
+  }
+}
+```
+
 ### Skip validation (useful for tests)
 
 ```typescript
@@ -157,7 +149,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
@@ -168,8 +160,7 @@ Your LangChain server must expose these endpoints:
 |---|---|---|---|
 | `/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": "...", ... }` |
+| `/stream` | POST | `Authorization: Bearer <key>` | `{ "messages": [...], "model": "...", ... }` |
 
 **Validation response:** `{ "valid": true }` or `{ "valid": false, "message": "reason" }`
 

package/dist/index.d.mts

@@ -84,6 +84,14 @@ interface GenerateOptions {
      * Array of image URLs or base64 data URIs to include with the request.
      */
     images?: string[];
+    /**
+     * Array of document URLs or base64 data URIs (e.g. PDFs) to include with the request.
+     */
+    documents?: string[];
+    /**
+     * Array of PDF URLs or base64 data URIs to include with the request.
+     */
+    pdf?: string[];
 }
 
 /**
@@ -138,57 +146,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.
@@ -199,17 +156,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)
+     * @param prompt - The user prompt string
+     * @param options - Optional overrides (model, system, maxTokens, temperature)
      * @returns The assistant's response text
      */
-    chat(messages: ChatMessage[], options?: GenerateOptions): Promise<string>;
+    chat(prompt: string, options?: GenerateOptions): Promise<string>;
 }
 
 /**
@@ -229,7 +186,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);
  * ```
  *
@@ -241,7 +198,7 @@ declare class KrutAIProvider {
  *   model: 'gpt-4o',
  * });
  * await ai.initialize();
- * const text = await ai.generate('Hello!');
+ * const text = await ai.chat('Hello!');
  * ```
  *
  * @example Streaming
@@ -252,10 +209,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
@@ -279,7 +234,7 @@ declare class KrutAIProvider {
  * });
  *
  * await ai.initialize();
- * const text = await ai.generate('Hello!');
+ * const text = await ai.chat('Hello!');
  * ```
  */
 declare function krutAI(config: KrutAIProviderConfig & {

package/dist/index.d.ts

@@ -84,6 +84,14 @@ interface GenerateOptions {
      * Array of image URLs or base64 data URIs to include with the request.
      */
     images?: string[];
+    /**
+     * Array of document URLs or base64 data URIs (e.g. PDFs) to include with the request.
+     */
+    documents?: string[];
+    /**
+     * Array of PDF URLs or base64 data URIs to include with the request.
+     */
+    pdf?: string[];
 }
 
 /**
@@ -138,57 +146,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.
@@ -199,17 +156,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)
+     * @param prompt - The user prompt string
+     * @param options - Optional overrides (model, system, maxTokens, temperature)
      * @returns The assistant's response text
      */
-    chat(messages: ChatMessage[], options?: GenerateOptions): Promise<string>;
+    chat(prompt: string, options?: GenerateOptions): Promise<string>;
 }
 
 /**
@@ -229,7 +186,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);
  * ```
  *
@@ -241,7 +198,7 @@ declare class KrutAIProvider {
  *   model: 'gpt-4o',
  * });
  * await ai.initialize();
- * const text = await ai.generate('Hello!');
+ * const text = await ai.chat('Hello!');
  * ```
  *
  * @example Streaming
@@ -252,10 +209,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
@@ -279,7 +234,7 @@ declare class KrutAIProvider {
  * });
  *
  * await ai.initialize();
- * const text = await ai.generate('Hello!');
+ * const text = await ai.chat('Hello!');
  * ```
  */
 declare function krutAI(config: KrutAIProviderConfig & {