Metadata-Version: 2.5
Name: amon-hen
Version: 0.1.18
Summary: Local, CPU-only video moment retrieval from the command line
Project-URL: Homepage, https://github.com/flxhrdyn/amon-hen
Project-URL: Repository, https://github.com/flxhrdyn/amon-hen
Project-URL: Issues, https://github.com/flxhrdyn/amon-hen/issues
Project-URL: Changelog, https://github.com/flxhrdyn/amon-hen/blob/main/CHANGELOG.md
Project-URL: Model Hub, https://huggingface.co/felixhrdyn/mobileclip2-s0-onnx
Author-email: Felix Hardyan <felix@felixhrdyn.com>
License: MIT
License-File: LICENSE
Keywords: cli,clip,computer-vision,mobileclip,multimodal,onnx,onnxruntime,semantic-search,sqlite-vec,video-retrieval,video-search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Requires-Dist: huggingface-hub>=0.24
Requires-Dist: imageio-ffmpeg>=0.5
Requires-Dist: numpy>=1.26
Requires-Dist: onnxruntime>=1.18
Requires-Dist: pillow>=10.0
Requires-Dist: prompt-toolkit>=3.0.53
Requires-Dist: rich>=15.0.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: tokenizers>=0.20
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# Amon Hen

> *"From the Seat of Seeing, no moment remains hidden."*

A fast, lightweight CLI and Python library for natural language video moment retrieval on local CPU. Runs entirely on CPU without discrete GPUs, background daemons, or cloud dependencies.

[![PyPI](https://img.shields.io/pypi/v/amon-hen?color=blue)](https://pypi.org/project/amon-hen/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

## Key Highlights

* **100% CPU Execution:** Powered by Apple's MobileCLIP2 architecture, Whisper-Tiny ONNX, and ONNX Runtime.
* **Hybrid Visual & Speech Retrieval:** Simultaneously retrieves moments based on visual semantics and spoken dialogue.
* **Low Footprint:** Hybrid FP32-vision + INT8-quantized text pipeline (approx. 105 MB RAM).
* **Zero Infrastructure:** Embedded vector database and full-text index via SQLite, `sqlite-vec`, and FTS5 (single `.db` file).
* **High Throughput:** 3-gate adaptive motion sampler achieving 4.8x to 18.5x realtime indexing speed.
* **Temporal Grouping:** Merges consecutive matching frames into start-end timestamp intervals.


---

## Installation

```bash
# Recommended via uv
uv tool install amon-hen

# Or via pipx
pipx install amon-hen

# Or standard pip
pip install amon-hen
```

---

## Quickstart

### 1. Interactive Terminal UI
Run `amon-hen` without arguments to launch the interactive prompt:

```bash
amon-hen
```

Supports instant search queries, history navigation (`↑`/`↓`), `/open <n>` to play matches in your default player, and `/cut <n> [output]` to export clips.


### 2. Index Videos
```bash
# Index a video or entire folder with adaptive motion sampling
amon-hen index /path/to/videos/ --sampler adaptive
```

### 3. Search Moments
```bash
# Search visual actions or spoken dialogue (Battle of Amon Hen)
amon-hen search "swords fight warriors in forest"

# Search real-world surveillance events (CCTV footage)
amon-hen search "a person holding an umbrella"
```

### 4. Extract Video Clip
```bash
# Extract matching segment into a standalone video clip
amon-hen cut battle-of-amon-hen.webm --start 00:03:56 --end 00:04:52 -o battle_climax.mp4
```



---


## Python API

```python
from amonhen.encode import TextEncoder
from amonhen.model_registry import get_model
from amonhen.pipeline import search
from amonhen.store import Store

# 1. Connect to index
store = Store("index.db", embed_dim=512)

# 2. Load CPU-optimized text encoder
spec = get_model("mobileclip2-s0")
text_encoder = TextEncoder(spec)

# 3. Retrieve matching video segments
results = search("red sports car turning", store=store, text_encoder=text_encoder)
for seg in results:
    print(
        f"{seg.video_path}: {seg.start_ms / 1000.0:.1f}s - {seg.end_ms / 1000.0:.1f}s (score: {seg.score:.3f})"
    )

store.close()
```


---

## Resources & Links

* **GitHub Repository:** [https://github.com/flxhrdyn/amon-hen](https://github.com/flxhrdyn/amon-hen)
* **CLI User Manual:** [https://github.com/flxhrdyn/amon-hen/blob/main/docs/CLI_GUIDE.md](https://github.com/flxhrdyn/amon-hen/blob/main/docs/CLI_GUIDE.md)
* **Python API Documentation:** [https://github.com/flxhrdyn/amon-hen/blob/main/docs/PYTHON_API.md](https://github.com/flxhrdyn/amon-hen/blob/main/docs/PYTHON_API.md)
* **Project Roadmap:** [https://github.com/flxhrdyn/amon-hen/blob/main/docs/ROADMAP.md](https://github.com/flxhrdyn/amon-hen/blob/main/docs/ROADMAP.md)
* **Hugging Face Model Hub:** [https://huggingface.co/felixhrdyn/mobileclip2-s0-onnx](https://huggingface.co/felixhrdyn/mobileclip2-s0-onnx)
* **License:** MIT License
