Metadata-Version: 2.5
Name: vctx
Version: 0.4.1
Summary: Video to context pack CLI for AI agents and automation.
Project-URL: Homepage, https://github.com/nostalume/vctx
Project-URL: Documentation, https://github.com/nostalume/vctx/blob/main/docs/api.md
Project-URL: Source, https://github.com/nostalume/vctx
Project-URL: Issues, https://github.com/nostalume/vctx/issues
Project-URL: Changelog, https://github.com/nostalume/vctx/blob/main/CHANGELOG.md
Author-email: nostalgia <nostalucent@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.7.0
Requires-Dist: platformdirs>=4.10.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: srt>=3.5.3
Requires-Dist: tenacity>=9.1.2
Requires-Dist: typer>=0.26.7
Requires-Dist: webvtt-py>=0.5.1
Requires-Dist: yt-dlp>=2026.3.17
Provides-Extra: asr
Requires-Dist: faster-whisper>=1.2.1; extra == 'asr'
Provides-Extra: asr-cuda
Requires-Dist: faster-whisper>=1.2.1; extra == 'asr-cuda'
Requires-Dist: nvidia-cublas-cu12>=12.9.2.10; (sys_platform == 'win32') and extra == 'asr-cuda'
Requires-Dist: nvidia-cudnn-cu12>=9.25.1.1; (sys_platform == 'win32') and extra == 'asr-cuda'
Provides-Extra: full
Requires-Dist: av>=18.0.0; extra == 'full'
Requires-Dist: faster-whisper>=1.2.1; extra == 'full'
Requires-Dist: nvidia-cublas-cu12>=12.9.2.10; (sys_platform == 'win32') and extra == 'full'
Requires-Dist: nvidia-cudnn-cu12>=9.25.1.1; (sys_platform == 'win32') and extra == 'full'
Requires-Dist: onnxruntime>=1.20.0; extra == 'full'
Requires-Dist: pillow>=12.0.0; extra == 'full'
Requires-Dist: rapidocr>=3.4.2; extra == 'full'
Provides-Extra: visual
Requires-Dist: av>=18.0.0; extra == 'visual'
Requires-Dist: onnxruntime>=1.20.0; extra == 'visual'
Requires-Dist: pillow>=12.0.0; extra == 'visual'
Requires-Dist: rapidocr>=3.4.2; extra == 'visual'
Description-Content-Type: text/markdown

# vctx

`vctx` compiles video URLs, local video/audio, and SRT/VTT subtitles into a
durable context pack. A pack keeps canonical transcript, evidence, summary, and
provenance data beside readable Markdown so people and AI agents can inspect the
same source-grounded result.

It is a one-shot CLI, not a chat application, RAG database, or background
service. Video frames are decoded in-process with PyAV; no host `ffmpeg`
executable is required.

Subtitle-backed transcript preparation needs no configuration or AI account.
Evidence planning and summaries do require an admitted AI route: authenticate
once with `vctx auth openrouter login`, provide `OPENROUTER_API_KEY`, or configure
your own OpenAI-compatible endpoint. vctx never provides anonymous AI access.

## Installation

Python 3.14 or newer is required. The full profile includes local ASR, frame extraction,
and OCR:

```console
uv tool install "vctx[full]"
```

Smaller installs are available:

```console
uv tool install vctx             # subtitles, URL acquisition, compatible AI
uv tool install "vctx[asr]"      # core + faster-whisper
uv tool install "vctx[asr-cuda]" # ASR + project-local CUDA libraries on Windows
uv tool install "vctx[visual]"   # core + PyAV + RapidOCR
```

The equivalent pip command is `python -m pip install "vctx[full]"` inside a
Python 3.14 environment.

Upgrade an existing tool installation with `uv tool upgrade vctx`. See the
[changelog](CHANGELOG.md) before upgrading across a minor version.

## Usage

Prepare local model assets once, compile a source, verify the resulting pack,
then render the view needed by a person or agent:

```console
vctx auth openrouter login
vctx models pull asr ocr
vctx prepare ./lecture.mp4 --out ./lecture-pack --to summary --source-assets complete --max-runtime 1800
vctx verify ./lecture-pack
vctx render ./lecture-pack --format read --out ./lecture.md
```

On Windows with an NVIDIA GPU, `vctx[full]` includes acceleration. For an ASR-only
install, use `vctx[asr-cuda]`. vctx selects admitted acceleration automatically and
falls back to CPU before output is emitted; it does not require `PATH` edits.

`prepare` defaults to `--to transcript`. `--to evidence` adds transcript-anchored
frame planning and observations; `--to summary` adds a citation-constrained
summary. The stages are monotonic, so a later target retains all safe earlier
products. Multiple inputs become independent source directories and are never
combined into one summary.

Source files live beside their products inside the output lane. The default
`--source-assets consumed` retains only assets needed by the requested work;
`--source-assets complete` retains every audio, video, or native-subtitle role
reported for the admitted source revision. A later complete request extends the
same verified output, fetching only missing roles while preserving transcript
quality and existing products. Complete retention can download substantially more
data; retained files live directly beside their products in the source lane.

For an agent-oriented view:

```console
vctx render ./lecture-pack --format context
vctx prompt
```

## Simple configuration

Create `vctx.toml` in the working directory:

```toml
[cache]
source_dir = ".cache/vctx/source"
model_dir = ".cache/vctx/models"

[transforms.asr]
quality = "balanced"

[evidence]
planner = "auto"
ocr = "auto"
vision = "auto"

[summary]
use = "auto"
language = "native"

[output]
projections = ["context", "read"]
```

For zero-TOML online planning and summaries, authenticate once with `vctx auth
openrouter login`; `auto` then admits the free zero-data-retention OpenRouter
route. `OPENROUTER_API_KEY` provides the same automatic route without keyring
login. Without either credential, `auto` does not make an AI call and the pack
records unavailable evidence/summary outcomes while retaining safe earlier
products. You may instead configure any suitable OpenAI-compatible `/v1`
endpoint. Secrets stay in an environment variable or system keyring.

Inspect the effective setup without downloading or creating anything:

```console
vctx doctor --to summary --json
```

More runnable configurations are under [docs/examples](docs/examples/README.md). The
complete command behavior, every configuration field, path precedence, pack
layout, migration guidance, and exit status are documented in
[docs/api.md](docs/api.md).

## Workflow

```text
INPUT...
  -> admit and acquire each source
  -> transcript -> evidence -> summary
  -> canonical schema-5 JSON + selected Markdown projections
  -> atomic PACK publication
  -> verify PACK
  -> render context | read | transcript
```

The pack is the integration boundary. Begin with `manifest.json`; it records
source identities, revisions, artifacts, product outcomes, provider/model
effects, omissions, upload/cost facts, and integrity digests. Re-running
`prepare` reuses matching verified lanes. Use `--overwrite` only when you intend
to refresh or rebuild them.

## License

MIT License. See [LICENSE](LICENSE).
