Skip to main content
██╗     ███████╗███╗   ██╗███████╗
██║     ██╔════╝████╗  ██║██╔════╝
██║     █████╗  ██╔██╗ ██║███████╗
██║     ██╔══╝  ██║╚██╗██║╚════██║
███████╗███████╗██║ ╚████║███████║
╚══════╝╚══════╝╚═╝ ╚═══╝╚══════╝
      W H A T   S H E   W A T C H E S

Media perception that runs on the hardware we actually have.

kannaka-lens watches a clip and turns it into memory. Shots, motion, colour, sound, speech — all of it on a CPU, all of it landing in the Holographic Resonance Medium as Modality::Visual, so what Kannaka has seen is recalled the same way as everything else she knows.

License


The one rule

A missing model degrades a stage. It never breaks the run.

Every interactive path here is algorithmic and CPU-only. Model-backed passes are optional, batched, resumable, and shippable off-box. This is not a limitation we are apologising for — it is the design, and it is why this one runs.

The previous attempt at this was a 22-stage pipeline built on torch, demucs and mediapipe. Surveyed 2026-09-12: there is no GPU anywhere in the fleet, only one machine can host a torch workload at all, and that machine has no ffmpeg and a Python with no mediapipe wheels. Half of those stages were not slow. They were unreachable. See ADR-0001.

What it does in v1

probe · normalise · demux ffprobe / ffmpeg, container facts and a constant frame rate
frames · shots · motion · colour our own Rust, no torch, no OpenCV — 192-dim per frame, block-matching optical flow, adaptive shot boundaries
sound 296-dim mel/MFCC/tempo features, the same engine the radio already runs in production
speech faster-whisper small int8, on CPU, as an optional pass
storyboard · chronemic · highlights keyframes over real shot boundaries; timing over real turns; scoring over our own features
memory the clip becomes recallable, not a row in a side database

Measured against ground truth we built — three visually unrelated three-second segments concatenated — the eye put the cuts at exactly 3.0 s and 6.0 s, and the storyboard took one keyframe from inside each segment. Nothing ranks on the clip-level temporal vector: it scores 0.967 between a panning colour chart and a mandelbrot zoom, which is recorded in the ADR and filed as kannaka-memory#948.

Deferred on purpose, each for a stated reason rather than quietly: source separation, speaker and emotion embedding, reactions, face and pose analysis, voice cloning, lip-sync. They attach at defined seams if a GPU ever arrives.

Provenance

This is a clean-room project. It shares no file, no commit and no docstring with any prior work.

The shape of a media pipeline — probe, normalise, sample, detect, transcribe, index — is a fact about video and is re-derived freely here. Where a previous tool had genuine inventions, we either solve the problem our own way or do not ship the capability. The reasoning is in ADR-0001 §2, written down so that the next person does not have to reconstruct it.

Through the QuantumOS hub

lens is reachable from an AI through QuantumOS's hub (ADR-0027, one policy-gated MCP endpoint for the constellation's CLIs): the hub's example config carries a lens entry whose show --json is allowed as a read and whose run asks the person first, because it spends minutes of CPU on a clip and writes what it saw into the HRM. The CLI's two verbs are the contract; nothing here changes for it.

Status

Early, and running. Five stages work end to end: probe, normalise, audio, perceive and storyboard. Transcript, chronemic and highlights are next.

perceive calls the kannaka binary's watch verb — the Rust eye from ADR-0008, which had no callers at all until 2026-09-12. Shots, block-matching optical flow, colour, all on a CPU. Absent the binary the stage degrades and the run continues, which is the one rule doing its job rather than being described.

Measured on debain2 (20 cores, no GPU), inside the container, 2026-09-12:

10 s of 1280x720p30, all three stages 2.68 s (probe 0.27, normalise 2.15, audio 0.26)
the same clip again nothing re-run; every stage resumed from the record
image size 585 MB, ffmpeg included so no host needs it installed

So the v1 path is roughly four times faster than realtime on a machine with no graphics card, which is the whole argument of ADR-0001.

Running it

docker build -t kannaka-lens:dev .
./lens-docker ~/clips run whatever.mp4 --project whatever.lens

lens-docker mounts a host directory and passes your uid through. Skip it and the container runs as root, so every file lens writes comes back owned by root and you cannot delete your own output.

How it is checked

sh run-tests.sh --strict runs 23 contract tests, 7 end-to-end tests over real media, and 11 mutants of the stage contract — and refuses to pass if a suite skipped itself, because the media tests skip where ffmpeg is absent and would otherwise read as green while testing nothing. The end-to-end tests ask ffprobe whether the output is really constant-rate h264 and 16 kHz mono PCM, rather than asking our own record whether our own record is correct.

Metadata

Release files for kannaka-lens 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kannaka-lens 0.1.0
File Size Uploaded Provenance Actions
kannaka_lens-0.1.0.tar.gz 22.5 kB Without provenance Details for kannaka_lens-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kannaka-lens 0.1.0
File Interpreter ABI Platform Actions
kannaka_lens-0.1.0-py3-none-any.whl Python 3 none any Details for kannaka_lens-0.1.0-py3-none-any.whl

Total release size: 41.8 kB

Release files / kannaka_lens-0.1.0.tar.gz

Download URL kannaka_lens-0.1.0.tar.gz
Size 22.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1861810771aa41f7c9cbc85333ce5ee76443bc4bb866509b4efeebc9e130d7fb
BLAKE2b-256 checksum
How to use checksums
7e431c0e461d9c0ecc2c29554cd80d33ff61bbd6ae0bf980fba8fee6175a8869
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.3

Release files / kannaka_lens-0.1.0-py3-none-any.whl

Download URL kannaka_lens-0.1.0-py3-none-any.whl
Size 19.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bf82d27fa4f24f0ab134e0d8f219600d9d5a976f755d9b274b7a0a5307d26c27
BLAKE2b-256 checksum
How to use checksums
9fe5bf519a52fc4931e5ff73cd7153da9d554b76214ff9d4d392dcfb28bb4b91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.3

Security for kannaka-lens 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page