LangCode Agent

Un agente configurabile basato su DeepAgents che supporta più provider LLM.

Caratteristiche

• 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 responsive: Interfaccia web per gestione configurazioni ottimizzata per mobile e desktop
• Dashboard monitoraggio: Monitoraggio in tempo reale del sistema con supporto multilingue
• Marketplace plugin: Scopri e installa plugin dal marketplace
• Analytics avanzate: Analisi dettagliate dell'uso e raccomandazioni
• Comandi integrati: Comandi speciali con prefisso "/" per gestione rapida
• MCP Integration: Connect to MCP servers for external services and tools
• Skill Management: Discover, install, and manage agent skills from skills.sh registry
• Memory Enhancement: Sistema di memoria persistente per fatti, preferenze e cronologia conversazioni
• Planning Enhancement: Pianificazione avanzata dei task con dipendenze, tracciamento progresso e monitoraggio stato
• Monitoraggio: Sistema di logging e monitoraggio delle performance
• Dashboard performance: Monitoraggio dettagliato delle performance
• Ottimizzazioni performance: Caching, connection pooling, lazy loading
• Sistema di plugin: Estendi le funzionalità con plugin personalizzati
• Plugin inclusi: File tools, System utils, Example plugin
• Supporto multilingue: Interfaccia in italiano e inglese per CLI, dashboard e web UI
• Design responsive: Interfacce web ottimizzate per dispositivi mobili e desktop

Installazione

Installazione Locale

1. Clona questo repository
2. Installa i pacchetti richiesti:

   pip install -r requirements.txt
   

Installazione con Docker

# Build dell'immagine
docker build -t langcode-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 \
  langcode-agent

Configurazione del Completamento Shell

Bash

# Aggiungi al tuo ~/.bashrc o ~/.bash_profile
source /path/to/langcode_agent/completions/langcode.bash

Zsh

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

Configurazione

Puoi configurare LangCode 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

# Accedi alla dashboard di monitoraggio
# http://localhost:8000/monitoring

# Accedi al marketplace dei plugin
# http://localhost:8000/marketplace

L'interfaccia web include:

• Gestione completa delle configurazioni
• Chat con l'agente
• Monitoraggio dello stato del sistema
• Test di connessione
• Dashboard di monitoraggio in tempo reale con supporto multilingue
• Design responsive: Ottimizzata per dispositivi mobili e desktop
• Marketplace plugin: Scopri e installa plugin dal marketplace

Utilizzo

CLI Unificata (langcode)

Tutte le funzionalità sono accessibili tramite un unico comando langcode:

# Avvia l'agent (chat interattiva)
langcode
langcode chat

# Avvia web server
langcode server
langcode server --port 3000

# Gestione configurazioni
langcode config list                    # Lista configurazioni
langcode config add -n ollama -p ollama -m gemma2:9b -u http://192.168.0.50:11434
langcode config use ollama              # Attiva configurazione
langcode config active                  # Mostra configurazione attiva
langcode config test                    # Testa connessione
langcode config export -f json -o backup
langcode config import backup.json
langcode config search ollama           # Cerca configurazioni

# TUI interattiva
langcode tui

# Analytics e monitoraggio
langcode analytics                      # Riepilogo rapido
langcode analytics --report             # Report completo
langcode dashboard                      # Dashboard performance

# Skills management
langcode skills list                    # Lista skills installate
langcode skills search "coding"         # Cerca skills
langcode skills install "skill-name"    # Installa skill
langcode skills details "skill-name"    # Dettagli skill

# Memory
langcode memory remember "fact"         # Ricorda un fatto
langcode memory recall "query"          # Cerca fatti
langcode memory preference set k v      # Imposta preferenza
langcode memory stats                   # Statistiche

# Planning
langcode plan create "name" "t1;t2"     # Crea piano
langcode plan list                      # Lista piani
langcode plan progress plan_id           # Progresso piano

# Info
langcode version
langcode --help

Utilizzo Locale (alternativo)

Esegui l'agente direttamente:

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
/marketplace        - Apre il marketplace dei plugin
/analytics          - Mostra il report analytics
/language           - Cambia la lingua dell'interfaccia
/performance        - Mostra il report delle performance
/monitoring         - Apre la dashboard di monitoraggio
/skills list        - Elenca skills installate
/skills search <q>  - Cerca skills nel registry
/skills install <n> - Installa una skill
/skills details <n> - Mostra dettagli di una skill
/memory remember    - Ricorda un fatto
/memory recall      - Cerca fatti nella memoria
/memory preference  - Gestisci preferenze
/memory stats       - Statistiche memoria
/plan create <n>    - Crea un piano
/plan list          - Lista tutti i piani
/plan progress <id> - Mostra progresso piano
/plan start <id>    - Inizia un task
/plan complete <id> - Completa un task
/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?
🤖 LangCode: Ciao! Sono LangCode, un agente AI configurabile...

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

