Metadata-Version: 2.4
Name: the-shortcut
Version: 1.0.0
Summary: Local-first, contract-bounded AI-assisted video editing runtime
Author: xuctang
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/xuctang/the-shortcut
Project-URL: Repository, https://github.com/xuctang/the-shortcut
Project-URL: Issues, https://github.com/xuctang/the-shortcut/issues
Project-URL: Changelog, https://github.com/xuctang/the-shortcut/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/xuctang/the-shortcut/tree/main/docs
Keywords: ai,ffmpeg,non-linear-editing,premiere,video-editing
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: litellm>=1.83.7
Requires-Dist: pillow>=12.3.0
Requires-Dist: referencing>=0.37.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: local-analysis
Requires-Dist: librosa>=0.11.0; extra == "local-analysis"
Provides-Extra: local-vision
Requires-Dist: opencv-python-headless>=5.0.0.93; extra == "local-vision"
Provides-Extra: semantic-asr-openai
Requires-Dist: openai>=2.30.0; extra == "semantic-asr-openai"
Dynamic: license-file

# theShortCut

[![CI](https://github.com/xuctang/the-shortcut/actions/workflows/ci.yml/badge.svg)](https://github.com/xuctang/the-shortcut/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/xuctang/the-shortcut/blob/main/LICENSE)

`the-shortcut` is a Python package and CLI for local-first, AI-assisted video
editing. Model stages may propose editorial intent; deterministic code owns
source selection, frame and sample timing, timeline compilation, media
execution, export, validation, and QC.

## Status

The current package version is `1.0.0`. The 1.0 contract covers the documented
CLI, persisted data contracts, package contents, and supported delivery
targets.

This status does not claim that model-assisted edits are professionally
qualified. Editorial quality remains a review outcome. Inspect the current
evidence-backed Aspect status locally:

```bash
python -m the_shortcut.cli qualify-aspects
```

## Supported delivery targets

| Target | Deliverable | Boundary |
| --- | --- | --- |
| `review` | Watchable Review MP4 at `exports/review/final.mp4` | Review media, not an editable NLE project |
| `premiere` | Premiere-compatible XML rough-cut bundle, with optional ZIP | Rough-cut handoff, not a complete native Premiere project |
| `ffmpeg` | FFmpeg video, audio, and subtitle stems | Render/stems delivery, not an editable NLE project |

CapCut, FCPXML, Final Cut, DaVinci, and user-facing OTIO are reserved rather
than supported runnable targets.

## Install

Python 3.11 or newer is required. Published releases install with:

```bash
python -m pip install the-shortcut
```

To install from a source checkout in an activated virtual environment:

```bash
git clone https://github.com/xuctang/the-shortcut.git
cd the-shortcut
python -m pip install .
python -m the_shortcut.cli --help
```

For development:

```bash
python -m pip install -e '.[dev]'
```

Stable media execution requires `ffmpeg` and `ffprobe` on `PATH`:

```bash
ffmpeg -version
ffprobe -version
```

Inspect the installed runtime without media or model access:

```bash
python -m the_shortcut.cli list-workflows
python -m the_shortcut.cli list-aspects --workflow short_form
python -m the_shortcut.cli qualify-aspects
```

Project caches are explicit runtime data rather than invisible permanent
storage. Inspect one cache without changing it, or move it reversibly into the
resolved runtime workspace quarantine:

```bash
python -m the_shortcut.cli runtime-workspace \
  --root /absolute/runtime/root \
  --inspect-project-cache /absolute/runtime/root/users/USER/projects/PROJECT
python -m the_shortcut.cli runtime-workspace \
  --root /absolute/runtime/root \
  --quarantine-project-cache /absolute/runtime/root/users/USER/projects/PROJECT
```

The quarantine command never permanently deletes data. It accepts only the
exact Project layout owned by the selected runtime workspace and reports the
original and recovery paths. Inspection is portable; quarantine currently
requires Linux or macOS so it can use an atomic, directory-anchored move.

Optional Python capabilities and platform troubleshooting are documented in
[Local Setup and Troubleshooting](https://github.com/xuctang/the-shortcut/blob/main/docs/LOCAL_SETUP_AND_TROUBLESHOOTING.md).

## Start 1: edit through Codex

Open this repository in Codex, attach media or provide local paths, and state
the requested edit in ordinary language, for example:

> Turn these clips into a 45-second vertical product recap. Keep the original
> speech, use clean captions, and produce a review MP4.

The repository skills under `.agents/skills/` handle onboarding and actionable
video-edit intake. They preserve task-relevant instructions, place new media
in the selected Project by default, build the current v3 intake, and run the
same deterministic pipeline used by the CLI. Ask for one-time material
explicitly when media should remain Run-owned rather than Project-owned.

If a selected Codex model stage waits, the workflow executes its immutable
task bundle once and resumes through the exact invocation receipt. It does not
choose a recent Run or reconstruct a request from memory. The corresponding
CLI lifecycle is:

```bash
python -m the_shortcut.cli video-edit prepare REQUEST.json
python -m the_shortcut.cli video-edit run REQUEST.json
python -m the_shortcut.cli video-edit resume RECEIPT.json
python -m the_shortcut.cli video-edit status RUN_DIR
```

Codex supplies the model only when the selected Profile stage route declares
Codex parent execution. It does not require an external model API credential.
See [Short-Form Pipeline](https://github.com/xuctang/the-shortcut/blob/main/docs/SHORT_FORM_LOCAL_PIPELINE.md) for the intake,
waiting, receipt, and artifact contracts.

## Start 2: run a general local project

A minimal project contains requirements and at least one supported media file:

```text
project/
  requirements.md
  raw_footage/
    A001.mp4
    A001.mp4.transcript.json  # required by speech-dependent original-audio paths
```

Run it with an explicit output directory and delivery target:

```bash
python -m the_shortcut.cli run ./project ./run --export-target review
```

Use `--export-target premiere` for the XML rough-cut bundle or
`--export-target ffmpeg` for stems. The CLI also accepts repeatable
`--edit-aspect`, an explicit processing mode, and run overrides; inspect the
current arguments instead of copying an assumed configuration:

```bash
python -m the_shortcut.cli run --help
```

Profile-aware projects under `users/<user_id>/projects/<project_id>/` resolve
their selected Profile before execution. A standalone project directory is
also valid. Generated state and deliverables stay under the requested Run
directory.

## Start 3: run short-form from a complete project

Use a registered Project plus a strict `short_form_project_brief.v1`:

```bash
python -m the_shortcut.cli short-form-project \
  ./project \
  ./short_form_project_brief.json \
  ./short-form-run \
  --planner deterministic
```

The Project/Profile owns the source universe, transcripts, references,
processing configuration, and evidence providers. The brief owns narrative,
duration, delivery, captions, audio, variants, and handoff intent. Missing
required authority fails before media execution rather than receiving an
invented default.

Model-assisted short-form uses the same entry point with one exact route file:

```bash
python -m the_shortcut.cli short-form-project \
  ./project \
  ./short_form_project_brief.json \
  ./short-form-run \
  --planner model_assisted \
  --llm-config ./llm_stages.json
```

Run a Codex-backed route through the Codex conversational workflow so the
parent can execute and resume waiting task bundles. An explicitly configured
LiteLLM route executes its selected provider/model Adapter. There is no silent
fallback between Codex, LiteLLM, another model, or deterministic planning.

The full short-form contracts and examples live in
[Short-Form Pipeline](https://github.com/xuctang/the-shortcut/blob/main/docs/SHORT_FORM_LOCAL_PIPELINE.md).

## Workflows and Aspects

One `PipelineRuntime` dispatches registered Workflows through exact Input and
execution Adapter coverage. Each Workflow retains its own input, candidate,
stage-order, timeline, and delivery contracts; the repository does not impose
one universal candidate or timeline schema.

List the current executable Workflows and their bound atomic Edit Aspects:

```bash
python -m the_shortcut.cli list-workflows
python -m the_shortcut.cli list-aspects --workflow WORKFLOW_ID
```

Structured Workflows use their strict spec entry point:

```bash
python -m the_shortcut.cli workflow WORKFLOW_ID ./spec.json ./run
```

An Aspect is optional editing guidance plus any declared evidence and
validation behavior. Runnable support and professional qualification are
separate: experimental or unqualified status is disclosed, not hidden.
See [Workflows](https://github.com/xuctang/the-shortcut/blob/main/docs/WORKFLOWS.md) for the current registry and support matrix.

## Model execution boundary

Model-assisted stages use the route selected by the active Profile or explicit
run configuration:

- a Codex route declares parent execution, its executor skill, and sealed task
  payload policy;
- a LiteLLM route explicitly declares its provider, model, thinking level,
  timeout, sampling, and any credential reference required by that registered
  route.

The runtime does not choose a default model or silently substitute another
route. Model output remains platform-independent intent and may reference only
the candidate identities exposed by its stage contract. Deterministic code
validates that output before compiling executable media operations.

Route details, sealed task bundles, retries, and failure behavior are owned by
[Model Stage Execution](https://github.com/xuctang/the-shortcut/blob/main/docs/MODEL_STAGE_EXECUTION.md).

## Architecture at a glance

```text
raw request
  -> Workflow Input Adapter
  -> prepared request + Workflow registry resolution
  -> Workflow-owned evidence and candidate construction
  -> optional selected model stage
  -> deterministic validation and timeline compilation
  -> audio, captions, render, export, QC, and indexed artifacts
```

Shared runtime code owns orchestration, artifact publication, model-stage
execution, and common delivery mechanics. Workflow Modules own domain input,
candidate, planning, timeline, and validation semantics. Export Adapters own
target-specific deliverables.

Invalid schemas, source/hash mismatches, unavailable required tools, impossible
timeline state, and export contract failures stop execution. Weak evidence or
subjective editorial quality remains diagnostic unless an explicit contract
makes it a failure.

Read [System Architecture Specification](https://github.com/xuctang/the-shortcut/blob/main/docs/SYSTEM_ARCHITECTURE_SPEC.md) for
the full runtime boundary and [Documentation Index](https://github.com/xuctang/the-shortcut/blob/main/docs/README.md) for the
module, data-contract, capability, export, and ADR maps.

## Repository layout

- `the_shortcut/`: package runtime, validators, compilers, Adapters, and CLI.
- `.agents/skills/`: repository-scoped Codex onboarding and execution skills.
- `the_shortcut/resources/`: packaged schemas, registries, configuration, and
  executor protocol.
- `docs/`: architecture, workflow, setup, release, and support documentation.
- `tests/`: deterministic contract, runtime, packaging, and acceptance tests.
- `users/user_template/`: example Profile and Project input structure.
- `runs/`: generated output when a caller explicitly chooses that location;
  generated runs are not source documentation.

## Local verification

The standard local correctness gates do not require an LLM, VLM, ASR provider,
Ollama server, or media-pipeline run:

```bash
python -m pip install -e '.[dev]'
python -m ruff format --check the_shortcut tests tools
python -m ruff check the_shortcut tests tools
python -m compileall -q the_shortcut tests tools
python -m pytest -q
```

Before publishing a candidate, also build and inspect both distribution
formats:

```bash
python -m build
python -m twine check dist/*
python tools/verify_distribution.py dist
```

The complete clean-install and source-distribution checks are in the
[Release Checklist](https://github.com/xuctang/the-shortcut/blob/main/docs/RELEASING.md).

## Documentation and project policy

- [Documentation Index](https://github.com/xuctang/the-shortcut/blob/main/docs/README.md)
- [Local Setup and Troubleshooting](https://github.com/xuctang/the-shortcut/blob/main/docs/LOCAL_SETUP_AND_TROUBLESHOOTING.md)
- [Short-Form Pipeline](https://github.com/xuctang/the-shortcut/blob/main/docs/SHORT_FORM_LOCAL_PIPELINE.md)
- [System Architecture Specification](https://github.com/xuctang/the-shortcut/blob/main/docs/SYSTEM_ARCHITECTURE_SPEC.md)
- [Workflows](https://github.com/xuctang/the-shortcut/blob/main/docs/WORKFLOWS.md)
- [Changelog](https://github.com/xuctang/the-shortcut/blob/main/CHANGELOG.md)
- [Contributing](https://github.com/xuctang/the-shortcut/blob/main/CONTRIBUTING.md)
- [Security Policy](https://github.com/xuctang/the-shortcut/blob/main/SECURITY.md)
- [Release Checklist](https://github.com/xuctang/the-shortcut/blob/main/docs/RELEASING.md)

The project is licensed under Apache-2.0. See
[LICENSE](https://github.com/xuctang/the-shortcut/blob/main/LICENSE) and
[NOTICE](https://github.com/xuctang/the-shortcut/blob/main/NOTICE).
