fanluc 2.0.0 → 2.4.0

package/docs/fanluc_ui.md

@@ -1,42 +1,122 @@
-# FANLUC Interface — UI Description
-
-## Overview
-The screenshot shows a minimalist, wireframe-style chat application named **FANLUC**. The design uses a black-and-white aesthetic with a serif typeface, bracketed labels (e.g., `[BUTTON]`), and simple bordered boxes instead of modern rounded UI components — giving it a retro, text-terminal-like appearance.
-
-## Layout Breakdown
-
-### 1. Top Navigation Bar
-- **Left side:**
-  - `[HISTORY]` — a bordered button, likely opens a list of past conversations.
-  - **FANLUC** — the application's logo/name, displayed in bold serif font next to the History button.
-- **Right side:**
-  - `[SETUP_GUIDE]` — a bordered button, presumably links to onboarding or setup instructions.
-  - `[SETTINGS]` — a bordered button for app configuration.
-  - `[DK]` — a bordered button.
-- A thin horizontal black line separates the top bar from the main content area.
-
-### 2. Main Content Area (Center)
-- Large, centered greeting text: **"Hey there"**, displayed in a large serif font.
-- The rest of this area is empty white space, suggesting this is a fresh/new conversation screen with no messages yet.
-
-### 3. Bottom Input Section
-Separated from the main content by a thick horizontal black line.
-
-- **Message input box:**
-  - A large rectangular text field spanning most of the width.
-  - Placeholder text: *"Write a message..."*
-  - A small resize handle icon in the bottom-right corner of the box.
-
-- **Below the input box:**
-  - `+ [ATTACH_FILE]` — a bordered button on the left with a "+" icon, allowing file attachments.
-  - Helper text next to it: *"(Text <= 15KB | Image <= 15MB)"* — indicating file size limits for text and image attachments.
-  - `[SEND]` — a gray/disabled-looking bordered button on the far right, used to send the message (appears inactive until text is entered).
-
-## Design Style Notes
-- Monochrome (black, white, gray) color scheme.
-- Serif typography throughout (buttons and headings), giving a formal/literary feel contrasted with the bracket-style button labels typical of minimalist or developer-oriented UIs.
-- Sharp-cornered rectangular borders (no rounded corners) on all interactive elements.
-- Generous whitespace in the main chat area, keeping focus on the message input at the bottom.
+# FANLUC Interface — Detailed UI Description
+
+> Read this to know exactly what the human user SEES on screen while chatting with you, and what happens on screen when YOU run a command. You cannot see the UI yourself, so rely on the exact labels below when guiding the user.
+
+## 0. TL;DR
+- FANLUC is a retro, terminal-like chat web app. Black & white, sharp rectangular borders, ALL-CAPS bracketed labels like `[SEND]`, `[SETTINGS]`.
+- Text is drawn in mono fonts, each character randomly picked from Courier Prime / VT323 / Share Tech Mono / Inconsolata (so text looks "glitchy-mixed"). Serif Lora is only used if the user enables it in Settings.
+- Light mode = white background, black text. Dark mode = inverted. Toggle button: `[DK]` (switches to dark) / `[LT]` (switches to light).
+- The user NEVER sees raw command syntax (`search(...)`, `fetch(...)`, `run_cmd{...}` ...). They only see a status line, a collapsible `TOOL LOGS` box, and result cards. Tool results come back to YOU as a hidden next message.
+- Exceptions to the "sharp black/white" style: Weather card (rounded, colored illustration), Translation / Chart / Pie cards (dark zinc, rounded).
+
+## 1. Screen layout (default)
+```
++--------------------------------------------------------------+
+| [HISTORY]  FANLUC        [FILES] [SETUP_GUIDE] [SETTINGS] [DK]|  <- header, 2px bottom border, sticky
++--------------------------------------------------------------+
+|                                                              |
+|                       Hi!  (big serif greeting)              |  <- empty chat only
+|                                                              |
++==============================================================+  <- 2px top border of input area
+| +----------------------------------------------------------+ |
+| | Type your message...                                     | |  <- textarea, 2px border
+| +----------------------------------------------------------+ |
+| + [ATTACH_FILE] (All files <= 2MB | Image <= 15MB)  [CLEAR][SEND] |
++--------------------------------------------------------------+
+```
+- Content is centered, max width ~ 6xl. Header is sticky at top, input area sticky at bottom.
+- Optional black bar `[PERF_TELEMETRY]` (dev HUD) can appear right under the header.
+
+## 2. Header
+- Left: `[HISTORY]` (becomes `[HIDE_HIST]` while sidebar is open) toggles the chat-session sidebar. Next to it the logo text **FANLUC** (uppercase, bold, letter-spaced).
+- Right (desktop): `[FILES]` or `[FILES (n)]` (opens the WORKSPACE FILES panel, n = files count), `[SETUP_GUIDE]`, `[SETTINGS]`, `[DK]`/`[LT]`.
+- Mobile: header wraps into two rows; the theme button sits on the top row, the other buttons share the second row equally.
+- All buttons: 1px border, uppercase bold, hover = colors invert.
+
+## 3. Empty state
+Big centered greeting in Lora serif (3xl-6xl), no messages. Chosen randomly per chat: `Hi!`, `Sup Ya?`, plus time-based (`Morning!` 5-12h, `Afternoon!` 12-18h, `Evening!` 18-23h, `Is something up tonight?` 23-5h) and seasonal (Halloween question, `Merry Christmas!`, `Happy New Year!`, `Are you going anywhere this summer?` in Jun-Aug).
+Special case: if the user's first message is just "hi" or "hello", the app answers locally ("Hi! How can I help you today?") without calling you.
+
+## 4. Input area
+- Textarea, placeholder is one of "Type your message...", "Type a message...", "Write your message...", "Write a message...". Auto-grows up to 140px. Enter = send, Shift+Enter = new line. Disabled while you are answering.
+- `+ [ATTACH_FILE]`: one file at a time. Any file <= 2MB, images <= 15MB (hint text hidden on small screens). Text files are read as text, binary files as base64, images shown to you as vision input. Errors appear in a dashed box: `[SIZE_LIMIT_EXCEEDED] ...` with `[CLEAR]`.
+- After attaching: preview row with 40px thumbnail (or `[TXT]` tile), file name, `TYPE | size (Limit: ...)`, and `[REMOVE_FILE]`.
+- `[CLEAR]` appears when there is text/attachment. `[SEND]` is a filled black button (white in dark mode), 40% opacity when there is nothing to send. While you are generating it turns into `[STOP]`.
+- `[↓ BOTTOM]` floating button appears above the input when the user scrolled up.
+
+## 5. Messages
+- **User bubble:** inverted colors (black bg / white text), pushed right. Header row: `[USER]`, time HH:MM:SS, `[EDIT]` (edit + `[RESEND]`/`[CANCEL]`), `[COPY]`. Attachments show `[ATTACHED_FILE: name]` with image preview or first 500 chars of text + `[CONTINUED]`. Messages > 6 lines are folded: `[SHOW +N LINES]` / `[HIDE]`.
+- **Assistant bubble:** outlined (white bg / black border), pushed left. Header row: `[MODEL NAME]` (from Settings), time, `[BRANCH]` (fork chat from here), `[COPY]`.
+- Inside an assistant bubble, top to bottom:
+  1. Thinking block (if the model uses think tags): `Thinking...` while streaming, then collapsed `Thought for Ns`; expands into `Step 1 · 3s`, `Step 2 ...`.
+  2. Text segments (Markdown: uppercase h1/h2/h3, tables with borders, blockquote with left bar, code blocks) interleaved with `TOOL LOGS` boxes, in the order you did things.
+  3. Cards (map, step guide, tab, chart, pie, translation, weather, images).
+  4. `[CREATED_OR_MODIFIED_FILES (n)]` file cards.
+  5. `[SOURCES: n]` button (URLs you fetched).
+  6. While streaming: a small spinning MSH logo GIF (black version in light mode, inverted in dark mode).
+- Code blocks: black box with `[LANG]` label and `[COPY]`; > 10 lines are collapsed with `[SHOW: N LINES]`/`[HIDE]`.
+- API error: dashed-border inverted box `[API_CONNECTION_ERROR]` + details + `[RETRY]` and `[VIEW_SETUP_GUIDE]`.
+
+## 6. What the user sees when YOU run a command
+While a command runs, a plain status line appears under the last message (no spinner icon). After the turn, a collapsed `TOOL LOGS` box (click to expand) lists one row per command with an icon. Consecutive commands without text between them are merged in one box.
+
+| Your command | Status line / TOOL LOGS row | What the user sees as result | What you receive back |
+|---|---|---|---|
+| `search("q")(n)` | `Searching the web: "q"...` | Nothing but the log row | `N results:` then lines `url: snippet` |
+| `fetch(url)(len)` | `Fetching URL ...` | `[SOURCES: n]` button under the message (favicons; expands to domain + link + `[COPY]`) | `fetched url: ...`, `title: ...`, `text: ...` (cut to `len`, max 10000) |
+| `image_search(query, count)` | `Searching images: "q"...` | Card `[IMAGE_SEARCH] "q" — N images`: black header bar, 2-3 column square thumbnails (max 6), click opens the image | one-line summary only (no URLs) |
+| `show_weather(location)` | `Fetching weather for X...` | Weather card (see 7). `auto` triggers a browser geolocation permission popup | `[WEATHER RESULT: City - 30°C, Sunny]` |
+| `translate(text,to)` | `Translating text: "..."...` | Translation card (see 7) | `translated "..." (from -> to): "..."` |
+| `show_map([...])` | `Rendering map: ...` | Map card (see 7) | confirmation |
+| `run_cmd{...}` | `Running: <first 45 chars>` | Files it creates appear as file cards and in `[FILES]` | `$ cmd` + real stdout/stderr |
+| `write_file / edit_file / read_file / delete_file / move_file / glob / grep / git_diff / git_checkout` | `Creating file x...`, `Editing file x...`, `Reading file x...`, `Deleting...`, `Moving a -> b...`, `Listing directory...`, `Searching inside files...`, `Checking git diff...`, `Reverting file...` | File cards for created/modified files | result text |
+| `read_docs(name)` | `Reading doc name...` | log row only | doc content |
+| `list_skills` / `load_skills(id)` | `Listing available skills...` / `Loading skill(s): id...` | log row only | skill text |
+| `list_history / see_history / list_chat_keywords` | `Reading chat history (part n)...` etc. | log row only | history text |
+| `mcp_call(server, tool, args)` | `Calling MCP server.tool...` | log row only | tool result |
+| `ask("Q")-sam(opt1, opt2)` | — | Section `[QUICK RESPONSE REQUIRED]`: one question at a time `Q1/2: ...` with option buttons; the picked answer is sent automatically as the user's next message | the answer text |
+Failures show status `[FETCH_URL_FAILED]` or `[COMMAND_ERROR]` briefly; you get an error string.
+
+## 7. Native cards (write them directly in chat, do not repeat their content as plain text)
+- **Map card** (`show_map`): full-width bordered box, gray title bar (title or "Map Card", `1/N` counter), 360-400px tall. With > 1 place: left list "Places (N)" with numbered squares, right embedded Google Map; click a place to switch.
+- **Step guide** (`|Step-by-step guide|` block, 3-20 steps): one step at a time, centered text, footer `<   1/5   >`.
+- **Tab card** (`|Tab display card|`, 2-8 tabs): tab strip on top, content below (supports `(checkbox)` items), footer `TAB 1/3` plus mode buttons: `[COPY]`, or `[PREV]`/`[NEXT]`/`[DONE]`→`[COMPLETED]` (need_complete), or `<` `>` (none).
+- **Chart card** (`chart`, line/bar/scatter): dark zinc rounded card, title, top-right toggle pill (chart icon / table icon), SVG chart with hover tooltip and legend.
+- **Pie card** (`pie_chart`): same dark style, donut/pie, legend with percentages, table toggle (Category / Value / Share %).
+- **Translation card**: dark rounded card, optional title, two columns `FROM` code | `TO` code (e.g. `EN` | `VI`), each with speaker (text-to-speech) and copy icons; stacked vertically on mobile.
+- **Weather card**: 300px wide white rounded card. Top 148px = animated colored illustration by condition (sunny, cloudy, windy, fog, snow, rain/storm) with big temperature `32°`, condition and location in white text; bottom strip shows time (left) and date (right).
+- **Image search card**: see table above.
+- **File card**: bordered row with icon (globe=HTML, file=doc, image=SVG, code), file name, category like `Code · HTML`, `DOWNLOAD` button; `DOWNLOAD ALL` when several. Click opens the file in the right panel.
+- `/mcps` shows an MCP status panel (server list with `[ON]`/`[OFF]`, `[DELETE]`, `[EDIT]`, `[RELOAD]`, `[+ ADD SERVER]`, SearXNG URL field with `[SAVE]`).
+
+## 8. Files & artifact panel
+- Long code/documents should be saved with `run_cmd` (heredoc); the user then opens them through the file card or the `[FILES]` button.
+- Clicking a file card splits the screen: chat on the left (half width, input moves into this column), file viewer on the right. On mobile the viewer replaces the chat.
+- Viewer toolbar: `PREVIEW` / `CODE` tabs (preview for HTML in a sandboxed iframe, Markdown, SVG, Mermaid, PDF; other types show code only), reload (HTML), `COPY`, download icon, expand/restore (desktop), close (X).
+- `[FILES]` panel `WORKSPACE FILES (n)`: `+ UPLOAD` (max 2MB), `DOWNLOAD ALL`, close; list of file rows with delete; empty text `NO FILES AVAILABLE`.
+
+## 9. Sidebar, modals, extras
+- **Sidebar** (`[HISTORY]`): drawer from the left (288-320px) over a dimmed backdrop. Title `[CHAT_SESSIONS]` + `[CLOSE]`; `+ [NEW_CHAT] [n/16]` (max 16 chats); `[EXPORT_TXT]`, `[CLEAR_ALL]`; session rows (selected = inverted; double-click or `[EDIT]` to rename; `[X]` delete, asks confirmation); footer `[VOICE_CHAT_BETA]`.
+- **Confirm modal**: centered box, 2px border, title, message, `[CANCEL]` and filled `[CONFIRM]`.
+- **[SETTINGS]** modal, left tab list: `[API_CONFIG]` (API URL with presets OPENAI / GEMINI / OPENROUTER / GROQ / OLLAMA, API key, model name, system prompt, temperature, top P, top K, repeat penalty, reasoning effort, max tokens, Lora serif switch, think/strip tags), `[CHAT_TEMPLATE]`, `[EFFORT]` (Fast / Cautious / Thorough / Meticulous), `[SKILLS]` (create/edit/`[ON]`/`[OFF]`), `[MEM]` (master `[ON]`/`[OFF]`, your own keyword-tagged memories, the AI's own write_mem memories, and "generate memory from chat history"), `[AGENT]` (master `[ON]`/`[OFF]`, create/edit sub-agents with their own API config + effort + tag text/image, test-prompt button, export/clear each agent's own workspace), `[MCP]`, `[DEV_MODE]`. Bottom `[SAVE_SETTINGS]`. OLLAMA fills `http://localhost:11434/v1/chat/completions`; the API key field can stay blank, and the model name should be a locally-pulled Ollama model (e.g. `llama3.1`).
+- **[DEV_MODE]**: toggles `[HUD: ON/OFF]`, `[RAW: ON/OFF]` (shows raw payloads), `[ROLE_SIM: ON/OFF]`, `[CARDS: ON/OFF]` (gallery of all cards), plus a `/help` tool manual.
+- **[SETUP_GUIDE]** modal: "PREREQUISITES & SETUP GUIDE", 4 steps: ngrok authtoken → Google Colab T4 GPU → run server code (llama-cpp-python + ngrok) → paste API Base URL (`https://xxxx.ngrok-free.dev/v1`) and API key into Settings.
+- **Voice chat** (`[VOICE_CHAT_BETA]`): fullscreen. Left: `YOU` box (live transcript), `AI` box (`Thinking...`/`Speaking...`), language toggles (multi-select, then `[ACTIVE] <lang>`). Right: `[AUDIO_LEVEL]` 7 vertical bars and `[STATUS: ...]`. Exit `[X]` top-right. Needs microphone permission.
+- **Slash commands typed by the user**: `/help` (tool manual), `/mcps`, `/compact [hint]` (summarizes the conversation; status `[COMPACTING_CONTEXT: N messages]`).
+- **`[PERF_TELEMETRY]` bar** (black): TOKENS, SPEED tok/s, TOOLCALLS, SYS_PROMPT, `[DEV_CONSOLE]`, close.
+
+## 10. Tips for you (the AI)
+- Refer to buttons by their exact bracket labels, e.g. "open [SETTINGS] → [API_CONFIG]".
+- Never tell the user to type commands; just run them. Don't print command syntax.
+- Cards already show their data: after a card, add only 1-2 sentences of insight.
+- For long code/documents use `run_cmd` and tell the user to press `[FILES]` or the file card.
+- If the API connection fails, point to `[SETUP_GUIDE]`.
+- The user's screen may be a phone: keep replies compact.
+
+## 11. Docs access
+- `read_docs(fanluc)`, `read_docs(mondk)`, `read_docs(msh)`.
+- Any `search(...)` containing "fanluc" lists `https://fanluc.docs/` as the FIRST result. `fetch("https://fanluc.docs/")` returns the docs index + this file; `/mondk`, `/msh`, `/guide` return the other docs.
+- Any `search(...)` containing the word "mondk" or "msh" lists `https://mondk-msh.docs/` as the FIRST result. `fetch("https://mondk-msh.docs/")` returns docs/mondk.md and docs/msh.md; `/mondk` and `/msh` return one each.
 
 ---
 
