ruflo 3.5.1 → 3.5.3

package/src/ruvocal/docs/adr/ADR-038-RUVOCAL-FORK.md

@@ -0,0 +1,286 @@
+# ADR-038: RuVocal — HF Chat UI Fork with Self-Contained RVF Document Store
+
+**Status:** Implemented
+**Date:** 2026-03-05
+**Updated:** 2026-03-05
+**Related:** ADR-029 (HF Chat UI Integration), ADR-035 (MCP Tool Groups), ADR-037 (Autopilot Mode)
+
+## Context
+
+The current `chat-ui-mcp` package uses the upstream HuggingFace Chat UI (`ghcr.io/huggingface/chat-ui-db:latest`) which bundles MongoDB for conversation storage. This creates several problems:
+
+1. **External dependency** — MongoDB requires a running server, connection management, and separate backup strategy.
+2. **Container bloat** — MongoDB adds ~500MB to the container image.
+3. **Upstream lock-in** — Using a pre-built Docker image means we can't modify the SvelteKit app.
+4. **Operational complexity** — Two databases (MongoDB + PostgreSQL) to maintain.
+
+We initially considered PostgreSQL (ruvector-postgres) as the replacement, but pivoted to a lighter approach: a self-contained RVF (RuVector Format) document store that persists to a single JSON file on disk. This eliminates all external database dependencies while preserving the full MongoDB Collection API.
+
+## Decision
+
+Fork HuggingFace Chat UI as **RuVocal** (`/workspaces/dev/packages/ruvocal`), replacing MongoDB with a pure TypeScript in-memory document store persisted to a single `.rvf.json` file.
+
+### Name
+
+**RuVocal** = **Ru**Vector + **Vocal** (voice/conversation). A conversational AI interface powered by ruvector.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        RuVocal Stack                             │
+│                                                                  │
+│  ┌──────────────────┐    ┌──────────────────┐                   │
+│  │   RuVocal UI     │    │   MCP Bridge     │                   │
+│  │   (SvelteKit 2)  │───▶│   (Node.js)      │                   │
+│  │                  │    │                  │                   │
+│  │  - Chat UI       │    │  - Tool proxy    │                   │
+│  │  - Autopilot     │    │  - Autopilot SSE │                   │
+│  │  - Task cards    │    │  - System prompt │                   │
+│  │  - Auth (OIDC)   │    │  - 201 tools     │                   │
+│  └────────┬─────────┘    └──────────────────┘                   │
+│           │                                                      │
+│           ▼                                                      │
+│  ┌──────────────────────────────────────────┐                   │
+│  │         RVF Document Store               │                   │
+│  │         (In-Memory + Disk Persist)       │                   │
+│  │                                           │                   │
+│  │  File: db/ruvocal.rvf.json               │                   │
+│  │                                           │                   │
+│  │  Collections (16):                        │                   │
+│  │  - conversations    (chat sessions)       │                   │
+│  │  - users            (auth/profiles)       │                   │
+│  │  - sessions         (auth sessions)       │                   │
+│  │  - settings         (user preferences)    │                   │
+│  │  - assistants       (custom assistants)   │                   │
+│  │  - reports          (abuse reports)       │                   │
+│  │  - messageEvents    (feedback/votes)      │                   │
+│  │  - semaphores       (rate limiting)       │                   │
+│  │  - tokens           (token cache)         │                   │
+│  │  - config           (runtime config)      │                   │
+│  │  - migrationResults (migration tracking)  │                   │
+│  │  - tools            (tool registry)       │                   │
+│  │  - _files           (GridFS replacement)  │                   │
+│  │  + per-tenant namespaced collections      │                   │
+│  │                                           │                   │
+│  │  Features:                                │                   │
+│  │  - MongoDB-compatible Collection API      │                   │
+│  │  - Multi-tenant data isolation            │                   │
+│  │  - Debounced auto-save (500ms)            │                   │
+│  │  - Zero external dependencies             │                   │
+│  └───────────────────────────────────────────┘                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## RVF Document Store (`rvf.ts`)
+
+### Storage Format
+
+```json
+{
+  "rvf_version": "2.0",
+  "format": "rvf-database",
+  "collections": {
+    "conversations": { "id1": {...}, "id2": {...} },
+    "users": { ... },
+    ...
+  },
+  "tenants": {
+    "tenant-a": { "conversations": {...}, ... },
+    "tenant-b": { "conversations": {...}, ... }
+  },
+  "metadata": {
+    "created_at": "2026-03-05T...",
+    "updated_at": "2026-03-05T...",
+    "doc_count": 1234,
+    "multi_tenant": true
+  }
+}
+```
+
+### MongoDB-Compatible API
+
+The `RvfCollection<T>` class implements the full MongoDB Collection interface used by all 56 importing files in HF Chat UI:
+
+```typescript
+class RvfCollection<T> {
+    // CRUD
+    findOne(filter, options?): Promise<T | null>;
+    find(filter, options?): RvfCursor<T>;
+    insertOne(doc): Promise<{ insertedId: ObjectId }>;
+    insertMany(docs): Promise<{ insertedIds: ObjectId[] }>;
+    updateOne(filter, update, options?): Promise<UpdateResult>;
+    updateMany(filter, update): Promise<UpdateResult>;
+    deleteOne(filter): Promise<DeleteResult>;
+    deleteMany(filter): Promise<DeleteResult>;
+    countDocuments(filter?): Promise<number>;
+    distinct(field, filter?): Promise<unknown[]>;
+    bulkWrite(ops): Promise<BulkWriteResult>;
+    findOneAndUpdate(filter, update, options?): Promise<{ value: T | null }>;
+    findOneAndDelete(filter): Promise<{ value: T | null }>;
+
+    // Aggregation
+    aggregate(pipeline, options?): { next(): Promise<T | null>; toArray(): Promise<T[]> };
+
+    // Indexes (no-ops — in-memory store doesn't need them)
+    createIndex(spec, options?): Promise<void>;
+    listIndexes(): { toArray(): Promise<IndexInfo[]> };
+
+    // Multi-tenant
+    forTenant(tenantId: string): RvfCollection<T>;
+}
+```
+
+### Query Operators Implemented
+
+| Operator | Description |
+|----------|-------------|
+| `$or` | Logical OR |
+| `$and` | Logical AND |
+| `$not` | Logical NOT |
+| `$exists` | Field existence |
+| `$gt`, `$gte`, `$lt`, `$lte` | Comparison |
+| `$ne` | Not equal |
+| `$in`, `$nin` | Array membership |
+| `$regex`, `$options` | Regular expression |
+
+### Update Operators Implemented
+
+| Operator | Description |
+|----------|-------------|
+| `$set` | Set field value |
+| `$unset` | Remove field |
+| `$inc` | Increment numeric field |
+| `$push` | Push to array (with `$each`) |
+| `$pull` | Remove from array |
+| `$addToSet` | Add unique to array |
+| `$setOnInsert` | Set on upsert only |
+
+### Cursor API
+
+```typescript
+class RvfCursor<T> {
+    sort(spec): this;
+    limit(n): this;
+    skip(n): this;
+    project<U>(spec): RvfCursor<U>;
+    batchSize(n): this;
+    map<U>(fn): RvfCursor<U>;
+    toArray(): Promise<T[]>;
+    hasNext(): Promise<boolean>;
+    next(): Promise<T | null>;
+    tryNext(): Promise<T | null>;
+    [Symbol.asyncIterator](): AsyncGenerator<T>;
+}
+```
+
+### Aggregation Pipeline Stages
+
+| Stage | Description |
+|-------|-------------|
+| `$match` | Filter documents |
+| `$sort` | Sort results |
+| `$limit` | Limit result count |
+| `$skip` | Skip results |
+| `$project` | Include/exclude fields |
+| `$group` | Group with `$sum`, `$count` |
+
+## Multi-Tenant Support
+
+Tenant isolation is built into the store at the collection level:
+
+```typescript
+// Global collection (default)
+const conversations = new RvfCollection<Conversation>("conversations");
+
+// Tenant-scoped view — fully isolated data
+const tenantConvs = conversations.forTenant("tenant-abc");
+await tenantConvs.insertOne({ title: "Hello" });
+
+// Won't find tenant data
+await conversations.findOne({ title: "Hello" }); // null
+
+// Stats
+listTenants();      // ["tenant-abc"]
+getTenantStats();   // { "tenant-abc": { collections: 1, documents: 1 } }
+```
+
+Tenant data is persisted separately in the RVF file under the `tenants` key.
+
+## Performance Benchmarks (47 tests, all passing)
+
+| Operation | Dataset | Time | Throughput |
+|-----------|---------|------|------------|
+| Insert | 10,000 docs | 63ms | ~159k ops/s |
+| Find (range) | 10,000 docs | 5ms | 1,000 results |
+| UpdateMany | 10,000 docs | 15ms | 5,000 matched |
+| Aggregate | 10,000 docs | 28ms | match+sort+limit |
+| Concurrent (5 ops) | 1,000 docs | 1.9ms | mixed read/write |
+| Multi-tenant insert | 10×1,000 docs | 25ms | 10 tenants |
+| Single tenant query | 1,000 docs | 0.5ms | 499 results |
+
+## Test Coverage
+
+47 tests across 9 test suites:
+
+- **CRUD** (13 tests): insertOne/Many, updateOne/Many, deleteOne/Many, countDocuments, distinct, findOneAndUpdate/Delete, bulkWrite
+- **Query Operators** (7 tests): $gt/$gte/$lt/$lte, $ne, $in/$nin, $exists, $or/$and, $regex, $not
+- **Update Operators** (6 tests): $inc, $push, $push+$each, $pull, $addToSet, $unset
+- **Cursor** (4 tests): sort/limit/skip, async iterator, tryNext/hasNext/next, map
+- **Aggregation** (3 tests): $match+$sort+$limit, aggregate().next(), $group+$sum
+- **GridFS** (2 tests): upload+download, delete
+- **Multi-tenant** (2 tests): isolation, listTenants+stats
+- **Persistence** (1 test): flush to disk and reload
+- **ObjectId** (3 tests): equals, createFromHexString, toJSON
+- **Benchmarks** (6 tests): insert, find, update, aggregate, concurrent, multi-tenant
+
+## Files Modified
+
+| File | Change |
+|------|--------|
+| `src/lib/server/database/rvf.ts` | NEW — RVF document store (850+ lines) |
+| `src/lib/server/database.ts` | REWRITTEN — Uses RvfCollection instead of MongoDB |
+| `src/lib/server/config.ts` | MODIFIED — RvfCollection types |
+| `src/lib/migrations/migrations.ts` | REWRITTEN — No MongoDB sessions/transactions |
+| `scripts/setups/vitest-setup-server.ts` | REWRITTEN — No MongoMemoryServer |
+| `src/lib/server/database/__tests__/rvf.spec.ts` | NEW — 47 tests + benchmarks |
+
+## Environment Variables
+
+```bash
+# RVF store path (defaults to db/ruvocal.rvf.json)
+RVF_DB_PATH=/data/ruvocal
+
+# Empty string = in-memory only (for tests)
+RVF_DB_PATH=
+
+# Everything else stays the same
+PUBLIC_APP_NAME=RuVocal
+PUBLIC_ORIGIN=https://chat.example.com
+OPENAI_BASE_URL=https://openrouter.ai/api/v1
+```
+
+## Benefits
+
+| Aspect | MongoDB (upstream) | RVF Store (RuVocal) |
+|--------|-------------------|---------------------|
+| **Dependencies** | MongoDB server required | Zero — pure TypeScript |
+| **Container size** | +500MB for MongoDB | 0 extra |
+| **Persistence** | Network database | Single JSON file |
+| **Startup time** | Seconds (connection) | Instant |
+| **Multi-tenant** | Not built-in | Native tenant isolation |
+| **Backup** | mongodump | cp ruvocal.rvf.json |
+| **UI customization** | Cannot modify upstream | Full SvelteKit source |
+| **Test speed** | MongoMemoryServer (~2s) | In-memory (~300ms) |
+
+## Risks
+
+1. **In-memory limitation** — All data lives in RAM; unsuitable for datasets >100MB
+2. **Single-writer** — No concurrent process writes (single Node process assumed)
+3. **Upstream sync** — Forking means manual merge of upstream HF Chat UI updates
+
+## Mitigation
+
+1. For large deployments, future upgrade path to ruvector-postgres (PostgresAdapter already exists at `postgres.ts`)
+2. The debounced save + flush-on-exit pattern prevents data loss; WAL logging can be added if needed
+3. Keep fork minimal — only database layer changed, UI components untouched

