truetype/langcode_agent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive architecture and usage documentation in docs/

Browse Source
This commit is contained in:
truetype committed 2026-03-20 18:07:02 +01:00
1 parent 5e70e22780
commit b17c180fbe
1 file changed
+409
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture_and_usage.md
+409
View File
@@ -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.