amon-hen 0.1.0__tar.gz

amon_hen-0.1.0/.env.example

@@ -0,0 +1,3 @@
+# Hugging Face Access Token (Write Permission for publishing models)
+# Get yours from: https://huggingface.co/settings/tokens
+HF_TOKEN=

amon_hen-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,66 @@
+name: Bug Report
+description: Report an issue or unexpected behavior in Amon Hen
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: input
+    id: version
+    attributes:
+      label: Amon Hen Version
+      description: What version of Amon Hen are you using? (e.g. `amon-hen --version` or git commit hash)
+      placeholder: e.g. 0.1.0
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Linux (Ubuntu/Debian/Fedora/etc.)
+        - macOS (Apple Silicon - M1/M2/M3/M4)
+        - macOS (Intel)
+        - Windows 10 / 11
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      placeholder: e.g. Python 3.12.2
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the Bug
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Steps or CLI command to reproduce the behavior.
+      placeholder: |
+        1. Run `amon-hen index my_video.mp4`
+        2. Run `amon-hen search "a red car"`
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Error Output
+      description: Paste any error traceback or terminal output here.
+      render: shell

amon_hen-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: GitHub Discussions & Questions
+    url: https://github.com/flxhrdyn/amon-hen/discussions
+    about: Ask questions, share ideas, and discuss with the community.

amon_hen-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature Request
+description: Suggest an idea or enhancement for Amon Hen
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have a feature idea? We would love to hear it!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: A clear and concise description of what the problem or limitation is.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you would like
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you have considered
+      description: Any alternative solutions or features you have considered.
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or references here.

amon_hen-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## Description
+
+Please provide a brief summary of the changes introduced in this PR and the motivation behind them.
+
+Closes #(issue)
+
+---
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update / Benchmark result
+- [ ] Performance improvement
+
+---
+
+## Checklist
+
+- [ ] My code follows the style guidelines of this project (`uv run ruff check .`)
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] All new and existing tests passed (`uv run pytest`)
+- [ ] I have updated the documentation accordingly
+- [ ] My changes generate no new warnings or regressions