package/src/ruvocal/docs/source/_toctree.yml

@@ -0,0 +1,30 @@
+- local: index
+  title: Chat UI
+- title: Installation
+  sections:
+    - local: installation/local
+      title: Local
+    - local: installation/docker
+      title: Docker
+    - local: installation/helm
+      title: Helm
+- title: Configuration
+  sections:
+    - local: configuration/overview
+      title: Overview
+    - local: configuration/theming
+      title: Theming
+    - local: configuration/open-id
+      title: OpenID
+    - local: configuration/mcp-tools
+      title: MCP Tools
+    - local: configuration/llm-router
+      title: LLM Router
+    - local: configuration/metrics
+      title: Metrics
+    - local: configuration/common-issues
+      title: Common Issues
+- title: Developing
+  sections:
+    - local: developing/architecture
+      title: Architecture

package/src/ruvocal/docs/source/configuration/common-issues.md

@@ -0,0 +1,38 @@
+# Common Issues
+
+## 403: You don't have access to this conversation
+
+This usually happens when running Chat UI over HTTP without proper cookie configuration.
+
+**Recommended:** Set up a reverse proxy (NGINX, Caddy) to handle HTTPS.
+
+**Alternative:** If you must run over HTTP, configure cookies:
+
+```ini
+COOKIE_SECURE=false
+COOKIE_SAMESITE=lax
+```
+
+Also ensure `PUBLIC_ORIGIN` matches your actual URL:
+
+```ini
+PUBLIC_ORIGIN=http://localhost:5173
+```
+
+## Models not loading
+
+If models aren't appearing in the UI:
+
+1. Verify `OPENAI_BASE_URL` is correct and accessible
+2. Check that `OPENAI_API_KEY` is valid
+3. Ensure the endpoint returns models at `${OPENAI_BASE_URL}/models`
+
+## Database connection errors
+
+For development, you can skip MongoDB entirely - Chat UI will use an embedded database.
+
+For production, verify:
+
+- `MONGODB_URL` is a valid connection string
+- Your IP is whitelisted (for MongoDB Atlas)
+- The database user has read/write permissions

