Cipro-V1-Nano-Language-Model

🏛️ Cipro V1 - Nano Financial Specialist 🇮🇹

⚠️ PROJECT STATUS: FASE 1 (ALPHA) Nano LLM specializzato in Finanza & Economia. Sviluppato da zero in 2.5 mesi con un budget di soli 18€.

Ester Egg "La stazione venne inaugurata il 29 maggio 1999 come parte del prolungamento da Ottaviano a Valle Aurelia." -Wiki

Cipro V1 non è un modello generalista: è un Nano Language Model verticale, progettato specificamente per il dominio economico-finanziario italiano.

Il progetto dimostra come creare un'IA settoriale ("Domain Expert") utilizzando una pipeline di addestramento rigorosa, partendo da zero fino alla specializzazione tramite Instruction Tuning.

---

🏗️ La Pipeline di Costruzione: Come è nato Cipro V1

Per costruire un modello capace di parlare di "tassi BCE" e "spread" partendo da una rete neurale vuota, abbiamo seguito una strategia a due fasi sequenziali:

1️⃣ FASE 1: Foundation & Language Acquisition (Il "Corpo")

• L'Obiettivo: Prima di poter rispondere a delle domande, il modello doveva imparare l'italiano e il lessico finanziario.
• I Dati: Abbiamo creato il Nano Italian Corpus - Economics, un mix ibrido di:
  • Dati Sintetici: Testi generati da LLM superiori per spiegare concetti economici con chiarezza didattica.
  • Dati Istituzionali: Comunicazioni ufficiali della BCE per acquisire il registro formale.
• Il Risultato: In questa fase il modello ha letto 18.5 Milioni di caratteri (TXT), imparando la grammatica, la sintassi e le relazioni tra le parole (es. sapere che dopo "tasso di" spesso segue "interesse" o "inflazione").
• Stop Condition: Il pre-training è stato interrotto solo quando la Loss è scesa sotto 3.20, segnando una solida comprensione linguistica.

2️⃣ FASE 2: Instruction Tuning (La "Mente")

• L'Obiettivo: Trasformare il modello da un "generatore di testo" a un "assistente che risponde".
• Il Metodo (SFT): Una volta acquisita la lingua, abbiamo congelato la conoscenza base e raffinato il modello su un dataset JSON curato di coppie Domanda/Risposta (Q&A).
• Il Risultato: Il modello ha imparato a strutturare le risposte, smettendo di completare le frasi a caso e iniziando a comportarsi come un consulente (Instruction Following).

---

📊 Training Run & Performance

I numeri confermano il successo della strategia "Language First, Task Second":

• Pre-Training Loss: 9.63 $\to$ 3.14 (Acquisizione della lingua completata)
• SFT Loss: 4.98 $\to$ 0.41 (Specializzazione estrema sul task Q&A)

Nota: La Loss SFT molto bassa (0.41) indica che il modello ha "memorizzato" molto bene i concetti chiave, ideale per scopi didattici, sebbene comporti un certo overfitting.

Il progetto nasce come risorsa educativa per dimostrare come costruire, addestrare e specializzare (SFT) una Intelligenza Artificiale Generativa utilizzando PyTorch puro, senza affidarsi a librerie pre-confezionate di alto livello.

🧠 Model Architecture

Cipro V1 è basato su un'architettura Transformer Decoder-only. A differenza dei modelli encoder (come BERT), Cipro V1 è autoregressivo: genera il token successivo basandosi sulla sequenza precedente.

Specifiche Tecniche

• Tipo: Decoder-only Transformer (Custom PyTorch Implementation).
• Parametri: ~30M (Nano scale).
• Context Window: 384 tokens.
• Embedding Dimension (d_model): 512.
• Layers: 10 blocchi decoder.
• Heads: 8 attention heads.
• Vocabolario: 14,000 token (BPE Custom Tokenizer).

Caratteristiche del Codice

Il modello implementa diverse ottimizzazioni didattiche moderne:

1. Pre-Normalization: La LayerNorm è applicata prima dell'attenzione e del feed-forward per una maggiore stabilità dei gradienti.
2. GELU Activation: Utilizzata al posto della ReLU classica.
3. Rotary / Positional Embeddings: Implementazione standard sinusoidale.
4. Tokenizer BPE Custom: Addestrato specificamente per gestire il gergo finanziario italiano (es. "Eurosistema", "tasso d'inflazione") e token speciali [BOS], [EOS].

---

📊 Training Run & Performance

Il modello è stato addestrato in due fasi distinte su una singola GPU.

Fase 1: Pre-Training (Knowledge Acquisition)

Addestramento non supervisionato su 18.5 Milioni di caratteri di testi economici misti (Sintetici + Istituzionali BCE).

• Loss Iniziale: 9.63
• Loss Finale: 3.14
• Risultato: Il modello ha acquisito la sintassi italiana e la struttura delle frasi economiche complesse.

Fase 2: Supervised Fine-Tuning (SFT)

Raffinamento su un dataset curato di coppie Domanda/Risposta (JSON).

• Loss Iniziale: 4.98
• Loss Finale: 0.41
• Risultato: Il modello ha imparato a rispondere in formato Q&A, ma la loss molto bassa (0.41) suggerisce un overfitting sul dataset di istruzione (memorizzazione delle risposte).

---

🧪 Esempi di Generazione (Chat)

Il modello è in grado di definire concetti economici, anche se con occasionali imprecisioni logiche dovute alla dimensione ridotta ("Nano").

