@blank-utils/llm 0.1.0 → 0.2.0

package/dist/react/index.d.ts

@@ -0,0 +1,310 @@
+/**
+ * React Integration for Local LLM
+ *
+ * Provides React context, hooks, and components for easy LLM integration.
+ *
+ * @example
+ * ```tsx
+ * import { LLMProvider, useChat } from 'local-llm/react';
+ *
+ * function App() {
+ *   return (
+ *     <LLMProvider model="qwen-2.5-0.5b">
+ *       <ChatComponent />
+ *     </LLMProvider>
+ *   );
+ * }
+ *
+ * function ChatComponent() {
+ *   const { messages, send, isGenerating } = useChat();
+ *
+ *   return (
+ *     <div>
+ *       {messages.map((m, i) => <p key={i}>{m.content}</p>)}
+ *       <button onClick={() => send('Hello!')}>Send</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+import * as React from 'react';
+import type { LLMConfig, ChatMessage, GenerateOptions, LoadProgress, Backend } from '../types';
+import { type LocalLLM } from '../core';
+export type { ChatMessage, GenerateOptions, LoadProgress, Backend } from '../types';
+export type { LocalLLM } from '../core';
+export interface LLMContextValue {
+    /** The LLM instance (null while loading) */
+    llm: LocalLLM | null;
+    /** Whether the model is currently loading */
+    isLoading: boolean;
+    /** Whether the model is ready for inference */
+    isReady: boolean;
+    /** Current loading progress */
+    loadProgress: LoadProgress | null;
+    /** Error if loading failed */
+    error: Error | null;
+    /** Current model ID */
+    modelId: string | null;
+    /** Backend being used */
+    backend: Backend | null;
+    /** Manually reload the model */
+    reload: () => Promise<void>;
+    /** Unload the model */
+    unload: () => Promise<void>;
+}
+export interface LLMProviderProps extends Omit<LLMConfig, 'onLoadProgress'> {
+    children: React.ReactNode;
+    /**
+     * Auto-load the model on mount
+     * @default true
+     */
+    autoLoad?: boolean;
+    /**
+     * Callback when model finishes loading
+     */
+    onLoad?: (llm: LocalLLM) => void;
+    /**
+     * Callback on loading progress
+     */
+    onProgress?: (progress: LoadProgress) => void;
+    /**
+     * Callback on error
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Provider component that manages LLM lifecycle
+ *
+ * @example
+ * ```tsx
+ * <LLMProvider
+ *   model="qwen-2.5-0.5b"
+ *   backend="auto"
+ *   onProgress={(p) => console.log(p.progress)}
+ * >
+ *   <App />
+ * </LLMProvider>
+ * ```
+ */
+export declare function LLMProvider({ children, autoLoad, onLoad, onProgress, onError, ...config }: LLMProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the LLM context
+ *
+ * @throws If used outside of LLMProvider
+ *
+ * @example
+ * ```tsx
+ * const { llm, isReady, loadProgress } = useLLM();
+ * ```
+ */
+export declare function useLLM(): LLMContextValue;
+export interface UseChatOptions {
+    /** Initial messages */
+    initialMessages?: ChatMessage[];
+    /** System prompt */
+    systemPrompt?: string;
+    /** Generation options */
+    generateOptions?: GenerateOptions;
+    /**
+     * Queue messages while model is loading
+     * When true, users can send messages before model loads - they'll be processed once ready
+     * @default true
+     */
+    queueWhileLoading?: boolean;
+    /** Called when generation starts */
+    onStart?: () => void;
+    /** Called on each token (streaming) */
+    onToken?: (token: string, fullText: string) => void;
+    /** Called when generation completes */
+    onFinish?: (response: string) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+export interface UseChatReturn {
+    /** All messages in the conversation */
+    messages: ChatMessage[];
+    /** Current input value (for controlled input) */
+    input: string;
+    /** Set the input value */
+    setInput: (input: string) => void;
+    /** Whether currently generating a response */
+    isGenerating: boolean;
+    /** Whether a message is queued waiting for model to load */
+    isPending: boolean;
+    /** Current streaming text (while generating) */
+    streamingText: string;
+    /** Send a message and get a response */
+    send: (content?: string) => Promise<string>;
+    /** Stop the current generation */
+    stop: () => void;
+    /** Clear all messages */
+    clear: () => void;
+    /** Add a message without generating a response */
+    append: (message: ChatMessage) => void;
+    /** Reload/regenerate the last assistant message */
+    reload: () => Promise<string>;
+}
+/**
+ * Hook for managing a chat conversation with the LLM
+ *
+ * Supports **eager loading** - users can send messages while the model loads.
+ * Messages are queued and processed automatically once the model is ready.
+ *
+ * @example
+ * ```tsx
+ * function ChatComponent() {
+ *   const { isLoading, loadProgress } = useLLM();
+ *   const {
+ *     messages,
+ *     input,
+ *     setInput,
+ *     send,
+ *     isGenerating,
+ *     isPending,  // true if message is queued waiting for model
+ *     streamingText,
+ *   } = useChat({
+ *     systemPrompt: 'You are a helpful assistant.',
+ *     queueWhileLoading: true,  // default: true
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {isLoading && <p>Loading model... {loadProgress?.progress}%</p>}
+ *
+ *       {messages.map((m, i) => (
+ *         <div key={i} className={m.role}>
+ *           {m.content}
+ *         </div>
+ *       ))}
+ *
+ *       {isPending && <p className="pending">Waiting for model to load...</p>}
+ *       {isGenerating && <div className="assistant">{streamingText}</div>}
+ *
+ *       {/* Users can type immediately, even before model loads *\/}
+ *       <input
+ *         value={input}
+ *         onChange={(e) => setInput(e.target.value)}
+ *         onKeyDown={(e) => e.key === 'Enter' && send()}
+ *         placeholder={isLoading ? 'Type now, send when ready...' : 'Type a message...'}
+ *       />
+ *       <button onClick={() => send()} disabled={isGenerating}>
+ *         {isPending ? 'Queued...' : 'Send'}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useChat(options?: UseChatOptions): UseChatReturn;
+export interface UseStreamOptions {
+    /** Generation options */
+    generateOptions?: GenerateOptions;
+    /** Called on each token */
+    onToken?: (token: string, fullText: string) => void;
+    /** Called when complete */
+    onFinish?: (response: string) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+export interface UseStreamReturn {
+    /** Current streamed text */
+    text: string;
+    /** Whether currently streaming */
+    isStreaming: boolean;
+    /** Start streaming a response */
+    stream: (messages: ChatMessage[] | string) => Promise<string>;
+    /** Stop streaming */
+    stop: () => void;
+    /** Clear the text */
+    clear: () => void;
+}
+/**
+ * Hook for simple streaming generation
+ *
+ * @example
+ * ```tsx
+ * function StreamComponent() {
+ *   const { text, isStreaming, stream, clear } = useStream();
+ *
+ *   return (
+ *     <div>
+ *       <pre>{text}</pre>
+ *       <button onClick={() => stream('Tell me a story')} disabled={isStreaming}>
+ *         Generate
+ *       </button>
+ *       <button onClick={clear}>Clear</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useStream(options?: UseStreamOptions): UseStreamReturn;
+export interface UseCompletionOptions {
+    /** Generation options */
+    generateOptions?: GenerateOptions;
+}
+export interface UseCompletionReturn {
+    /** Current completion text */
+    completion: string;
+    /** Whether currently generating */
+    isLoading: boolean;
+    /** Generate a completion (non-streaming) */
+    complete: (prompt: string) => Promise<string>;
+    /** Clear the completion */
+    clear: () => void;
+}
+/**
+ * Hook for simple non-streaming completion
+ *
+ * @example
+ * ```tsx
+ * function CompletionComponent() {
+ *   const { completion, isLoading, complete } = useCompletion();
+ *
+ *   return (
+ *     <div>
+ *       <p>{completion}</p>
+ *       <button onClick={() => complete('Summarize this')} disabled={isLoading}>
+ *         Complete
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCompletion(options?: UseCompletionOptions): UseCompletionReturn;
+export interface LLMLoadingProps {
+    /** Custom loading UI */
+    children?: React.ReactNode;
+    /** Class name for the wrapper */
+    className?: string;
+}
+/**
+ * Component that shows loading state while LLM is loading
+ *
+ * @example
+ * ```tsx
+ * <LLMLoading>
+ *   <p>Loading model...</p>
+ * </LLMLoading>
+ * ```
+ */
+export declare function LLMLoading({ children, className }: LLMLoadingProps): import("react/jsx-runtime").JSX.Element | null;
+export interface LLMReadyProps {
+    /** Content to show when ready */
+    children: React.ReactNode;
+    /** Content to show while loading */
+    fallback?: React.ReactNode;
+}
+/**
+ * Component that only renders children when LLM is ready
+ *
+ * @example
+ * ```tsx
+ * <LLMReady fallback={<Loading />}>
+ *   <ChatInterface />
+ * </LLMReady>
+ * ```
+ */
+export declare function LLMReady({ children, fallback }: LLMReadyProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/react/index.js

@@ -118,7 +118,7 @@ class WebLLMProvider {
   }
   async load(modelId, onProgress) {
     const resolvedModel = resolveModelId(modelId);
-    const { CreateMLCEngine } = await import("../index-mv82xhnr.js");
+    const { CreateMLCEngine } = await import("../index-yyxm9rp0.js");
     const initProgressCallback = (report) => {
       if (onProgress) {
         const progress = {
@@ -308,7 +308,7 @@ class TransformersProvider {
   }
   async load(modelId, onProgress) {
     const resolvedModel = modelId in TRANSFORMERS_MODELS ? TRANSFORMERS_MODELS[modelId] : modelId;
-    const { pipeline, env } = await import("../transformers.web-nb96jrhe.js");
+    const { pipeline, env } = await import("../transformers.web-1qr6h84s.js");
     env.allowLocalModels = false;
     env.useBrowserCache = true;
     let deviceOption = "wasm";
@@ -359,7 +359,7 @@ class TransformersProvider {
       throw new Error("Model not loaded. Call load() first.");
     }
     const prompt = formatPrompt(messages, this.currentModel);
-    const { TextStreamer } = await import("../transformers.web-nb96jrhe.js");
+    const { TextStreamer } = await import("../transformers.web-1qr6h84s.js");
     let fullText = "";
     const streamer = new TextStreamer(this.pipeline.tokenizer, {
       skip_prompt: true,
@@ -521,7 +521,7 @@ function createLoadingIndicator(containerSelector) {
     element: indicator
   };
 }
-// src/index.ts
+// src/core.ts
 function normalizeMessages(input, systemPrompt) {
   const messages = [];
   if (systemPrompt) {
@@ -599,7 +599,6 @@ async function isWebGPUSupported() {
   const caps = await detectCapabilities();
   return caps.webgpu;
 }
-var src_default = createLLM;
 
 // src/react/index.tsx
 import { jsxDEV, Fragment } from "react/jsx-dev-runtime";
@@ -950,5 +949,7 @@ export {
   LLMLoading
 };
 
-//# debugId=9760E9C5A8B8695164756E2164756E21
+export { checkWebGPU, checkWasm, detectCapabilities, logCapabilities, DEFAULT_WEBLLM_MODEL, WEBLLM_MODELS, WebLLMProvider, createWebLLMProvider, DEFAULT_TRANSFORMERS_MODEL, TRANSFORMERS_MODELS, TransformersProvider, createTransformersProvider, createOutputStreamer, attachToElements, createChatUI, createLoadingIndicator, createLLM, isWebGPUSupported, LLMProvider, useLLM, useChat, useStream, useCompletion, LLMLoading, LLMReady };
+
+//# debugId=654DAC199C2102F264756E2164756E21
 //# sourceMappingURL=index.js.map