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