vibe-ai-c 4.0.0 → 5.4.0

package/README.md

@@ -1,175 +1,166 @@
-# # VibeAI v4.0 - Orchestrator SDK
+# VibeAI v5.4.0
 
-VibeAI is a zero-dependency, browser-based AI management SDK. It handles multiple LLM providers (OpenAI, DeepSeek, Gemini, etc.), secure API key storage (AES-GCM), and complex task orchestration like concurrent batch processing.
+**Industrial-grade, zero-dependency, secure AI SDK for the modern web.**
 
-### 📦 Installation (Recommended)
+VibeAI is a "Good Taste" driven wrapper for OpenAI-compatible APIs. It eliminates the friction of managing providers, API keys, and complex SSE streams, allowing you to focus on the UI "vibe" while it handles the plumbing.
 
-For the most stable and optimized experience, always import from **unpkg**:
+## 🚀 Quick Start
 
-```javascript
-import { vibeAI } from 'https://unpkg.com/vibe-ai-c@4.0.0';
-```
-
----
-
-## 🏗 Core Architecture
-
-VibeAI v4.0 follows a three-tier hierarchy:
-
-1. **`vibeAI` (The Manager)**: Handles global configuration, UI modal rendering, encryption, and provider persistence.
-2. **`VibeInstance` (The Context)**: A bound interface to a specific UI element (e.g., a dropdown selector). It manages its own `AbortController` and state.
-3. **`VibeBatch` (The Orchestrator)**: Handles high-concurrency tasks, retries, and progress tracking.
-
----
-
-## 🛠 Quick Start
-
-### 1. Initialization and UI Binding
-
-Bind the SDK to your UI elements. VibeAI will automatically populate selects and handle focus-safe updates.
-
-```html
-<!-- HTML -->
-<button id="settings-btn">Open AI Settings</button>
-<select id="chat-model-selector"></select>
-
-<script type="module">
-    import { vibeAI } from 'https://unpkg.com/vibe-ai-c@4.0.0';
-
-    await vibeAI.init({ setupBtnId: 'settings-btn' });
-    // Bind a selector to manage model choices
-    vibeAI.bindModelSelect('chat-model-selector');
-</script>
-```
-
-### 2. Single Chat (Simple vs Stream)
-
-Use an **Instance** to perform chat operations.
+Inject high-performance AI capabilities into any static HTML page in seconds.
 
 ```javascript
-const instance = vibeAI.getInstance('chat-model-selector');
-
-// A. Simple Ask (Returns string)
-const response = await instance.ask("What is the capital of France?");
-console.log(response);
-
-// B. Streaming Chat
-const stream = await instance.chat({ 
-    messages: [{ role: 'user', content: 'Write a poem.' }] 
-}, { stream: true });
-
-for await (const chunk of stream) {
-    process.stdout.write(chunk); // UI: update your text container here
-}
-```
+import { vibeAI } from 'https://unpkg.com/vibe-ai-c@5.4.0';
 
-### 3. Concurrent Batch Processing (Orchestrator)
+// 1. Initialize with your config button
+vibeAI.init({ setupBtnId: 'settings-btn' });
 
-Process hundreds of tasks with built-in concurrency limits and retries.
+// 2. Bind a standard <select> to the model list
+vibeAI.bindSelect('model-picker');
 
-```javascript
-const batch = vibeAI.createBatch('chat-model-selector', {
-    concurrency: 5, // Process 5 tasks at a time
-    retry: 2        // Retry failed tasks twice
+// 3. Chat
+const inst = vibeAI.getInstance('model-picker');
+const stream = inst.streamChat({ 
+    messages: [{ role: 'user', content: 'Hello' }] 
 });
 
-const tasks = ["Summarize A", "Summarize B", "Summarize C"];
-tasks.forEach(t => batch.add(t));
-
-const results = await batch.run((done, total, last) => {
-    console.log(`Progress: ${done}/${total} | Success: ${last.success}`);
-});
+for await (const chunk of stream) {
+    console.log(chunk.delta); // { type: 'content', delta: '...' }
+}
 ```
 
 ---
 
-## 🖼 Vision Support (Multimodal)
+## 🛠️ Integration Logic
 
-VibeAI provides a helper to convert `File` objects into LLM-compatible vision payloads.
+### 1. Rendering (Don't DIY CSS)
+Hand-writing CSS for AI responses is a trap. Use `marked.js` for parsing and `github-markdown-css` for styling. This ensures your "thoughts" and "content" look professional without adding 1000 lines of custom CSS.
 