👤 You: /analytics
📊 Advanced Analytics Report (Last 30 days)
============================================================

💬 Conversation Statistics:
  Total Conversations: 45
  Total Message Characters: 12,500
  Total Response Characters: 25,800
  Average Message Length: 278 chars
  Average Response Length: 573 chars

🤖 Provider Usage:
  ollama: 30 (66.7%)
  openai: 15 (33.3%)
  Most Used: ollama

💡 Insights and Recommendations:
  💡 You're heavily using ollama (67% of conversations). Consider diversifying with other providers for different use cases.
  ✅ Great response times! Average is 0.8s.

👤 You: /exit
👋 Goodbye!

Utilizzo con Docker

# Avvia con Docker Compose
docker-compose up -d

# Accedi al terminale
docker exec -it langcode-agent langcode

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

Utilizzo dell'API REST

Avvia il server API:

langcode server
# oppure
python api_server.py

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

Endpoint API Disponibili

• GET /: Interfaccia web
• GET /monitoring: Dashboard di monitoraggio
• GET /marketplace: Marketplace dei plugin
• 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
  }'

Analytics Avanzate

LangCode Agent include un sistema avanzato di analytics per monitorare l'uso e ottenere raccomandazioni.

Report Analytics

Il report analytics include:

1. Statistiche Conversazioni:

   • Numero totale di conversazioni
   • Caratteri totali dei messaggi e risposte
   • Lunghezza media di messaggi e risposte

2. Utilizzo Provider:

   • Quale provider viene usato di più
   • Distribuzione percentuale dell'uso
   • Modello più utilizzato

3. Metriche di Performance:

   • Tempo di risposta medio
   • Tempo di risposta minimo e massimo
   • Tempo totale di risposta

4. Utilizzo Strumenti:

   • Quali strumenti vengono usati di più
   • Numero di utilizzi per strumento

5. Utilizzo Comandi:

   • Quali comandi vengono usati di più
   • Numero di utilizzi per comando

6. Pattern di Errori:

   • Errori ricorrenti
   • Pattern di errore più comuni

7. Statistiche Sessioni:

   • Numero totale di sessioni
   • Durata media delle sessioni
   • Messaggi medi per sessione

Raccomandazioni

Il sistema genera automaticamente raccomandazioni basate sui pattern di utilizzo:

• Diversificazione provider: Se usi troppo un singolo provider
• Ottimizzazione performance: Se i tempi di risposta sono lenti
• Utilizzo strumenti: Se usi frequentemente certi strumenti
• Gestione errori: Se ci sono errori ricorrenti
• Pattern di utilizzo: Se l'uso è troppo basso o troppo alto

Visualizzare le Analytics

# Usa il comando /analytics
/analytics

# Oppure esegui lo script direttamente
python analytics.py

Configurazione

I dati di analytics vengono salvati in ~/.langcode/analytics/ e includono:

• Conversazioni (truncati per privacy)
• Utilizzo strumenti
• Utilizzo provider
• Utilizzo comandi
• Pattern di errori
• Sessioni utente

Marketplace dei Plugin

LangCode Agent include un marketplace per scoprire e installare plugin.

Accesso al Marketplace

# Avvia il server API
python api_server.py

# Accedi al marketplace
# http://localhost:8000/marketplace

Funzionalità del Marketplace

Il marketplace include:

1. Plugin Disponibili:

   • Catalogo di plugin disponibili per l'installazione
   • Statistiche di download e valutazioni
   • Descrizioni dettagliate

2. Plugin Installati:

   • Elenco dei plugin attualmente installati
   • Versioni e informazioni
   • Opzioni di disinstallazione

3. Ricerca Plugin:

   • Ricerca per nome o descrizione
   • Filtraggio per categoria
   • Ordinamento per popolarità

4. Gestione Plugin:

   • Installazione con un click
   • Disinstallazione semplice
   • Aggiornamenti automatici

Plugin Inclusi

1. Example Plugin: Plugin di esempio che dimostra come creare plugin

   • Strumenti: example_hello, example_echo, example_math
   • Comandi: /example, /hello, /math

2. 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

3. 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

Installare Plugin dal Marketplace

# Usa il comando /plugins per vedere i plugin disponibili
/plugins

# Oppure usa l'interfaccia web
# http://localhost:8000/marketplace