amon_hen-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run Ruff Linter
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+  test:
+    name: Test (${{ matrix.os }} - Py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run Test Suite
+        run: uv run pytest -v

amon_hen-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release & Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+
+jobs:
+  build-and-publish:
+    name: Build and Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/amon-hen
+
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

amon_hen-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+*.db
+docs/superpowers/
+.env
+.env.*
+!.env.example
+models/
+benchmarks/charades_sta_subset/

amon_hen-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2026-08-28
+
+### Added
+* **CPU-Native Moment Retrieval:** Natural language video search running entirely on CPU using Apple's MobileCLIP2 architecture and ONNX Runtime.
+* **Hybrid Quantization Model:** Default distribution using `vision_model.onnx` (FP32) and `text_model_quantized.onnx` (INT8) for a ~105 MB footprint with 18.5x realtime indexing throughput.
+* **Vector Storage:** SQLite vector database powered by `sqlite-vec` for embedded, single-file storage with zero server dependencies.
+* **Adaptive Frame Sampling:** Motion-aware frame decoding via `imageio-ffmpeg` with embedding-based deduplication (up to 7.8x speedup over fixed per-second sampling).
+* **Temporal Segment Merging:** Consecutive frame grouping into coherent start-end timestamps with per-video baseline calibration.
+* **Interactive Tolkien REPL:** Terminal UI with prompt history, banner styling, visual score bars, and slash commands (`/open`, `/help`, `/exit`).
+* **External Media Player Launcher:** Instant playback at matched timestamps with automatic detection for `mpv`, `vlc`, and `ffplay`.
+* **Benchmark Suite:** Charades-STA evaluation harness with mIoU, R@1, and R@5 metrics and synthetic dataset generation.
+* **Model Distribution:** Automated ONNX export, INT8 dynamic quantizer, numerical parity verifier, and Hugging Face publisher for `flxhrdyn/mobileclip2-s0-onnx`.

amon_hen-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[support@felixhrdyn.com](mailto:support@felixhrdyn.com).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

amon_hen-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to Amon Hen
+
+Thank you for your interest in contributing to **Amon Hen**! We welcome contributions of all kinds: bug reports, documentation improvements, benchmark evaluations, feature proposals, and code contributions.
+
+---
+
+## Code of Conduct
+
+All contributors and maintainers are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). Please read it before participating.
+
+---
+
+## Development Setup
+
+Amon Hen uses [`uv`](https://github.com/astral-sh/uv) as the fast Python package and project manager.
+
+### 1. Prerequisites
+* Python >= 3.11
+* `uv` installed ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
+* Git
+
+### 2. Clone and Setup
+```bash
+git clone https://github.com/flxhrdyn/amon-hen.git
+cd amon-hen
+
+# Install dependencies into virtualenv
+uv sync --all-groups
+```
+
+### 3. Run the Test Suite
+```bash
+# Run unit and integration tests
+uv run pytest
+
+# Run tests with verbose output
+uv run pytest -v
+```
+
+### 4. Code Quality & Linting
+We use [`ruff`](https://github.com/astral-sh/ruff) for linting and formatting.
+
+```bash
+# Check code style and linting rules
+uv run ruff check .
+
+# Auto-fix lint errors where possible
+uv run ruff check . --fix
+
+# Format code
+uv run ruff format .
+```
+
+---
+
+## Project Architecture & Structure
+
+```
+amon-hen/
+├── src/amonhen/
+│   ├── cli.py             # Typer CLI application & interactive entry point
+│   ├── decode.py          # Video decoding via imageio-ffmpeg
+│   ├── encode.py          # Vision & text ONNX embedding pipelines
+│   ├── interactive.py     # Tolkien-themed REPL interactive session
+│   ├── model_registry.py  # Hugging Face model registry & downloader
+│   ├── pipeline.py        # Indexing & search pipeline orchestration
+│   ├── player.py          # System media player launcher with timestamp seeking
+│   ├── progress.py        # Dual-level Rich progress reporters
+│   ├── sample.py          # Adaptive motion-based frame sampling & dedup
+│   ├── segment.py         # Temporal segment merging & thresholding
+│   ├── store.py           # SQLite vector store powered by sqlite-vec
+│   └── theme.py           # Tolkien styling, banners, score bars, & verbs
+├── tests/                 # Comprehensive unit & integration tests
+├── benchmarks/            # Evaluation benchmarks (Charades-STA metrics & runner)
+├── demo/                  # Canonical demo assets & GIF generator
+└── tools/                 # ONNX export, INT8 quantization, & HF publishing tools
+```
+
+---
+
+## Development Guidelines
+
+1. **Test-Driven Development (TDD):**
+   - Write tests for any new features or bug fixes in `tests/`.
+   - Ensure 100% of tests pass before submitting a PR.
+2. **CPU-First & Low Memory:**
+   - Amon Hen is strictly designed to run on CPU without requiring discrete GPUs.
+   - Keep memory usage low and avoid loading unnecessary heavy dependencies into runtime.
+3. **Typing & Linting:**
+   - Use Python 3.11+ type annotations (`int | str`, `list[Segment]`, etc.).
+   - Pass all `ruff check .` rules without warnings.
+
+---
+
+## Submitting a Pull Request
+
+1. **Fork** the repository and create your branch from `main`:
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+2. **Make your changes** with clear, atomic commits.
+3. **Verify tests and linter pass:**
+   ```bash
+   uv run pytest
+   uv run ruff check .
+   ```
+4. **Push** to your fork and submit a Pull Request against `main`.
+5. Describe your changes clearly in the PR template, referencing any related issues.
+
+---
+
+## Reporting Issues
+
+If you find a bug or have a feature request:
+- Search existing [Issues](https://github.com/flxhrdyn/amon-hen/issues) to avoid duplicates.
+- Open an issue using our structured bug report or feature request template.
+- Provide minimal reproduction steps, OS version, and video codec details if reporting a video indexing issue.

amon_hen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Hardyan and Amon Hen Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.