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.

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

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

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.16
File Size Uploaded Provenance Actions
yt_gpt-1.0.16.tar.gz 394.0 kB Without provenance Details for yt_gpt-1.0.16.tar.gz

Built distribution (wheel)

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

Total release size: 794.2 kB

Release files / yt_gpt-1.0.16.tar.gz

Download URL yt_gpt-1.0.16.tar.gz
Size 394.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a0f22b7a8080afbab37209a03a345e4412c32194bbedb630142920d7beaa5cb3
BLAKE2b-256 checksum
How to use checksums
a96ef51cec8c38a2268b6117240d0828c42d1e865d9fcd1b033f53c5311149b9
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.16-py3-none-any.whl

Download URL yt_gpt-1.0.16-py3-none-any.whl
Size 400.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e1b518fd0aed92a3fce813a240e927625879310d8ec86a8d4d1adedfd4db4eb4
BLAKE2b-256 checksum
How to use checksums
15b9aee6dd2c9cece6e4d8043e1b40333dd1952de8b9f6eab911868f2db19ac0
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.16

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