Metadata-Version: 2.4
Name: polli-cosmos
Version: 0.8.0
Summary: Provenance-first video normalization toolkit for ingest, crop, and web optimization
Author: Polli Labs
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pillow>=10.4.0
Requires-Dist: psutil>=6.1.0
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: questionary>=2.0.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: typer>=0.12.5
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.6.9; extra == 'dev'
Requires-Dist: ty<1,>=0.0.1a0; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings-python<2,>=1.10; extra == 'docs'
Requires-Dist: mkdocstrings<1,>=0.24; extra == 'docs'
Provides-Extra: release
Requires-Dist: build<2,>=1.2; extra == 'release'
Requires-Dist: hatchling<2,>=1.24; extra == 'release'
Requires-Dist: twine<7,>=6; extra == 'release'
Provides-Extra: video-av
Requires-Dist: av<17,>=14; extra == 'video-av'
Requires-Dist: numpy<3,>=1.26; extra == 'video-av'
Provides-Extra: video-torchcodec
Requires-Dist: numpy<3,>=1.26; extra == 'video-torchcodec'
Requires-Dist: torch<2.12,>=2.11; extra == 'video-torchcodec'
Requires-Dist: torchcodec<0.12,>=0.11.1; extra == 'video-torchcodec'
Description-Content-Type: text/markdown

# Cosmos

[![CI](https://github.com/polli-labs/cosmos/actions/workflows/ci.yml/badge.svg)](https://github.com/polli-labs/cosmos/actions/workflows/ci.yml)
[![Docs](https://github.com/polli-labs/cosmos/actions/workflows/docs.yml/badge.svg)](https://github.com/polli-labs/cosmos/actions/workflows/docs.yml)
[![PyPI](https://img.shields.io/pypi/v/polli-cosmos.svg)](https://pypi.org/project/polli-cosmos/)

Cosmos is a provenance-first video normalization toolkit for agent and human media pipelines.

It turns heterogeneous camera/video inputs into deterministic, web-ready derivatives and
emits machine-joinable sidecars so downstream systems can trust, trace, and reproduce each asset.

Cosmos is designed for both operators and automation:

- `cosmos` CLI for ingest/crop/optimize/provenance workflows
- `cosmos.sdk` for stable Python integration, including typed video probe/frame extraction
- run-level and artifact-level provenance sidecars for reproducibility

## Scope today

- First-class adapter for COSM camera ingest workflows (manifest-aware processing)
- General MP4 post-processing surfaces for crop, preview, optimize, and provenance lookup
- Typed FFmpeg-backed video metadata and RGB frame extraction for downstream SDK consumers
- Deterministic CLI contracts suitable for unattended agent execution

The near-term direction is to add more ingestion adapters while keeping the same normalized
output and provenance contracts.

## Documentation

- Docs home: https://docs.polli.ai/cosmos/
- CLI reference: [docs/cosmos-cli.md](docs/cosmos-cli.md)
- SDK reference: [docs/sdk.md](docs/sdk.md)
- Provenance guide: [docs/provenance.md](docs/provenance.md)
- Encoder behavior matrix: [docs/encoder-behavior.md](docs/encoder-behavior.md)

## Agent skill (recommended for agent operators)

Cosmos keeps a canonical in-repo skill package that should be consulted before
changing CLI, SDK, ffmpeg policy, provenance fields, or release behavior.

- Entrypoint: [skills/cosmos/SKILL.md](skills/cosmos/SKILL.md)
- API contracts: [skills/cosmos/references/api-surfaces.md](skills/cosmos/references/api-surfaces.md)
- Maintenance ritual: [skills/cosmos/references/maintenance-ritual.md](skills/cosmos/references/maintenance-ritual.md)

## Install

- Production: `pip install polli-cosmos`
- Development (recommended from an existing checkout):

```bash
bash dev/scripts/bootstrap-dev.sh
```

- Development (manual):

```bash
make dev-setup
```

- Docs tooling:

```bash
make docs-setup
```

- If dependency metadata changes, refresh the committed lockfile with `uv lock`.
- Contributor docs and the canonical quality gate live in `CONTRIBUTING.md`.

## CLI quickstart

```bash
cosmos --help
cosmos ingest run --help
cosmos crop run --help
cosmos optimize run --help
cosmos crop preview --help
```

## Common workflows

### 1) Ingest camera outputs

```bash
make run.ingest IN=/path/to/raw OUT=./out YES=1
```

### 2) Crop MP4 views with jobs JSON

```bash
make run.crop INPUT=/path/to/clip.mp4 OUT=_work/out JOBS=_work/job.json YES=1
```

### 3) Generate crop previews (contact sheets + stacked overlays)

```bash
cosmos crop preview \
  --input /path/to/clip.mp4 \
  --jobs-file _work/job.json \
  --out _work/preview \
  --frame start --frame mid \
  --stack-time 0 \
  --yes
```

### 4) Optimize MP4s for web delivery

```bash
# Faststart remux (default mode=auto, no transform flags)
cosmos optimize run --input /path/to/clip.mp4 --out-dir _work/web --yes

# Explicit transcode
cosmos optimize run \
  --input /path/to/clip.mp4 \
  --out-dir _work/web \
  --mode transcode \
  --target-height 1080 --fps 30 --crf 23 \
  --yes
```

### 5) Inspect provenance mapping

```bash
make run.provenance DIR=_work/out
```

## Crop jobs semantics

Crop jobs accept either offsets or centers:

- Recommended: `offset_x`, `offset_y` in `[-1, 1]` relative to available margin
  - `0` is centered
  - positive values move right/down
  - negative values move left/up
- Alternative: `center_x`, `center_y` in `[0, 1]`
- Do not combine offsets and centers in a single job.

Other common fields:

- `targets`: one or more square output sizes
- `trim_unit: "time"`, `trim_start`, `trim_end` for bounded crops

## Provenance and stable IDs

- Clip IDs: `clip-<stem>-<sha8>`
- View IDs: `view-<stem>-<sha8>`
- Optimize sidecars: `*.mp4.cosmos_optimized.v1.json`

Core join behavior:

- `view.source.sha256 == clip.output.sha256`

See [docs/provenance.md](docs/provenance.md) for full schema links and examples.

## Encoder policy (cross-platform)

- macOS: `h264_videotoolbox` -> `libx264`
- Linux: `h264_nvenc` -> `h264_qsv` -> `h264_vaapi` -> `libx264`
- Windows: `h264_nvenc` -> `h264_qsv` -> `h264_amf` -> `libx264`

Cosmos runtime-probes auto-selected hardware encoders and falls back to `libx264`
if the host advertises an encoder that is not actually usable.

## Developer workflow

```bash
make dev-setup
make check
uv run mkdocs build --strict
```

## Optional local E2E lanes

- Slim ingest repro: `make e2e-repro-slim`
- 8K windowed repro: `make e2e-repro-8k`
- Full heavy repro: `make e2e-repro-full`

These are fixture-gated and intentionally off for standard CI.
