Add bookviz CLI and gallery workflow

Author: aivuk

.github/workflows/pages.yml

@@ -0,0 +1,47 @@
+name: Deploy Gallery
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Build gallery
+        run: uv run bookviz gallery --input books --output site --metrics word-freq lexical-diversity --window-size 200
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.pyc
+outputs/
+site/
+books/gutenberg/
+

README.md

@@ -0,0 +1,98 @@
+# Language Experiments
+
+Language Experiments turns books into visual fingerprints. It tokenizes a text,
+computes a linguistic metric, maps the metric to colors, and writes PNG and
+HTML viewers where each pixel represents a token or a sliding window of tokens.
+
+## Setup
+
+```bash
+uv sync
+```
+
+## Commands
+
+List available metrics and color maps:
+
+```bash
+uv run bookviz list
+```
+
+Render one book:
+
+```bash
+uv run bookviz render books/dubliners.txt --metric word-freq --color heat --html
+```
+
+The legacy form still works:
+
+```bash
+uv run python book_png.py books/dubliners.txt --metric word-freq --html
+```
+
+Render a sliding-window view:
+
+```bash
+uv run bookviz render books/ulysses.txt \
+  --metric lexical-diversity \
+  --window-size 200 \
+  --window-step 50 \
+  --html
+```
+
+Compare books with shared color normalization:
+
+```bash
+uv run bookviz compare \
+  books/dubliners.txt books/ulysses.txt books/moby-dick.txt \
+  --metric lexical-diversity \
+  --window-size 200 \
+  --output outputs/comparison.png \
+  --html
+```
+
+Download a book from Project Gutenberg:
+
+```bash
+uv run bookviz gutenberg 2701 --title moby-dick
+```
+
+Generate a static gallery:
+
+```bash
+uv run bookviz gallery \
+  --input books \
+  --output site \
+  --metrics word-freq lexical-diversity bigram-diversity \
+  --window-size 200
+```
+
+## Metrics
+
+Token metrics:
+
+- `word-freq`
+- `word-freq-linear`
+- `bigram-prob`
+- `bigram-diversity`
+- `word-length`
+- `word-position`
+- `unique-word`
+
+Window metrics:
+
+- `avg-word-length`
+- `lexical-diversity`
+- `punctuation-density`
+- `repetition-density`
+- `sentence-length`
+
+Token metrics can also be used with `--window-size`; their values are averaged
+inside each window.
+
+## GitHub Pages
+
+The workflow at `.github/workflows/pages.yml` builds the gallery with `uv` and
+publishes the generated `site/` directory to GitHub Pages. Enable Pages in the
+repository settings and choose GitHub Actions as the source.
+