Indipendente dal provider: Funziona con OpenAI, Ollama, OpenRouter 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

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")
MODEL_NAME: Il nome specifico del modello (es. "gpt-4o", "gemma2:9b")
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)

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"

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

Puoi quindi interagire con l'agente nel terminale. Digita 'exit' per uscire.

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.

Strumenti Disponibili per Ogni Provider

Per ogni provider configurato (Ollama, OpenAI, OpenRouter), 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"

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

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

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 PROXMOX_HOST=192.168.0.100 \
  -e PROXMOX_USER=root \
  -e PROXMOX_PASSWORD=password \
  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

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.