Migenta - LocalAI Dynamic Agent

Migenta e un sistema agentico locale in grado di elaborare dati eterogenei (PDF, DOCX, CSV, XLSX, immagini, testo) e eseguire azioni dinamiche completamente offline, senza dipendere da servizi cloud.

---

Indice

• Caratteristiche
• Requisiti
• Installazione
• Uso
• Comandi CLI
• Azioni Supportate
• Architettura
• Tecnologie
• Sviluppo
• Documentazione Tesi
• Licenza

---

Caratteristiche

Principali

• 100% Offline: Funziona senza connessione internet
• Data Sovereignty: Tutti i dati rimangono localmente
• Open Source: Licenza MIT, codice aperto
• Estendibile: Architettura modulare per facile estensione
• Multi-format: Supporta PDF, DOCX, CSV, XLSX, JPG, PNG, TXT
• Action-Oriented: Esegue azioni concrete basate su richieste naturali

Funzionalita

Funzionalita	Descrizione
Data Processing	Elabora file di vari formati
Vector Database	Indicizza e cerca dati con ChromaDB
Embedding	Converte testo in vettori con SentenceTransformers
LLM Inference	Genera risposte con modelli locali (GGUF/ONNX)
Action Engine	Esegue 13 tipi di azioni sul filesystem
CLI Interface	Interfaccia a riga di comando completa
REPL Mode	Modalita interattiva con autocompletamento
Dry Run	Simula operazioni senza modificare

---

Requisiti

Dipendenze di Sistema

Sistema	Requisito	Installazione
Tutti	Python 3.8+	python.org
Tutti	Tesseract OCR 4.0+	Vedi sotto
Linux	libtesseract-dev	sudo apt-get install libtesseract-dev
Mac	Homebrew	brew.sh

Installazione Tesseract OCR

Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install tesseract-ocr
sudo apt-get install libtesseract-dev
# Lingue opzionali
sudo apt-get install tesseract-ocr-ita tesseract-ocr-eng tesseract-ocr-fra

Mac:

brew install tesseract
brew install tesseract-lang

Windows:

1. Scaricare installer da UB-Mannheim/tesseract
2. Eseguire installer e aggiungere al PATH
3. Scaricare file lingue (.traineddata) per lingue aggiuntive

---

Installazione

1. Clonare il Repository

git clone https://git.naxod.com/luca/migenta.git
cd migenta

2. Installare Dipendenze Python

pip3 install -r requisiti.txt

Nota: Se si verificano errori durante l'installazione:

• Assicurarsi che Python 3.8+ sia installato
• Usare un virtual environment: python3 -m venv venv && source venv/bin/activate
• Su Windows: python -m venv venv && venv\Scripts\activate

3. Scaricare Modelli AI

Modello di Embedding (Obbligatorio)

Il modello all-MiniLM-L6-v2 verra scaricato automaticamente da SentenceTransformers alla prima esecuzione.

Modello LLM (Opzionale ma Consigliato)

Scaricare un modello GGUF o ONNX e posizionarlo in modelli/llm/:

Modelli GGUF (consigliati per CPU):

# Phi-2 (2.5GB, veloce)
mkdir -p modelli/llm/
wget https://huggingface.co/TheBloke/phi-2-GGUF/resolve/main/phi-2.Q4_K_M.gguf -O modelli/llm/phi-2.gguf

# Mistral-7B (4GB, piu potente)
wget https://huggingface.co/TheBloke/Mistral-7B-GGUF/resolve/main/mistral-7b.Q4_K_M.gguf -O modelli/llm/mistral-7b.gguf

Modelli ONNX (alternativa):

• Scaricare modelli ONNX da HuggingFace
• Posizionare in modelli/llm/
• Aggiornare DEFAULT_LLM_MODEL in script/agente_ai.py

---

Uso

Avvio Rapido

# Mostra informazioni sul progetto
python3 migenta.py info

# Addestra dati da una cartella
python3 migenta.py addestra --percorso dati/

# Esegui una query
python3 migenta.py query --query "Crea un report dei file in dati/"

