documente/prd.md

# Product Requirements Document (PRD)

## NotebookLM Agent API

**Versione:** 1.0.0  
**Data:** 2026-04-05  
**Autore:** NotebookLM Agent Team  
**Status:** Draft

---

## 1. Panoramica del Prodotto

### 1.1 Nome del Prodotto
**NotebookLM Agent API** - Un agente LLM che fornisce accesso programmatico a Google NotebookLM tramite interfaccia API con webhook.

### 1.2 Descrizione
Sistema agentico basato su Python che integra Google NotebookLM tramite la libreria `notebooklm-py`, offrendo:
- Interfaccia API REST per automazione
- Webhook per integrazione con altri agenti AI
- Skill nativa per agenti AI (OpenCode, Claude, Codex)
- Metodologia Spec-Driven Development (SDD)
- Test Driven Development (TDD)

### 1.3 Obiettivi Principali
1. Fornire accesso programmatico completo a NotebookLM
2. Creare un'interfaccia API standardizzata per integrazione multi-agent
3. Supportare workflow automatizzati di ricerca e generazione contenuti
4. Garantire qualità del codice attraverso TDD e SDD

---

## 2. Obiettivi

### 2.1 Obiettivi di Business
- [ ] Creare un servizio API stabile per NotebookLM
- [ ] Supportare integrazione con ecosistema AI multi-agent
- [ ] Fornire webhook per event-driven architecture
- [ ] Garantire manutenibilità attraverso test automatizzati (>90% coverage)

### 2.2 Obiettivi Utente
- [ ] Creare notebook e gestire fonti programmaticamente
- [ ] Generare contenuti (audio, video, quiz, flashcard) via API
- [ ] Ricevere notifiche webhook su completamento operazioni
- [ ] Integrare con altri agenti AI tramite API standard

### 2.3 Metriche di Successo (KPI)
| Metrica | Target | Note |
|---------|--------|------|
| Code Coverage | ≥90% | Pytest + coverage |
| API Uptime | ≥99.5% | Per operazioni core |
| Response Time (API) | <500ms | Per operazioni sync |
| Webhook Delivery | ≥99% | Con retry automatico |
| Test Pass Rate | 100% | CI/CD gate |

---

## 3. Pubblico Target

### 3.1 Persona 1: AI Agent Developer
- **Ruolo:** Sviluppatore di agenti AI
- **Needs:** API stabile, webhook affidabili, documentazione chiara
- **Frustrazioni:** API instabili, mancanza di webhook, documentazione scarsa
- **Obiettivi:** Integrare NotebookLM nel proprio agente AI

### 3.2 Persona 2: Automation Engineer
- **Ruolo:** Ingegnere automazione
- **Needs:** Automazione research-to-content, batch processing
- **Frustrazioni:** Processi manuali ripetitivi
- **Obiettivi:** Pipeline automatizzate di ricerca e generazione

### 3.3 Persona 3: Content Creator
- **Ruolo:** Creatore di contenuti
- **Needs:** Generazione podcast/video da fonti multiple
- **Frustrazioni:** Operazioni manuali su NotebookLM
- **Obiettivi:** Workflow automatizzato research → content

---

## 4. Requisiti Funzionali

### 4.1 Core: API REST

#### REQ-001: Gestione Notebook
**Priorità:** Alta  
**Descrizione:** CRUD operazioni su notebook NotebookLM
**Criteri di Accettazione:**
- [ ] POST /api/v1/notebooks - Creare notebook
- [ ] GET /api/v1/notebooks - Listare notebook
- [ ] GET /api/v1/notebooks/{id} - Ottenere dettagli
- [ ] DELETE /api/v1/notebooks/{id} - Eliminare notebook
- [ ] PATCH /api/v1/notebooks/{id} - Aggiornare notebook

**User Story:**  
*"Come sviluppatore, voglio creare e gestire notebook via API per automatizzare workflow"*

#### REQ-002: Gestione Fonti
**Priorità:** Alta  
**Descrizione:** Aggiungere e gestire fonti (URL, PDF, YouTube, Drive)
**Criteri di Accettazione:**
- [ ] POST /api/v1/notebooks/{id}/sources - Aggiungere fonte
- [ ] GET /api/v1/notebooks/{id}/sources - Listare fonti
- [ ] DELETE /api/v1/notebooks/{id}/sources/{source_id} - Rimuovere fonte
- [ ] GET /api/v1/notebooks/{id}/sources/{source_id}/fulltext - Ottenere testo indicizzato
- [ ] POST /api/v1/notebooks/{id}/sources/research - Avviare ricerca web/Drive

