merleau 0.2.0__tar.gz → 0.3.0__tar.gz

{merleau-0.2.0 → merleau-0.3.0}/CLAUDE.md

@@ -13,11 +13,15 @@ See `research/positioning_merleau.md` for market positioning and differentiation
 ```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
 
@@ -31,7 +35,10 @@ uv publish --token <token>
 merleau/
 ├── merleau/
 │   ├── __init__.py    # Package version
-│   └── cli.py         # CLI entry point (ponty command)
+│   └── 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

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

@@ -1,7 +1,9 @@
 Metadata-Version: 2.4
 Name: merleau
-Version: 0.2.0
+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.2.0 → merleau-0.3.0}/README.md

@@ -5,6 +5,10 @@
 
 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.
@@ -16,6 +20,7 @@ Google Gemini is the **only major AI provider** with native video understanding
 - **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
 
@@ -53,6 +58,16 @@ ponty video.mp4 -m gemini-2.0-flash
 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 |
@@ -61,6 +76,41 @@ ponty video.mp4 --no-cost
 | `-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:

{merleau-0.2.0 → merleau-0.3.0}/merleau/__init__.py

@@ -1,3 +1,3 @@
 """Merleau - Video analysis using Google's Gemini API."""
 
-__version__ = "0.2.0"
+__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.2.0 → merleau-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "merleau"
-version = "0.2.0"
+version = "0.3.0"
 description = "Video analysis using Google's Gemini 2.5 Flash API"
 requires-python = ">=3.10"
 dependencies = [
@@ -8,6 +8,9 @@ dependencies = [
     "python-dotenv",
 ]
 
+[project.optional-dependencies]
+web = ["streamlit>=1.30.0"]
+
 [project.scripts]
 ponty = "merleau.cli:main"
 

merleau-0.3.0/streamlit_app.py

@@ -0,0 +1,178 @@
+"""Streamlit web interface for Merleau video analysis."""
+
+import os
+import tempfile
+
+import streamlit as st
+from dotenv import load_dotenv
+
+from merleau.cli import AnalysisResult, analyze_video
+
+# Page config
+st.set_page_config(
+    page_title="Merleau - Video Understanding",
+    page_icon="👁️",
+    layout="centered",
+)
+
+# Load environment variables
+load_dotenv()
+
+
+# Header
+st.title("👁️ Merleau")
+st.markdown("*Video understanding from your browser*")
+
+# Sidebar for settings
+with st.sidebar:
+    st.header("Settings")
+
+    api_key = st.text_input(
+        "Gemini API Key",
+        type="password",
+        value=os.getenv("GEMINI_API_KEY", ""),
+        help="Get your key from [Google AI Studio](https://aistudio.google.com/apikey)"
+    )
+
+    model = st.selectbox(
+        "Model",
+        ["gemini-2.5-flash", "gemini-2.0-flash", "gemini-1.5-pro"],
+        index=0,
+    )
+
+    st.divider()
+    st.markdown("""
+    **Links**
+    - [GitHub](https://github.com/yanndebray/merleau)
+    - [PyPI](https://pypi.org/project/merleau/)
+    - [Documentation](https://yanndebray.github.io/merleau/)
+    """)
+
+# Main content
+tab1, tab2 = st.tabs(["📁 Upload Video", "🎬 Record Screen"])
+
+with tab1:
+    uploaded_file = st.file_uploader(
+        "Choose a video file",
+        type=["mp4", "mov", "avi", "mkv", "webm"],
+        help="Supported formats: MP4, MOV, AVI, MKV, WebM"
+    )
+
+    if uploaded_file:
+        st.video(uploaded_file)
+
+with tab2:
+    st.info("🎥 **Screen Recording** - Use your browser's built-in screen capture, then upload the recording above.")
+    st.markdown("""
+    **Quick recording options:**
+    1. **Windows**: `Win + G` → Record
+    2. **Mac**: `Cmd + Shift + 5` → Screen Recording
+    3. **Chrome**: Extensions like Loom or Screencastify
+    """)
+
+# Prompt input
+st.divider()
+prompt = st.text_area(
+    "What would you like to know about the video?",
+    value="Explain what happens in this video",
+    height=100,
+)
+
+# Analyze button
+col1, col2 = st.columns([3, 1])
+with col1:
+    analyze_btn = st.button("🔍 Analyze Video", type="primary", use_container_width=True)
+with col2:
+    show_cost = st.checkbox("Show cost", value=True)
+
+# Analysis
+if analyze_btn:
+    if not api_key:
+        st.error("Please enter your Gemini API key in the sidebar.")
+    elif not uploaded_file:
+        st.warning("Please upload a video file first.")
+    else:
+        # Save uploaded file to temp location
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".mp4") as tmp:
+            tmp.write(uploaded_file.getvalue())
+            tmp_path = tmp.name
+
+        try:
+            # Progress indicators
+            progress_text = st.empty()
+            progress_bar = st.progress(0)
+
+            progress_text.text("📤 Uploading video...")
+            progress_bar.progress(10)
+
+            def on_upload(uri):
+                progress_text.text("⏳ Processing video...")
+                progress_bar.progress(30)
+
+            processing_dots = [0]
+            def on_processing():
+                processing_dots[0] += 1
+                progress = min(30 + (processing_dots[0] * 5), 70)
+                progress_bar.progress(progress)
+
+            def on_analyzing():
+                progress_text.text("🧠 Analyzing with Gemini...")
+                progress_bar.progress(80)
+
+            result: AnalysisResult = analyze_video(
+                video_path=tmp_path,
+                prompt=prompt,
+                model=model,
+                api_key=api_key,
+                on_upload=on_upload,
+                on_processing=on_processing,
+                on_analyzing=on_analyzing,
+            )
+
+            progress_bar.progress(100)
+            progress_text.empty()
+            progress_bar.empty()
+
+            # Display results
+            st.success("Analysis complete!")
+
+            st.markdown("### 📝 Analysis")
+            st.markdown(result.text)
+
+            if show_cost:
+                st.divider()
+                col1, col2, col3 = st.columns(3)
+                with col1:
+                    st.metric("Prompt Tokens", f"{result.prompt_tokens:,}")
+                with col2:
+                    st.metric("Response Tokens", f"{result.response_tokens:,}")
+                with col3:
+                    st.metric("Total Cost", f"${result.total_cost:.4f}")
+
+            # Store in session for history
+            if "history" not in st.session_state:
+                st.session_state.history = []
+            st.session_state.history.append({
+                "filename": uploaded_file.name,
+                "prompt": prompt,
+                "result": result.text,
+                "cost": result.total_cost,
+            })
+
+        except Exception as e:
+            st.error(f"Error: {e}")
+        finally:
+            # Cleanup temp file
+            if os.path.exists(tmp_path):
+                os.unlink(tmp_path)
+
+# History section
+if "history" in st.session_state and st.session_state.history:
+    st.divider()
+    with st.expander(f"📜 Analysis History ({len(st.session_state.history)} items)"):
+        for i, item in enumerate(reversed(st.session_state.history)):
+            st.markdown(f"**{item['filename']}** - ${item['cost']:.4f}")
+            st.caption(f"Prompt: {item['prompt'][:50]}...")
+            if st.button(f"Show full analysis", key=f"history_{i}"):
+                st.markdown(item['result'])
+            st.divider()