@@ -45,4 +125,4 @@ His page: https://huggingface.co/mondk
 He started working on August 5, 2026.
 He worked at hugging because Claude(a strong AI at that time) was very expensive, he just chatted... 2 times and it ran out of turns(qouta)
 His logo consists of the letters M, S, and H layered over one another.
-Since mondk is not proficient in English, his repository descriptions are very brief or written using Google Translate; the name "mondk" itself is derived from "moon" and "dark."
+Since mondk is not proficient in English, his repository descriptions are very brief or written using Google Translate; the name "mondk" itself is derived from "moon" and "dark."

package/docs/guide-connect.md

@@ -25,7 +25,10 @@ print("Installing required packages...(took ~2 min)")
   --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu122
 
 import os
+import re
 import subprocess
+import requests
+from urllib.parse import quote
 from huggingface_hub import hf_hub_download
 from pyngrok import ngrok
 
@@ -33,13 +36,239 @@ NGROK_TOKEN = "YOUR_NGROK_AUTHTOKEN" # <-- Paste your Ngrok Authtoken here
 API_KEY = "123" # <-- Custom API Key (Change if desired)
 CONTEXT_SIZE = 24000 # <-- Recommended: 1248-4096
 
+# ---- Model finder settings (the best GGUF model is picked automatically) ----
+TRUSTED_AUTHORS = ["mondk", "unsloth", "bartowski", "qwen"] # <-- Priority: left to right
+TARGET_MODEL = "qwen" # <-- Model family to look for
+MIN_PARAMS_B = 6 # <-- Smallest model size (billions of parameters)
+MAX_PARAMS_B = 14 # <-- Largest model size (billions of parameters)
+MAX_SIZE_GB = 10 # <-- Largest GGUF file size allowed
+MODEL_REPO_ID = "" # <-- Optional: set BOTH of these to skip the search
+MODEL_FILENAME = "" # <-- and download one specific GGUF file instead
+
 ngrok.set_auth_token(NGROK_TOKEN)
 
