eyeroll 0.1.0__tar.gz

eyeroll-0.1.0/.env.example

@@ -0,0 +1 @@
+GEMINI_API_KEY=your-api-key-here

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

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - feat/**
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: Run tests
+        run: python -m pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Check if version exists on PyPI
+        id: check
+        run: |
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if pip index versions eyeroll 2>/dev/null | grep -q "$VERSION"; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Publish to PyPI
+        if: steps.check.outputs.exists == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1

eyeroll-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,52 @@
+name: Publish Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v6
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: release-build
+    permissions:
+      id-token: write
+      contents: read
+    environment:
+      name: pypi
+      url: https://pypi.org/project/eyeroll/
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

eyeroll-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Environment
+.env
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project
+*.mp4
+*.webm
+*.gif
+*.png
+*.jpg
+*.jpeg
+!docs/*.png
+output/
+tmp/
+.eyeroll/
+
+# npx skills install artifacts (local symlinks)
+.agents/
+.adal/
+.augment/
+.claude/
+.codebuddy/
+.commandcode/
+.continue/
+.crush/
+.cursor/
+.factory/
+.goose/
+.iflow/
+.junie/
+.kilocode/
+.kiro/
+.kode/
+.mcpjam/
+.mux/
+.neovate/
+.openhands/
+.pi/
+.pochi/
+.qoder/
+.qwen/
+.roo/
+.trae/
+.vibe/
+.windsurf/
+.zencoder/
+skills-lock.json

eyeroll-0.1.0/CLAUDE.md

@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+## Project
+
+eyeroll — AI eyes that roll through video footage. Takes video URLs (Loom, YouTube), local video files, or screenshots as input. Uses Gemini Flash for vision analysis and audio transcription. Produces structured notes that coding agents can act on — fix bugs, build features, create skills, or anything else.
+
+## Commands
+
+```bash
+# Install
+pip install .
+# or with uv:
+uv sync
+
+# Run tests
+pytest
+pytest --cov --cov-report=term-missing
+
+# CLI
+eyeroll init                                              # set up Gemini API key
+eyeroll watch <url-or-path>                               # analyze a video/screenshot
+eyeroll watch <url> --context "broken after PR #432"      # with reporter context
+eyeroll watch <path> --verbose --output report.md         # verbose + write to file
+```
+
+## Architecture
+
+- **Pipeline**: `acquire.py` (download/locate) → `extract.py` (frames + audio) → `analyze.py` (Gemini vision + synthesis) → `watch.py` (orchestrator)
+- **acquire.py**: Downloads from URLs via yt-dlp, resolves local files. Returns file_path, media_type, title.
+- **extract.py**: ffmpeg wrappers for key frame extraction, audio extraction, duration detection. Falls back to imageio-ffmpeg.
+- **analyze.py**: Gemini Flash API calls. Frame-by-frame analysis with structured prompts, direct video upload for short videos, audio transcription, and synthesis into bug report.
+- **watch.py**: Orchestrates the full pipeline. Chooses strategy (direct upload vs frame-by-frame) based on video size/duration. Handles cleanup.
+- **cli.py**: Click CLI with `init` and `watch` commands.
+
+## Key design decisions
+
+- **Single backend (Gemini Flash)**: Intentionally simple. One API key, one set of failure modes. Gemini handles video, images, and audio natively.
+- **Direct upload vs frame-by-frame**: Videos under 20MB/2min are sent whole to Gemini (better context). Longer videos use frame extraction.
+- **Context text is critical**: Most bug videos are silent screen recordings. The reporter's Slack message or issue description often contains more intent than the video itself.
+- **No codebase mapping in the skill itself**: The skill produces a bug report. Claude Code (which has codebase context) handles finding relevant code and implementing fixes.
+
+## Testing patterns
+
+- Mock all Gemini API calls in tests — never hit external services.
+- Use synthetic test videos generated via ffmpeg fixtures.
+- Test acquire.py with both URL and local file paths.

eyeroll-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mnvsk97
+
+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.

eyeroll-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: eyeroll
+Version: 0.1.0
+Summary: AI eyes that roll through video footage — watch, understand, turn into code actions.
+Project-URL: Homepage, https://github.com/mnvsk97/eyeroll
+Project-URL: Repository, https://github.com/mnvsk97/eyeroll
+Project-URL: Issues, https://github.com/mnvsk97/eyeroll/issues
+Author: mnvsk97
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,bug-report,claude-code,gemini,skills,video
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Bug Tracking
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: google-genai>=1.0
+Requires-Dist: imageio-ffmpeg>=0.5
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: yt-dlp>=2024.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# eyeroll
+
+AI eyes that roll through video footage — watch, understand, act.
+
+eyeroll is a collection of AI coding agent skills that analyze screen recordings, Loom videos, YouTube links, and screenshots, then turn them into code actions.
+
+## Skills
+
+| Skill | What it does |
+|-------|-------------|
+| **watch-video** | Watch a video and produce structured notes |
+| **video-to-pr** | Watch a bug video → diagnose → fix → raise PR |
+| **video-to-skill** | Watch a tutorial/demo → generate a Claude Code skill |
+
+## Install
+
+```bash
+# Install all skills
+npx skills add mnvsk97/eyeroll
+
+# Install a specific skill
+npx skills add mnvsk97/eyeroll@video-to-pr
+npx skills add mnvsk97/eyeroll@video-to-skill
+npx skills add mnvsk97/eyeroll@watch-video
+```
+
+## Setup
+
+```bash
+pip install eyeroll    # or: pip install git+https://github.com/mnvsk97/eyeroll.git
+eyeroll init           # set up Gemini API key
+brew install yt-dlp    # for URL downloads (Loom, YouTube)
+```
+
+Or just set the key: `export GEMINI_API_KEY=your-key` ([get one free](https://aistudio.google.com/apikey))
+
+## Usage
+
+### In Claude Code (via skills)
+
+```
+User: fix this bug: https://loom.com/share/abc123
+      → video-to-pr skill activates, watches video, finds code, fixes, raises PR
+
+User: watch this tutorial and create a skill from it: ./demo.mp4
+      → video-to-skill skill activates, watches video, generates SKILL.md
+
+User: look at this recording, what's going on?
+      → watch-video skill activates, produces structured notes
+```
+
+### Standalone CLI
+
+```bash
+eyeroll watch https://loom.com/share/abc123
+eyeroll watch ./bug.mp4 --context "checkout broken after PR #432"
+eyeroll watch screenshot.png --verbose
+```
+
+## How it works
+
+```
+Video (Loom / YouTube / local file / screenshot)
+    ↓
+eyeroll extracts: frames, audio, on-screen text
+    ↓
+Gemini Flash analyzes: what's shown, what's said, what happened
+    ↓
+Structured notes → skill decides what to do next
+    ↓
+video-to-pr:    search codebase → fix → PR
+video-to-skill: extract workflow → generate SKILL.md
+watch-video:    return notes to the agent
+```
+
+## Supported inputs
+
+| Input | Notes |
+|-------|-------|
+| Loom URLs | Requires yt-dlp |
+| YouTube URLs | Requires yt-dlp |
+| Local video files (.mp4, .webm, .mov) | Direct analysis |
+| Screenshots (.png, .jpg, .gif) | Single-frame analysis |
+| Any yt-dlp supported URL | 1000+ sites |
+
+## Requirements
+
+- Python 3.11+
+- ffmpeg (`brew install ffmpeg`)
+- yt-dlp (`brew install yt-dlp`) — for URL downloads
+- Gemini API key ([free](https://aistudio.google.com/apikey))
+
+## Cost
+
+Typically under $0.15 per video analysis using Gemini 2.0 Flash.
+
+## License
+
+MIT

eyeroll-0.1.0/README.md

@@ -0,0 +1,99 @@
+# eyeroll
+
+AI eyes that roll through video footage — watch, understand, act.
+
+eyeroll is a collection of AI coding agent skills that analyze screen recordings, Loom videos, YouTube links, and screenshots, then turn them into code actions.
+
+## Skills
+
+| Skill | What it does |
+|-------|-------------|
+| **watch-video** | Watch a video and produce structured notes |
+| **video-to-pr** | Watch a bug video → diagnose → fix → raise PR |
+| **video-to-skill** | Watch a tutorial/demo → generate a Claude Code skill |
+
+## Install
+
+```bash
+# Install all skills
+npx skills add mnvsk97/eyeroll
+
+# Install a specific skill
+npx skills add mnvsk97/eyeroll@video-to-pr
+npx skills add mnvsk97/eyeroll@video-to-skill
+npx skills add mnvsk97/eyeroll@watch-video
+```
+
+## Setup
+
+```bash
+pip install eyeroll    # or: pip install git+https://github.com/mnvsk97/eyeroll.git
+eyeroll init           # set up Gemini API key
+brew install yt-dlp    # for URL downloads (Loom, YouTube)
+```
+
+Or just set the key: `export GEMINI_API_KEY=your-key` ([get one free](https://aistudio.google.com/apikey))
+
+## Usage
+
+### In Claude Code (via skills)
+
+```
+User: fix this bug: https://loom.com/share/abc123
+      → video-to-pr skill activates, watches video, finds code, fixes, raises PR
+
+User: watch this tutorial and create a skill from it: ./demo.mp4
+      → video-to-skill skill activates, watches video, generates SKILL.md
+
+User: look at this recording, what's going on?
+      → watch-video skill activates, produces structured notes
+```
+
+### Standalone CLI
+
+```bash
+eyeroll watch https://loom.com/share/abc123
+eyeroll watch ./bug.mp4 --context "checkout broken after PR #432"
+eyeroll watch screenshot.png --verbose
+```
+
+## How it works
+
+```
+Video (Loom / YouTube / local file / screenshot)
+    ↓
+eyeroll extracts: frames, audio, on-screen text
+    ↓
+Gemini Flash analyzes: what's shown, what's said, what happened
+    ↓
+Structured notes → skill decides what to do next
+    ↓
+video-to-pr:    search codebase → fix → PR
+video-to-skill: extract workflow → generate SKILL.md
+watch-video:    return notes to the agent
+```
+
+## Supported inputs
+
+| Input | Notes |
+|-------|-------|
+| Loom URLs | Requires yt-dlp |
+| YouTube URLs | Requires yt-dlp |
+| Local video files (.mp4, .webm, .mov) | Direct analysis |
+| Screenshots (.png, .jpg, .gif) | Single-frame analysis |
+| Any yt-dlp supported URL | 1000+ sites |
+
+## Requirements
+
+- Python 3.11+
+- ffmpeg (`brew install ffmpeg`)
+- yt-dlp (`brew install yt-dlp`) — for URL downloads
+- Gemini API key ([free](https://aistudio.google.com/apikey))
+
+## Cost
+
+Typically under $0.15 per video analysis using Gemini 2.0 Flash.
+
+## License
+
+MIT

eyeroll-0.1.0/eyeroll/__init__.py

@@ -0,0 +1 @@
+"""eyeroll — AI eyes that roll through video footage. Watch, understand, act."""

eyeroll-0.1.0/eyeroll/acquire.py

@@ -0,0 +1,127 @@
+"""Download or locate video/image from URL or local path."""
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+SUPPORTED_VIDEO_EXTS = {".mp4", ".webm", ".mov", ".avi", ".mkv"}
+SUPPORTED_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"}
+SUPPORTED_EXTS = SUPPORTED_VIDEO_EXTS | SUPPORTED_IMAGE_EXTS
+
+
+def _is_url(source: str) -> bool:
+    return source.startswith("http://") or source.startswith("https://")
+
+
+def _get_ytdlp() -> str:
+    path = shutil.which("yt-dlp")
+    if path:
+        return path
+    raise RuntimeError(
+        "yt-dlp is not installed.\n\n"
+        "Install with: brew install yt-dlp  (macOS)\n"
+        "              pip install yt-dlp    (any platform)"
+    )
+
+
+def detect_media_type(file_path: str) -> str:
+    """Return 'video' or 'image' based on file extension."""
+    ext = Path(file_path).suffix.lower()
+    if ext in SUPPORTED_VIDEO_EXTS:
+        return "video"
+    if ext in SUPPORTED_IMAGE_EXTS:
+        return "image"
+    raise ValueError(f"Unsupported file type: {ext}")
+
+
+def acquire(source: str, output_dir: str | None = None) -> dict:
+    """Download or locate media from a URL or local path.
+
+    Returns dict with keys:
+        file_path: absolute path to the media file
+        media_type: 'video' or 'image'
+        source_url: original URL (or None for local files)
+        title: video title (from yt-dlp metadata, or filename)
+    """
+    if _is_url(source):
+        return _download_url(source, output_dir)
+    return _resolve_local(source)
+
+
+def _download_url(url: str, output_dir: str | None = None) -> dict:
+    ytdlp = _get_ytdlp()
+    if output_dir is None:
+        output_dir = tempfile.mkdtemp(prefix="eyeroll_")
+
+    # First, get metadata to know the title
+    meta_result = subprocess.run(
+        [ytdlp, "--dump-json", "--no-download", url],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+
+    title = None
+    if meta_result.returncode == 0:
+        import json
+        try:
+            meta = json.loads(meta_result.stdout)
+            title = meta.get("title")
+        except json.JSONDecodeError:
+            pass
+
+    # Download the video
+    output_template = os.path.join(output_dir, "%(title)s.%(ext)s")
+    result = subprocess.run(
+        [
+            ytdlp,
+            "--no-playlist",
+            "--merge-output-format", "mp4",
+            "-o", output_template,
+            url,
+        ],
+        capture_output=True,
+        text=True,
+        timeout=300,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"yt-dlp failed to download: {url}\n\n"
+            f"stderr: {result.stderr[:500]}"
+        )
+
+    # Find the downloaded file
+    downloaded = _find_media_file(output_dir)
+    if not downloaded:
+        raise RuntimeError(f"yt-dlp ran successfully but no media file found in {output_dir}")
+
+    return {
+        "file_path": downloaded,
+        "media_type": detect_media_type(downloaded),
+        "source_url": url,
+        "title": title or Path(downloaded).stem,
+    }
+
+
+def _resolve_local(path: str) -> dict:
+    abs_path = str(Path(path).expanduser().resolve())
+    if not os.path.isfile(abs_path):
+        raise FileNotFoundError(f"File not found: {abs_path}")
+
+    return {
+        "file_path": abs_path,
+        "media_type": detect_media_type(abs_path),
+        "source_url": None,
+        "title": Path(abs_path).stem,
+    }
+
+
+def _find_media_file(directory: str) -> str | None:
+    """Find the first supported media file in a directory."""
+    for f in sorted(os.listdir(directory)):
+        if Path(f).suffix.lower() in SUPPORTED_EXTS:
+            return os.path.join(directory, f)
+    return None