package/src/ruvocal/docs/source/configuration/llm-router.md

@@ -0,0 +1,105 @@
+# LLM Router
+
+Chat UI includes an intelligent routing system that automatically selects the best model for each request. When enabled, users see a virtual "Omni" model that routes to specialized models based on the conversation context.
+
+The router uses [katanemo/Arch-Router-1.5B](https://huggingface.co/katanemo/Arch-Router-1.5B) for route selection.
+
+## Configuration
+
+### Basic Setup
+
+```ini
+# Arch router endpoint (OpenAI-compatible)
+LLM_ROUTER_ARCH_BASE_URL=https://router.huggingface.co/v1
+LLM_ROUTER_ARCH_MODEL=katanemo/Arch-Router-1.5B
+
+# Path to your routes policy JSON
+LLM_ROUTER_ROUTES_PATH=./config/routes.json
+```
+
+### Routes Policy
+
+Create a JSON file defining your routes. Each route specifies:
+
+```json
+[
+	{
+		"name": "coding",
+		"description": "Programming, debugging, code review",
+		"primary_model": "Qwen/Qwen3-Coder-480B-A35B-Instruct",
+		"fallback_models": ["meta-llama/Llama-3.3-70B-Instruct"]
+	},
+	{
+		"name": "casual_conversation",
+		"description": "General chat, questions, explanations",
+		"primary_model": "meta-llama/Llama-3.3-70B-Instruct"
+	}
+]
+```
+
+### Fallback Behavior
+
+```ini
+# Route to use when Arch returns "other"
+LLM_ROUTER_OTHER_ROUTE=casual_conversation
+
+# Model to use if Arch selection fails entirely
+LLM_ROUTER_FALLBACK_MODEL=meta-llama/Llama-3.3-70B-Instruct
+
+# Selection timeout (milliseconds)
+LLM_ROUTER_ARCH_TIMEOUT_MS=10000
+```
+
+## Multimodal Routing
+
+When a user sends an image, the router can bypass Arch and route directly to a vision model:
+
+```ini
+LLM_ROUTER_ENABLE_MULTIMODAL=true
+LLM_ROUTER_MULTIMODAL_MODEL=meta-llama/Llama-3.2-90B-Vision-Instruct
+```
+
+## Tools Routing
+
+When a user has MCP servers enabled, the router can automatically select a tools-capable model:
+
+```ini
+LLM_ROUTER_ENABLE_TOOLS=true
+LLM_ROUTER_TOOLS_MODEL=meta-llama/Llama-3.3-70B-Instruct
+```
+
+## UI Customization
+
+Customize how the router appears in the model selector:
+
+```ini
+PUBLIC_LLM_ROUTER_ALIAS_ID=omni
+PUBLIC_LLM_ROUTER_DISPLAY_NAME=Omni
+PUBLIC_LLM_ROUTER_LOGO_URL=https://example.com/logo.png
+```
+
+## How It Works
+
+When a user selects Omni:
+
+1. Chat UI sends the conversation context to the Arch router
+2. Arch analyzes the content and returns a route name
+3. Chat UI maps the route to the corresponding model
+4. The request streams from the selected model
+5. On errors, fallback models are tried in order
+
+The route selection is displayed in the UI so users can see which model was chosen.
+
+## Message Length Limits
+
+To optimize router performance, message content is trimmed before sending to Arch:
+
+```ini
+# Max characters for assistant messages (default: 500)
+LLM_ROUTER_MAX_ASSISTANT_LENGTH=500
+
+# Max characters for previous user messages (default: 400)
+LLM_ROUTER_MAX_PREV_USER_LENGTH=400
+```
+
+The latest user message is never trimmed.

package/src/ruvocal/docs/source/configuration/mcp-tools.md

@@ -0,0 +1,84 @@
+# MCP Tools
+
+Chat UI supports tool calling via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). MCP servers expose tools that models can invoke during conversations.
+
+## Server Types
+
+Chat UI supports two types of MCP servers:
+
+### Base Servers (Admin-configured)
+
+Base servers are configured by the administrator via environment variables. They appear for all users and can be enabled/disabled per-user but not removed.
+
+```ini
+MCP_SERVERS=[
+  {"name": "Web Search (Exa)", "url": "https://mcp.exa.ai/mcp"},
+  {"name": "Hugging Face", "url": "https://hf.co/mcp"}
+]
+```
+
+Each server entry requires:
+
+- `name` - Display name shown in the UI
+- `url` - MCP server endpoint URL
+- `headers` (optional) - Custom headers for authentication
+
+### User Servers (Added from UI)
+
+Users can add their own MCP servers directly from the UI:
+
+1. Open the chat input and click the **+** button (or go to Settings)
+2. Select **MCP Servers**
+3. Click **Add Server**
+4. Enter the server name and URL
+5. Run **Health Check** to verify connectivity
+
+User-added servers are stored in the browser and can be removed at any time. They work alongside base servers.
+
+## User Token Forwarding
+
+When users are logged in via Hugging Face, you can forward their access token to MCP servers:
+
+```ini
+MCP_FORWARD_HF_USER_TOKEN=true
+```
+
+This allows MCP servers to access user-specific resources on their behalf.
+
+## Using Tools
+
+1. Enable the servers you want to use from the MCP Servers panel
+2. Start chatting - models will automatically use tools when appropriate
+
+### Model Requirements
+
+Not all models support tool calling. To enable tools for a specific model, add it to your `MODELS` override:
+
+```ini
+MODELS=`[
+  {
+    "id": "meta-llama/Llama-3.3-70B-Instruct",
+    "supportsTools": true
+  }
+]`
+```
+
+## Tool Execution Flow
+
+When a model decides to use a tool:
+
+1. The model generates a tool call with parameters
+2. Chat UI executes the call against the MCP server
+3. Results are displayed in the chat as a collapsible "tool" block
+4. Results are fed back to the model for follow-up responses
+
+## Integration with LLM Router
+
+When using the [LLM Router](./llm-router), you can configure automatic routing to a tools-capable model:
+
+```ini
+LLM_ROUTER_ENABLE_TOOLS=true
+LLM_ROUTER_TOOLS_MODEL=meta-llama/Llama-3.3-70B-Instruct
+```
+
+When a user has MCP servers enabled and selects the Omni model, the router will automatically use the specified tools model.

