documente/prd-v2.md

# Product Requirements Document (PRD)

## Agentic Retrieval System - Powered by Datapizza AI

**Versione:** 2.0.0  
**Data:** 2026-04-06  
**Autore:** Development Team  
**Status:** Draft

---

## 1. Panoramica del Prodotto

### 1.1 Nome del Prodotto
**AgenticRAG** - Sistema di retrieval agentico con interfaccia web e API REST, basato sul framework datapizza-ai.

### 1.2 Descrizione
Sistema RAG (Retrieval-Augmented Generation) avanzato che combina:
- **Interfaccia Web** per interazione umana intuitiva
- **API REST** documentata con Swagger/OpenAPI
- **Architettura Agentic** basata su datapizza-ai
- **Multi-Provider LLM** (OpenAI, Google, Anthropic, Mistral, Azure)
- **Vector Store** integrato (Qdrant)
- **Pipeline RAG** completa con embedding, retrieval e generazione

### 1.3 Obiettivi Principali
1. Creare un sistema RAG production-ready con interfaccia web
2. Esporre API REST complete con documentazione Swagger
3. Supportare multipli provider LLM tramite datapizza-ai
4. Fornire ingestion documentale avanzata (PDF, DOCX, TXT, web)
5. Implementare chat agentica con memoria e contesto

---

## 2. Obiettivi

### 2.1 Obiettivi di Business
- [ ] Sistema RAG utilizzabile via web browser
- [ ] API REST documentata e testabile via Swagger UI
- [ ] Supporto multi-tenant per team/organizzazioni
- [ ] Deployment semplificato con Docker
- [ ] Performance ottimizzate per produzione

### 2.2 Obiettivi Utente
- [ ] Caricare documenti via web UI (drag & drop)
- [ ] Interagire via chat con i documenti caricati
- [ ] Configurare provider LLM preferito
- [ ] Monitorare uso e performance via dashboard
- [ ] Integrare via API REST in applicazioni esterne

### 2.3 Metriche di Successo (KPI)
| Metrica | Target | Note |
|---------|--------|------|
| Web UI Load Time | <2s | First contentful paint |
| API Response Time | <500ms | Per operazioni sync |
| Document Ingestion | <30s | Per file <10MB |
| Retrieval Accuracy | >90% | Precision@5 |
| User Satisfaction | >4.5/5 | NPS score |

---

## 3. Pubblico Target

### 3.1 Persona 1: Knowledge Worker
- **Ruolo:** Professionista che gestisce documentazione
- **Needs:** Interrogare documenti aziendali via chat, ottenere risposte precise
- **Frustrazioni:** Ricerca manuale in documenti, dispersione informazioni
- **Obiettivi:** Accedere rapidamente al knowledge base aziendale

### 3.2 Persona 2: Software Developer
- **Ruolo:** Sviluppatore che integra RAG in applicazioni
- **Needs:** API REST stabile, documentazione chiara, SDK
- **Frustrazioni:** API instabili, documentazione scarsa
- **Obiettivi:** Integrare capacità RAG in applicazioni esistenti

### 3.3 Persona 3: Data Scientist
- **Ruolo:** Ricercatore/analista di dati
- **Needs:** Pipeline RAG configurabile, multiple LLM, evaluation
- **Frustrazioni:** Framework rigidi, difficoltà tuning
- **Obiettivi:** Sperimentare con diverse configurazioni RAG

---

## 4. Requisiti Funzionali

### 4.1 Core: Web Interface

#### REQ-001: Dashboard Principale
**Priorità:** Alta  
**Descrizione:** Interfaccia web principale con overview del sistema
**Criteri di Accettazione:**
- [ ] Visualizzazione documenti caricati
- [ ] Statistiche uso (query, documenti, token)
- [ ] Accesso rapido alla chat
- [ ] Configurazione provider LLM
- [ ] Tema chiaro/scuro

**User Story:**  
*"Come utente, voglio una dashboard intuitiva per gestire il mio knowledge base"*

#### REQ-002: Document Upload
**Priorità:** Alta  
**Descrizione:** Caricamento documenti via web UI
**Criteri di Accettazione:**
- [ ] Drag & drop multi-file
- [ ] Supporto PDF, DOCX, TXT, MD
- [ ] Progress bar caricamento
- [ ] Estrazione testo automatica (Docling/Azure AI)
- [ ] Chunking configurabile
- [ ] Indexing in vector store (Qdrant)

**User Story:**  
*"Come utente, voglio caricare documenti semplicemente trascinandoli"*

#### REQ-003: Chat Interface
**Priorità:** Alta  
**Descrizione:** Interfaccia chat per interrogare i documenti
**Criteri di Accettazione:**
- [ ] UI chat moderna (stile ChatGPT/Claude)
- [ ] Streaming risposte in tempo reale
- [ ] Visualizzazione sorgenti (retrieved chunks)
- [ ] History conversazioni
- [ ] Export conversazione (PDF, Markdown)
- [ ] Citations cliccabili ai documenti

