V2.2.0: Big release, OpenAI endpointing and CPU tier returns

Author: liampetti

.dockerignore

@@ -84,3 +84,11 @@ Thumbs.db
 Makefile
 docker-compose*.yml
 compose*.yml
+
+# =============================================================================
+# Re-include first-run seed files the Dockerfiles COPY into /app/seed
+# (must come AFTER the broad excludes above — last match wins)
+# =============================================================================
+!data/config.example.yml
+!data/models/grammars/
+!data/models/grammars/agent.gbnf

.env.example

@@ -1,11 +1,14 @@
 # Fulloch Environment Variables
 # Copy to .env and fill in your values; loaded automatically via python-dotenv.
+# The whole file is OPTIONAL — `docker compose up` works without it (sensible
+# defaults apply). Create it to set the values below.
 
 # =============================================================================
 # Web Search (SearXNG)
 # =============================================================================
 # Overrides server.secret_key in searxng_data/settings.yml at runtime.
-# Required by compose.yml. Generate with: openssl rand -hex 32
+# Optional — compose falls back to a placeholder for local use. Set a real value
+# before exposing SearXNG beyond localhost. Generate with: openssl rand -hex 32
 SEARXNG_SECRET=
 
 # =============================================================================
@@ -17,6 +20,17 @@ SEARXNG_SECRET=
 # openssl rand -hex 32. (HTTPS is separate — dashboard_ssl_* in config.yml.)
 FULLOCH_DASHBOARD_TOKEN=
 
+# =============================================================================
+# Remote LLM / Parloch mode (optional — only for models.llm.backend: openai)
+# =============================================================================
+# When the language model runs off-device on an OpenAI-compatible endpoint, the
+# endpoint (models.llm.base_url) and model (models.llm.model) live in config.yml;
+# only the API key belongs here, to keep the secret out of committed config.
+# OPENAI_API_KEY is used as a fallback; if neither is set the client sends
+# "not-needed" (fine for local servers that ignore it).
+FULLOCH_LLM_API_KEY=
+# OPENAI_API_KEY=
+
 # =============================================================================
 # Container healthcheck port (optional)
 # =============================================================================

