docs: simplify documentation - clarify two separate systems
Some checks are pending
CI / test (3.10) (push) Waiting to run
CI / test (3.11) (push) Waiting to run
CI / test (3.12) (push) Waiting to run
CI / lint (push) Waiting to run

Rewrite documentation to clearly separate the two systems:

README.md Changes:
- Restructure as two independent systems (NotebookLM Agent vs DocuMente)
- Clear separation of requirements:
  * NotebookLM Agent: NO Qdrant needed
  * DocuMente RAG: Qdrant REQUIRED
- Remove confusing 'dual-system' language
- Add FAQ section clarifying common questions
- Simplified examples for each system
- Clear statement: systems work independently

docs/integration.md Changes:
- Remove overly complex architecture diagrams
- Focus on practical usage only
- Simplified to 3 steps: start services → sync → query
- Remove redundant API documentation (refer to SKILL.md)
- Add clear use cases section
- Shorter troubleshooting section

docs/README.md Changes:
- Minimal structure overview
- Clear separation of endpoints by system
- Quick links to relevant docs

Impact:
- 821 lines removed, 259 added
- Much clearer for new users
- No confusion about Qdrant requirements
- Clear distinction between the two systems

Closes documentation clarity issue
This commit is contained in:
Luca Sacchi Ricciardi
2026-04-06 18:48:16 +02:00
parent e239829938
commit 2aa96e9efa
3 changed files with 287 additions and 849 deletions

View File

@@ -1,71 +1,55 @@
# Documentation
# Documentazione
Benvenuto nella documentazione di NotebookLM Agent API.
## Struttura
## Indice
```
docs/
├── README.md # Questo file - panoramica
├── integration.md # Come usare NotebookLM con RAG
└── api/ # Documentazione API dettagliata
```
- [API Reference](./api/) - Documentazione completa delle API (TODO)
- [Examples](./examples/) - Esempi di utilizzo (TODO)
## Guide Rapide
## Panoramica
### Solo NotebookLM Agent
Non serve Qdrant. Vedi [README principale](../README.md) sezione "NotebookLM Agent".
NotebookLM Agent API fornisce:
### NotebookLM + RAG
Serve Qdrant. Vedi [integration.md](./integration.md).
1. **REST API** per gestire notebook, fonti, chat e generazione contenuti
2. **Webhook System** per notifiche event-driven
3. **AI Skill** per integrazione con agenti AI
### API Reference
Endpoint dettagliati in [api/endpoints.md](./api/endpoints.md).
---
## Endpoint Principali
### Notebook Management
- `POST /api/v1/notebooks` - Creare notebook
- `GET /api/v1/notebooks` - Listare notebook
- `GET /api/v1/notebooks/{id}` - Ottenere notebook
- `DELETE /api/v1/notebooks/{id}` - Eliminare notebook
### NotebookLM Agent
```
POST /api/v1/notebooks # Crea notebook
GET /api/v1/notebooks # Lista notebook
POST /api/v1/notebooks/{id}/sources # Aggiungi fonte
POST /api/v1/notebooks/{id}/chat # Chat
POST /api/v1/webhooks # Registra webhook
```
### Source Management
- `POST /api/v1/notebooks/{id}/sources` - Aggiungere fonte
- `GET /api/v1/notebooks/{id}/sources` - Listare fonti
- `POST /api/v1/notebooks/{id}/sources/research` - Ricerca web
### DocuMente RAG
```
POST /api/v1/documents # Upload documento
POST /api/v1/query # Query RAG
POST /api/v1/notebooklm/sync/{id} # Sincronizza notebook
GET /api/v1/notebooklm/indexed # Lista sincronizzati
```
### Content Generation
- `POST /api/v1/notebooks/{id}/generate/audio` - Generare podcast
- `POST /api/v1/notebooks/{id}/generate/video` - Generare video
- `POST /api/v1/notebooks/{id}/generate/quiz` - Generare quiz
- `POST /api/v1/notebooks/{id}/generate/flashcards` - Generare flashcard
### Webhooks
- `POST /api/v1/webhooks` - Registrare webhook
- `GET /api/v1/webhooks` - Listare webhook
- `POST /api/v1/webhooks/{id}/test` - Testare webhook
---
## Autenticazione
Tutte le richieste API richiedono header `X-API-Key`:
```bash
curl http://localhost:8000/api/v1/notebooks \
-H "X-API-Key: your-api-key"
Header richiesto:
```
X-API-Key: your-api-key
```
## Webhook Security
---
I webhook includono firma HMAC-SHA256 nell'header `X-Webhook-Signature`:
```python
import hmac
import hashlib
signature = hmac.new(
secret.encode(),
payload.encode(),
hashlib.sha256
).hexdigest()
```
## Risorse
- [README](../README.md) - Panoramica progetto
- [PRD](../prd.md) - Requisiti prodotto
- [SKILL.md](../SKILL.md) - Skill per agenti AI
- [CONTRIBUTING](../CONTRIBUTING.md) - Come contribuire
Per informazioni complete vedi [SKILL.md](../SKILL.md)