# Modalita interattiva
python3 migenta.py interattivo

Dati di Esempio

Il progetto include dati di esempio in dati/test/:

• test.txt - File di testo
• test.csv - File CSV
• test.pdf - File PDF

---

Comandi CLI

Comando: info

Mostra informazioni sul progetto.

python3 migenta.py info

Output: Nome, versione, descrizione, stato sessioni, ecc.

---

Comando: addestra

Addestra dati da una cartella e li indicizza in ChromaDB.

# Addestramento base
python3 migenta.py addestra --percorso dati/

# Con opzioni avanzate
python3 migenta.py addestra \
  --percorso dati/ \
  --output db_chroma/ \
  --escludi .tmp,.log \
  --max-size 10 \
  --batch-size 32 \
  --force \
  --lingua eng+ita

Opzioni:

• --percorso: Cartella da scansionare (obbligatorio)
• --output: Percorso output ChromaDB (default: db_chroma/)
• --escludi: Estensioni da escludere (default: .tmp,.log)
• --max-size: Dimensione massima file in MB (0 = nessun limite)
• --batch-size: Numero di file per batch (default: 32)
• --force: Ricrea la collection ChromaDB
• --lingua: Lingue per OCR (default: eng+ita)

---

Comando: aggiorna

Aggiorna incrementale di ChromaDB con file modificati/nuovi.

# Aggiornamento normale
python3 migenta.py aggiorna --percorso dati/

# Simulazione (dry run)
python3 migenta.py aggiorna --percorso dati/ --dry-run

Opzioni:

• --percorso: Cartella da scansionare (default: dati/)
• --dry-run: Simula senza modificare (default: False)

---

Comando: aggiungi

Gestisce sorgenti dati aggiuntive.

# Aggiungi nuova sorgente
python3 migenta.py aggiungi \
  --percorso /nuovi/dati/ \
  --nome "Nuova Sorgente" \
  --descrizione "Dati aggiuntivi"

# Lista sorgenti
python3 migenta.py aggiungi --lista

# Rimuovi sorgente
python3 migenta.py aggiungi --rimuovi "Nuova Sorgente"

# Indicizza sorgente specifica
python3 migenta.py aggiungi --indicizza "Nuova Sorgente"

# Con dry run
python3 migenta.py aggiungi --indicizza "Nuova Sorgente" --dry-run

Opzioni:

• --percorso: Path sorgente (per aggiunta)
• --nome: Nome sorgente (per aggiunta/rimozione)
• --descrizione: Descrizione sorgente
• --lista: Elenca sorgenti registrate
• --rimuovi: Rimuovi sorgente per nome
• --indicizza: Indicizza sorgente specifica
• --dry-run: Simula senza modificare

---

Comando: test

Esegue test di verifica.

# Esegui test di una sessione
python3 migenta.py test --sessione 11

# Esegui tutti i test
python3 migenta.py test --tutte

Opzioni:

• --sessione: Numero sessione da testare (0-12)
• --tutte: Esegue tutti i test

---

Comando: query

Esegue una query all'agente AI.

# Query semplice
python3 migenta.py query --query "Crea un report dei file"

# Con opzioni avanzate
python3 migenta.py query \
  --query "Organizza i file per data" \
  --dry-run false \
  --max-tokens 512 \
  --temperature 0.7

Opzioni:

• --query: Testo della query (obbligatorio)
• --dry-run: Simula senza esecuzione (default: True)
• --max-tokens: Token massimi per risposta (default: 512)
• --temperature: Temperatura LLM (default: 0.7)

---

Comando: azioni

Gestisce azioni direttamente.

# Lista tipi di azioni
python3 migenta.py azioni --lista

# Lista azioni disponibili
python3 migenta.py azioni --tipi

Opzioni:

• --lista: Elenca tutti i tipi di azione
• --tipi: Mostra cataloghi azioni

---

Comando: verifica

Verifica stato del progetto.

# Verifica una sessione
python3 migenta.py verifica --sessione 12

