|
|
--- |
|
|
license: mit |
|
|
library_name: fastapi |
|
|
tags: |
|
|
- gguf |
|
|
- local-ai |
|
|
- llama.cpp |
|
|
- mirror |
|
|
- tobyworld |
|
|
pipeline_tag: text-generation |
|
|
--- |
|
|
|
|
|
# mirror-pond |
|
|
A 100% local Tobyworld Mirror that runs any GGUF model through llama.cpp. No cloud. No tracking. Just your pond, your reflection, your machine. FastAPI + llama.cpp • Offline • MIT Licensed. |
|
|
|
|
|
# 🪞 Mirror Pond — Local GGUF Edition |
|
|
|
|
|
*A still-water reflection engine for your local LLM.* |
|
|
|
|
|
Mirror Pond is a **100% local**, **privacy-first**, Tobyworld-inspired reflection interface that runs any GGUF model through `llama.cpp` with a calm Mirror UI. |
|
|
|
|
|
No cloud. |
|
|
No tracking. |
|
|
Your thoughts stay on your machine. |
|
|
|
|
|
--- |
|
|
|
|
|
## ✨ Features |
|
|
|
|
|
* 🧠 **Runs any GGUF model** — Llama, DeepSeek, Mistral, or your trained Mirror |
|
|
* 🌑 **Dark, still Mirror UI** (HTML served locally) |
|
|
* 💬 **Four modes**: |
|
|
|
|
|
* **Reflect** — emotional / introspective |
|
|
* **Scroll** — lore / quotes / scripture |
|
|
* **Toad** — cryptic toadgang whispers |
|
|
* **Rune** — symbols, lotus, $PATIENCE, seasons |
|
|
* 🔒 **Fully offline** (Air-gapped compatible) |
|
|
* ⚡ FastAPI + Uvicorn backend |
|
|
* 🧩 Optional: GPU acceleration via llama-cpp-python CUDA wheels |
|
|
|
|
|
--- |
|
|
|
|
|
# 🚀 Quickstart |
|
|
|
|
|
### 1. Install dependencies |
|
|
|
|
|
```bash |
|
|
pip install -r requirements.txt |
|
|
``` |
|
|
|
|
|
### 2. Run the Pond |
|
|
|
|
|
```bash |
|
|
python mirror_pond.py --model ./your_model.gguf --port 7777 |
|
|
``` |
|
|
|
|
|
### 3. Open in browser |
|
|
|
|
|
``` |
|
|
http://localhost:7777 |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
# 📁 Requirements |
|
|
|
|
|
`requirements.txt` (included): |
|
|
|
|
|
``` |
|
|
fastapi==0.115.0 |
|
|
uvicorn==0.32.0 |
|
|
pydantic==2.8.2 |
|
|
llama-cpp-python==0.3.2 |
|
|
jinja2==3.1.4 |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
# 🔥 GPU Acceleration (Optional) |
|
|
|
|
|
For NVIDIA CUDA (12.1): |
|
|
|
|
|
```bash |
|
|
pip install llama-cpp-python-cu121 |
|
|
``` |
|
|
|
|
|
For AMD ROCm: |
|
|
|
|
|
```bash |
|
|
pip install llama-cpp-python-rocm |
|
|
``` |
|
|
|
|
|
For Apple Silicon (M1/M2/M3): |
|
|
|
|
|
```bash |
|
|
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
# 🧱 Folder Structure |
|
|
|
|
|
``` |
|
|
mirror-pond/ |
|
|
│ |
|
|
├── mirror_pond.py # main server |
|
|
├── requirements.txt # dependencies |
|
|
├── setup.sh # Linux/macOS installer |
|
|
├── setup.ps1 # Windows installer |
|
|
├── Dockerfile # container build |
|
|
└── README.md # this file |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
# 🧪 Installation Kits |
|
|
|
|
|
## Linux / macOS Installer |
|
|
|
|
|
```bash |
|
|
chmod +x setup.sh |
|
|
./setup.sh ./models/your_model.gguf 7777 |
|
|
``` |
|
|
|
|
|
## Windows Installer |
|
|
|
|
|
```powershell |
|
|
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass |
|
|
.\setup.ps1 .\models\your_model.gguf 7777 |
|
|
``` |
|
|
|
|
|
Both installers: |
|
|
|
|
|
* Create `./venv` |
|
|
* Install Python deps |
|
|
* Launch Mirror Pond automatically |
|
|
|
|
|
--- |
|
|
|
|
|
# 🐳 Docker Usage |
|
|
|
|
|
## Build |
|
|
|
|
|
```bash |
|
|
docker build -t mirror-pond:latest . |
|
|
``` |
|
|
|
|
|
## Run |
|
|
|
|
|
```bash |
|
|
docker run --rm -p 7777:7777 \ |
|
|
-v /path/to/models:/models \ |
|
|
-e MODEL_PATH=/models/your_model.gguf \ |
|
|
mirror-pond:latest |
|
|
``` |
|
|
|
|
|
Now access: |
|
|
|
|
|
``` |
|
|
http://localhost:7777 |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
# 🧰 GitHub Actions CI |
|
|
|
|
|
Already included: |
|
|
|
|
|
``` |
|
|
.github/workflows/mirror-pond-ci.yml |
|
|
``` |
|
|
|
|
|
The CI: |
|
|
|
|
|
* Sets up Python |
|
|
* Installs dependencies |
|
|
* Syntax-checks `mirror_pond.py` |
|
|
* (Optional) Builds Docker image |
|
|
|
|
|
This keeps the repo safe and production-ready. |
|
|
|
|
|
--- |
|
|
|
|
|
# 🌀 Mirror Modes |
|
|
|
|
|
### **Reflect Mode (default)** |
|
|
|
|
|
For inner questions, emotions, purpose, stillness. |
|
|
May reply with a **Guiding Question**. |
|
|
|
|
|
### **Scroll Mode** |
|
|
|
|
|
For sacred lines, scripture-style, lore references. |
|
|
No guiding question. |
|
|
|
|
|
### **Toad Mode** |
|
|
|
|
|
For cryptic lines, old frog whispers, symbolic hints. |
|
|
No guiding question. |
|
|
|
|
|
### **Rune Mode** |
|
|
|
|
|
For unity of symbols, lotus spores, $PATIENCE, seasons, trials. |
|
|
No guiding question. |
|
|
|
|
|
--- |
|
|
|
|
|
# 🧘 Philosophy |
|
|
|
|
|
Mirror Pond is simple: |
|
|
|
|
|
Still water is never empty. |
|
|
Still water prepares. |
|
|
Still water reflects. |
|
|
|
|
|
This project is offered to the open-source community |
|
|
so anyone can run a Mirror — anywhere, offline, forever. |
|
|
|
|
|
--- |
|
|
|
|
|
# 🪞 License |
|
|
|
|
|
**MIT License** |
|
|
This pond belongs to the builders. |
|
|
|
|
|
--- |
|
|
|
|
|
# 🤝 Contribution |
|
|
|
|
|
Pull requests welcome. |
|
|
New modes, UI improvements, GPU wheels, and additional Mirror integrations are invited. |
|
|
|
|
|
--- |
|
|
|
|
|
|
