PAI Platform - Personality Artificial Intelligence

PAI Platform non è solo un generatore di chatbot. È un sistema di preservazione digitale progettato per catturare l'essenza, i ricordi e la personalità di un essere umano, cristallizzandoli in un'Intelligenza Artificiale interattiva.

Attraverso un questionario psicologico approfondito (ora con oltre 120 punti dati, inclusi ricordi sensoriali e storici basati su protocolli scientifici) e un sofisticato sistema RAG (Retrieval-Augmented Generation), la PAI crea un "Gemello Digitale" in grado di ricordare fatti, emulare schemi linguistici e mantenere relazioni coerenti nel tempo.

---

✨ Funzionalità Chiave

• 🧠 Profilazione Profonda & Sensoriale: Genera un'istruzione di sistema complessa basata su ricordi d'infanzia, tratti psicologici, valori, trigger sensoriali (odori, suoni) e contesto storico.
• 🔒 Livelli di Privacy (Chiavi di Accesso): Crea password specifiche (es. "FIGLIO", "MOGLIE") che sbloccano ricordi privati o cambiamenti comportamentali. L'AI agisce diversamente in base a chi le parla.
• 📚 Memoria Infinita (RAG Ottimizzato): Include Hybrid Re-ranking lato client (Weighted Fusion tra Vector Score e Lexical Density con Stop-words filtering), Chunking automatico, Query Expansion e ottimizzazione del contesto per mitigare l'effetto "Lost in the Middle".
• 🛠 Function Calling & Active Recall: Supporto nativo per l'uso di strumenti (Tool Use) con provider compatibili (es. OpenRouter/OpenAI). L'AI decide autonomamente quando interrogare la memoria. Se il modello non supporta i tool, il sistema ricade automaticamente su un motore di "Active Recall" basato su prompt.
• 🎨 Agnostico ai Modelli: Supporta Google Gemini (Default) e qualsiasi modello tramite OpenRouter (Claude 3, GPT-4, Llama 3, Dolphin, ecc.), configurabili da .env.
• ⚡ Embeddings Open Source: Utilizza modelli Hugging Face (es. sentence-transformers/all-MiniLM-L6-v2) per generare vettori ad alta efficienza e basso costo tramite proxy PHP.
• 💅 UI Moderna: Costruita con React 19, Tailwind CSS e concetti di Glassmorphism.

---

🛠 Stack Tecnologico

• Frontend: React 19, TypeScript, Vite, Tailwind CSS.
• Backend: PHP (API Leggere), MySQL (Storage Utenti e Metadati).
• Vector Database: Qdrant (per la Memoria a Lungo Termine).
• Motori AI: Google Generative AI Web SDK (Gemini), OpenRouter API.

---

🧠 L'Architettura: Sistema RAG Ibrido

Il cuore della Piattaforma PAI è il suo sistema avanzato di Generazione Aumentata dal Recupero (RAG), che opera in due modalità intelligenti:

1. Function Calling (Tool Use) - Preferita

Se il modello LLM supporta le chiamate a funzione (es. GPT-4, Claude 3 Opus via OpenRouter), il sistema fornisce uno strumento search_memories.

• L'LLM riceve il messaggio dell'utente.
• Decide autonomamente se ha bisogno di informazioni aggiuntive.
• Esegue il tool con una query specifica (es. trasforma "quel viaggio nel 90" in "vacanza famiglia estate 1990").
• I risultati vengono iniettati nella conversazione e l'LLM genera la risposta finale.

2. Active Recall Fallback (Legacy)

Se il modello non supporta i tool o la chiamata fallisce (es. modelli locali più piccoli o Gemini base in configurazione standard), il sistema attiva una procedura di fallback robusta:

1. Query Expansion: Il sistema analizza l'input e la cronologia per generare una query di ricerca dichiarativa ottimizzata (es. "L'utente chiede del suo cane" -> "Nome e dettagli del cane dell'utente").
2. Recupero Vettoriale: Viene eseguito un fetching ampio (Oversampling) su Qdrant.
3. Hybrid Re-ranking: I risultati vengono riordinati localmente combinando lo score semantico con un'analisi lessicale avanzata (filtrazione Stop Words e boost per termini rari).
4. Context Optimization: I ricordi vengono ordinati per posizionare i più rilevanti vicino alla fine del prompt (recency bias), mitigando l'effetto "Lost in the Middle".

In tutti i casi, vengono applicati filtri di sicurezza rigorosi basati sulle Chiavi di Accesso.

---

🚀 Guida all'Installazione

Prerequisiti

• Node.js & npm
• PHP & MySQL (XAMPP, MAMP, o Docker)
• Qdrant (Cloud o istanza Docker locale)
• API Keys (Google Gemini o OpenRouter)

1. Installazione

Clona la repository e installa le dipendenze del frontend:

git clone https://github.com/tuo-repo/pai-platform.git
cd pai-platform
npm install

2. Configurazione Backend

1. Punta il tuo server web (Apache/Nginx) alla root del progetto.
2. Importa il file backend/database.sql nel tuo database MySQL.
3. Configura backend/api/db.php con le credenziali del tuo database.

3. Configurazione Variabili d'Ambiente

Rinomina .env.example (se esiste) o crea un file .env nella directory principale.

# URL Backend API (Punta al tuo server PHP)
VITE_BACKEND_URL=http://localhost/pai-platform/api

# Configurazione Google Gemini (Obbligatorio)
GEMINI_API_KEY=tua_api_key_gemini
GEMINI_MODEL=gemini-2.0-flash

# Configurazione Hugging Face (Obbligatorio per Embeddings)
HUGGINGFACE_API_KEY=tua_key_hf
HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

# OpenRouter (Opzionale - Per usare altri modelli come Claude/GPT)
OPENROUTER_API_KEY=
OPENROUTER_MODEL=cognitivecomputations/dolphin-mistral-24b-venice-edition:free

# Qdrant Vector DB (Obbligatorio per la Memoria)
QDRANT_URL=https://tua-url-cluster-qdrant.url
QDRANT_API_KEY=tua_api_key_qdrant

4. Avvio Locale

npm run dev

---

📂 Struttura del Progetto

• components: Componenti UI (Chat, Auth, Dashboard, Modali).
• services: Livello logico e servizi.
  • ai/*: Moduli di intelligenza artificiale (Chat, Generatori, Embeddings, Impostazioni, Prompt).
  • ai/tools.ts: Definizioni dei tool per Function Calling.
  • vectorService.ts: Interazione Qdrant (Embedding, Ricerca, Salvataggio).
  • chatHistoryService.ts: Gestione del LocalStorage per le sessioni.
• data: Dati statici (Struttura del questionario).
• docs: Documentazione completa del questionario e metodologie (Vedi QUESTIONNAIRE_MASTER_LIST.md).
• backend/api: Endpoint PHP per le operazioni CRUD su Utenti e PAI.

---

🛡 Nota sulla Sicurezza

Sebbene PAI Platform utilizzi Chiavi di Accesso per filtrare i ricordi, attualmente il filtro avviene a livello di query verso il Vector DB. In un ambiente di produzione ad alta sicurezza, assicurati che l'implementazione backend verifichi rigorosamente la proprietà dei dati prima di restituire i payload vettoriali al frontend.

---

📜 Licenza

Licenza MIT. Sentiti libero di forkare il progetto e costruire la tua eternità digitale.