.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: Release images
+
+# Tag-triggered build: the slow CUDA + flash-attn compile happens once here and
+# is pushed to GHCR, so users `docker pull` instead of building. Two variants:
+#   - GPU (default): ghcr.io/<owner>/fulloch:<version> + :latest
+#   - CPU (slim):    ghcr.io/<owner>/fulloch:<version>-cpu + :latest-cpu + :cpu
+# Weights stay out of the images (the first-run wizard downloads them).
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:  # allow a manual build of the current ref
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-push:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - variant: gpu
+            dockerfile: Dockerfile
+            suffix: ""
+          - variant: cpu
+            dockerfile: Dockerfile.cpu
+            suffix: "-cpu"
+    steps:
+      - uses: actions/checkout@v4
+
+      # The CUDA devel base + flash-attn build is large; reclaim runner disk so
+      # the GPU build doesn't run out of space (cheap no-op for the CPU build).
+      - name: Free disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc \
+            /opt/hostedtoolcache/CodeQL
+          sudo docker image prune --all --force || true
+          df -h
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Image metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/fulloch
+          flavor: |
+            latest=false
+            suffix=${{ matrix.suffix }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest
+            # Short, suffix-free alias for the CPU image (README/run docs pull
+            # `:cpu`). suffix= overrides the global `-cpu` flavor so it lands as
+            # exactly `:cpu`, not `:cpu-cpu`; only emitted on the CPU matrix leg.
+            type=raw,value=cpu,suffix=,enable=${{ matrix.variant == 'cpu' }}
+
+      - name: Build and push (${{ matrix.variant }})
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ${{ matrix.dockerfile }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha,scope=${{ matrix.variant }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.variant }}

.gitignore

@@ -100,6 +100,7 @@ Thumbs.db
 0ld/
 dev/
 data/voices/private
+scripts/gen_kokoro_demos.py
 
 # =============================================================================
 # Keep Example Configs (negation patterns)

CONTRIBUTING.md

@@ -10,12 +10,14 @@ Thank you for your interest in contributing to Fulloch! This document provides g
    ```bash
    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-   pip install -r requirements.txt
+   pip install -r requirements.txt   # full GPU stack (tiny/CPU set: requirements-cpu.txt)
    # Install special packages (see requirements.txt for details)
    pip install --no-deps git+https://github.com/liampetti/Qwen3-TTS-streaming.git@97da215
    pip install --no-build-isolation --no-deps git+https://github.com/Dao-AILab/flash-attention.git@ef9e6a6
    pip install -e ".[dev]"  # Install dev dependencies
    ```
+   The test suite stubs the heavy GPU stack, so `pip install -r requirements-ci.txt`
+   is enough to run `pytest` (no GPU needed).
 4. Copy configuration files:
    ```bash
    cp data/config.example.yml data/config.yml

Dockerfile

@@ -4,13 +4,18 @@ FROM pytorch/pytorch:2.8.0-cuda12.8-cudnn9-devel AS builder
 ENV DEBIAN_FRONTEND=noninteractive
 ENV CMAKE_ARGS="-DGGML_CUDA=on"
 ENV FORCE_CMAKE=1
+# Cap flash-attn's parallel nvcc jobs so the build doesn't exhaust RAM on small
+# CI runners (each job needs a few GB). Override with --build-arg MAX_JOBS=N.
+ARG MAX_JOBS=4
+ENV MAX_JOBS=${MAX_JOBS}
 
 RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
 
 COPY requirements.txt /tmp/requirements.txt
 RUN pip install --no-cache-dir -r /tmp/requirements.txt && \
     pip install --no-deps git+https://github.com/liampetti/Qwen3-TTS-streaming.git@97da215 && \
-    pip install flash-attn --no-build-isolation
+    pip install flash-attn --no-build-isolation && \
+    python -m spacy download en_core_web_sm
 
 # Stage 2: Runtime (no CUDA compilers/headers)
 FROM pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime
@@ -20,7 +25,10 @@ ENV DEBIAN_FRONTEND=noninteractive
 WORKDIR /app
 
 ENV HF_HOME=/app/data/models
-ENV HF_HUB_OFFLINE=1
+# HF_HUB_OFFLINE is managed at runtime by app.py (online for the first-run
+# wizard download, offline once models are cached) — not pinned here.
+# Image variant — the wizard offers all tiers on the GPU image.
+ENV FULLOCH_VARIANT=gpu
 
 # Install runtime system dependencies
 # - gcc: needed by Triton JIT for TTS kernels
@@ -33,6 +41,7 @@ RUN apt-get update && apt-get install -y \
     libsox-dev \
     libsox-fmt-all \
     ffmpeg \
+    espeak-ng \
     libportaudio2 \
     libasound2-plugins \
     libpulse0 \
@@ -52,12 +61,21 @@ RUN useradd -m -u 1000 -s /bin/bash appuser
 USER appuser
 
 # Copy application code
-COPY --chown=appuser:appuser app.py fulloch.png ./
+COPY --chown=appuser:appuser app.py fulloch.png parloch.png ./
 COPY --chown=appuser:appuser core/ core/
 COPY --chown=appuser:appuser tools/ tools/
 COPY --chown=appuser:appuser utils/ utils/
 COPY --chown=appuser:appuser audio/ audio/
 COPY --chown=appuser:appuser server/ server/
 COPY --chown=appuser:appuser wav/ wav/
 
+# First-run seeds (copied into the empty ./data volume by core/bootstrap.py):
+# the config template the wizard fills in, and the app's own GBNF grammar (which
+# the wizard's downloader can't fetch). Weights stay OUT of the image — the
+# wizard pulls them on first run.
+COPY --chown=appuser:appuser data/config.example.yml /app/seed/config.example.yml
+COPY --chown=appuser:appuser data/models/grammars/agent.gbnf /app/seed/grammars/agent.gbnf
+
+# Bootstrap + setup-or-run is handled in app.main() (core/bootstrap.py): an empty
+# ./data boots into the setup wizard, a populated one straight to the assistant.
 CMD ["python", "app.py"]

Dockerfile.cpu

@@ -0,0 +1,65 @@
+# Fulloch — CPU image (slim "tiny + remote" variant).
+#
+# No CUDA, no flash-attn, no llama-cpp, no Qwen speech. Ships Moonshine ASR +
+# Kokoro TTS (both CPU) and the regex-only / remote-OpenAI LLM paths, so a
+# low-power / no-GPU host can run the tiny tier or offload reasoning to a remote
+# endpoint. Much smaller than the GPU image. The wizard hides GPU-only backends
+# (FULLOCH_VARIANT=cpu).
+FROM python:3.11-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+WORKDIR /app
+
+ENV HF_HOME=/app/data/models
+# HF_HUB_OFFLINE is managed at runtime by app.py (online for the first-run
+# wizard download, offline once models are cached) — not pinned here.
+# Image variant — the wizard offers only the CPU-runnable backends/tiers.
+ENV FULLOCH_VARIANT=cpu
+
+# Runtime system deps:
+# - espeak-ng: Kokoro TTS grapheme-to-phoneme
+# - libsndfile1: soundfile I/O; ffmpeg: audio decode
+# - libportaudio2: PortAudio (sounddevice); libasound2-plugins + libpulse0:
+#   ALSA->PulseAudio bridge for host audio passthrough
+# - gcc: a couple of wheels JIT/compile at runtime
+RUN apt-get update && apt-get install -y \
+    gcc \
+    ffmpeg \
+    espeak-ng \
+    libsndfile1 \
+    libportaudio2 \
+    libasound2-plugins \
+    libpulse0 \
+    procps \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Route ALSA's default device through PulseAudio (same as the GPU image).
+RUN printf 'pcm.!default { type pulse }\nctl.!default { type pulse }\n' > /etc/asound.conf
+
+# CPU PyTorch from the CPU wheel index (keeps the CUDA build out), then the
+# CPU dependency set.
+RUN pip install --no-cache-dir torch==2.8.0 torchaudio==2.8.0 \
+        --index-url https://download.pytorch.org/whl/cpu
+COPY requirements-cpu.txt /tmp/requirements-cpu.txt
+RUN pip install --no-cache-dir -r /tmp/requirements-cpu.txt
+RUN python -m spacy download en_core_web_sm
+
+# Non-root user
+RUN useradd -m -u 1000 -s /bin/bash appuser
+USER appuser
+
+# Application code
+COPY --chown=appuser:appuser app.py fulloch.png parloch.png ./
+COPY --chown=appuser:appuser core/ core/
+COPY --chown=appuser:appuser tools/ tools/
+COPY --chown=appuser:appuser utils/ utils/
+COPY --chown=appuser:appuser audio/ audio/
+COPY --chown=appuser:appuser server/ server/
+COPY --chown=appuser:appuser wav/ wav/
+
+# First-run seeds (copied into the empty ./data volume by core/bootstrap.py).
+COPY --chown=appuser:appuser data/config.example.yml /app/seed/config.example.yml
+COPY --chown=appuser:appuser data/models/grammars/agent.gbnf /app/seed/grammars/agent.gbnf
+
+CMD ["python", "app.py"]