Creare un Plugin per il Marketplace

Per creare un plugin per il marketplace:

1. Crea un file Python seguendo la struttura dei plugin esistenti
2. Testa il plugin localmente
3. Sottometti il plugin al marketplace (futura implementazione)

Dashboard di Monitoraggio

LangCode Agent include una dashboard di monitoraggio in tempo reale con supporto multilingue.

Accesso alla Dashboard

# Avvia il server API
python api_server.py

# Accedi alla dashboard
# http://localhost:8000/monitoring

Funzionalità della Dashboard

La dashboard include:

1. Statistiche Generali:

   • Stato del sistema (online/offline)
   • Uptime del sistema
   • Richieste totali
   • Errori totali
   • Tasso di errore

2. Provider Attivo:

   • Provider configurato
   • Modello in uso
   • Stato connessione
   • Chiamate al provider

3. Utilizzo Strumenti:

   • Strumenti caricati
   • Plugin attivi

4. Risorse di Sistema:

   • Utilizzo CPU
   • Utilizzo memoria
   • Utilizzo disco

5. Performance:

   • Tempo di risposta medio
   • Richieste al minuto
   • Picco richieste

6. Logs:

   • Logs recenti del sistema
   • Filtraggio per tipo (info, warning, error, success)

7. Informazioni di Sistema:

   • Hostname
   • Piattaforma
   • Architettura
   • Versione Python
   • Versione LangCode

Supporto Multilingue della Dashboard

La dashboard supporta italiano e inglese:

• Selettore lingua: In alto a destra nella dashboard
• Persistenza: La preferenza di lingua viene salvata nel browser
• Traduzione completa: Tutti i testi della dashboard sono tradotti
• Aggiornamento in tempo reale: La lingua cambia istantaneamente

Aggiornamento Automatico

La dashboard si aggiorna automaticamente ogni 30 secondi. Puoi anche aggiornare manualmente con il pulsante "🔄 Aggiorna Dati" (o "🔄 Refresh Data" in inglese).

Interfaccia Web Responsive

L'interfaccia web è stata ottimizzata per essere responsive e funzionare su dispositivi mobili e desktop.

Caratteristiche Responsive

1. Layout adattivo: Si adatta automaticamente a diverse dimensioni dello schermo
2. Touch-friendly: Pulsanti e campi ottimizzati per touch screen
3. Navigazione mobile: Menu e tab ottimizzati per dispositivi mobili
4. Dimensioni appropriate: Font e spaziature adatti a schermi piccoli
5. Supporto multilingue: Interfaccia in italiano e inglese

Accesso da Dispositivi Mobili

L'interfaccia web è accessibile da qualsiasi dispositivo nella stessa rete:

# Avvia il server API
python api_server.py

# Accedi da un dispositivo mobile nella stessa rete
# http://<IP_DEL_SERVER>:8000

Esempio:

# Se il server è su 192.168.0.50
# http://192.168.0.50:8000

Ottimizzazioni per Mobile

• Pulsanti più grandi: Facili da toccare su schermi touch
• Layout a colonna singola: Su schermi stretti
• Font leggibili: Dimensioni appropriate per la lettura su mobile
• Navigazione semplificata: Tab e menu ottimizzati per touch
• Caricamento rapido: Ottimizzazioni per connessioni lente

Ottimizzazioni Performance

LangCode Agent include diverse ottimizzazioni per migliorare le performance:

Caching

• Configurazioni: Le configurazioni vengono cachate per 30 secondi
• Provider tools: Gli strumenti provider vengono cachati per 5 minuti
• Creazione agente: L'agente viene cachato per 10 minuti
• Risposte API: Le risposte API vengono cachate per 10 secondi

Connection Pooling

• Pool di connessioni: Gestisce le connessioni ai provider
• Riutilizzo connessioni: Riutilizza le connessioni esistenti
• Pulizia automatica: Rimuove le connessioni inattive dopo 5 minuti

Lazy Loading

• Caricamento moduli: I moduli vengono caricati solo quando necessari
• Caricamento strumenti: Gli strumenti vengono caricati on-demand
• Risorse pesanti: Le risorse pesanti vengono caricate in modo lazy

Batch Processing

• Elaborazione parallela: Le operazioni vengono eseguite in parallelo
• Thread pool: Utilizza un pool di thread per le operazioni concorrenti
• Timeout configurabile: Timeout configurabile per le operazioni batch

Applicare le Ottimizzazioni

# Applica tutte le ottimizzazioni
python performance.py

# Visualizza il report delle performance
python performance.py