-```javascript
-const fileInput = document.querySelector('input[type="file"]');
-const imagePart = await VibeAI.fileToVisionPayload(fileInput.files[0]);
-
-const instance = vibeAI.getInstance('chat-model-selector');
-await instance.chat({
-    messages: [{
-        role: 'user',
-        content: [
-            { type: 'text', text: 'What is in this image?' },
-            imagePart
-        ]
-    }]
-});
+```html
+<!-- Add to your <head> -->
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.5.1/github-markdown.min.css">
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
 ```
 
----
-
-## 📖 API Reference for LLMs
+### 2. The Streaming Protocol
+VibeAI v5.4 uses a rich object stream to support reasoning models (like DeepSeek R1 or OpenAI o1).
 
-### `vibeAI` Methods
+- `type: 'thought'`: Internal reasoning/chain-of-thought tokens.
+- `type: 'content'`: The actual message response.
+- `type: 'usage'`: Final token telemetry (prompt/completion counts).
 
-- `init({ setupBtnId: string })`: Initializes storage and binds the settings button.
-- `bindModelSelect(elementId: string)`: Automatically populates a `<select>` and persists its choice.
-- `getInstance(id: string): VibeInstance`: Returns a controlled instance for a specific selector.
-- `createBatch(instanceId: string, options: {concurrency, retry}): VibeBatch`: Creates a batch processor.
-- `static fileToVisionPayload(file: File): Promise<object>`: Converts File to OpenAI Vision format.
+### 3. Security Architecture
+VibeAI uses the **Web Crypto API** for industrial-grade security:
+- **Derivation**: PBKDF2 with 100,000 iterations.
+- **Encryption**: AES-GCM (256-bit).
+- **Decryption**: Keys exist only in volatile memory (`#sessionKey`) and are never stored in plaintext in `localStorage`.
 
-### `VibeInstance` Methods
-
-- `chat(payload: object, options: {stream: boolean})`: Returns `Promise<JSON>` or `AsyncGenerator<string>`.
-- `ask(prompt: string)`: Convenience method for quick text prompts.
-- `abort()`: Aborts the current active request for this instance.
-
-### `VibeBatch` Methods
-
-- `add(promptOrPayload: string|object)`: Enqueues a task.
-- `run(onProgress: function)`: Executes tasks. Callback returns `(done, total, lastResult)`.
+> **⚠️ DISCLAIMER**: While VibeAI uses robust encryption, it is a client-side SDK. The security of your keys depends on the physical security of the device and the integrity of the browser environment. Always encourage users to use the **"Enable Encryption"** toggle in the config modal.
 
 ---
 
-## 🛡 Security & Privacy
-
-- **Zero External Dependencies**: No tracking, no third-party scripts.
-- **Optional Encryption**: Uses **AES-GCM (Web Crypto API)** to encrypt API keys locally. Keys are never sent to any server except the AI provider's endpoint.
-- **Local Persistence**: All configurations are stored in `localStorage` under `vibe_ai_v3_config`.
-
----
+## 📄 Complete Implementation Example
 
-## 🧩 Comprehensive Integration Example
+This boilerplate combines VibeAI with Markdown rendering and a clean, bento-style layout.
 
