diff --git a/docs/architecture_and_usage.md b/docs/architecture_and_usage.md new file mode 100644 index 0000000..0a78878 --- /dev/null +++ b/docs/architecture_and_usage.md @@ -0,0 +1,409 @@ +# MaxClaw Agent: Architettura e Guida all'Utilizzo + +## Cos'è MaxClaw Agent? + +MaxClaw Agent è un **agente AI intelligente** che può essere configurato per lavorare con diversi modelli di intelligenza artificiale (come GPT-4o di OpenAI, modelli locali con Ollama, o Claude tramite OpenRouter). In pratica, è come avere un assistente virtuale programmabile che può: + +- **Leggere e scrivere file** sul tuo computer +- **Eseguire comandi** di sistema +- **Pianificare attività complesse** scomponendole in passi più semplici +- **Delegare compiti** a sotto-agenti specializzati +- **Gestire configurazioni** in modo sicuro + +## Architettura del Sistema + +### Componenti Principali + +``` +┌─────────────────────────────────────────────────────────────┐ +│ MaxClaw Agent │ +├─────────────────────────────────────────────────────────────┤ +│ 1. Agente Principale (main.py) │ +│ - Coordina tutto il sistema │ +│ - Gestisce le conversazioni │ +│ - Carica la configurazione │ +├─────────────────────────────────────────────────────────────┤ +│ 2. Sistema di Configurazione │ +│ - config_manager.py: Gestisce le configurazioni │ +│ - config_cli.py: Interfaccia a riga di comando │ +│ - config_tui.py: Interfaccia grafica testuale │ +├─────────────────────────────────────────────────────────────┤ +│ 3. Strumenti (Tools) │ +│ - Strumenti unificati per provider │ +│ - Strumenti per Proxmox │ +│ - Strumenti per Ollama │ +├─────────────────────────────────────────────────────────────┤ +│ 4. Provider LLM │ +│ - OpenAI (GPT-4o, GPT-4o-mini, ecc.) │ +│ - Ollama (modelli locali) │ +│ - OpenRouter (Claude, altri modelli) │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Come Funziona il Flusso + +1. **L'utente scrive un messaggio** (es. "Elenca i file nella directory corrente") +2. **L'agente analizza la richiesta** e decide quali strumenti usare +3. **Esegue gli strumenti necessari** (es. ls, read_file, ecc.) +4. **Elabora i risultati** e genera una risposta +5. **Restituisce la risposta** all'utente + +## Esempi Concreti di Utilizzo + +### Esempio 1: Gestione Base dei File + +**Scenario**: Vuoi organizzare i file nella tua directory Downloads. + +**Domanda**: "Analizza i file nella mia directory Downloads e suggeriscimi come organizzarli per tipo" + +**Cosa fa l'agente**: +1. Usa lo strumento `ls` per elencare i file +2. Usa lo strumento `read_file` per leggere alcuni file +3. Analizza i tipi di file (documenti, immagini, video, ecc.) +4. Suggerisce una struttura di cartelle +5. Può anche creare le cartelle e spostare i file se autorizzato + +**Risposta dell'agente**: +``` +Ho analizzato la tua directory Downloads. Ecco cosa ho trovato: + +📁 File trovati: +- 15 documenti PDF +- 8 immagini JPG +- 3 video MP4 +- 5 file ZIP +- 2 file eseguibili + +💡 Suggerimento di organizzazione: +Downloads/ +├── Documenti/ +├── Immagini/ +├── Video/ +├── Archivi/ +└── Software/ + +Vuoi che crei questa struttura e sposti i file? +``` + +### Esempio 2: Analisi di Codice + +**Scenario**: Hai un progetto Python e vuoi trovare errori. + +**Domanda**: "Controlla se ci sono errori di sintassi nei file Python nella directory src/" + +**Cosa fa l'agente**: +1. Usa `ls` per trovare tutti i file .py +2. Usa `read_file` per leggere ogni file +3. Analizza la sintassi di ogni file +4. Segnala eventuali errori + +**Risposta dell'agente**: +``` +Ho analizzato 12 file Python nella directory src/. + +✅ File senza errori: +- main.py +- utils.py +- config.py + +❌ File con errori: +- database.py: Errore di sintassi alla riga 45 (mancano due punti) +- api.py: Indentazione errata alla riga 78 + +Vuoi che corregga questi errori automaticamente? +``` + +### Esempio 3: Gestione di Server con Proxmox + +**Scenario**: Vuoi controllare le tue macchine virtuali su Proxmox. + +**Domanda**: "Mostrami lo stato di tutte le VM nel mio cluster Proxmox" + +**Cosa fa l'agente**: +1. Usa lo strumento `proxmox_list_vms` +2. Recupera informazioni su tutte le VM +3. Formatta i dati in modo leggibile + +**Risposta dell'agente**: +``` +Ecco lo stato delle tue VM nel cluster Proxmox: + +🖥️ VM 100: web-server + - Stato: ✅ In esecuzione + - CPU: 15% + - Memoria: 2.1 GB / 4 GB + - Uptime: 5 giorni, 3 ore + +🖥️ VM 101: database-server + - Stato: ✅ In esecuzione + - CPU: 8% + - Memoria: 1.5 GB / 2 GB + - Uptime: 5 giorni, 3 ore + +🖥️ VM 102: dev-machine + - Stato: ⏸️ Sospesa + - CPU: 0% + - Memoria: 0 GB / 8 GB + +Vuoi avviare la VM 102 o vedere dettagli su una specifica VM? +``` + +### Esempio 4: Gestione Modelli AI con Ollama + +**Scenario**: Vuoi vedere quali modelli AI hai disponibili localmente. + +**Domanda**: "Quali modelli ho su Ollama? Scarica anche il modello llama2:13b" + +**Cosa fa l'agente**: +1. Usa `ollama_list_models` per vedere i modelli disponibili +2. Usa `ollama_pull_model` per scaricare il nuovo modello +3. Mostra il progresso del download + +**Risposta dell'agente**: +``` +Modelli disponibili su Ollama (http://192.168.0.50:11434): + +📦 Modelli installati: +- gemma2:9b (5.2 GB) +- llama2:7b (3.8 GB) +- mistral:7b (4.1 GB) + +⬇️ Download di llama2:13b in corso... +[██████████░░░░░░░░░░] 45% - 2.3 GB / 5.1 GB + +Il download richiederà circa 5 minuti. +Vuoi che ti avvisi quando è completato? +``` + +### Esempio 5: Creazione di uno Script Automatico + +**Scenario**: Vuoi creare uno script che faccia backup automatici. + +**Domanda**: "Crea uno script bash che faccia backup incrementali della directory /home/user/documents ogni giorno alle 2:00" + +**Cosa fa l'agente**: +1. Usa `write_file` per creare lo script +2. Usa `execute` per renderlo eseguibile +3. Fornisce istruzioni per l'automazione + +**Risposta dell'agente**: +``` +Ho creato lo script di backup: + +📁 File creati: +- backup_script.sh (script principale) +- backup_cron.txt (configurazione per cron) + +📋 Contenuto di backup_script.sh: +#!/bin/bash +# Script di backup incrementale +SOURCE="/home/user/documents" +DEST="/backup/documents" +DATE=$(date +%Y-%m-%d) +rsync -avz --delete "$SOURCE" "$DEST/$DATE/" + +🔧 Per automatizzare: +1. chmod +x backup_script.sh +2. crontab -e +3. Aggiungi: 0 2 * * * /path/to/backup_script.sh + +Vuoi che esegua il backup adesso per testarlo? +``` + +### Esempio 6: Ricerca e Analisi di Dati + +**Scenario**: Hai un file CSV con dati di vendite e vuoi analizzarlo. + +**Domanda**: "Analizza il file vendite_2024.csv e dimmi quali sono i prodotti più venduti" + +**Cosa fa l'agente**: +1. Usa `read_file` per leggere il file CSV +2. Analizza i dati con Python +3. Calcola statistiche e crea grafici + +**Risposta dell'agente**: +``` +Ho analizzato il file vendite_2024.csv (1.234 righe). + +📊 Top 5 prodotti più venduti: +1. Smartphone X - 150 unità - €75.000 +2. Laptop Pro - 120 unità - €180.000 +3. Cuffie Wireless - 200 unità - €10.000 +4. Tablet Mini - 80 unità - €32.000 +5. Smartwatch - 95 unità - €19.000 + +📈 Statistiche: +- Vendite totali: €316.000 +- Media per prodotto: €63.200 +- Mese migliore: Dicembre (€45.000) + +Ho creato un grafico in vendite_analysis.png. +Vuoi che esporti questi dati in un report PDF? +``` + +### Esempio 7: Configurazione Multi-Provider + +**Scenario**: Vuoi confrontare le risposte di diversi modelli AI. + +**Domanda**: "Confronta come GPT-4o e Claude 3.5 rispondono alla domanda 'Spiega la relatività in modo semplice'" + +**Cosa fa l'agente**: +1. Usa `ollama_set_default_model` per configurare Ollama +2. Usa `openai_set_default_model` per configurare OpenAI +3. Invia la stessa domanda a entrambi +4. Confronta le risposte + +**Risposta dell'agente**: +``` +Ho configurato i due provider e inviato la domanda. + +🤖 Risposta di GPT-4o (OpenAI): +"La relatività è come avere due orologi: uno sulla Terra e uno su un'astronave veloce. Quando l'astronave viaggia vicino alla velocità della luce, il suo orologio rallenta rispetto a quello sulla Terra. Questo perché il tempo è relativo alla velocità..." + +🤖 Risposta di Claude 3.5 (OpenRouter): +"Immagina di essere su un treno che passa vicino a un altro treno fermo. Se il tuo treno si muove, sembra che l'altro treno si stia muovendo al contrario. La relatività dice che il movimento è sempre relativo a chi osserva..." + +📊 Confronto: +- GPT-4o: Più tecnico, usa esempi pratici +- Claude 3.5: Più intuitivo, usa analogie semplici + +Vuoi che approfondisca qualche aspetto specifico? +``` + +### Esempio 8: Automazione di Task Complessi + +**Scenario**: Vuoi preparare un ambiente di sviluppo completo. + +**Domanda**: "Prepara un ambiente di sviluppo Python con virtualenv, installa le dipendenze, e configura Git" + +**Cosa fa l'agente**: +1. Usa `execute` per creare virtualenv +2. Usa `write_file` per creare requirements.txt +3. Usa `execute` per installare pacchetti +4. Configura Git con i tuoi dati + +**Risposta dell'agente**: +``` +Ho preparato l'ambiente di sviluppo: + +✅ Virtualenv creato: .venv +✅ Requirements.txt creato con: + - flask==2.3.0 + - requests==2.31.0 + - pandas==2.0.0 + - pytest==7.4.0 + +✅ Dipendenze installate (15 pacchetti) +✅ Git configurato: + - Nome: Mario Rossi + - Email: mario@example.com + - Branch predefinito: main + +📁 Struttura creata: +progetto/ +├── .venv/ +├── src/ +├── tests/ +├── requirements.txt +└── .gitignore + +Per attivare l'ambiente: source .venv/bin/activate +Vuoi che crei anche un file README.md? +``` + +## Come Iniziare + +### 1. Configurazione Base +```bash +# Configura Ollama (modello locale) +export MODEL_PROVIDER=ollama +export MODEL_NAME=gemma2:9b +export OLLAMA_BASE_URL=http://192.168.0.50:11434 + +# Avvia l'agente +python main.py +``` + +### 2. Prima Conversazione +``` +👤 Tu: Ciao, chi sei? +🤖 MaxClaw: Sono MaxClaw, un agente AI configurabile. Posso aiutarti a gestire file, eseguire comandi, analizzare dati e molto altro. Come posso aiutarti oggi? + +👤 Tu: Mostrami i file nella directory corrente +🤖 MaxClaw: [Esegue ls e mostra i file] + +👤 Tu: Crea un file di testo con "Hello World" +🤖 MaxClaw: [Crea hello.txt con il contenuto specificato] +``` + +### 3. Configurazione Avanzata +```bash +# Configurazione persistente +python config_cli.py add --name "mio-ollama" \ + --provider "ollama" \ + --model "gemma2:9b" \ + --base-url "http://192.168.0.50:11434" \ + --set-active + +# Testa la connessione +python config_cli.py test "mio-ollama" +``` + +## Best Practices + +### 1. Sicurezza +- **Non condividere mai le chiavi API** in chiaro +- **Usa la configurazione persistente** per evitare di esporre credenziali +- **Testa prima di eseguire** comandi distruttivi + +### 2. Performance +- **Usa modelli locali** (Ollama) per task semplici +- **Usa modelli cloud** (OpenAI, OpenRouter) per task complessi +- **Configura timeout** appropriati per le connessioni + +### 3. Organizzazione +- **Usa configurazioni nominate** per diversi ambienti +- **Esporta regolarmente** le configurazioni come backup +- **Documenta le tue configurazioni** personalizzate + +## Risoluzione Problemi + +### Problema: "Connessione rifiutata" +**Soluzione**: Verifica che il servizio sia in esecuzione +```bash +# Per Ollama +curl http://192.168.0.50:11434 + +# Per Proxmox +ping 192.168.0.100 +``` + +### Problema: "Modello non trovato" +**Soluzione**: Verifica che il modello sia disponibile +```bash +# Per Ollama +ollama list + +# Per OpenAI +python config_cli.py test "openai-config" +``` + +### Problema: "Permessi insufficienti" +**Soluzione**: Verifica i permessi dei file +```bash +ls -la ~/.maxclaw/ +chmod 600 ~/.maxclaw/config.json +``` + +## Prossimi Passi + +1. **Sperimenta con diversi provider**: Prova OpenAI, Ollama, OpenRouter +2. **Crea strumenti personalizzati**: Aggiungi funzionalità specifiche per il tuo ambiente +3. **Automatizza task ripetitivi**: Usa l'agente per attività quotidiane +4. **Contribuisci al progetto**: Segnala bug, suggerisci miglioramenti + +## Conclusione + +MaxClaw Agent è uno strumento potente e flessibile che può adattarsi a molteplici esigenze. Che tu voglia gestire file, analizzare dati, amministrare server o sperimentare con modelli AI, questo agente può aiutarti a automatizzare e semplificare il tuo lavoro. + +La chiave è iniziare con task semplici e gradualmente esplorare funzionalità più avanzate man mano che acquisisci familiarità con il sistema. \ No newline at end of file