notebooklm-easy 0.1.0__tar.gz

notebooklm_easy-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: notebooklm-easy
+Version: 0.1.0
+Summary: A synchronous, one-call-per-task convenience wrapper around notebooklm-py
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: notebooklm-py<0.9,>=0.8.2
+Provides-Extra: browser
+Requires-Dist: notebooklm-py[browser]; extra == "browser"
+Provides-Extra: cookies
+Requires-Dist: notebooklm-py[cookies]; extra == "cookies"
+Provides-Extra: headless
+Requires-Dist: notebooklm-py[headless]; extra == "headless"
+
+# notebooklm-easy
+
+A synchronous, one-call-per-task convenience wrapper around
+[`notebooklm-py`](https://github.com/teng-lin/notebooklm-py) — the unofficial
+Python API for Google NotebookLM / Gemini Notebook.
+
+`notebooklm-py` itself is fully async and, for every generated artifact
+(podcast, video, quiz, ...), a three-step dance: `generate_*()` kicks it
+off, `wait_for_completion()` polls it, and a matching `download_*()` fetches
+the finished file. That's the right shape for a library embedded in an
+existing async app. This wrapper is for the much more common case — a plain
+script — and does two things:
+
+1. **No `async`/`await`.** Every method is a normal blocking call. You don't
+   write `async def main(): ...; asyncio.run(main())` at all.
+2. **One call per artifact**, not three. `nlm.audio(nb.id, "podcast.mp3")`
+   generates, waits, and downloads in a single line.
+
+It does not reimplement anything — auth, RPC calls, polling, and downloads
+are all still done by `notebooklm-py` itself. This is a thin facade over it.
+Anything it doesn't wrap is still reachable (see [Escape hatch](#escape-hatch)).
+
+## Install
+
+```bash
+pip install notebooklm-py notebooklm-easy   # or: pip install -e . from this folder
+```
+
+`notebooklm-easy` depends on `notebooklm-py` and does not vendor it — you're
+always running the real, upstream library underneath.
+
+You still need to authenticate once with `notebooklm-py`'s own CLI (this
+wrapper doesn't change auth at all — see its
+[Installation guide](https://github.com/teng-lin/notebooklm-py/blob/main/docs/installation.md)
+for the full picture):
+
+```bash
+pip install "notebooklm-py[browser]"
+notebooklm login                      # opens a browser once
+notebooklm auth check --test --json   # confirms it worked
+```
+
+After that, `notebooklm_easy.NotebookLM()` (no arguments) picks up the saved
+session automatically, exactly like `NotebookLMClient.from_storage()` does.
+
+## Quick start
+
+```python
+from notebooklm_easy import NotebookLM
+
+with NotebookLM() as nlm:
+    # Reuses a notebook with this exact title if one exists, else creates it
+    nb = nlm.get_or_create_notebook("Research")
+
+    # Add sources — URLs and local file paths, auto-detected, uploaded
+    # concurrently, and waited-on by default so the next call can use them
+    nlm.add_sources(nb.id, [
+        "https://en.wikipedia.org/wiki/Artificial_intelligence",
+        "./paper.pdf",
+    ])
+
+    # Ask a question — returns just the answer text
+    print(nlm.ask(nb.id, "What are the key themes?"))
+
+    # Generate + wait + download, in one call each
+    nlm.audio(nb.id, "podcast.mp3", instructions="make it engaging")
+    nlm.quiz(nb.id, "quiz.json", difficulty="hard")
+    nlm.report(nb.id, "briefing.md", format="briefing_doc")
+```
+
+That's the whole shape of the library: a `NotebookLM` object, used as a
+context manager (or with explicit `.close()`), with one method per thing
+you want to do.
+
+## Auth / multiple accounts
+
+`NotebookLM(...)` accepts every keyword `NotebookLMClient.from_storage()`
+does, and passes them straight through — most commonly `profile` for
+switching between `notebooklm login --profile <name>` accounts, and
+`backend="android"` to use the Android gRPC backend instead of the default
+web one:
+
+```python
+with NotebookLM(profile="work") as nlm:
+    ...
+```
+
+## Notebooks
+
+```python
+nlm.create_notebook("Title")          # always creates a new one
+nlm.get_or_create_notebook("Title")   # reuses an existing notebook with this exact title
+nlm.list_notebooks()                  # -> list[Notebook]
+nlm.delete_notebook(notebook_id)
+```
+
+## Sources
+
+```python
+# One source — auto-detects URL (http/https, including YouTube) vs. an
+# existing local file path (PDF, text, Markdown, Word, EPUB, audio, video,
+# image — whatever notebooklm-py's add_file supports).
+nlm.add_source(nb.id, "https://example.com")
+nlm.add_source(nb.id, "./report.pdf")
+
+# Several at once, uploaded concurrently, in the same order back:
+sources = nlm.add_sources(nb.id, ["https://a.example", "./b.pdf", "https://youtube.com/watch?v=..."])
+
+# Raw pasted text has no URL/path to auto-detect, so it's its own method:
+nlm.add_text(nb.id, "My Notes", "... text content ...")
+```
+
+All three default to `wait=True` — they block until NotebookLM finishes
+processing the source, so the very next `ask()` or `generate_*` call sees
+it. Pass `wait=False` to fire-and-forget instead (matching
+`notebooklm-py`'s own default).
+
+## Chat
+
+```python
+answer = nlm.ask(nb.id, "Summarize this")                  # -> str, just the answer
+result = nlm.ask_full(nb.id, "Summarize this")              # -> AskResult (citations, conversation_id, ...)
+```
+
+## Generating content
+
+One method per artifact type. Each does `generate_* -> wait_for_completion
+-> download_*` and returns the path it wrote to. Every enum-typed option
+(`format`, `difficulty`, `style`, ...) accepts a plain, case-insensitive
+string as well as the real `notebooklm.types` enum member — `"hard"` and
+`QuizDifficulty.HARD` both work.
+
+```python
+nlm.audio(nb.id, "podcast.mp3", instructions="make it fun", format="deep_dive", length="short")
+nlm.video(nb.id, "overview.mp4", format="explainer", style="whiteboard")
+nlm.cinematic_video(nb.id, "documentary.mp4", instructions="documentary-style summary")
+nlm.report(nb.id, "briefing.md", format="briefing_doc")       # or study_guide / blog_post / concept_explanation / custom
+nlm.study_guide(nb.id, "study_guide.md")
+nlm.quiz(nb.id, "quiz.json", difficulty="hard", quantity="more", output_format="json")   # or markdown / html
+nlm.flashcards(nb.id, "cards.json", difficulty="easy")
+nlm.slide_deck(nb.id, "slides.pdf", format="presenter_slides", output_format="pdf")       # or pptx
+nlm.infographic(nb.id, "infographic.png", orientation="portrait", style="bento_grid")
+nlm.data_table(nb.id, "data.csv", instructions="compare key concepts")
+nlm.mind_map(nb.id, "mindmap.json", kind="interactive")        # or "note_backed"
+```
+
+Every one of these takes `source_ids=[...]` to scope generation to specific
+sources (default: all of them), and `timeout=<seconds>` to override how
+long it waits before giving up (defaults are generous — 300s for most
+types, 600s for video/slide-deck/audio, which tend to run longer).
+
+### Handling failure
+
+If generation finishes in a `failed` or `removed` (delisted, e.g. after a
+daily quota rejection) state, these methods raise `GenerationFailedError`
+instead of silently returning a broken path:
+
+```python
+from notebooklm_easy import GenerationFailedError
+
+try:
+    nlm.audio(nb.id, "podcast.mp3")
+except GenerationFailedError as e:
+    print(e.status.error, e.status.error_code)   # the raw GenerationStatus is on .status
+```
+
+Every other error — auth problems, rate limits, network issues, a bad
+notebook id — is exactly whatever `notebooklm-py` itself raises (see its
+[`exceptions.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/exceptions.py)),
+unchanged. This wrapper doesn't catch or reshape those.
+
+## Escape hatch
+
+Anything this wrapper doesn't cover — sharing, labels, research, notes,
+collections, settings, the `raw` backend-selected wire access, or a
+`generate_*`/`download_*` combination not wrapped as its own method — is
+still one call away. Every `NotebookLM` instance exposes the real async
+client:
+
+```python
+with NotebookLM() as nlm:
+    # nlm.client is the actual notebooklm.NotebookLMClient — every
+    # namespace (sharing, labels, research, notes, collections, raw, ...)
+    # is there, unwrapped.
+    coro = nlm.client.sharing.set_public(nb.id, view_level="editor")
+    nlm.run(coro)   # runs it on the same background loop as everything else
+```
+
+**Important:** don't `await` `nlm.client.<...>(...)` yourself from a
+different `asyncio` context (e.g. inside your own `async def`) — always go
+through `nlm.run(coro)`. `notebooklm-py`'s client is loop-bound (it asserts
+every call happens on the exact event loop it was opened on); `NotebookLM`
+opens it on a dedicated background loop and `run()` is what submits work to
+that same loop correctly. See `notebooklm_easy/_loop.py` for the full
+rationale.
+
+If your program is *already* async end-to-end, skip this wrapper entirely
+and use `notebooklm.NotebookLMClient` directly — that's what it's for.
+
+## Using this inside a bot (or any other async app)
+
+`NotebookLM` is synchronous — every method blocks the calling thread until
+it's done (`ask()` for a few seconds, a generated artifact for a minute or
+more). That's fine in a plain script, but calling it directly inside an
+`async def` handler of an asyncio-based bot (kurigram/pyrogram, aiogram,
+discord.py, ...) freezes that bot's entire event loop — every other
+chat/user — for as long as the call takes, since asyncio is single-threaded.
+
+The fix: create **one** `NotebookLM()` for the whole bot process (not one
+per request — see why in the example), and reach every blocking call
+through `asyncio.to_thread(...)` from inside your `async def` handlers, so
+it runs on a worker thread instead of the bot's event loop.
+`examples/telegram_notes_bot.py` is a complete, runnable example of exactly
+this: a kurigram/pyrogram bot with a `/notes <youtube_link>` command that
+adds the video as a source and returns notes, done correctly.
+
+## Testing without live Google auth
+
+`tests/test_smoke.py` exercises the whole wrapper (notebook get-or-create,
+source auto-detection, bulk add, chat, one-call generate+wait+download,
+failure handling, enum coercion, and — importantly — that every call really
+does run on the one background loop) against the real installed
+`notebooklm-py` types, with only `NotebookLMClient.from_storage` swapped for
+a fake that never touches the network. Useful both as a regression test and
+as a template if you want to unit-test your own code that uses this wrapper
+without a live Google session.
+
+```bash
+pip install pytest
+pytest tests/
+```

notebooklm_easy-0.1.0/README.md

@@ -0,0 +1,231 @@
+# notebooklm-easy
+
+A synchronous, one-call-per-task convenience wrapper around
+[`notebooklm-py`](https://github.com/teng-lin/notebooklm-py) — the unofficial
+Python API for Google NotebookLM / Gemini Notebook.
+
+`notebooklm-py` itself is fully async and, for every generated artifact
+(podcast, video, quiz, ...), a three-step dance: `generate_*()` kicks it
+off, `wait_for_completion()` polls it, and a matching `download_*()` fetches
+the finished file. That's the right shape for a library embedded in an
+existing async app. This wrapper is for the much more common case — a plain
+script — and does two things:
+
+1. **No `async`/`await`.** Every method is a normal blocking call. You don't
+   write `async def main(): ...; asyncio.run(main())` at all.
+2. **One call per artifact**, not three. `nlm.audio(nb.id, "podcast.mp3")`
+   generates, waits, and downloads in a single line.
+
+It does not reimplement anything — auth, RPC calls, polling, and downloads
+are all still done by `notebooklm-py` itself. This is a thin facade over it.
+Anything it doesn't wrap is still reachable (see [Escape hatch](#escape-hatch)).
+
+## Install
+
+```bash
+pip install notebooklm-py notebooklm-easy   # or: pip install -e . from this folder
+```
+
+`notebooklm-easy` depends on `notebooklm-py` and does not vendor it — you're
+always running the real, upstream library underneath.
+
+You still need to authenticate once with `notebooklm-py`'s own CLI (this
+wrapper doesn't change auth at all — see its
+[Installation guide](https://github.com/teng-lin/notebooklm-py/blob/main/docs/installation.md)
+for the full picture):
+
+```bash
+pip install "notebooklm-py[browser]"
+notebooklm login                      # opens a browser once
+notebooklm auth check --test --json   # confirms it worked
+```
+
+After that, `notebooklm_easy.NotebookLM()` (no arguments) picks up the saved
+session automatically, exactly like `NotebookLMClient.from_storage()` does.
+
+## Quick start
+
+```python
+from notebooklm_easy import NotebookLM
+
+with NotebookLM() as nlm:
+    # Reuses a notebook with this exact title if one exists, else creates it
+    nb = nlm.get_or_create_notebook("Research")
+
+    # Add sources — URLs and local file paths, auto-detected, uploaded
+    # concurrently, and waited-on by default so the next call can use them
+    nlm.add_sources(nb.id, [
+        "https://en.wikipedia.org/wiki/Artificial_intelligence",
+        "./paper.pdf",
+    ])
+
+    # Ask a question — returns just the answer text
+    print(nlm.ask(nb.id, "What are the key themes?"))
+
+    # Generate + wait + download, in one call each
+    nlm.audio(nb.id, "podcast.mp3", instructions="make it engaging")
+    nlm.quiz(nb.id, "quiz.json", difficulty="hard")
+    nlm.report(nb.id, "briefing.md", format="briefing_doc")
+```
+
+That's the whole shape of the library: a `NotebookLM` object, used as a
+context manager (or with explicit `.close()`), with one method per thing
+you want to do.
+
+## Auth / multiple accounts
+
+`NotebookLM(...)` accepts every keyword `NotebookLMClient.from_storage()`
+does, and passes them straight through — most commonly `profile` for
+switching between `notebooklm login --profile <name>` accounts, and
+`backend="android"` to use the Android gRPC backend instead of the default
+web one:
+
+```python
+with NotebookLM(profile="work") as nlm:
+    ...
+```
+
+## Notebooks
+
+```python
+nlm.create_notebook("Title")          # always creates a new one
+nlm.get_or_create_notebook("Title")   # reuses an existing notebook with this exact title
+nlm.list_notebooks()                  # -> list[Notebook]
+nlm.delete_notebook(notebook_id)
+```
+
+## Sources
+
+```python
+# One source — auto-detects URL (http/https, including YouTube) vs. an
+# existing local file path (PDF, text, Markdown, Word, EPUB, audio, video,
+# image — whatever notebooklm-py's add_file supports).
+nlm.add_source(nb.id, "https://example.com")
+nlm.add_source(nb.id, "./report.pdf")
+
+# Several at once, uploaded concurrently, in the same order back:
+sources = nlm.add_sources(nb.id, ["https://a.example", "./b.pdf", "https://youtube.com/watch?v=..."])
+
+# Raw pasted text has no URL/path to auto-detect, so it's its own method:
+nlm.add_text(nb.id, "My Notes", "... text content ...")
+```
+
+All three default to `wait=True` — they block until NotebookLM finishes
+processing the source, so the very next `ask()` or `generate_*` call sees
+it. Pass `wait=False` to fire-and-forget instead (matching
+`notebooklm-py`'s own default).
+
+## Chat
+
+```python
+answer = nlm.ask(nb.id, "Summarize this")                  # -> str, just the answer
+result = nlm.ask_full(nb.id, "Summarize this")              # -> AskResult (citations, conversation_id, ...)
+```
+
+## Generating content
+
+One method per artifact type. Each does `generate_* -> wait_for_completion
+-> download_*` and returns the path it wrote to. Every enum-typed option
+(`format`, `difficulty`, `style`, ...) accepts a plain, case-insensitive
+string as well as the real `notebooklm.types` enum member — `"hard"` and
+`QuizDifficulty.HARD` both work.
+
+```python
+nlm.audio(nb.id, "podcast.mp3", instructions="make it fun", format="deep_dive", length="short")
+nlm.video(nb.id, "overview.mp4", format="explainer", style="whiteboard")
+nlm.cinematic_video(nb.id, "documentary.mp4", instructions="documentary-style summary")
+nlm.report(nb.id, "briefing.md", format="briefing_doc")       # or study_guide / blog_post / concept_explanation / custom
+nlm.study_guide(nb.id, "study_guide.md")
+nlm.quiz(nb.id, "quiz.json", difficulty="hard", quantity="more", output_format="json")   # or markdown / html
+nlm.flashcards(nb.id, "cards.json", difficulty="easy")
+nlm.slide_deck(nb.id, "slides.pdf", format="presenter_slides", output_format="pdf")       # or pptx
+nlm.infographic(nb.id, "infographic.png", orientation="portrait", style="bento_grid")
+nlm.data_table(nb.id, "data.csv", instructions="compare key concepts")
+nlm.mind_map(nb.id, "mindmap.json", kind="interactive")        # or "note_backed"
+```
+
+Every one of these takes `source_ids=[...]` to scope generation to specific
+sources (default: all of them), and `timeout=<seconds>` to override how
+long it waits before giving up (defaults are generous — 300s for most
+types, 600s for video/slide-deck/audio, which tend to run longer).
+
+### Handling failure
+
+If generation finishes in a `failed` or `removed` (delisted, e.g. after a
+daily quota rejection) state, these methods raise `GenerationFailedError`
+instead of silently returning a broken path:
+
+```python
+from notebooklm_easy import GenerationFailedError
+
+try:
+    nlm.audio(nb.id, "podcast.mp3")
+except GenerationFailedError as e:
+    print(e.status.error, e.status.error_code)   # the raw GenerationStatus is on .status
+```
+
+Every other error — auth problems, rate limits, network issues, a bad
+notebook id — is exactly whatever `notebooklm-py` itself raises (see its
+[`exceptions.py`](https://github.com/teng-lin/notebooklm-py/blob/main/src/notebooklm/exceptions.py)),
+unchanged. This wrapper doesn't catch or reshape those.
+
+## Escape hatch
+
+Anything this wrapper doesn't cover — sharing, labels, research, notes,
+collections, settings, the `raw` backend-selected wire access, or a
+`generate_*`/`download_*` combination not wrapped as its own method — is
+still one call away. Every `NotebookLM` instance exposes the real async
+client:
+
+```python
+with NotebookLM() as nlm:
+    # nlm.client is the actual notebooklm.NotebookLMClient — every
+    # namespace (sharing, labels, research, notes, collections, raw, ...)
+    # is there, unwrapped.
+    coro = nlm.client.sharing.set_public(nb.id, view_level="editor")
+    nlm.run(coro)   # runs it on the same background loop as everything else
+```
+
+**Important:** don't `await` `nlm.client.<...>(...)` yourself from a
+different `asyncio` context (e.g. inside your own `async def`) — always go
+through `nlm.run(coro)`. `notebooklm-py`'s client is loop-bound (it asserts
+every call happens on the exact event loop it was opened on); `NotebookLM`
+opens it on a dedicated background loop and `run()` is what submits work to
+that same loop correctly. See `notebooklm_easy/_loop.py` for the full
+rationale.
+
+If your program is *already* async end-to-end, skip this wrapper entirely
+and use `notebooklm.NotebookLMClient` directly — that's what it's for.
+
+## Using this inside a bot (or any other async app)
+
+`NotebookLM` is synchronous — every method blocks the calling thread until
+it's done (`ask()` for a few seconds, a generated artifact for a minute or
+more). That's fine in a plain script, but calling it directly inside an
+`async def` handler of an asyncio-based bot (kurigram/pyrogram, aiogram,
+discord.py, ...) freezes that bot's entire event loop — every other
+chat/user — for as long as the call takes, since asyncio is single-threaded.
+
+The fix: create **one** `NotebookLM()` for the whole bot process (not one
+per request — see why in the example), and reach every blocking call
+through `asyncio.to_thread(...)` from inside your `async def` handlers, so
+it runs on a worker thread instead of the bot's event loop.
+`examples/telegram_notes_bot.py` is a complete, runnable example of exactly
+this: a kurigram/pyrogram bot with a `/notes <youtube_link>` command that
+adds the video as a source and returns notes, done correctly.
+
+## Testing without live Google auth
+
+`tests/test_smoke.py` exercises the whole wrapper (notebook get-or-create,
+source auto-detection, bulk add, chat, one-call generate+wait+download,
+failure handling, enum coercion, and — importantly — that every call really
+does run on the one background loop) against the real installed
+`notebooklm-py` types, with only `NotebookLMClient.from_storage` swapped for
+a fake that never touches the network. Useful both as a regression test and
+as a template if you want to unit-test your own code that uses this wrapper
+without a live Google session.
+
+```bash
+pip install pytest
+pytest tests/
+```

notebooklm_easy-0.1.0/notebooklm_easy/__init__.py

@@ -0,0 +1,21 @@
+"""notebooklm-easy — a synchronous, one-call-per-task wrapper around
+notebooklm-py (https://github.com/teng-lin/notebooklm-py).
+
+    from notebooklm_easy import NotebookLM
+
+    with NotebookLM() as nlm:
+        nb = nlm.get_or_create_notebook("Research")
+        nlm.add_sources(nb.id, ["https://example.com"])
+        print(nlm.ask(nb.id, "Summarize this"))
+        nlm.audio(nb.id, "podcast.mp3")
+
+See client.py's module docstring for the design rationale, and the
+package README for the full usage guide.
+"""
+
+from .client import NotebookLM
+from .exceptions import GenerationFailedError, NotebookLMEasyError
+
+__all__ = ["NotebookLM", "NotebookLMEasyError", "GenerationFailedError"]
+
+__version__ = "0.1.0"

notebooklm_easy-0.1.0/notebooklm_easy/_enums.py

@@ -0,0 +1,46 @@
+"""Forgiving string -> notebooklm-py enum coercion.
+
+notebooklm-py's ``generate_*`` methods take real ``Enum`` members
+(``QuizDifficulty.HARD``, ``AudioFormat.DEEP_DIVE``, ...) — accurate, but it
+means importing and remembering a dozen enum classes for what's usually a
+single word. ``coerce()`` lets every convenience method here accept that
+same enum member OR a plain, case-insensitive string ("hard", "deep_dive",
+"deep-dive", "Deep Dive" all resolve to ``AudioFormat.DEEP_DIVE``) OR the
+raw underlying value (an int, or the exact string an ``str, Enum`` uses,
+e.g. "briefing_doc" for ``ReportFormat.BRIEFING_DOC``) — whichever is
+easiest for the caller. ``None`` passes through unchanged so every optional
+enum parameter keeps working un-set.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TypeVar
+
+_E = TypeVar("_E", bound=Enum)
+
+
+def coerce(enum_cls: type[_E], value: _E | str | int | None) -> _E | None:
+    if value is None or isinstance(value, enum_cls):
+        return value
+    if isinstance(value, str):
+        key = value.strip().upper().replace(" ", "_").replace("-", "_")
+        try:
+            return enum_cls[key]
+        except KeyError:
+            pass
+        try:
+            return enum_cls(value)  # value-based lookup, e.g. ReportFormat("briefing_doc")
+        except ValueError:
+            pass
+        try:
+            return enum_cls(value.lower())
+        except ValueError:
+            pass
+    else:
+        try:
+            return enum_cls(value)  # e.g. a plain int for an int Enum
+        except ValueError:
+            pass
+    valid = ", ".join(m.name.lower() for m in enum_cls)
+    raise ValueError(f"Invalid {enum_cls.__name__} {value!r} — choose one of: {valid}")

notebooklm_easy-0.1.0/notebooklm_easy/_loop.py

@@ -0,0 +1,60 @@
+"""
+A persistent background event loop that a synchronous caller can submit
+coroutines to.
+
+Why this exists instead of just wrapping every call in ``asyncio.run()``:
+notebooklm-py's ``NotebookLMClient`` is explicitly loop-bound. It captures
+the event loop it was opened on (``async with NotebookLMClient.from_storage()``)
+and every subsequent call asserts it's running on *that same* loop
+(see notebooklm's own ``_loop_affinity.py`` / ``_loop_bound.py`` /
+``LoopBoundPrimitive``) — calling it from a different loop raises a
+``RuntimeError`` rather than silently working. ``asyncio.run()`` tears down
+and recreates a brand-new loop on every call, so a naive "just run() each
+method" wrapper would break on the second call. Instead, this module opens
+ONE loop in a dedicated background thread, keeps it alive for the lifetime
+of a ``NotebookLM`` instance, and runs every coroutine on it via
+``asyncio.run_coroutine_threadsafe`` — the client is opened on this loop
+once, in ``NotebookLM.__init__``, and every method call is submitted to the
+same loop for the object's whole lifetime.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+_T = TypeVar("_T")
+
+
+class BackgroundLoop:
+    """Owns one event loop running forever on a dedicated daemon thread."""
+
+    def __init__(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        self._ready = threading.Event()
+        self._thread = threading.Thread(target=self._run, name="notebooklm-easy-loop", daemon=True)
+        self._thread.start()
+        self._ready.wait()
+
+    def _run(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._ready.set()
+        self._loop.run_forever()
+
+    def run(self, coro: Coroutine[Any, Any, _T], timeout: float | None = None) -> _T:
+        """Submit `coro` to the background loop and block the calling
+        (synchronous) thread until it finishes. Re-raises whatever
+        exception the coroutine raised, with its original traceback."""
+        if self._loop.is_closed():
+            raise RuntimeError("This NotebookLM client is closed — create a new one.")
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        return future.result(timeout)
+
+    def close(self, timeout: float = 10.0) -> None:
+        if self._loop.is_closed():
+            return
+        self._loop.call_soon_threadsafe(self._loop.stop)
+        self._thread.join(timeout=timeout)
+        self._loop.close()