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

DocuMente - 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