Input: che cosa è la politica monetaria?

Cipro V1: "La politica monetaria è l’insieme delle azioni adottate da una banca centrale per controllare l’offerta di moneta e le condizioni di liquidità nell’economia..."

Input: cosa è il rischio di credito?

Cipro V1: "Il rischio di credito viene valutato attraverso modelli di rating, analisi di bilancio e indicatori come la probabilità di default..."

---

🖼️ Visualizzazione dei Risultati (Chat Log)

(Screenshot reale della sessione di test)

🧐 Analisi Critica: Genio o Allucinazione?

I risultati mostrati nell'immagine sono un successo tecnico straordinario per un modello di soli 30M parametri addestrato da zero. Ecco cosa ci dicono questi output sulla natura delle Reti Neurali Generative:

1. Il Fenomeno dell'Overfitting (Il caso "WACC")

Nel log vediamo che il modello risponde alla domanda sul WACC in modo quasi robotico e perfetto.

• L'Errore: La risposta è rigida, quasi recitata a memoria.
• Il Successo: Questo dimostra che la fase di SFT (Supervised Fine-Tuning) ha funzionato con una potenza incredibile. La Loss è scesa a 0.41, il che significa che il modello ha "memorizzato" i concetti chiave del dataset di training. Per scopi didattici, è la prova che il meccanismo di backpropagation ha fatto il suo dovere.

2. L'Allucinazione Associativa (Il caso "Rischio di Mercato")

Alla domanda sul Rischio di Mercato, Cipro V1 risponde parlando di "domanda e offerta che coincidono".

• L'Errore: Concettualmente, ha descritto l'Equilibrio di Mercato, non il Rischio.
• Il Successo: Questo è l'esempio più affascinante. Il modello ha visto la parola "Mercato" e, probabilisticamente, l'ha associata al concetto più frequente nel suo "cervello" (l'equilibrio).
  • Tuttavia, nota la Sintassi: "Il rischio di mercato si forma nel punto in cui...". La frase è grammaticalmente perfetta.
  • Cipro V1 ha imparato perfettamente l'italiano finanziario; gli manca solo la "memoria del mondo" per distinguere sfumature complesse, un limite intrinseco dei Nano-modelli, non un difetto del codice.

Conclusione

Cipro V1 non è ChatGPT. È un laboratorio trasparente che mostra come un'IA impara a parlare prima ancora di imparare a ragionare.

---

💻 How to Use (Python)

⚠️ Nota Importante: Questo codice non utilizza API esterne o modelli pre-addestrati di Hugging Face. Utilizza l'architettura Custom GPT definita nel file model.py presente in questa repository.

🏦 Cipro-V1-Nano-Language-Model

Cipro-V1 è un modello di linguaggio "Nano" sviluppato da zero, specializzato nel dominio economico e finanziario. Non è un semplice wrapper: l'architettura, il tokenizer e il processo di addestramento sono stati progettati specificamente per gestire la terminologia tecnica del settore.

---

🛠 Specifiche Tecniche

• Model Type: Custom GPT (Decoder-only)
• Parameters: ~184MB (PyTorch Weights)
• Layers: 10
• Heads: 8
• Embedding Dim: 512
• Context Window: 384 tokens
• Tokenizer: Custom BPE (14,000 vocab size)

---

🚀 Come Usare Cipro-V1 (Inference)

Per utilizzare il modello è necessario abilitare trust_remote_code=True poiché l'architettura è definita localmente nel file model.py.

import torch
import torch.nn.functional as F
from transformers import AutoModel, AutoTokenizer

# Caricamento Modello e Tokenizer
model_id = "FlavioRubensOttaviani/Cipro-V1-Nano-Language-Model"
model = AutoModel.from_pretrained(model_id, trust_remote_code=True)
tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
model.eval()

def genera_risposta(prompt, max_tokens=150):
    # Formattazione Q&A coerente con il Fine-Tuning
    testo = f"Domanda: {prompt}\nRisposta: "
    input_ids = torch.tensor(tokenizer.encode(testo).ids).unsqueeze(0)
    
    generated = input_ids
    for _ in range(max_tokens):
        # Window di contesto (384)
        idx_cond = generated[:, -384:]
        
        with torch.no_grad():
            logits = model(idx_cond)
            # Temperatura impostata a 0.7 per bilanciare precisione e creatività
            logits = logits[:, -1, :] / 0.7 
            
            # Top-K filtering (K=60)
            v, _ = torch.topk(logits, 60)
            logits[logits < v[:, [-1]]] = -float('Inf')
            
            probs = F.softmax(logits, dim=-1)
            next_token = torch.multinomial(probs, num_samples=1)
            
            if next_token.item() == tokenizer.token_to_id("[EOS]"):
                break
                
            generated = torch.cat((generated, next_token), dim=1)
    
    return tokenizer.decode(generated[0][input_ids.shape[1]:].tolist())

# Esempio di utilizzo
domanda = "Che cosa sono i flussi di cassa?"
print(f"Cipro-V1: {genera_risposta(domanda)}")

📂 Datasets Correlati
I dati utilizzati per il training sono disponibili qui:

Pre-training: Nano Italian Corpus - Economics

👥 Credits & Authors
Progetto sviluppato da:

Dr. Ottaviani Flavio Rubens AI Engineer

Davide Buccino Data Analyst

Rilasciato sotto licenza MIT per la ricerca open-source sui Small Language Models (SLM).