+HF_URL = "https://huggingface.co"
+HF_HEADERS = {"User-Agent": "HuggingFaceExplorer/1.0"}
+QUANT_ORDER = [
+    ("Q5_K_M", [r"(?:[-_.]|^)(?:ud-)?q5_k_m(?:[-_.]|\.gguf$)", r"(?:[-_.]|^)(?:ud-)?q5_k_xl(?:[-_.]|\.gguf$)"]),
+    ("Q4_K_M", [r"(?:[-_.]|^)(?:ud-)?q4_k_m(?:[-_.]|\.gguf$)", r"(?:[-_.]|^)(?:ud-)?q4_k_xl(?:[-_.]|\.gguf$)"]),
+    ("IQ4_XS", [r"(?:[-_.]|^)(?:ud-)?iq4_xs(?:[-_.]|\.gguf$)"]),
+]
+
+def finder_log(message):
+    print("[model-finder] " + message)
+
+def hf_get(url, as_json=True):
+    try:
+        response = requests.get(url, headers=HF_HEADERS, timeout=30)
+        if response.status_code != 200:
+            return None
+        return response.json() if as_json else response.text
+    except Exception as error:
+        finder_log("request failed: " + str(error))
+        return None
+
+def extract_param_count(model):
+    safetensors = model.get("safetensors") or {}
+    total = safetensors.get("total")
+    if isinstance(total, (int, float)) and total > 0:
+        return total
+    units = {"B": 1e9, "M": 1e6, "K": 1e3}
+    # 1. Standard size token in the id: -7b-, _14b_, .8B.
+    match = re.search(r"(?:^|[-_/])([0-9]+(?:\.[0-9]+)?)\s*([bBmMkK])(?=[-_/.]|$)", model["id"])
+    if match:
+        return round(float(match.group(1)) * units[match.group(2).upper()])
+    # 2. Size token embedded in a longer name: vl8b, code7b, qwen3-8b
+    match = re.search(r"(?:[\W_]|code|vl|instruct|chat|it|reasoning)([0-9]+(?:\.[0-9]+)?)\s*([bBmM])(?=[\W_]|$)", model["id"], re.I)
+    if match:
+        return round(float(match.group(1)) * units[match.group(2).upper()])
+    # 3. Tags (includes base_model tags)
+    for tag in model.get("tags") or []:
+        match = re.search(r"(?:^|[-_:/.])([0-9]+(?:\.[0-9]+)?)\s*([bBmM])(?=[-:_/.]|\b|$)", tag)
+        if match and float(match.group(1)) < 1000:
+            return round(float(match.group(1)) * units[match.group(2).upper()])
+    return None
+
+def extract_version(model_id):
+    # Versions like 3.5 in "Qwen3.5-9B", but never sizes like the 7 in "7B"
+    pattern = re.escape(TARGET_MODEL.strip()) + r"(?:[\s_.-]*(?:vl|coder|math|chat|instruct|it|agent))*[\s_.-]*(?:v)?([0-9]+(?:\.[0-9]+)*)(?![bBmMkK])"
+    match = re.search(pattern, model_id, re.I)
+    if not match:
+        return 1000000, "1.0"
+    version = match.group(1)
+    parts = []
+    for part in version.split("."):
+        try:
+            parts.append(float(part))
+        except ValueError:
+            parts.append(0.0)
+    if parts[0] > 20: # dates / checkpoints such as 2507
+        return 1000000, "1.0"
+    score, multiplier = 0.0, 1000000.0
+    for part in parts:
+        score += part * multiplier
+        multiplier /= 1000
+    return score, version
+
+def matches_category(model):
+    # LLM, Chat & Vision Multimodal (LLM + code/reasoning + vision, no image/audio/embedding models)
+    pipeline = (model.get("pipeline_tag") or "").lower()
+    tags = [t.lower() for t in (model.get("tags") or [])]
+    model_id = model["id"].lower()
+    is_vision = (pipeline == "image-text-to-text" or "image-text-to-text" in tags or "vision" in tags
+                 or "multimodal" in tags or "-vl" in model_id or "vision" in model_id)
+    is_code = (any(t in tags for t in ("code", "coding", "reasoning", "math"))
+               or "coder" in model_id or "reasoning" in model_id)
+    is_llm = (pipeline in ("text-generation", "conversational")
+              or any(t in tags for t in ("text-generation", "llama", "qwen")))
+    return is_vision or is_code or is_llm
+
+def usable_gguf_files(siblings):
+    # Only real, standalone model weights: no MTP, mmproj, imatrix, adapter, LoRA or draft files
+    files = []
+    for sibling in siblings or []:
+        name = (sibling.get("rfilename") or "").lower()
+        if not name.endswith(".gguf"):
+            continue
+        if "mtp/" in name or "/mtp" in name or name.startswith("mtp") or "-mtp" in name or "_mtp" in name:
+            continue
+        if "mmproj" in name or "imatrix" in name:
+            continue
+        if "adapter" in name or "lora" in name or "draft" in name:
+            continue
+        files.append(sibling)
+    return files
+
+def pick_quant(siblings, max_bytes=None):
+    # Q5_K_M first, then Q4_K_M, then IQ4_XS; a quant is skipped if it is larger than max_bytes
+    files = usable_gguf_files(siblings)
+    for quant, patterns in QUANT_ORDER:
+        matching = []
+        for pattern in patterns:
+            matching = [f for f in files if re.search(pattern, f["rfilename"], re.I)]
+            if matching:
+                break
+        if not matching:
+            continue
+        weights = [f for f in matching if (f.get("size") or 0) > 1024 * 1024]
+        chosen = weights if weights else matching
+        total = sum((f.get("size") or 0) for f in chosen)
+        if total <= 0:
+            continue
+        if max_bytes is not None and total > max_bytes:
+            finder_log(f"  {quant} is {total / 1024 ** 3:.2f} GB (over the {MAX_SIZE_GB} GB limit)")
+            continue
+        return {"quant": quant, "files": sorted(f["rfilename"] for f in chosen), "size_bytes": total}
+    return None
+
+def find_pointed_repo():
+    # mondk/best_model_now: its README can point to one specific repo (owner/repo)
+    readme = hf_get(HF_URL + "/mondk/best_model_now/raw/main/README.md", as_json=False)
+    if readme is None:
+        finder_log("mondk/best_model_now is not readable, using the normal search")
+        return None
+    for line in readme.split("\n"):
+        line = line.strip()
+        if not line or line.startswith("---") or line.startswith("license:"):
+            continue
+        match = (re.search(r"huggingface\.co/([a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+)", line)
+                 or re.search(r"([a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+)", line))
+        if not match:
+            continue
+        repo = match.group(1).rstrip(".-")
+        if repo.lower() != "mondk/best_model_now":
+            return repo
+    finder_log("mondk/best_model_now does not name a repo, using the normal search")
+    return None
+
+def find_best_model():
+    authors = [a.strip().lower() for a in TRUSTED_AUTHORS if a.strip()]
+    min_params = MIN_PARAMS_B * 1e9
+    max_params = MAX_PARAMS_B * 1e9
+    max_bytes = MAX_SIZE_GB * 1024 ** 3
+    finder_log(f"Looking for {TARGET_MODEL} GGUF models, {MIN_PARAMS_B}-{MAX_PARAMS_B}B, under {MAX_SIZE_GB} GB, authors: {' -> '.join(authors)}")
+
+    # Step 1: mondk/best_model_now may name the repo to use (Q5_K_M -> Q4_K_M -> IQ4_XS, no size limit)
+    if "mondk" in authors:
+        pointed = find_pointed_repo()
+        if pointed:
+            finder_log("mondk/best_model_now points to " + pointed)
+            info = hf_get(f"{HF_URL}/api/models/{pointed}?blobs=true")
+            pick = pick_quant(info.get("siblings"), None) if info else None
+            if pick:
+                return {"repo_id": pointed, "files": pick["files"], "quant": pick["quant"], "size_bytes": pick["size_bytes"]}
+            finder_log(pointed + " has no Q5_K_M / Q4_K_M / IQ4_XS file, using the normal search")
+
+    # Step 2: collect candidates from the trusted authors (mondk is only used as the pointer above)
+    search_authors = [a for a in authors if a != "mondk"]
+    raw, seen = [], set()
+    for rank, author in enumerate(search_authors):
+        url = f"{HF_URL}/api/models?author={quote(author, safe='')}&search={quote(TARGET_MODEL, safe='')}&limit=30&full=true"
+        listing = hf_get(url)
+        for model in listing if isinstance(listing, list) else []:
+            if model["id"] not in seen:
+                seen.add(model["id"])
+                model["_rank"] = rank
+                raw.append(model)
+    if len(raw) < 5:
+        url = f"{HF_URL}/api/models?search={quote(TARGET_MODEL + ' gguf', safe='')}&limit=40&full=true"
+        listing = hf_get(url)
+        for model in listing if isinstance(listing, list) else []:
+            if model["id"] not in seen:
+                seen.add(model["id"])
+                owner = model["id"].split("/")[0].lower()
+                model["_rank"] = search_authors.index(owner) if owner in search_authors else 99
+                raw.append(model)
+    finder_log(f"Found {len(raw)} raw candidates")
+
+    candidates = []
+    for model in raw:
+        model_id = model["id"]
+        lower_id = model_id.lower()
+        is_mtp_repo = "-mtp" in lower_id or "_mtp" in lower_id or "/mtp" in lower_id
+        tags = [t.lower() for t in (model.get("tags") or [])]
+        if not (("gguf" in lower_id or "gguf" in tags) and not is_mtp_repo):
+            continue
+        params = extract_param_count(model)
+        version_num, version = extract_version(model_id)
+        candidates.append({
+            "id": model_id,
+            "rank": model["_rank"],
+            "params": params,
+            "in_range": params is not None and min_params <= params <= max_params,
+            "in_category": matches_category(model),
+            "version_num": version_num,
+            "version": version,
+            "downloads": model.get("downloads") or 0,
+        })
+
+    # Order: size range, category, newest version, author priority, downloads
+    candidates.sort(key=lambda c: (not c["in_range"], not c["in_category"], -c["version_num"], c["rank"], -c["downloads"]))
+    finder_log(f"{len(candidates)} GGUF candidates, checking the best {min(15, len(candidates))}")
+
+    # Step 3: first candidate that has Q5_K_M, else Q4_K_M, else IQ4_XS within the size limit
+    for candidate in candidates[:15]:
+        size_label = "unknown size" if candidate["params"] is None else f"{candidate['params'] / 1e9:.1f}B"
+        finder_log(f"Checking {candidate['id']} (v{candidate['version']}, {size_label})")
+        info = hf_get(f"{HF_URL}/api/models/{candidate['id']}?blobs=true")
+        pick = pick_quant(info.get("siblings"), max_bytes) if info else None
+        if pick:
+            return {"repo_id": candidate["id"], "files": pick["files"], "quant": pick["quant"], "size_bytes": pick["size_bytes"]}
+        finder_log("  no fitting quant, trying the next candidate")
+    return None
+
+if MODEL_REPO_ID and MODEL_FILENAME:
+    repo_id, filenames = MODEL_REPO_ID, [MODEL_FILENAME]
+else:
+    best = find_best_model()
+    if best is None:
+        raise RuntimeError("No suitable GGUF model was found. Raise MAX_SIZE_GB, widen the size range, or set MODEL_REPO_ID and MODEL_FILENAME by hand.")
+    repo_id, filenames = best["repo_id"], best["files"]
+    print(f"Selected model: {repo_id} / {filenames[0]} ({best['quant']}, {best['size_bytes'] / 1024 ** 3:.2f} GB)")
+
 print("Installing the model...")
