merleau 0.1.1__tar.gz → 0.3.0__tar.gz

merleau-0.3.0/.github/workflows/python-publish.yml

@@ -0,0 +1,65 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      url: https://pypi.org/p/merleau
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

merleau-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+.env
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/

merleau-0.3.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Merleau is a CLI tool for video understanding using Google's Gemini API. Named after Maurice Merleau-Ponty, the phenomenologist philosopher. The CLI command is `ponty`.
+
+See `research/positioning_merleau.md` for market positioning and differentiation strategy.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync
+uv sync --extra web  # Include Streamlit
+
+# Run the CLI
+uv run ponty video.mp4
+uv run ponty video.mp4 -p "Custom prompt" -m gemini-2.0-flash
+
+# Run the web UI
+uv run streamlit run streamlit_app.py
+
+# Build package
+uv build
+
+# Publish to PyPI
+uv publish --token <token>
+```
+
+## Architecture
+
+```
+merleau/
+├── merleau/
+│   ├── __init__.py    # Package version
+│   └── cli.py         # CLI + core analyze_video() function
+├── streamlit_app.py   # Web UI (run with: streamlit run streamlit_app.py)
+├── website/           # Landing page (GitHub Pages)
+│   └── index.html     # Single-page site
+├── research/          # Market research and positioning
+├── pyproject.toml     # Package config with [project.scripts] entry point
+└── analyze_video.py   # Legacy standalone script
+```
+
+### CLI Flow (merleau/cli.py)
+1. Parse arguments (video path, prompt, model, cost flag)
+2. Load API key from environment or `.env`
+3. Upload video to Gemini Files API
+4. Poll for processing completion
+5. Generate content analysis
+6. Display results and optional cost breakdown
+
+## Key Differentiators
+
+- **Native Gemini video** - Only CLI with true video understanding (not frame extraction)
+- **YouTube URL support** - Direct analysis via Gemini's preview feature
+- **Cost transparency** - Token usage and pricing shown by default
+
+## Configuration
+
+- `.env` - Contains `GEMINI_API_KEY` (required)
+- `pyproject.toml` - Package metadata, dependencies, and CLI entry point

{merleau-0.1.1 → merleau-0.3.0}/PKG-INFO

@@ -1,7 +1,9 @@
 Metadata-Version: 2.4
 Name: merleau
-Version: 0.1.1
+Version: 0.3.0
 Summary: Video analysis using Google's Gemini 2.5 Flash API
 Requires-Python: >=3.10
 Requires-Dist: google-genai
 Requires-Dist: python-dotenv
+Provides-Extra: web
+Requires-Dist: streamlit>=1.30.0; extra == 'web'

merleau-0.3.0/README.md

@@ -0,0 +1,127 @@
+# Merleau
+
+> *"The world is not what I think, but what I live through."*
+> — Maurice Merleau-Ponty
+
+A CLI tool for video understanding using Google's Gemini API. Named after [Maurice Merleau-Ponty](https://en.wikipedia.org/wiki/Maurice_Merleau-Ponty), the phenomenologist philosopher whose work on perception inspires how this tool helps you perceive your videos.
+
+**[Website](https://yanndebray.github.io/merleau/)** · **[PyPI](https://pypi.org/project/merleau/)** · **[GitHub](https://github.com/yanndebray/merleau)**
+
+https://github.com/user-attachments/assets/e2c5b476-ddab-49ab-a35c-9ae5e880c25c
+
+## Why Merleau?
+
+Google Gemini is the **only major AI provider** with native video understanding—Claude doesn't support video, and GPT-4o requires frame extraction workarounds. Merleau is the first CLI that actually understands video rather than analyzing frames.
+
+## Features
+
+- **Native Gemini video processing** - Upload and analyze videos directly
+- **YouTube URL support** - Analyze videos directly from YouTube (free preview)
+- **Customizable prompts** - Ask any question about your video
+- **Cost estimation** - Token usage tracking and cost breakdown
+- **Multiple models** - Support for different Gemini models
+- **Web UI** - Streamlit app for browser-based analysis
+
+## Installation
+
+Using [uv](https://docs.astral.sh/uv/) (recommended):
+```bash
+uv sync
+```
+
+Or install from PyPI:
+```bash
+pip install merleau
+```
+
+## Configuration
+
+1. Get a Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey)
+2. Set the API key as an environment variable or create a `.env` file:
+   ```
+   GEMINI_API_KEY=your_api_key_here
+   ```
+
+## Usage
+
+```bash
+# Basic video analysis
+ponty video.mp4
+
+# Custom prompt
+ponty video.mp4 -p "Summarize the key points in this video"
+
+# Use a different model
+ponty video.mp4 -m gemini-2.0-flash
+
+# Hide cost information
+ponty video.mp4 --no-cost
+```
+
+### Web UI
+
+```bash
+# Install with web dependencies
+pip install merleau[web]
+
+# Run the Streamlit app
+streamlit run streamlit_app.py
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --prompt` | Prompt for the analysis (default: "Explain what happens in this video") |
+| `-m, --model` | Gemini model to use (default: gemini-2.5-flash) |
+| `--no-cost` | Hide usage and cost information |
+
+## Reducing Costs with Compression
+
+Compressing videos before analysis can reduce API costs by ~10-15% without degrading analysis quality. Gemini's token count is affected by video resolution and bitrate.
+
+### Quick Compression with ffmpeg
+
+```bash
+# Basic compression (recommended)
+ffmpeg -i input.mp4 -vcodec libx264 -crf 28 -preset medium -vf "scale=1280:-2" output.mp4
+
+# Aggressive compression (smaller file, lower quality)
+ffmpeg -i input.mp4 -vcodec libx264 -crf 32 -preset medium -vf "scale=640:-2" output.mp4
+
+# Keep audio (for speech analysis)
+ffmpeg -i input.mp4 -vcodec libx264 -crf 28 -preset medium -vf "scale=1280:-2" -acodec aac -b:a 128k output.mp4
+```
+
+### Compression Options Explained
+
+| Option | Description |
+|--------|-------------|
+| `-crf 28` | Quality level (18-28 recommended, higher = smaller file) |
+| `-preset medium` | Encoding speed/quality tradeoff |
+| `-vf "scale=1280:-2"` | Resize to 1280px width, maintain aspect ratio |
+| `-an` | Remove audio (if not needed) |
+| `-acodec aac -b:a 128k` | Compress audio to 128kbps AAC |
+
+### Cost Comparison Example
+
+| Version | File Size | Prompt Tokens | Input Cost |
+|---------|-----------|---------------|------------|
+| Original (1080p) | 52 MB | 14,757 | $0.00221 |
+| Compressed (720p) | 2.6 MB | 13,157 | $0.00197 |
+| **Savings** | **95%** | **10.8%** | **10.8%** |
+
+## Output
+
+The CLI provides:
+- Video content analysis from Gemini
+- Token usage breakdown (prompt, response, total)
+- Estimated cost based on Gemini pricing
+
+## Pricing Reference
+
+Gemini 2.5 Flash (as of 2025):
+- Input: $0.15 per 1M tokens (text/image), $0.075 per 1M tokens (video)
+- Output: $0.60 per 1M tokens, $3.50 for thinking tokens
+
+A 1-hour video costs approximately **$0.11-0.32** to analyze.

merleau-0.3.0/analyze_video.py

@@ -0,0 +1,56 @@
+import os
+import time
+from dotenv import load_dotenv
+from google import genai
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Initialize the client with the API key
+client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
+
+# Upload the video file
+video_path = "MATLAB_Modernizer.mp4"
+print(f"Uploading video: {video_path}")
+myfile = client.files.upload(file=video_path)
+print(f"Upload complete. File URI: {myfile.uri}")
+
+# Wait for the file to be processed (become ACTIVE)
+print("Waiting for file to be processed...")
+while myfile.state.name == "PROCESSING":
+    print(".", end="", flush=True)
+    time.sleep(2)
+    myfile = client.files.get(name=myfile.name)
+
+if myfile.state.name == "FAILED":
+    raise ValueError(f"File processing failed: {myfile.state.name}")
+
+print(f"\nFile state: {myfile.state.name}")
+
+# Generate content using Gemini 2.5 Flash
+print("\nAnalyzing video with Gemini 2.5 Flash...")
+response = client.models.generate_content(
+    model="gemini-2.5-flash",
+    contents=[myfile, "Explain what happens in this video"]
+)
+print("\n--- Video Analysis ---")
+print(response.text)
+
+# Show usage/cost information
+print("\n--- Usage Information ---")
+if hasattr(response, 'usage_metadata'):
+    usage = response.usage_metadata
+    print(f"Prompt tokens: {usage.prompt_token_count}")
+    print(f"Response tokens: {usage.candidates_token_count}")
+    print(f"Total tokens: {usage.total_token_count}")
+
+    # Gemini 2.5 Flash pricing (as of 2025):
+    # Input: $0.15 per 1M tokens (text/image), $0.075 per 1M tokens for video
+    # Output: $0.60 per 1M tokens, $3.50 for thinking tokens
+    input_cost = (usage.prompt_token_count / 1_000_000) * 0.15
+    output_cost = (usage.candidates_token_count / 1_000_000) * 0.60
+    total_cost = input_cost + output_cost
+    print(f"\nEstimated cost:")
+    print(f"  Input:  ${input_cost:.6f}")
+    print(f"  Output: ${output_cost:.6f}")
+    print(f"  Total:  ${total_cost:.6f}")

merleau-0.3.0/merleau/__init__.py

@@ -0,0 +1,3 @@
+"""Merleau - Video analysis using Google's Gemini API."""
+
+__version__ = "0.3.0"

merleau-0.3.0/merleau/cli.py

@@ -0,0 +1,215 @@
+"""Command-line interface for Merleau video analysis."""
+
+import argparse
+import os
+import sys
+import time
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from dotenv import load_dotenv
+from google import genai
+
+
+@dataclass
+class AnalysisResult:
+    """Result from video analysis."""
+    text: str
+    prompt_tokens: int
+    response_tokens: int
+    total_tokens: int
+    input_cost: float
+    output_cost: float
+    total_cost: float
+
+
+def wait_for_processing(client, file, on_progress: Optional[Callable] = None):
+    """Wait for file to finish processing."""
+    while file.state.name == "PROCESSING":
+        if on_progress:
+            on_progress()
+        else:
+            print(".", end="", flush=True)
+        time.sleep(2)
+        file = client.files.get(name=file.name)
+    if not on_progress:
+        print()
+    return file
+
+
+def calculate_cost(usage):
+    """Calculate cost from usage metadata."""
+    # Gemini 2.5 Flash pricing (as of 2025):
+    # Input: $0.15 per 1M tokens (text/image), $0.075 per 1M tokens for video
+    # Output: $0.60 per 1M tokens, $3.50 for thinking tokens
+    input_cost = (usage.prompt_token_count / 1_000_000) * 0.15
+    output_cost = (usage.candidates_token_count / 1_000_000) * 0.60
+    return input_cost, output_cost, input_cost + output_cost
+
+
+def print_usage(usage):
+    """Print token usage and cost estimation."""
+    print("\n--- Usage Information ---")
+    print(f"Prompt tokens: {usage.prompt_token_count}")
+    print(f"Response tokens: {usage.candidates_token_count}")
+    print(f"Total tokens: {usage.total_token_count}")
+
+    input_cost, output_cost, total_cost = calculate_cost(usage)
+    print(f"\nEstimated cost:")
+    print(f"  Input:  ${input_cost:.6f}")
+    print(f"  Output: ${output_cost:.6f}")
+    print(f"  Total:  ${total_cost:.6f}")
+
+
+def analyze_video(
+    video_path: str,
+    prompt: str = "Explain what happens in this video",
+    model: str = "gemini-2.5-flash",
+    api_key: Optional[str] = None,
+    on_upload: Optional[Callable[[str], None]] = None,
+    on_processing: Optional[Callable] = None,
+    on_analyzing: Optional[Callable] = None,
+) -> AnalysisResult:
+    """
+    Analyze a video file using Gemini.
+
+    Args:
+        video_path: Path to the video file
+        prompt: Analysis prompt
+        model: Gemini model to use
+        api_key: Optional API key (falls back to env var)
+        on_upload: Callback when upload completes (receives file URI)
+        on_processing: Callback during processing (called repeatedly)
+        on_analyzing: Callback when analysis starts
+
+    Returns:
+        AnalysisResult with text, tokens, and cost
+
+    Raises:
+        ValueError: If API key not found or file doesn't exist
+        RuntimeError: If file processing fails
+    """
+    load_dotenv()
+
+    api_key = api_key or os.getenv("GEMINI_API_KEY")
+    if not api_key:
+        raise ValueError("GEMINI_API_KEY not found in environment or .env file")
+
+    if not os.path.exists(video_path):
+        raise ValueError(f"Video file not found: {video_path}")
+
+    client = genai.Client(api_key=api_key)
+
+    # Upload video
+    myfile = client.files.upload(file=video_path)
+    if on_upload:
+        on_upload(myfile.uri)
+
+    # Wait for processing
+    myfile = wait_for_processing(client, myfile, on_progress=on_processing)
+
+    if myfile.state.name == "FAILED":
+        raise RuntimeError("File processing failed")
+
+    # Generate analysis
+    if on_analyzing:
+        on_analyzing()
+
+    response = client.models.generate_content(
+        model=model,
+        contents=[myfile, prompt]
+    )
+
+    # Extract usage info
+    usage = response.usage_metadata
+    input_cost, output_cost, total_cost = calculate_cost(usage)
+
+    return AnalysisResult(
+        text=response.text,
+        prompt_tokens=usage.prompt_token_count,
+        response_tokens=usage.candidates_token_count,
+        total_tokens=usage.total_token_count,
+        input_cost=input_cost,
+        output_cost=output_cost,
+        total_cost=total_cost,
+    )
+
+
+def analyze(video_path, prompt, model, show_cost):
+    """Analyze a video file using Gemini (CLI wrapper)."""
+    try:
+        print(f"Uploading video: {video_path}")
+
+        def on_upload(uri):
+            print(f"Upload complete. File URI: {uri}")
+            print("Waiting for file to be processed...", end="")
+
+        def on_processing():
+            print(".", end="", flush=True)
+
+        def on_analyzing():
+            print()
+            print(f"\nAnalyzing video with {model}...")
+
+        result = analyze_video(
+            video_path=video_path,
+            prompt=prompt,
+            model=model,
+            on_upload=on_upload,
+            on_processing=on_processing,
+            on_analyzing=on_analyzing,
+        )
+
+        print("\n--- Video Analysis ---")
+        print(result.text)
+
+        if show_cost:
+            print("\n--- Usage Information ---")
+            print(f"Prompt tokens: {result.prompt_tokens}")
+            print(f"Response tokens: {result.response_tokens}")
+            print(f"Total tokens: {result.total_tokens}")
+            print(f"\nEstimated cost:")
+            print(f"  Input:  ${result.input_cost:.6f}")
+            print(f"  Output: ${result.output_cost:.6f}")
+            print(f"  Total:  ${result.total_cost:.6f}")
+
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except RuntimeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    """Main entry point for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="ponty",
+        description="Analyze videos using Google's Gemini API"
+    )
+    parser.add_argument(
+        "video",
+        help="Path to the video file to analyze"
+    )
+    parser.add_argument(
+        "-p", "--prompt",
+        default="Explain what happens in this video",
+        help="Prompt for the analysis (default: 'Explain what happens in this video')"
+    )
+    parser.add_argument(
+        "-m", "--model",
+        default="gemini-2.5-flash",
+        help="Gemini model to use (default: gemini-2.5-flash)"
+    )
+    parser.add_argument(
+        "--no-cost",
+        action="store_true",
+        help="Hide usage and cost information"
+    )
+
+    args = parser.parse_args()
+    analyze(args.video, args.prompt, args.model, show_cost=not args.no_cost)
+
+
+if __name__ == "__main__":
+    main()

merleau-0.3.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "merleau"
+version = "0.3.0"
+description = "Video analysis using Google's Gemini 2.5 Flash API"
+requires-python = ">=3.10"
+dependencies = [
+    "google-genai",
+    "python-dotenv",
+]
+
+[project.optional-dependencies]
+web = ["streamlit>=1.30.0"]
+
+[project.scripts]
+ponty = "merleau.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"