**User Story:**  
*"Come utente, voglio fare domande ai miei documenti e vedere le fonti delle risposte"*

#### REQ-004: Document Management
**Priorità:** Media  
**Descrizione:** Gestione documenti caricati
**Criteri di Accettazione:**
- [ ] Lista documenti con metadata
- [ ] Preview documento
- [ ] Ricerca documenti
- [ ] Cancellazione documento
- [ ] Tagging/categorizzazione

### 4.2 Core: API REST

#### REQ-005: Documents API
**Priorità:** Alta  
**Descrizione:** CRUD operazioni sui documenti via API
**Criteri di Accettazione:**
- [ ] POST /api/v1/documents - Upload documento
- [ ] GET /api/v1/documents - Lista documenti
- [ ] GET /api/v1/documents/{id} - Dettaglio documento
- [ ] DELETE /api/v1/documents/{id} - Cancellazione
- [ ] GET /api/v1/documents/{id}/content - Contenuto estratto

**User Story:**  
*"Come developer, voglio gestire documenti via API REST"*

#### REQ-006: Query API
**Priorità:** Alta  
**Descrizione:** Endpoint per interrogare il knowledge base
**Criteri di Accettazione:**
- [ ] POST /api/v1/query - Query semplice
- [ ] POST /api/v1/chat - Conversazione con memoria
- [ ] Streaming response (SSE)
- [ ] Reranking opzionale
- [ ] Filtraggio per metadata

**User Story:**  
*"Come developer, voglio interrogare il sistema RAG via API"*

#### REQ-007: Configuration API
**Priorità:** Media  
**Descrizione:** Configurazione sistema via API
**Criteri di Accettazione:**
- [ ] GET /api/v1/config - Configurazione corrente
- [ ] PUT /api/v1/config - Aggiornamento config
- [ ] GET /api/v1/providers - Lista provider LLM disponibili
- [ ] POST /api/v1/providers/{id}/set - Selezione provider

### 4.3 Core: RAG Pipeline (datapizza-ai)

#### REQ-008: Document Processing
**Priorità:** Alta  
**Descrizione:** Pipeline di processing documenti con datapizza-ai
**Criteri di Accettazione:**
- [ ] Parser multi-formato (Docling, Azure AI)
- [ ] Text splitting intelligente (NodeSplitter)
- [ ] Embedding generation (OpenAI, Google, Cohere)
- [ ] Vector storage (Qdrant)
- [ ] Metadata extraction

#### REQ-009: Retrieval Engine
**Priorità:** Alta  
**Descrizione:** Sistema di retrieval avanzato
**Criteri di Accettazione:**
- [ ] Semantic search con embeddings
- [ ] Hybrid search (keyword + semantic)
- [ ] Reranking (Cohere, Together AI)
- [ ] Query rewriting per migliorare retrieval
- [ ] Context compression

#### REQ-010: Agent System
**Priorità:** Alta  
**Descrizione:** Sistema agentico per risposte intelligenti
**Criteri di Accettazione:**
- [ ] Agent configuration (system prompt, tools)
- [ ] Multi-turn conversation memory
- [ ] Tool integration (web search, custom tools)
- [ ] Streaming responses
- [ ] Multi-agent orchestration

### 4.4 Core: Swagger/OpenAPI

#### REQ-011: API Documentation
**Priorità:** Alta  
**Descrizione:** Documentazione API completa
**Criteri di Accettazione:**
- [ ] Swagger UI disponibile su /docs
- [ ] OpenAPI schema su /openapi.json
- [ ] Esempi di request/response
- [ ] Authentication documentation
- [ ] Try-it-now functionality

---

## 5. Requisiti Non Funzionali

### 5.1 Performance
- Web UI Load Time: <2s
- API Response Time: <500ms
- Document Processing: <30s per 10MB
- Concurrent Users: ≥100

### 5.2 Sicurezza
- HTTPS obbligatorio
- API Key authentication
- JWT per sessioni web
- Rate limiting per utente/IP
- Sanitizzazione input

### 5.3 Scalabilità
- Stateless API design
- Containerizzazione Docker
- Horizontal scaling support
- Queue-based document processing

### 5.4 Usabilità (Web UI)
- Responsive design (mobile-first)
- Accessibility WCAG 2.1 AA
- Loading states feedback
- Error handling user-friendly

---

## 6. Stack Tecnologico

### 6.1 Core Technologies
| Componente | Tecnologia | Versione |
|------------|------------|----------|
| Language | Python | ≥3.10 |
| Framework API | FastAPI | ≥0.100 |
| Framework Web UI | React + Vite | ≥18 |
| Async | asyncio | built-in |
| Validation | Pydantic | ≥2.0 |