Strumenti Unificati per Provider

LangCode 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

LangCode Agent supporta i seguenti provider:

1. Ollama - Modelli locali
2. OpenAI - GPT-4o, GPT-4o-mini, GPT-4-turbo, ecc.
3. OpenRouter - Accesso a centinaia di modelli
4. Anthropic - Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku, ecc.
5. 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

LangCode 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

Ollama Agent con Tool Calling

LangCode Agent include OllamaToolAgent che supporta il tool calling per modelli Ollama locali senza bisogno di API keys esterne.

Caratteristiche Principali

• Tool calling locale: Nessuna dipendenza da API esterne
• Intent detection: Riconosce automaticamente le intenzioni dell'utente
• Strumenti built-in: Sistema, filesystem, ricerca, esecuzione comandi
• Supporto multilingua: Pattern in italiano e inglese

Strumenti Disponibili

Strumento	Descrizione	Esempio
system_info	Informazioni di sistema (OS, Python, directory, utente)	"Che OS stai usando?"
ls	Lista file in una directory	"Cosa c'è in questa cartella?"
read_file	Leggi il contenuto di un file	"Leggi il file requirements.txt"
write_file	Scrivi contenuto in un file	"Scrivi un file test.txt con dentro 'Hello'"
search	Cerca file per pattern	"Cerca i file *.py"
execute	Esegui comandi shell	"ls -lha", "git status"

Pattern di Intent Detection

L'agent riconosce automaticamente le intenzioni basandosi su parole chiave:

System Info:

• "sistema operativo", "che OS", "che sistema"
• "system info", "what os", "operating system"

Lista File:

• "lista file", "mostrami", "cosa c'è"
• "list files", "show me", "ls"

Leggi File:

• "leggi", "leggere", "mostrami il file"
• "read", "show me", "open"

Scrivi File:

• "scrivi", "crea", "salva"
• "write", "create", "save"

Cerca File:

• "cerca", "trova"
• "search", "find"

Esegui Comandi:

• Comandi shell con argomenti: ls -lha, git status, cat file.txt
• "esegui", "run", "comando"

Esempi di Utilizzo

👤 You: Che OS stai usando?
🤖 LangCode: OS: Linux 5.15.0, Python: 3.12.0, Current dir: /home/user, User: user

👤 You: Cosa c'è in questa cartella?
🤖 LangCode: FILE: main.py
           FILE: requirements.txt
           DIR: tests

👤 You: Leggi il file requirements.txt
🤖 LangCode: langchain>=0.3.0
           requests>=2.31.0
           ...

👤 You: Scrivi un file test.txt con dentro "Hello World"
🤖 LangCode: Successfully wrote to test.txt

👤 You: Cerca i file *.py
🤖 LangCode: Found 15 matches:
           main.py
           utils.py
           ...

👤 You: ls -lha
🤖 LangCode: STDOUT:
           -rw-r--r-- 1 user 11 Mar 23 test.txt

Configurazione

L'OllamaToolAgent viene caricato automaticamente quando usi Ollama come provider:

# Configura Ollama
langcode config add -n ollama -p ollama -m qwen3.5:4b -u http://192.168.0.50:11434 --set-active

# Avvia l'agent
langcode

# Oppure direttamente
python langcode.py

Struttura del Codice

# ollama_agent.py
from langcode_agent.ollama_agent import create_ollama_tool_agent

# Crea l'agent con tool integrati
agent = create_ollama_tool_agent(
    model=llm,
    include_builtin_tools=True  # system_info, ls, read_file, etc.
)

# Usa l'agent
result = agent.invoke({"messages": [HumanMessage(content="Che OS usi?")]})

Sistema di Plugin

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

Plugin Inclusi

1. Example Plugin: Plugin di esempio che dimostra come creare plugin

   • Strumenti: example_hello, example_echo, example_math
   • Comandi: /example, /hello, /math

2. 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

3. 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

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

Lingue Disponibili

• Italiano (it) - Predefinito
• Inglese (en)

Cambiare Lingua

# Usa la variabile d'ambiente
export LANGCODE_LANGUAGE=en

# Oppure usa il comando /language
/language en

Aggiungere una Nuova Lingua

Per aggiungere una nuova lingua:

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

Dashboard Multilingue

La dashboard di monitoraggio supporta anche il cambio lingua:

• Selettore lingua: In alto a destra nella dashboard
• Persistenza: La preferenza viene salvata nel browser
• Traduzione completa: Tutti i testi sono tradotti in italiano e inglese

Web UI Multilingue

L'interfaccia web supporta il cambio lingua:

