@blank-utils/llm 0.2.3 → 0.2.7

package/README.md

@@ -39,20 +39,61 @@ bun add @blank-utils/llm
 
 ## Quick Start
 
-### React (Recommended)
+### Quick Chat (Fully Featured App)
+
+The fastest way to get started. `<ChatApp>` includes the provider, model management, and UI in a single component:
+
+```tsx
+import { ChatApp } from "@blank-utils/llm/react";
+
+export default function App() {
+  return (
+    <ChatApp
+      defaultModel="qwen-2.5-0.5b"
+      theme="dark" // 'dark' | 'light'
+      systemPrompt="You are a helpful assistant."
+    />
+  );
+}
+```
+
+### Components (Custom Setup)
+
+If you already have a provider or want more control, use the `<Chat>` component:
+
+```tsx
+import { LLMProvider, Chat } from "@blank-utils/llm/react";
+
+export default function App() {
+  return (
+    <LLMProvider model="qwen-2.5-0.5b">
+      <Chat
+        theme="dark"
+        systemPrompt="You are a helpful assistant."
+        placeholder="Ask me anything..."
+      />
+    </LLMProvider>
+  );
+}
+```
+
+### Custom UI with Hooks
+
+Build your own interface from scratch using our hooks:
 
 ```tsx
 import { LLMProvider, useChat, useLLM } from "@blank-utils/llm/react";
+// ... (rest of the hooks example)
 
 function App() {
   return (
     <LLMProvider model="qwen-2.5-0.5b">
-      <Chat />
+      <ChatUI />
     </LLMProvider>
   );
 }
 
-function Chat() {
+function ChatUI() {
   const { isLoading, loadProgress } = useLLM();
   const {
     messages,
@@ -143,7 +184,9 @@ const cleanup = llm.attachToInput("#prompt-input", "#response-output", {
 │   │   ├── webllm.ts     # WebLLM backend (WebGPU)
 │   │   └── transformers.ts # Transformers.js backend (WASM / WebGPU)
 │   └── react/
-│       └── index.tsx     # React context, provider, hooks, components
+│       ├── index.tsx     # React context, provider, hooks
+│       ├── components.tsx # <Chat> — ready-made chat interface
+│       └── chat-input.tsx # <ChatInput> — auto-resizing input widget
 └── dist/                 # Built output (ESM)
 ```
 
@@ -279,6 +322,93 @@ Conditional rendering components:
 </LLMReady>
 ```
 
+### Default Chat Interface explained
+
+The `<Chat>` and `<ChatApp>` components provide a production-ready interface with "Terminal Luxury" aesthetics.
+
+**Key Features & Usage Points:**
+
+- **✨ Zero Config**: Just drop it in. No CSS files to import, no state to manage.
+- **🎨 Rich Text Rendering**:
+  - **Global Markdown**: Bold, cursives, lists, tables.
+  - **Code Blocks**: Syntax highlighting for 20+ languages.
+  - **Diagrams**: Renders `mermaid` diagrams automatically.
+  - **Math**: Supports LateX expressions.
+- **⚡ Eager Interaction**: Users can type and send messages _while_ the model is still initializing. The chat controls the queue.
+- **🌗 Theming**: Built-in 'dark' (cherry red accents) and 'light' modes.
+- **🔄 Model Switching**:
+  - If using `<ChatApp />`, a model selector dropdown is included automatically.
+  - If using `<Chat />`, pass `onModelChange` to enable the dropdown.
+- **🛠️ Extensible Toolbar**: Use the `inputActions` prop to add your own buttons (e.g., upload, clear) to the input area.
+
+### `<Chat>` Component API
+
+```tsx
+<Chat
+  // Appearance
+  theme="dark" // 'dark' | 'light'
+  maxHeight="600px" // CSS max-height
+  className="my-chat" // Extra classes
+  // Content
+  systemPrompt="..." // Default: "You are a helpful AI assistant..."
+  welcomeMessage="..." // Text shown when chat is empty
+  placeholder="..." // Input placeholder
+  // Features
+  showHeader={true} // Toggle header/model info
+  showProgress={true} // Toggle loading progress bar
+  // Callbacks
+  onSend={(msg) => {}} // Listen to user messages
+  onResponse={(res) => {}} // Listen to AI responses
+  onModelChange={(id) => {}} // Enable model switching dropdown
+  inputActions={
+    <>
+      <button>Clear</button>
+    </>
+  } // Add custom buttons
+/>
+```
+
+### `<ChatApp>` Component API
+
+Wrapper that combines `LLMProvider` and `Chat`.
+
+```tsx
+<ChatApp
+  defaultModel="qwen-2.5-0.5b"
+  defaultBackend="auto" // 'webllm' | 'transformers'
+  autoLoad={true} // Start downloading immediately
+  {...chatProps} // All <Chat> props are supported
+/>
+```
+
+### `<ChatInput>`
+
+Standalone auto-resizing input component. Use it to build custom chat layouts:
+
+```tsx
+import { ChatInput } from "@blank-utils/llm/react";
+
+<ChatInput
+  value={input} // Controlled value
+  onChange={setInput} // Value change handler
+  onSend={handleSend} // Submit handler (Enter or button)
+  onStop={handleStop} // Stop generation
+  disabled={false} // Disable input
+  isGenerating={false} // Show stop button instead of send
+  placeholder="Type..." // Placeholder text
+  maxRows={5} // Max rows before scroll
+  theme="dark" // 'dark' | 'light'
+  actions={<MyButtons />} // Custom toolbar actions
+/>;
+```
+
+**Features:**
+
+- 📝 Auto-resizes up to `maxRows` then scrolls
+- ⌨️ Enter to send, Shift+Enter for newline
+- ⏹️ Stop button while generating
+- 🎨 Dark/light theme support
+
 ---
 
 ## Vanilla JS API