-```javascript
-import { vibeAI } from 'https://unpkg.com/vibe-ai-c@4.0.0';
-
-async function main() {
-    // 1. Setup
-    await vibeAI.init({ setupBtnId: 'ai-config-btn' });
-    vibeAI.bindModelSelect('primary-selector');
-
-    const appInstance = vibeAI.getInstance('primary-selector');
-
-    // 2. High-level usage
-    try {
-        const result = await appInstance.ask("System check: Online.");
-        console.log("AI Status:", result);
-    } catch (err) {
-        console.error("Initialization failed:", err.message);
-        // Tips: Health Check in UI will show specific HTTP error codes
-    }
-
-    // 3. Automated Batching
-    document.getElementById('batch-process-btn').onclick = async () => {
-        const orchestrator = vibeAI.createBatch('primary-selector', { concurrency: 3 });
-
-        ['Task 1', 'Task 2', 'Task 3'].forEach(job => orchestrator.add(job));
-
-        await orchestrator.run((done, total) => {
-            document.getElementById('progress-bar').style.width = `${(done/total)*100}%`;
-        });
-    };
-}
-
-main();
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>VibeAI Production Demo</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.5.1/github-markdown.min.css">
+    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+    <style>
+        body { background: #f4f4f7; }
+        .markdown-body { background: transparent !important; font-size: 14px; }
+        .thought { border-left: 2px solid #e2e8f0; padding-left: 1rem; color: #64748b; font-style: italic; margin-bottom: 1rem; font-size: 13px; }
+    </style>
+</head>
+<body class="h-screen flex flex-col p-4">
+
+    <!-- Header -->
+    <header class="max-w-4xl w-full mx-auto flex justify-between items-center mb-4">
+        <h1 class="text-xl font-bold text-slate-800">VibeAI <span class="text-blue-500">v5.4</span></h1>
+        <div class="flex gap-2">
+            <select id="m-select" class="border rounded-lg px-3 py-1 text-sm bg-white outline-none"></select>
+            <button id="cfg-btn" class="bg-white border rounded-lg px-3 py-1 text-sm font-semibold shadow-sm hover:bg-slate-50">⚙️ Config</button>
+        </div>
+    </header>
+
+    <!-- Chat Area -->
+    <main id="chat" class="max-w-4xl w-full mx-auto flex-1 overflow-y-auto space-y-4 mb-4"></main>
+
+    <!-- Input Area -->
+    <footer class="max-w-4xl w-full mx-auto bg-white rounded-2xl shadow-lg p-2 flex gap-2">
+        <input id="prompt" type="text" placeholder="Ask anything..." class="flex-1 px-4 py-2 outline-none">
+        <button id="send" class="bg-blue-600 text-white px-6 py-2 rounded-xl font-bold">Send</button>
+    </footer>
+
+    <script type="module">
+        import { vibeAI } from 'https://unpkg.com/vibe-ai-c@5.4.0';
+
+        vibeAI.init({ setupBtnId: 'cfg-btn' });
+        vibeAI.bindSelect('m-select');
+
+        const chat = document.getElementById('chat');
+        const prompt = document.getElementById('prompt');
+        const sendBtn = document.getElementById('send');
+
+        async function handleSend() {
+            const val = prompt.value.trim();
+            if (!val) return;
+            prompt.value = '';
+
+            // Render User Message
+            chat.innerHTML += `<div class="bg-slate-200 self-end ml-auto px-4 py-2 rounded-2xl max-w-[80%] text-sm">${val}</div>`;
+
+            // Prep AI Bubble
+            const aiId = 'ai-' + Date.now();
+            chat.innerHTML += `
+                <div id="${aiId}" class="bg-white p-6 rounded-2xl shadow-sm border border-slate-100 max-w-[90%]">
+                    <div class="thought hidden"></div>
+                    <div class="markdown-body">...</div>
+                </div>`;
+            
+            const aiCard = document.getElementById(aiId);
+            const tDiv = aiCard.querySelector('.thought');
+            const cDiv = aiCard.querySelector('.markdown-body');
+            
+            let fullContent = "";
+            let fullThought = "";
+
+            try {
+                const inst = vibeAI.getInstance('m-select');
+                const stream = inst.streamChat({ messages: [{ role: 'user', content: val }] });
+
+                for await (const chunk of stream) {
+                    if (chunk.type === 'thought') {
+                        tDiv.classList.remove('hidden');
+                        fullThought += chunk.delta;
+                        tDiv.innerText = fullThought;
+                    }
+                    if (chunk.type === 'content') {
+                        fullContent += chunk.delta;
+                        cDiv.innerHTML = marked.parse(fullContent);
+                    }
+                }
+            } catch (e) {
+                cDiv.innerHTML = `<span class="text-red-500">❌ ${e.message}</span>`;
+            }
+            chat.scrollTop = chat.scrollHeight;
+        }
+
+        sendBtn.onclick = handleSend;
+        prompt.onkeydown = (e) => e.key === 'Enter' && handleSend();
+    </script>
+</body>
+</html>
 ```
 
-*Focus on UX. Protect the Input. Master the Stream.*
+## 💎 Key Decisions in v5.4
+
+- **Consolidated Gate**: The `unlockGate()` method replaces two separate modals, reducing DOM bloat by 40%.
+- **Lazy Status**: Provider health (`✅`/`❌`) is updated reactively during real chat attempts, saving unnecessary pings to the API.
+- **Diagnostic Hints**: Automatic detection of missing `/v1` in URLs or missing `sk-` in keys provides immediate developer feedback without manual debugging.
+- **Nuclear Reset**: Added a safety valve for forgotten passwords, allowing users to wipe encrypted keys and re-configure without losing app history.