From ce9b2d73f7237952ef6dcfd5039a63db6efe5394 Mon Sep 17 00:00:00 2001
From: Vlad Doloman <github@vaku.org.ua>
Date: Fri, 26 Jun 2026 18:17:54 +0300
Subject: [PATCH] docs: add README with setup, config, states, and reverse
 proxy guide

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b0a972d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,121 @@
+# Llamagochi
+
+A browser-based virtual pet llama that mirrors a running `llama-server` instance by tailing its log file. The llama animates differently depending on what the server is doing — loading a model, processing a prompt, generating tokens, sleeping, or erroring out.
+
+```
+IDLE           PROCESSING PROMPT     GENERATING        SLEEPING
+ ear twitches   eyes scan left/right  mouth talks       zzz floats up
+                progress bar shown    tail wags
+```
+
+## Requirements
+
+- Python 3.10+
+- `llama-server` running in **router mode** (the multi-model router that logs `cmd_child_to_router:state:{...}` JSON lines)
+- The log file must be accessible from the machine running Llamagochi (local path or a mount)
+
+## Installation
+
+```bash
+git clone <repo>
+cd llamagochi
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Running
+
+```bash
+python server.py --log /path/to/llama-server.log
+```
+
+The web UI is then available at `http://localhost:8080`.
+
+### Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--log PATH` | — | Path to the llama-server log file (required unless set in `config.json` or `$LLAMAGOCHI_LOG`) |
+| `--port PORT` | `8080` | HTTP port to listen on |
+| `--reopen-log` | off | Close and reopen the log file on every poll cycle. Use this when the log is on a network filesystem (sshfs, NFS) that caches file content at open time |
+
+### Configuration file
+
+Instead of passing `--log` every time, create `config.json` in the project directory:
+
+```json
+{
+  "log": "/path/to/llama-server.log",
+  "reopen_log": true
+}
+```
+
+`reopen_log` in the config is equivalent to `--reopen-log` on the command line. CLI flags take precedence.
+
+### Environment variable
+
+```bash
+export LLAMAGOCHI_LOG=/path/to/llama-server.log
+python server.py
+```
+
+## Reverse proxy (HTTPS)
+
+Llamagochi uses WebSocket (`/ws`) and HTTP polling (`/state`). Both must be proxied. Example nginx snippet:
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:8080;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+}
+```
+
+The frontend automatically uses `wss://` when the page is served over HTTPS.
+
+## States
+
+| State | What it means |
+|---|---|
+| `idle` | Server is up, no active request |
+| `waiting` | Router received a request, slot not yet assigned |
+| `loading` | Model is loading into VRAM (progress bar shown) |
+| `warming_up` | Model weights loaded, running warmup pass |
+| `processing_prompt` | Evaluating the prompt (progress bar 0–100%) |
+| `generating` | Generating tokens |
+| `sleeping` | Server idle-timeout reached, model evicted |
+| `unloading` | LRU eviction in progress |
+| `error` | Model failed to load |
+| `offline` / `LOG OFFLINE` | Llamagochi cannot read the log file |
+
+## Connection status dot (top-right of screen)
+
+| Colour | Meaning |
+|---|---|
+| Green | WebSocket live — real-time updates |
+| Amber | WebSocket down, falling back to HTTP polling every 2 s |
+| Red | Both WebSocket and HTTP polling are unreachable |
+
+When the WebSocket reconnects, polling stops automatically.
+
+## Log file format
+
+Llamagochi expects the log produced by `llama-server` router mode, optionally prefixed with timestamps by the `ts` utility:
+
+```
+[2026-06-22 20:09:31] [51201] 3.13.636.722 I srv  update_slots: all slots are idle
+[2026-06-22 20:09:31] 339.42.030.150 I srv  proxy_reques: proxying request to model ...
+```
+
+Lines prefixed with `[PORT]` are child-process lines; unprefixed lines are router-level. Both are understood.
+
+## Running tests
+
+```bash
+pytest
+```
+
+32 tests covering the log parser state machine and log watcher.