Metadata-Version: 2.5
Name: vctx
Version: 0.3.0
Summary: Video to context pack CLI for AI agents and automation.
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: full
Requires-Dist: av>=18.0.0; extra == 'full'
Requires-Dist: faster-whisper>=1.2.1; 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[visual]"   # core + PyAV + RapidOCR
```

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

## 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
vctx verify ./lecture-pack
vctx render ./lecture-pack --format read --out ./lecture.md
```

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

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]
use = "instance:local"

[instances.asr.local]
type = "local-faster-whisper"
model = "small"
device = "auto"
compute = "auto"
cache = "persistent"

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

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

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

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