feat(api): implement notebook management CRUD endpoints

Implement Sprint 1: Notebook Management CRUD - Add NotebookService with full CRUD operations - Add POST /api/v1/notebooks (create notebook) - Add GET /api/v1/notebooks (list with pagination) - Add GET /api/v1/notebooks/{id} (get by ID) - Add PATCH /api/v1/notebooks/{id} (partial update) - Add DELETE /api/v1/notebooks/{id} (delete) - Add Pydantic models for requests/responses - Add custom exceptions (ValidationError, NotFoundError, NotebookLMError) - Add comprehensive unit tests (31 tests, 97% coverage) - Add API integration tests (26 tests) - Fix router prefix duplication - Fix JSON serialization in error responses BREAKING CHANGE: None
2026-04-06 01:13:13 +02:00
commit 4b7a419a98
65 changed files with 10507 additions and 0 deletions
--- a/prd.md
+++ b/prd.md
@@ -0,0 +1,472 @@
+# 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*