**User Story:**  
*"Come utente, voglio aggiungere fonti programmaticamente per analisi bulk"*

#### REQ-003: Chat e Query
**Priorità:** Alta  
**Descrizione:** Interagire con i contenuti tramite chat
**Criteri di Accettazione:**
- [ ] POST /api/v1/notebooks/{id}/chat - Inviare messaggio
- [ ] GET /api/v1/notebooks/{id}/chat/history - Ottenere storico
- [ ] POST /api/v1/notebooks/{id}/chat/save - Salvare risposta come nota

**User Story:**  
*"Come utente, voglio interrogare le fonti via API per estrarre insights"*

#### REQ-004: Generazione Contenuti
**Priorità:** Alta  
**Descrizione:** Generare tutti i tipi di contenuto NotebookLM
**Criteri di Accettazione:**
- [ ] POST /api/v1/notebooks/{id}/generate/audio - Generare podcast
- [ ] POST /api/v1/notebooks/{id}/generate/video - Generare video
- [ ] POST /api/v1/notebooks/{id}/generate/slide-deck - Generare slide
- [ ] POST /api/v1/notebooks/{id}/generate/infographic - Generare infografica
- [ ] POST /api/v1/notebooks/{id}/generate/quiz - Generare quiz
- [ ] POST /api/v1/notebooks/{id}/generate/flashcards - Generare flashcard
- [ ] POST /api/v1/notebooks/{id}/generate/report - Generare report
- [ ] POST /api/v1/notebooks/{id}/generate/mind-map - Generare mappa mentale
- [ ] POST /api/v1/notebooks/{id}/generate/data-table - Generare tabella dati

**User Story:**  
*"Come creatore, voglio generare contenuti multi-formato automaticamente"*

#### REQ-005: Gestione Artifacts
**Priorità:** Alta  
**Descrizione:** Monitorare e scaricare contenuti generati
**Criteri di Accettazione:**
- [ ] GET /api/v1/notebooks/{id}/artifacts - Listare artifacts
- [ ] GET /api/v1/notebooks/{id}/artifacts/{artifact_id}/status - Controllare stato
- [ ] GET /api/v1/notebooks/{id}/artifacts/{artifact_id}/download - Scaricare artifact
- [ ] POST /api/v1/notebooks/{id}/artifacts/{artifact_id}/wait - Attendere completamento

**User Story:**  
*"Come utente, voglio scaricare contenuti generati in vari formati"*

### 4.2 Core: Webhook System

#### REQ-006: Webhook Management
**Priorità:** Alta  
**Descrizione:** Gestire endpoint webhook per notifiche eventi
**Criteri di Accettazione:**
- [ ] POST /api/v1/webhooks - Registrare webhook
- [ ] GET /api/v1/webhooks - Listare webhook registrati
- [ ] DELETE /api/v1/webhooks/{id} - Rimuovere webhook
- [ ] POST /api/v1/webhooks/{id}/test - Testare webhook

**User Story:**  
*"Come sviluppatore, voglio ricevere notifiche su eventi NotebookLM"*

#### REQ-007: Eventi Webhook
**Priorità:** Alta  
**Descrizione:** Inviare notifiche su eventi specifici
**Criteri di Accettazione:**
- [ ] source.added - Nuova fonte aggiunta
- [ ] source.ready - Fonte indicizzata e pronta
- [ ] artifact.generated - Artifact generato con successo
- [ ] artifact.failed - Generazione artifact fallita
- [ ] research.completed - Ricerca completata
- [ ] notebook.shared - Notebook condiviso

**User Story:**  
*"Come agente AI, voglio essere notificato quando un contenuto è pronto"*

#### REQ-008: Webhook Reliability
**Priorità:** Media  
**Descrizione:** Garantire affidabilità delivery webhook
**Criteri di Accettazione:**
- [ ] Retry automatico con exponential backoff
- [ ] Firma HMAC per verifica autenticità
- [ ] Timeout configurabile (default: 30s)
- [ ] Delivery tracking con ID univoco

**User Story:**  
*"Come sviluppatore, voglio webhook affidabili con verifica sicurezza"*

### 4.3 Core: Skill AI

