Add comprehensive architecture and usage documentation in docs/
This commit is contained in:
truetype committed
1 parent
5e70e22780
commit
b17c180fbe
1 file changed
+409
@@ -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.
|
||||
Reference in new issue
Block a user