Indipendente dal provider: Funziona con OpenAI, Ollama, OpenRouter, Anthropic, Google e qualsiasi altro provider supportato da init_chat_model di LangChain
Basato su DeepAgents: Include pianificazione, accesso al filesystem, sub-agenti e gestione del contesto out of the box
Configurazione semplice: Imposta le variabili d'ambiente per scegliere il tuo provider e modello
Configurazione persistente: Gestisci e conserva le configurazioni tramite CLI o TUI
Estensibile: Aggiungi strumenti personalizzati, modifica i prompt e configura i sub-agenti secondo le tue esigenze
Strumenti unificati: Gestisci qualsiasi provider con la stessa interfaccia
Strumenti personalizzati: Include strumenti per gestire Proxmox e Ollama
Completamento shell: Supporta bash e zsh per autocompletamento dei comandi
Test completi: Suite di test per garantire la qualità del codice
Docker support: Containerizzazione per deployment facile
API REST: Server API per accesso remoto
Web UI: Interfaccia web per gestione configurazioni
Comandi integrati: Comandi speciali con prefisso "/" per gestione rapida
Monitoraggio: Sistema di logging e monitoraggio delle performance
Dashboard performance: Monitoraggio dettagliato delle performance
Sistema di plugin: Estendi le funzionalità con plugin personalizzati
Plugin inclusi: File tools, System utils, Example plugin
Supporto multilingue: Interfaccia in italiano e inglese

Installazione

Installazione Locale

Clona questo repository
Installa i pacchetti richiesti:
```
pip install -r requirements.txt
```

Installazione con Docker

# Build dell'immagine
docker build -t maxclaw-agent .

# Esecuzione con Docker Compose
docker-compose up -d

# Esecuzione diretta
docker run -it --rm \
  -e MODEL_PROVIDER=ollama \
  -e MODEL_NAME=gemma2:9b \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  maxclaw-agent

Configurazione del Completamento Shell

Bash

# Aggiungi al tuo ~/.bashrc o ~/.bash_profile
source /path/to/maxclaw_agent/completions/maxclaw.bash

Zsh

# Aggiungi al tuo ~/.zshrc
fpath=(/path/to/maxclaw_agent/completions $fpath)
autoload -Uz compinit && compinit

Configurazione

Puoi configurare MaxClaw Agent in diversi modi:

1. Variabili d'ambiente (Avvio Rapido)

Imposta le seguenti variabili d'ambiente per configurare il tuo provider LLM:

