Metadata-Version: 2.5
Name: mdrack-media
Version: 1.0.0rc1
Summary: Pure timed-media contracts and builder inputs for mdrack-core
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mdrack-core==1.0.0rc1
Description-Content-Type: text/markdown

# mdrack-media

`mdrack-media` publishes immutable timed-text, transcript, frame-caption, locator,
policy, identifier, fingerprint, event and future-builder input contracts for MDRack.

Distribution version `1.0.0rc1` publishes media contract version `1.0.0-rc.1`.
Python 3.11 or newer is required. The only runtime dependency is
`mdrack-core==1.0.0rc1`.

## Boundary

The package validates caller-prepared values, groups timed atoms with a caller-owned
token counter, projects typed millisecond locators to generic
`mdrack_core.Locator` records, and provides provider-free audio, video transcript, and
video frame-caption batch projections. The builders do not read files, access a database or network,
call providers, load a tokenizer, or create embeddings; vectors remain caller-owned.
Source
identity is accepted only by deterministic ID helpers and is never admitted to
media event fields.

Frame-caption batches expose stable frame IDs as searchable units and preserve
integer-millisecond `video_frame` evidence. They can be narrowed with core
categorical branch scopes and fused with transcript branches using weighted RRF;
these are experimental retrieval compositions, not default production behavior.
`retrieve_media()` provides the corresponding provider-free prepared-batch
retrieval helper with transcript-only, frame-only, and weighted hybrid modes,
pre-limit categorical/facet filtering, deterministic IDs/order, and optional
nearby-frame evidence kept outside the core result.

Token counts always retain `exact` or `estimated` truthfulness together with the
fingerprint of the counter. Producer, normalization, grouper, token-counter,
aggregation and embedding fingerprints use distinct runtime types so they cannot be
silently interchanged.

`group_timed_atoms()` is strict: it never sorts, repairs, normalizes, truncates, or
adds retrieval overlap. Input atom overlap remains in exact source provenance;
boundaries cannot split an overlap-connected component, so emitted passage ranges
never overlap. A component that cannot satisfy a hard limit is rejected by default
or returned only with an explicit `unsplittable`/`hard_limit_exceeded` flag.

`provisional_abc_policies()` and `run_grouping_variants()` provide deterministic
experiment plumbing and aggregate structural metrics. A/B/C are not an optimized
or selected default; policy selection remains deferred to retrieval evaluation.

## Provider-free examples

- [Transcript and transcript-builder serialization](examples/transcript_serialization.py)
- [Frame artifact and frame-builder serialization](examples/frame_builder_serialization.py)

Both examples construct deterministic identities, serialize with `to_dict()`, and
round-trip with `from_dict()`. They require no media file, provider, database, or
network access.

See [API.md](API.md) for the frozen surface and [CHANGELOG.md](CHANGELOG.md) for
release notes.
