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/README.md
+++ b/README.md
@@ -0,0 +1,176 @@
+# NotebookLM Agent API
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com/)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Tests](https://img.shields.io/badge/tests-pytest-blue.svg)](https://docs.pytest.org/)
+
+> **API e Webhook Interface per Google NotebookLM Automation**
+
+Questo progetto fornisce un'interfaccia API REST completa per Google NotebookLM, con supporto webhook per integrazione con altri agenti AI. Sviluppato seguendo le metodologie **Spec-Driven Development (SDD)** e **Test Driven Development (TDD)**.
+
+## Caratteristiche
+
+- **API REST Completa**: Gestione notebook, fonti, chat, generazione contenuti
+- **Webhook System**: Notifiche event-driven per integrazione multi-agent
+- **AI Skill**: Interfaccia nativa per OpenCode e altri agenti AI
+- **Qualità del Codice**: ≥90% test coverage, type hints, linting
+- **Metodologie**: SDD + TDD + Conventional Commits
+
+## Requisiti
+
+- Python 3.10+
+- [uv](https://github.com/astral-sh/uv) per dependency management
+- Account Google con accesso a NotebookLM
+
+## Installazione
+
+```bash
+# Clona il repository
+git clone https://github.com/example/notebooklm-agent.git
+cd notebooklm-agent
+
+# Crea virtual environment
+uv venv --python 3.10
+source .venv/bin/activate
+
+# Installa dipendenze
+uv sync --extra dev --extra browser
+
+# Installa pre-commit hooks
+uv run pre-commit install
+
+# Configura ambiente
+cp .env.example .env
+# Modifica .env con le tue configurazioni
+```
+
+## Configurazione
+
+Crea un file `.env`:
+
+```env
+# API Configuration
+NOTEBOOKLM_AGENT_API_KEY=your-api-key
+NOTEBOOKLM_AGENT_WEBHOOK_SECRET=your-webhook-secret
+NOTEBOOKLM_AGENT_PORT=8000
+NOTEBOOKLM_AGENT_HOST=0.0.0.0
+
+# NotebookLM Configuration
+NOTEBOOKLM_HOME=~/.notebooklm
+NOTEBOOKLM_PROFILE=default
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FORMAT=json
+```
+
+## Autenticazione NotebookLM
+
+```bash
+# Login a NotebookLM (prima volta)
+notebooklm login
+
+# Verifica autenticazione
+notebooklm auth check
+```
+
+## Avvio
+
+```bash
+# Development server
+uv run fastapi dev src/notebooklm_agent/api/main.py
+
+# Production server
+uv run gunicorn notebooklm_agent.api.main:app -w 4 -k uvicorn.workers.UvicornWorker
+```
+
+L'API sarà disponibile su `http://localhost:8000`
+
+- API docs: `http://localhost:8000/docs`
+- OpenAPI schema: `http://localhost:8000/openapi.json`
+
+## Uso Rapido
+
+```bash
+# Creare notebook
+curl -X POST http://localhost:8000/api/v1/notebooks \
+  -H "X-API-Key: your-key" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Ricerca AI"}'
+
+# Aggiungere fonte
+curl -X POST http://localhost:8000/api/v1/notebooks/{id}/sources \
+  -H "X-API-Key: your-key" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "url", "url": "https://example.com"}'
+
+# Generare podcast
+curl -X POST http://localhost:8000/api/v1/notebooks/{id}/generate/audio \
+  -H "X-API-Key: your-key" \
+  -H "Content-Type: application/json" \
+  -d '{"instructions": "Make it engaging"}'
+```
+
+## Testing
+
+```bash
+# Esegui tutti i test
+uv run pytest
+
+# Con coverage
+uv run pytest --cov=src/notebooklm_agent --cov-report=term-missing
+
+# Solo unit test
+uv run pytest tests/unit/ -m unit
+
+# Solo integration test
+uv run pytest tests/integration/ -m integration
+```
+
+## Sviluppo
+
+### Workflow
+
+1. **Spec-Driven**: Definisci requisiti in `prd.md`
+2. **TDD**: Scrivi test → Implementa → Refactor
+3. **Conventional Commits**: Segui lo standard per i commit
+4. **Pre-commit**: I controlli automatici garantiscono qualità
+
+### Struttura Progetto
+
+```
+notebooklm-agent/
+├── src/notebooklm_agent/    # Codice sorgente
+├── tests/                   # Test suite
+├── docs/                    # Documentazione
+├── prd.md                   # Product Requirements
+├── AGENTS.md                # Linee guida OpenCode
+├── SKILL.md                 # Definizione skill AI
+└── CONTRIBUTING.md          # Guida contribuzione
+```
+
+## Documentazione
+
+- [PRD](./prd.md) - Product Requirements Document
+- [AGENTS.md](./AGENTS.md) - Linee guida per OpenCode
+- [SKILL.md](./SKILL.md) - Skill per agenti AI
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - Come contribuire
+
+## Stato del Progetto
+
+⚠️ **Versione Iniziale**: Questo progetto è in fase di setup iniziale. Le funzionalità API sono pianificate per le prossime release.
+
+Vedi [CHANGELOG.md](./CHANGELOG.md) per lo stato attuale e la roadmap.
+
+## Licenza
+
+MIT License - vedi [LICENSE](./LICENSE) per dettagli.
+
+## Contributing
+
+Vedi [CONTRIBUTING.md](./CONTRIBUTING.md) per le linee guida su come contribuire al progetto.
+
+---
+
+**Nota**: Questo è un progetto non ufficiale e non è affiliato con Google. Usa le API interne di NotebookLM che possono cambiare senza preavviso.