Metadata-Version: 2.4
Name: perplexity-notebooklm
Version: 0.3.0
Summary: Integração dual NotebookLM <-> Perplexity (conta Pro, sem API key) via MCP + skill
Project-URL: Homepage, https://github.com/wgardim-hub/notebooklm2perplexity
Project-URL: Repository, https://github.com/wgardim-hub/notebooklm2perplexity
Author: wgardim
License: MIT
License-File: LICENSE
Keywords: mcp,no-api-key,notebooklm,perplexity,research
Requires-Python: <3.14,>=3.10
Requires-Dist: curl-cffi>=0.5.7
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: all
Requires-Dist: model2vec>=0.8.0; extra == 'all'
Requires-Dist: notebooklm-mcp>=2.0.11; extra == 'all'
Requires-Dist: notebooklm-py>=0.7.2; extra == 'all'
Requires-Dist: selenium>=4.0.0; extra == 'all'
Provides-Extra: notebooklm
Requires-Dist: notebooklm-mcp>=2.0.11; extra == 'notebooklm'
Requires-Dist: notebooklm-py>=0.7.2; extra == 'notebooklm'
Requires-Dist: selenium>=4.0.0; extra == 'notebooklm'
Provides-Extra: semantic
Requires-Dist: model2vec>=0.8.0; extra == 'semantic'
Description-Content-Type: text/markdown

<div align="center">

<img src="docs/assets/banner.svg" alt="Perplexity ⇄ NotebookLM" width="100%">

**English** · [Português 🇧🇷](README.pt-BR.md)

### The missing bridge between **Perplexity's** web intelligence and **NotebookLM's** knowledge base — driven by Claude Code, with **zero paid API keys.**

