yutome 0.1.0__tar.gz

yutome-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+
+.env
+.env.*
+!.env.example
+
+.claude/settings.local.json
+
+data/
+
+# Cloudflare Worker subproject — track source, ignore build/runtime artifacts
+cloudflare/*/node_modules/
+cloudflare/*/.wrangler/
+cloudflare/*/dist/
+
+.DS_Store

yutome-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kifah Meeran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yutome-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: yutome
+Version: 0.1.0
+Summary: A local transcript library for the YouTube channels you point at
+Project-URL: Homepage, https://github.com/MaskyS/yutome
+Project-URL: Repository, https://github.com/MaskyS/yutome
+Project-URL: Issues, https://github.com/MaskyS/yutome/issues
+Author-email: Kifah Meeran <contact@maskys.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: knowledge-base,local-first,mcp,rag,search,transcripts,youtube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: rapidfuzz>=3.14.5
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: websockets>=13
+Requires-Dist: wordfreq>=3.1.1
+Provides-Extra: all
+Requires-Dist: curl-cffi<0.15,>=0.11; extra == 'all'
+Requires-Dist: fastapi<1,>=0.115; extra == 'all'
+Requires-Dist: faster-whisper>=1.1; extra == 'all'
+Requires-Dist: google-genai>=1.40; extra == 'all'
+Requires-Dist: lancedb>=0.20; extra == 'all'
+Requires-Dist: mcp[cli]<2,>=1.20; extra == 'all'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'all'
+Requires-Dist: voyageai>=0.3; extra == 'all'
+Requires-Dist: youtube-transcript-api>=1.2; extra == 'all'
+Requires-Dist: yt-dlp>=2025.6.9; extra == 'all'
+Provides-Extra: asr
+Requires-Dist: faster-whisper>=1.1; extra == 'asr'
+Provides-Extra: embeddings
+Requires-Dist: voyageai>=0.3; extra == 'embeddings'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.40; extra == 'gemini'
+Provides-Extra: http
+Requires-Dist: fastapi<1,>=0.115; extra == 'http'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'http'
+Provides-Extra: ingest
+Requires-Dist: curl-cffi<0.15,>=0.11; extra == 'ingest'
+Requires-Dist: youtube-transcript-api>=1.2; extra == 'ingest'
+Requires-Dist: yt-dlp>=2025.6.9; extra == 'ingest'
+Provides-Extra: mcp
+Requires-Dist: mcp[cli]<2,>=1.20; extra == 'mcp'
+Provides-Extra: vectors
+Requires-Dist: lancedb>=0.20; extra == 'vectors'
+Description-Content-Type: text/markdown
+
+# Yutome
+
+Yutome ingests transcripts from the YouTube channels you point at, stores them on your machine, and connects to whichever AI app you already use — Claude, ChatGPT, Cursor, anything MCP-compatible.
+
+The library is searchable from the command line, from any local MCP client, or remotely from claude.ai / ChatGPT through a small Cloudflare Worker you deploy yourself.
+
+Yutome is a command-line tool. You set it up from the terminal; from there it handles sync, cleanup, and exports. A coding agent (Claude Code, Cursor) can drive any of it.
+
+## Install
+
+Requires Python ≥3.11 and [`uv`](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv tool install 'yutome[all]'
+```
+
+This puts a single `yutome` command on your PATH. The `[all]` extra pulls in the full feature set (yt-dlp, LanceDB, Voyage embeddings, MCP server, HTTP API). Without it you'll hit ImportErrors on first run.
+
+If your default `python3` is older than 3.11, add `--python 3.11` to that command — uv will fetch a 3.11 for you.
+
+**Alternatives:**
+
+```bash
+# pipx — uses whichever python3 is on your PATH; needs 3.11+
+pipx install 'yutome[all]'
+
+# Install the latest unreleased commit
+uv tool install 'yutome[all] @ git+https://github.com/MaskyS/yutome.git'
+
+# For hacking on the code
+git clone https://github.com/MaskyS/yutome.git
+cd yutome
+uv sync --extra all
+uv run yutome --help
+```
+
+## Quickstart
+
+```bash
+yutome setup                                  # guided first-run: creates ./yutome.toml, ./data, etc.
+yutome add https://www.youtube.com/@LexClips  # add a YouTube channel or video as a source
+yutome sync                                   # discover videos, fetch transcripts, build indexes
+yutome find "first principles"                # ranked search across everything indexed
+```
+
+`yutome setup` is interactive by default; pass `-y` to skip prompts and just print what would happen. It prompts for any API keys it needs. To set keys ahead of time, copy `.env.example` to `.env`. The only commonly-needed key is `VOYAGE_API_KEY` (semantic search) — get one at [voyageai.com](https://www.voyageai.com/). Without it, `find` still works but falls back to keyword search only. Every other key in `.env.example` is optional and tied to a specific feature (Gemini transcript cleanup, Webshare residential proxy, OAuth subscription import, etc.).
+
+The indexed corpus lives under `./data/` next to `yutome.toml` — SQLite catalog, LanceDB vector index, transcript artifacts. Back it up like any other project directory.
+
+Run `yutome --help` for the full surface. The most-used commands:
+
+| Goal | Command |
+|---|---|
+| First-run setup | `yutome setup` |
+| Add a channel/video | `yutome add <url>` |
+| Import a subscription list | `yutome import-youtube` or `yutome import <file>` |
+| Index everything new | `yutome sync` |
+| Search | `yutome find "<query>"` |
+| List or inspect indexed objects | `yutome list videos`, `yutome show video <id>`, … |
+| Local MCP server | `yutome mcp serve` (usually invoked via Claude config, not by hand) |
+| Deploy/manage remote connector | `yutome connect --deploy`, `yutome remote bridge`, `yutome status` |
+
+Commands like `list`, `show`, `remote`, `export`, `quality` are groups — append `--help` (e.g. `yutome list --help`) to see their subcommands.
+
+## Connect to Claude / ChatGPT
+
+### Local (recommended for daily use)
+
+For **Claude Code** or **Codex** opened against this repo, the bundled `.mcp.json` is picked up automatically — no extra config.
+
+For **Claude Desktop**, add this block to `~/Library/Application Support/Claude/claude_desktop_config.json`. Use an absolute path to `yutome.toml`, since Desktop won't launch from your project directory:
+
+```json
+{
+  "mcpServers": {
+    "yutome": {
+      "command": "uv",
+      "args": ["run", "yutome", "mcp", "serve", "--config", "/absolute/path/to/yutome.toml"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see `yutome` in the connectors list with `find`, `list`, `show`, and `q` tools.
+
+### Remote (Claude.ai web, ChatGPT, phone)
+
+```bash
+yutome connect --deploy   # one-time: deploy the Worker, generate secrets, save state
+yutome remote bridge      # keep this running while you want queries to work
+```
+
+`connect --deploy` deploys a Cloudflare Worker to your own account (free plan is enough), generates an OAuth-protected `/mcp` endpoint, and prints a pairing code. Paste the `/mcp` URL into a Claude.ai or ChatGPT custom connector and complete OAuth in the browser tab using the pairing code.
+
+The Worker is just a relay — your corpus stays on your laptop. `yutome remote bridge` is the WebSocket process that lets the Worker reach it; if it's not running, the connector reports "desktop offline". Full setup walkthrough: [`docs/remote-access.md`](https://github.com/MaskyS/yutome/blob/main/docs/remote-access.md) and [`cloudflare/yutome-capsule/README.md`](https://github.com/MaskyS/yutome/blob/main/cloudflare/yutome-capsule/README.md).
+
+## Docs
+
+See [`docs/README.md`](https://github.com/MaskyS/yutome/blob/main/docs/README.md) for an index. The most useful starting points:
+
+- [`docs/remote-access.md`](https://github.com/MaskyS/yutome/blob/main/docs/remote-access.md) — connecting Claude / ChatGPT / agents
+- [`docs/cloud-capsule-strategy.md`](https://github.com/MaskyS/yutome/blob/main/docs/cloud-capsule-strategy.md) — how the Cloudflare Worker is designed
+- [`docs/query-api.md`](https://github.com/MaskyS/yutome/blob/main/docs/query-api.md) — the query language `find` / `q` speak
+- [`docs/plan.md`](https://github.com/MaskyS/yutome/blob/main/docs/plan.md) — internal architecture history (not a usage guide)
+
+## Status
+
+**v0.1.0 — early release.** Released under the MIT license; the API and CLI surface may shift between point releases.
+
+Found a bug or a confusing doc? Open an issue: <https://github.com/MaskyS/yutome/issues>.

yutome-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Yutome
+
+Yutome ingests transcripts from the YouTube channels you point at, stores them on your machine, and connects to whichever AI app you already use — Claude, ChatGPT, Cursor, anything MCP-compatible.
+
+The library is searchable from the command line, from any local MCP client, or remotely from claude.ai / ChatGPT through a small Cloudflare Worker you deploy yourself.
+
+Yutome is a command-line tool. You set it up from the terminal; from there it handles sync, cleanup, and exports. A coding agent (Claude Code, Cursor) can drive any of it.
+
+## Install
+
+Requires Python ≥3.11 and [`uv`](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv tool install 'yutome[all]'
+```
+
+This puts a single `yutome` command on your PATH. The `[all]` extra pulls in the full feature set (yt-dlp, LanceDB, Voyage embeddings, MCP server, HTTP API). Without it you'll hit ImportErrors on first run.
+
+If your default `python3` is older than 3.11, add `--python 3.11` to that command — uv will fetch a 3.11 for you.
+
+**Alternatives:**
+
+```bash
+# pipx — uses whichever python3 is on your PATH; needs 3.11+
+pipx install 'yutome[all]'
+
+# Install the latest unreleased commit
+uv tool install 'yutome[all] @ git+https://github.com/MaskyS/yutome.git'
+
+# For hacking on the code
+git clone https://github.com/MaskyS/yutome.git
+cd yutome
+uv sync --extra all
+uv run yutome --help
+```
+
+## Quickstart
+
+```bash
+yutome setup                                  # guided first-run: creates ./yutome.toml, ./data, etc.
+yutome add https://www.youtube.com/@LexClips  # add a YouTube channel or video as a source
+yutome sync                                   # discover videos, fetch transcripts, build indexes
+yutome find "first principles"                # ranked search across everything indexed
+```
+
+`yutome setup` is interactive by default; pass `-y` to skip prompts and just print what would happen. It prompts for any API keys it needs. To set keys ahead of time, copy `.env.example` to `.env`. The only commonly-needed key is `VOYAGE_API_KEY` (semantic search) — get one at [voyageai.com](https://www.voyageai.com/). Without it, `find` still works but falls back to keyword search only. Every other key in `.env.example` is optional and tied to a specific feature (Gemini transcript cleanup, Webshare residential proxy, OAuth subscription import, etc.).
+
+The indexed corpus lives under `./data/` next to `yutome.toml` — SQLite catalog, LanceDB vector index, transcript artifacts. Back it up like any other project directory.
+
+Run `yutome --help` for the full surface. The most-used commands:
+
+| Goal | Command |
+|---|---|
+| First-run setup | `yutome setup` |
+| Add a channel/video | `yutome add <url>` |
+| Import a subscription list | `yutome import-youtube` or `yutome import <file>` |
+| Index everything new | `yutome sync` |
+| Search | `yutome find "<query>"` |
+| List or inspect indexed objects | `yutome list videos`, `yutome show video <id>`, … |
+| Local MCP server | `yutome mcp serve` (usually invoked via Claude config, not by hand) |
+| Deploy/manage remote connector | `yutome connect --deploy`, `yutome remote bridge`, `yutome status` |
+
+Commands like `list`, `show`, `remote`, `export`, `quality` are groups — append `--help` (e.g. `yutome list --help`) to see their subcommands.
+
+## Connect to Claude / ChatGPT
+
+### Local (recommended for daily use)
+
+For **Claude Code** or **Codex** opened against this repo, the bundled `.mcp.json` is picked up automatically — no extra config.
+
+For **Claude Desktop**, add this block to `~/Library/Application Support/Claude/claude_desktop_config.json`. Use an absolute path to `yutome.toml`, since Desktop won't launch from your project directory:
+
+```json
+{
+  "mcpServers": {
+    "yutome": {
+      "command": "uv",
+      "args": ["run", "yutome", "mcp", "serve", "--config", "/absolute/path/to/yutome.toml"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see `yutome` in the connectors list with `find`, `list`, `show`, and `q` tools.
+
+### Remote (Claude.ai web, ChatGPT, phone)
+
+```bash
+yutome connect --deploy   # one-time: deploy the Worker, generate secrets, save state
+yutome remote bridge      # keep this running while you want queries to work
+```
+
+`connect --deploy` deploys a Cloudflare Worker to your own account (free plan is enough), generates an OAuth-protected `/mcp` endpoint, and prints a pairing code. Paste the `/mcp` URL into a Claude.ai or ChatGPT custom connector and complete OAuth in the browser tab using the pairing code.
+
+The Worker is just a relay — your corpus stays on your laptop. `yutome remote bridge` is the WebSocket process that lets the Worker reach it; if it's not running, the connector reports "desktop offline". Full setup walkthrough: [`docs/remote-access.md`](https://github.com/MaskyS/yutome/blob/main/docs/remote-access.md) and [`cloudflare/yutome-capsule/README.md`](https://github.com/MaskyS/yutome/blob/main/cloudflare/yutome-capsule/README.md).
+
+## Docs
+
+See [`docs/README.md`](https://github.com/MaskyS/yutome/blob/main/docs/README.md) for an index. The most useful starting points:
+
+- [`docs/remote-access.md`](https://github.com/MaskyS/yutome/blob/main/docs/remote-access.md) — connecting Claude / ChatGPT / agents
+- [`docs/cloud-capsule-strategy.md`](https://github.com/MaskyS/yutome/blob/main/docs/cloud-capsule-strategy.md) — how the Cloudflare Worker is designed
+- [`docs/query-api.md`](https://github.com/MaskyS/yutome/blob/main/docs/query-api.md) — the query language `find` / `q` speak
+- [`docs/plan.md`](https://github.com/MaskyS/yutome/blob/main/docs/plan.md) — internal architecture history (not a usage guide)
+
+## Status
+
+**v0.1.0 — early release.** Released under the MIT license; the API and CLI surface may shift between point releases.
+
+Found a bug or a confusing doc? Open an issue: <https://github.com/MaskyS/yutome/issues>.

yutome-0.1.0/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+name = "yutome"
+version = "0.1.0"
+description = "A local transcript library for the YouTube channels you point at"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Kifah Meeran", email = "contact@maskys.com" },
+]
+keywords = [
+    "youtube",
+    "knowledge-base",
+    "transcripts",
+    "search",
+    "mcp",
+    "rag",
+    "local-first",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Text Processing :: Indexing",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+dependencies = [
+    "pydantic>=2.8,<3",
+    "rapidfuzz>=3.14.5",
+    "typer>=0.12,<1",
+    "websockets>=13",
+    "wordfreq>=3.1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/MaskyS/yutome"
+Repository = "https://github.com/MaskyS/yutome"
+Issues = "https://github.com/MaskyS/yutome/issues"
+
+[project.optional-dependencies]
+ingest = [
+    "curl-cffi>=0.11,<0.15",
+    "yt-dlp>=2025.6.9",
+    "youtube-transcript-api>=1.2",
+]
+vectors = [
+    "lancedb>=0.20",
+]
+asr = [
+    "faster-whisper>=1.1",
+]
+embeddings = [
+    "voyageai>=0.3",
+]
+gemini = [
+    "google-genai>=1.40",
+]
+mcp = [
+    "mcp[cli]>=1.20,<2",
+]
+http = [
+    "fastapi>=0.115,<1",
+    "uvicorn>=0.30,<1",
+]
+all = [
+    "curl-cffi>=0.11,<0.15",
+    "yt-dlp>=2025.6.9",
+    "youtube-transcript-api>=1.2",
+    "lancedb>=0.20",
+    "faster-whisper>=1.1",
+    "voyageai>=0.3",
+    "google-genai>=1.40",
+    "mcp[cli]>=1.20,<2",
+    "fastapi>=0.115,<1",
+    "uvicorn>=0.30,<1",
+]
+
+[project.scripts]
+yutome = "yutome.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.2,<9",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yutome"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/yutome",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+exclude = [
+    "cloudflare",
+    "docs",
+    "data",
+    ".env*",
+    "*.log",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

yutome-0.1.0/src/yutome/__init__.py

@@ -0,0 +1,9 @@
+"""YouTube channel knowledge base indexer."""
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = _pkg_version("yutome")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"

yutome-0.1.0/src/yutome/__main__.py

@@ -0,0 +1,5 @@
+from yutome.cli import app
+
+
+if __name__ == "__main__":
+    app()