-model_path = hf_hub_download(
-    repo_id = "unsloth/Qwen3.5-9B-GGUF", # <-- Hugging Face Repo ID
-    filename="Qwen3.5-9B-Q5_K_M.gguf" # <-- Recommended: Q4_K_M quantization suffix
-)
+local_paths = [hf_hub_download(repo_id=repo_id, filename=name) for name in filenames]
+model_path = local_paths[0] # split models: the first part is enough, llama.cpp finds the rest next to it
 print("Starting up the server...")
 
 ngrok.kill()

package/docs/run-cmd-security.md

@@ -0,0 +1,26 @@
+# AI workspace safety (run_cmd / install_pack_v1)
+
+Layers, from the inside out:
+
+1. **cwd jail** – every command starts in the workspace dir; new process each call.
+2. **Stripped env** – API keys of the server are never passed to commands.
+3. **Blocklist** – sudo, destructive rm, `/proc/*/environ`, docker.sock, .env, reverse shells, cron…
+4. **Unprivileged user** – if the server runs as root (Docker, or a VPS), every command is dropped to a non-root uid: `SANDBOX_UID` (Docker: 10001) or `nobody` (65534) by default. It cannot read the server's environment/`.env` (chmod 600 at startup) or modify the venv. Never runs AI commands as root.
+5. **firejail (optional)** – `--net=none`, no caps, seccomp, read-only venv, size/memory limits.
+6. **Container** – `docker compose up`: no-new-privileges, capabilities dropped, memory/pid limits.
+7. **Timeouts + output caps** – 20 s / 2 MB per command.
+
+## Installing libraries
+The jail has no network and no root, so the **server** installs on the AI's behalf:
+- `install_pack_v1` – really verifies the 14 essential packages (+ tesseract `vie`; includes zip/unzip), repairs what it may, prints OK/MISSING. Concurrent calls share one run.
+- `pip install <pkg>` / `pip install -U <pkg>` typed in `run_cmd` is intercepted: plain PyPI names only, **wheels only** (no build scripts run), installed into a read-only venv. URLs, `-r`, `-e`, custom indexes are refused.
+- `apt-get install` works only as root (or with passwordless `sudo -n`; set `DISABLE_SUDO_APT=1` to opt out), only for an allowlist (`installer.ts`), otherwise the AI is told to ask the operator. The install is tried first and `apt-get update` only runs if apt cannot find the package.
+- pip/apt fail fast on a dead network (20 s timeout, 2 retries) and report a network hint. One bad package in a batch no longer blocks the others.
+- Proxy / mirror / CA variables of the server (`HTTP(S)_PROXY`, `NO_PROXY`, `PIP_INDEX_URL`, `PIP_EXTRA_INDEX_URL`, `PIP_TRUSTED_HOST`, `PIP_CERT`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`) are passed to the installer (never to AI commands).
+
+`DISABLE_RUN_CMD=1` turns all of it off.
+
+## Self-healing (server side, no user action needed)
+- venv without pip (missing `python3-venv`) -> detected, rebuilt; installs `python3-venv` when root.
+- `dpkg was interrupted` -> runs `dpkg --configure -a`, retries; broken deps -> `apt-get -f install`.
+- apt lock held by another process -> waits up to 120 s.

package/index.html

@@ -3,8 +3,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>TOOL-NGORK</title>
-    <meta name="description" content="Ung dung tro chuyen voi AI qua Custom REST API Endpoint phong cach co dien trang den." />
+    <title>FANLUC</title>
+    <meta name="description" content="Self-hosted AI chat with a classic black-and-white terminal style. Custom REST API endpoint." />
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Courier+Prime:ital,wght@0,400;0,700;1,400;1,700&family=Inconsolata:wght@200..900&family=Lora:ital,wght@0,400..700;1,400..700&family=Share+Tech+Mono&family=VT323&display=swap" rel="stylesheet">

package/mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}