• Selettore lingua: In alto a destra nell'interfaccia
• Persistenza: La preferenza viene salvata nel browser
• Traduzione completa: Tutti i testi sono tradotti in italiano e inglese

Monitoraggio Performance

LangCode 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 ~/.langcode/performance/ e includono:

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

MCP Integration

LangCode Agent supports the Model Context Protocol (MCP) for connecting to external services and tools.

Configurazione MCP

Per configurare un server MCP:

langcode config add -n my-mcp -p mcp -u http://localhost:8080 --api-key your-key

Utilizzo MCP

Una volta configurato, gli strumenti MCP sono automaticamente disponibili nell'agente.

Strumenti MCP Disponibili

• Gli strumenti variano in base al server MCP configurato
• Consulta la documentazione del server MCP per gli strumenti specifici

Skill Management

LangCode Agent può scoprire, installare e gestire skills dal registry skills.sh.

Cercare Skills

# Cerca skills per parola chiave
langcode skills search "coding"
/skills search "coding"

Installare Skills

# Installa una skill
langcode skills install "code-review-expert"
/skills install "code-review-expert"

Elencare Skills Installate

# Lista tutte le skills installate
langcode skills list
/skills list

Dettagli Skill

# Mostra dettagli di una skill
langcode skills details "code-review-expert"
/skills details "code-review-expert"

Disinstallare Skills

# Disinstalla una skill
langcode skills uninstall "code-review-expert"
/skills uninstall "code-review-expert"

Strumenti Skills nell'Agente

L'agente ha accesso a strumenti per:

• search_skills: Cerca skills nel registry
• install_skill: Installa una skill
• uninstall_skill: Disinstalla una skill
• list_installed_skills: Lista skills installate
• get_skill_details: Ottieni dettagli di una skill

Memory Enhancement

LangCode Agent include un sistema di memoria persistente per ricordare fatti, preferenze e cronologia delle conversazioni.

Comandi Memory

# Ricorda un fatto
/memory remember Il mio colore preferito è il blu

# Cerca fatti nella memoria
/memory recall colore

# Imposta una preferenza
/memory preference set tema "dark mode"

/memory preference set lingua "italiano"

# Ottieni una preferenza
/memory preference get tema

# Statistiche memoria
/memory stats

Strumenti Memory nell'Agente

L'agente ha accesso a strumenti per:

• remember: Ricorda un fatto
• recall: Cerca fatti nella memoria
• preference: Gestisci preferenze utente
• memory_stats: Ottieni statistiche della memoria

Come Funziona

La memoria persistente:

• Salva automaticamente le conversazioni
• Permette di aggiungere fatti categorizzati
• Mantiene le preferenze dell'utente
• Traccia le skills utilizzate
• Persiste tra le sessioni

Planning Enhancement

LangCode Agent include un sistema avanzato di pianificazione con dipendenze, tracciamento del progresso e monitoraggio dello stato.

Creare un Piano

# Crea un piano con più task
/plan create "My Project" "Task 1; Task 2; Task 3"

Elencare Piani

# Lista tutti i piani
/plan list

Progresso del Piano

# Mostra progresso di un piano
/plan progress plan_0000

Gestire Task

# Inizia un task
/plan start task_0000

# Completa un task
/plan complete task_0000

Strumenti Planning nell'Agente

L'agente ha accesso a strumenti per:

• create_task: Crea un nuovo task
• start_task: Inizia a lavorare su un task
• complete_task: Marca un task come completato
• list_tasks: Lista tutti i task
• get_ready_tasks: Ottieni task pronti per essere iniziati
• get_plan_progress: Ottieni progresso di un piano

Caratteristiche Avanzate

• Priorità: low, medium, high, urgent
• Dipendenze: I task possono dipendere da altri task
• Stati: pending, in_progress, completed, failed, cancelled
• Progresso: Calcolo automatico della percentuale di completamento

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 langcode-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 LANGCODE_LANGUAGE=it \
  langcode-agent

Personalizzazione

Per personalizzare l'agente, modifica main.py:

• Cambia il prompt di sistema predefinito in create_langcode_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

LangCode Agent include un sistema di monitoraggio e logging:

• Log dettagliati: Tutte le azioni vengono registrate in ~/.langcode/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
• Dashboard web: Monitoraggio in tempo reale via interfaccia web con supporto multilingue
• Interfacce responsive: Ottimizzate per dispositivi mobili e desktop
• Marketplace plugin: Scopri e installa plugin dal marketplace
• Analytics avanzate: Analisi dettagliate dell'uso e raccomandazioni

Sicurezza

LangCode 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.