# NanoHat OS Agent — Technical Specification & Case Study

> Sub-1B parameter local desktop automation runtime tailored for Linux / Fedora Workstation. Powered by distilled student models (SmolLM2-360M, Qwen2.5-0.5B), a pure native Python execution harness, and 250,600 verified multi-turn action traces with fail-closed mechanical safety gates.

- **Status:** v3.0.0 Production Release // Local First
- **Repository:** https://github.com/asimansari-git/NanoHat
- **HTML Case Study:** https://asimansari.com/projects/nanohat.html
- **Canonical Domain:** https://nanohat.asimansari.com

---

## 1. System Architecture & Model Hierarchy

NanoHat replaces cloud LLM wrappers with a local-first, low-latency execution harness running close to the metal on Linux.

### Distilled Student Checkpoints
- **Primary Runtime:** SmolLM2-360M-Instruct (Quantized GGUF Q4_K_M / Q8_0)
- **Secondary Runtime:** Qwen2.5-0.5B-Instruct (Quantized GGUF Q4_K_M)
- **Target Platform:** Fedora Linux Workstation (x86_64, Linux kernel 6.x+, GNOME / Wayland / X11)
- **Inference Engine:** `llama.cpp` CPU-optimized C/C++ runtime (<85ms single-turn latency on commodity laptop CPUs)
- **Zero Framework Bloat:** 100% native Python standard library (`subprocess`, `asyncio`, `socket`, `ctypes`) without LangChain, CrewAI, or AutoGen overhead.

---

## 2. The 17-Tool Canonical POSIX Registry

The tool execution surface is strictly frozen to 17 orthogonal tools across 7 subsystem modules:

| Subsystem Module | Tools | Risk Tier | Execution Mechanics |
| :--- | :--- | :--- | :--- |
| **System & Diagnostics** (`tools/diag.py`) | `system_health(target)`, `service_status(unit)`, `hardware_profile()` | READONLY | Parses `/proc`, `sysfs`, and `systemctl` state via direct POSIX descriptors. |
| **Process Inspection** (`tools/proc.py`) | `process_list(sort_by, limit)`, `process_inspect(pid)` | READONLY | Inspects `/proc/[pid]/status`, memory maps, and parent-child hierarchies. |
| **POSIX Shell** (`tools/shell.py`) | `shell_command(cmd, timeout)` | WRITE | Subshell execution isolated with timeout timers (default: 15s) and stderr capture. |
| **File Operations** (`tools/files.py`) | `file_read(path, offset, limit)`, `file_write(path, content)`, `directory_list(path)` | WRITE | Validates canonical realpath targets; prevents directory traversal attacks. |
| **Window & Desktop UI** (`tools/gui.py`) | `window_focus(title)`, `keystroke_send(keys)`, `screenshot_capture()` | WRITE | Interacts via `xdotool`, `wmctrl`, and GNOME D-Bus IPC endpoints. |
| **Network Auditing** (`tools/net.py`) | `network_ping(host)`, `dns_resolve(domain)`, `route_table()` | READONLY | Socket-level ICMP ping and interface routing table parsing. |
| **Destructive Safety** (`tools/admin.py`) | `process_kill(pid, signal)`, `service_restart(unit)`, `file_delete(path)` | DESTRUCTIVE | **FAIL-CLOSED:** Refuses headless execution without explicit TTY human confirmation. |

---

## 3. The 4-Gate Mechanical Verification Pipeline

To distill desktop tool-calling capabilities without catastrophic hallucinations, 250,600 multi-turn POSIX desktop action traces (152.7M high-entropy tokens) were passed through 4 automated gates prior to LoRA fine-tuning:

1. **Gate 01: Syntax & Schema Validation:** Enforces strict JSON grammar constraints and verifies that return payloads match canonical byte signatures (`OK: [payload]` or `ERROR[reason]: [payload]`).
2. **Gate 02: Mock Environment Replay:** Re-executes each generated trace against mock Linux systemd units, process tables, and D-Bus fixtures to ensure action validity.
3. **Gate 03: Information Density & Entropy Filtering:** Strips conversational filler and redundant pleasantries, ensuring student weights only train on high-density state transitions.
4. **Gate 04: Dataset Purity & Deduplication:** Calculates structural n-gram fingerprints across all trajectories, discarding overlapping or repetitive traces to prevent memorization.

---

## 4. Benchmark Results & Operational Baseline

- **Single-Step POSIX Command Accuracy:** 98.4% across 1,200 curated Linux administration prompts.
- **Multi-Turn Recovery Rate:** 91.2% self-correction rate when encountering `ERROR[not_found]` or `ERROR[permission_denied]` feedback.
- **Memory Footprint:** 340MB RAM under full load during quantized SmolLM2-360M inference.
- **Telemetry Invariant:** 0 outgoing network bytes during local reasoning and tool execution.