alt-text-llm 0.1.0__tar.gz

alt_text_llm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexander Turner (TurnTrout)
+
+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.

alt_text_llm-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include README.md LICENSE

alt_text_llm-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: alt-text-llm
+Version: 0.1.0
+Summary: AI-powered alt text generation and labeling tools for markdown content
+Author: TurnTrout
+License-Expression: MIT
+Project-URL: Repository, https://github.com/alexander-turner/alt-text-llm
+Keywords: alt-text,accessibility,markdown,llm,ai
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gitpython
+Requires-Dist: requests
+Requires-Dist: ruamel.yaml
+Requires-Dist: markdown-it-py
+Requires-Dist: rich
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Dynamic: license-file
+
+# alt-text-llm
+
+AI-powered alt text generation and labeling tools for markdown content. Originally developed for [my website](https://turntrout.com/design) ([repo](https://github.com/alexander-turner/TurnTrout.com)).
+
+## Installation
+
+### Quick install from GitHub
+
+```bash
+pip install git+https://github.com/alexander-turner/alt-text-llm.git
+```
+
+### Automated setup (includes system dependencies)
+
+```bash
+git clone https://github.com/alexander-turner/alt-text-llm.git
+cd alt-text-llm
+./setup.sh
+```
+
+## Prerequisites
+
+The following command-line tools must be installed:
+
+- **`llm`** - LLM interface ([install instructions](https://llm.datasette.io/))
+- **`git`** - Version control
+- **`magick`** (ImageMagick) - Image processing
+- **`ffmpeg`** - Video processing
+- **`imgcat`** - Terminal image display
+
+**macOS:**
+
+```bash
+brew install imagemagick ffmpeg imgcat
+pip install llm
+```
+
+**Linux:**
+
+```bash
+sudo apt-get install imagemagick ffmpeg
+pip install llm
+# imgcat: curl -sL https://iterm2.com/utilities/imgcat -o ~/.local/bin/imgcat && chmod +x ~/.local/bin/imgcat
+```
+
+## Usage
+
+The tool provides three main commands: `scan`, `generate`, and `label`.
+
+### 1. Scan for missing alt text
+
+Scan your markdown files to find images without meaningful alt text:
+
+```bash
+alt-text-llm scan --root /path/to/markdown/files
+```
+
+This creates `asset_queue.json` with all assets needing alt text.
+
+### 2. Generate AI suggestions
+
+Generate alt text suggestions using an LLM:
+
+```bash
+alt-text-llm generate \
+  --root /path/to/markdown/files \
+  --model gemini-2.5-flash \
+  --suggestions-file suggested_alts.json
+```
+
+**Available options:**
+
+- `--model` (required) - LLM model to use (e.g., `gemini-2.5-flash`, `gpt-4o-mini`, `claude-3-5-sonnet`)
+- `--max-chars` - Maximum characters for alt text (default: 300)
+- `--timeout` - LLM timeout in seconds (default: 120)
+- `--estimate-only` - Only show cost estimate without generating
+- `--process-existing` - Also process assets that already have captions
+
+**Cost estimation:**
+
+```bash
+alt-text-llm generate \
+  --root /path/to/markdown/files \
+  --model gemini-2.5-flash \
+  --estimate-only
+```
+
+### 3. Label and approve suggestions
+
+Interactively review and approve the AI-generated suggestions:
+
+```bash
+alt-text-llm label \
+  --suggestions-file suggested_alts.json \
+  --output asset_captions.json
+```
+
+**Interactive commands:**
+
+- Edit the suggested alt text (vim keybindings enabled)
+- Press Enter to accept the suggestion as-is
+- Submit `undo` or `u` to go back to the previous item
+- Images display in your terminal (requires `imgcat`)
+
+## Example workflow
+
+```bash
+# 1. Scan markdown files for missing alt text
+alt-text-llm scan --root ./content
+
+# 2. Estimate the cost
+alt-text-llm generate \
+  --root ./content \
+  --model gemini-2.5-flash \
+  --estimate-only
+
+# 3. Generate suggestions (if cost is acceptable)
+alt-text-llm generate \
+  --root ./content \
+  --model gemini-2.5-flash
+
+# 4. Review and approve suggestions
+alt-text-llm label
+```
+
+## Configuration
+
+### LLM Integration
+
+This tool uses the [`llm` CLI tool](https://llm.datasette.io/) to generate alt text. This provides access to many different AI models including:
+
+- **Gemini** (Google) via the [llm-gemini plugin](https://github.com/simonw/llm-gemini)
+- **Claude** (Anthropic) via the [llm-claude-3 plugin](https://github.com/tomviner/llm-claude-3)
+- And [many more via plugins](https://llm.datasette.io/en/stable/plugins/directory.html)
+
+### Setting up your model
+
+**For Gemini models (default):**
+
+```bash
+llm install llm-gemini
+llm keys set gemini # enter API key
+llm -m gemini-2.5-flash "Hello, world!"
+```
+
+**For other models:**
+
+1. Install the appropriate llm plugin (e.g., `llm install llm-openai`)
+2. Configure your API key (e.g., `llm keys set openai`)
+3. Use the model name with `--model` flag (e.g., `--model gpt-4o-mini`)
+
+See the [llm documentation](https://llm.datasette.io/en/stable/setup.html) for setup instructions and the [plugin directory](https://llm.datasette.io/en/stable/plugins/directory.html) for available models.
+
+## Output files
+
+- `asset_queue.json` - Queue of assets needing alt text (from `scan`)
+- `suggested_alts.json` - AI-generated suggestions (from `generate`)
+- `asset_captions.json` - Approved final captions (from `label`)

alt_text_llm-0.1.0/README.md

@@ -0,0 +1,158 @@
+# alt-text-llm
+
+AI-powered alt text generation and labeling tools for markdown content. Originally developed for [my website](https://turntrout.com/design) ([repo](https://github.com/alexander-turner/TurnTrout.com)).
+
+## Installation
+
+### Quick install from GitHub
+
+```bash
+pip install git+https://github.com/alexander-turner/alt-text-llm.git
+```
+
+### Automated setup (includes system dependencies)
+
+```bash
+git clone https://github.com/alexander-turner/alt-text-llm.git
+cd alt-text-llm
+./setup.sh
+```
+
+## Prerequisites
+
+The following command-line tools must be installed:
+
+- **`llm`** - LLM interface ([install instructions](https://llm.datasette.io/))
+- **`git`** - Version control
+- **`magick`** (ImageMagick) - Image processing
+- **`ffmpeg`** - Video processing
+- **`imgcat`** - Terminal image display
+
+**macOS:**
+
+```bash
+brew install imagemagick ffmpeg imgcat
+pip install llm
+```
+
+**Linux:**
+
+```bash
+sudo apt-get install imagemagick ffmpeg
+pip install llm
+# imgcat: curl -sL https://iterm2.com/utilities/imgcat -o ~/.local/bin/imgcat && chmod +x ~/.local/bin/imgcat
+```
+
+## Usage
+
+The tool provides three main commands: `scan`, `generate`, and `label`.
+
+### 1. Scan for missing alt text
+
+Scan your markdown files to find images without meaningful alt text:
+
+```bash
+alt-text-llm scan --root /path/to/markdown/files
+```
+
+This creates `asset_queue.json` with all assets needing alt text.
+
+### 2. Generate AI suggestions
+
+Generate alt text suggestions using an LLM:
+
+```bash
+alt-text-llm generate \
+  --root /path/to/markdown/files \
+  --model gemini-2.5-flash \
+  --suggestions-file suggested_alts.json
+```
+
+**Available options:**
+
+- `--model` (required) - LLM model to use (e.g., `gemini-2.5-flash`, `gpt-4o-mini`, `claude-3-5-sonnet`)
+- `--max-chars` - Maximum characters for alt text (default: 300)
+- `--timeout` - LLM timeout in seconds (default: 120)
+- `--estimate-only` - Only show cost estimate without generating
+- `--process-existing` - Also process assets that already have captions
+
+**Cost estimation:**
+
+```bash
+alt-text-llm generate \
+  --root /path/to/markdown/files \
+  --model gemini-2.5-flash \
+  --estimate-only
+```
+
+### 3. Label and approve suggestions
+
+Interactively review and approve the AI-generated suggestions:
+
+```bash
+alt-text-llm label \
+  --suggestions-file suggested_alts.json \
+  --output asset_captions.json
+```
+
+**Interactive commands:**
+
+- Edit the suggested alt text (vim keybindings enabled)
+- Press Enter to accept the suggestion as-is
+- Submit `undo` or `u` to go back to the previous item
+- Images display in your terminal (requires `imgcat`)
+
+## Example workflow
+
+```bash
+# 1. Scan markdown files for missing alt text
+alt-text-llm scan --root ./content
+
+# 2. Estimate the cost
+alt-text-llm generate \
+  --root ./content \
+  --model gemini-2.5-flash \
+  --estimate-only
+
+# 3. Generate suggestions (if cost is acceptable)
+alt-text-llm generate \
+  --root ./content \
+  --model gemini-2.5-flash
+
+# 4. Review and approve suggestions
+alt-text-llm label
+```
+
+## Configuration
+
+### LLM Integration
+
+This tool uses the [`llm` CLI tool](https://llm.datasette.io/) to generate alt text. This provides access to many different AI models including:
+
+- **Gemini** (Google) via the [llm-gemini plugin](https://github.com/simonw/llm-gemini)
+- **Claude** (Anthropic) via the [llm-claude-3 plugin](https://github.com/tomviner/llm-claude-3)
+- And [many more via plugins](https://llm.datasette.io/en/stable/plugins/directory.html)
+
+### Setting up your model
+
+**For Gemini models (default):**
+
+```bash
+llm install llm-gemini
+llm keys set gemini # enter API key
+llm -m gemini-2.5-flash "Hello, world!"
+```
+
+**For other models:**
+
+1. Install the appropriate llm plugin (e.g., `llm install llm-openai`)
+2. Configure your API key (e.g., `llm keys set openai`)
+3. Use the model name with `--model` flag (e.g., `--model gpt-4o-mini`)
+
+See the [llm documentation](https://llm.datasette.io/en/stable/setup.html) for setup instructions and the [plugin directory](https://llm.datasette.io/en/stable/plugins/directory.html) for available models.
+
+## Output files
+
+- `asset_queue.json` - Queue of assets needing alt text (from `scan`)
+- `suggested_alts.json` - AI-generated suggestions (from `generate`)
+- `asset_captions.json` - Approved final captions (from `label`)

alt_text_llm-0.1.0/alt_text_llm/__init__.py

@@ -0,0 +1,13 @@
+"""AI-powered alt text generation and labeling tools."""
+
+__version__ = "0.1.0"
+
+from alt_text_llm import generate, label, main, scan, utils
+
+__all__ = [
+    "generate",
+    "label",
+    "main",
+    "scan",
+    "utils",
+]

alt_text_llm-0.1.0/alt_text_llm/generate.py

@@ -0,0 +1,208 @@
+"""Generate AI alt text suggestions for assets lacking meaningful alt text."""
+
+import asyncio
+import shutil
+import subprocess
+import tempfile
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from rich.console import Console
+from tqdm.rich import tqdm
+from tqdm.std import TqdmExperimentalWarning
+
+from alt_text_llm import scan, utils
+
+warnings.filterwarnings("ignore", category=TqdmExperimentalWarning)
+
+# Approximate cost estimates per 1000 tokens (as of Sep 2025)
+MODEL_COSTS = {
+    # https://www.helicone.ai/llm-cost
+    "gemini-2.5-pro": {"input": 0.00125, "output": 0.01},
+    "gemini-2.5-flash": {"input": 0.0003, "output": 0.0025},
+    "gemini-2.5-flash-lite": {"input": 0.00001, "output": 0.00004},
+    # https://developers.googleblog.com/en/continuing-to-bring-you-our-latest-models-with-an-improved-gemini-2-5-flash-and-flash-lite-release/?ref=testingcatalog.com
+    "gemini-2.5-flash-lite-preview-09-2025": {
+        "input": 0.00001,
+        "output": 0.00004,
+    },
+    "gemini-2.5-flash-preview-09-2025": {"input": 0.00001, "output": 0.00004},
+}
+
+
+def _run_llm(
+    attachment: Path,
+    prompt: str,
+    model: str,
+    timeout: int,
+) -> str:
+    """Execute LLM command and return generated caption."""
+    llm_path = utils.find_executable("llm")
+
+    result = subprocess.run(
+        [llm_path, "-m", model, "-a", str(attachment), "--usage", prompt],
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+
+    if result.returncode != 0:
+        error_output = result.stderr.strip() or result.stdout.strip()
+        raise utils.AltGenerationError(
+            f"Caption generation failed for {attachment}: {error_output}"
+        )
+
+    cleaned = result.stdout.strip()
+    if not cleaned:
+        raise utils.AltGenerationError("LLM returned empty caption")
+    return cleaned
+
+
+@dataclass(slots=True)
+class GenerateAltTextOptions:
+    """Options for generating alt text."""
+
+    root: Path
+    model: str
+    max_chars: int
+    timeout: int
+    output_path: Path
+    skip_existing: bool = False
+
+
+def estimate_cost(
+    model: str,
+    queue_count: int,
+    avg_prompt_tokens: int = 4500,
+    avg_output_tokens: int = 1500,
+) -> str:
+    """Estimate the cost of processing the queue with the given model."""
+    # Normalize model name for cost lookup
+    model_lower = model.lower()
+
+    if model_lower in MODEL_COSTS:
+        cost_info = MODEL_COSTS[model_lower]
+    else:
+        return f"Can't estimate cost for unknown model: {model}. Available models: {MODEL_COSTS.keys()}"
+
+    # Calculate costs
+    input_cost = (avg_prompt_tokens * queue_count / 1000) * cost_info["input"]
+    output_cost = (avg_output_tokens * queue_count / 1000) * cost_info[
+        "output"
+    ]
+    total_cost = input_cost + output_cost
+
+    return f"Estimated cost: ${total_cost:.3f} (${input_cost:.3f} input + ${output_cost:.3f} output)"
+
+
+def filter_existing_captions(
+    queue_items: Sequence["scan.QueueItem"],
+    output_paths: Sequence[Path],
+    console: Console,
+    verbose: bool = True,
+) -> list["scan.QueueItem"]:
+    """Filter out items that already have captions in the output paths."""
+    existing_captions = set()
+    for output_path in output_paths:
+        existing_captions.update(utils.load_existing_captions(output_path))
+    original_count = len(queue_items)
+    filtered_items = [
+        item
+        for item in queue_items
+        if item.asset_path not in existing_captions
+    ]
+    skipped_count = original_count - len(filtered_items)
+    if skipped_count > 0 and verbose:
+        console.print(
+            f"[dim]Skipped {skipped_count} items with existing captions[/dim]"
+        )
+    return filtered_items
+
+
+# ---------------------------------------------------------------------------
+# Async helpers for parallel LLM calls
+# ---------------------------------------------------------------------------
+
+
+_CONCURRENCY_LIMIT = 32
+
+
+async def _run_llm_async(
+    queue_item: "scan.QueueItem",
+    options: GenerateAltTextOptions,
+    sem: asyncio.Semaphore,
+) -> utils.AltGenerationResult:
+    """Download asset, run LLM in a thread; clean up; return suggestion
+    payload."""
+    workspace = Path(tempfile.mkdtemp())
+    try:
+        async with sem:
+            attachment = await asyncio.to_thread(
+                utils.download_asset, queue_item, workspace
+            )
+            prompt = utils.build_prompt(queue_item, options.max_chars)
+            caption = await asyncio.to_thread(
+                _run_llm,
+                attachment,
+                prompt,
+                options.model,
+                options.timeout,
+            )
+        return utils.AltGenerationResult(
+            markdown_file=queue_item.markdown_file,
+            asset_path=queue_item.asset_path,
+            suggested_alt=caption,
+            model=options.model,
+            context_snippet=queue_item.context_snippet,
+            line_number=queue_item.line_number,
+        )
+    finally:
+        shutil.rmtree(workspace, ignore_errors=True)
+
+
+async def async_generate_suggestions(
+    queue_items: Sequence["scan.QueueItem"],
+    options: GenerateAltTextOptions,
+) -> list[utils.AltGenerationResult]:
+    """Generate suggestions concurrently for *queue_items*."""
+    sem = asyncio.Semaphore(_CONCURRENCY_LIMIT)
+    tasks: list[asyncio.Task[utils.AltGenerationResult]] = []
+
+    for qi in queue_items:
+        tasks.append(
+            asyncio.create_task(
+                _run_llm_async(
+                    qi,
+                    options,
+                    sem,
+                )
+            )
+        )
+
+    task_count = len(tasks)
+    if task_count == 0:
+        return []
+
+    suggestions: list[utils.AltGenerationResult] = []
+    with tqdm(total=task_count, desc="Generating alt text") as progress_bar:
+        try:
+            for finished in asyncio.as_completed(tasks):
+                try:
+                    result = await finished
+                    suggestions.append(result)
+                except (
+                    utils.AltGenerationError,
+                    FileNotFoundError,
+                ) as err:
+                    # Skip individual items that fail (e.g., unsupported file types)
+                    progress_bar.write(f"Skipped item due to error: {err}")
+                progress_bar.update(1)
+        except asyncio.CancelledError:
+            progress_bar.set_description(
+                "Generating alt text (cancelled, finishing up...)"
+            )
+
+    return suggestions