# Verifica tutte le sessioni
python3 migenta.py verifica --tutte

Opzioni:

• --sessione: Verifica sessione specifica
• --tutte: Verifica tutte le sessioni

---

Comando: interattivo

Avvia modalita interattiva (REPL).

python3 migenta.py interattivo

Comandi REPL:

Comando	Descrizione
addestra [percorso]	Addestra dati
aggiorna [percorso]	Aggiorna dati
aggiungi lista	Lista sorgenti
query "testo"	Esegue query
azioni lista	Lista azioni
test [sessione]	Esegue test
verifica [sessione]	Verifica sessione
info	Mostra info progetto
aiuto	Mostra help
esci	Esce dal REPL

---

Comando: progetti

Mostra stato del progetto.

# Stato generale
python3 migenta.py progetti --stato

# Stato sessioni
python3 migenta.py progetti --sessioni

Opzioni:

• --stato: Mostra stato generale
• --sessioni: Elenca stato tutte le sessioni

---

Azioni Supportate

Migenta supporta 13 tipi di azioni:

Azione	Descrizione	Esempio
CREA_FILE	Crea un nuovo file	Crea file report.txt
MODIFICA_FILE	Modifica un file	Modifica file data.json
ELIMINA_FILE	Elimina un file	Elimina file temp.txt
COPIA_FILE	Copia un file	Copia file.txt in backup.txt
SPOSTA_FILE	Sposta un file	Sposta old.txt in archive/old.txt
CREA_CARTELLA	Crea una cartella	Crea cartella output/
ELIMINA_CARTELLA	Elimina una cartella	Elimina cartella temp/
ESEGUI_COMANDO	Esegue comando shell	Esegui comando ls -la
RICERCA_TESTO	Cerca testo in file	Cerca 'pattern' in file.txt
SOSTITUISCI_TESTO	Sostituisci testo	Sostituisci a con b in file.txt
GENERA_REPORT	Genera report	Genera report output.md
COMPRIMI_FILE	Comprime file	Comprimi file.zip in output/
ESTRAI_ARCHIVIO	Estrae archivio	Estrai file.zip in output/

---

Architettura

┌───────────────────────────────────────────────────────────┐
│              MIGENTA - LocalAI Dynamic Agent              │
├───────────────────────────────────────────────────────────┤
│                                                           │
│  ┌────────────┐  ┌──────────────┐     ┌───────────────┐   │
│  │ migenta.py │  │    script/   │     │    config/    │   │
│  │   (CLI)    │  │              │     │               │   │
│  └──────┬─────┘  │ addestra_    │     │ sorgenti...   │   │
│         │        │  dati.py     │     │ ultimo...     │   │
│         │        │ aggiorna_    │     └───────────────┘   │
│         │        │  dati.py     │                         │
│         │        │ aggiungi_    │     ┌───────────────┐   │
│         │        │  sorgente.py │     │   modelli/    │   │
│         │        │ agente_ai.py │     │ ┌───────────┐ │   │
│         │        │ test_*.py    │     │ │embeddings │ │   │
│         │        └──────┬───────┘     │ ├───────────┤ │   │
│         │               │             │ │   llm/    │ │   │
│         │               │             │ └───────────┘ │   │
│         │               │             └───────────────┘   │
│         │               ▼                                 │
│         │        ┌──────────────┐                         │
│         │        │  db_chroma/  │                         │
│         │        │ (ChromaDB)   │                         │
│         │        └──────────────┘                         │
│         │                                                 │
│         └───────────────┬─────────────────────────────────┤
│                         │                                 │
│                         ▼                                 │
│                ┌──────────────────┐                       │
│                │  script/azioni/  │                       │
│                │                  │                       │
│                │ base.py          │                       │
│                │ azioni_          │                       │
│                │  concrete.py     │                       │
│                └──────────────────┘                       │
│                                                           │
└───────────────────────────────────────────────────────────┘

---

Tecnologie

Librerie Python

