Agentic Launcher

App Android in Python (KivyMD) con AI locale (GGUF via llama-cpp-python) per controllare il dispositivo tramite linguaggio naturale.

---

Struttura Progetto

TheProject/
├── main.py              # UI KivyMD (entry point)
├── ai_engine.py         # Inferenza GGUF locale
├── dispatcher.py        # Router JSON → azioni
├── android_bridge.py    # Bridge pyjnius → Java Android
├── buildozer.spec       # Configurazione build APK
├── requirements.txt     # Dipendenze desktop
├── recipes/
│   └── llama_cpp_python/
│       └── __init__.py  # Recipe Buildozer per llama-cpp
└── assets/
    └── model.gguf       # ← DA SCARICARE (vedi sotto)

---

Step 1: Scarica il Modello

Vai su Hugging Face e scarica un modello GGUF compatibile.

Consigliato (buon bilanciamento velocità/qualità su telefono):

• Gemma-3-1B GGUF — 1B parametri, ~700MB INT4
• Qwen2.5-1.5B GGUF — alternativa più veloce

# Con huggingface-hub CLI
pip install huggingface-hub
huggingface-cli download \
  lmstudio-community/gemma-3-1b-it-GGUF \
  gemma-3-1b-it-Q4_K_M.gguf \
  --local-dir ./assets/

# Rinomina in model.gguf
mv assets/gemma-3-1b-it-Q4_K_M.gguf assets/model.gguf

---

Step 2: Test su Desktop (Mac/Linux)

# Crea ambiente virtuale
python3 -m venv .venv
source .venv/bin/activate

# Installa dipendenze (CPU)
pip install -r requirements.txt

# Per GPU Metal su Mac Apple Silicon:
# CMAKE_ARGS="-DLLAMA_METAL=on" pip install llama-cpp-python

# Avvia app
python main.py

Su desktop pyjnius non è disponibile, quindi le azioni Android vengono simulate e loggate invece di essere eseguite.

---

Step 3: Build APK Android

3a. Prerequisiti (su Linux/WSL — Buildozer non funziona su macOS)

# Ubuntu/Debian
sudo apt install -y \
    python3-dev python3-pip \
    build-essential cmake \
    libvulkan-dev vulkan-tools \
    git zip unzip openjdk-17-jdk

pip install buildozer cython

3b. Build CPU (sicura, funziona su tutti i dispositivi)

buildozer android debug

3c. Build GPU Vulkan (Snapdragon 7xx/8xx, Exynos, MediaTek Dimensity)

export LLAMA_VULKAN=1
buildozer android debug

Prima della build Vulkan, verifica che il dispositivo supporti Vulkan 1.1+:

adb shell getprop ro.hardware.vulkan
# Output atteso: adreno (o mali, xclipse, ecc.)

3d. Deploy sul dispositivo

# Con disposivo USB in modalità debug collegato
buildozer android deploy run logcat

---

Permessi Richiesti

Permesso	Motivo
MODIFY_AUDIO_SETTINGS	Cambio volume
WRITE_SETTINGS	Cambio luminosità (richiede conferma utente)
QUERY_ALL_PACKAGES	Aprire app per package name
BLUETOOTH_CONNECT	Toggle Bluetooth (Android 12+)
INTERNET	Solo per download modello iniziale

WRITE_SETTINGS: Android 6+ richiede che l'utente autorizzi manualmente questa permission da Impostazioni > App > Agentic Launcher > Modifica impostazioni sistema. L'app deve reindirizzare lì con Settings.ACTION_MANAGE_WRITE_SETTINGS.

---

Comandi Esempio

Input utente	JSON generato	Azione
"abbassa il volume al 30%"	{"action":"SET_VOLUME","stream":"music","level":5}	Volume music a 5/15
"apri Spotify"	{"action":"LAUNCH_APP","package":"com.spotify.music"}	Avvia Spotify
"attiva il bluetooth"	{"action":"SET_BLUETOOTH","state":"on"}	Abilita BT
"torna alla home"	{"action":"HOME"}	Simulta tasto Home
"alza la luminosità"	{"action":"SET_BRIGHTNESS","level":200}	Luminosità a 200/255

---

GPU Vulkan vs CPU — Quando usare cosa?

Modalità	n_gpu_layers	Pro	Contro
CPU multi-thread	0	Compatibile con tutti	Più lento (~5-10 tok/s su 1B)
GPU Vulkan parziale	10-20	Buon bilanciamento	Richiede NDK Vulkan headers
GPU Vulkan full	-1	Massima velocità	Alto consumo VRAM, può crashare

Modifica N_GPU_LAYERS in main.py per trovare il giusto equilibrio per il tuo dispositivo.