[![version](https://img.shields.io/badge/version-0.2.0-blue)](https://github.com/wgardim-hub/notebooklm2perplexity/releases)
[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![python](https://img.shields.io/badge/python-3.13-3776ab)](pyproject.toml)
[![no API key](https://img.shields.io/badge/API%20key-not%20required-success)]()
[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-7c3aed)]()

</div>

---

## Why this exists

You research on **Perplexity**. You build knowledge on **NotebookLM**. Today they don't talk —
you copy-paste between tabs, lose citations, and re-research the same topics.

This project closes the loop. It's the **only** tool that wires Perplexity and NotebookLM
**both ways**, using your **Pro accounts** (cookies) instead of paid API keys — so it costs
you nothing beyond subscriptions you already pay for.

```mermaid
flowchart LR
    subgraph PPLX["🔎 Perplexity Pro"]
        S[search / reason / deep research<br/>+ citations]
    end
    subgraph NLM["📓 NotebookLM"]
        N[sources · summaries · audio/video/mind-map]
    end
    S -- "research → source (verified, deduped)" --> N
    N -- "summary → enrich / fact-check" --> S
    C[/"Claude Code<br/>orchestrator"/] -.drives.- S
    C -.drives.- N
```

---

## What you get

| | Capability |
|---|---|
| 🔁 | **Bidirectional dual flow** — research → notebook source, *and* notebook → enriched research. Nobody else does both. |
| 🔑 | **No paid API keys** — Perplexity via account cookies; NotebookLM via a one-time cookie-bridge. |
| 📎 | **Citations preserved** — replicates the SSE recipe that surfaces real web sources. |
| 🧹 | **4-layer dedup** — never ingest the same thing twice (query → exact → near-verbatim → **semantic embeddings**, all local). |
| 🛡️ | **Adversarial citation verification** — drops hallucinated/dead sources before they reach your notebook. |
| 🤖 | **Agentic deep-research** — decomposes a question, searches each angle, synthesizes a cited report. |
| 🎧 | **Media pipeline** — turn research into a NotebookLM audio overview, video, or mind-map in one call. |
| 👁️ | **Continuous watcher** — monitors notebooks for real changes (stable source-id signal) with hard ToS guards. |
| 🔌 | **Ships as a Claude Code plugin** — `/dual-research`, `/notebook-enrich`, MCP server, session hook. |

---

## Quickstart

> Prereqs: **[uv](https://docs.astral.sh/uv/)** on PATH + **Python 3.12/3.13** (not 3.14). uv handles the venv & deps. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).

```bash
# 1. Install as a Claude Code plugin (brings MCP + commands + skill + hook).
#    uv run auto-creates the venv on first launch — cross-OS, no hardcoded paths.
/plugin marketplace add wgardim-hub/notebooklm2perplexity
/plugin install perplexity-notebooklm@perplexity-notebooklm-dev   # restart Claude Code

# 2. Guided login (pulls cookies from a logged-in Chrome — no manual paste).
#    Open once: chrome --remote-debugging-port=9222 --user-data-dir="<profile>"
#    logged into perplexity.ai AND NotebookLM, then:
uv run --directory <repo> perplexity-nlm-auth

# 3. Verify everything ("did I configure it right?")
uv run --directory <repo> perplexity-nlm-doctor
```

> One canonical path. **Don't** also copy the skill into `~/.claude/skills/` — the plugin ships it.
> The package is self-contained (no vendored deps) — once published to PyPI, the MCP runs via
> `uvx perplexity-notebooklm`. Manual install & `python -m perplexity_mcp.server`: see [`docs/INSTALL.md`](docs/INSTALL.md).

---

## The two flows

```python
from dual_flow import research_to_notebook, notebook_to_research, research_to_media

# Perplexity → NotebookLM  (research becomes a verified, deduped source)
research_to_notebook("State of commercial fusion in 2026", NB, tool="research",
                     verify=True, dedup=True)

# NotebookLM → Perplexity  (read the notebook, fact-check & update against the live web)
notebook_to_research(NB, tool="search")

# Research → media  (source + audio / video / mind-map in one call)
research_to_media("AI in real estate 2026", NB, kind="mind_map")
```

> **NotebookLM auth:** Google blocks automated logins, so the first run needs a real
> Chrome you control:
> `chrome.exe --remote-debugging-port=9222 --user-data-dir="D:\nlm-chrome"` (log in once).
> After that it's pure HTTP with automatic cookie re-bridge.

---

## Architecture

```
perplexity_mcp/      MCP server · pluggable backend (helallao) · cited_search
                     resilience (retry/jitter/rate-limit) · security · validate
                     verify_citations (adversarial) · agentic (deep-research)
notebooklm_write/    nlm_http (notebooklm-py HTTP/RPC + cookie-bridge) · add_source (Selenium fallback)
                     ledger (4-layer dedup) · embed (local model2vec)
dual_flow.py         the bidirectional orchestration
rag.py · watch.py    cross-notebook BM25 retrieval · change watcher
evals/ · skills/     regression harness · Claude Code skill
.claude-plugin/      plugin manifest · commands · hooks
```

**Design principles:** small, single-purpose modules · pluggable Perplexity backend
(swap providers without touching callers) · graceful degradation everywhere (no Chrome →
clean error; no embedder → falls back to MinHash; stale cookie → auto re-bridge) ·
eval harness as a regression gate · honest about limits.

### Dedup, in 4 layers (cheapest first)

| Layer | Catches | Cost |
|-------|---------|------|
| **Query** | re-researching the same topic | free (skips *before* the Pro call) |
| **Exact hash** | identical content | free |
| **MinHash** | near-verbatim edits | free |
| **Semantic** | reworded / paraphrased (cosine ≈ 0.90) | local embedding, no API |

---

## Reliability & safety

- **Resilience:** exponential backoff + full jitter, rate limiting, single-flight auth refresh.
- **Your accounts, your cookies:** every user authenticates with **their own** Perplexity/NotebookLM. Credentials live only in your local `.env` + `~/.notebooklm/` (git-ignored, never committed, never shipped in the package). Nothing personal is bundled — a fresh install has zero cookies; you run `perplexity-nlm-auth` to pull your own.
- **Security:** secrets only in `.env` (git-ignored); cookie values never logged (redaction); file perms hardened.
- **ToS-aware automation:** the watcher defaults to dry-run, enforces a ≥10-min poll floor, an interruptible kill-switch, and writes only through an explicit callback with a human checkpoint.
- **Tested:** eval harness (`evals/run.py`) + end-to-end validation on real accounts (dual flow, 44-notebook RAG, dedup, watcher).

---

## Honest limitations

A senior project says what it *doesn't* do:

- Built on **unofficial** Perplexity/NotebookLM interfaces — they can change; expect occasional maintenance.
- Continuous automation against your accounts carries inherent **ToS risk** — use sparingly.
- Semantic dedup needs the optional local model; without it, dedup falls back to lexical.
- NotebookLM write/read needs a logged-in Chrome on the debug port (Google blocks headless login).

---

## Roadmap

See [`docs/INNOVATION.md`](docs/INNOVATION.md) for the full ranked roadmap, and
[`docs/BENCHMARK.md`](docs/BENCHMARK.md) for how this compares against 7 ecosystem projects.

## License

MIT — see [`LICENSE`](LICENSE). Not affiliated with Perplexity AI or Google.