package/src/ruvocal/docs/source/configuration/metrics.md

@@ -0,0 +1,9 @@
+# Metrics
+
+The server can expose prometheus metrics on port `5565` but is off by default. You may enable the metrics server with `METRICS_ENABLED=true` and change the port with `METRICS_PORT=1234`.
+
+<Tip>
+
+In development with `npm run dev`, the metrics server does not shutdown gracefully due to Sveltekit not providing hooks for restart. It's recommended to disable the metrics server in this case.
+
+</Tip>

package/src/ruvocal/docs/source/configuration/open-id.md

@@ -0,0 +1,57 @@
+# OpenID
+
+By default, users are attributed a unique ID based on their browser session. To authenticate users with OpenID Connect, configure the following:
+
+```ini
+OPENID_CLIENT_ID=your_client_id
+OPENID_CLIENT_SECRET=your_client_secret
+OPENID_SCOPES="openid profile"
+```
+
+Use the provider URL for standard OpenID Connect discovery:
+
+```ini
+OPENID_PROVIDER_URL=https://your-provider.com
+```
+
+Advanced: you can also provide a client metadata document via `OPENID_CONFIG`. This value must be a JSON/JSON5 object (for example, a CIMD document) and is parsed server‑side to populate OpenID settings.
+
+**Redirect URI:** `https://your-domain.com/login/callback`
+
+## Access Control
+
+Restrict access to specific users:
+
+```ini
+# Allow only specific email addresses
+ALLOWED_USER_EMAILS=["user@example.com", "admin@example.com"]
+
+# Allow all users from specific domains
+ALLOWED_USER_DOMAINS=["example.com", "company.org"]
+```
+
+## Hugging Face Login
+
+For Hugging Face authentication, you can use automatic client registration:
+
+```ini
+OPENID_CLIENT_ID=__CIMD__
+```
+
+This creates an OAuth app automatically when deployed. See the [CIMD spec](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) for details.
+
+## User Token Forwarding
+
+When users log in via Hugging Face, you can forward their token for inference:
+
+```ini
+USE_USER_TOKEN=true
+```
+
+## Auto-Login
+
+Force authentication on all routes:
+
+```ini
+AUTOMATIC_LOGIN=true
+```