Skip to main content

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.

Install the published package and run it directly:

python -m venv .venv
source .venv/bin/activate      # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install yt-gpt
yt-gpt serve

Open http://127.0.0.1:8765. Cloning and pip install -e ".[dev]" are only needed when developing the backend.

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

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).

Metadata

Release files for yt-gpt 1.0.17

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for yt-gpt 1.0.17
File Size Uploaded Provenance Actions
yt_gpt-1.0.17.tar.gz 394.2 kB Without provenance Details for yt_gpt-1.0.17.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for yt-gpt 1.0.17
File Interpreter ABI Platform Actions
yt_gpt-1.0.17-py3-none-any.whl Python 3 none any Details for yt_gpt-1.0.17-py3-none-any.whl

Total release size: 794.5 kB

Release files / yt_gpt-1.0.17.tar.gz

Download URL yt_gpt-1.0.17.tar.gz
Size 394.2 kB
Tags Source
SHA-256 checksum
How to use checksums
fc65f71d1a8608c4348723e854e1e7a6564f0be4d554862ac09e69992a3fefc0
BLAKE2b-256 checksum
How to use checksums
c502dcb830b62c57a53ab67436ca39e1eb4ab0c3875a1ce77d51332dd436f7a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / yt_gpt-1.0.17-py3-none-any.whl

Download URL yt_gpt-1.0.17-py3-none-any.whl
Size 400.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8ac669864ac0d72dbe407b43f30de6add4d283d052897e4285b22156948fa28f
BLAKE2b-256 checksum
How to use checksums
7920e9541948bece91380ac1fc63dd3425a9f6107b17a345712c665fbafa11bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for yt-gpt 1.0.17

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page