#### REQ-009: Skill OpenCode
**Priorità:** Alta  
**Descrizione:** Skill nativa per OpenCode CLI
**Criteri di Accettazione:**
- [ ] File SKILL.md conforme specifiche OpenCode
- [ ] Comandi natural language supportati
- [ ] Autonomy rules definite
- [ ] Error handling documentato

**User Story:**  
*"Come utente OpenCode, voglio usare NotebookLM tramite comandi naturali"*

#### REQ-010: Multi-Agent Integration
**Priorità:** Media  
**Descrizione:** Supporto per integrazione con altri agenti AI
**Criteri di Accettazione:**
- [ ] API Key authentication per agenti
- [ ] Rate limiting per tenant
- [ ] Isolamento risorse per agente

---

## 5. Requisiti Non Funzionali

### 5.1 Performance
- API Response Time: <500ms per operazioni sincrone
- Webhook Delivery: <5s dalla generazione evento
- Throughput: 100 req/s per endpoint API
- Connessioni concorrenti: ≥1000

### 5.2 Sicurezza
- API Key authentication per tutti gli endpoint
- HTTPS obbligatorio in produzione
- HMAC signature per webhook
- Sanitizzazione input (prevenzione injection)
- Nessuna persistenza credenziali NotebookLM (usa storage_state.json)

### 5.3 Affidabilità
- Uptime target: 99.5%
- Retry automatico per operazioni fallite
- Circuit breaker per API esterne (NotebookLM)
- Graceful degradation su rate limiting

### 5.4 Scalabilità
- Architettura stateless
- Supporto per horizontal scaling
- Queue-based processing per operazioni lunghe
- Caching risultati dove appropriato

### 5.5 Monitoring
- Logging strutturato (JSON)
- Metrics (Prometheus-compatible)
- Health check endpoints
- Alerting su errori critici

---

## 6. Stack Tecnologico

### 6.1 Core Technologies
| Componente | Tecnologia | Versione |
|------------|------------|----------|
| Language | Python | ≥3.10 |
| Framework API | FastAPI | ≥0.100 |
| Async | asyncio | built-in |
| HTTP Client | httpx | ≥0.27 |
| Validation | Pydantic | ≥2.0 |

### 6.2 NotebookLM Integration
| Componente | Tecnologia | Note |
|------------|------------|------|
| NotebookLM Client | notebooklm-py | ≥0.3.4 |
| Auth | playwright | Per browser login |
| Storage | Local JSON | storage_state.json |

### 6.3 Testing & Quality
| Componente | Tecnologia | Scopo |
|------------|------------|-------|
| Testing | pytest | Unit/Integration/E2E |
| Coverage | pytest-cov | ≥90% target |
| Linting | ruff | Code quality |
| Type Check | mypy | Static typing |
| Pre-commit | pre-commit | Git hooks |

### 6.4 DevOps
| Componente | Tecnologia | Scopo |
|------------|------------|-------|
| Package | uv | Dependency management |
| Build | hatchling | Package building |
| Git | conventional commits | Standardizzazione commit |
| Changelog | common-changelog | Gestione changelog |

---

## 7. Architettura

### 7.1 System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Clients                              │
│  (OpenCode, Claude, Codex, Custom Agents, Direct API)      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   NotebookLM Agent API                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  REST API   │  │   Webhook   │  │   Skill Interface   │  │
│  │   Layer     │  │   Manager   │  │                     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Service   │  │   Event     │  │   Queue/Worker      │  │
│  │    Layer    │  │   Bus       │  │   (Celery/RQ)       │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              NotebookLM-py Client Library                   │
│              (Async wrapper + RPC handling)                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Google NotebookLM                         │
│              (Undocumented Internal APIs)                    │
└─────────────────────────────────────────────────────────────┘
```

### 7.2 API Structure

```
/api/v1/
├── notebooks/
│   ├── GET    /                    # List
│   ├── POST   /                    # Create
│   ├── GET    /{id}                # Get
│   ├── DELETE /{id}                # Delete
│   ├── PATCH  /{id}                # Update
│   ├── sources/
│   │   ├── GET    /                # List sources
│   │   ├── POST   /                # Add source
│   │   ├── DELETE /{source_id}     # Remove source
│   │   ├── GET    /{source_id}/fulltext
│   │   └── POST   /research        # Web/Drive research
│   ├── chat/
│   │   ├── POST   /                # Send message
│   │   ├── GET    /history         # Get history
│   │   └── POST   /save            # Save as note
│   ├── generate/
│   │   ├── POST   /audio
│   │   ├── POST   /video
│   │   ├── POST   /slide-deck
│   │   ├── POST   /infographic
│   │   ├── POST   /quiz
│   │   ├── POST   /flashcards
│   │   ├── POST   /report
│   │   ├── POST   /mind-map
│   │   └── POST   /data-table
│   └── artifacts/
│       ├── GET    /                # List
│       ├── GET    /{id}/status     # Status
│       ├── GET    /{id}/download   # Download
│       └── POST   /{id}/wait       # Wait completion
├── webhooks/
│   ├── GET    /                    # List
│   ├── POST   /                    # Register
│   ├── DELETE /{id}                # Remove
│   └── POST   /{id}/test           # Test
└── health/
    ├── GET    /                    # Health check
    └── GET    /ready               # Readiness probe
