ruflo 3.42.2 → 3.42.3

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

@@ -1,38 +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
+# 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

@@ -1,105 +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.
+# 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

@@ -1,84 +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.
+# 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

@@ -1,9 +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>
+# 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

@@ -1,57 +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
-```
+# 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
+```