MODEL_PROVIDER: Il provider da utilizzare (es. "openai", "ollama", "openrouter", "anthropic", "google")
MODEL_NAME: Il nome specifico del modello (es. "gpt-4o", "gemma2:9b", "claude-3-5-sonnet")
Variabili specifiche per il provider:
- Per OpenAI: OPENAI_API_KEY
- Per Ollama: OLLAMA_BASE_URL (predefinito a http://localhost:11434)
- Per OpenRouter: OPENROUTER_API_KEY e opzionalmente OPENROUTER_BASE_URL (predefinito a https://openrouter.ai/api/v1)
- Per Anthropic: ANTHROPIC_API_KEY
- Per Google: GOOGLE_API_KEY

Esempi di Configurazione

OpenAI

export MODEL_PROVIDER="openai"
export MODEL_NAME="gpt-4o"
export OPENAI_API_KEY="la-tua-chiave-api-openai"

Ollama (locale)

export MODEL_PROVIDER="ollama"
export MODEL_NAME="gemma2:9b"
export OLLAMA_BASE_URL="http://192.168.0.50:11434"

OpenRouter

export MODEL_PROVIDER="openrouter"
export MODEL_NAME="anthropic/claude-3.5-sonnet"
export OPENROUTER_API_KEY="la-tua-chiave-api-openrouter"

Anthropic

export MODEL_PROVIDER="anthropic"
export MODEL_NAME="claude-3-5-sonnet-20241022"
export ANTHROPIC_API_KEY="la-tua-chiave-api-anthropic"

Google

export MODEL_PROVIDER="google"
export MODEL_NAME="gemini-1.5-pro"
export GOOGLE_API_KEY="la-tua-chiave-api-google"

2. Configurazione Persistente (Consigliato)

Utilizza la CLI, la TUI o l'interfaccia web per gestire le configurazioni che persistono tra le sessioni.

Utilizzo della CLI

# Elenca le configurazioni
python config_cli.py list

# Cerca configurazioni
python config_cli.py search "ollama"

# Aggiungi una nuova configurazione interattivamente
python config_cli.py add

# Aggiungi una nuova configurazione in modo non interattivo
python config_cli.py add --name "mio-ollama" --provider "ollama" --model "gemma2:9b" --base-url "http://192.168.0.50:11434" --set-active

# Rimuovi una configurazione
python config_cli.py remove "mio-ollama"

# Imposta la configurazione attiva
python config_cli.py set-active "mio-ollama"

# Mostra la configurazione attiva
python config_cli.py active

# Testa la connessione a una configurazione
python config_cli.py test "mio-ollama"

# Esporta configurazioni in JSON
python config_cli.py export --format json --output backup

# Importa configurazioni da JSON
python config_cli.py import backup.json

Utilizzo della TUI

# Avvia l'Interfaccia Utente Testuale
python config_tui.py

Naviga usando le frecce direzionali, premi Invio per selezionare e 'q' per uscire.

La TUI ora include:

Ricerca e filtro delle configurazioni
Esportazione/importazione in JSON/YAML
Test di connessione diretto
Navigazione migliorata

Utilizzo dell'Interfaccia Web

Avvia il server API e accedi all'interfaccia web:

# Avvia il server API
python api_server.py

# Accedi all'interfaccia web
# http://localhost:8000

L'interfaccia web include:

Gestione completa delle configurazioni
Chat con l'agente
Monitoraggio dello stato del sistema
Test di connessione

Utilizzo

Utilizzo Locale

Esegui l'agente:

python main.py

Comandi Speciali (prefissati con "/")

Quando interagisci con l'agente, puoi usare comandi speciali preceduti da "/" per gestire il sistema senza confonderli con i messaggi di chat:

/help, /?           - Mostra i comandi disponibili
/status             - Mostra lo stato del sistema
/config list        - Elenca tutte le configurazioni
/config active      - Mostra la configurazione attiva
/config test        - Testa la connessione alla configurazione attiva
/config use <name>  - Cambia la configurazione attiva
/models             - Elenca i modelli disponibili per il provider attivo
/clear              - Pulisce lo schermo
/plugins            - Elenca i plugin disponibili
/language           - Cambia la lingua dell'interfaccia
/performance        - Mostra il report delle performance
/exit, /quit        - Esci dall'agente

Esempio di sessione:

👤 You: /status
📊 Stato del Sistema:
Provider: ollama
Modello: gemma2:9b
Ollama URL: http://192.168.0.50:11434

👤 You: /config list
📋 Configurazioni disponibili:
✅ mio-ollama: ollama - gemma2:9b
   openai-gpt4: openai - gpt-4o

👤 You: Ciao, chi sei?
🤖 MaxClaw: Ciao! Sono MaxClaw, un agente AI configurabile...

👤 You: Elenca i file nella directory corrente
🤖 MaxClaw: [Esegue ls e mostra i file]

👤 You: /performance
📊 Performance Report (Last 24 hours)
==================================================

📈 Request Statistics:
  Total Requests: 150
  Total Errors: 2
  Error Rate: 1.33%
  Avg Response Time: 0.245s

👤 You: /exit
👋 Goodbye!

Utilizzo con Docker

# Avvia con Docker Compose
docker-compose up -d

# Accedi al terminale
docker exec -it maxclaw-agent python main.py

# Oppure esegui direttamente
docker run -it --rm maxclaw-agent

Utilizzo dell'API REST

Avvia il server API:

python api_server.py

L'API sarà disponibile su http://localhost:8000

Endpoint API Disponibili

GET /: Interfaccia web
GET /health: Health check
POST /chat: Chat con l'agente
GET /configurations: Elenca tutte le configurazioni
POST /configurations: Aggiungi una configurazione
DELETE /configurations/{name}: Rimuovi una configurazione
POST /configurations/{name}/activate: Attiva una configurazione
GET /configurations/active: Mostra la configurazione attiva
POST /configurations/{name}/test: Testa una configurazione
GET /providers: Elenca i provider disponibili

Esempio di Utilizzo dell'API

# Chat con l'agente
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Ciao, chi sei?"}'

# Elenca configurazioni
curl http://localhost:8000/configurations

# Aggiungi una configurazione
curl -X POST http://localhost:8000/configurations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mio-ollama",
    "provider": "ollama",
    "model_name": "gemma2:9b",
    "base_url": "http://192.168.0.50:11434",
    "set_active": true
  }'

Strumenti Unificati per Provider

MaxClaw Agent ora fornisce un'interfaccia unificata per gestire qualsiasi provider LLM. Una volta configurato un provider, puoi usare gli stessi comandi per tutti.

Provider Supportati

MaxClaw Agent supporta i seguenti provider:

Ollama - Modelli locali
OpenAI - GPT-4o, GPT-4o-mini, GPT-4-turbo, ecc.
OpenRouter - Accesso a centinaia di modelli
Anthropic - Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku, ecc.
Google - Gemini 1.5 Pro, Gemini 1.5 Flash, ecc.

Strumenti Disponibili per Ogni Provider

Per ogni provider configurato, hai accesso a:

{provider}_list_models: Elenca tutti i modelli disponibili
{provider}_model_info: Ottieni informazioni dettagliate su un modello
{provider}_test_connection: Testa la connessione al provider
{provider}_get_default_model: Mostra il modello predefinito
{provider}_set_default_model: Imposta un modello predefinito
{provider}_info: Mostra informazioni sulla configurazione del provider

Esempi di Utilizzo

# Con Ollama configurato:
"List available Ollama models"
"Test connection to Ollama"
"What's the default model for Ollama?"

# Con OpenAI configurato:
"List available OpenAI models"
"Test connection to OpenAI"
"Show me OpenAI configuration"

# Con OpenRouter configurato:
"List available OpenRouter models"
"Test connection to OpenRouter"
"Show me OpenRouter configuration"

# Con Anthropic configurato:
"List available Anthropic models"
"Test connection to Anthropic"
"Show me Anthropic configuration"

# Con Google configurato:
"List available Google models"
"Test connection to Google"
"Show me Google configuration"

Configurazione Automatica

Gli strumenti vengono caricati automaticamente in base alle variabili d'ambiente configurate:

# Se hai configurato Ollama:
export OLLAMA_BASE_URL="http://192.168.0.50:11434"
# → Verranno caricati automaticamente gli strumenti Ollama

# Se hai configurato OpenAI:
export OPENAI_API_KEY="sk-..."
# → Verranno caricati automaticamente gli strumenti OpenAI

# Se hai configurato OpenRouter:
export OPENROUTER_API_KEY="sk-or-..."
# → Verranno caricati automaticamente gli strumenti OpenRouter

# Se hai configurato Anthropic:
export ANTHROPIC_API_KEY="sk-ant-..."
# → Verranno caricati automaticamente gli strumenti Anthropic

# Se hai configurato Google:
export GOOGLE_API_KEY="AIza..."
# → Verranno caricati automaticamente gli strumenti Google

Strumenti Personalizzati

MaxClaw Agent include anche strumenti personalizzati per gestire il tuo ambiente:

Strumenti Proxmox

Configura le variabili d'ambiente per abilitare gli strumenti Proxmox:

export PROXMOX_HOST="192.168.0.100"
export PROXMOX_USER="root"
export PROXMOX_PASSWORD="tua-password"  # oppure
export PROXMOX_TOKEN="tuo-api-token"

Strumenti disponibili:

proxmox_list_vms: Elenca tutte le VM nel cluster
proxmox_vm_status: Ottieni lo stato di una VM specifica
proxmox_start_vm: Avvia una VM
proxmox_stop_vm: Ferma una VM
proxmox_restart_vm: Riavvia una VM
proxmox_create_snapshot: Crea uno snapshot
proxmox_list_snapshots: Elenca gli snapshot di una VM

Strumenti Ollama (Legacy)

Gli strumenti Ollama specifici sono ancora disponibili per retrocompatibilità:

ollama_list_models: Elenca tutti i modelli disponibili
ollama_model_info: Ottieni informazioni dettagliate su un modello
ollama_pull_model: Scarica un nuovo modello
ollama_delete_model: Elimina un modello
ollama_generate: Genera una completion
ollama_status: Controlla se Ollama è in esecuzione
ollama_running_models: Mostra i modelli attualmente in esecuzione

Sistema di Plugin

MaxClaw Agent include un sistema di plugin per estendere le funzionalità.

Plugin Inclusi

Example Plugin: Plugin di esempio che dimostra come creare plugin
- Strumenti: example_hello, example_echo, example_math
- Comandi: /example, /hello, /math
File Tools Plugin: Strumenti aggiuntivi per la gestione dei file
- Strumenti: file_find, file_size, file_copy, file_move, file_delete, file_info, dir_list, dir_create
- Comandi: /find, /size, /copy, /move, /delete, /info, /dir, /mkdir
System Utils Plugin: Strumenti per informazioni di sistema
- Strumenti: system_info, system_uptime, system_ip, system_hostname, system_platform, system_users, system_processes, system_disk_usage
- Comandi: /sysinfo, /uptime, /ip, /hostname, /platform, /users, /ps, /df

Creare un Plugin

Per creare un plugin, crea un file Python nella directory plugins/:

from plugins.base import BasePlugin
from langchain.tools import Tool

class MyPlugin(BasePlugin):
    def __init__(self):
        super().__init__(
            name="my_plugin",
            version="1.0.0",
            description="My custom plugin"
        )
    
    def get_tools(self):
        return [
            Tool(
                name="my_tool",
                func=self.my_tool_func,
                description="My custom tool"
            )
        ]
    
    def get_commands(self):
        return {
            "/mycommand": self.my_command_func
        }
    
    def my_tool_func(self):
        return "Hello from my plugin!"
    
    def my_command_func(self, args=None):
        return "My command executed!"

Gestire i Plugin

# Elenca i plugin disponibili
/plugins

# Carica tutti i plugin
python -c "from plugins.manager import plugin_manager; plugin_manager.load_all_plugins()"

# Usa un tool di un plugin
"Use my_tool from my_plugin"

# Usa un comando di un plugin
/mycommand

Esempi di Utilizzo dei Plugin

File Tools Plugin

# Trova file per nome
"Find all .py files in the current directory"
# oppure
/find *.py

# Ottieni dimensione di un file
"Get the size of main.py"
# oppure
/size main.py

# Copia un file
"Copy config.json to backup_config.json"
# oppure
/copy config.json backup_config.json

# Elenca directory con dettagli
"List files in the current directory with details"
# oppure
/dir

System Utils Plugin

# Ottieni informazioni di sistema
"Show system information"
# oppure
/sysinfo

# Ottieni uptime del sistema
"How long has the system been running?"
# oppure
/uptime

# Ottieni indirizzo IP
"What is my IP address?"
# oppure
/ip

# Ottieni informazioni sulla piattaforma
"What platform am I running on?"
# oppure
/platform

# Elenca utenti loggati
"Who is logged in?"
# oppure
/users

# Elenca processi in esecuzione
"Show running processes"
# oppure
/ps

# Mostra utilizzo disco
"Show disk usage"
# oppure
/df

Supporto Multilingue

MaxClaw Agent supporta più lingue per l'interfaccia utente.

Lingue Disponibili

Italiano (it) - Predefinito
Inglese (en)

Cambiare Lingua

# Usa la variabile d'ambiente
export MAXCLAW_LANGUAGE=en

# Oppure usa il comando /language
/language en

Aggiungere una Nuova Lingua

Per aggiungere una nuova lingua:

Crea un file JSON nella directory i18n/ (es. fr.json)
Copia la struttura da en.json o it.json
Traduci tutti i valori
L'agente rileverà automaticamente la nuova lingua

Monitoraggio Performance

MaxClaw Agent include un sistema avanzato di monitoraggio delle performance.

Dashboard Performance

Il dashboard raccoglie e analizza:

Richieste API e tempi di risposta
Utilizzo degli strumenti
Utilizzo dei provider
Statistiche di sistema (CPU, memoria, disco)
Errori e tassi di successo

Visualizzare le Performance

# Usa il comando /performance
/performance

# Oppure esegui lo script direttamente
python dashboard.py

Report Disponibili

Il report include:

Statistiche richieste (totale, errori, tasso di errore)
Distribuzione codici di stato
Endpoint più utilizzati
Utilizzo degli strumenti (chiamate, tasso di successo, durata media)
Utilizzo dei provider
Statistiche di sistema

Configurazione

I dati di performance vengono salvati in ~/.maxclaw/performance/ e includono:

Richieste API
Errori
Tempi di risposta
Utilizzo strumenti
Utilizzo provider
Statistiche di sistema

Test

Esegui la suite di test:

# Esegui tutti i test
pytest tests/

# Esegui test specifici
pytest tests/test_config_manager.py
pytest tests/test_provider_tools.py

# Esegui con output verboso
pytest tests/ -v

Docker

Build dell'Immagine

docker build -t maxclaw-agent .

Esecuzione con Docker Compose

# Avvia tutti i servizi
docker-compose up -d

# Visualizza i log
docker-compose logs -f

# Ferma i servizi
docker-compose down

Variabili d'Ambiente Docker

Puoi configurare il container Docker con le seguenti variabili d'ambiente:

docker run -it --rm \
  -e MODEL_PROVIDER=ollama \
  -e MODEL_NAME=gemma2:9b \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -e OPENAI_API_KEY=sk-... \
  -e OPENROUTER_API_KEY=sk-or-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e GOOGLE_API_KEY=AIza... \
  -e PROXMOX_HOST=192.168.0.100 \
  -e PROXMOX_USER=root \
  -e PROXMOX_PASSWORD=password \
  -e MAXCLAW_LANGUAGE=it \
  maxclaw-agent

Personalizzazione

Per personalizzare l'agente, modifica main.py:

Cambia il prompt di sistema predefinito in create_maxclaw_agent
Aggiungi strumenti personalizzati alla chiamata create_deep_agent
Configura i sub-agenti o altre funzionalità di DeepAgents
Crea plugin per estendere le funzionalità

Monitoraggio e Logging

MaxClaw Agent include un sistema di monitoraggio e logging:

Log dettagliati: Tutte le azioni vengono registrate in ~/.maxclaw/logs/
Statistiche di sistema: Monitoraggio di uptime, richieste, errori
Metriche di performance: Tempi di risposta, utilizzo cache
Report di stato: Visualizzazione completa dello stato del sistema
Dashboard performance: Monitoraggio avanzato delle performance

Sicurezza

MaxClaw Agent implementa misure di sicurezza avanzate:

Crittografia a riposo: Tutte le informazioni sensibili (chiavi API) sono crittografate usando la crittografia simmetrica Fernet
Permessi di file sicuri: La directory di configurazione e i file sono impostati con accesso solo al proprietario (700 per le directory, 600 per i file)
Gestione automatica delle chiavi: Le chiavi di crittografia vengono generate e memorizzate automaticamente in modo sicuro
Validazione completa: Tutte le configurazioni vengono validate prima del salvataggio per prevenire errori

Licenza

MIT

Contribuire

I contributi sono i benvenuti! Sentiti libero di aprire issue o inviare pull request.

Contatti

Per domande o supporto, apri una issue nel repository.