```

---

## 8. Metodologia di Sviluppo

### 8.1 Spec-Driven Development (SDD)
1. **Specifica:** Definire requisiti e API contract prima del codice
2. **Review:** Revisione specifica con stakeholder
3. **Implementazione:** Sviluppo seguendo la spec
4. **Validazione:** Verifica conformità alla spec

### 8.2 Test Driven Development (TDD)
1. **Red:** Scrivere test che fallisce
2. **Green:** Implementare codice minimo per passare il test
3. **Refactor:** Migliorare codice mantenendo test pass

### 8.3 Testing Strategy
| Livello | Scope | Tools | Coverage |
|---------|-------|-------|----------|
| Unit | Funzioni isolate | pytest, mock | ≥90% |
| Integration | Componenti integrati | pytest, httpx | ≥80% |
| E2E | Flussi completi | pytest, real API | Key paths |

### 8.4 Conventional Commits
```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

**Types:** feat, fix, docs, style, refactor, test, chore, ci  
**Scopes:** api, webhook, skill, notebook, source, artifact, auth

---

## 9. Piano di Rilascio

### 9.1 Milestone

| Milestone | Data | Features | Stato |
|-----------|------|----------|-------|
| v0.1.0 | 2026-04-15 | Core API (notebook, source, chat) | Pianificato |
| v0.2.0 | 2026-04-30 | Generazione contenuti + webhook | Pianificato |
| v0.3.0 | 2026-05-15 | Skill OpenCode + multi-agent | Pianificato |
| v1.0.0 | 2026-06-01 | Production ready + docs complete | Pianificato |

### 9.2 Roadmap
- **Q2 2026:** Core features, stabilizzazione API
- **Q3 2026:** Advanced features, performance optimization
- **Q4 2026:** Enterprise features, scaling improvements

---

## 10. Analisi dei Rischi

| Rischio | Probabilità | Impatto | Mitigazione |
|---------|-------------|---------|-------------|
| API NotebookLM cambiano | Alta | Alto | Wrapper abstraction, monitoring |
| Rate limiting agressivo | Media | Medio | Retry logic, queue-based processing |
| Auth session scade | Media | Medio | Refresh automatico, alerting |
| Webhook delivery fallisce | Media | Medio | Retry con backoff, dead letter queue |
| Breaking changes notebooklm-py | Bassa | Alto | Version pinning, vendor tests |

---

## 11. Note e Assunzioni

### 11.1 Assunzioni
- Utente ha account Google valido con accesso NotebookLM
- `notebooklm-py` è installato e funzionante
- Playwright configurato per autenticazione browser
- Ambiente Python 3.10+ disponibile

### 11.2 Dipendenze Esterne
- Google NotebookLM (undocumented APIs)
- notebooklm-py library
- Playwright (browser automation)

### 11.3 Vincoli
- Nessuna persistenza server-side per credenziali
- Rate limits di NotebookLM applicati
- Alcune operazioni sono asincrone per natura

---

## 12. Approvazioni

| Ruolo | Nome | Firma | Data |
|-------|------|-------|------|
| Product Owner | | | |
| Tech Lead | | | |
| QA Lead | | | |

---

## 13. Cronologia Revisioni

| Versione | Data | Autore | Modifiche |
|----------|------|--------|-----------|
| 0.1.0 | 2026-04-05 | NotebookLM Agent Team | Bozza iniziale |

---

**Documento PRD**  
*Ultimo aggiornamento: 2026-04-05*