Upload README.md with huggingface_hub

README.md

@@ -1,84 +1,125 @@
----
-library_name: gguf
-pipeline_tag: text-generation
-tags:
-- gguf
-- function-calling
-- agent
-- homelab
-- gemma
-- qwen
-- eightly-os
-- tool-use
-license: apache-2.0
-base_model:
-- google/functiongemma-270m-it
-- google/gemma-2-2b-it
-- Qwen/Qwen3-4B
-- Qwen/Qwen3-8B
----
-
-# Eightly Agent
-
-Tiered model family powering **Nova**, the built-in AI agent for [Eight.ly OS](https://eight.ly) — a self-hosted homelab operating system that combines virtualization, containers, storage, networking, and an AI control plane in a single Go binary.
-
-This repo ships four GGUFs designed to be deployed together. The host OS routes each turn to the right model based on intent and available hardware.
+# Eight.ly Agent
 
-## Models
-
-| File | Size | Role | Base | Use |
-|------|------|------|------|-----|
-| `eightly-agent-fg.gguf` | 359 MB | **Tool router** | FunctionGemma 270m | Sub-1s function calls on CPU. Fine-tuned on 4,684 Eight.ly OS tool-calling examples. |
-| `eightly-agent-e2b-Q4_K_M.gguf` | 3.2 GB | Conversational | Gemma 4 E2B | Natural chat and reasoning on modest hardware |
-| `eightly-agent-q4b-Q4_K_M.gguf` | 2.4 GB | Conversational | Qwen3 4B | Mid-tier homelabs |
-| `eightly-agent-q8b-Q4_K_M.gguf` | 4.7 GB | Conversational | Qwen3 8B | Beefy boxes — best reasoning quality |
+Fine-tuned on 4,684 Eight.ly OS tool-calling examples across 41 NAS management tools (Docker, storage, VMs, LXC, file sharing, system administration).
 
 ## Architecture
 
-Nova uses a **dual-mode router**: tool-bound turns dispatch to `fg` for near-instant function calls, while open-ended or reasoning turns go to whichever conversational model fits the host's hardware tier. The OS handles selection automatically — no configuration required.
+```
+user query
+    |
+    v
++---------------+
+| Nova Router   |
+| (Go intent    |
+|  classifier)  |
++-------+-------+
+        |
+   +----+----+
+   v         v
++------+  +----------------+
+| fg   |  | conversational |
+|359MB |  | tier (gemma2,  |
+|tool  |  | q4b, q8b, e2b) |
+|calls |  |                |
++------+  +----------------+
+```
 
-This means a Pi-class device gets working AI control without GPU, while beefier boxes get richer conversation without sacrificing tool-call latency.
+The Nova Router is a zero-latency Go pattern matcher (57 test cases) that classifies queries into `no_tool`, `tool`, or `maybe`. Tool queries route to FunctionGemma for structured tool-call extraction via GBNF grammar. Conversational queries skip directly to the response model.
 
-## Running
+## Evaluation
 
-Standard GGUFs — anything that speaks llama.cpp will load them.
+| Metric | Value |
+|--------|-------|
+| Tool-call accuracy (fg) | 87.5% (13/15 standard audit suite) |
+| FunctionGemma latency | Sub-1s on CPU |
+| Median tool-query response | 6.9s end-to-end |
+| No-tool response time | 1-3s |
+| System queries | 10-18s |
+| Container/health queries | 6-14s |
+
+Evaluated by Opus 4.7 auditor over 8 rounds. Remaining sharp edges: Docker stop/kill semantics, acknowledgment over-eagerness, storage pool labeling.
+
+## Models
 
-**With Ollama:**
+| Model | Base | GGUF Size | Role |
+|-------|------|-----------|------|
+| eightly-agent-fg | FunctionGemma 270M | 359 MB | Tool router (dual-model worker) |
+| eightly-agent-q4b | Qwen3 4B | 2.4 GB | Single-model fallback |
+| eightly-agent-q8b | Qwen3 8B | 4.7 GB | Best single-model quality |
+| eightly-agent-e2b | Gemma 4 E2B | 3.2 GB | Experimental (not yet deployed) |
+
+Conversational tier uses stock `gemma2:2b` (1.6 GB) as the response synthesizer.
+
+## Training Data
+
+- 4,684 tool-calling examples (FunctionGemma fine-tune)
+- 41 tools across 6 domains: Docker, Storage, VMs, LXC, File Sharing, System
+- Dataset: [smashingtags/eightly-agent-dataset](https://huggingface.co/datasets/smashingtags/eightly-agent-dataset)
+
+## Usage
 
 ```bash
-# Pull the function-caller
-ollama create eightly-agent-fg -f Modelfile.fg
-
-# Use it
-curl http://localhost:11434/api/generate -d '{
-  "model": "eightly-agent-fg",
-  "prompt": "<bos><start_of_turn>developer\nYou are a model that can do function calling...<start_of_turn>user\nHow much disk space is free?<end_of_turn>\n<start_of_turn>model\n",
-  "raw": true,
-  "stream": false
-}'
+# Pull the FunctionGemma tool router
+ollama pull smashingtags/eightly-agent-fg
+
+# Pull the single-model fallback (Qwen3 4B)
+ollama pull smashingtags/eightly-agent-q4b
+
+# Pull the high-quality single-model (Qwen3 8B)
+ollama pull smashingtags/eightly-agent-q8b
+
+# Run locally
+ollama run smashingtags/eightly-agent-q4b
 ```
 
-**With llama.cpp directly:**
+These models are designed to work within the Eight.ly OS Nova assistant pipeline. FunctionGemma expects a scoped tool catalog with GBNF grammar constraints. The q4b/q8b models support native Ollama tool calling.
 
-```bash
-llama-server -m eightly-agent-fg.gguf --port 8081
+## Example: Tool-Calling Flow
+
+**User:** "How much disk space is free?"
+
+**Step 1 — FunctionGemma routes to tool:**
+```
+<start_function_call>call:get_storage_status{}<end_function_call>
 ```
 
-Or just run [Eight.ly OS](https://eight.ly) and it wires everything up for you.
+**Step 2 — Tool executes, returns real data:**
+```json
+{"mountpoint": "/mnt/storage", "total": "69.8 GB", "used": "22 MB", "free": "69.8 GB", "percent": "0.03%"}
+```
 
-## Tool Calling Format
+**Step 3 — Conversational model responds:**
+> "Your storage pool at /mnt/storage has 69.8 GB free out of 69.8 GB total — essentially empty at 0.03% used."
 
-`fg` is fine-tuned on FunctionGemma's native format with `<start_function_call>call:NAME{args}<end_function_call>` tokens. Tool declarations are baked into the prompt as `<start_function_declaration>declaration:NAME{...}<end_function_declaration>` blocks. The model was trained on 4,684 examples across 41 NAS management tools.
+End-to-end: ~6.9 seconds median. FunctionGemma decision: sub-1 second.
 
 ## 41 Tools
 
-Storage, Docker containers, VMs (KVM/QEMU), LXC, SMB/NFS file sharing, network interfaces, firewall, SnapRAID parity, ZFS pools, SMART health, system info, app store, and more.
+**Docker:** list_containers, get_container_logs, get_container_stats, list_docker_stacks, list_docker_images, list_docker_networks, list_docker_volumes, container_action, pull_docker_image, install_app
+
+**Storage:** get_storage_status, get_storage_capacity, get_cache_status, get_snapraid_status, get_disk_health, get_zfs_pools, run_snapraid_sync, run_smart_test, spin_down_disks, create_backup
 
-## Status
+**VMs:** list_vms, get_vm_stats, list_vm_snapshots, vm_action, create_vm_snapshot
 
-Active development. Eight.ly OS is in alpha; this model family is being trained against an evolving 41-tool catalog spanning storage, virtualization, containers, networking, and system control.
+**LXC:** list_lxc_containers, lxc_action
+
+**File Sharing:** get_smb_shares, get_nfs_exports, create_smb_share, create_nfs_export
+
+**System:** get_system_info, get_system_version, get_system_logs, get_node_time, get_network_interfaces, get_firewall_rules, get_health_overview, get_nova_models, search_apps, set_timezone, reboot_system
+
+## Roadmap
+
+- Tool catalog growing from 41 tools. Next: scheduling tools, backup management, network diagnostics.
+- Multi-turn context for follow-up questions.
+- Additional domain scoping refinements based on real user feedback.
+- Gemma 4 E2B deployment and evaluation.
 
 ## Links
 
-- [eight.ly](https://eight.ly)
-- GitHub: [smashingtags/eightly-os](https://github.com/smashingtags/eightly-os) *(private during alpha)*
+- **Product:** [eight.ly](https://eight.ly)
+- **Dataset:** [smashingtags/eightly-agent-dataset](https://huggingface.co/datasets/smashingtags/eightly-agent-dataset)
+- **Discord:** [discord.gg/Y9jbyrnTTj](https://discord.gg/Y9jbyrnTTj)
+
+## License
+
+Apache 2.0