ai.matey.react.core 0.2.0

package/dist/esm/use-object.js

@@ -0,0 +1,247 @@
+/**
+ * useObject Hook
+ *
+ * React hook for streaming structured objects with streaming support.
+ *
+ * @module
+ */
+import { useState, useCallback, useRef } from 'react';
+/**
+ * useObject - React hook for streaming structured objects.
+ *
+ * Provides state management for streaming JSON objects with
+ * partial updates as data arrives.
+ *
+ * @example
+ * ```tsx
+ * import { useObject } from 'ai.matey.react.core';
+ *
+ * interface Recipe {
+ *   name: string;
+ *   ingredients: string[];
+ *   instructions: string[];
+ * }
+ *
+ * function RecipeGenerator() {
+ *   const { object, submit, isLoading } = useObject<Recipe>({
+ *     api: '/api/generate-recipe',
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => submit('Generate a pasta recipe')} disabled={isLoading}>
+ *         Generate Recipe
+ *       </button>
+ *       {object && (
+ *         <div>
+ *           <h2>{object.name}</h2>
+ *           <ul>{object.ingredients?.map((i, idx) => <li key={idx}>{i}</li>)}</ul>
+ *         </div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useObject(options = {}) {
+    const { api = '/api/object', schema, initialValue, headers = {}, body = {}, onFinish, onError, } = options;
+    // State
+    const [object, setObject] = useState(initialValue);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(undefined);
+    // Refs for abort control
+    const abortControllerRef = useRef(null);
+    /**
+     * Stop current streaming request.
+     */
+    const stop = useCallback(() => {
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+        }
+    }, []);
+    /**
+     * Submit a prompt to generate an object.
+     */
+    const submit = useCallback(async (prompt) => {
+        try {
+            setIsLoading(true);
+            setError(undefined);
+            setObject(undefined);
+            // Create abort controller
+            abortControllerRef.current = new AbortController();
+            const { signal } = abortControllerRef.current;
+            // Prepare request body
+            const requestBody = {
+                prompt,
+                schema,
+                ...body,
+            };
+            // Make request
+            const response = await fetch(api, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...headers,
+                },
+                body: JSON.stringify(requestBody),
+                signal,
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            if (!response.body) {
+                throw new Error('Response body is null');
+            }
+            // Handle streaming response
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let jsonBuffer = '';
+            // Read stream
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                const chunk = decoder.decode(value, { stream: true });
+                // Parse SSE data format
+                const lines = chunk.split('\n');
+                for (const line of lines) {
+                    if (line.startsWith('data: ')) {
+                        const data = line.slice(6);
+                        if (data === '[DONE]') {
+                            break;
+                        }
+                        try {
+                            const parsed = JSON.parse(data);
+                            if (parsed.object) {
+                                // Direct object update
+                                setObject(parsed.object);
+                            }
+                            else if (parsed.partial) {
+                                // Partial JSON string
+                                jsonBuffer = parsed.partial;
+                                try {
+                                    const partialObject = JSON.parse(jsonBuffer);
+                                    setObject(partialObject);
+                                }
+                                catch {
+                                    // Incomplete JSON, try to parse what we can
+                                    const repaired = tryRepairJson(jsonBuffer);
+                                    if (repaired) {
+                                        setObject(repaired);
+                                    }
+                                }
+                            }
+                            else if (parsed.delta) {
+                                // Delta update - append to buffer
+                                jsonBuffer += parsed.delta;
+                                try {
+                                    const partialObject = JSON.parse(jsonBuffer);
+                                    setObject(partialObject);
+                                }
+                                catch {
+                                    // Incomplete JSON
+                                    const repaired = tryRepairJson(jsonBuffer);
+                                    if (repaired) {
+                                        setObject(repaired);
+                                    }
+                                }
+                            }
+                        }
+                        catch {
+                            // Ignore parse errors
+                        }
+                    }
+                }
+            }
+            // Try to parse final object
+            let finalObject;
+            if (jsonBuffer) {
+                try {
+                    finalObject = JSON.parse(jsonBuffer);
+                    setObject(finalObject);
+                }
+                catch {
+                    // Keep partial object
+                }
+            }
+            onFinish?.({ object: finalObject, error: undefined });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                // Request was aborted
+                return;
+            }
+            const error = err instanceof Error ? err : new Error(String(err));
+            setError(error);
+            onError?.(error);
+            onFinish?.({ object: undefined, error });
+        }
+        finally {
+            setIsLoading(false);
+            abortControllerRef.current = null;
+        }
+    }, [api, body, headers, onError, onFinish, schema]);
+    return {
+        object,
+        submit,
+        stop,
+        isLoading,
+        error,
+    };
+}
+/**
+ * Try to repair incomplete JSON by closing open brackets.
+ */
+function tryRepairJson(json) {
+    if (!json.trim()) {
+        return null;
+    }
+    // Count open brackets
+    let openBraces = 0;
+    let openBrackets = 0;
+    let inString = false;
+    let escape = false;
+    for (const char of json) {
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (char === '\\') {
+            escape = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString) {
+            continue;
+        }
+        if (char === '{')
+            openBraces++;
+        if (char === '}')
+            openBraces--;
+        if (char === '[')
+            openBrackets++;
+        if (char === ']')
+            openBrackets--;
+    }
+    // Try to close the JSON
+    let repaired = json;
+    // If we're in a string, close it
+    if (inString) {
+        repaired += '"';
+    }
+    // Close brackets and braces
+    repaired += ']'.repeat(Math.max(0, openBrackets));
+    repaired += '}'.repeat(Math.max(0, openBraces));
+    try {
+        return JSON.parse(repaired);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=use-object.js.map

package/dist/esm/use-object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-object.js","sourceRoot":"","sources":["../../src/use-object.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AI Matey React Core
+ *
+ * Core React hooks for building AI-powered applications.
+ *
+ * @packageDocumentation
+ */
+export { useChat } from './use-chat.js';
+export { useCompletion } from './use-completion.js';
+export { useObject } from './use-object.js';
+export type { Message, ToolCall, ToolInvocation, Tool, UseChatOptions, UseChatReturn, ChatRequestOptions, UseCompletionOptions, UseCompletionReturn, CompletionRequestOptions, UseObjectOptions, UseObjectReturn, DirectBackend, DirectModeOptions, DirectToolCallHandler, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,YAAY,EACV,OAAO,EACP,QAAQ,EACR,cAAc,EACd,IAAI,EACJ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EAEf,aAAa,EACb,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/types/types.d.ts

@@ -0,0 +1,295 @@
+/**
+ * React Core Types
+ *
+ * Type definitions for React hooks and utilities.
+ *
+ * @module
+ */
+import type { IRChatRequest, IRChatResponse, IRStreamChunk, IRParameters, IRTool } from 'ai.matey.types';
+/**
+ * Backend adapter interface for direct mode.
+ * This allows using a BackendAdapter or Bridge directly without HTTP.
+ */
+export interface DirectBackend {
+    execute(request: IRChatRequest, signal?: AbortSignal): Promise<IRChatResponse>;
+    executeStream?(request: IRChatRequest, signal?: AbortSignal): AsyncGenerator<IRStreamChunk, void, undefined>;
+}
+/**
+ * Handler for tool calls in direct mode.
+ */
+export type DirectToolCallHandler = (toolName: string, toolInput: Record<string, unknown>, toolId: string) => Promise<string | {
+    content: string;
+    isError?: boolean;
+}>;
+/**
+ * Direct backend mode options.
+ */
+export interface DirectModeOptions {
+    /**
+     * The backend adapter to use (Bridge or BackendAdapter).
+     */
+    backend: DirectBackend;
+    /**
+     * System prompt to prepend to conversations.
+     */
+    systemPrompt?: string | (() => string | Promise<string>);
+    /**
+     * Default IR parameters for requests.
+     */
+    defaultParameters?: IRParameters;
+    /**
+     * Available tools for the conversation.
+     */
+    tools?: readonly IRTool[];
+    /**
+     * Handler for tool calls.
+     */
+    onToolCall?: DirectToolCallHandler;
+    /**
+     * Auto-execute tools and continue the conversation.
+     * @default false
+     */
+    autoExecuteTools?: boolean;
+    /**
+     * Maximum tool execution rounds.
+     * @default 10
+     */
+    maxToolRounds?: number;
+}
+/**
+ * Message in a chat conversation.
+ */
+export interface Message {
+    /** Unique message ID */
+    id: string;
+    /** Message role */
+    role: 'user' | 'assistant' | 'system';
+    /** Message content */
+    content: string;
+    /** Creation timestamp */
+    createdAt?: Date;
+    /** Tool calls made by this message */
+    toolCalls?: ToolCall[];
+    /** Tool invocations and results */
+    toolInvocations?: ToolInvocation[];
+}
+/**
+ * Tool call request.
+ */
+export interface ToolCall {
+    /** Tool call ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool arguments */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Tool invocation with result.
+ */
+export interface ToolInvocation {
+    /** Tool call ID */
+    toolCallId: string;
+    /** Tool name */
+    toolName: string;
+    /** Tool arguments */
+    args: Record<string, unknown>;
+    /** Tool result */
+    result?: unknown;
+    /** Invocation state */
+    state: 'pending' | 'completed' | 'error';
+}
+/**
+ * Chat hook options.
+ *
+ * Supports two modes:
+ * 1. HTTP Mode (default): Uses `api` endpoint with fetch
+ * 2. Direct Mode: Uses `direct.backend` with wrapper-ir for direct backend access
+ */
+export interface UseChatOptions {
+    /** Initial messages */
+    initialMessages?: Message[];
+    /** Initial input value */
+    initialInput?: string;
+    /** Chat ID for persistence */
+    id?: string;
+    /** API endpoint for chat */
+    api?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body extras */
+    body?: Record<string, unknown>;
+    /** Stream protocol */
+    streamProtocol?: 'text' | 'data';
+    /** Called for each response chunk (HTTP mode only) */
+    onResponse?: (response: Response) => void;
+    /**
+     * Direct backend mode configuration.
+     * When provided, bypasses HTTP and uses the backend adapter directly.
+     */
+    direct?: DirectModeOptions;
+    /** Generate unique message IDs */
+    generateId?: () => string;
+    /** Called when response stream finishes */
+    onFinish?: (message: Message) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Keep last message on error */
+    keepLastMessageOnError?: boolean;
+    /** Max number of automatic tool retries */
+    maxToolRoundtrips?: number;
+    /** Send extra message fields */
+    sendExtraMessageFields?: boolean;
+}
+/**
+ * Chat hook return value.
+ */
+export interface UseChatReturn {
+    /** Chat messages */
+    messages: Message[];
+    /** Current input value */
+    input: string;
+    /** Set input value */
+    setInput: (input: string) => void;
+    /** Handle input change */
+    handleInputChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    /** Handle form submit */
+    handleSubmit: (e?: React.FormEvent<HTMLFormElement>, options?: ChatRequestOptions) => void;
+    /** Submit message programmatically */
+    append: (message: Message | string, options?: ChatRequestOptions) => Promise<string | null | undefined>;
+    /** Reload last message */
+    reload: (options?: ChatRequestOptions) => Promise<string | null | undefined>;
+    /** Stop streaming */
+    stop: () => void;
+    /** Set messages */
+    setMessages: (messages: Message[] | ((messages: Message[]) => Message[])) => void;
+    /** Whether currently loading */
+    isLoading: boolean;
+    /** Error if any */
+    error: Error | undefined;
+    /** Data from API */
+    data?: unknown[];
+}
+/**
+ * Chat request options.
+ */
+export interface ChatRequestOptions {
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body extras */
+    body?: Record<string, unknown>;
+    /** Data to send */
+    data?: Record<string, string>;
+    /** Tools to use */
+    tools?: Record<string, Tool>;
+}
+/**
+ * Tool definition.
+ */
+export interface Tool {
+    /** Tool description */
+    description?: string;
+    /** Tool parameter schema */
+    parameters: Record<string, unknown>;
+    /** Execute the tool */
+    execute?: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Completion hook options.
+ */
+export interface UseCompletionOptions {
+    /** Initial prompt */
+    initialInput?: string;
+    /** Initial completion */
+    initialCompletion?: string;
+    /** Completion ID */
+    id?: string;
+    /** API endpoint */
+    api?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body extras */
+    body?: Record<string, unknown>;
+    /** Called when completion finishes */
+    onFinish?: (prompt: string, completion: string) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Called for each response chunk */
+    onResponse?: (response: Response) => void;
+    /** Stream protocol */
+    streamProtocol?: 'text' | 'data';
+}
+/**
+ * Completion hook return value.
+ */
+export interface UseCompletionReturn {
+    /** Current completion */
+    completion: string;
+    /** Current input */
+    input: string;
+    /** Set input */
+    setInput: (input: string) => void;
+    /** Handle input change */
+    handleInputChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    /** Handle form submit */
+    handleSubmit: (e?: React.FormEvent<HTMLFormElement>) => void;
+    /** Complete programmatically */
+    complete: (prompt: string, options?: CompletionRequestOptions) => Promise<string | null | undefined>;
+    /** Stop streaming */
+    stop: () => void;
+    /** Set completion */
+    setCompletion: (completion: string) => void;
+    /** Whether currently loading */
+    isLoading: boolean;
+    /** Error if any */
+    error: Error | undefined;
+    /** Data from API */
+    data?: unknown[];
+}
+/**
+ * Completion request options.
+ */
+export interface CompletionRequestOptions {
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body extras */
+    body?: Record<string, unknown>;
+}
+/**
+ * Object hook options.
+ */
+export interface UseObjectOptions<T> {
+    /** API endpoint */
+    api?: string;
+    /** Schema for validation */
+    schema?: unknown;
+    /** Initial object value */
+    initialValue?: Partial<T>;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body extras */
+    body?: Record<string, unknown>;
+    /** Called on finish */
+    onFinish?: (event: {
+        object: T | undefined;
+        error: Error | undefined;
+    }) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Object hook return value.
+ */
+export interface UseObjectReturn<T> {
+    /** Partial object being streamed */
+    object: Partial<T> | undefined;
+    /** Submit a prompt */
+    submit: (prompt: string) => void;
+    /** Stop streaming */
+    stop: () => void;
+    /** Whether currently loading */
+    isLoading: boolean;
+    /** Error if any */
+    error: Error | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types/use-chat.d.ts

@@ -0,0 +1,73 @@
+/**
+ * useChat Hook
+ *
+ * React hook for building chat interfaces with streaming support.
+ * Supports both HTTP API mode and direct backend mode.
+ *
+ * @module
+ */
+import type { UseChatOptions, UseChatReturn } from './types.js';
+/**
+ * useChat - React hook for chat interfaces.
+ *
+ * Provides state management, streaming, and utilities for building
+ * chat applications with AI backends.
+ *
+ * Supports two modes:
+ * 1. HTTP Mode (default): Uses `api` endpoint with fetch
+ * 2. Direct Mode: Uses `direct.backend` for direct backend access
+ *
+ * @example HTTP Mode
+ * ```tsx
+ * import { useChat } from 'ai.matey.react.core';
+ *
+ * function ChatComponent() {
+ *   const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+ *     api: '/api/chat',
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {messages.map((m) => (
+ *         <div key={m.id}>{m.role}: {m.content}</div>
+ *       ))}
+ *       <form onSubmit={handleSubmit}>
+ *         <input value={input} onChange={handleInputChange} />
+ *         <button type="submit" disabled={isLoading}>Send</button>
+ *       </form>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Direct Mode
+ * ```tsx
+ * import { useChat } from 'ai.matey.react.core';
+ * import { AnthropicBackend } from 'ai.matey.backend/anthropic';
+ *
+ * const backend = new AnthropicBackend({ apiKey: process.env.ANTHROPIC_API_KEY });
+ *
+ * function ChatComponent() {
+ *   const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+ *     direct: {
+ *       backend,
+ *       systemPrompt: 'You are a helpful assistant.',
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {messages.map((m) => (
+ *         <div key={m.id}>{m.role}: {m.content}</div>
+ *       ))}
+ *       <form onSubmit={handleSubmit}>
+ *         <input value={input} onChange={handleInputChange} />
+ *         <button type="submit" disabled={isLoading}>Send</button>
+ *       </form>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useChat(options?: UseChatOptions): UseChatReturn;
+//# sourceMappingURL=use-chat.d.ts.map

package/dist/types/use-chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-chat.d.ts","sourceRoot":"","sources":["../../src/use-chat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAW,cAAc,EAAE,aAAa,EAAsB,MAAM,YAAY,CAAC;AAmB7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,aAAa,CA6anE"}