Categoria	Libreria	Utilizzo
Vector DB	ChromaDB	Database vettoriale locale
Embeddings	SentenceTransformers	Modelli di embedding
LLM	llama-cpp-python	Esecuzione modelli GGUF
LLM	ONNX Runtime	Esecuzione modelli ONNX
PDF	pdfplumber	Estrazione testo da PDF
DOCX	python-docx	Lettura Word documenti
CSV/XLSX	pandas, openpyxl	Gestione spreadsheet
OCR	pytesseract, Pillow	OCR da immagini
CLI	rich, tqdm	Interfaccia utente avanzata

Modelli AI Supportati

Tipo	Modello	Dimensione	Note
Embedding	all-MiniLM-L6-v2	~80MB	Default
LLM (GGUF)	Phi-2	~2.5GB	Veloce per CPU
LLM (GGUF)	Mistral-7B	~4GB	Potente
LLM (ONNX)	Vari	Variabile	Alternativa

---

Sviluppo

Sessioni di Sviluppo

Sessione	Titolo	Stato	Tempo
0	Inizializzazione Progetto	✅	10 min
1	Setup Ambiente	✅	15 min
2	Addestramento Iniziale	✅	1 ora
3	Test e Ottimizzazione	✅	1 ora
4	Aggiornamento Incrementale	✅	45 min
5	Aggiunta Sorgenti	✅	30 min
6	Test Integrazione	✅	1 ora
7	Contesto e Prompt	✅	1 ora
8	Inferenza LLM	✅	1 ora
9	Esecuzione Azioni	✅	2 ore
10	Integrazione Agente	✅	1 ora
11	Interfaccia CLI	✅	1 ora
12	Documentazione	🔄	1 ora

Stato: 12/13 sessioni completate (92.3%) Tempo totale: 08:25:00 (stimato: ~12.5 ore)

Contribuire

1. Fork del repository
2. Crea un branch: git checkout -b feature/nome-feature
3. Fai le modifiche
4. Testa: python3 script/verifica/verifica_sessione_<N>.py
5. Commit: git commit -m "Aggiunta funzione X"
6. Push: git push origin feature/nome-feature
7. Pull Request

Vedi CONTRIBUTING.md per linee guida dettagliate.

Verifica del Progetto

Tutti i 110 test automatici sono passati:

# Verifica una sessione
python3 script/verifica/verifica_sessione_11.py

# Verifica tutte le sessioni
for i in {0..11}; do python3 script/verifica/verifica_sessione_$i.py; done

---

Documentazione Tesi

Il progetto include documentazione completa per una tesi universitaria:

File	Descrizione	Righe
tesi/introduzione.md	Capitolo 1: Contesto e obiettivi	300+
tesi/implementazione.md	Capitolo 2: Dettagli tecnici	1,000+
tesi/risultati.md	Capitolo 3: Test e benchmark	200+
tesi/conclusione.md	Capitolo 4: Conclusioni	150+

Totale documentazione: ~1,850+ righe

Struttura Tesi

1. Introduzione

   • Contesto e motivazioni
   • Obiettivi del progetto
   • Architettura generale
   • Tecnologie utilizzate

2. Implementazione

   • Dettagli di tutte le 12 sessioni
   • Codice sorgente commentato
   • Pattern di progettazione

3. Risultati

   • 110 test automatici
   • Benchmark di prestazione
   • Confronto con soluzioni esistenti

4. Conclusione

   • Riassunto del lavoro
   • Limitazioni e soluzioni
   • Sviluppi futuri

---

Licenza

MIT License

Copyright (c) 2026 Migenta - LocalAI Dynamic Agent

Permesso di usare, copiare, modificare, unire, pubblicare, distribuire, sublicenziare e/o vendere copie del software.

Vedi LICENSE per il testo completo della licenza.

---

Contatti

• Repository: https://git.naxod.com/luca/migenta
• Autore: Luca
• Email: lab@naxod.com

---

Documentazione generata automaticamente come parte della Sessione 12 - Documentazione e Finalizzazione Ultimo aggiornamento: 2026-05-09 20:48:10