Metadata-Version: 2.4
Name: yt-gpt
Version: 1.0.16
Summary: A local, NotebookLM-style workspace for YouTube: transcripts, retrieval and grounded chat.
Author: yt-gpt contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/anomalyco/yt-gpt
Project-URL: Documentation, https://github.com/anomalyco/yt-gpt#readme
Project-URL: Issues, https://github.com/anomalyco/yt-gpt/issues
Keywords: youtube,transcripts,llm,rag,notebooklm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: pydantic>=2.7
Requires-Dist: httpx>=0.27
Requires-Dist: yt-dlp>=2024.10.7
Requires-Dist: litellm>=1.50
Requires-Dist: numpy>=1.26
Requires-Dist: keyring>=25
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: imageio-ffmpeg>=0.5
Requires-Dist: Pillow>=10.0
Requires-Dist: imagehash>=4.3
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: tomli-w>=1.0
Provides-Extra: whisper
Requires-Dist: faster-whisper>=1.0; extra == "whisper"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Provides-Extra: all
Requires-Dist: yt-gpt[whisper]; extra == "all"
Dynamic: license-file

# yt-gpt backend

The FastAPI service, ingestion pipeline, retrieval engine and CLI that power the
`yt-gpt` package. The compiled frontend is bundled under
`src/yt_gpt/server/static` and served by the same process.

```bash
pip install -e ".[dev]"
yt-gpt serve
```

Open <http://127.0.0.1:8765>.

## Layout

```
src/yt_gpt/
├── cli.py              # yt-gpt serve | doctor | embed | export | version
├── config.py           # ~/.yt-gpt, config.toml, secret key
├── server/             # FastAPI app, routes, SSE, static bundle
├── auth/               # AuthProvider + local password profiles
├── workspace/          # atomic file store, models, transcripts.md export
├── ingest/             # URL normalisation, yt-dlp, captions, cleaning, chunking, jobs
├── retrieval/          # BM25 index + optional dense vectors + RRF
├── llm/                # LiteLLM wrapper, embeddings, prompts, context, chat, tools
├── vision/             # lazy scene sampling, contact sheets, exact frames
└── sources/            # reserved namespace; sources are stored by workspace/store.py
```

## Data

Everything lives under `~/.yt-gpt` (override with `YT_GPT_HOME`). There is no
database. `segments.jsonl` and `meta.json` are the source of truth; `clean.txt`,
`chunks.jsonl`, `vectors.npy` and `transcripts.md` are derived. `yt-gpt doctor
--rebuild` rebuilds text artifacts; `yt-gpt embed` rebuilds vectors.

API keys are stored in the OS keyring. If no keyring backend is available, a
`0600` file under `~/.yt-gpt/secrets/` is used instead.

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check .
ruff format --check .
mypy src
```

To run against the Vite dev server, build the frontend with
`VITE_API_MODE=http VITE_API_URL=http://127.0.0.1:8765 npm run build`, or run
`npm run dev` and keep the API on port 8765 (CORS for `localhost:5173` and
`127.0.0.1:5173` is enabled).

## Publishing

The workflow at `.github/workflows/autopublish.yml` is manually triggered with a
version string. It builds the frontend with `VITE_API_MODE=http`, bundles the
dist output, runs lint/type checks and the test suite, updates
`yt_gpt/version.py`, builds the wheel/sdist and publishes to PyPI. Configure a PyPI Trusted Publisher for this repository and workflow (or
add a `PYPI_API_TOKEN` repository secret as a fallback).

## Notes

- The server binds to `127.0.0.1` by default. Use `--host` only when you know
  what you are doing.
- Whisper is optional: `pip install "yt-gpt[whisper]"`.
- Visual analysis is lazy and opt-in. The workspace and session toggles default to
  off, text-only workspaces never download video, and frames require a vision-capable
  chat model.
- Retrieval is hybrid when an embedding model is configured: vector search is fused
  with BM25 using reciprocal rank fusion. Without vectors it falls back to BM25.
- License: MIT (see `LICENSE`).