### 6.2 Datapizza AI Framework
| Componente | Tecnologia | Scopo |
|------------|------------|-------|
| Core | datapizza-ai | Framework RAG/Agent |
| Clients | datapizza-ai-clients-openai | OpenAI integration |
| | datapizza-ai-clients-google | Google Gemini |
| | datapizza-ai-clients-anthropic | Claude |
| Embedders | datapizza-ai-embedders | Text embeddings |
| Vector Store | datapizza-ai-vectorstores-qdrant | Qdrant integration |
| Parsers | datapizza-ai-modules-parsers-docling | Document parsing |
| Tools | datapizza-ai-tools | Web search, etc. |

### 6.3 Frontend
| Componente | Tecnologia | Scopo |
|------------|------------|-------|
| Framework | React 18 | UI library |
| Build | Vite | Build tool |
| Styling | Tailwind CSS | CSS framework |
| Components | shadcn/ui | UI components |
| Icons | Lucide React | Icons |
| State | React Query | Server state |
| HTTP Client | Axios | API calls |

### 6.4 DevOps
| Componente | Tecnologia | Scopo |
|------------|------------|-------|
| Container | Docker | Containerization |
| Compose | Docker Compose | Multi-service |
| Orchestration | Kubernetes (optional) | Scaling |

---

## 7. Architettura

### 7.1 System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Web Browser                              │
│              (React UI - User Interface)                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP/WebSocket
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   API Layer (FastAPI)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  REST API   │  │   Swagger   │  │   WebSocket (chat)  │  │
│  │             │  │   /docs     │  │                     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              Agentic RAG Engine (datapizza-ai)              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Agent     │  │  Retrieval  │  │  Document Pipeline  │  │
│  │   System    │  │   Engine    │  │  (Ingestion)        │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   LLM       │  │  Embedding  │  │    Vector Store     │  │
│  │  Clients    │  │   Models    │  │    (Qdrant)         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### 7.2 API Structure

```
/api/v1/
├── documents/
│   ├── POST   /                    # Upload document
│   ├── GET    /                    # List documents
│   ├── GET    /{id}                # Get document
│   ├── DELETE /{id}                # Delete document
│   └── GET    /{id}/content        # Get extracted content
├── query/
│   └── POST   /                    # Query knowledge base
├── chat/
│   ├── POST   /                    # Send message
│   ├── GET    /history             # Get chat history
│   └── DELETE /history             # Clear history
├── config/
│   ├── GET    /                    # Get config
│   ├── PUT    /                    # Update config
│   └── GET    /providers           # List LLM providers
└── health/
    └── GET    /                    # Health check

/docs (Swagger UI)
/openapi.json (OpenAPI schema)
```

### 7.3 Frontend Structure

```
/src
├── components/         # React components
│   ├── Chat/          # Chat interface
│   ├── Documents/     # Document management
│   ├── Dashboard/     # Dashboard view
│   └── Settings/      # Configuration
├── hooks/             # Custom React hooks
├── api/               # API client
├── types/             # TypeScript types
└── utils/             # Utilities
```

---

## 8. Piano di Sviluppo

### 8.1 Fasi

| Fase | Durata | Focus | Deliverables |
|------|--------|-------|--------------|
| Fase 1 | 2 settimane | Backend API + datapizza-ai | API REST completa, RAG pipeline |
| Fase 2 | 2 settimane | Frontend Web UI | React UI, chat, document upload |
| Fase 3 | 1 settimana | Integrazione + Testing | End-to-end testing, bugfix |
| Fase 4 | 1 settimana | Documentazione + Deploy | Swagger, README, Docker |

### 8.2 Milestone

| Milestone | Data | Features |
|-----------|------|----------|
| v0.1.0 | +2 settimane | Backend API completo |
| v0.2.0 | +4 settimane | Web UI funzionante |
| v0.3.0 | +5 settimane | Testing e ottimizzazione |
| v1.0.0 | +6 settimane | Production ready |

---

## 9. Dipendenze

### 9.1 Backend (Python)
```
datapizza-ai>=0.1.0
datapizza-ai-clients-openai
datapizza-ai-embedders-openai
datapizza-ai-vectorstores-qdrant
datapizza-ai-modules-parsers-docling
datapizza-ai-tools-duckduckgo

fastapi>=0.100.0
uvicorn[standard]>=0.23.0
pydantic>=2.0.0
python-multipart>=0.0.6
```

### 9.2 Frontend (JavaScript/TypeScript)
```
react@^18.2.0
react-dom@^18.2.0
react-router-dom@^6.0.0
axios@^1.6.0
@tanstack/react-query@^5.0.0
tailwindcss@^3.4.0
lucide-react@^0.300.0
```

---

## 10. Success Criteria

Il progetto sarà considerato completo quando:

1. ✅ Utente può caricare documenti via web UI
2. ✅ Utente può interrogare documenti via chat
3. ✅ API REST documentata con Swagger funzionante
4. ✅ Multi-provider LLM supportato (OpenAI, Google, Anthropic)
5. ✅ RAG pipeline con retrieval e generation funzionante
6. ✅ Containerizzazione Docker funzionante
7. ✅ Test coverage >80%
8. ✅ Documentazione completa

---

**Documento PRD v2.0**  
*Ultimo aggiornamento: 2026-04-06*