Skip to content

Commit 2fb8c58

Browse files
cloudcover95cloudcover95
committed
Deploy: v2.0-Sovereign | Monolithic GUI Hub, LLM Auto-Fetch & Wheel Packaging
1 parent 7c15472 commit 2fb8c58

16 files changed

Lines changed: 2080 additions & 1015 deletions

‎.github/workflows/build-release.yml‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ on:
33
push:
44
tags:
55
- 'v*' # Triggers on v1.0, v1.1, etc.
6+
workflow_dispatch: {}
67

78
jobs:
89
build_and_release:
@@ -12,16 +13,29 @@ jobs:
1213
steps:
1314
- uses: actions/checkout@v4
1415

15-
- name: Install PlatformIO
16-
run: pip install -U platformio
16+
- name: Set up Python
17+
uses: actions/setup-python@v5
18+
with:
19+
python-version: '3.11'
20+
21+
- name: Install PlatformIO and build tools
22+
run: |
23+
python -m pip install --upgrade pip
24+
pip install -U platformio build
1725
1826
- name: Compile Sovereign Firmware
1927
run: pio run -e micro
20-
28+
29+
- name: Build Python SDK package
30+
run: |
31+
python -m build --sdist --wheel
32+
2133
- name: Create GitHub Release
2234
uses: softprops/action-gh-release@v1
2335
with:
24-
files: .pio/build/micro/firmware.hex
36+
files: |
37+
.pio/build/micro/firmware.hex
38+
dist/*
2539
body: "Sovereign Assistive HID v1.1 | Liquid Glass UI | PoE Cursor Scaling"
2640
env:
2741
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.pio/build/micro/.sconsign312.dblite‎

0 Bytes
Binary file not shown.

‎.pio/build/micro/firmware.elf‎

1.2 KB
Binary file not shown.

‎.pio/build/micro/firmware.hex‎

Lines changed: 970 additions & 909 deletions
Large diffs are not rendered by default.

‎.pio/build/micro/src/main.cpp.o‎

1.57 KB
Binary file not shown.

‎LLM_SETUP.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
# Crispy Mouse - Sovereign Predictor Setup Guide
2+
3+
## Overview
4+
5+
The Crispy Mouse SDK includes **Sovereign Predictor** — an ultra-optimized local LLM inference engine powered by **Phi-3 Mini** (1.4B parameters). This enables on-device word prediction without requiring cloud services or GPUs.
6+
7+
### Features
8+
9+
✓ **Phi-3 Mini (1.4B)** - Smallest quantized LLM with high quality
10+
✓ **512 Context Window** - Ultra-fast inference (~100ms)
11+
✓ **Thread Cancellation** - Kill old predictions instantly when user types
12+
✓ **Deterministic Output** - Temperature 0.2 for consistent, logical completions
13+
✓ **CPU-Optimized** - Runs on any Windows 11 machine
14+
✓ **3-Word Predictions** - Engineered prompt for discrete options
15+
16+
---
17+
18+
## Setup Instructions
19+
20+
### 1. Install Dependencies
21+
22+
Run `setup_local.bat` (Windows 11):
23+
```batch
24+
setup_local.bat
25+
```
26+
27+
This will install:
28+
- `llama-cpp-python` - Core inference engine
29+
- `pyserial`, `pyautogui`, `tobii-research` - Existing dependencies
30+
31+
### 2. Download Phi-3 Mini Model
32+
33+
You need a quantized `.gguf` model file. **Recommended: Phi-3 Mini (1.4B)**
34+
35+
```
36+
Model: phi-3-mini-4k-instruct-q4.gguf
37+
Source: https://huggingface.co/TheBloke/phi-3-mini-4k-instruct-GGUF
38+
Size: ~2.3GB
39+
Type: Q4 quantization (excellent quality/speed tradeoff)
40+
```
41+
42+
**Alternative Models:**
43+
44+
| Model | Size | Speed | Quality | Recommended |
45+
|-------|------|-------|---------|------------|
46+
| TinyLlama-1.1B-Q4 | 0.4GB | ⚡⚡⚡ | ⭐⭐ | Fast testing |
47+
| Phi-3-Mini-Q4 | 2.3GB | ⚡⚡ | ⭐⭐⭐⭐⭐ | **Best choice** |
48+
| Mistral-7B-Q4 | 4.2GB | ⚡ | ⭐⭐⭐⭐ | High quality |
49+
50+
### 3. Create Models Directory & Place File
51+
52+
```powershell
53+
# PowerShell (Windows 11)
54+
mkdir models
55+
cd models
56+
57+
# Download phi-3-mini-4k-instruct-q4.gguf from HuggingFace
58+
# Place file as: models/phi-3-mini-4k-instruct-q4.gguf
59+
```
60+
61+
### 4. Launch Keyboard with Predictions
62+
63+
```powershell
64+
# Activate environment
65+
.venv\Scripts\activate
66+
67+
# Run with Sovereign Predictor
68+
python crispy_keyboard.py
69+
```
70+
71+
The keyboard will:
72+
1. Load Phi-3 Mini in foreground (quick with 512 ctx window)
73+
2. Display "[ Loading... ]" briefly
74+
3. Show "[ Ready ]" when predictions are active
75+
4. Display word suggestions as you type
76+
77+
---
78+
79+
## Usage
80+
81+
### Prediction Buttons
82+
83+
As you type on the virtual keyboard:
84+
85+
```
86+
[ hello ] [ world ] [ everyone ]
87+
QWERTY Keyboard
88+
```
89+
90+
Click any button to inject that word + space into the active window.
91+
92+
### How It Works
93+
94+
```
95+
User types: "hel"
96+
↓
97+
Keyboard buffers "hel"
98+
↓
99+
request_completion("hel") called
100+
↓
101+
Old predictions killed (thread cancellation)
102+
↓
103+
New inference spawned in background thread
104+
↓
105+
Phi-3 Mini generates: "hello, help, helmet"
106+
↓
107+
UI updates buttons (NO LAG)
108+
↓
109+
User clicks "hello" → text injected
110+
```
111+
112+
### Performance Tips
113+
114+
**Ultra-Fast Predictions:**
115+
- Phi-3 Mini with 512 context = ~100-150ms per prediction
116+
- Thread cancellation prevents wasted computation
117+
- Low temperature (0.2) avoids random tokens
118+
- n_threads should match your CPU core count
119+
120+
**Better Quality:**
121+
- Use Q5 quantization instead of Q4 (~3GB)
122+
- Increase max_tokens to 20 (slower but longer words)
123+
- Lower temperature further (0.1) for safety
124+
125+
---
126+
127+
## Architecture
128+
129+
### SovereignPredictor Class
130+
131+
```python
132+
# Initialize
133+
predictor = SovereignPredictor(
134+
model_path="./models/phi-3-mini-4k-instruct-q4.gguf",
135+
n_threads=6 # Match your CPU cores
136+
)
137+
138+
# Request predictions (kills old threads)
139+
predictor.request_completion(
140+
context_buffer="hello w",
141+
callback=update_ui_buttons
142+
)
143+
```
144+
145+
### Key Features
146+
147+
**Thread Cancellation:**
148+
```python
149+
# If user types "he" → "hel" → "hell" very quickly
150+
# Only the LAST request generates predictions
151+
# Previous threads are killed via cancel_flag
152+
if self.current_task and self.current_task.is_alive():
153+
self.cancel_flag.set()
154+
self.current_task.join(timeout=0.1)
155+
```
156+
157+
**Engineered Prompt:**
158+
```python
159+
prompt = "Complete this text naturally. Reply ONLY with 3 single-word options separated by commas.\nText: hello w"
160+
# Forces output like: "world, window, whisper"
161+
```
162+
163+
**Low Temperature:**
164+
```python
165+
temperature=0.2 # Deterministic, logical completions
166+
# Not 0.7 which could produce: "world, xyzzzzz, pizza"
167+
```
168+
169+
---
170+
171+
## Customization
172+
173+
### Adjust CPU Threads
174+
175+
Edit `crispy_keyboard.py`:
176+
```python
177+
self.predictor = initialize_predictor(
178+
model_path="./models/phi-3-mini-4k-instruct-q4.gguf",
179+
n_threads=8 # Change based on your CPU
180+
)
181+
```
182+
183+
**CPU Core Count Reference:**
184+
- Dual-core (16-bit CPU): `n_threads=2`
185+
- Quad-core (i5): `n_threads=4`
186+
- 6-core (R5 5600X): `n_threads=6`
187+
- 8-core (R7): `n_threads=8`
188+
189+
### Change Model Path
190+
191+
Edit `crispy_keyboard.py`:
192+
```python
193+
self.predictor = initialize_predictor(
194+
model_path="./models/my-mistral-model.gguf",
195+
n_threads=6
196+
)
197+
```
198+
199+
### Tweak Inference Parameters
200+
201+
Edit `crispy_llm.py`:
202+
```python
203+
def _generate_predictions(self, context_buffer, callback):
204+
# Adjust these:
205+
response = self.llm(
206+
prompt,
207+
max_tokens=15, # Longer completions (slower)
208+
temperature=0.2, # Lower = more consistent
209+
stop=["\n", ".", "!"],
210+
)
211+
```
212+
213+
---
214+
215+
## Troubleshooting
216+
217+
### "Model not found"
218+
- Check `models/phi-3-mini-4k-instruct-q4.gguf` exists
219+
- Verify file path (should be relative to project root)
220+
- Confirm file downloaded completely (2.3GB)
221+
222+
### Predictions are slow (>500ms)
223+
- First prediction is loaded + inference (2-3s normal)
224+
- Subsequent predictions should be <200ms
225+
- Reduce `n_threads` if CPU throttling
226+
- Use smaller model (TinyLlama) for testing
227+
228+
### High CPU usage
229+
- Phi-3 Mini uses ~1-2 cores during inference
230+
- Other threads are killed (not accumulating)
231+
- Normal behavior — predictions complete quickly
232+
- Close other apps if needed
233+
234+
### Keyboard won't start
235+
- Check Python version: `python --version` (need 3.8+)
236+
- Verify llama-cpp-python installed: `pip list`
237+
- Try running from project directory: `cd /workspaces/crispy-mouse`
238+
239+
### Nonsensical predictions
240+
- Temperature too high (change 0.2 → 0.1)
241+
- Model too small (upgrade to Phi-3 Standard or Mistral)
242+
- Prompt context needs more examples
243+
244+
---
245+
246+
## Files Modified
247+
248+
```
249+
crispy-mouse/
250+
├── crispy_llm.py # SovereignPredictor class
251+
├── crispy_keyboard.py # Integration + callbacks
252+
├── models/
253+
│ └── phi-3-mini-4k-instruct-q4.gguf # Downloaded model
254+
├── setup_local.bat # Installation script
255+
├── requirements.txt # llama-cpp-python
256+
└── LLM_SETUP.md # This guide
257+
```
258+
259+
---
260+
261+
## References
262+
263+
- **Llama.cpp**: https://github.com/ggerganov/llama.cpp
264+
- **Llama-cpp-python**: https://github.com/abetlen/llama-cpp-python
265+
- **Phi-3 Models**: https://huggingface.co/microsoft/Phi-3-mini-4k-instruct-gguf
266+
- **TheBloke GGUF**: https://huggingface.co/TheBloke (quantized models)
267+
268+
---
269+
270+
**Last Updated:** March 28, 2026
271+
**Version:** Crispy Mouse v1.1 Sovereign Release
272+
**Predictor:** SovereignPredictor (Phi-3 Mini Optimized)

‎README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,31 @@
1+
## 🚀 Sovereign Deployment (End Users)
2+
1. **Download:** Go to the [Releases](https://github.com/cloudcover95/crispy-mouse/releases) tab and download `firmware.hex`.
3+
2. **Setup:** Double-click `setup_local.bat` on your Windows 11 machine to inject the Tobii/HID driver manifold.
4+
3. **Flash:** Use **XLoader** (Windows) to upload the `firmware.hex` to your ATmega32U4.
5+
4. **Initialize:** Run `python crispy_calibrate.py` to sync your eyes to the liquid glass interface.
6+
7+
🚀 The Sovereign Stack Trace
8+
9+
JuniorCloud LLC | Crispy Mouse v1.1-Sovereign
10+
11+
Hardware: ATmega32U4 (HID) + MPU-6050 (IMU) + Analog 0-40KPa (Pneumatic)
12+
Middleware: Python 3.11 + pyserial + pyautogui + Windows 11 User32 API
13+
Optical: Tobii Eye Tracker 5 + tobii-research SDK (Macro-Gaze Fusion)
14+
AI/Logic: Gemini 3 Flash (Google) x JuniorCloud Iteration Protocol (Block 2)
15+
Deployment: Edge-Native / Docker-SDK / local-zsh / No-Cloud Dependency
16+
17+
🔧 Full Stack Architecture Outline (The Summary)
18+
19+
L1 (Physical): MPU-6050 Gyro + Pressure Transducer + Tobii IR Optical Stream.
20+
21+
L2 (Firmware): 100Hz EMA Filter Matrix + Pneumatic State Machine (Arduino C++).
22+
23+
L3 (Hub): Windows 11 Python Manifold + Saccade-Warp Logic + Commandstroke Binds.
24+
25+
L4 (UI): Liquid Glass "White Fog" Alpha-Interface (tkinter).
26+
27+
#JuniorCloudLLC #Gemini3Flash #SovereignSDK #AssistiveHID #SensorFusion #LockedInRecovery #EdgeCompute #MPU6050 #TobiiResearch
28+
#old setups/txt below:
129
# crispy-mouse
230
to run: local (make flash) codespace webbrowser (make build)*also see below for setup
331
personal computer type and click onscreen keyboard "SUP mouse" with dampening variables, control pressure sensitivity, sequenced input commands + windows key "keybind" ______________________________________________________

‎config.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"model_choice": "phi-3-mini",
3+
"latency_alpha": 0.15,
4+
"sensitivity": 2.2,
5+
"pressure_threshold": 550,
6+
"saccade_warp_threshold": 250,
7+
"ui_alpha": 0.70,
8+
"cursor_scale_force": true,
9+
"commands": {
10+
"TOP_LEFT": ["alt", "tab"],
11+
"TOP_RIGHT": ["win", "d"],
12+
"BOTTOM_LEFT": ["esc"],
13+
"BOTTOM_RIGHT": ["win", "s"]
14+
}
15+
}

0 commit comments

Comments
 (0)