feat: implement AgenticRAG system with datapizza-ai
Major refactoring from NotebookLM API to Agentic Retrieval System:
## New Features
- AgenticRAG backend powered by datapizza-ai framework
- Web interface for document upload and chat
- REST API with Swagger/OpenAPI documentation
- Document processing pipeline (Docling, chunking, embedding)
- Qdrant vector store integration
- Multi-provider LLM support (OpenAI, Google, Anthropic)
## New Components
- src/agentic_rag/api/ - FastAPI REST API
- Documents API (upload, list, delete)
- Query API (RAG queries)
- Chat API (conversational interface)
- Swagger UI at /api/docs
- src/agentic_rag/services/
- Document service with datapizza-ai pipeline
- RAG service with retrieval + generation
- Vector store service (Qdrant)
- static/index.html - Web UI (upload + chat)
## Dependencies
- datapizza-ai (core framework)
- datapizza-ai-clients-openai
- datapizza-ai-embedders-openai
- datapizza-ai-vectorstores-qdrant
- FastAPI, Pydantic, Qdrant
## API Endpoints
- POST /api/v1/documents - Upload documents
- GET /api/v1/documents - List documents
- POST /api/v1/query - Query knowledge base
- POST /api/v1/chat - Chat interface
- GET /api/docs - Swagger documentation
- GET / - Web UI
🏁 Ready for testing and deployment!
This commit is contained in:
Luca Sacchi Ricciardi
440
prd-v2.md
Normal file
440
prd-v2.md
Normal file
@@ -0,0 +1,440 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user