added ZstdMiddleware to ebook_search

sunshine is a cool idea but has been causing annoying ui glitches and started preventing the display manning for starting
Its a cool idea in theory but not useful enough for me to want to debug

.github/workflows/build_systems.yml

@@ -23,6 +23,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Build default package
-        run: "nixos-rebuild build --flake ./#${{ matrix.system }}"
+        run: "nixos-rebuild build --accept-flake-config --flake ./#${{ matrix.system }}"
       - name: copy to nix-cache
         run: nix copy --accept-flake-config --to unix:///host-nix/var/nix/daemon-socket/socket .#nixosConfigurations.${{ matrix.system }}.config.system.build.toplevel

.github/workflows/fix_eval_warnings.yml

@@ -1,30 +0,0 @@
-name: fix_eval_warnings
-on:
-  workflow_run:
-    workflows: ["build_systems"]
-    types: [completed]
-
-jobs:
-  check-warnings:
-    if: >-
-      github.event.workflow_run.conclusion != 'cancelled' &&
-      github.event.workflow_run.head_branch == 'main' &&
-      (github.event.workflow_run.event == 'push' || github.event.workflow_run.event == 'schedule')
-    runs-on: self-hosted
-    permissions:
-      contents: write
-      pull-requests: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Fix eval warnings
-        env:
-          GH_TOKEN: ${{ secrets.GH_TOKEN_FOR_UPDATES }}
-        run: >-
-          nix develop .#devShells.x86_64-linux.default -c
-          python -m python.eval_warnings.main
-          --run-id "${{ github.event.workflow_run.id }}"
-          --repo "${{ github.repository }}"
-          --ollama-url "${{ secrets.OLLAMA_URL }}"
-          --run-url "${{ github.event.workflow_run.html_url }}"

.github/workflows/merge_flake_lock_update.yml

@@ -6,24 +6,18 @@ on:
 
 jobs:
   merge:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
 
     permissions:
       contents: write
       pull-requests: write
 
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
       - name: merge_flake_lock_update
-        run: |
-          pr_number=$(gh pr list --state open --author RichieCahill --label flake_lock_update --json number --jq '.[0].number')
-          echo "pr_number=$pr_number" >> $GITHUB_ENV
-          if [ -n "$pr_number" ]; then
-            gh pr merge "$pr_number" --rebase
-          else
-            echo "No open PR found with label flake_lock_update"
-          fi
+        run: >-
+          nix develop .#devShells.x86_64-linux.default -c
+          python -m python.gitea_flake_lock merge
+          --repo "${{ github.repository }}"
         env:
-          GITHUB_TOKEN: ${{ secrets.GH_TOKEN_FOR_UPDATES }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_URL: https://gitea.tmmworkshop.com

.github/workflows/pytest.yml

@@ -1,13 +1,13 @@
 name: pytest
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - main
   pull_request:
     branches:
       - main
-  merge_group:
 
 jobs:
   pytest:

.github/workflows/update-flake-lock.yml

@@ -6,18 +6,21 @@ on:
 
 jobs:
   lockfile:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@main
       - name: Update flake.lock
-        uses: DeterminateSystems/update-flake-lock@main
-        with:
-          token: ${{ secrets.GH_TOKEN_FOR_UPDATES }}
-          pr-title: "Update flake.lock"
-          pr-labels: |
-            dependencies
-            automated
-            flake_lock_update
+        run: nix flake update
+      - name: Create or update flake.lock PR
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_URL: https://gitea.tmmworkshop.com
+        run: >-
+          nix develop .#devShells.x86_64-linux.default -c
+          python -m python.gitea_flake_lock update
+          --repo "${{ github.repository }}"

.gitignore

@@ -171,4 +171,5 @@ frontend/dist/
 frontend/node_modules/
 
 # data from testing llms
-data/*
+data/*
+.ebook_search_bm25

common/global/default.nix

@@ -23,7 +23,10 @@
   boot = {
     tmp.useTmpfs = true;
     kernelPackages = lib.mkDefault pkgs.linuxPackages_6_12;
-    zfs.package = lib.mkDefault pkgs.zfs_2_4;
+    zfs = {
+      package = lib.mkDefault pkgs.zfs_2_4;
+      forceImportRoot = lib.mkDefault false;
+    };
   };
 
   hardware.enableRedistributableFirmware = true;
@@ -37,10 +40,17 @@
 
   nixpkgs = {
     overlays = builtins.attrValues outputs.overlays;
-    config.allowUnfree = true;
+    config = {
+      allowUnfree = true;
+      permittedInsecurePackages = [
+        "openssl-1.1.1w" # This is for discord-canary
+      ];
+    };
   };
 
   services = {
+    dbus.implementation = "dbus";
+
     # firmware update
     fwupd.enable = true;
 

common/optional/monitoring-agent.nix

@@ -0,0 +1,256 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  monitoringInterface = "ztwfunumly";
+  nodeTextfileDir = "/var/lib/prometheus-node-exporter-textfile";
+
+  mkProcessNameTemplate =
+    perPid: template: if perPid then "${template}:{{.PID}}:{{.StartTime}}" else template;
+
+  mkProcessMatchers = perPid: [
+    {
+      name = mkProcessNameTemplate perPid "{{.Username}}:{{.Matches.Module}}";
+      cmdline = [ "^/nix/store[^ ]*/bin/python[^ ]* -m (?P<Module>[^ ]+)" ];
+    }
+    {
+      name = mkProcessNameTemplate perPid "{{.Username}}:{{.Matches.Wrapped}}";
+      cmdline = [
+        "^/nix/store[^ ]*/bin/python[^ ]* /nix/store[^ ]*/bin/\\.?(?P<Wrapped>[^ /]+?)(?:-wrapped)?(?:\\s|$)"
+      ];
+    }
+    {
+      name = mkProcessNameTemplate perPid "{{.Username}}:{{.Matches.Wrapped}}";
+      cmdline = [
+        "^/nix/store[^ ]*/bin/node /nix/store[^ ]*-(?P<Wrapped>[A-Za-z0-9._+-]+)-[0-9][^ /]*/"
+      ];
+    }
+    {
+      name = mkProcessNameTemplate perPid "{{.Username}}:{{.Matches.Wrapped}}";
+      cmdline = [ "^/nix/store[^ ]*/(?:bin/|lib/[^ ]*/)?\\.?(?P<Wrapped>[^ /]+?)(?:-wrapped)?(?:\\s|$)" ];
+    }
+    {
+      name = mkProcessNameTemplate perPid "{{.Username}}:{{.ExeBase}}";
+      cmdline = [ ".+" ];
+    }
+  ];
+
+  perPidConfig = pkgs.writeText "process-exporter-per-pid.yaml" (
+    builtins.toJSON {
+      process_names = mkProcessMatchers true;
+    }
+  );
+
+  zpoolLatencyScript = pkgs.writeShellScript "zpool-latency-exporter" ''
+        set -euo pipefail
+
+        out_dir=${lib.escapeShellArg nodeTextfileDir}
+        host=${lib.escapeShellArg config.networking.hostName}
+        tmp_file="$(mktemp "$out_dir/zpool.prom.XXXXXX")"
+        trap 'rm -f "$tmp_file"' EXIT
+
+        pools="$(zpool list -H -o name | paste -sd, -)"
+
+        cat >"$tmp_file" <<'EOF'
+    # HELP zpool_iostat_total_wait_read_ns Average total read wait time reported by zpool iostat.
+    # TYPE zpool_iostat_total_wait_read_ns gauge
+    # HELP zpool_iostat_total_wait_write_ns Average total write wait time reported by zpool iostat.
+    # TYPE zpool_iostat_total_wait_write_ns gauge
+    # HELP zpool_iostat_disk_wait_read_ns Average disk read wait time reported by zpool iostat.
+    # TYPE zpool_iostat_disk_wait_read_ns gauge
+    # HELP zpool_iostat_disk_wait_write_ns Average disk write wait time reported by zpool iostat.
+    # TYPE zpool_iostat_disk_wait_write_ns gauge
+    # HELP zpool_iostat_syncq_wait_read_ns Average synchronous queue read wait time reported by zpool iostat.
+    # TYPE zpool_iostat_syncq_wait_read_ns gauge
+    # HELP zpool_iostat_syncq_wait_write_ns Average synchronous queue write wait time reported by zpool iostat.
+    # TYPE zpool_iostat_syncq_wait_write_ns gauge
+    # HELP zpool_iostat_asyncq_wait_read_ns Average asynchronous queue read wait time reported by zpool iostat.
+    # TYPE zpool_iostat_asyncq_wait_read_ns gauge
+    # HELP zpool_iostat_asyncq_wait_write_ns Average asynchronous queue write wait time reported by zpool iostat.
+    # TYPE zpool_iostat_asyncq_wait_write_ns gauge
+    EOF
+
+        zpool iostat -Hplvy -y 1 1 | awk -F '\t' -v host="$host" -v pools="$pools" '
+          function esc(str, out) {
+            out = str
+            gsub(/\\/, "\\\\", out)
+            gsub(/"/, "\\\"", out)
+            return out
+          }
+
+          function emit(metric, pool, vdev, value) {
+            if (value == "" || value == "-") {
+              return
+            }
+
+            printf "%s{host=\"%s\",pool=\"%s\",vdev=\"%s\"} %s\n",
+              metric,
+              esc(host),
+              esc(pool),
+              esc(vdev),
+              value
+          }
+
+          BEGIN {
+            split(pools, pool_names, ",")
+            for (idx in pool_names) {
+              if (pool_names[idx] != "") {
+                known_pools[pool_names[idx]] = 1
+              }
+            }
+          }
+
+          NF == 0 {
+            next
+          }
+
+          {
+            row_name = $1
+
+            if (row_name in known_pools) {
+              current_pool = row_name
+              current_vdev = "_pool"
+            } else if (current_pool == "") {
+              next
+            } else {
+              current_vdev = row_name
+            }
+
+            emit("zpool_iostat_total_wait_read_ns", current_pool, current_vdev, $8)
+            emit("zpool_iostat_total_wait_write_ns", current_pool, current_vdev, $9)
+            emit("zpool_iostat_disk_wait_read_ns", current_pool, current_vdev, $10)
+            emit("zpool_iostat_disk_wait_write_ns", current_pool, current_vdev, $11)
+            emit("zpool_iostat_syncq_wait_read_ns", current_pool, current_vdev, $12)
+            emit("zpool_iostat_syncq_wait_write_ns", current_pool, current_vdev, $13)
+            emit("zpool_iostat_asyncq_wait_read_ns", current_pool, current_vdev, $14)
+            emit("zpool_iostat_asyncq_wait_write_ns", current_pool, current_vdev, $15)
+          }
+        ' >>"$tmp_file"
+
+        mv "$tmp_file" "$out_dir/zpool.prom"
+        trap - EXIT
+  '';
+in
+{
+  networking.firewall.interfaces.${monitoringInterface}.allowedTCPPorts = [
+    9100
+    9134
+    9256
+    9257
+    9633
+  ];
+
+  services.prometheus.exporters = {
+    node = {
+      enable = true;
+      enabledCollectors = [
+        "pressure"
+        "processes"
+        "systemd"
+      ];
+      extraFlags = [ "--collector.textfile.directory=${nodeTextfileDir}" ];
+    };
+
+    process = {
+      enable = true;
+      user = "root";
+      group = "root";
+      settings.process_names = mkProcessMatchers false;
+      extraFlags = [
+        "-gather-smaps=false"
+        "-remove-empty-groups=true"
+        "-threads=false"
+      ];
+    };
+
+    smartctl.enable = true;
+    zfs.enable = true;
+  };
+
+  programs.atop = {
+    enable = true;
+    atopService.enable = true;
+    atopRotateTimer.enable = true;
+    atopacctService.enable = true;
+    settings.interval = 30;
+  };
+
+  systemd = {
+    services = {
+      prometheus-process-pid-exporter = {
+        description = "Prometheus process exporter with per-PID naming";
+        wantedBy = [ "multi-user.target" ];
+        after = [ "network.target" ];
+        serviceConfig = {
+          ExecStart = ''
+            ${pkgs.prometheus-process-exporter}/bin/process-exporter \
+              --web.listen-address 0.0.0.0:9257 \
+              --config.path ${perPidConfig} \
+              -children=false \
+              -gather-smaps=false \
+              -remove-empty-groups=true \
+              -threads=false
+          '';
+          User = "root";
+          Group = "root";
+          Restart = "always";
+          WorkingDirectory = "/tmp";
+          CapabilityBoundingSet = [ "" ];
+          DeviceAllow = [ "" ];
+          LockPersonality = true;
+          MemoryDenyWriteExecute = true;
+          NoNewPrivileges = true;
+          PrivateDevices = true;
+          PrivateTmp = true;
+          ProtectClock = true;
+          ProtectControlGroups = true;
+          ProtectHome = true;
+          ProtectHostname = true;
+          ProtectKernelLogs = true;
+          ProtectKernelModules = true;
+          ProtectKernelTunables = true;
+          ProtectSystem = "strict";
+          RemoveIPC = true;
+          RestrictAddressFamilies = [
+            "AF_INET"
+            "AF_INET6"
+          ];
+          RestrictNamespaces = true;
+          RestrictRealtime = true;
+          RestrictSUIDSGID = true;
+          SystemCallArchitectures = "native";
+          UMask = "0077";
+        };
+      };
+
+      zpool-latency-exporter = {
+        description = "Exports ZFS latency metrics for node_exporter textfile collection";
+        after = [ "zfs-import.target" ];
+        requires = [ "zfs-import.target" ];
+        path = [
+          config.boot.zfs.package
+          pkgs.coreutils
+          pkgs.gawk
+        ];
+        serviceConfig = {
+          Type = "oneshot";
+          ExecStart = zpoolLatencyScript;
+        };
+      };
+    };
+
+    timers.zpool-latency-exporter = {
+      wantedBy = [ "timers.target" ];
+      timerConfig = {
+        OnBootSec = "2m";
+        OnUnitActiveSec = "60s";
+        Unit = "zpool-latency-exporter.service";
+      };
+    };
+
+    tmpfiles.rules = [ "d ${nodeTextfileDir} 0755 root root - -" ];
+  };
+}

common/optional/update.nix

@@ -4,7 +4,7 @@
     flags = [ "--accept-flake-config" ];
     randomizedDelaySec = "1h";
     persistent = true;
-    flake = "github:RichieCahill/dotfiles";
+    flake = "git+https://gitea.tmmworkshop.com/richie/dotfiles?ref=main";
     allowReboot = true;
     dates = "Sat *-*-* 06:00:00";
   };

docs/zfs_failed_root_import_recovry.md

@@ -0,0 +1,76 @@
+# ZFS failed root import recovery
+
+## Fast path
+
+If the machine fails to boot because ZFS refuses to import `root_pool`:
+
+### GRUB
+
+1. At the bootloader menu, select the normal NixOS entry.
+2. Press `e`.
+3. Find the line that starts with `linux`.
+4. Append this to the end of that line:
+
+```text
+zfs_force=1
+```
+
+5. Boot once with `Ctrl+x` or `F10`.
+
+### systemd-boot
+
+1. At the bootloader menu, highlight the normal NixOS entry.
+2. Press `e`.
+3. Append this to the end of the options line:
+
+```text
+zfs_force=1
+```
+
+4. Press `Enter` to boot once.
+
+## After boot
+
+Run:
+
+```bash
+sudo zpool status
+sudo zpool import
+journalctl -b | rg "ZFS|zfs|import|root_pool"
+```
+
+## Expected result
+
+`sudo zpool status` should show `root_pool` as `ONLINE`.
+
+## Reboot test
+
+Run:
+
+```bash
+sudo reboot
+```
+
+Do not add `zfs_force=1` the second time.
+
+## If it still fails
+
+Boot once more with:
+
+```text
+zfs_force=1
+```
+
+Then run:
+
+```bash
+sudo zpool status -v
+sudo zpool history | tail -n 50
+journalctl -b | rg "ZFS|zfs|import|root_pool"
+```
+
+## Notes
+
+- Root pool name is `root_pool`.
+- This is a one-time recovery path after disk moves, controller changes, dirty exports, or interrupted imports.
+- Some hosts also need the LUKS unlock USB key inserted before boot.

flake.lock

@@ -8,11 +8,11 @@
       },
       "locked": {
         "dir": "pkgs/firefox-addons",
-        "lastModified": 1776398575,
-        "narHash": "sha256-WArU6WOdWxzbzGqYk4w1Mucg+bw/SCl6MoSp+/cZMio=",
+        "lastModified": 1781150628,
+        "narHash": "sha256-b4mp8l3qWuSCyYYo9HSngDtcB3PpecYiOXjULrjwwlw=",
         "owner": "rycee",
         "repo": "nur-expressions",
-        "rev": "05815686caf4e3678f5aeb5fd36e567886ab0d30",
+        "rev": "753319310f4673a2dabbfab87482187b40bf9bac",
         "type": "gitlab"
       },
       "original": {
@@ -29,11 +29,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1776454077,
-        "narHash": "sha256-7zSUFWsU0+jlD7WB3YAxQ84Z/iJurA5hKPm8EfEyGJk=",
+        "lastModified": 1781189114,
+        "narHash": "sha256-5inaamLgUMWy+MOBE9ChF9QAF1o/74LFuHkI0W/9rqc=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "565e5349208fe7d0831ef959103c9bafbeac0681",
+        "rev": "486595d2cf49cfcd649b58a284fa11ac0e34da22",
         "type": "github"
       },
       "original": {
@@ -43,12 +43,15 @@
       }
     },
     "nixos-hardware": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      },
       "locked": {
-        "lastModified": 1775490113,
-        "narHash": "sha256-2ZBhDNZZwYkRmefK5XLOusCJHnoeKkoN95hoSGgMxWM=",
+        "lastModified": 1781168557,
+        "narHash": "sha256-LOnLQ2tpYF9gqIDDr3+j3DbpJJr/QCH6zPRT2GzEUOE=",
         "owner": "nixos",
         "repo": "nixos-hardware",
-        "rev": "c775c2772ba56e906cbeb4e0b2db19079ef11ff7",
+        "rev": "6358ff76821101c178e3ab4919a62799bfe3652e",
         "type": "github"
       },
       "original": {
@@ -60,27 +63,24 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1776169885,
-        "narHash": "sha256-l/iNYDZ4bGOAFQY2q8y5OAfBBtrDAaPuRQqWaFHVRXM=",
-        "owner": "nixos",
-        "repo": "nixpkgs",
-        "rev": "4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9",
-        "type": "github"
+        "lastModified": 1767892417,
+        "narHash": "sha256-8bW3q88CEg2u4hSP66Vf4lpbLonHz7hqDNBMcCY7E9U=",
+        "rev": "3497aa5c9457a9d88d71fa93a4a8368816fbeeba",
+        "type": "tarball",
+        "url": "https://releases.nixos.org/nixos/unstable/nixos-26.05pre924538.3497aa5c9457/nixexprs.tar.xz"
       },
       "original": {
-        "owner": "nixos",
-        "ref": "nixos-unstable",
-        "repo": "nixpkgs",
-        "type": "github"
+        "type": "tarball",
+        "url": "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz"
       }
     },
     "nixpkgs-master": {
       "locked": {
-        "lastModified": 1776469842,
-        "narHash": "sha256-sqzM6PKMQoGk8Sl+uv2sbP1qiS2SPQhA2yn5zgZINMc=",
+        "lastModified": 1781229721,
+        "narHash": "sha256-ORvqDbb/LYxiJljGIejapjkc/kJbVote2N1WSb9W45I=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "025c852a89be820b3117f604c8ace42e9b4caa08",
+        "rev": "173d0ad7a974f8543a9ab01d2271b2e290341b33",
         "type": "github"
       },
       "original": {
@@ -106,12 +106,28 @@
         "type": "github"
       }
     },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1781074563,
+        "narHash": "sha256-md8WlXOlfnIeHeOScMTTHFyf2d6iaTwPl2apR5EQ3P4=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "9ae611a455b90cf061d8f332b977e387bda8e1ca",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "firefox-addons": "firefox-addons",
         "home-manager": "home-manager",
         "nixos-hardware": "nixos-hardware",
-        "nixpkgs": "nixpkgs",
+        "nixpkgs": "nixpkgs_2",
         "nixpkgs-master": "nixpkgs-master",
         "nixpkgs-stable": "nixpkgs-stable",
         "sops-nix": "sops-nix",
@@ -125,11 +141,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1776119890,
-        "narHash": "sha256-Zm6bxLNnEOYuS/SzrAGsYuXSwk3cbkRQZY0fJnk8a5M=",
+        "lastModified": 1780547341,
+        "narHash": "sha256-Gq8KNx5A7hBB3uGJaj6eQfLDIz5YdLu92gqBcvHvoUo=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "d4971dd58c6627bfee52a1ad4237637c0a2fb0cd",
+        "rev": "9ed65852b6257fbeae4355bc24ecfea307ca759a",
         "type": "github"
       },
       "original": {

frontend/.gitignore

@@ -1,24 +0,0 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
-
-node_modules
-dist
-dist-ssr
-*.local
-
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
-.idea
-.DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?

overlays/default.nix

@@ -17,16 +17,41 @@
 
   python-env = final: _prev: {
     my_python = final.python314.withPackages (
-      ps: with ps; [
+      ps:
+      let
+        bm25s = ps.buildPythonPackage rec {
+          pname = "bm25s";
+          version = "0.3.9";
+          pyproject = true;
+
+          src = final.fetchPypi {
+            inherit pname version;
+            hash = "sha256-iVxnnZUrfeg1XttfPhpiCh4vKU0dQrkZvwghzOLi9Zc=";
+          };
+
+          build-system = [ ps.setuptools ];
+          dependencies = with ps; [
+            numpy
+            scipy
+          ];
+
+          pythonImportsCheck = [ "bm25s" ];
+        };
+      in
+      with ps;
+      [
         alembic
         apprise
         apscheduler
+        beautifulsoup4
+        ebooklib
         fastapi
         fastapi-cli
-        faster-whisper
         httpx
         mypy
+        numpy
         orjson
+        pgvector
         polars
         psycopg
         pydantic
@@ -40,6 +65,7 @@
         scalene
         sqlalchemy
         sqlalchemy
+        bm25s
         tenacity
         textual
         tiktoken

python/alembic/richie/versions/2026_06_03-adding_audiobook_libreary_metadata_d7864d1ffc17.py

@@ -0,0 +1,93 @@
+"""adding audiobook libreary metadata.
+
+Revision ID: d7864d1ffc17
+Revises: c8a794340928
+Create Date: 2026-06-03 20:24:09.200837
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+
+from python.orm import RichieBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "d7864d1ffc17"
+down_revision: str | None = "c8a794340928"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = RichieBase.schema_name
+
+
+def upgrade() -> None:
+    """Upgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "audiobook_author",
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_audiobook_author")),
+        sa.UniqueConstraint("name", name=op.f("uq_audiobook_author_name")),
+        schema=schema,
+    )
+    op.create_table(
+        "audiobook_series",
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("author_id", sa.Integer(), nullable=False),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["author_id"],
+            [f"{schema}.audiobook_author.id"],
+            name=op.f("fk_audiobook_series_author_id_audiobook_author"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_audiobook_series")),
+        sa.UniqueConstraint("author_id", "name", name=op.f("uq_audiobook_series_author_id")),
+        schema=schema,
+    )
+    op.create_table(
+        "audiobook",
+        sa.Column("title", sa.String(), nullable=False),
+        sa.Column("author_id", sa.Integer(), nullable=False),
+        sa.Column("series_id", sa.Integer(), nullable=True),
+        sa.Column("series_index", sa.Integer(), nullable=False),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["author_id"],
+            [f"{schema}.audiobook_author.id"],
+            name=op.f("fk_audiobook_author_id_audiobook_author"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["series_id"],
+            [f"{schema}.audiobook_series.id"],
+            name=op.f("fk_audiobook_series_id_audiobook_series"),
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_audiobook")),
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("audiobook", schema=schema)
+    op.drop_table("audiobook_series", schema=schema)
+    op.drop_table("audiobook_author", schema=schema)
+    # ### end Alembic commands ###

python/alembic/richie/versions/2026_06_10-add_ebook_search_tables_2db132cace1a.py

@@ -0,0 +1,200 @@
+"""add ebook search tables.
+
+Revision ID: 2db132cace1a
+Revises: b3c60cc5beb5
+Create Date: 2026-06-10 22:10:54.379159
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pgvector
+import sqlalchemy as sa
+from alembic import op
+
+from python.orm import RichieBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "2db132cace1a"
+down_revision: str | None = "b3c60cc5beb5"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = RichieBase.schema_name
+
+
+def upgrade() -> None:
+    """Upgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "ebook_embedding_model",
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("dimension", sa.Integer(), nullable=False),
+        sa.Column("is_default", sa.Boolean(), nullable=False),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_ebook_embedding_model")),
+        sa.UniqueConstraint("name", name=op.f("uq_ebook_embedding_model_name")),
+        schema=schema,
+    )
+    op.create_table(
+        "ebook_source",
+        sa.Column("title", sa.String(), nullable=False),
+        sa.Column("author", sa.String(), nullable=True),
+        sa.Column("language", sa.String(), nullable=True),
+        sa.Column("publisher", sa.String(), nullable=True),
+        sa.Column("identifier", sa.String(), nullable=True),
+        sa.Column("file_path", sa.String(), nullable=False),
+        sa.Column("file_sha256", sa.String(length=64), nullable=False),
+        sa.Column("file_mtime", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("file_size", sa.BigInteger(), nullable=False),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_ebook_source")),
+        sa.UniqueConstraint("file_path", name=op.f("uq_ebook_source_file_path")),
+        sa.UniqueConstraint("file_sha256", name=op.f("uq_ebook_source_file_sha256")),
+        schema=schema,
+    )
+    op.create_table(
+        "ebook_chapter",
+        sa.Column("source_id", sa.Integer(), nullable=False),
+        sa.Column("spine_index", sa.Integer(), nullable=False),
+        sa.Column("title", sa.String(), nullable=True),
+        sa.Column("href", sa.String(), nullable=True),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["source_id"],
+            [f"{schema}.ebook_source.id"],
+            name=op.f("fk_ebook_chapter_source_id_ebook_source"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_ebook_chapter")),
+        sa.UniqueConstraint("source_id", "spine_index", name=op.f("uq_ebook_chapter_source_id")),
+        schema=schema,
+    )
+    op.create_table(
+        "ebook_chunk",
+        sa.Column("source_id", sa.Integer(), nullable=False),
+        sa.Column("chapter_id", sa.Integer(), nullable=True),
+        sa.Column("chunk_index", sa.Integer(), nullable=False),
+        sa.Column("text", sa.String(), nullable=False),
+        sa.Column("token_start", sa.Integer(), nullable=False),
+        sa.Column("token_count", sa.Integer(), nullable=False),
+        sa.Column("page_label", sa.String(), nullable=True),
+        sa.Column("content_sha256", sa.String(length=64), nullable=False),
+        sa.Column("search_text", sa.String(), nullable=False),
+        sa.Column("id", sa.BigInteger(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["chapter_id"],
+            [f"{schema}.ebook_chapter.id"],
+            name=op.f("fk_ebook_chunk_chapter_id_ebook_chapter"),
+            ondelete="SET NULL",
+        ),
+        sa.ForeignKeyConstraint(
+            ["source_id"],
+            [f"{schema}.ebook_source.id"],
+            name=op.f("fk_ebook_chunk_source_id_ebook_source"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_ebook_chunk")),
+        sa.UniqueConstraint("source_id", "chunk_index", name="uq_ebook_chunk_source_id_chunk_index"),
+        sa.UniqueConstraint("source_id", "content_sha256", name="uq_ebook_chunk_source_id_content_sha256"),
+        schema=schema,
+    )
+    op.create_table(
+        "ebook_chunk_embedding_1024",
+        sa.Column("chunk_id", sa.BigInteger(), nullable=False),
+        sa.Column("model_id", sa.Integer(), nullable=False),
+        sa.Column("embedding", pgvector.sqlalchemy.vector.VECTOR(dim=1024), nullable=False),
+        sa.Column("id", sa.BigInteger(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["chunk_id"],
+            [f"{schema}.ebook_chunk.id"],
+            name=op.f("fk_ebook_chunk_embedding_1024_chunk_id_ebook_chunk"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["model_id"],
+            [f"{schema}.ebook_embedding_model.id"],
+            name=op.f("fk_ebook_chunk_embedding_1024_model_id_ebook_embedding_model"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_ebook_chunk_embedding_1024")),
+        sa.UniqueConstraint("chunk_id", "model_id", name=op.f("uq_ebook_chunk_embedding_1024_chunk_id")),
+        schema=schema,
+    )
+    op.create_table(
+        "ebook_chunk_embedding_2560",
+        sa.Column("chunk_id", sa.BigInteger(), nullable=False),
+        sa.Column("model_id", sa.Integer(), nullable=False),
+        sa.Column("embedding", pgvector.sqlalchemy.vector.VECTOR(dim=2560), nullable=False),
+        sa.Column("id", sa.BigInteger(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["chunk_id"],
+            [f"{schema}.ebook_chunk.id"],
+            name=op.f("fk_ebook_chunk_embedding_2560_chunk_id_ebook_chunk"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["model_id"],
+            [f"{schema}.ebook_embedding_model.id"],
+            name=op.f("fk_ebook_chunk_embedding_2560_model_id_ebook_embedding_model"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_ebook_chunk_embedding_2560")),
+        sa.UniqueConstraint("chunk_id", "model_id", name=op.f("uq_ebook_chunk_embedding_2560_chunk_id")),
+        schema=schema,
+    )
+    op.create_table(
+        "ebook_chunk_embedding_4096",
+        sa.Column("chunk_id", sa.BigInteger(), nullable=False),
+        sa.Column("model_id", sa.Integer(), nullable=False),
+        sa.Column("embedding", pgvector.sqlalchemy.vector.VECTOR(dim=4096), nullable=False),
+        sa.Column("id", sa.BigInteger(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["chunk_id"],
+            [f"{schema}.ebook_chunk.id"],
+            name=op.f("fk_ebook_chunk_embedding_4096_chunk_id_ebook_chunk"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["model_id"],
+            [f"{schema}.ebook_embedding_model.id"],
+            name=op.f("fk_ebook_chunk_embedding_4096_model_id_ebook_embedding_model"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_ebook_chunk_embedding_4096")),
+        sa.UniqueConstraint("chunk_id", "model_id", name=op.f("uq_ebook_chunk_embedding_4096_chunk_id")),
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("ebook_chunk_embedding_4096", schema=schema)
+    op.drop_table("ebook_chunk_embedding_2560", schema=schema)
+    op.drop_table("ebook_chunk_embedding_1024", schema=schema)
+    op.drop_table("ebook_chunk", schema=schema)
+    op.drop_table("ebook_chapter", schema=schema)
+    op.drop_table("ebook_source", schema=schema)
+    op.drop_table("ebook_embedding_model", schema=schema)
+    # ### end Alembic commands ###

python/alembic/richie/versions/2026_06_10-updated_series_index_to_float_and_added__b3c60cc5beb5.py

@@ -0,0 +1,63 @@
+"""updated series_index to float and added UniqueConstraint to audiobook and audiobook_author.
+
+Revision ID: b3c60cc5beb5
+Revises: d7864d1ffc17
+Create Date: 2026-06-10 20:02:43.073725
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+
+from python.orm import RichieBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "b3c60cc5beb5"
+down_revision: str | None = "d7864d1ffc17"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = RichieBase.schema_name
+
+
+def upgrade() -> None:
+    """Upgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column(
+        "audiobook",
+        "series_index",
+        existing_type=sa.INTEGER(),
+        type_=sa.Float(),
+        existing_nullable=False,
+        schema=schema,
+    )
+    op.create_unique_constraint(
+        op.f("uq_audiobook_author_id"),
+        "audiobook",
+        ["author_id", "series_id", "title"],
+        schema=schema,
+        postgresql_nulls_not_distinct=True,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_constraint(op.f("uq_audiobook_author_id"), "audiobook", schema=schema, type_="unique")
+    op.alter_column(
+        "audiobook",
+        "series_index",
+        existing_type=sa.Float(),
+        type_=sa.INTEGER(),
+        existing_nullable=False,
+        schema=schema,
+    )
+    # ### end Alembic commands ###

python/api/main.py

@@ -9,9 +9,9 @@ import typer
 import uvicorn
 from fastapi import FastAPI
 
-from python.api.middleware import ZstdMiddleware
 from python.api.routers import contact_router, views_router
 from python.common import configure_logger
+from python.fastapi_tools import ZstdMiddleware
 from python.orm.common import get_postgres_engine
 
 logger = logging.getLogger(__name__)

python/api/routers/contact.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.orm import selectinload
 
-from python.api.dependencies import DbSession
+from python.fastapi_tools.db import DbSession
 from python.orm.richie.contact import Contact, ContactRelationship, Need, RelationshipType
 
 TEMPLATES_DIR = Path(__file__).parent.parent / "templates"

python/api/routers/views.py

@@ -9,7 +9,7 @@ from fastapi.templating import Jinja2Templates
 from sqlalchemy import select
 from sqlalchemy.orm import Session, selectinload
 
-from python.api.dependencies import DbSession
+from python.fastapi_tools.db import DbSession
 from python.orm.richie.contact import Contact, ContactRelationship, Need, RelationshipType
 
 TEMPLATES_DIR = Path(__file__).parent.parent / "templates"

python/ebook_search/__init__.py

@@ -0,0 +1 @@
+"""EPUB search package."""

python/ebook_search/answer.py

@@ -0,0 +1,57 @@
+"""Grounded answer generation."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from python.ebook_search.llm_interface import request_chat_completion
+
+if TYPE_CHECKING:
+    from python.ebook_search.config import EbookSearchConfig
+    from python.ebook_search.search import SearchResult
+
+logger = logging.getLogger(__name__)
+
+
+def answer_query(query: str, results: list[SearchResult], config: EbookSearchConfig) -> str:
+    """Answer a question using only retrieved chunks."""
+    if not config.answer_enabled:
+        logger.info("ebook_answer_skipped_disabled")
+        return "Answer generation is disabled. Source chunks are shown below."
+
+    if not results:
+        logger.info("ebook_answer_skipped_no_results")
+        return "No relevant sources were found."
+
+    logger.info(
+        "ebook_answer_request_start base_url=%s model=%s sources=%s query_length=%s",
+        config.vllm_base_url,
+        config.chat_model,
+        len(results),
+        len(query),
+    )
+    context = "\n\n".join(
+        f"[{index}] {result.source_title}{' - ' + result.chapter_title if result.chapter_title else ''}\n{result.text}"
+        for index, result in enumerate(results, start=1)
+    )
+    content = request_chat_completion(
+        config,
+        [
+            {
+                "role": "system",
+                "content": (
+                    "Answer only from the provided context. Cite sources with bracketed numbers like [1]. "
+                    "If the context is insufficient, say so."
+                ),
+            },
+            {"role": "user", "content": f"Question:\n{query}\n\nContext:\n{context}"},
+        ],
+    )
+
+    logger.info(
+        "ebook_answer_request_complete model=%s answer_length=%s",
+        config.chat_model,
+        len(content),
+    )
+    return content or "The model returned an empty answer."

python/ebook_search/api/__init__.py

@@ -0,0 +1 @@
+"""Web and external API adapters for EPUB search."""

python/ebook_search/api/bm25_tasks.py

@@ -0,0 +1,60 @@
+"""Background BM25 refresh tasks for the web app."""
+
+from __future__ import annotations
+
+import logging
+from threading import Timer
+from typing import TYPE_CHECKING
+
+from sqlalchemy.orm import Session
+
+from python.ebook_search.bm25_corpus import load_bm25_corpus, refresh_bm25_corpus
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sqlalchemy.engine import Engine
+
+    from python.ebook_search.config import EbookSearchConfig
+
+logger = logging.getLogger(__name__)
+
+
+def schedule_bm25_refresh(app: FastAPI) -> None:
+    """Schedule a delayed BM25 corpus refresh, replacing any pending refresh."""
+    existing_timer = getattr(app.state, "bm25_refresh_timer", None)
+    if existing_timer is not None:
+        existing_timer.cancel()
+
+    timer = Timer(app.state.config.bm25_refresh_delay_seconds, refresh_bm25_for_app, args=(app,))
+    timer.daemon = True
+    timer.start()
+    app.state.bm25_refresh_timer = timer
+    logger.info(
+        "ebook_bm25_refresh_scheduled delay_seconds=%s",
+        app.state.config.bm25_refresh_delay_seconds,
+    )
+
+
+def cancel_bm25_refresh(app: FastAPI) -> None:
+    """Cancel any pending BM25 corpus refresh."""
+    existing_timer = getattr(app.state, "bm25_refresh_timer", None)
+    if existing_timer is not None:
+        existing_timer.cancel()
+        app.state.bm25_refresh_timer = None
+        logger.info("ebook_bm25_refresh_cancelled")
+
+
+def refresh_bm25_for_app(app: FastAPI) -> None:
+    """Refresh the BM25 corpus using the app engine and config."""
+    try:
+        refresh_bm25_for_engine(app.state.engine, app.state.config)
+    except Exception:
+        logger.exception("ebook_bm25_refresh_failed")
+
+
+def refresh_bm25_for_engine(engine: Engine, config: EbookSearchConfig) -> None:
+    """Refresh the BM25 corpus using a SQLAlchemy engine."""
+    with Session(engine) as session:
+        refresh_bm25_corpus(session, config)
+    load_bm25_corpus.cache_clear()
+    logger.info("ebook_bm25_corpus_cache_cleared_after_refresh")

python/ebook_search/api/main.py

@@ -0,0 +1,79 @@
+"""FastAPI HTMX app for EPUB search."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+import uvicorn
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from sqlalchemy.orm import Session
+
+from python.common import configure_logger
+from python.ebook_search.api.bm25_tasks import cancel_bm25_refresh
+from python.ebook_search.api.routes import admin_router, page_router, search_router
+from python.ebook_search.api.web import STATIC_DIR
+from python.ebook_search.bm25_corpus import ensure_bm25_corpus
+from python.ebook_search.config import load_config
+from python.fastapi_tools import ZstdMiddleware
+from python.orm.common import get_postgres_engine
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Manage application startup and shutdown resources."""
+    logger.info("ebook_search_startup")
+    app.state.engine = get_postgres_engine(name="RICHIE", vector_engine=True)
+    with Session(app.state.engine) as session:
+        ensure_bm25_corpus(session, app.state.config)
+    try:
+        yield
+    finally:
+        logger.info("ebook_search_shutdown")
+        cancel_bm25_refresh(app)
+        app.state.engine.dispose()
+
+
+def create_app() -> FastAPI:
+    """Create the EPUB search web app."""
+    app = FastAPI(title="EPUB Search", lifespan=lifespan)
+    app.add_middleware(ZstdMiddleware)
+    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+    app.state.config = load_config()
+    logger.info(
+        "ebook_search_config_loaded top_k=%s embedding_model=%s rerank_enabled=%s answer_enabled=%s library_paths=%s",
+        app.state.config.top_k,
+        app.state.config.embedding_model,
+        app.state.config.rerank.enabled,
+        app.state.config.answer_enabled,
+        len(app.state.config.library_paths),
+    )
+
+    app.include_router(admin_router)
+    app.include_router(page_router)
+    app.include_router(search_router)
+
+    return app
+
+
+def serve(
+    host: Annotated[str, typer.Option("--host", "-h", help="Host to bind to")] = "127.0.0.1",
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to bind to")] = 8070,
+    log_level: Annotated[str, typer.Option("--log-level", "-l", help="Log level")] = "INFO",
+) -> None:
+    """Start the EPUB search server."""
+    configure_logger(log_level)
+    uvicorn.run(create_app(), host=host, port=port)
+
+
+if __name__ == "__main__":
+    typer.run(serve)

python/ebook_search/api/routes/__init__.py

@@ -0,0 +1,11 @@
+"""EPUB search web route modules."""
+
+from python.ebook_search.api.routes.admin import router as admin_router
+from python.ebook_search.api.routes.page import router as page_router
+from python.ebook_search.api.routes.search import router as search_router
+
+__all__ = [
+    "admin_router",
+    "page_router",
+    "search_router",
+]

python/ebook_search/api/routes/admin.py

@@ -0,0 +1,107 @@
+"""Admin routes for the EPUB search web UI."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import replace
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse
+from sqlalchemy.orm import Session
+
+from python.ebook_search.api.bm25_tasks import schedule_bm25_refresh
+from python.ebook_search.api.web import templates
+from python.ebook_search.embeddings import embed_missing_chunks, embedding_model_stats
+from python.ebook_search.ingest import ingest_configured_paths
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/admin")
+EMBED_ALL_BATCH_SIZE = 32
+
+
+@router.get("", response_class=HTMLResponse)
+def admin(request: Request) -> HTMLResponse:
+    """Render the admin page."""
+    with Session(request.app.state.engine) as session:
+        stats = embedding_model_stats(session)
+    logger.info("ebook_admin_page_loaded models=%s", len(stats))
+    return templates.TemplateResponse(request, "admin.html", {"config": request.app.state.config, "stats": stats})
+
+
+@router.post("/scan", response_class=HTMLResponse)
+def scan_library(request: Request) -> HTMLResponse:
+    """Scan configured library paths for EPUB changes."""
+    try:
+        with Session(request.app.state.engine) as session:
+            count = ingest_configured_paths(session, request.app.state.config)
+            session.commit()
+    except Exception as error:
+        logger.exception("ebook_admin_scan_failed")
+        return templates.TemplateResponse(request, "partials/error.html", {"message": str(error)}, status_code=500)
+
+    logger.info("ebook_admin_scan_complete changed_files=%s", count)
+    if count > 0:
+        schedule_bm25_refresh(request.app)
+    return templates.TemplateResponse(request, "partials/admin_status.html", {"message": f"Indexed {count} EPUBs"})
+
+
+@router.post("/embed-missing", response_class=HTMLResponse)
+def embed_missing(request: Request) -> HTMLResponse:
+    """Embed chunks missing vectors for the configured model."""
+    try:
+        with Session(request.app.state.engine) as session:
+            count = embed_missing_chunks(session, request.app.state.config)
+            session.commit()
+    except Exception as error:
+        logger.exception("ebook_admin_embed_missing_failed")
+        return templates.TemplateResponse(request, "partials/error.html", {"message": str(error)}, status_code=500)
+
+    logger.info("ebook_admin_embed_missing_complete chunks=%s", count)
+    return templates.TemplateResponse(
+        request,
+        "partials/admin_status.html",
+        {"message": f"Embedded {count} chunks"},
+    )
+
+
+@router.post("/embed-all", response_class=HTMLResponse)
+def embed_all(request: Request) -> HTMLResponse:
+    """Embed all chunks missing vectors in fixed-size batches."""
+    total = 0
+    batches = 0
+    config = replace(request.app.state.config, embedding_batch_size=EMBED_ALL_BATCH_SIZE)
+    try:
+        with Session(request.app.state.engine) as session:
+            while True:
+                count = embed_missing_chunks(session, config)
+                if count == 0:
+                    break
+                session.commit()
+                total += count
+                batches += 1
+                logger.info(
+                    "ebook_admin_embed_all_batch_complete batch=%s chunks=%s total_chunks=%s",
+                    batches,
+                    count,
+                    total,
+                )
+    except Exception as error:
+        logger.exception(
+            "ebook_admin_embed_all_failed batches=%s chunks=%s",
+            batches,
+            total,
+        )
+        return templates.TemplateResponse(
+            request,
+            "partials/error.html",
+            {"message": f"Embed all failed after {total} chunks in {batches} batches: {error}"},
+            status_code=500,
+        )
+
+    logger.info("ebook_admin_embed_all_complete batches=%s chunks=%s", batches, total)
+    return templates.TemplateResponse(
+        request,
+        "partials/admin_status.html",
+        {"message": f"Embedded {total} chunks in {batches} batches of {EMBED_ALL_BATCH_SIZE}"},
+    )

python/ebook_search/api/routes/page.py

@@ -0,0 +1,57 @@
+"""Page routes for the EPUB search web UI."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from python.ebook_search.api.web import templates
+from python.orm.richie import EbookSource
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get("/", response_class=HTMLResponse)
+def index(request: Request) -> HTMLResponse:
+    """Render the search page."""
+    return templates.TemplateResponse(request, "search.html", {"config": request.app.state.config})
+
+
+@router.get("/books", response_class=HTMLResponse)
+def books(request: Request) -> HTMLResponse:
+    """Render the indexed books page."""
+    with Session(request.app.state.engine) as session:
+        sources = list(session.scalars(select(EbookSource).order_by(EbookSource.title)).all())
+    logger.info("ebook_books_page_loaded count=%s", len(sources))
+    return templates.TemplateResponse(request, "books.html", {"sources": sources})
+
+
+@router.get("/books/{source_id}", response_class=HTMLResponse)
+def book_detail(source_id: int, request: Request) -> HTMLResponse:
+    """Render details for one indexed book."""
+    with Session(request.app.state.engine) as session:
+        source = session.get(EbookSource, source_id)
+        if source is not None:
+            chapter_count = len(source.chapters)
+            chunk_count = len(source.chunks)
+        else:
+            chapter_count = 0
+            chunk_count = 0
+    logger.info(
+        "ebook_book_detail_loaded source_id=%s found=%s chapters=%s chunks=%s",
+        source_id,
+        source is not None,
+        chapter_count,
+        chunk_count,
+    )
+    return templates.TemplateResponse(
+        request,
+        "book_detail.html",
+        {"chapter_count": chapter_count, "chunk_count": chunk_count, "source": source},
+    )

python/ebook_search/api/routes/search.py

@@ -0,0 +1,58 @@
+"""Search routes for the EPUB search web UI."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import replace
+from time import perf_counter
+from typing import Annotated
+
+from fastapi import APIRouter, Form, Request
+from fastapi.responses import HTMLResponse
+
+from python.ebook_search.answer import answer_query
+from python.ebook_search.api.web import templates
+from python.ebook_search.search import search_ebooks
+from python.ebook_search.timing import runtime_step_from_start
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.post("/search", response_class=HTMLResponse)
+def search(
+    request: Request,
+    query: Annotated[str, Form()],
+    rerank: Annotated[str | None, Form()] = None,
+) -> HTMLResponse:
+    """Run a search and render HTMX results."""
+    try:
+        response = search_ebooks(request.app.state.engine, query, request.app.state.config, rerank=rerank == "true")
+    except Exception as error:
+        logger.exception("ebook_search_request_failed")
+        return templates.TemplateResponse(request, "partials/error.html", {"message": str(error)}, status_code=500)
+
+    answer_start = perf_counter()
+    if request.app.state.config.answer_enabled:
+        try:
+            answer = answer_query(query, response.results, request.app.state.config)
+        except RuntimeError as error:
+            logger.warning("ebook_answer_request_failed_falling_back error=%s", error)
+            answer = "Answer generation failed. Source chunks are still shown below."
+    else:
+        logger.info("ebook_answer_skipped_disabled")
+        answer = "Answer generation is disabled. Source chunks are shown below."
+    answer_step_name = "Answer generation" if request.app.state.config.answer_enabled else "Answer skipped"
+    response = replace(
+        response,
+        timings=(*response.timings, runtime_step_from_start(answer_step_name, answer_start)),
+    )
+
+    logger.info(
+        "ebook_search_request_complete results=%s rank_label=%s runtime_ms=%.1f",
+        len(response.results),
+        response.rank_label,
+        response.total_runtime_ms,
+    )
+    return templates.TemplateResponse(request, "partials/results.html", {"answer": answer, "response": response})

python/ebook_search/api/static/style.css

@@ -0,0 +1,140 @@
+body {
+    margin: 0;
+    background: #f7f7f4;
+    color: #202124;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+main {
+    max-width: 960px;
+    margin: 0 auto;
+    padding: 24px;
+}
+
+nav {
+    display: flex;
+    gap: 12px;
+    align-items: center;
+    margin-bottom: 20px;
+}
+
+nav form {
+    margin: 0;
+}
+
+.actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 12px;
+    margin-bottom: 24px;
+}
+
+textarea {
+    display: block;
+    width: 100%;
+    margin: 8px 0 12px;
+}
+
+button {
+    padding: 8px 14px;
+}
+
+.check {
+    display: inline-flex;
+    gap: 8px;
+    align-items: center;
+    margin-right: 12px;
+}
+
+.rank-label {
+    margin-top: 24px;
+    font-weight: 700;
+}
+
+.results {
+    padding-left: 24px;
+}
+
+.meta,
+.scores,
+.status {
+    color: #626a73;
+}
+
+.scores {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin: 12px 0;
+}
+
+.scores div {
+    display: inline-flex;
+    gap: 4px;
+    align-items: baseline;
+}
+
+.scores dt {
+    font-weight: 700;
+}
+
+.scores dd {
+    margin: 0;
+}
+
+.runtime {
+    margin-top: 16px;
+}
+
+.timing-chart {
+    display: grid;
+    gap: 8px;
+    padding: 0;
+    list-style: none;
+}
+
+.timing-chart li {
+    display: grid;
+    grid-template-columns: minmax(150px, 1fr) minmax(160px, 2fr) auto auto;
+    gap: 8px;
+    align-items: center;
+}
+
+.timing-bar {
+    height: 10px;
+    overflow: hidden;
+    background: #e5e5df;
+}
+
+.timing-bar span {
+    display: block;
+    height: 100%;
+    background: #3767c8;
+}
+
+.timing-value,
+.timing-remaining {
+    color: #626a73;
+    font-variant-numeric: tabular-nums;
+}
+
+table {
+    width: 100%;
+    border-collapse: collapse;
+}
+
+th,
+td {
+    padding: 8px;
+    border-bottom: 1px solid #d8d8d2;
+    text-align: left;
+}
+
+th {
+    font-weight: 700;
+}
+
+.error {
+    color: #9f1d20;
+    font-weight: 700;
+}

python/ebook_search/api/templates/admin.html

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>EPUB Admin</title>
+    <script src="https://unpkg.com/htmx.org@2.0.4"></script>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <main>
+        <nav>
+            <a href="/">Search</a>
+            <a href="/books">Books</a>
+            <a href="/admin">Admin</a>
+        </nav>
+        <h1>Admin</h1>
+        <section id="admin-status"></section>
+        <section class="actions">
+            <form hx-post="/admin/scan" hx-target="#admin-status" hx-swap="innerHTML">
+                <button type="submit">Scan</button>
+            </form>
+            <form hx-post="/admin/embed-missing" hx-target="#admin-status" hx-swap="innerHTML">
+                <button type="submit">Embed</button>
+            </form>
+            <form hx-post="/admin/embed-all" hx-target="#admin-status" hx-swap="innerHTML">
+                <button type="submit">Embed all</button>
+            </form>
+        </section>
+        <section>
+            <h2>Embeddings</h2>
+            <table>
+                <thead>
+                    <tr>
+                        <th>Model</th>
+                        <th>Dimensions</th>
+                        <th>Embedded</th>
+                        <th>Missing</th>
+                        <th>Total chunks</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    {% for item in stats %}
+                        <tr>
+                            <td>{{ item.model_name }}</td>
+                            <td>{{ item.dimension }}</td>
+                            <td>{{ item.embedded_chunks }}</td>
+                            <td>{{ item.missing_chunks }}</td>
+                            <td>{{ item.total_chunks }}</td>
+                        </tr>
+                    {% endfor %}
+                </tbody>
+            </table>
+        </section>
+    </main>
+</body>
+</html>

python/ebook_search/api/templates/book_detail.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% if source %}{{ source.title }}{% else %}Book not found{% endif %}</title>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <main>
+        <nav>
+            <a href="/">Search</a>
+            <a href="/books">Books</a>
+            <a href="/admin">Admin</a>
+        </nav>
+        {% if source %}
+            <h1>{{ source.title }}</h1>
+            <p class="meta">{{ source.author or "Unknown author" }}</p>
+            <dl>
+                <dt>File</dt>
+                <dd>{{ source.file_path }}</dd>
+                <dt>Chapters</dt>
+                <dd>{{ chapter_count }}</dd>
+                <dt>Chunks</dt>
+                <dd>{{ chunk_count }}</dd>
+            </dl>
+        {% else %}
+            <h1>Book not found</h1>
+        {% endif %}
+    </main>
+</body>
+</html>

python/ebook_search/api/templates/books.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>EPUB Books</title>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <main>
+        <nav>
+            <a href="/">Search</a>
+            <a href="/books">Books</a>
+            <a href="/admin">Admin</a>
+        </nav>
+        <h1>Books</h1>
+        {% if sources %}
+            <ol class="results">
+                {% for source in sources %}
+                    <li>
+                        <h2><a href="/books/{{ source.id }}">{{ source.title }}</a></h2>
+                        <p class="meta">{{ source.author or "Unknown author" }}</p>
+                    </li>
+                {% endfor %}
+            </ol>
+        {% else %}
+            <p>No EPUBs indexed.</p>
+        {% endif %}
+    </main>
+</body>
+</html>

python/ebook_search/api/templates/partials/admin_status.html

@@ -0,0 +1 @@
+<p class="status">{{ message }}</p>

python/ebook_search/api/templates/partials/error.html

@@ -0,0 +1 @@
+<p class="error">{{ message }}</p>

python/ebook_search/api/templates/partials/results.html

@@ -0,0 +1,74 @@
+<div class="rank-label">{{ response.rank_label }}</div>
+{% if response.timings %}
+    <section class="runtime">
+        <h2>Runtime</h2>
+        <p class="meta">Total {{ "%.1f"|format(response.total_runtime_ms) }} ms</p>
+        <ol class="timing-chart">
+            {% set total = response.total_runtime_ms %}
+            {% set ns = namespace(remaining=total) %}
+            {% for step in response.timings %}
+                {% set width = (step.duration_ms / total * 100) if total else 0 %}
+                {% if step.counts_toward_total %}
+                    {% set ns.remaining = ns.remaining - step.duration_ms %}
+                {% endif %}
+                <li>
+                    <span class="timing-label">{{ step.name }}</span>
+                    <span class="timing-bar"><span style="width: {{ "%.2f"|format(width) }}%"></span></span>
+                    <span class="timing-value">{{ "%.1f"|format(step.duration_ms) }} ms</span>
+                    <span class="timing-remaining">{{ "%.1f"|format([ns.remaining, 0]|max) }} ms left</span>
+                </li>
+            {% endfor %}
+        </ol>
+    </section>
+{% endif %}
+<section class="answer">
+    <h2>Answer</h2>
+    <p>{{ answer }}</p>
+</section>
+{% if response.results %}
+    <ol class="results">
+        {% for result in response.results %}
+            <li>
+                <h2>{{ result.source_title }}</h2>
+                <p class="meta">
+                    {% if result.source_author %}{{ result.source_author }}{% endif %}
+                    {% if result.chapter_title %} · {{ result.chapter_title }}{% endif %}
+                    {% if result.page_label %} · page {{ result.page_label }}{% endif %}
+                </p>
+                <p>{{ result.text }}</p>
+                <dl class="scores">
+                    <div>
+                        <dt>final</dt>
+                        <dd>{{ "%.3f"|format(result.score) }}</dd>
+                    </div>
+                    {% if result.rerank_score is not none %}
+                        <div>
+                            <dt>rerank</dt>
+                            <dd>{{ "%.3f"|format(result.rerank_score) }}</dd>
+                        </div>
+                    {% endif %}
+                    {% if result.vector_score is not none %}
+                        <div>
+                            <dt>vector cosine</dt>
+                            <dd>{{ "%.3f"|format(result.vector_score) }}</dd>
+                        </div>
+                    {% endif %}
+                    {% if result.bm25_score is not none %}
+                        <div>
+                            <dt>BM25</dt>
+                            <dd>{{ "%.6f"|format(result.bm25_score) }}</dd>
+                        </div>
+                    {% endif %}
+                    {% if result.fused_score is not none %}
+                        <div>
+                            <dt>RRF</dt>
+                            <dd>{{ "%.3f"|format(result.fused_score) }}</dd>
+                        </div>
+                    {% endif %}
+                </dl>
+            </li>
+        {% endfor %}
+    </ol>
+{% else %}
+    <p>No results.</p>
+{% endif %}

python/ebook_search/api/templates/search.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>EPUB Search</title>
+    <script src="https://unpkg.com/htmx.org@2.0.4"></script>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <main>
+        <nav>
+            <a href="/">Search</a>
+            <a href="/books">Books</a>
+            <a href="/admin">Admin</a>
+        </nav>
+        <h1>EPUB Search</h1>
+        <form hx-post="/search" hx-target="#results" hx-swap="innerHTML">
+            <label for="query">Search</label>
+            <textarea id="query" name="query" rows="4" required></textarea>
+            <label class="check">
+                <input type="checkbox" name="rerank" value="true" {% if config.rerank.enabled %}checked{% endif %}>
+                Rerank
+            </label>
+            <button type="submit">Search</button>
+        </form>
+        <section id="results"></section>
+    </main>
+</body>
+</html>

python/ebook_search/api/web.py

@@ -0,0 +1,13 @@
+"""Shared web UI resources for EPUB search."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi.templating import Jinja2Templates
+
+PACKAGE_DIR = Path(__file__).resolve().parent
+TEMPLATE_DIR = PACKAGE_DIR / "templates"
+STATIC_DIR = PACKAGE_DIR / "static"
+
+templates = Jinja2Templates(directory=TEMPLATE_DIR)

python/ebook_search/bm25_corpus.py

@@ -0,0 +1,237 @@
+"""Persisted BM25 corpus management."""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from functools import cache
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import bm25s
+from sqlalchemy import func, select, union_all
+
+from python.orm.richie import EbookChapter, EbookChunk, EbookSource
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session
+
+    from python.ebook_search.config import EbookSearchConfig
+
+logger = logging.getLogger(__name__)
+MANIFEST_NAME = "manifest.json"
+REQUIRED_INDEX_FILES = frozenset(
+    {
+        "data.csc.index.npy",
+        "indices.csc.index.npy",
+        "indptr.csc.index.npy",
+        "params.index.json",
+        "vocab.index.json",
+        "corpus.jsonl",
+    }
+)
+
+
+@dataclass(frozen=True)
+class BM25Manifest:
+    """Metadata describing a persisted BM25 corpus."""
+
+    created_at: datetime
+    db_updated_at: datetime | None
+    chunk_count: int
+
+
+@dataclass(frozen=True)
+class BM25Corpus:
+    """Loaded persisted BM25 corpus and retriever."""
+
+    retriever: object | None
+    records: tuple[dict[str, object], ...]
+    manifest: BM25Manifest
+
+
+class BM25CorpusUnavailableError(RuntimeError):
+    """Raised when the persisted BM25 corpus cannot be loaded."""
+
+
+def bm25_index_path(config: EbookSearchConfig) -> Path:
+    """Return the configured BM25 index path relative to the current working directory."""
+    path = Path(config.bm25_index_dir).expanduser()
+    if path.is_absolute():
+        return path
+    return Path.cwd() / path
+
+
+def ensure_bm25_corpus(session: Session, config: EbookSearchConfig) -> None:
+    """Create or refresh the persisted BM25 corpus when it is missing or stale."""
+    index_path = bm25_index_path(config)
+    manifest = read_bm25_manifest(index_path)
+    db_updated_at = corpus_last_updated_at(session)
+    if not bm25_index_exists(index_path, manifest):
+        logger.info("ebook_bm25_index_missing path=%s", index_path)
+        refresh_bm25_corpus(session, config, db_updated_at=db_updated_at)
+        return
+    if db_updated_at is not None and manifest is not None and manifest.created_at < db_updated_at:
+        logger.info(
+            "ebook_bm25_index_stale path=%s created_at=%s db_updated_at=%s",
+            index_path,
+            manifest.created_at.isoformat(),
+            db_updated_at.isoformat(),
+        )
+        refresh_bm25_corpus(session, config, db_updated_at=db_updated_at)
+        return
+    logger.info(
+        "ebook_bm25_index_current path=%s chunks=%s created_at=%s",
+        index_path,
+        manifest.chunk_count if manifest else 0,
+        manifest.created_at.isoformat() if manifest else None,
+    )
+
+
+def refresh_bm25_corpus(
+    session: Session,
+    config: EbookSearchConfig,
+    *,
+    db_updated_at: datetime | None = None,
+) -> BM25Manifest:
+    """Rebuild and persist the BM25 corpus from the current database chunks."""
+    index_path = bm25_index_path(config)
+    records = fetch_bm25_corpus_records(session)
+    manifest = BM25Manifest(
+        created_at=datetime.now(tz=UTC),
+        db_updated_at=db_updated_at if db_updated_at is not None else corpus_last_updated_at(session),
+        chunk_count=len(records),
+    )
+    write_bm25_corpus(index_path, records, manifest)
+    logger.info(
+        "ebook_bm25_index_refreshed path=%s chunks=%s created_at=%s",
+        index_path,
+        manifest.chunk_count,
+        manifest.created_at.isoformat(),
+    )
+    return manifest
+
+
+@cache
+def load_bm25_corpus(config: EbookSearchConfig) -> BM25Corpus:
+    """Load the BM25 corpus into memory once per process.
+
+    Background refresh tasks clear this cache after rebuilding the on-disk corpus.
+    """
+    index_path = bm25_index_path(config)
+    logger.info("ebook_bm25_corpus_cache_load path=%s", index_path)
+    manifest = read_bm25_manifest(index_path)
+    if manifest is None or not bm25_index_exists(index_path, manifest):
+        msg = f"BM25 corpus is not available: {index_path}"
+        raise BM25CorpusUnavailableError(msg)
+    if manifest.chunk_count == 0:
+        return BM25Corpus(retriever=None, records=(), manifest=manifest)
+
+    retriever = bm25s.BM25.load(index_path, load_corpus=True, mmap=True)
+    records = tuple(dict(record) for record in retriever.corpus)
+    return BM25Corpus(retriever=retriever, records=records, manifest=manifest)
+
+
+def score_bm25_corpus(query: str, corpus: BM25Corpus, *, limit: int) -> list[tuple[dict[str, object], float]]:
+    """Score a query against a loaded BM25 corpus."""
+    if corpus.retriever is None or not corpus.records:
+        return []
+    k = min(limit, len(corpus.records))
+    documents, scores = corpus.retriever.retrieve(
+        bm25s.tokenize(query, show_progress=False),
+        corpus=list(corpus.records),
+        k=k,
+        show_progress=False,
+    )
+    results: list[tuple[dict[str, object], float]] = []
+    for document, score in zip(documents[0], scores[0], strict=True):
+        score_value = float(score)
+        if score_value <= 0:
+            continue
+        results.append((dict(document), score_value))
+    return results
+
+
+def fetch_bm25_corpus_records(session: Session) -> list[dict[str, object]]:
+    """Fetch BM25 corpus records from the database."""
+    statement = (
+        select(
+            EbookChunk.id.label("chunk_id"),
+            EbookChunk.text.label("text"),
+            EbookSource.title.label("source_title"),
+            EbookSource.author.label("source_author"),
+            EbookChapter.title.label("chapter_title"),
+            EbookChunk.page_label.label("page_label"),
+            EbookChunk.search_text.label("bm25_text"),
+        )
+        .select_from(EbookChunk)
+        .join(EbookSource, EbookSource.id == EbookChunk.source_id)
+        .outerjoin(EbookChapter, EbookChapter.id == EbookChunk.chapter_id)
+        .order_by(EbookChunk.id)
+    )
+    return [dict(row) for row in session.execute(statement).mappings()]
+
+
+def corpus_last_updated_at(session: Session) -> datetime | None:
+    """Return the latest source/chapter/chunk update timestamp relevant to BM25 text."""
+    update_times = union_all(
+        select(func.max(EbookSource.updated).label("updated")),
+        select(func.max(EbookChapter.updated).label("updated")),
+        select(func.max(EbookChunk.updated).label("updated")),
+    ).subquery()
+    return session.scalar(select(func.max(update_times.c.updated)))
+
+
+def write_bm25_corpus(index_path: Path, records: list[dict[str, object]], manifest: BM25Manifest) -> None:
+    """Write a BM25 corpus and manifest atomically."""
+    index_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = Path(tempfile.mkdtemp(prefix=f"{index_path.name}.", dir=index_path.parent))
+    try:
+        if records:
+            retriever = bm25s.BM25()
+            texts = [str(record["bm25_text"]) for record in records]
+            retriever.index(bm25s.tokenize(texts, show_progress=False), show_progress=False)
+            retriever.save(temp_path, corpus=records, show_progress=False)
+        write_bm25_manifest(temp_path, manifest)
+        if index_path.exists():
+            shutil.rmtree(index_path)
+        temp_path.rename(index_path)
+    except Exception:
+        shutil.rmtree(temp_path, ignore_errors=True)
+        raise
+
+
+def read_bm25_manifest(index_path: Path) -> BM25Manifest | None:
+    """Read the BM25 manifest if it exists and is valid."""
+    manifest_path = index_path / MANIFEST_NAME
+    if not manifest_path.exists():
+        return None
+    body = json.loads(manifest_path.read_text(encoding="utf-8"))
+    return BM25Manifest(
+        created_at=datetime.fromisoformat(str(body["created_at"])),
+        db_updated_at=datetime.fromisoformat(str(body["db_updated_at"])) if body.get("db_updated_at") else None,
+        chunk_count=int(body["chunk_count"]),
+    )
+
+
+def write_bm25_manifest(index_path: Path, manifest: BM25Manifest) -> None:
+    """Write the BM25 manifest to an index directory."""
+    body = {
+        "created_at": manifest.created_at.isoformat(),
+        "db_updated_at": manifest.db_updated_at.isoformat() if manifest.db_updated_at else None,
+        "chunk_count": manifest.chunk_count,
+    }
+    (index_path / MANIFEST_NAME).write_text(json.dumps(body, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def bm25_index_exists(index_path: Path, manifest: BM25Manifest | None) -> bool:
+    """Return whether a usable persisted BM25 index exists."""
+    if manifest is None or not index_path.is_dir():
+        return False
+    if manifest.chunk_count == 0:
+        return True
+    return all((index_path / file_name).exists() for file_name in REQUIRED_INDEX_FILES)

python/ebook_search/config.py

@@ -0,0 +1,117 @@
+"""Configuration for the EPUB search app."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from os import getenv
+
+
+def getenv_bool(name: str, *, default: bool) -> bool:
+    """Read a boolean environment variable with a default fallback."""
+    value = getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def getenv_int(name: str, *, default: int) -> int:
+    """Read an integer environment variable with a default fallback."""
+    value = getenv(name)
+    if value is None or not value.strip():
+        return default
+    return int(value)
+
+
+@dataclass(frozen=True)
+class RerankConfig:
+    """vLLM reranker settings."""
+
+    enabled: bool = False
+    base_url: str = "http://192.168.90.25:8001"
+    model: str = "qwen3-reranker-06b"
+    candidates: int = 24
+    timeout_seconds: float = 30.0
+
+
+@dataclass(frozen=True)
+class EbookSearchConfig:
+    """Runtime settings for EPUB search."""
+
+    rerank: RerankConfig
+    top_k: int = 12
+    library_paths: tuple[str, ...] = ()
+    vllm_base_url: str = "https://ollama.com/v1"
+    vllm_api_key: str = "not-needed"
+    chat_model: str = "deepseek-v4-flash"
+    answer_enabled: bool = True
+    embedding_base_url: str = "http://192.168.90.25:8000/v1"
+    embedding_api_key: str = "not-needed"
+    embedding_model: str = "qwen3-embedding-0.6b"
+    embedding_batch_size: int = 32
+    bm25_index_dir: str = ".ebook_search_bm25"
+    bm25_refresh_delay_seconds: int = 60
+
+
+def load_rerank_config() -> RerankConfig:
+    """Load reranker config from environment variables."""
+    return RerankConfig(
+        enabled=getenv_bool("EBOOK_SEARCH_RERANK_ENABLED", default=False),
+        base_url=getenv("EBOOK_SEARCH_RERANK_BASE_URL", "http://192.168.90.25:8001"),
+        model=getenv("EBOOK_SEARCH_RERANK_MODEL", "qwen3-reranker-06b"),
+        candidates=getenv_int("EBOOK_SEARCH_RERANK_CANDIDATES", default=24),
+        timeout_seconds=float(getenv_int("EBOOK_SEARCH_RERANK_TIMEOUT_SECONDS", default=30)),
+    )
+
+
+def load_config() -> EbookSearchConfig:
+    """Load EPUB search config from environment variables."""
+    return EbookSearchConfig(
+        rerank=load_rerank_config(),
+        top_k=getenv_int("EBOOK_SEARCH_TOP_K", default=12),
+        library_paths=library_paths_from_env(),
+        vllm_base_url=getenv("EBOOK_SEARCH_VLLM_BASE_URL", "https://ollama.com/v1"),
+        vllm_api_key=getenv("EBOOK_SEARCH_VLLM_API_KEY") or getenv("OLLAMA_API_KEY") or "not-needed",
+        chat_model=getenv("EBOOK_SEARCH_CHAT_MODEL", "deepseek-v4-flash"),
+        answer_enabled=getenv_bool("EBOOK_SEARCH_ANSWER_ENABLED", default=True),
+        embedding_base_url=getenv("EBOOK_SEARCH_EMBEDDING_BASE_URL", "http://192.168.90.25:8000/v1"),
+        embedding_api_key=getenv("EBOOK_SEARCH_EMBEDDING_API_KEY", "not-needed"),
+        embedding_model=normalize_embedding_model(),
+        embedding_batch_size=getenv_int("EBOOK_SEARCH_EMBEDDING_BATCH_SIZE", default=32),
+        bm25_index_dir=getenv("EBOOK_SEARCH_BM25_INDEX_DIR", ".ebook_search_bm25"),
+        bm25_refresh_delay_seconds=getenv_int("EBOOK_SEARCH_BM25_REFRESH_DELAY_SECONDS", default=60),
+    )
+
+
+def normalize_embedding_model(default: str = "qwen3-embedding-0.6b") -> str:
+    """Normalize supported embedding aliases to provider model names."""
+    aliases = {
+        "Qwen3-Embedding-0.6B": "qwen3-embedding-0.6b",
+        "Qwen3-Embedding-4B": "qwen3-embedding-4b",
+        "Qwen3-Embedding-8B": "qwen3-embedding-8b",
+        "Qwen/Qwen3-Embedding-0.6B": "qwen3-embedding-0.6b",
+        "Qwen/Qwen3-Embedding-4B": "qwen3-embedding-4b",
+        "Qwen/Qwen3-Embedding-8B": "qwen3-embedding-8b",
+        "qwen3-embedding:0.6b": "qwen3-embedding-0.6b",
+        "qwen3-embedding:4b": "qwen3-embedding-4b",
+        "qwen3-embedding:8b": "qwen3-embedding-8b",
+        "qwen3-embedding-0.6b": "qwen3-embedding-0.6b",
+        "qwen3-embedding-4b": "qwen3-embedding-4b",
+        "qwen3-embedding-8b": "qwen3-embedding-8b",
+    }
+
+    model = getenv("EBOOK_SEARCH_EMBEDDING_MODEL", default)
+    standard_model = aliases.get(model)
+
+    if standard_model is None:
+        error = f"Embedding model {model} is not supported. Supported models are {aliases.keys()}"
+        raise ValueError(error)
+
+    return standard_model
+
+
+def library_paths_from_env() -> tuple[str, ...]:
+    """Read configured EPUB library paths from the environment."""
+    value = getenv("EBOOK_SEARCH_LIBRARY_PATHS")
+    if value is None:
+        return ()
+    return tuple(path for path in value.split(":") if path)

python/ebook_search/embeddings.py

@@ -0,0 +1,170 @@
+"""Embedding model helpers."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sqlalchemy import func, select
+from sqlalchemy.dialects.postgresql import insert
+
+from python.ebook_search.llm_interface import request_embeddings
+from python.orm.richie import (
+    EbookChunk,
+    EbookChunkEmbedding1024,
+    EbookChunkEmbedding2560,
+    EbookChunkEmbedding4096,
+    EbookEmbeddingModel,
+)
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sqlalchemy.orm import Session
+
+    from python.ebook_search.config import EbookSearchConfig
+
+MODEL_DIMENSIONS = {
+    "qwen3-embedding-0.6b": 1024,
+    "qwen3-embedding-4b": 2560,
+    "qwen3-embedding-8b": 4096,
+}
+
+
+def get_embedding_table(
+    dimension: int,
+) -> type[EbookChunkEmbedding1024 | EbookChunkEmbedding2560 | EbookChunkEmbedding4096]:
+    """Return the embedding table mapped to an embedding dimension."""
+    embedding_tables = {
+        1024: EbookChunkEmbedding1024,
+        2560: EbookChunkEmbedding2560,
+        4096: EbookChunkEmbedding4096,
+    }
+    table = embedding_tables.get(dimension)
+    if not table:
+        msg = f"Embedding dimension {dimension} is not supported"
+        raise ValueError(msg)
+    return table
+
+
+@dataclass(frozen=True)
+class EmbeddingModelStats:
+    """Embedding coverage for one model."""
+
+    model_name: str
+    dimension: int
+    embedded_chunks: int
+    total_chunks: int
+
+    @property
+    def missing_chunks(self) -> int:
+        """Return chunks missing this embedding model."""
+        return max(self.total_chunks - self.embedded_chunks, 0)
+
+
+def embed_texts(texts: Sequence[str], config: EbookSearchConfig) -> list[list[float]]:
+    """Embed text with the configured vLLM embedding model."""
+    logger.info(
+        "ebook_embed_request_start base_url=%s model=%s count=%s",
+        config.embedding_base_url,
+        config.embedding_model,
+        len(texts),
+    )
+    vectors = request_embeddings(texts, config)
+    expected_dimension = MODEL_DIMENSIONS[config.embedding_model]
+    for vector in vectors:
+        if len(vector) != expected_dimension:
+            msg = f"Expected {expected_dimension} dimensions, got {len(vector)}"
+            raise ValueError(msg)
+    logger.info(
+        "ebook_embed_request_complete model=%s count=%s dimension=%s",
+        config.embedding_model,
+        len(vectors),
+        expected_dimension,
+    )
+    return vectors
+
+
+def embed_query(query: str, config: EbookSearchConfig) -> list[float]:
+    """Embed a search query with the Qwen retrieval instruction."""
+    instructed_query = f"Instruct: Retrieve relevant passages for the query.\nQuery: {query}"
+    return embed_texts([instructed_query], config)[0]
+
+
+def ensure_embedding_models(session: Session) -> None:
+    """Ensure supported embedding model rows exist."""
+    for name, dimension in MODEL_DIMENSIONS.items():
+        existing = session.scalar(select(EbookEmbeddingModel).where(EbookEmbeddingModel.name == name))
+        if existing is None:
+            session.add(EbookEmbeddingModel(name=name, dimension=dimension, is_default=name == "qwen3-embedding-0.6b"))
+            logger.info("ebook_embedding_model_created model=%s dimension=%s", name, dimension)
+    session.flush()
+
+
+def embedding_model_stats(session: Session) -> list[EmbeddingModelStats]:
+    """Return embedding coverage counts for every supported model."""
+    total_chunks = session.scalar(select(func.count(EbookChunk.id))) or 0
+    models = {
+        model.name: model
+        for model in session.scalars(
+            select(EbookEmbeddingModel)
+            .where(EbookEmbeddingModel.name.in_(MODEL_DIMENSIONS))
+            .order_by(EbookEmbeddingModel.name)
+        )
+    }
+
+    stats: list[EmbeddingModelStats] = []
+    for model_name, dimension in MODEL_DIMENSIONS.items():
+        model = models.get(model_name)
+        embedded_chunks = 0
+        if model is not None:
+            table = get_embedding_table(dimension)
+            embedded_chunks = session.scalar(select(func.count(table.id)).where(table.model_id == model.id)) or 0
+        stats.append(
+            EmbeddingModelStats(
+                model_name=model_name,
+                dimension=dimension,
+                embedded_chunks=embedded_chunks,
+                total_chunks=total_chunks,
+            )
+        )
+    return stats
+
+
+def embed_missing_chunks(session: Session, config: EbookSearchConfig) -> int:
+    """Embed chunks missing embeddings for the configured model."""
+    ensure_embedding_models(session)
+    model = session.scalar(select(EbookEmbeddingModel).where(EbookEmbeddingModel.name == config.embedding_model))
+    if model is None:
+        supported_models = ", ".join(MODEL_DIMENSIONS)
+        msg = f"Unknown embedding model: {config.embedding_model}. Supported models: {supported_models}"
+        raise ValueError(msg)
+
+    table = get_embedding_table(model.dimension)
+    chunks = list(
+        session.scalars(
+            select(EbookChunk)
+            .outerjoin(table, (table.chunk_id == EbookChunk.id) & (table.model_id == model.id))
+            .where(table.id.is_(None))
+            .order_by(EbookChunk.id)
+            .limit(config.embedding_batch_size)
+        )
+    )
+    if not chunks:
+        logger.info("ebook_embed_missing_none model=%s", config.embedding_model)
+        return 0
+
+    logger.info("ebook_embed_missing_batch_start model=%s count=%s", config.embedding_model, len(chunks))
+    vectors = embed_texts([chunk.text for chunk in chunks], config)
+    rows = [
+        {"chunk_id": chunk.id, "model_id": model.id, "embedding": vector}
+        for chunk, vector in zip(chunks, vectors, strict=True)
+    ]
+    statement = insert(table).values(rows).on_conflict_do_nothing(index_elements=["chunk_id", "model_id"])
+    session.execute(statement)
+    session.flush()
+    logger.info("ebook_embed_missing_batch_complete model=%s count=%s", config.embedding_model, len(rows))
+    return len(rows)

python/ebook_search/epub_parse.py

@@ -0,0 +1,95 @@
+"""EPUB parsing helpers."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from bs4 import BeautifulSoup
+from ebooklib import ITEM_DOCUMENT, epub
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+WHITESPACE_RE = re.compile(r"\s+")
+
+
+@dataclass(frozen=True)
+class ParsedChapter:
+    """Text extracted from one EPUB spine document."""
+
+    title: str | None
+    href: str | None
+    text: str
+    page_labels: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ParsedEpub:
+    """Parsed EPUB metadata and text."""
+
+    title: str
+    author: str | None
+    language: str | None
+    publisher: str | None
+    identifier: str | None
+    chapters: tuple[ParsedChapter, ...]
+
+
+def parse_epub(path: Path) -> ParsedEpub:
+    """Parse EPUB metadata and spine text."""
+    book = epub.read_epub(path)
+    chapters = []
+    for item in book.get_items_of_type(ITEM_DOCUMENT):
+        soup = BeautifulSoup(item.get_content(), "html.parser")
+        title = chapter_title(soup)
+        page_labels = tuple(extract_page_labels(soup))
+        text = clean_text(soup.get_text(" "))
+        if text:
+            chapters.append(ParsedChapter(title=title, href=item.get_name(), text=text, page_labels=page_labels))
+
+    return ParsedEpub(
+        title=metadata_value(book, "title") or path.stem,
+        author=metadata_value(book, "creator"),
+        language=metadata_value(book, "language"),
+        publisher=metadata_value(book, "publisher"),
+        identifier=metadata_value(book, "identifier"),
+        chapters=tuple(chapters),
+    )
+
+
+def metadata_value(book: epub.EpubBook, name: str) -> str | None:
+    """Return the first non-empty Dublin Core metadata value for a name."""
+    values = book.get_metadata("DC", name)
+    if not values:
+        return None
+    value = values[0][0]
+    return str(value).strip() or None
+
+
+def chapter_title(soup: BeautifulSoup) -> str | None:
+    """Extract the best available title from an EPUB document soup."""
+    heading = soup.find(["h1", "h2", "h3"])
+    if heading is None:
+        title = soup.find("title")
+        if title is None:
+            return None
+        return clean_text(title.get_text(" ")) or None
+    return clean_text(heading.get_text(" ")) or None
+
+
+def extract_page_labels(soup: BeautifulSoup) -> list[str]:
+    """Extract EPUB page-break labels from a document soup."""
+    labels: list[str] = []
+    for tag in soup.find_all(attrs={"epub:type": "pagebreak"}):
+        label = tag.get("title") or tag.get("aria-label") or tag.get_text(" ")
+        clean = clean_text(str(label))
+        if clean:
+            labels.append(clean)
+    return labels
+
+
+def clean_text(text: str) -> str:
+    """Normalize whitespace in extracted EPUB text."""
+    return WHITESPACE_RE.sub(" ", text).strip()

python/ebook_search/ingest.py

@@ -0,0 +1,190 @@
+"""EPUB ingestion into Richie DB."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import tiktoken
+from sqlalchemy import or_, select
+
+from python.ebook_search.epub_parse import parse_epub
+from python.orm.richie import EbookChapter, EbookChunk, EbookSource
+
+logger = logging.getLogger(__name__)
+DEFAULT_CHUNK_TOKENS = 700
+DEFAULT_CHUNK_OVERLAP = 100
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session
+
+    from python.ebook_search.config import EbookSearchConfig
+    from python.ebook_search.epub_parse import ParsedChapter
+
+
+@dataclass(frozen=True)
+class TextChunk:
+    """A token-bounded chunk of text."""
+
+    text: str
+    token_start: int
+    token_count: int
+
+
+def chunk_text(
+    text: str,
+    *,
+    chunk_tokens: int = DEFAULT_CHUNK_TOKENS,
+    overlap_tokens: int = DEFAULT_CHUNK_OVERLAP,
+) -> list[TextChunk]:
+    """Split text into overlapping token chunks."""
+    if chunk_tokens <= 0:
+        msg = "chunk_tokens must be positive"
+        raise ValueError(msg)
+    if overlap_tokens < 0 or overlap_tokens >= chunk_tokens:
+        msg = "overlap_tokens must be non-negative and smaller than chunk_tokens"
+        raise ValueError(msg)
+
+    encoding = tiktoken.get_encoding("cl100k_base")
+    tokens = encoding.encode(text)
+    if not tokens:
+        return []
+
+    chunks: list[TextChunk] = []
+    step = chunk_tokens - overlap_tokens
+    for start in range(0, len(tokens), step):
+        chunk = tokens[start : start + chunk_tokens]
+        if not chunk:
+            continue
+        chunks.append(
+            TextChunk(
+                text=encoding.decode(chunk).strip(),
+                token_start=start,
+                token_count=len(chunk),
+            )
+        )
+        if start + chunk_tokens >= len(tokens):
+            break
+    return [chunk for chunk in chunks if chunk.text]
+
+
+def ingest_configured_paths(session: Session, config: EbookSearchConfig) -> int:
+    """Ingest every EPUB found under configured library paths."""
+    count = 0
+    for library_path in config.library_paths:
+        path = Path(library_path).expanduser()
+        logger.info("ebook_ingest_path_start path=%s", path)
+        if path.is_file() and path.suffix.lower() == ".epub":
+            count += int(ingest_file(session, path))
+        elif path.is_dir():
+            for epub_path in sorted(path.rglob("*.epub")):
+                count += int(ingest_file(session, epub_path))
+        else:
+            logger.warning("ebook_ingest_path_missing path=%s", path)
+    logger.info("ebook_ingest_paths_complete changed_files=%s configured_paths=%s", count, len(config.library_paths))
+    return count
+
+
+def ingest_file(session: Session, path: Path) -> bool:
+    """Ingest one EPUB file. Return True when the database changed."""
+    resolved_path = path.expanduser().resolve()
+    logger.info("ebook_ingest_file_start path=%s", resolved_path)
+    file_hash = sha256_file(resolved_path)
+    existing = find_existing_source(session, resolved_path, file_hash)
+    if existing is not None and existing.file_sha256 == file_hash:
+        stat = resolved_path.stat()
+        existing.file_path = str(resolved_path)
+        existing.file_mtime = datetime.fromtimestamp(stat.st_mtime, tz=UTC)
+        existing.file_size = stat.st_size
+        session.flush()
+        logger.info("ebook_ingest_file_unchanged source_id=%s path=%s", existing.id, resolved_path)
+        return False
+    if existing is not None:
+        logger.info("ebook_ingest_file_replacing source_id=%s path=%s", existing.id, resolved_path)
+        session.delete(existing)
+        session.flush()
+
+    stat = resolved_path.stat()
+    parsed = parse_epub(resolved_path)
+    source = EbookSource(
+        title=parsed.title,
+        author=parsed.author,
+        language=parsed.language,
+        publisher=parsed.publisher,
+        identifier=parsed.identifier,
+        file_path=str(resolved_path),
+        file_sha256=file_hash,
+        file_mtime=datetime.fromtimestamp(stat.st_mtime, tz=UTC),
+        file_size=stat.st_size,
+    )
+    session.add(source)
+    session.flush()
+
+    chunk_index = 0
+    for spine_index, parsed_chapter in enumerate(parsed.chapters):
+        chapter = EbookChapter(
+            source_id=source.id,
+            spine_index=spine_index,
+            title=parsed_chapter.title,
+            href=parsed_chapter.href,
+        )
+        session.add(chapter)
+        session.flush()
+        chunk_index = add_chapter_chunks(session, source, chapter, parsed_chapter, chunk_index)
+
+    session.flush()
+    logger.info(
+        "ebook_ingest_file_complete source_id=%s path=%s chapters=%s chunks=%s",
+        source.id,
+        resolved_path,
+        len(parsed.chapters),
+        chunk_index,
+    )
+    return True
+
+
+def find_existing_source(session: Session, path: Path, file_hash: str) -> EbookSource | None:
+    """Find an existing source by canonical path or file hash."""
+    return session.scalar(
+        select(EbookSource).where(or_(EbookSource.file_path == str(path), EbookSource.file_sha256 == file_hash))
+    )
+
+
+def add_chapter_chunks(
+    session: Session,
+    source: EbookSource,
+    chapter: EbookChapter,
+    parsed_chapter: ParsedChapter,
+    chunk_index: int,
+) -> int:
+    """Add chunk rows for one parsed chapter and return the next chunk index."""
+    page_label = parsed_chapter.page_labels[0] if parsed_chapter.page_labels else None
+    for text_chunk in chunk_text(parsed_chapter.text):
+        session.add(
+            EbookChunk(
+                source_id=source.id,
+                chapter_id=chapter.id,
+                chunk_index=chunk_index,
+                text=text_chunk.text,
+                token_start=text_chunk.token_start,
+                token_count=text_chunk.token_count,
+                page_label=page_label,
+                content_sha256=hashlib.sha256(text_chunk.text.encode()).hexdigest(),
+                search_text=f"{source.title} {source.author or ''} {chapter.title or ''} {text_chunk.text}",
+            )
+        )
+        chunk_index += 1
+    return chunk_index
+
+
+def sha256_file(path: Path) -> str:
+    """Calculate the SHA-256 digest for a file."""
+    digest = hashlib.sha256()
+    with path.open("rb") as file:
+        for block in iter(lambda: file.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()

python/ebook_search/llm_interface.py

@@ -0,0 +1,143 @@
+"""LLM provider HTTP adapters."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import httpx
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from python.ebook_search.config import EbookSearchConfig, RerankConfig
+
+logger = logging.getLogger(__name__)
+
+
+def auth_headers(api_key: str) -> dict[str, str]:
+    """Build authorization headers when an API key is configured."""
+    if api_key == "not-needed":
+        return {}
+    return {"Authorization": f"Bearer {api_key}"}
+
+
+def request_embeddings(texts: Sequence[str], config: EbookSearchConfig) -> list[list[float]]:
+    """Request embeddings from the configured OpenAI-compatible endpoint."""
+    try:
+        response = httpx.post(
+            f"{config.embedding_base_url.rstrip('/')}/embeddings",
+            headers=auth_headers(config.embedding_api_key),
+            json={"model": config.embedding_model, "input": list(texts)},
+            timeout=60,
+        )
+        response.raise_for_status()
+        return embedding_vectors_from_response(response.json())
+    except (httpx.HTTPError, ValueError, KeyError, TypeError) as error:
+        logger.exception(
+            "ebook_embed_request_failed base_url=%s model=%s count=%s",
+            config.embedding_base_url,
+            config.embedding_model,
+            len(texts),
+        )
+        msg = f"Embedding request failed. base_url={config.embedding_base_url} model={config.embedding_model}"
+        raise RuntimeError(msg) from error
+
+
+def embedding_vectors_from_response(body: object) -> list[list[float]]:
+    """Extract embedding vectors from an OpenAI-compatible embedding response."""
+    if not isinstance(body, dict):
+        msg = "Embedding response is not an object"
+        raise TypeError(msg)
+
+    data = body["data"]
+    if not isinstance(data, list):
+        msg = "Embedding response data is not a list"
+        raise TypeError(msg)
+
+    vectors: list[list[float]] = []
+    for item in data:
+        if not isinstance(item, dict):
+            msg = "Embedding item is not an object"
+            raise TypeError(msg)
+        embedding = item["embedding"]
+        if not isinstance(embedding, list):
+            msg = "Embedding value is not a list"
+            raise TypeError(msg)
+        vectors.append([float(value) for value in embedding])
+    return vectors
+
+
+def request_rerank(
+    query: str,
+    documents: Sequence[str],
+    config: RerankConfig,
+) -> object | None:
+    """Request rerank scores from the configured vLLM endpoint."""
+    payload = {
+        "model": config.model,
+        "query": query,
+        "documents": list(documents),
+    }
+    response = httpx.post(
+        f"{config.base_url.rstrip('/')}/rerank",
+        json=payload,
+        timeout=config.timeout_seconds,
+    )
+    response.raise_for_status()
+    try:
+        return response.json()
+    except ValueError:
+        logger.debug("ebook_rerank_response_invalid_json", extra={"response": response.text})
+        return None
+
+
+def request_chat_completion(
+    config: EbookSearchConfig,
+    messages: Sequence[dict[str, str]],
+) -> str:
+    """Request a chat completion from the configured OpenAI-compatible endpoint."""
+    try:
+        response = httpx.post(
+            f"{config.vllm_base_url.rstrip('/')}/chat/completions",
+            headers=auth_headers(config.vllm_api_key),
+            json={
+                "model": config.chat_model,
+                "messages": list(messages),
+                "temperature": 0,
+            },
+            timeout=60,
+        )
+        response.raise_for_status()
+        return chat_content_from_response(response.json())
+    except (httpx.HTTPError, ValueError, KeyError, TypeError) as error:
+        msg = f"Chat request failed. base_url={config.vllm_base_url} model={config.chat_model}"
+        raise RuntimeError(msg) from error
+
+
+def chat_content_from_response(body: object) -> str:
+    """Extract text content from an OpenAI-compatible chat response."""
+    if not isinstance(body, dict):
+        msg = "Chat response is not an object"
+        raise TypeError(msg)
+
+    choices = body["choices"]
+    if not isinstance(choices, list) or not choices:
+        msg = "Chat response has no choices"
+        raise ValueError(msg)
+
+    first = choices[0]
+    if not isinstance(first, dict):
+        msg = "Chat choice is not an object"
+        raise TypeError(msg)
+
+    message = first["message"]
+    if not isinstance(message, dict):
+        msg = "Chat message is not an object"
+        raise TypeError(msg)
+
+    content = message.get("content") or ""
+    if not isinstance(content, str):
+        msg = "Chat content is not text"
+        raise TypeError(msg)
+    return content

python/ebook_search/rerank.py

@@ -0,0 +1,129 @@
+"""vLLM-backed optional reranking."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from python.ebook_search.llm_interface import request_rerank
+
+if TYPE_CHECKING:
+    from python.ebook_search.config import RerankConfig
+    from python.ebook_search.search import SearchResult
+
+logger = logging.getLogger(__name__)
+RERANK_SCORE_WEIGHT = 0.7
+HYBRID_SCORE_WEIGHT = 0.3
+
+
+@dataclass(frozen=True)
+class RerankResult:
+    """A relevance score for one candidate chunk."""
+
+    chunk_id: int
+    score: float
+
+
+def rerank_chunks(query: str, candidates: list[SearchResult], config: RerankConfig) -> list[SearchResult]:
+    """Rerank candidates with a vLLM rerank endpoint."""
+    if not candidates:
+        return []
+
+    logger.info(
+        "ebook_rerank_request_start base_url=%s model=%s candidates=%s",
+        config.base_url,
+        config.model,
+        len(candidates),
+    )
+    scores = score_candidates(query, candidates, config)
+    results = sorted(
+        (
+            replace(
+                result,
+                score=final_rerank_score(result, scores[result.chunk_id].score, candidates),
+                rerank_score=scores[result.chunk_id].score,
+            )
+            for result in candidates
+        ),
+        key=lambda result: result.score,
+        reverse=True,
+    )
+    logger.info(
+        "ebook_rerank_request_complete base_url=%s model=%s candidates=%s",
+        config.base_url,
+        config.model,
+        len(results),
+    )
+    return results
+
+
+def score_candidates(
+    query: str,
+    candidates: list[SearchResult],
+    config: RerankConfig,
+) -> dict[int, RerankResult]:
+    """Score candidate chunks with the configured rerank API."""
+    body = request_rerank(query, [candidate.text for candidate in candidates], config)
+    if body is None:
+        return zero_rerank_scores(candidates)
+
+    scores = parse_vllm_scores(body, candidates)
+    for result in scores.values():
+        logger.debug("ebook_rerank_candidate_scored chunk_id=%s score=%s", result.chunk_id, result.score)
+    return scores
+
+
+def parse_vllm_scores(body: object, candidates: list[SearchResult]) -> dict[int, RerankResult]:
+    """Parse vLLM rerank scores into chunk-id keyed results."""
+    if not isinstance(body, dict):
+        logger.debug("ebook_rerank_response_not_object", extra={"response": body})
+        return zero_rerank_scores(candidates)
+
+    results = body.get("results") or body.get("data")
+    if not isinstance(results, list):
+        logger.debug("ebook_rerank_response_missing_results", extra={"response": body})
+        return zero_rerank_scores(candidates)
+
+    scores = zero_rerank_scores(candidates)
+    for item in results:
+        if not isinstance(item, dict):
+            continue
+        index = item.get("index")
+        score = item.get("relevance_score", item.get("score"))
+        if not isinstance(index, int) or index < 0 or index >= len(candidates):
+            continue
+        if not isinstance(score, int | float):
+            continue
+        chunk_id = candidates[index].chunk_id
+        scores[chunk_id] = RerankResult(chunk_id=chunk_id, score=clamp_score(float(score)))
+    return scores
+
+
+def zero_rerank_scores(candidates: list[SearchResult]) -> dict[int, RerankResult]:
+    """Return zero relevance scores for all candidate chunks."""
+    return {candidate.chunk_id: RerankResult(chunk_id=candidate.chunk_id, score=0.0) for candidate in candidates}
+
+
+def clamp_score(score: float) -> float:
+    """Clamp a rerank score into the supported 0.0 to 1.0 range."""
+    return min(max(score, 0.0), 1.0)
+
+
+def final_rerank_score(result: SearchResult, rerank_score: float, candidates: list[SearchResult]) -> float:
+    """Combine rerank relevance with normalized hybrid retrieval evidence."""
+    return (RERANK_SCORE_WEIGHT * rerank_score) + (HYBRID_SCORE_WEIGHT * normalized_hybrid_score(result, candidates))
+
+
+def normalized_hybrid_score(result: SearchResult, candidates: list[SearchResult]) -> float:
+    """Normalize a candidate hybrid score against the rerank candidate set."""
+    hybrid_scores = [
+        candidate.fused_score if candidate.fused_score is not None else candidate.score for candidate in candidates
+    ]
+    low = min(hybrid_scores)
+    high = max(hybrid_scores)
+    if high == low:
+        return 1.0
+
+    score = result.fused_score if result.fused_score is not None else result.score
+    return (score - low) / (high - low)

python/ebook_search/search.py

@@ -0,0 +1,377 @@
+"""Hybrid search orchestration."""
+
+from __future__ import annotations
+
+import logging
+import re
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import literal, select
+from sqlalchemy.orm import Session
+
+from python.ebook_search.bm25_corpus import (
+    load_bm25_corpus,
+    score_bm25_corpus,
+)
+from python.ebook_search.embeddings import MODEL_DIMENSIONS, embed_query, get_embedding_table
+from python.ebook_search.rerank import rerank_chunks
+from python.ebook_search.timing import RuntimeStep, timed_result
+from python.orm.richie import (
+    EbookChapter,
+    EbookChunk,
+    EbookEmbeddingModel,
+    EbookSource,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from sqlalchemy.engine import Engine
+
+    from python.ebook_search.config import EbookSearchConfig
+
+logger = logging.getLogger(__name__)
+BM25_CANDIDATE_LIMIT = 120
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    """One source chunk returned by search."""
+
+    chunk_id: int
+    text: str
+    source_title: str
+    score: float = 0.0
+    vector_score: float | None = None
+    bm25_score: float | None = None
+    fused_score: float | None = None
+    rerank_score: float | None = None
+    source_author: str | None = None
+    chapter_title: str | None = None
+    page_label: str | None = None
+    rank_source: str = "Hybrid"
+
+
+@dataclass(frozen=True)
+class SearchResponse:
+    """Search output for the UI."""
+
+    query: str
+    results: list[SearchResult]
+    rank_label: str
+    timings: tuple[RuntimeStep, ...] = ()
+
+    @property
+    def total_runtime_ms(self) -> float:
+        """Return total measured runtime for the response."""
+        return sum(step.duration_ms for step in self.timings if step.counts_toward_total)
+
+
+@dataclass(frozen=True)
+class RetrievalResponse:
+    """Parallel retrieval output for vector and BM25 candidates."""
+
+    vector_results: list[SearchResult]
+    lexical_results: list[SearchResult]
+    timings: tuple[RuntimeStep, ...]
+
+
+def search_ebooks(
+    engine: Engine,
+    query: str,
+    config: EbookSearchConfig,
+    *,
+    rerank: bool = False,
+) -> SearchResponse:
+    """Run hybrid vector/BM25 search and optional reranking."""
+    if not query.strip():
+        logger.info("ebook_search_empty_query")
+        return SearchResponse(query=query, results=[], rank_label="Hybrid")
+
+    logger.info("ebook_search_start query_length=%s rerank=%s", len(query), rerank)
+    timings: list[RuntimeStep] = []
+    bm25_query, timing = timed_result("BM25 query preparation", retrieval_query_from_text, query)
+    timings.append(timing)
+    retrieval, timing = timed_result(
+        "Hybrid retrieval",
+        parallel_retrieval,
+        engine,
+        query,
+        bm25_query,
+        config,
+    )
+    timings.extend(retrieval.timings)
+    timings.append(timing)
+    fused, timing = timed_result(
+        "Reciprocal rank fusion",
+        reciprocal_rank_fusion,
+        retrieval.vector_results,
+        retrieval.lexical_results,
+    )
+    timings.append(timing)
+    if config.rerank.enabled and rerank:
+        response, timing = timed_result("Rerank", apply_rerank, query, fused, config)
+    else:
+        response, timing = timed_result("Rerank skipped", skip_rerank, query, fused, config)
+    timings.append(timing)
+    response = replace(response, timings=tuple(timings))
+    logger.info(
+        "ebook_search_complete vector_candidates=%s lexical_candidates=%s "
+        "fused_candidates=%s returned=%s rank_label=%s runtime_ms=%.1f",
+        len(retrieval.vector_results),
+        len(retrieval.lexical_results),
+        len(fused),
+        len(response.results),
+        response.rank_label,
+        response.total_runtime_ms,
+    )
+    return response
+
+
+def parallel_retrieval(
+    engine: Engine,
+    vector_query: str,
+    bm25_query: str,
+    config: EbookSearchConfig,
+) -> RetrievalResponse:
+    """Run vector and BM25 candidate retrieval concurrently with separate database sessions."""
+    with ThreadPoolExecutor(max_workers=2, thread_name_prefix="ebook-search") as executor:
+        vector_future = executor.submit(
+            timed_result,
+            "Embedding + vector search",
+            vector_candidates,
+            engine,
+            vector_query,
+            config,
+        )
+        bm25_future = executor.submit(
+            timed_result,
+            "BM25 search",
+            bm25_candidates,
+            bm25_query,
+            config,
+        )
+        vector_results, vector_timing = vector_future.result()
+        lexical_results, lexical_timing = bm25_future.result()
+
+    logger.info(
+        "ebook_parallel_retrieval_complete vector_candidates=%s lexical_candidates=%s",
+        len(vector_results),
+        len(lexical_results),
+    )
+    return RetrievalResponse(
+        vector_results=vector_results,
+        lexical_results=lexical_results,
+        timings=(
+            replace(vector_timing, counts_toward_total=False),
+            replace(lexical_timing, counts_toward_total=False),
+        ),
+    )
+
+
+def skip_rerank(
+    query: str,
+    candidates: list[SearchResult],
+    config: EbookSearchConfig,
+) -> SearchResponse:
+    """Return fused hybrid results without reranking."""
+    logger.info("ebook_rerank_skipped candidates=%s", len(candidates))
+    return SearchResponse(query=query, results=candidates[: config.top_k], rank_label="Hybrid")
+
+
+def apply_rerank(
+    query: str,
+    candidates: list[SearchResult],
+    config: EbookSearchConfig,
+) -> SearchResponse:
+    """Rerank already-fused hybrid candidates."""
+    reranked = rerank_chunks(query, candidates[: config.rerank.candidates], config.rerank)
+    logger.info(
+        "ebook_rerank_complete input_candidates=%s returned=%s",
+        min(len(candidates), config.rerank.candidates),
+        len(reranked),
+    )
+    return SearchResponse(
+        query=query,
+        results=[replace(result, rank_source="Hybrid + rerank") for result in reranked[: config.top_k]],
+        rank_label="Hybrid + rerank",
+    )
+
+
+def vector_candidates(engine: Engine, query: str, config: EbookSearchConfig) -> list[SearchResult]:
+    """Return pgvector cosine candidates for a natural-language query."""
+    with Session(engine) as session:
+        model = session.scalar(select(EbookEmbeddingModel).where(EbookEmbeddingModel.name == config.embedding_model))
+        if model is None:
+            msg = f"Embedding model is not registered: {config.embedding_model}"
+            raise ValueError(msg)
+
+        expected_dimension = MODEL_DIMENSIONS[config.embedding_model]
+        if model.dimension != expected_dimension:
+            msg = f"Model row dimension {model.dimension} does not match configured dimension {expected_dimension}"
+            raise ValueError(msg)
+
+        embedding = embed_query(query, config)
+        limit = max(config.rerank.candidates, config.top_k) * 4
+        embedding_table = get_embedding_table(model.dimension)
+
+        embedding_param = literal(embedding, type_=Vector(model.dimension))
+        distance = embedding_table.embedding.op("<=>")(embedding_param)
+        score = (literal(1.0) - distance).label("score")
+        statement = (
+            select(
+                EbookChunk.id.label("chunk_id"),
+                EbookChunk.text.label("text"),
+                EbookSource.title.label("source_title"),
+                EbookSource.author.label("source_author"),
+                EbookChapter.title.label("chapter_title"),
+                EbookChunk.page_label.label("page_label"),
+                score,
+            )
+            .select_from(embedding_table)
+            .join(EbookChunk, EbookChunk.id == embedding_table.chunk_id)
+            .join(EbookSource, EbookSource.id == EbookChunk.source_id)
+            .outerjoin(EbookChapter, EbookChapter.id == EbookChunk.chapter_id)
+            .where(embedding_table.model_id == model.id)
+            .order_by(distance)
+            .limit(limit)
+        )
+        rows = session.execute(statement).mappings()
+        results = [search_result_from_row(row) for row in rows]
+        logger.info(
+            "ebook_vector_search_complete model=%s dimension=%s candidates=%s",
+            config.embedding_model,
+            model.dimension,
+            len(results),
+        )
+        return results
+
+
+def bm25_candidates(query: str, config: EbookSearchConfig) -> list[SearchResult]:
+    """Return BM25-ranked lexical candidates using the persisted corpus."""
+    corpus = load_bm25_corpus(config)
+    if not corpus.records:
+        logger.info("ebook_bm25_search_complete corpus=0 candidates=0")
+        return []
+
+    scored_records = score_bm25_corpus(query, corpus, limit=BM25_CANDIDATE_LIMIT)
+    results = [
+        replace(search_result_from_row(record), score=score, vector_score=None, bm25_score=score)
+        for record, score in scored_records
+    ]
+
+    max_score = results[0].bm25_score if results else 0.0
+    logger.info(
+        "ebook_bm25_search_complete corpus=%s candidates=%s max_score=%.6f",
+        len(corpus.records),
+        len(results),
+        max_score,
+    )
+    return results
+
+
+def reciprocal_rank_fusion(
+    vector_results: list[SearchResult],
+    lexical_results: list[SearchResult],
+    *,
+    rank_constant: int = 60,
+) -> list[SearchResult]:
+    """Fuse vector and lexical rankings with Reciprocal Rank Fusion."""
+    by_chunk: dict[int, SearchResult] = {}
+    scores: dict[int, float] = {}
+    vector_scores: dict[int, float] = {}
+    bm25_scores: dict[int, float] = {}
+
+    for rank, result in enumerate(vector_results, start=1):
+        by_chunk.setdefault(result.chunk_id, result)
+        vector_scores[result.chunk_id] = result.vector_score if result.vector_score is not None else result.score
+        scores[result.chunk_id] = scores.get(result.chunk_id, 0.0) + (1 / (rank_constant + rank))
+
+    for rank, result in enumerate(lexical_results, start=1):
+        by_chunk.setdefault(result.chunk_id, result)
+        bm25_scores[result.chunk_id] = result.bm25_score if result.bm25_score is not None else result.score
+        scores[result.chunk_id] = scores.get(result.chunk_id, 0.0) + (1 / (rank_constant + rank))
+
+    return sorted(
+        (
+            replace(
+                result,
+                score=scores[result.chunk_id],
+                vector_score=vector_scores.get(result.chunk_id),
+                bm25_score=bm25_scores.get(result.chunk_id),
+                fused_score=scores[result.chunk_id],
+                rank_source="Hybrid",
+            )
+            for result in by_chunk.values()
+        ),
+        key=lambda result: result.score,
+        reverse=True,
+    )
+
+
+def search_result_from_row(row: Mapping[str, object]) -> SearchResult:
+    """Convert a database row mapping into a search result."""
+    return SearchResult(
+        chunk_id=int(row["chunk_id"]),
+        text=str(row["text"]),
+        source_title=str(row["source_title"]),
+        source_author=optional_str(row["source_author"]),
+        chapter_title=optional_str(row["chapter_title"]),
+        page_label=optional_str(row["page_label"]),
+        score=float(row["score"]) if "score" in row else 0.0,
+        vector_score=float(row["score"]) if "score" in row else None,
+    )
+
+
+def optional_str(value: object) -> str | None:
+    """Convert nullable database values to optional strings."""
+    if value is None:
+        return None
+    return str(value)
+
+
+TOKEN_RE = re.compile(r"[A-Za-z0-9_]+")
+
+
+def tokens(text_value: str) -> list[str]:
+    """Extract tokens from a text value.
+
+    This is a simple approximation of the tokenization used by PostgreSQL's full-text search,
+    which is sufficient for BM25 candidate retrieval. It lowercases tokens and includes alphanumeric characters and
+    underscores.
+    """
+    return [match.group(0).lower() for match in TOKEN_RE.finditer(text_value)]
+
+
+QUERY_STOP_WORDS = {
+    "a",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "does",
+    "for",
+    "in",
+    "is",
+    "of",
+    "the",
+    "to",
+    "what",
+    "when",
+    "where",
+    "which",
+    "who",
+    "why",
+}
+
+
+def retrieval_query_from_text(query: str) -> str:
+    """Remove generic question words while preserving entity and series terms."""
+    keywords = [token for token in tokens(query) if token not in QUERY_STOP_WORDS]
+    if not keywords:
+        return query
+    return " ".join(keywords)

python/ebook_search/timing.py

@@ -0,0 +1,36 @@
+"""Runtime timing helpers for EPUB search."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from time import perf_counter
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@dataclass(frozen=True)
+class RuntimeStep:
+    """Elapsed runtime for one named search step."""
+
+    name: str
+    duration_ms: float
+    counts_toward_total: bool = True
+
+
+def runtime_step_from_start(name: str, start_seconds: float) -> RuntimeStep:
+    """Create a runtime step from a prior perf_counter timestamp."""
+    return RuntimeStep(name=name, duration_ms=(perf_counter() - start_seconds) * 1000)
+
+
+def timed_result[T, **P](
+    name: str,
+    operation: Callable[P, T],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> tuple[T, RuntimeStep]:
+    """Run an operation and return its result plus elapsed runtime."""
+    start_seconds = perf_counter()
+    result = operation(*args, **kwargs)
+    return result, runtime_step_from_start(name, start_seconds)

python/fastapi_tools/__init__.py

@@ -0,0 +1,6 @@
+"""Reusable FastAPI tools."""
+
+from python.fastapi_tools.db import DbSession, get_db
+from python.fastapi_tools.zstd_middleware import ZstdMiddleware
+
+__all__ = ["DbSession", "ZstdMiddleware", "get_db"]

python/fastapi_tools/zstd_middleware.py

@@ -1,4 +1,4 @@
-"""Middleware for the FastAPI application."""
+"""Zstd response compression middleware."""
 
 from compression import zstd
 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint

python/gitea.py

@@ -0,0 +1,347 @@
+"""Small Gitea API client for repository automation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Self
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_PAGE_SIZE = 100
+EXPECTED_NO_CONTENT = 204
+EXPECTED_CREATED = 201
+EXPECTED_OK = 200
+
+
+@dataclass(frozen=True)
+class CreatedIssue:
+    """Issue data returned by Gitea."""
+
+    number: int | None
+    html_url: str | None
+    title: str
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    """Pull request data returned by Gitea."""
+
+    number: int
+    title: str
+    html_url: str | None
+    labels: tuple[str, ...]
+    head_branch: str | None
+    base_branch: str | None
+
+
+@dataclass(frozen=True)
+class WorkflowJob:
+    """Workflow job data returned by Gitea Actions."""
+
+    id: int
+    name: str
+    run_id: int | None
+    status: str | None
+    conclusion: str | None
+
+
+class GiteaError(RuntimeError):
+    """Raised when Gitea rejects an API request."""
+
+
+def split_repo_name(repo: str) -> tuple[str, str]:
+    """Split an owner/repo string into its parts."""
+    owner, separator, repo_name = repo.partition("/")
+    if not separator or not owner or not repo_name:
+        msg = f"Invalid repository name: {repo}"
+        raise ValueError(msg)
+    return owner, repo_name
+
+
+class GiteaClient:
+    """HTTP client for the subset of Gitea APIs used in this repository."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str,
+        timeout: int = 30,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        """Initialize the Gitea client."""
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"Authorization": f"token {token}"},
+            transport=transport,
+        )
+
+    def create_issue(
+        self,
+        *,
+        owner: str,
+        repo: str,
+        title: str,
+        body: str,
+        labels: list[int] | None = None,
+    ) -> CreatedIssue:
+        """Create a Gitea issue."""
+        payload: dict[str, object] = {"title": title, "body": body, "labels": labels or []}
+        response = self._request(
+            "POST",
+            f"/api/v1/repos/{owner}/{repo}/issues",
+            expected_statuses={EXPECTED_CREATED},
+            json=payload,
+        )
+        data = response.json()
+        return CreatedIssue(
+            number=_optional_int(data.get("number")),
+            html_url=_optional_str(data.get("html_url")),
+            title=str(data.get("title", title)),
+        )
+
+    def resolve_label_ids(self, *, owner: str, repo: str, labels: list[str]) -> list[int]:
+        """Resolve label names to Gitea label IDs."""
+        if not labels:
+            return []
+
+        available_labels: dict[str, int] = {}
+        page = 1
+        while True:
+            response = self._request(
+                "GET",
+                f"/api/v1/repos/{owner}/{repo}/labels",
+                params={"page": page, "limit": DEFAULT_PAGE_SIZE},
+            )
+            batch = response.json()
+            if not batch:
+                break
+            for label in batch:
+                label_name = str(label.get("name", ""))
+                label_id = _optional_int(label.get("id"))
+                if label_name and label_id is not None:
+                    available_labels[label_name] = label_id
+            if len(batch) < DEFAULT_PAGE_SIZE:
+                break
+            page += 1
+
+        missing = [label for label in labels if label not in available_labels]
+        if missing:
+            missing_names = ", ".join(sorted(missing))
+            msg = f"Missing Gitea labels: {missing_names}"
+            raise GiteaError(msg)
+
+        return [available_labels[label] for label in labels]
+
+    def list_open_pull_requests(
+        self,
+        *,
+        owner: str,
+        repo: str,
+        labels: list[str] | None = None,
+        head: str | None = None,
+    ) -> list[PullRequest]:
+        """List open pull requests for a repository."""
+        expected_labels = set(labels or [])
+        pull_requests: list[PullRequest] = []
+        page = 1
+        while True:
+            response = self._request(
+                "GET",
+                f"/api/v1/repos/{owner}/{repo}/pulls",
+                params={"state": "open", "page": page, "limit": DEFAULT_PAGE_SIZE},
+            )
+            batch = response.json()
+            if not batch:
+                break
+
+            for item in batch:
+                pull_request = _pull_request_from_api(item)
+                if head and pull_request.head_branch != head:
+                    continue
+                if expected_labels and not expected_labels.issubset(set(pull_request.labels)):
+                    continue
+                pull_requests.append(pull_request)
+
+            if len(batch) < DEFAULT_PAGE_SIZE:
+                break
+            page += 1
+
+        return pull_requests
+
+    def create_pull_request(
+        self,
+        *,
+        owner: str,
+        repo: str,
+        title: str,
+        body: str,
+        head: str,
+        base: str,
+        labels: list[str] | None = None,
+    ) -> PullRequest:
+        """Create a pull request."""
+        payload: dict[str, object] = {
+            "title": title,
+            "body": body,
+            "head": head,
+            "base": base,
+        }
+        if labels:
+            payload["labels"] = self.resolve_label_ids(owner=owner, repo=repo, labels=labels)
+
+        response = self._request(
+            "POST",
+            f"/api/v1/repos/{owner}/{repo}/pulls",
+            expected_statuses={EXPECTED_CREATED},
+            json=payload,
+        )
+        return _pull_request_from_api(response.json())
+
+    def merge_pull_request(
+        self,
+        *,
+        owner: str,
+        repo: str,
+        number: int,
+        merge_method: str = "rebase",
+        head_commit_id: str | None = None,
+        delete_branch_after_merge: bool = False,
+    ) -> None:
+        """Merge a pull request."""
+        payload: dict[str, object] = {
+            "Do": merge_method,
+            "delete_branch_after_merge": delete_branch_after_merge,
+        }
+        if head_commit_id:
+            payload["head_commit_id"] = head_commit_id
+
+        self._request(
+            "POST",
+            f"/api/v1/repos/{owner}/{repo}/pulls/{number}/merge",
+            json=payload,
+        )
+
+    def dispatch_workflow(self, *, owner: str, repo: str, workflow_id: str, ref: str) -> None:
+        """Trigger a workflow_dispatch run."""
+        workflow_path = quote(workflow_id, safe="")
+        self._request(
+            "POST",
+            f"/api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_path}/dispatches",
+            expected_statuses={EXPECTED_OK, EXPECTED_NO_CONTENT},
+            json={"ref": ref},
+        )
+
+    def list_run_jobs(self, *, owner: str, repo: str, run_id: str | int) -> list[WorkflowJob]:
+        """List workflow jobs for a specific run."""
+        jobs: list[WorkflowJob] = []
+        page = 1
+        while True:
+            response = self._request(
+                "GET",
+                f"/api/v1/repos/{owner}/{repo}/actions/jobs",
+                params={"page": page, "limit": DEFAULT_PAGE_SIZE},
+            )
+            payload = response.json()
+            batch = payload.get("jobs", [])
+            if not batch:
+                break
+
+            for item in batch:
+                if str(item.get("run_id")) != str(run_id):
+                    continue
+                jobs.append(_workflow_job_from_api(item))
+
+            if len(batch) < DEFAULT_PAGE_SIZE:
+                break
+            page += 1
+
+        return jobs
+
+    def download_job_logs(self, *, owner: str, repo: str, job_id: int) -> str:
+        """Download logs for a workflow job."""
+        response = self._request(
+            "GET",
+            f"/api/v1/repos/{owner}/{repo}/actions/jobs/{job_id}/logs",
+        )
+        return response.text
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Close the HTTP client."""
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        expected_statuses: set[int] | None = None,
+        **kwargs: object,
+    ) -> httpx.Response:
+        """Send an HTTP request and validate the response status."""
+        response = self._client.request(method, path, **kwargs)
+        statuses = expected_statuses or {EXPECTED_OK}
+        if response.status_code not in statuses:
+            msg = f"Gitea request failed ({response.status_code}): {response.text}"
+            raise GiteaError(msg)
+        return response
+
+
+def _pull_request_from_api(data: dict[str, object]) -> PullRequest:
+    """Convert Gitea API pull-request data into a dataclass."""
+    number = _optional_int(data.get("number")) or _optional_int(data.get("index"))
+    if number is None:
+        msg = "Gitea pull request payload is missing a number"
+        raise GiteaError(msg)
+
+    labels = tuple(str(label.get("name", "")) for label in data.get("labels", []))
+    head = data.get("head", {})
+    base = data.get("base", {})
+    return PullRequest(
+        number=number,
+        title=str(data.get("title", "")),
+        html_url=_optional_str(data.get("html_url")),
+        labels=tuple(label for label in labels if label),
+        head_branch=_optional_str(head.get("ref")) or _optional_str(data.get("head_branch")),
+        base_branch=_optional_str(base.get("ref")) or _optional_str(data.get("base_branch")),
+    )
+
+
+def _workflow_job_from_api(data: dict[str, object]) -> WorkflowJob:
+    """Convert Gitea API workflow-job data into a dataclass."""
+    job_id = _optional_int(data.get("id"))
+    if job_id is None:
+        msg = "Gitea workflow job payload is missing an ID"
+        raise GiteaError(msg)
+
+    return WorkflowJob(
+        id=job_id,
+        name=str(data.get("name", "")),
+        run_id=_optional_int(data.get("run_id")),
+        status=_optional_str(data.get("status")),
+        conclusion=_optional_str(data.get("conclusion")),
+    )
+
+
+def _optional_int(value: object) -> int | None:
+    """Convert an API value to an integer when present."""
+    if value is None:
+        return None
+    return int(value)
+
+
+def _optional_str(value: object) -> str | None:
+    """Convert an API value to a string when present."""
+    if value is None:
+        return None
+    return str(value)

python/gitea_flake_lock.py

@@ -0,0 +1,148 @@
+"""Automation helpers for flake.lock pull requests on Gitea."""
+
+from __future__ import annotations
+
+import subprocess
+from os import getenv
+from typing import Annotated
+
+import typer
+
+from python.gitea import GiteaClient, PullRequest, split_repo_name
+
+DEFAULT_BASE_BRANCH = "main"
+DEFAULT_BRANCH = "automation/update-flake-lock"
+DEFAULT_GITEA_URL = "https://gitea.tmmworkshop.com"
+PR_LABELS = ["dependencies", "automated", "flake_lock_update"]
+PR_CHECK_WORKFLOWS = ["build_systems.yml", "treefmt.yml", "pytest.yml"]
+PR_TITLE = "Update flake.lock"
+PR_BODY = "Automated flake.lock update."
+
+app = typer.Typer(add_completion=False)
+
+
+def run_cmd(cmd: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess command."""
+    return subprocess.run(cmd, capture_output=True, text=True, check=check)
+
+
+def ensure_flake_lock_pull_request(
+    client: GiteaClient,
+    *,
+    owner: str,
+    repo: str,
+    branch: str,
+    base: str,
+) -> PullRequest:
+    """Return an existing flake.lock PR for the branch or create one."""
+    pull_requests = client.list_open_pull_requests(owner=owner, repo=repo, head=branch)
+    if pull_requests:
+        return pull_requests[0]
+
+    return client.create_pull_request(
+        owner=owner,
+        repo=repo,
+        title=PR_TITLE,
+        body=PR_BODY,
+        head=branch,
+        base=base,
+        labels=PR_LABELS,
+    )
+
+
+def find_flake_lock_pull_request(client: GiteaClient, *, owner: str, repo: str) -> PullRequest | None:
+    """Find the first open flake.lock pull request."""
+    pull_requests = client.list_open_pull_requests(owner=owner, repo=repo, labels=["flake_lock_update"])
+    if not pull_requests:
+        return None
+    return pull_requests[0]
+
+
+def dispatch_pull_request_checks(client: GiteaClient, *, owner: str, repo: str, branch: str) -> None:
+    """Dispatch the workflows that normally run for pull requests."""
+    for workflow in PR_CHECK_WORKFLOWS:
+        client.dispatch_workflow(owner=owner, repo=repo, workflow_id=workflow, ref=branch)
+
+
+def has_worktree_changes() -> bool:
+    """Return whether `flake.lock` has worktree changes."""
+    result = run_cmd(["git", "diff", "--quiet", "--", "flake.lock"], check=False)
+    return result.returncode != 0
+
+
+def commit_flake_lock_update(*, branch: str) -> None:
+    """Commit the updated lock file to the automation branch."""
+    run_cmd(["git", "config", "user.name", "gitea-actions[bot]"])
+    run_cmd(["git", "config", "user.email", "gitea-actions@tmmworkshop.com"])
+    run_cmd(["git", "checkout", "-B", branch])
+    run_cmd(["git", "add", "flake.lock"])
+    run_cmd(["git", "commit", "-m", "chore: update flake.lock"])
+
+
+def push_branch(*, branch: str) -> None:
+    """Push the automation branch to origin."""
+    run_cmd(["git", "push", "origin", f"HEAD:{branch}", "--force"])
+
+
+def _required_gitea_token() -> str:
+    """Read the required Gitea token from the environment."""
+    token = getenv("GITEA_TOKEN")
+    if token:
+        return token
+
+    msg = "GITEA_TOKEN environment variable is required"
+    raise RuntimeError(msg)
+
+
+@app.command()
+def update(
+    repo: Annotated[str, typer.Option("--repo", help="Gitea repository in owner/repo form")],
+    base: Annotated[str, typer.Option("--base", help="Base branch")] = DEFAULT_BASE_BRANCH,
+    branch: Annotated[str, typer.Option("--branch", help="Automation branch")] = DEFAULT_BRANCH,
+) -> None:
+    """Commit flake.lock changes and ensure a pull request exists."""
+    if not has_worktree_changes():
+        typer.echo("No flake.lock changes detected")
+        return
+
+    commit_flake_lock_update(branch=branch)
+    push_branch(branch=branch)
+
+    owner, repo_name = split_repo_name(repo)
+    with GiteaClient(
+        base_url=getenv("GITEA_URL", DEFAULT_GITEA_URL),
+        token=_required_gitea_token(),
+    ) as client:
+        pull_request = ensure_flake_lock_pull_request(
+            client,
+            owner=owner,
+            repo=repo_name,
+            branch=branch,
+            base=base,
+        )
+        # We can remove this if Gitea fixes the following issue:
+        # https://github.com/go-gitea/gitea/issues/33963
+        dispatch_pull_request_checks(client, owner=owner, repo=repo_name, branch=branch)
+    typer.echo(pull_request.html_url or f"Pull request #{pull_request.number}")
+
+
+@app.command()
+def merge(
+    repo: Annotated[str, typer.Option("--repo", help="Gitea repository in owner/repo form")],
+) -> None:
+    """Merge the first open flake.lock pull request."""
+    owner, repo_name = split_repo_name(repo)
+    with GiteaClient(
+        base_url=getenv("GITEA_URL", DEFAULT_GITEA_URL),
+        token=_required_gitea_token(),
+    ) as client:
+        pull_request = find_flake_lock_pull_request(client, owner=owner, repo=repo_name)
+        if not pull_request:
+            typer.echo("No open PR found with label flake_lock_update")
+            return
+        client.merge_pull_request(owner=owner, repo=repo_name, number=pull_request.number, merge_method="rebase")
+    typer.echo(f"Merged PR #{pull_request.number}")
+
+
+if __name__ == "__main__":
+    app()

python/orm/common.py

@@ -31,8 +31,24 @@ def get_connection_info(name: str) -> tuple[str, str, str, str, str | None]:
     return cast("tuple[str, str, str, str, str | None]", (database, host, port, username, password))
 
 
-def get_postgres_engine(*, name: str = "POSTGRES", pool_pre_ping: bool = True) -> Engine:
-    """Create a SQLAlchemy engine from environment variables."""
+def get_postgres_engine(
+    *,
+    name: str = "POSTGRES",
+    pool_pre_ping: bool = True,
+    vector_engine: bool = False,
+) -> Engine:
+    """Create a SQLAlchemy engine from environment variables.
+
+    Args:
+        name (str, optional): The name of the environment variable prefix. Defaults to "POSTGRES".
+        pool_pre_ping (bool, optional): Whether to ping the database before each connection. Defaults to True.
+        This fixes the issue of trying to use a conection that has timed out on the database side.
+        vector_engine (bool, optional): Whether to use the vector search schema. Defaults to False.
+        This updates the search path the incldued the vecore types and operators.
+
+    Returns:
+        Engine: The SQLAlchemy engine.
+    """
     database, host, port, username, password = get_connection_info(name)
 
     url = URL.create(
@@ -44,8 +60,14 @@ def get_postgres_engine(*, name: str = "POSTGRES", pool_pre_ping: bool = True) -
         database=database,
     )
 
+    connect_args = {}
+    # There more better way to do this is with separate PG account and a dedicated vector schema for the vector types
+    if vector_engine:
+        connect_args["options"] = "-csearch_path=main,public"
+
     return create_engine(
         url=url,
         pool_pre_ping=pool_pre_ping,
         pool_recycle=1800,
+        connect_args=connect_args,
     )

python/orm/richie/__init__.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from python.orm.richie.audiobook import Audiobook, AudiobookAuthor, AudiobookSeries
 from python.orm.richie.base import RichieBase, TableBase, TableBaseBig, TableBaseSmall
 from python.orm.richie.contact import (
     Contact,
@@ -10,11 +11,30 @@ from python.orm.richie.contact import (
     Need,
     RelationshipType,
 )
+from python.orm.richie.ebook import (
+    EbookChapter,
+    EbookChunk,
+    EbookChunkEmbedding1024,
+    EbookChunkEmbedding2560,
+    EbookChunkEmbedding4096,
+    EbookEmbeddingModel,
+    EbookSource,
+)
 
 __all__ = [
+    "Audiobook",
+    "AudiobookAuthor",
+    "AudiobookSeries",
     "Contact",
     "ContactNeed",
     "ContactRelationship",
+    "EbookChapter",
+    "EbookChunk",
+    "EbookChunkEmbedding1024",
+    "EbookChunkEmbedding2560",
+    "EbookChunkEmbedding4096",
+    "EbookEmbeddingModel",
+    "EbookSource",
     "Need",
     "RelationshipType",
     "RichieBase",

python/orm/richie/audiobook.py

@@ -0,0 +1,55 @@
+"""Audiobook catalog models."""
+
+from __future__ import annotations
+
+from sqlalchemy import ForeignKey, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from python.orm.richie.base import TableBase
+
+
+class AudiobookAuthor(TableBase):
+    """Canonical audiobook author."""
+
+    __tablename__ = "audiobook_author"
+    __table_args__ = (UniqueConstraint("name"),)
+
+    name: Mapped[str] = mapped_column(String, unique=True)
+
+    books: Mapped[list[Audiobook]] = relationship("Audiobook", back_populates="author")
+    series: Mapped[list[AudiobookSeries]] = relationship("AudiobookSeries", back_populates="author")
+
+
+class AudiobookSeries(TableBase):
+    """Canonical audiobook series."""
+
+    __tablename__ = "audiobook_series"
+    __table_args__ = (UniqueConstraint("author_id", "name"),)
+
+    name: Mapped[str] = mapped_column(String)
+    author_id: Mapped[int] = mapped_column(ForeignKey("main.audiobook_author.id", ondelete="CASCADE"))
+
+    author: Mapped[AudiobookAuthor] = relationship("AudiobookAuthor", back_populates="series")
+    books: Mapped[list[Audiobook]] = relationship("Audiobook", back_populates="series")
+
+
+class Audiobook(TableBase):
+    """Canonical audiobook title."""
+
+    __tablename__ = "audiobook"
+    __table_args__ = (
+        UniqueConstraint(
+            "author_id",
+            "series_id",
+            "title",
+            postgresql_nulls_not_distinct=True,
+        ),
+    )
+
+    title: Mapped[str] = mapped_column(String)
+    author_id: Mapped[int] = mapped_column(ForeignKey("main.audiobook_author.id", ondelete="CASCADE"))
+    series_id: Mapped[int | None] = mapped_column(ForeignKey("main.audiobook_series.id", ondelete="SET NULL"))
+    series_index: Mapped[float] = mapped_column(default=0.0)
+
+    author: Mapped[AudiobookAuthor] = relationship("AudiobookAuthor", back_populates="books")
+    series: Mapped[AudiobookSeries | None] = relationship("AudiobookSeries", back_populates="books")

python/orm/richie/ebook.py

@@ -0,0 +1,130 @@
+"""EPUB search models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import BigInteger, Boolean, DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from python.orm.richie.base import TableBase, TableBaseBig
+
+
+class EbookSource(TableBase):
+    """One indexed EPUB file."""
+
+    __tablename__ = "ebook_source"
+    __table_args__ = (
+        UniqueConstraint("file_path"),
+        UniqueConstraint("file_sha256"),
+    )
+
+    title: Mapped[str]
+    author: Mapped[str | None]
+    language: Mapped[str | None]
+    publisher: Mapped[str | None]
+    identifier: Mapped[str | None]
+    file_path: Mapped[str]
+    file_sha256: Mapped[str] = mapped_column(String(64))
+    file_mtime: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    file_size: Mapped[int] = mapped_column(BigInteger)
+
+    chapters: Mapped[list[EbookChapter]] = relationship(
+        "EbookChapter",
+        back_populates="source",
+        cascade="all, delete-orphan",
+        passive_deletes=True,
+    )
+    chunks: Mapped[list[EbookChunk]] = relationship(
+        "EbookChunk",
+        back_populates="source",
+        cascade="all, delete-orphan",
+        passive_deletes=True,
+    )
+
+
+class EbookChapter(TableBase):
+    """A chapter or spine document inside an EPUB."""
+
+    __tablename__ = "ebook_chapter"
+    __table_args__ = (UniqueConstraint("source_id", "spine_index"),)
+
+    source_id: Mapped[int] = mapped_column(ForeignKey("main.ebook_source.id", ondelete="CASCADE"))
+    spine_index: Mapped[int]
+    title: Mapped[str | None]
+    href: Mapped[str | None]
+
+    source: Mapped[EbookSource] = relationship("EbookSource", back_populates="chapters")
+    chunks: Mapped[list[EbookChunk]] = relationship(
+        "EbookChunk",
+        back_populates="chapter",
+        cascade="all, delete-orphan",
+        passive_deletes=True,
+    )
+
+
+class EbookChunk(TableBaseBig):
+    """A searchable text chunk."""
+
+    __tablename__ = "ebook_chunk"
+    __table_args__ = (
+        UniqueConstraint("source_id", "chunk_index", name="uq_ebook_chunk_source_id_chunk_index"),
+        UniqueConstraint("source_id", "content_sha256", name="uq_ebook_chunk_source_id_content_sha256"),
+    )
+
+    source_id: Mapped[int] = mapped_column(ForeignKey("main.ebook_source.id", ondelete="CASCADE"))
+    chapter_id: Mapped[int | None] = mapped_column(ForeignKey("main.ebook_chapter.id", ondelete="SET NULL"))
+    chunk_index: Mapped[int]
+    text: Mapped[str]
+    token_start: Mapped[int]
+    token_count: Mapped[int]
+    page_label: Mapped[str | None]
+    content_sha256: Mapped[str] = mapped_column(String(64))
+    search_text: Mapped[str]
+
+    source: Mapped[EbookSource] = relationship("EbookSource", back_populates="chunks")
+    chapter: Mapped[EbookChapter | None] = relationship("EbookChapter", back_populates="chunks")
+
+
+class EbookEmbeddingModel(TableBase):
+    """A supported embedding model."""
+
+    __tablename__ = "ebook_embedding_model"
+
+    name: Mapped[str] = mapped_column(String, unique=True)
+    dimension: Mapped[int]
+    is_default: Mapped[bool] = mapped_column(Boolean, default=False)
+
+
+class EbookChunkEmbedding1024(TableBaseBig):
+    """1024-dimensional chunk embedding."""
+
+    __tablename__ = "ebook_chunk_embedding_1024"
+    __table_args__ = (UniqueConstraint("chunk_id", "model_id"),)
+
+    chunk_id: Mapped[int] = mapped_column(ForeignKey("main.ebook_chunk.id", ondelete="CASCADE"))
+    model_id: Mapped[int] = mapped_column(ForeignKey("main.ebook_embedding_model.id", ondelete="CASCADE"))
+    embedding: Mapped[list[float]] = mapped_column(Vector(1024))
+
+
+class EbookChunkEmbedding2560(TableBaseBig):
+    """2560-dimensional chunk embedding."""
+
+    __tablename__ = "ebook_chunk_embedding_2560"
+    __table_args__ = (UniqueConstraint("chunk_id", "model_id"),)
+
+    chunk_id: Mapped[int] = mapped_column(ForeignKey("main.ebook_chunk.id", ondelete="CASCADE"))
+    model_id: Mapped[int] = mapped_column(ForeignKey("main.ebook_embedding_model.id", ondelete="CASCADE"))
+    embedding: Mapped[list[float]] = mapped_column(Vector(2560))
+
+
+class EbookChunkEmbedding4096(TableBaseBig):
+    """4096-dimensional chunk embedding."""
+
+    __tablename__ = "ebook_chunk_embedding_4096"
+    __table_args__ = (UniqueConstraint("chunk_id", "model_id"),)
+
+    chunk_id: Mapped[int] = mapped_column(ForeignKey("main.ebook_chunk.id", ondelete="CASCADE"))
+    model_id: Mapped[int] = mapped_column(ForeignKey("main.ebook_embedding_model.id", ondelete="CASCADE"))
+    embedding: Mapped[list[float]] = mapped_column(Vector(4096))

python/tools/audiobook/__init__.py

@@ -0,0 +1 @@
+"""Audiobook tools."""

python/tools/audiobook/audible_convert.py

@@ -0,0 +1,471 @@
+"""Convert Audible AAX downloads into Audiobookshelf-friendly M4B files."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import shutil
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import asdict, dataclass
+from os import getenv
+from pathlib import Path  # noqa: TC003 This is required for the typer CLI
+from typing import TYPE_CHECKING, Annotated, Any
+from uuid import uuid7
+
+import typer
+
+from python.common import configure_logger
+from python.orm.common import get_postgres_engine
+from python.tools.audiobook.metadata_agent import (
+    AgentConfig,
+    StandardBookMetadata,
+    standard_book_metadata,
+    write_agent_log,
+)
+
+if TYPE_CHECKING:
+    from sqlalchemy.engine import Engine
+
+logger = logging.getLogger(__name__)
+
+SENSITIVE_COMMAND_ARGUMENTS = {"-activation_bytes"}
+BOOK_RANGE_PATTERN = re.compile(r"(?:^|-)books?-(?P<start>[1-9]\d*)-(?P<end>[1-9]\d*)(?:-|$)")
+
+
+@dataclass(frozen=True)
+class ConversionConfig:
+    """Runtime settings for one conversion command."""
+
+    resolved_output: Path
+    ollama_api_key: str
+    agent_config: AgentConfig
+    engine: Engine
+    activation_bytes: str | None
+    dry_run: bool
+    overwrite: bool
+    work_directory_name: str = ".audible_convert"
+    dry_run_directory_name: str = "dry-run"
+    temp_directory_name: str = "tmp"
+    log_directory_name: str = "logs"
+    review_directory_name: str = "review"
+
+
+@dataclass(frozen=True)
+class ConcurrentConversionResult:
+    """Result from running ffmpeg and metadata resolution together."""
+
+    metadata: StandardBookMetadata | None
+    conversion_error: Exception | None
+    metadata_error: Exception | None
+
+
+class CommandExecutionError(RuntimeError):
+    """Command failed without exposing sensitive arguments."""
+
+    def __init__(self, arguments: list[str], returncode: int) -> None:
+        """Create a redacted command failure."""
+        self.arguments = tuple(arguments)
+        self.returncode = returncode
+        command = " ".join(redact_command_arguments(arguments))
+        super().__init__(f"Command failed with exit code {returncode}: {command}")
+
+
+def main(
+    input_directory: Annotated[Path, typer.Argument(help="Directory audible-cli downloads AAX files into.")],
+    output_directory: Annotated[Path, typer.Argument(help="Audiobook output directory.")],
+    *,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Print planned output files and write marker files without converting."),
+    ] = False,
+    overwrite: Annotated[bool, typer.Option("--overwrite", help="Overwrite existing M4B files.")] = False,
+) -> None:
+    """Convert AAX files from a download directory into M4B files."""
+    configure_logger()
+    resolved_input = input_directory.resolve(strict=True)
+    resolved_output = output_directory.resolve()
+    if not dry_run:
+        resolved_output.mkdir(parents=True, exist_ok=True)
+
+    ollama_api_key = getenv("OLLAMA_API_KEY")
+    if not ollama_api_key:
+        msg = "OLLAMA_API_KEY is required for audiobook metadata resolution"
+        raise RuntimeError(msg)
+
+    config = ConversionConfig(
+        resolved_output=resolved_output,
+        ollama_api_key=ollama_api_key,
+        agent_config=AgentConfig(),
+        engine=get_postgres_engine(name="RICHIE"),
+        activation_bytes=getenv("AUDIBLE_ACTIVATION_BYTES"),
+        dry_run=dry_run,
+        overwrite=overwrite,
+    )
+
+    aax_files = sorted(resolved_input.glob("*.aax"))
+    if not aax_files:
+        logger.info("No AAX files found in %s", resolved_input)
+        return
+    for aax_file in aax_files:
+        logger.info("Converting %s", aax_file)
+        convert_aax_file_with_agent(aax_file, config)
+
+
+def run_command(arguments: list[str], *, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    """Run a command and return the completed process.
+
+    Args:
+        arguments: Command and arguments to run.
+        capture: Whether to capture stdout and stderr.
+
+    Returns:
+        The completed process.
+    """
+    logger.debug("%s", " ".join(redact_command_arguments(arguments)))
+    try:
+        return subprocess.run(arguments, check=True, capture_output=capture, text=True)
+    except subprocess.CalledProcessError as error:
+        raise CommandExecutionError(arguments, error.returncode) from error
+
+
+def redact_command_arguments(arguments: list[str]) -> list[str]:
+    """Return command arguments with sensitive values redacted."""
+    redacted = []
+    redact_next = False
+    for argument in arguments:
+        if redact_next:
+            redacted.append("<redacted>")
+            redact_next = False
+            continue
+
+        redacted.append(argument)
+        redact_next = argument in SENSITIVE_COMMAND_ARGUMENTS
+    return redacted
+
+
+def read_metadata(aax_file: Path) -> dict[str, str]:
+    """Read ffprobe format tags from an AAX file.
+
+    Args:
+        aax_file: AAX file to inspect.
+
+    Returns:
+        Lower-cased metadata tag names mapped to their values.
+    """
+    completed = run_command(
+        [
+            "ffprobe",
+            "-v",
+            "quiet",
+            "-print_format",
+            "json",
+            "-show_format",
+            str(aax_file),
+        ],
+        capture=True,
+    )
+    ffprobe_data: dict[str, Any] = json.loads(completed.stdout)
+    tags = ffprobe_data.get("format", {}).get("tags", {})
+    return {str(key).lower(): str(value) for key, value in tags.items()}
+
+
+def output_stem(metadata: StandardBookMetadata) -> str:
+    """Build the output stem for a book.
+
+    Args:
+        metadata: Book metadata.
+
+    Returns:
+        Output stem in author-series_01-title form.
+    """
+    index_slug = series_index_slug(metadata.series_index, metadata.title)
+    return f"{metadata.author}-{metadata.series}_{index_slug}-{metadata.title}"
+
+
+def series_index_slug(series_index: float, title: str = "") -> str:
+    """Return a filename-safe series index."""
+    if title_range := title_series_range_slug(series_index, title):
+        return title_range
+    index = float(series_index)
+    if index.is_integer():
+        return f"{int(index):02}"
+    return f"{int(index):02}.5"
+
+
+def title_series_range_slug(series_index: float, title: str) -> str | None:
+    """Return a series range slug found in an omnibus title."""
+    index = float(series_index)
+    if not index.is_integer():
+        return None
+    first_index = int(index)
+    for match in BOOK_RANGE_PATTERN.finditer(title):
+        start = int(match.group("start"))
+        end = int(match.group("end"))
+        if start == first_index and end > start:
+            return f"{start:02}-{end:02}"
+    return None
+
+
+def metadata_output_path(output_directory: Path, metadata: StandardBookMetadata) -> Path:
+    """Build the final M4B path from resolved metadata."""
+    stem = output_stem(metadata)
+    return output_directory / stem / f"{stem}.m4b"
+
+
+def convert_aax_file(
+    aax_file: Path,
+    destination: Path,
+    activation_bytes: str | None,
+    *,
+    overwrite: bool,
+) -> None:
+    """Convert an AAX file into an M4B file.
+
+    Args:
+        aax_file: Source AAX file.
+        destination: Destination M4B file.
+        activation_bytes: Optional Audible activation bytes for ffmpeg.
+        overwrite: Whether to overwrite an existing M4B.
+    """
+    if destination.exists() and not overwrite:
+        logger.info("Skipping existing file %s", destination)
+        return
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    arguments = ["ffmpeg", "-hide_banner", "-y" if overwrite else "-n"]
+    if activation_bytes:
+        arguments.extend(["-activation_bytes", activation_bytes])
+    arguments.extend(["-i", str(aax_file), "-map_metadata", "0", "-c", "copy", str(destination)])
+    run_command(arguments)
+
+
+def write_review_file(
+    *,
+    destination: Path | None,
+    ffprobe_metadata: dict[str, str],
+    log_file: Path,
+    metadata: StandardBookMetadata | None,
+    reason: str,
+    review_file: Path,
+    source: Path,
+    temp_file: Path | None,
+) -> None:
+    """Write a manual review file for an unresolved conversion."""
+    review_file.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "destination": str(destination) if destination else None,
+        "ffprobe_metadata": ffprobe_metadata,
+        "metadata": asdict(metadata) if metadata else None,
+        "reason": reason,
+        "source": str(source),
+        "temp_file": str(temp_file) if temp_file else None,
+    }
+    review_file.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+    write_agent_log(log_file, "review_written", path=str(review_file), reason=reason)
+
+
+def cleanup_temp_output(temp_file: Path) -> None:
+    """Remove a run's temporary output directory."""
+    shutil.rmtree(temp_file.parent, ignore_errors=True)
+
+
+def dry_run_aax_file_with_agent(
+    aax_file: Path,
+    ffprobe_metadata: dict[str, str],
+    engine: Engine,
+    config: ConversionConfig,
+    log_file: Path,
+    review_file: Path,
+) -> None:
+    """Resolve and print the planned output path without converting."""
+    metadata = standard_book_metadata(
+        aax_file.name,
+        ffprobe_metadata,
+        engine,
+        log_file,
+        config.ollama_api_key,
+        config.agent_config,
+    )
+    destination = None if metadata.needs_review else metadata_output_path(config.resolved_output, metadata)
+    if metadata.needs_review:
+        write_review_file(
+            destination=destination,
+            ffprobe_metadata=ffprobe_metadata,
+            log_file=log_file,
+            metadata=metadata,
+            reason="metadata_needs_review",
+            review_file=review_file,
+            source=aax_file,
+            temp_file=None,
+        )
+        typer.echo(f"{aax_file} -> REVIEW {review_file}")
+    else:
+        stem = output_stem(metadata)
+        dry_run_file = (
+            config.resolved_output / config.work_directory_name / config.dry_run_directory_name / stem / f"{stem}.m4b"
+        )
+        dry_run_file.parent.mkdir(parents=True, exist_ok=True)
+        dry_run_file.write_text(f"{destination}\n", encoding="utf-8")
+        write_agent_log(
+            log_file,
+            "dry_run_file_written",
+            destination=str(destination),
+            path=str(dry_run_file),
+        )
+        typer.echo(f"{aax_file} -> {destination}")
+
+
+def convert_temp_file_and_resolve_metadata(
+    aax_file: Path,
+    temp_file: Path,
+    ffprobe_metadata: dict[str, str],
+    config: ConversionConfig,
+    log_file: Path,
+) -> ConcurrentConversionResult:
+    """Run ffmpeg and metadata resolution in parallel."""
+    conversion_error: Exception | None = None
+    metadata_error: Exception | None = None
+    metadata: StandardBookMetadata | None = None
+
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        conversion_future = executor.submit(
+            convert_aax_file,
+            aax_file,
+            temp_file,
+            config.activation_bytes,
+            overwrite=True,
+        )
+        metadata_future = executor.submit(
+            standard_book_metadata,
+            aax_file.name,
+            ffprobe_metadata,
+            config.engine,
+            log_file,
+            config.ollama_api_key,
+            config.agent_config,
+        )
+
+        conversion_error = conversion_future.exception()
+        if conversion_error is None:
+            conversion_future.result()
+
+        metadata_error = metadata_future.exception()
+        if metadata_error is None:
+            metadata = metadata_future.result()
+
+    return ConcurrentConversionResult(
+        metadata=metadata,
+        conversion_error=conversion_error,
+        metadata_error=metadata_error,
+    )
+
+
+def convert_aax_file_with_agent(aax_file: Path, config: ConversionConfig) -> None:
+    """Convert one AAX file using the metadata agent for the final path."""
+    run_id = uuid7().hex
+    log_file = config.resolved_output / config.work_directory_name / config.log_directory_name / f"{run_id}.jsonl"
+    review_file = config.resolved_output / config.work_directory_name / config.review_directory_name / f"{run_id}.json"
+    write_agent_log(log_file, "conversion_start", source=str(aax_file), dry_run=config.dry_run)
+    try:
+        ffprobe_metadata = read_metadata(aax_file)
+    except Exception as error:
+        logger.exception("ffprobe failed")
+        write_review_file(
+            destination=None,
+            ffprobe_metadata={},
+            log_file=log_file,
+            metadata=None,
+            reason=f"ffprobe_failed: {error}",
+            review_file=review_file,
+            source=aax_file,
+            temp_file=None,
+        )
+        return
+
+    if config.dry_run:
+        dry_run_aax_file_with_agent(
+            aax_file,
+            ffprobe_metadata,
+            config.engine,
+            config,
+            log_file,
+            review_file,
+        )
+        return
+
+    temp_file = (
+        config.resolved_output / config.work_directory_name / config.temp_directory_name / run_id / "converted.m4b"
+    )
+    temp_file.parent.mkdir(parents=True, exist_ok=True)
+
+    result = convert_temp_file_and_resolve_metadata(aax_file, temp_file, ffprobe_metadata, config, log_file)
+
+    if result.conversion_error:
+        reason = f"ffmpeg_failed: {result.conversion_error}"
+        write_review_file(
+            destination=None,
+            ffprobe_metadata=ffprobe_metadata,
+            log_file=log_file,
+            metadata=result.metadata,
+            reason=reason,
+            review_file=review_file,
+            source=aax_file,
+            temp_file=temp_file if temp_file.exists() else None,
+        )
+        return
+
+    if result.metadata_error:
+        write_review_file(
+            destination=None,
+            ffprobe_metadata=ffprobe_metadata,
+            log_file=log_file,
+            metadata=None,
+            reason=f"metadata_failed: {result.metadata_error}",
+            review_file=review_file,
+            source=aax_file,
+            temp_file=temp_file,
+        )
+        return
+
+    if result.metadata is None or result.metadata.needs_review:
+        write_review_file(
+            destination=None,
+            ffprobe_metadata=ffprobe_metadata,
+            log_file=log_file,
+            metadata=result.metadata,
+            reason="metadata_needs_review",
+            review_file=review_file,
+            source=aax_file,
+            temp_file=temp_file,
+        )
+        return
+
+    destination = metadata_output_path(config.resolved_output, result.metadata)
+    if destination.exists() and not config.overwrite:
+        write_agent_log(log_file, "destination_exists", destination=str(destination))
+        cleanup_temp_output(temp_file)
+        return
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        temp_file.replace(destination)
+    except Exception as error:  # noqa: BLE001
+        write_review_file(
+            destination=destination,
+            ffprobe_metadata=ffprobe_metadata,
+            log_file=log_file,
+            metadata=result.metadata,
+            reason=f"rename_failed: {error}",
+            review_file=review_file,
+            source=aax_file,
+            temp_file=temp_file if temp_file.exists() else None,
+        )
+    else:
+        cleanup_temp_output(temp_file)
+        write_agent_log(log_file, "conversion_complete", destination=str(destination))
+
+
+if __name__ == "__main__":
+    typer.run(main)

python/tools/audiobook/catalog.py

@@ -0,0 +1,176 @@
+"""Import audiobook catalog authors and series from CSV files."""
+
+from __future__ import annotations
+
+import csv
+import logging
+from pathlib import Path  # noqa: TC003 This is required for the typer CLI
+from typing import Annotated
+
+import typer
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from python.common import configure_logger
+from python.orm.common import get_postgres_engine
+from python.orm.richie import AudiobookAuthor, AudiobookSeries
+
+logger = logging.getLogger(__name__)
+
+AUTHOR_NAME_COLUMN = "author_name"
+ID_COLUMN = "id"
+NAME_COLUMN = "name"
+
+
+class CatalogImportError(ValueError):
+    """CSV catalog import failed validation."""
+
+
+def main(
+    authors_csv: Annotated[Path, typer.Argument(help="CSV with name and optional id.")],
+    series_csv: Annotated[Path, typer.Argument(help="CSV with name, author_name, and optional id.")],
+) -> None:
+    """Upsert audiobook authors and series from CSV files."""
+    configure_logger()
+    try:
+        engine = get_postgres_engine(name="RICHIE")
+        with Session(engine) as session:
+            author_count = upsert_authors_from_csv(session, authors_csv)
+            series_count = upsert_series_from_csv(session, series_csv)
+            session.commit()
+    except CatalogImportError as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(code=1) from error
+
+    logger.info("Upserted %s authors and %s series", author_count, series_count)
+
+
+def upsert_authors_from_csv(session: Session, authors_csv: Path) -> int:
+    """Upsert authors from a CSV file."""
+    count = 0
+    for row_number, row in csv_rows(authors_csv):
+        name = required_csv_value(row, authors_csv, row_number, NAME_COLUMN)
+        upsert_author(session, name, csv_id(row, authors_csv, row_number))
+        count += 1
+    return count
+
+
+def upsert_series_from_csv(session: Session, series_csv: Path) -> int:
+    """Upsert series from a CSV file."""
+    count = 0
+    for row_number, row in csv_rows(series_csv):
+        series_name = required_csv_value(row, series_csv, row_number, NAME_COLUMN)
+        author_name = required_csv_value(row, series_csv, row_number, AUTHOR_NAME_COLUMN)
+        author = find_author_by_name(session, author_name)
+        if author is None:
+            msg = f"{series_csv}:{row_number}: author not found: {author_name}"
+            raise CatalogImportError(msg)
+        upsert_series(session, series_name, author, csv_id(row, series_csv, row_number))
+        count += 1
+    return count
+
+
+def upsert_author(session: Session, name: str, author_id: int | None) -> AudiobookAuthor:
+    """Upsert one author by id or exact name."""
+    if author_id is not None:
+        author = session.get(AudiobookAuthor, author_id)
+        if author is None:
+            author = AudiobookAuthor(id=author_id, name=name)
+            session.add(author)
+        else:
+            author.name = name
+        session.flush()
+        return author
+
+    author = find_author_by_name(session, name)
+    if author is None:
+        author = AudiobookAuthor(name=name)
+        session.add(author)
+        session.flush()
+    return author
+
+
+def upsert_series(
+    session: Session,
+    name: str,
+    author: AudiobookAuthor,
+    series_id: int | None,
+) -> AudiobookSeries:
+    """Upsert one series by id or exact author/name match."""
+    if series_id is not None:
+        series = session.get(AudiobookSeries, series_id)
+        if series is None:
+            series = AudiobookSeries(id=series_id, name=name, author=author)
+            session.add(series)
+        else:
+            series.name = name
+            series.author = author
+        session.flush()
+        return series
+
+    series = find_series_by_name_and_author(session, name, author.id)
+    if series is None:
+        series = AudiobookSeries(name=name, author=author)
+        session.add(series)
+        session.flush()
+    return series
+
+
+def find_author_by_name(session: Session, name: str) -> AudiobookAuthor | None:
+    """Find one author by exact name."""
+    return session.scalar(select(AudiobookAuthor).where(AudiobookAuthor.name == name))
+
+
+def find_series_by_name_and_author(
+    session: Session,
+    name: str,
+    author_id: int,
+) -> AudiobookSeries | None:
+    """Find one series by exact name and author."""
+    return session.scalar(
+        select(AudiobookSeries).where(
+            AudiobookSeries.name == name,
+            AudiobookSeries.author_id == author_id,
+        ),
+    )
+
+
+def csv_rows(csv_path: Path) -> list[tuple[int, dict[str, str | None]]]:
+    """Read a CSV file as numbered rows."""
+    with csv_path.open(newline="", encoding="utf-8") as file:
+        reader = csv.DictReader(file)
+        if reader.fieldnames is None:
+            msg = f"{csv_path}: missing CSV header"
+            raise CatalogImportError(msg)
+        return [(row_number, row) for row_number, row in enumerate(reader, start=2)]
+
+
+def required_csv_value(
+    row: dict[str, str | None],
+    csv_path: Path,
+    row_number: int,
+    column: str,
+) -> str:
+    """Read a required CSV value."""
+    value = row.get(column)
+    if value and value.strip():
+        return value.strip()
+    msg = f"{csv_path}:{row_number}: missing required column value: {column}"
+    raise CatalogImportError(msg)
+
+
+def csv_id(row: dict[str, str | None], csv_path: Path, row_number: int) -> int | None:
+    """Read an optional id field from a CSV row."""
+    value = row.get(ID_COLUMN)
+    if value is None or not value.strip():
+        return None
+    try:
+        return int(value)
+    except ValueError as error:
+        msg = f"{csv_path}:{row_number}: id must be an integer: {value}"
+        raise CatalogImportError(msg) from error
+    return None
+
+
+if __name__ == "__main__":
+    typer.run(main)

python/tools/audiobook/llm_tool_calling.py

@@ -0,0 +1,599 @@
+"""LLM tool calling support for audiobook metadata resolution."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sqlalchemy import or_, select
+
+from python.orm.richie import Audiobook, AudiobookAuthor, AudiobookSeries
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from sqlalchemy.orm import Session
+
+    from python.tools.audiobook.metadata_agent import AgentConfig
+
+CATALOG_SLUG_PATTERN = re.compile(r"^[a-z0-9]+(?:_[a-z0-9]+)*$")
+TITLE_SLUG_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+LogWriter = Callable[..., None]
+
+
+class MetadataResolutionError(ValueError):
+    """Metadata resolution failed validation."""
+
+
+@dataclass(frozen=True)
+class EnsuredBook:
+    """Book row plus whether it was created."""
+
+    book: Audiobook
+    action: str
+
+
+class CatalogToolRegistry:
+    """Controlled catalog tools exposed to the metadata model."""
+
+    def __init__(
+        self,
+        session: Session,
+        log_path: Path,
+        config: AgentConfig,
+        write_log: LogWriter,
+    ) -> None:
+        """Create a registry bound to one database session and audit log."""
+        self.session = session
+        self.log_path = log_path
+        self.config = config
+        self.write_log = write_log
+        self.seen_author_ids: set[int] = set()
+        self.seen_series_ids: set[int] = set()
+        self.seen_book_ids: set[int] = set()
+        self.created_author_ids: set[int] = set()
+        self.created_series_ids: set[int] = set()
+        self.created_book_ids: set[int] = set()
+
+    def tool_schemas(self) -> list[dict[str, object]]:
+        """Return Ollama tool schemas."""
+        schemas = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "search_authors",
+                    "description": "Search canonical audiobook authors by slug or noisy source text.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"query": {"type": "string"}},
+                        "required": ["query"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "search_series",
+                    "description": "Search canonical audiobook series by slug or noisy source text.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "query": {"type": "string"},
+                            "author_id": {"type": ["integer", "null"]},
+                        },
+                        "required": ["query"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "search_books",
+                    "description": "Search canonical audiobook titles with optional author and series filters.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "query": {"type": "string"},
+                            "author_id": {"type": ["integer", "null"]},
+                            "series_id": {"type": ["integer", "null"]},
+                        },
+                        "required": ["query"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "ensure_author",
+                    "description": "Normalize an author name to a catalog slug, then return or create that author.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"name": {"type": "string"}},
+                        "required": ["name"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "ensure_series",
+                    "description": "Normalize a series name to a catalog slug, then return or create it for an author.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "name": {"type": "string"},
+                            "author_id": {"type": "integer"},
+                        },
+                        "required": ["name", "author_id"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "ensure_book",
+                    "description": "Normalize a title to a book slug, then return or create it for an author/series.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "title": {"type": "string"},
+                            "author_id": {"type": "integer"},
+                            "series_id": {"type": ["integer", "null"]},
+                            "series_index": {"type": "number", "multipleOf": 0.5},
+                        },
+                        "required": ["title", "author_id", "series_id", "series_index"],
+                    },
+                },
+            },
+        ]
+        enabled_tool_names = set(self.config.tool_names)
+        return [schema for schema in schemas if schema["function"]["name"] in enabled_tool_names]
+
+    def run(self, name: str, arguments: dict[str, object]) -> list[dict[str, object]]:
+        """Run one catalog tool and audit the call."""
+        handlers = {
+            "search_authors": self.run_search_authors,
+            "search_series": self.run_search_series,
+            "search_books": self.run_search_books,
+            "ensure_author": self.run_ensure_author,
+            "ensure_series": self.run_ensure_series,
+            "ensure_book": self.run_ensure_book,
+        }
+        handler = handlers.get(name)
+        if handler is None:
+            self.write_log(self.log_path, "tool_error", tool=name, arguments=arguments, error="unknown_tool")
+            msg = f"Unknown audiobook metadata tool: {name}"
+            raise MetadataResolutionError(msg)
+        if name not in self.config.tool_names:
+            self.write_log(self.log_path, "tool_error", tool=name, arguments=arguments, error="tool_not_enabled")
+            msg = f"Audiobook metadata tool is not enabled: {name}"
+            raise MetadataResolutionError(msg)
+
+        started = time.perf_counter()
+        self.write_log(self.log_path, "tool_call", tool=name, arguments=arguments)
+        result = handler(arguments)
+        duration_ms = round((time.perf_counter() - started) * 1000, 3)
+        self.write_log(
+            self.log_path,
+            "tool_result",
+            tool=name,
+            duration_ms=duration_ms,
+            result_count=len(result),
+            preview=result[:3],
+        )
+        return result
+
+    def get_author(self, author_id: int) -> AudiobookAuthor | None:
+        """Return an author by id."""
+        return self.session.get(AudiobookAuthor, author_id)
+
+    def get_book(self, book_id: int) -> Audiobook | None:
+        """Return a book by id."""
+        return self.session.get(Audiobook, book_id)
+
+    def get_series(self, series_id: int) -> AudiobookSeries | None:
+        """Return a series by id."""
+        return self.session.get(AudiobookSeries, series_id)
+
+    def prune_unused_created_rows(self, *, author_id: int, book_id: int | None, series_id: int | None) -> None:
+        """Remove catalog rows created during this run but not used by final metadata."""
+        used_book_ids = {book_id} if book_id is not None else set()
+        for created_book_id in self.created_book_ids - used_book_ids:
+            if book := self.get_book(created_book_id):
+                self.session.delete(book)
+
+        self.session.flush()
+        used_series_ids = {series_id} if series_id is not None else set()
+        for created_series_id in self.created_series_ids - used_series_ids:
+            series = self.get_series(created_series_id)
+            if series and not series.books:
+                self.session.delete(series)
+
+        self.session.flush()
+        for created_author_id in self.created_author_ids - {author_id}:
+            author = self.get_author(created_author_id)
+            if author and not author.books and not author.series:
+                self.session.delete(author)
+
+    def run_search_authors(self, arguments: dict[str, object]) -> list[dict[str, object]]:
+        """Search authors from tool arguments and remember returned ids."""
+        query = required_string(arguments, "query")
+        statement = select(AudiobookAuthor).order_by(AudiobookAuthor.name).limit(self.config.max_tool_results)
+        if terms := query_terms(query):
+            statement = statement.where(or_(*(AudiobookAuthor.name.ilike(f"%{term}%") for term in terms)))
+
+        authors = self.session.scalars(statement).all()
+        self.seen_author_ids.update(author.id for author in authors)
+        return [{"id": author.id, "name": author.name} for author in authors]
+
+    def run_search_series(self, arguments: dict[str, object]) -> list[dict[str, object]]:
+        """Search series from tool arguments and remember returned ids."""
+        query = required_string(arguments, "query")
+        author_id = optional_int(arguments.get("author_id"), "author_id")
+        statement = select(AudiobookSeries).order_by(AudiobookSeries.name).limit(self.config.max_tool_results)
+        if terms := query_terms(query):
+            statement = statement.where(or_(*(AudiobookSeries.name.ilike(f"%{term}%") for term in terms)))
+        if author_id is not None:
+            statement = statement.where(AudiobookSeries.author_id == author_id)
+
+        series_rows = self.session.scalars(statement).all()
+        self.seen_series_ids.update(series.id for series in series_rows)
+        self.seen_author_ids.update(series.author_id for series in series_rows)
+        return [
+            {
+                "id": series.id,
+                "name": series.name,
+                "author_id": series.author_id,
+                "author": series.author.name,
+            }
+            for series in series_rows
+        ]
+
+    def run_search_books(self, arguments: dict[str, object]) -> list[dict[str, object]]:
+        """Search books from tool arguments and remember returned ids."""
+        query = required_string(arguments, "query")
+        author_id = optional_int(arguments.get("author_id"), "author_id")
+        series_id = optional_int(arguments.get("series_id"), "series_id")
+        statement = select(Audiobook).order_by(Audiobook.title).limit(self.config.max_tool_results)
+        if terms := query_terms(query):
+            statement = statement.where(or_(*(Audiobook.title.ilike(f"%{term}%") for term in terms)))
+        if author_id is not None:
+            statement = statement.where(Audiobook.author_id == author_id)
+        if series_id is not None:
+            statement = statement.where(Audiobook.series_id == series_id)
+
+        books = self.session.scalars(statement).all()
+        self.seen_book_ids.update(book.id for book in books)
+        self.seen_author_ids.update(book.author_id for book in books)
+        self.seen_series_ids.update(book.series_id for book in books if book.series_id is not None)
+        return [
+            {
+                "id": book.id,
+                "title": book.title,
+                "author_id": book.author_id,
+                "author": book.author.name,
+                "series_id": book.series_id,
+                "series": book.series.name if book.series else self.config.standalone_series,
+                "series_index": book.series_index,
+            }
+            for book in books
+        ]
+
+    def run_ensure_author(self, arguments: dict[str, object]) -> list[dict[str, object]]:
+        """Ensure an author from tool arguments and return a tool result."""
+        name = normalize_catalog_slug(required_string(arguments, "name"))
+        validate_catalog_slug(name, "author")
+        author = self.session.scalar(select(AudiobookAuthor).where(AudiobookAuthor.name == name))
+        action = "existing"
+        if author is None:
+            author = AudiobookAuthor(name=name)
+            self.session.add(author)
+            self.session.flush()
+            self.created_author_ids.add(author.id)
+            action = "created"
+
+        self.seen_author_ids.add(author.id)
+        return [{"id": author.id, "name": author.name, "action": action}]
+
+    def run_ensure_series(self, arguments: dict[str, object]) -> list[dict[str, object]]:
+        """Ensure a series from tool arguments and return a tool result."""
+        name = normalize_catalog_slug(required_string(arguments, "name"))
+        author_id = required_int(arguments, "author_id")
+        validate_catalog_slug(name, "series")
+        author = self.required_author(author_id)
+        series = self.find_series_by_catalog_slug(name, author.id)
+        action = "existing"
+        if series is None:
+            series = AudiobookSeries(name=name, author=author)
+            self.session.add(series)
+            self.session.flush()
+            self.created_series_ids.add(series.id)
+            action = "created"
+
+        self.seen_author_ids.add(author.id)
+        self.seen_series_ids.add(series.id)
+        return [self.series_result(series, action)]
+
+    def run_ensure_book(self, arguments: dict[str, object]) -> list[dict[str, object]]:
+        """Ensure a book from tool arguments and return a tool result."""
+        title = required_string(arguments, "title")
+        author_id = required_int(arguments, "author_id")
+        series_id = optional_int(arguments.get("series_id"), "series_id")
+        series_index = required_series_index(arguments, "series_index")
+        ensured = self.ensure_book(title, author_id, series_id, series_index)
+        return [self.book_result(ensured.book, ensured.action)]
+
+    def ensure_book(
+        self,
+        title: str,
+        author_id: int,
+        series_id: int | None,
+        series_index: float,
+    ) -> EnsuredBook:
+        """Return an existing book row, or create it after validating ownership."""
+        title = normalize_title_slug(title)
+        validate_title_slug(title)
+        author = self.required_author(author_id)
+        series = None
+        if series_id is None:
+            if series_index != 0:
+                msg = "standalone books must use series_index 0"
+                raise MetadataResolutionError(msg)
+        else:
+            series = self.required_series(series_id)
+            if series.author_id != author.id:
+                msg = f"series_id {series_id} does not belong to author_id {author_id}"
+                raise MetadataResolutionError(msg)
+            if series_index <= 0:
+                msg = "series books must use a positive series_index"
+                raise MetadataResolutionError(msg)
+
+        statement = select(Audiobook).where(
+            Audiobook.title == title,
+            Audiobook.author_id == author.id,
+        )
+        if series is None:
+            statement = statement.where(Audiobook.series_id.is_(None))
+        else:
+            statement = statement.where(Audiobook.series_id == series.id)
+        book = self.session.scalar(statement)
+        if book is None:
+            book = Audiobook(title=title, author=author, series=series, series_index=series_index)
+            self.session.add(book)
+            self.session.flush()
+            self.created_book_ids.add(book.id)
+            action = "created"
+        else:
+            action = "existing"
+
+        self.seen_book_ids.add(book.id)
+        self.seen_author_ids.add(author.id)
+        if book.series_id is not None:
+            self.seen_series_ids.add(book.series_id)
+        return EnsuredBook(book=book, action=action)
+
+    def required_author(self, author_id: int) -> AudiobookAuthor:
+        """Return an author or fail metadata resolution."""
+        author = self.get_author(author_id)
+        if author is None:
+            msg = f"author_id {author_id} does not exist"
+            raise MetadataResolutionError(msg)
+        return author
+
+    def required_series(self, series_id: int) -> AudiobookSeries:
+        """Return a series or fail metadata resolution."""
+        series = self.get_series(series_id)
+        if series is None:
+            msg = f"series_id {series_id} does not exist"
+            raise MetadataResolutionError(msg)
+        return series
+
+    def find_series_by_catalog_slug(self, name: str, author_id: int) -> AudiobookSeries | None:
+        """Return a series by exact slug or underscore-insensitive slug."""
+        exact = self.session.scalar(
+            select(AudiobookSeries).where(
+                AudiobookSeries.name == name,
+                AudiobookSeries.author_id == author_id,
+            ),
+        )
+        if exact is not None:
+            return exact
+
+        compact_name = compact_catalog_slug(name)
+        series_rows = self.session.scalars(
+            select(AudiobookSeries).where(AudiobookSeries.author_id == author_id).order_by(AudiobookSeries.name),
+        ).all()
+        for series in series_rows:
+            if compact_catalog_slug(series.name) == compact_name:
+                return series
+        return None
+
+    def series_result(self, series: AudiobookSeries, action: str) -> dict[str, object]:
+        """Build a normalized series tool result."""
+        return {
+            "id": series.id,
+            "name": series.name,
+            "author_id": series.author_id,
+            "author": series.author.name,
+            "action": action,
+        }
+
+    def book_result(self, book: Audiobook, action: str) -> dict[str, object]:
+        """Build a normalized book tool result."""
+        return {
+            "id": book.id,
+            "title": book.title,
+            "author_id": book.author_id,
+            "author": book.author.name,
+            "series_id": book.series_id,
+            "series": book.series.name if book.series else self.config.standalone_series,
+            "series_index": book.series_index,
+            "action": action,
+        }
+
+
+def run_tool_calls(
+    messages: list[dict[str, object]],
+    message: dict[str, object],
+    tool_calls: list[tuple[str, dict[str, object]]],
+    registry: CatalogToolRegistry,
+    log_path: Path,
+    write_log: LogWriter,
+) -> str | None:
+    """Run tool calls, append tool messages, and return fatal error text when stopped."""
+    messages.append(message)
+    for tool_name, arguments in tool_calls:
+        try:
+            tool_result = registry.run(tool_name, arguments)
+        except MetadataResolutionError as error:
+            if is_fatal_tool_error(error):
+                return str(error)
+            write_log(log_path, "tool_error", tool=tool_name, arguments=arguments, error=str(error))
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_name": tool_name,
+                    "content": json.dumps({"error": str(error)}, sort_keys=True),
+                },
+            )
+            continue
+        messages.append(
+            {
+                "role": "tool",
+                "tool_name": tool_name,
+                "content": json.dumps(tool_result, sort_keys=True),
+            },
+        )
+    return None
+
+
+def parse_tool_calls(message: dict[str, object]) -> list[tuple[str, dict[str, object]]]:
+    """Parse Ollama tool calls from a response message."""
+    raw_tool_calls = message.get("tool_calls") or []
+    if not isinstance(raw_tool_calls, list):
+        msg = "tool_calls must be a list"
+        raise MetadataResolutionError(msg)
+
+    tool_calls = []
+    for raw_call in raw_tool_calls:
+        if not isinstance(raw_call, dict):
+            msg = "tool call must be an object"
+            raise MetadataResolutionError(msg)
+        function = raw_call.get("function")
+        if not isinstance(function, dict):
+            msg = "tool call is missing function"
+            raise MetadataResolutionError(msg)
+        name = function.get("name")
+        if not isinstance(name, str) or not name:
+            msg = "tool call is missing function name"
+            raise MetadataResolutionError(msg)
+        arguments = parse_tool_arguments(function.get("arguments", {}))
+        tool_calls.append((name, arguments))
+    return tool_calls
+
+
+def parse_tool_arguments(raw_arguments: object) -> dict[str, object]:
+    """Parse tool call arguments returned by Ollama."""
+    if isinstance(raw_arguments, dict):
+        return {str(key): value for key, value in raw_arguments.items()}
+    if isinstance(raw_arguments, str):
+        parsed = json.loads(raw_arguments) if raw_arguments else {}
+        if isinstance(parsed, dict):
+            return {str(key): value for key, value in parsed.items()}
+    msg = "tool arguments must be an object"
+    raise MetadataResolutionError(msg)
+
+
+def validate_title_slug(title: str) -> None:
+    """Validate a canonical book title slug."""
+    if not TITLE_SLUG_PATTERN.fullmatch(title):
+        msg = f"title slug is invalid: {title}"
+        raise MetadataResolutionError(msg)
+
+
+def validate_catalog_slug(value: str, label: str) -> None:
+    """Validate a canonical catalog slug."""
+    if not CATALOG_SLUG_PATTERN.fullmatch(value):
+        msg = f"{label} slug is invalid: {value}"
+        raise MetadataResolutionError(msg)
+
+
+def normalize_catalog_slug(value: str) -> str:
+    """Normalize noisy catalog names into lower snake-case slugs."""
+    return re.sub(r"[^a-z0-9]+", "_", value.strip().casefold()).strip("_")
+
+
+def compact_catalog_slug(value: str) -> str:
+    """Return a catalog slug comparison key that ignores underscores."""
+    return normalize_catalog_slug(value).replace("_", "")
+
+
+def normalize_title_slug(value: str) -> str:
+    """Normalize noisy book titles into lower kebab-case slugs."""
+    return re.sub(r"[^a-z0-9]+", "-", value.strip().casefold()).strip("-")
+
+
+def is_fatal_tool_error(error: MetadataResolutionError) -> bool:
+    """Return whether a tool error should stop the agent immediately."""
+    message = str(error)
+    return message.startswith(
+        (
+            "Unknown audiobook metadata tool",
+            "Audiobook metadata tool is not enabled",
+        ),
+    )
+
+
+def query_terms(query: str) -> tuple[str, ...]:
+    """Return text variants useful for matching noisy audiobook metadata."""
+    normalized = query.strip().casefold()
+    underscore_slug = normalize_catalog_slug(normalized)
+    compact_slug = compact_catalog_slug(normalized)
+    hyphen_slug = normalize_title_slug(normalized)
+    return tuple(dict.fromkeys(term for term in (normalized, underscore_slug, compact_slug, hyphen_slug) if term))
+
+
+def required_string(data: dict[str, object], key: str) -> str:
+    """Read a required string field."""
+    value = data.get(key)
+    if not isinstance(value, str) or not value.strip():
+        msg = f"{key} must be a non-empty string"
+        raise MetadataResolutionError(msg)
+    return value.strip()
+
+
+def required_int(data: dict[str, object], key: str) -> int:
+    """Read a required integer field."""
+    value = data.get(key)
+    if isinstance(value, bool) or not isinstance(value, int):
+        msg = f"{key} must be an integer"
+        raise MetadataResolutionError(msg)
+    return value
+
+
+def required_series_index(data: dict[str, object], key: str) -> float:
+    """Read a required whole-number or half-number series index."""
+    value = data.get(key)
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        msg = f"{key} must be a number"
+        raise MetadataResolutionError(msg)
+    series_index = float(value)
+    if not (series_index * 2).is_integer():
+        msg = f"{key} must be a whole number or .5 increment"
+        raise MetadataResolutionError(msg)
+    return series_index
+
+
+def optional_int(value: object, key: str) -> int | None:
+    """Read an optional integer field."""
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int):
+        msg = f"{key} must be an integer or null"
+        raise MetadataResolutionError(msg)
+    return value

python/tools/audiobook/metadata_agent.py

@@ -0,0 +1,575 @@
+"""Resolve audiobook metadata with a controlled Ollama tool loop."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import asdict, dataclass, is_dataclass, replace
+from os import PathLike
+from typing import TYPE_CHECKING
+
+import httpx
+from sqlalchemy.orm import Session
+
+from python.common import utcnow
+from python.tools.audiobook.llm_tool_calling import (
+    CatalogToolRegistry,
+    MetadataResolutionError,
+    normalize_title_slug,
+    optional_int,
+    parse_tool_calls,
+    required_int,
+    required_series_index,
+    required_string,
+    run_tool_calls,
+    validate_catalog_slug,
+    validate_title_slug,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from sqlalchemy.engine import Engine
+
+    from python.orm.richie import AudiobookAuthor
+
+FENCED_JSON_PATTERN = re.compile(r"^```(?:json)?\s*(?P<json>.*?)\s*```$", re.IGNORECASE | re.DOTALL)
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    """Runtime settings for the audiobook metadata agent."""
+
+    model: str = "deepseek-v4-flash:cloud"
+    ollama_chat_url: str = "https://ollama.com/api/chat"
+    http_timeout_seconds: int = 300
+    max_agent_turns: int = 8
+    max_tool_results: int = 10
+    min_confidence: float = 0.85
+    invalid_final_retries: int = 1
+    standalone_series: str = "standalone"
+    tool_names: tuple[str, ...] = (
+        "search_authors",
+        "search_series",
+        "search_books",
+        "ensure_author",
+        "ensure_series",
+        "ensure_book",
+    )
+
+
+@dataclass(frozen=True)
+class StandardBookMetadata:
+    """Canonical metadata for the final audiobook path."""
+
+    author_id: int
+    author: str
+    book_id: int | None
+    title: str
+    series_id: int | None
+    series: str
+    series_index: float
+    confidence: float
+    needs_review: bool
+    evidence: list[str]
+
+
+@dataclass(frozen=True)
+class FinalMetadataFields:
+    """Raw model fields after schema validation."""
+
+    author_id: int
+    book_id: int | None
+    title: str
+    series_id: int | None
+    series_index: float
+    confidence: float
+    evidence: list[str]
+
+
+@dataclass(frozen=True)
+class ResolvedBookFields:
+    """Book fields after optional catalog book resolution."""
+
+    book_id: int | None
+    title: str
+    series_id: int | None
+    series_index: float
+
+
+@dataclass(frozen=True)
+class AgentStepResult:
+    """Outcome from one model response."""
+
+    metadata: StandardBookMetadata | None
+    invalid_final_count: int
+    should_continue: bool
+
+
+def standard_book_metadata(
+    aax_file_name: str,
+    aax_metadata_from_ffprobe: dict[str, str],
+    engine: Engine,
+    log_path: Path,
+    ollama_api_key: str,
+    config: AgentConfig,
+) -> StandardBookMetadata:
+    """Resolve canonical audiobook metadata with the configured Ollama Cloud model."""
+    with Session(engine) as session:
+        registry = CatalogToolRegistry(session, log_path, config, write_agent_log)
+        agent = AudiobookMetadataAgent(
+            registry=registry, log_path=log_path, ollama_api_key=ollama_api_key, config=config
+        )
+        metadata = agent.run(aax_file_name, aax_metadata_from_ffprobe)
+        if metadata.needs_review:
+            session.rollback()
+        else:
+            registry.prune_unused_created_rows(
+                author_id=metadata.author_id,
+                book_id=metadata.book_id,
+                series_id=metadata.series_id,
+            )
+            session.commit()
+        return metadata
+
+
+class AudiobookMetadataAgent:
+    """Ollama-backed metadata resolver with a fixed local tool registry."""
+
+    def __init__(
+        self,
+        *,
+        registry: CatalogToolRegistry,
+        log_path: Path,
+        ollama_api_key: str,
+        config: AgentConfig,
+    ) -> None:
+        """Create an Ollama metadata agent."""
+        self._registry = registry
+        self._log_path = log_path
+        self._ollama_api_key = ollama_api_key
+        self._config = config
+
+    def run(self, aax_file_name: str, aax_metadata_from_ffprobe: dict[str, str]) -> StandardBookMetadata:
+        """Resolve metadata for one AAX file."""
+        messages = [
+            {"role": "system", "content": system_prompt()},
+            {"role": "user", "content": user_prompt(aax_file_name, aax_metadata_from_ffprobe)},
+        ]
+        invalid_final_count = 0
+        result: StandardBookMetadata | None = None
+
+        for turn in range(1, self._config.max_agent_turns + 1):
+            step = self.run_step(messages, turn, invalid_final_count)
+            invalid_final_count = step.invalid_final_count
+            if step.should_continue:
+                continue
+            result = step.metadata
+            break
+
+        if result is None:
+            return self.force_final_response(messages)
+        return result
+
+    def run_step(
+        self,
+        messages: list[dict[str, object]],
+        turn: int,
+        invalid_final_count: int,
+    ) -> AgentStepResult:
+        """Run one model turn and return the next agent-loop action."""
+        data = self.chat(messages, turn)
+        message = data.get("message")
+        if not isinstance(message, dict):
+            return AgentStepResult(
+                metadata=review_metadata("Ollama response did not include a message", self._config),
+                invalid_final_count=invalid_final_count,
+                should_continue=False,
+            )
+
+        try:
+            tool_calls = parse_tool_calls(message)
+        except (json.JSONDecodeError, MetadataResolutionError) as error:
+            return AgentStepResult(
+                metadata=review_metadata(str(error), self._config),
+                invalid_final_count=invalid_final_count,
+                should_continue=False,
+            )
+        if tool_calls:
+            fatal_error = run_tool_calls(messages, message, tool_calls, self._registry, self._log_path, write_agent_log)
+            if fatal_error is not None:
+                return AgentStepResult(
+                    metadata=review_metadata(fatal_error, self._config),
+                    invalid_final_count=invalid_final_count,
+                    should_continue=False,
+                )
+            return AgentStepResult(metadata=None, invalid_final_count=invalid_final_count, should_continue=True)
+        return self.handle_final_message(messages, message, invalid_final_count)
+
+    def handle_final_message(
+        self,
+        messages: list[dict[str, object]],
+        message: dict[str, object],
+        invalid_final_count: int,
+    ) -> AgentStepResult:
+        """Validate a final model message or request one retry."""
+        content = message.get("content")
+        if not isinstance(content, str):
+            return AgentStepResult(
+                metadata=review_metadata("Ollama final response did not include string content", self._config),
+                invalid_final_count=invalid_final_count,
+                should_continue=False,
+            )
+
+        try:
+            resolved = self.validate_final(parse_final_json_content(content))
+        except (json.JSONDecodeError, MetadataResolutionError) as error:
+            return self.handle_invalid_final(messages, error, invalid_final_count)
+
+        write_agent_log(self._log_path, "final_metadata", metadata=resolved)
+        return AgentStepResult(metadata=resolved, invalid_final_count=invalid_final_count, should_continue=False)
+
+    def handle_invalid_final(
+        self,
+        messages: list[dict[str, object]],
+        error: json.JSONDecodeError | MetadataResolutionError,
+        invalid_final_count: int,
+    ) -> AgentStepResult:
+        """Log invalid final JSON and either retry or return review metadata."""
+        invalid_final_count += 1
+        write_agent_log(
+            self._log_path,
+            "final_validation_error",
+            error=str(error),
+            invalid_final_count=invalid_final_count,
+        )
+        if invalid_final_count > self._config.invalid_final_retries:
+            return AgentStepResult(
+                metadata=review_metadata(str(error), self._config),
+                invalid_final_count=invalid_final_count,
+                should_continue=False,
+            )
+        messages.append(
+            {
+                "role": "user",
+                "content": (
+                    "Your previous final answer was invalid. Return only valid JSON matching the required "
+                    f"schema. Validation error: {error}"
+                ),
+            },
+        )
+        return AgentStepResult(metadata=None, invalid_final_count=invalid_final_count, should_continue=True)
+
+    def force_final_response(self, messages: list[dict[str, object]]) -> StandardBookMetadata:
+        """Request a no-tool final answer after the normal turn limit."""
+        messages.append({"role": "user", "content": forced_final_prompt()})
+        write_agent_log(self._log_path, "forced_final_request", reason="max_turns")
+        data = self.chat(messages, self._config.max_agent_turns + 1, tools_enabled=False)
+        message = data.get("message")
+        if not isinstance(message, dict):
+            return review_metadata("Ollama forced final response did not include a message", self._config)
+        content = message.get("content")
+        if not isinstance(content, str):
+            return review_metadata("Ollama forced final response did not include string content", self._config)
+        try:
+            resolved = self.validate_final(parse_final_json_content(content))
+        except (json.JSONDecodeError, MetadataResolutionError) as error:
+            return review_metadata(f"Ollama forced final response was invalid: {error}", self._config)
+        write_agent_log(self._log_path, "final_metadata", metadata=resolved)
+        return resolved
+
+    def chat(self, messages: list[dict[str, object]], turn: int, *, tools_enabled: bool = True) -> dict[str, object]:
+        """Send one chat request to Ollama and log the request and response."""
+        payload = {
+            "model": self._config.model,
+            "messages": messages,
+            "stream": False,
+            "options": {"temperature": 0.1},
+        }
+        tool_names = []
+        if tools_enabled:
+            payload["tools"] = self._registry.tool_schemas()
+            tool_names = self._config.tool_names
+        write_agent_log(
+            self._log_path,
+            "model_request",
+            model=self._config.model,
+            turn=turn,
+            message_count=len(messages),
+            tool_names=tool_names,
+            tools_enabled=tools_enabled,
+        )
+        write_agent_log(
+            self._log_path,
+            "llm_messages_sent",
+            model=self._config.model,
+            turn=turn,
+            messages=messages,
+            tools_enabled=tools_enabled,
+        )
+        response = httpx.post(
+            self._config.ollama_chat_url,
+            headers={"Authorization": f"Bearer {self._ollama_api_key}"},
+            json=payload,
+            timeout=self._config.http_timeout_seconds,
+        )
+        response.raise_for_status()
+        raw_data = response.json()
+        if not isinstance(raw_data, dict):
+            return {}
+        data = {str(key): value for key, value in raw_data.items()}
+        message = data.get("message", {})
+        content = message.get("content") if isinstance(message, dict) else ""
+        write_agent_log(
+            self._log_path,
+            "llm_message_received",
+            model=self._config.model,
+            turn=turn,
+            message=message,
+        )
+        write_agent_log(
+            self._log_path,
+            "model_response",
+            model=self._config.model,
+            turn=turn,
+            has_tool_calls=bool(isinstance(message, dict) and message.get("tool_calls")),
+            content_chars=len(content) if isinstance(content, str) else 0,
+        )
+        return data
+
+    def validate_final(self, raw_metadata: object) -> StandardBookMetadata:
+        """Validate final model metadata against catalog rows."""
+        fields = parse_final_metadata_fields(raw_metadata)
+        fields = replace(fields, title=normalize_title_slug(fields.title))
+        author = self.validate_author(fields.author_id)
+        validate_title_slug(fields.title)
+        book_fields = self.resolve_book_fields(fields)
+        series = self.validate_series(fields.author_id, book_fields.series_id, book_fields.series_index)
+
+        return StandardBookMetadata(
+            author_id=fields.author_id,
+            author=author.name,
+            book_id=book_fields.book_id,
+            title=book_fields.title,
+            series_id=book_fields.series_id,
+            series=series,
+            series_index=book_fields.series_index,
+            confidence=fields.confidence,
+            needs_review=fields.confidence < self._config.min_confidence,
+            evidence=fields.evidence,
+        )
+
+    def validate_author(self, author_id: int) -> AudiobookAuthor:
+        """Validate that an author id was seen and exists."""
+        if author_id not in self._registry.seen_author_ids:
+            msg = f"author_id {author_id} was not returned by search_authors"
+            raise MetadataResolutionError(msg)
+        author = self._registry.get_author(author_id)
+        if author is None:
+            msg = f"author_id {author_id} does not exist"
+            raise MetadataResolutionError(msg)
+        validate_catalog_slug(author.name, "author")
+        return author
+
+    def resolve_book_fields(self, fields: FinalMetadataFields) -> ResolvedBookFields:
+        """Resolve final book fields from a seen book id or created book."""
+        if fields.book_id is None:
+            ensured = self._registry.ensure_book(
+                fields.title,
+                fields.author_id,
+                fields.series_id,
+                fields.series_index,
+            )
+            return ResolvedBookFields(
+                book_id=ensured.book.id,
+                title=ensured.book.title,
+                series_id=ensured.book.series_id,
+                series_index=ensured.book.series_index,
+            )
+
+        if fields.book_id not in self._registry.seen_book_ids:
+            msg = f"book_id {fields.book_id} was not returned by search_books"
+            raise MetadataResolutionError(msg)
+        book = self._registry.get_book(fields.book_id)
+        if book is None:
+            msg = f"book_id {fields.book_id} does not exist"
+            raise MetadataResolutionError(msg)
+        if book.author_id != fields.author_id:
+            msg = f"book_id {fields.book_id} does not belong to author_id {fields.author_id}"
+            raise MetadataResolutionError(msg)
+        return ResolvedBookFields(
+            book_id=fields.book_id,
+            title=book.title,
+            series_id=book.series_id,
+            series_index=book.series_index,
+        )
+
+    def validate_series(self, author_id: int, series_id: int | None, series_index: float) -> str:
+        """Validate final series fields and return the canonical series slug."""
+        if series_id is None:
+            if series_index != 0:
+                msg = "standalone books must use series_index 0"
+                raise MetadataResolutionError(msg)
+            return self._config.standalone_series
+
+        if series_id not in self._registry.seen_series_ids:
+            msg = f"series_id {series_id} was not returned by search_series"
+            raise MetadataResolutionError(msg)
+        series = self._registry.get_series(series_id)
+        if series is None:
+            msg = f"series_id {series_id} does not exist"
+            raise MetadataResolutionError(msg)
+        if series.author_id != author_id:
+            msg = f"series_id {series_id} does not belong to author_id {author_id}"
+            raise MetadataResolutionError(msg)
+        if series_index <= 0:
+            msg = "series books must use a positive series_index"
+            raise MetadataResolutionError(msg)
+        validate_catalog_slug(series.name, "series")
+        return series.name
+
+
+def write_agent_log(log_path: Path, event: str, **fields: object) -> None:
+    """Append one JSONL audit event."""
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    record = {
+        "created": utcnow().isoformat(),
+        "event": event,
+        **{key: json_log_value(value) for key, value in fields.items()},
+    }
+    with log_path.open("a", encoding="utf-8") as file:
+        file.write(json.dumps(record, sort_keys=True))
+        file.write("\n")
+
+
+def json_log_value(value: object) -> object:
+    """Return a JSON-serializable value for audit logs."""
+    if is_dataclass(value) and not isinstance(value, type):
+        return json_log_value(asdict(value))
+    if isinstance(value, dict):
+        return {str(key): json_log_value(item) for key, item in value.items()}
+    if isinstance(value, list | tuple):
+        return [json_log_value(item) for item in value]
+    if isinstance(value, set):
+        return [json_log_value(item) for item in sorted(value, key=str)]
+    if isinstance(value, PathLike):
+        return str(value)
+    return value
+
+
+def system_prompt() -> str:
+    """Return the stable system prompt."""
+    return """You standardize Audible audiobook metadata against a private catalog.
+
+Rules:
+- You must use the provided tools before returning final metadata.
+- Only use author_id, series_id, or book_id values returned by tools.
+- Return final metadata as JSON only. Do not wrap it in Markdown.
+- The final JSON object must contain author_id, book_id, title, series_id, series_index, confidence, and evidence.
+- title must be a canonical title slug using lower-case words separated by hyphens.
+- Use series_id null and series_index 0 for standalone books.
+- If you use a series_id, series_index must be a whole number or .5 value greater than 0.
+- Treat series slugs that differ only by underscores as the same series. Prefer the existing catalog row instead of
+  creating a new series.
+- Detect omnibus or box-set editions that contain multiple numbered novels, books, or novellas.
+- For an omnibus, make a best-effort range from the filename, tags, and catalog rows. Keep series_index as the
+  first covered book number and include the range in the title when the source title includes it, for example
+  books-1-3.
+- Be careful with omnibuses of novels or novellas later published as one book: keep the omnibus as the audiobook's
+  book record unless catalog rows clearly identify a better match.
+- Do not create publisher collections or author collections as series unless the book metadata clearly gives a
+  numbered series.
+- Series belong to authors. Use a series_id only when it belongs to the selected author_id.
+- Always search for the author before creating one. If no exact author slug exists, call ensure_author.
+- Always search for a series with author_id before creating one. If no exact series slug exists, call ensure_series.
+- Always search for a book before creating one. If no exact title slug exists, call ensure_book.
+- If a tool returns an error, correct your tool arguments or final metadata before continuing.
+- confidence must be a number from 0 to 1.
+- evidence must be a short list of strings explaining which filename, tags, and catalog rows support the answer."""
+
+
+def forced_final_prompt() -> str:
+    """Return the no-tools finalization prompt."""
+    return (
+        "Stop calling tools. Return final metadata as JSON only using the tool results already provided. "
+        "If search_books returned no matching rows but author and series are known, use book_id null and resolve "
+        "the title slug from the AAX filename and ffprobe tags. The validator will create the missing book. "
+        "Use only author_id and series_id values returned by earlier tool results."
+    )
+
+
+def user_prompt(aax_file_name: str, metadata: dict[str, str]) -> str:
+    """Build the user prompt from source metadata."""
+    return (
+        "Resolve this Audible audiobook.\n\n"
+        f"AAX file name: {aax_file_name}\n\n"
+        "ffprobe format tags:\n"
+        f"{json.dumps(metadata, indent=2, sort_keys=True)}"
+    )
+
+
+def parse_final_json_content(content: str) -> object:
+    """Parse final model content, accepting bare or fenced JSON."""
+    stripped = content.strip()
+    if match := FENCED_JSON_PATTERN.fullmatch(stripped):
+        stripped = match.group("json").strip()
+    return json.loads(stripped)
+
+
+def parse_final_metadata_fields(raw_metadata: object) -> FinalMetadataFields:
+    """Parse the model's final JSON object into typed fields."""
+    if not isinstance(raw_metadata, dict):
+        msg = "Final metadata must be a JSON object"
+        raise MetadataResolutionError(msg)
+    data = {str(key): value for key, value in raw_metadata.items()}
+    return FinalMetadataFields(
+        author_id=required_int(data, "author_id"),
+        book_id=optional_int(data.get("book_id"), "book_id"),
+        title=required_string(data, "title"),
+        series_id=optional_int(data.get("series_id"), "series_id"),
+        series_index=required_series_index(data, "series_index"),
+        confidence=required_float(data, "confidence"),
+        evidence=required_string_list(data, "evidence"),
+    )
+
+
+def review_metadata(reason: str, config: AgentConfig) -> StandardBookMetadata:
+    """Return a metadata result that must be reviewed manually."""
+    return StandardBookMetadata(
+        author_id=0,
+        author="unknown_author",
+        book_id=None,
+        title="unknown-title",
+        series_id=None,
+        series=config.standalone_series,
+        series_index=0,
+        confidence=0,
+        needs_review=True,
+        evidence=[reason],
+    )
+
+
+def required_float(data: dict[str, object], key: str) -> float:
+    """Read a required float field."""
+    value = data.get(key)
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        msg = f"{key} must be a number"
+        raise MetadataResolutionError(msg)
+    confidence = float(value)
+    if confidence < 0 or confidence > 1:
+        msg = f"{key} must be between 0 and 1"
+        raise MetadataResolutionError(msg)
+    return confidence
+
+
+def required_string_list(data: dict[str, object], key: str) -> list[str]:
+    """Read a required list of strings."""
+    value = data.get(key)
+    if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
+        msg = f"{key} must be a non-empty list of strings"
+        raise MetadataResolutionError(msg)
+    strings = [item.strip() for item in value if item.strip()]
+    if not strings:
+        msg = f"{key} must include at least one non-empty string"
+        raise MetadataResolutionError(msg)
+    return strings

python/tools/installer.py

@@ -1,3 +1,4 @@
+# ruff: noqa: LOG015, E501, D102, D103, D107 These need the be fixed
 """Install NixOS on a ZFS pool."""
 
 from __future__ import annotations
@@ -19,6 +20,7 @@ if TYPE_CHECKING:
 
 def configure_logger(level: str = "INFO") -> None:
     """Configure the logger.
+
     Args:
         level (str, optional): The logging level. Defaults to "INFO".
     """
@@ -32,15 +34,17 @@ def configure_logger(level: str = "INFO") -> None:
 
 def bash_wrapper(command: str) -> str:
     """Execute a bash command and capture the output.
+
     Args:
         command (str): The bash command to be executed.
+
     Returns:
         Tuple[str, int]: A tuple containing the output of the command (stdout) as a string,
         the error output (stderr) as a string (optional), and the return code as an integer.
     """
     logging.debug(f"running {command=}")
     # This is a acceptable risk
-    process = Popen(command.split(), stdout=PIPE, stderr=PIPE)  # noqa: S603
+    process = Popen(command.split(), stdout=PIPE, stderr=PIPE)
     output, _ = process.communicate()
     if process.returncode != 0:
         error = f"Failed to run command {command=} return code {process.returncode=}"
@@ -51,6 +55,7 @@ def bash_wrapper(command: str) -> str:
 
 def partition_disk(disk: str, swap_size: int, reserve: int = 0) -> None:
     """Partition a disk.
+
     Args:
         disk (str): The disk to partition.
         swap_size (int): The size of the swap partition in GB.
@@ -92,8 +97,9 @@ def partition_disk(disk: str, swap_size: int, reserve: int = 0) -> None:
 
 def create_zfs_pool(pool_disks: Sequence[str], mnt_dir: str) -> None:
     """Create a ZFS pool.
+
     Args:
-        disks (Sequence[str]): A tuple of disks to use for the pool.
+        pool_disks (Sequence[str]): A tuple of disks to use for the pool.
         mnt_dir (str): The mount directory.
     """
     if len(pool_disks) <= 0:
@@ -131,7 +137,6 @@ def create_zfs_pool(pool_disks: Sequence[str], mnt_dir: str) -> None:
 
 def create_zfs_datasets() -> None:
     """Create ZFS datasets."""
-
     bash_wrapper("zfs create -o canmount=noauto -o reservation=10G root_pool/root")
     bash_wrapper("zfs create root_pool/home")
     bash_wrapper("zfs create root_pool/var -o reservation=1G")
@@ -160,6 +165,9 @@ def get_cpu_manufacturer() -> str:
         if "vendor_id" in line:
             return id_vendor[line.split(": ")[1].strip()]
 
+    error = "CPU manufacturer not found"
+    raise RuntimeError(error)
+
 
 def get_boot_drive_id(disk: str) -> str:
     """Get the boot drive ID."""
@@ -167,9 +175,8 @@ def get_boot_drive_id(disk: str) -> str:
     return output.splitlines()[1]
 
 
-def create_nix_hardware_file(mnt_dir: str, disks: Sequence[str], encrypt: bool) -> None:
+def create_nix_hardware_file(mnt_dir: str, disks: Sequence[str], *, encrypt: bool) -> None:
     """Create a NixOS hardware file."""
-
     cpu_manufacturer = get_cpu_manufacturer()
 
     devices = ""
@@ -219,7 +226,7 @@ def create_nix_hardware_file(mnt_dir: str, disks: Sequence[str], encrypt: bool)
     Path(f"{mnt_dir}/etc/nixos/hardware-configuration.nix").write_text(nix_hardware)
 
 
-def install_nixos(mnt_dir: str, disks: Sequence[str], encrypt: bool) -> None:
+def install_nixos(mnt_dir: str, disks: Sequence[str], *, encrypt: bool) -> None:
     """Install NixOS."""
     bash_wrapper(f"mount -o X-mount.mkdir -t zfs root_pool/root {mnt_dir}")
     bash_wrapper(f"mount -o X-mount.mkdir -t zfs root_pool/home {mnt_dir}/home")
@@ -230,14 +237,16 @@ def install_nixos(mnt_dir: str, disks: Sequence[str], encrypt: bool) -> None:
         bash_wrapper(f"mkfs.vfat -n EFI {disk}-part1")
 
     # set up mirroring afterwards if more than one disk
-    boot_partition = f"mount -t vfat -o fmask=0077,dmask=0077,iocharset=iso8859-1,X-mount.mkdir {disks[0]}-part1 {mnt_dir}/boot"
+    boot_partition = (
+        f"mount -t vfat -o fmask=0077,dmask=0077,iocharset=iso8859-1,X-mount.mkdir {disks[0]}-part1 {mnt_dir}/boot"
+    )
     bash_wrapper(boot_partition)
 
     bash_wrapper(f"nixos-generate-config --root {mnt_dir}")
 
-    create_nix_hardware_file(mnt_dir, disks, encrypt)
+    create_nix_hardware_file(mnt_dir, disks, encrypt=encrypt)
 
-    run(("nixos-install", "--root", mnt_dir), check=True)  # noqa: S603
+    run(("nixos-install", "--root", mnt_dir), check=True)
 
 
 def installer(
@@ -258,16 +267,14 @@ def installer(
                 f'printf "{encrypt_key}" | cryptsetup luksFormat --type luks2 {disk}-part2 -',
                 f'printf "{encrypt_key}" | cryptsetup luksOpen {disk}-part2 luks-root-pool-{disk.split("/")[-1]}-part2 -',
             ):
-                run(command, shell=True, check=True)
+                run(command, shell=True, check=True)  # noqa: S602
 
     mnt_dir = "/tmp/nix_install"  # noqa: S108
 
     Path(mnt_dir).mkdir(parents=True, exist_ok=True)
 
     if encrypt_key:
-        pool_disks = [
-            f"/dev/mapper/luks-root-pool-{disk.split('/')[-1]}-part2" for disk in disks
-        ]
+        pool_disks = [f"/dev/mapper/luks-root-pool-{disk.split('/')[-1]}-part2" for disk in disks]
     else:
         pool_disks = [f"{disk}-part2" for disk in disks]
 
@@ -275,22 +282,24 @@ def installer(
 
     create_zfs_datasets()
 
-    install_nixos(mnt_dir, disks, encrypt_key)
+    install_nixos(mnt_dir, disks, encrypt=encrypt_key)
 
     logging.info("Installation complete")
 
 
 class Cursor:
-    def __init__(self):
+    """Cursor class to store the cursor position."""
+
+    def __init__(self) -> None:
         self.x_position = 0
         self.y_position = 0
         self.height = 0
         self.width = 0
 
-    def set_height(self, height: int):
+    def set_height(self, height: int) -> None:
         self.height = height
 
-    def set_width(self, width: int):
+    def set_width(self, width: int) -> None:
         self.width = width
 
     def x_bounce_check(self, cursor: int) -> int:
@@ -301,10 +310,10 @@ class Cursor:
         cursor = max(0, cursor)
         return min(self.height - 1, cursor)
 
-    def set_x(self, x: int):
+    def set_x(self, x: int) -> None:
         self.x_position = self.x_bounce_check(x)
 
-    def set_y(self, y: int):
+    def set_y(self, y: int) -> None:
         self.y_position = self.y_bounce_check(y)
 
     def get_x(self) -> int:
@@ -313,16 +322,16 @@ class Cursor:
     def get_y(self) -> int:
         return self.y_position
 
-    def move_up(self):
+    def move_up(self) -> None:
         self.set_y(self.y_position - 1)
 
-    def move_down(self):
+    def move_down(self) -> None:
         self.set_y(self.y_position + 1)
 
-    def move_left(self):
+    def move_left(self) -> None:
         self.set_x(self.x_position - 1)
 
-    def move_right(self):
+    def move_right(self) -> None:
         self.set_x(self.x_position + 1)
 
     def navigation(self, key: int) -> None:
@@ -339,7 +348,7 @@ class Cursor:
 class State:
     """State class to store the state of the program."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         self.key = 0
         self.cursor = Cursor()
 
@@ -358,10 +367,7 @@ class State:
 
 def get_device(raw_device: str) -> dict[str, str]:
     raw_device_components = raw_device.split(" ")
-    return {
-        thing.split("=")[0].lower(): thing.split("=")[1].strip('"')
-        for thing in raw_device_components
-    }
+    return {thing.split("=")[0].lower(): thing.split("=")[1].strip('"') for thing in raw_device_components}
 
 
 def get_devices() -> list[dict[str, str]]:
@@ -373,6 +379,7 @@ def get_devices() -> list[dict[str, str]]:
 
 def get_device_id_mapping() -> dict[str, set[str]]:
     """Get a list of device ids.
+
     Returns:
         list[str]: the list of device ids
     """
@@ -387,9 +394,7 @@ def get_device_id_mapping() -> dict[str, set[str]]:
     return device_id_mapping
 
 
-def calculate_device_menu_padding(
-    devices: list[dict[str, str]], column: str, padding: int = 0
-) -> int:
+def calculate_device_menu_padding(devices: list[dict[str, str]], column: str, padding: int = 0) -> int:
     return max(len(device[column]) for device in devices) + padding
 
 
@@ -430,7 +435,8 @@ def draw_device_menu(
     menu_start_y: int = 0,
     menu_start_x: int = 0,
 ) -> State:
-    """draw the device menu and handle user input
+    """Draw the device menu and handle user input.
+
     Args:
         std_screen (curses.window): the curses window to draw on
         devices (list[dict[str, str]]): the list of devices to draw
@@ -438,6 +444,7 @@ def draw_device_menu(
         state (State): the state object to update
         menu_start_y (int, optional): the y position to start drawing the menu. Defaults to 0.
         menu_start_x (int, optional): the x position to start drawing the menu. Defaults to 0.
+
     Returns:
         State: the updated state object
     """
@@ -448,7 +455,9 @@ def draw_device_menu(
     type_padding = calculate_device_menu_padding(devices, "type", padding)
     mountpoints_padding = calculate_device_menu_padding(devices, "mountpoints", padding)
 
-    device_header = f"{'Name':{name_padding}}{'Size':{size_padding}}{'Type':{type_padding}}{'Mountpoints':{mountpoints_padding}}"
+    device_header = (
+        f"{'Name':{name_padding}}{'Size':{size_padding}}{'Type':{type_padding}}{'Mountpoints':{mountpoints_padding}}"
+    )
 
     menu_width = range(menu_start_x, len(device_header) + menu_start_x)
 
@@ -482,7 +491,7 @@ def draw_device_menu(
 
 def debug_menu(std_screen: curses.window, key: int) -> None:
     height, width = std_screen.getmaxyx()
-    width_height = "Width: {}, Height: {}".format(width, height)
+    width_height = f"Width: {width}, Height: {height}"
     std_screen.addstr(height - 4, 0, width_height, curses.color_pair(5))
 
     key_pressed = f"Last key pressed: {key}"[: width - 1]
@@ -490,7 +499,7 @@ def debug_menu(std_screen: curses.window, key: int) -> None:
         key_pressed = "No key press detected..."[: width - 1]
     std_screen.addstr(height - 3, 0, key_pressed)
 
-    for i in range(0, 8):
+    for i in range(8):
         std_screen.addstr(height - 2, i * 3, f"{i}██", curses.color_pair(i))
 
 
@@ -503,9 +512,7 @@ def status_bar(
     std_screen.attron(curses.A_REVERSE)
     std_screen.attron(curses.color_pair(3))
 
-    status_bar = (
-        f"Press 'q' to exit | STATUS BAR | Pos: {cursor.get_x()}, {cursor.get_y()}"
-    )
+    status_bar = f"Press 'q' to exit | STATUS BAR | Pos: {cursor.get_x()}, {cursor.get_y()}"
     std_screen.addstr(height - 1, 0, status_bar)
     std_screen.addstr(height - 1, len(status_bar), " " * (width - len(status_bar) - 1))
 
@@ -516,7 +523,7 @@ def status_bar(
 def set_color() -> None:
     curses.start_color()
     curses.use_default_colors()
-    for i in range(0, curses.COLORS):
+    for i in range(curses.COLORS):
         curses.init_pair(i + 1, i, -1)
 
 
@@ -528,10 +535,10 @@ def get_text_input(std_screen: curses.window, prompt: str, y: int, x: int) -> st
         key = std_screen.getch()
         if key == ord("\n"):
             break
-        elif key == 27:  # ESC key
+        if key == 27:  # ESC key  # noqa: PLR2004
             input_str = ""
             break
-        elif key in (curses.KEY_BACKSPACE, ord("\b"), 127):
+        if key in (curses.KEY_BACKSPACE, ord("\b"), 127):
             input_str = input_str[:-1]
             std_screen.addstr(y, x + len(prompt), input_str + " ")
         else:
@@ -557,9 +564,7 @@ def swap_size_input(
             state.swap_size = int(swap_size_str)
             state.show_swap_input = False
         except ValueError:
-            std_screen.addstr(
-                swap_offset, 0, "Invalid input. Press any key to continue."
-            )
+            std_screen.addstr(swap_offset, 0, "Invalid input. Press any key to continue.")
             std_screen.getch()
             state.show_swap_input = False
 
@@ -577,16 +582,12 @@ def reserve_size_input(
         state.show_reserve_input = True
 
     if state.show_reserve_input:
-        reserve_size_str = get_text_input(
-            std_screen, reserve_size_text, reserve_offset, 0
-        )
+        reserve_size_str = get_text_input(std_screen, reserve_size_text, reserve_offset, 0)
         try:
             state.reserve_size = int(reserve_size_str)
             state.show_reserve_input = False
         except ValueError:
-            std_screen.addstr(
-                reserve_offset, 0, "Invalid input. Press any key to continue."
-            )
+            std_screen.addstr(reserve_offset, 0, "Invalid input. Press any key to continue.")
             std_screen.getch()
             state.show_reserve_input = False
 
@@ -594,7 +595,8 @@ def reserve_size_input(
 
 
 def draw_menu(std_screen: curses.window) -> State:
-    """draw the menu and handle user input
+    """Draw the menu and handle user input.
+
     Args:
         std_screen (curses.window): the curses window to draw on
     Returns:

systems/bob/default.nix

@@ -7,6 +7,7 @@
     "${inputs.self}/common/global"
     "${inputs.self}/common/optional/docker.nix"
     "${inputs.self}/common/optional/scanner.nix"
+    "${inputs.self}/common/optional/monitoring-agent.nix"
     "${inputs.self}/common/optional/steam.nix"
     "${inputs.self}/common/optional/syncthing_base.nix"
     "${inputs.self}/common/optional/systemd-boot.nix"
@@ -27,7 +28,12 @@
   networking = {
     hostName = "bob";
     hostId = "7c678a41";
-    firewall.enable = true;
+    firewall = {
+      enable = true;
+      allowedTCPPorts = [
+        8000
+      ];
+    };
     networkmanager.enable = true;
   };
 

systems/bob/hardware.nix

@@ -30,6 +30,11 @@
         keyFile = "/dev/disk/by-id/usb-Samsung_Flash_Drive_FIT_0374620080067131-0:0";
       };
     };
+
+    zfs.extraPools = [
+      "storage"
+    ];
+
     kernelModules = [ "kvm-amd" ];
     extraModulePackages = [ ];
   };

systems/bob/llms.nix

@@ -4,7 +4,7 @@
     host = "0.0.0.0";
     enable = true;
 
-    syncModels = true;
+    syncModels = false;
     loadModels = [
       "codellama:7b"
       "deepscaler:1.5b"
@@ -42,11 +42,12 @@
       "qwen3:8b"
       "qwen3.5:27b"
       "qwen3.5:35b"
+      "qwen3.6:27b"
       "qwen3.6:35b"
+      "rinex20/translategemma3:12b"
       "translategemma:12b"
       "translategemma:27b"
       "translategemma:4b"
-      "rinex20/translategemma3:12b"
     ];
     models = "/zfs/storage/models";
     openFirewall = true;

systems/jeeves/default.nix

@@ -10,10 +10,12 @@ in
     "${inputs.self}/users/steve"
     "${inputs.self}/common/global"
     "${inputs.self}/common/optional/docker.nix"
+    "${inputs.self}/common/optional/monitoring-agent.nix"
     "${inputs.self}/common/optional/ssh_decrypt.nix"
     "${inputs.self}/common/optional/syncthing_base.nix"
     "${inputs.self}/common/optional/update.nix"
     "${inputs.self}/common/optional/zerotier.nix"
+    ./monitoring
     ./docker
     ./services
     ./web_services

systems/jeeves/monitoring/dashboards/overview.json

@@ -0,0 +1,426 @@
+{
+  "annotations": {
+    "list": [
+      {
+        "builtIn": 1,
+        "datasource": {
+          "type": "grafana",
+          "uid": "-- Grafana --"
+        },
+        "enable": true,
+        "hide": true,
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "name": "Annotations & Alerts",
+        "type": "dashboard"
+      }
+    ]
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "links": [],
+  "panels": [
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 6,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "100 * (1 - avg by (instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])))",
+          "legendFormat": "{{instance}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "CPU Used",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 6,
+        "x": 6,
+        "y": 0
+      },
+      "id": 2,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "100 * (1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes))",
+          "legendFormat": "{{instance}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "RAM Used",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 6,
+        "x": 12,
+        "y": 0
+      },
+      "id": 3,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "100 * (1 - (node_memory_SwapFree_bytes / node_memory_SwapTotal_bytes))",
+          "legendFormat": "{{instance}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Swap Used",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 6,
+        "x": 18,
+        "y": 0
+      },
+      "id": 4,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "node_load1",
+          "legendFormat": "{{instance}} load1",
+          "range": true,
+          "refId": "A"
+        },
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "node_load5",
+          "legendFormat": "{{instance}} load5",
+          "range": true,
+          "refId": "B"
+        },
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "node_load15",
+          "legendFormat": "{{instance}} load15",
+          "range": true,
+          "refId": "C"
+        }
+      ],
+      "title": "Load",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "Bps"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 9,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "id": 5,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "sum by (instance) (rate(node_disk_read_bytes_total[5m]))",
+          "legendFormat": "{{instance}} read",
+          "range": true,
+          "refId": "A"
+        },
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "sum by (instance) (rate(node_disk_written_bytes_total[5m]))",
+          "legendFormat": "{{instance}} write",
+          "range": true,
+          "refId": "B"
+        }
+      ],
+      "title": "Disk Throughput",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 9,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "id": 6,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "100 * (1 - (node_filesystem_avail_bytes{mountpoint=~\"(/|/home|/var|/zfs.*)\",fstype!=\"\"} / node_filesystem_size_bytes{mountpoint=~\"(/|/home|/var|/zfs.*)\",fstype!=\"\"}))",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{mountpoint}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Filesystem Usage",
+      "type": "table"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 0,
+        "y": 17
+      },
+      "id": 7,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(10, rate(namedprocess_namegroup_cpu_seconds_total[5m]))",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{groupname}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Top Grouped CPU",
+      "type": "table"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 12,
+        "y": 17
+      },
+      "id": 8,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(10, namedprocess_namegroup_memory_bytes{memtype=\"resident\"})",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{groupname}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Top Grouped Memory",
+      "type": "table"
+    }
+  ],
+  "refresh": "30s",
+  "schemaVersion": 39,
+  "style": "dark",
+  "tags": [
+    "monitoring"
+  ],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-24h",
+    "to": "now"
+  },
+  "timepicker": {},
+  "timezone": "",
+  "title": "Overview",
+  "uid": "monitor-overview",
+  "version": 1,
+  "weekStart": ""
+}

systems/jeeves/monitoring/dashboards/process-history-grouped.json

@@ -0,0 +1,216 @@
+{
+  "annotations": {
+    "list": [
+      {
+        "builtIn": 1,
+        "datasource": {
+          "type": "grafana",
+          "uid": "-- Grafana --"
+        },
+        "enable": true,
+        "hide": true,
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "name": "Annotations & Alerts",
+        "type": "dashboard"
+      }
+    ]
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "links": [],
+  "panels": [
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(10, rate(namedprocess_namegroup_cpu_seconds_total[5m]))",
+          "legendFormat": "{{instance}} {{groupname}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Grouped CPU",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "id": 2,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(10, namedprocess_namegroup_memory_bytes{memtype=\"resident\"})",
+          "legendFormat": "{{instance}} {{groupname}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Grouped Resident Memory",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "Bps"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 0,
+        "y": 10
+      },
+      "id": 3,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(10, rate(namedprocess_namegroup_read_bytes_total[5m]))",
+          "legendFormat": "{{instance}} {{groupname}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Grouped Read I/O",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "Bps"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 12,
+        "y": 10
+      },
+      "id": 4,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(10, rate(namedprocess_namegroup_write_bytes_total[5m]))",
+          "legendFormat": "{{instance}} {{groupname}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Grouped Write I/O",
+      "type": "timeseries"
+    }
+  ],
+  "refresh": "30s",
+  "schemaVersion": 39,
+  "style": "dark",
+  "tags": [
+    "monitoring",
+    "process"
+  ],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-7d",
+    "to": "now"
+  },
+  "timepicker": {},
+  "timezone": "",
+  "title": "Process History Grouped",
+  "uid": "monitor-process-history",
+  "version": 1,
+  "weekStart": ""
+}

systems/jeeves/monitoring/dashboards/process-live-pid.json

@@ -0,0 +1,224 @@
+{
+  "annotations": {
+    "list": [
+      {
+        "builtIn": 1,
+        "datasource": {
+          "type": "grafana",
+          "uid": "-- Grafana --"
+        },
+        "enable": true,
+        "hide": true,
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "name": "Annotations & Alerts",
+        "type": "dashboard"
+      }
+    ]
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "links": [],
+  "panels": [
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-pid-short"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-pid-short"
+          },
+          "editorMode": "code",
+          "expr": "topk(20, rate(namedprocess_namegroup_cpu_seconds_total[2m]))",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{groupname}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Top PID CPU",
+      "type": "table"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-pid-short"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "id": 2,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-pid-short"
+          },
+          "editorMode": "code",
+          "expr": "topk(20, namedprocess_namegroup_memory_bytes{memtype=\"resident\"})",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{groupname}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Top PID RSS",
+      "type": "table"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-pid-short"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "Bps"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 0,
+        "y": 10
+      },
+      "id": 3,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-pid-short"
+          },
+          "editorMode": "code",
+          "expr": "topk(20, rate(namedprocess_namegroup_read_bytes_total[2m]))",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{groupname}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Top PID Read I/O",
+      "type": "table"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-pid-short"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "Bps"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 12,
+        "x": 12,
+        "y": 10
+      },
+      "id": 4,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-pid-short"
+          },
+          "editorMode": "code",
+          "expr": "topk(20, rate(namedprocess_namegroup_write_bytes_total[2m]))",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{groupname}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Top PID Write I/O",
+      "type": "table"
+    }
+  ],
+  "refresh": "15s",
+  "schemaVersion": 39,
+  "style": "dark",
+  "tags": [
+    "monitoring",
+    "process"
+  ],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-10m",
+    "to": "now"
+  },
+  "timepicker": {},
+  "timezone": "",
+  "title": "Process Live PID",
+  "uid": "monitor-process-pid",
+  "version": 1,
+  "weekStart": ""
+}

systems/jeeves/monitoring/dashboards/storage-zfs.json

@@ -0,0 +1,351 @@
+{
+  "annotations": {
+    "list": [
+      {
+        "builtIn": 1,
+        "datasource": {
+          "type": "grafana",
+          "uid": "-- Grafana --"
+        },
+        "enable": true,
+        "hide": true,
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "name": "Annotations & Alerts",
+        "type": "dashboard"
+      }
+    ]
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "links": [],
+  "panels": [
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 8,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "100 * (zfs_pool_allocated_bytes / zfs_pool_size_bytes)",
+          "legendFormat": "{{instance}} {{pool}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Pool Usage",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 8,
+        "x": 8,
+        "y": 0
+      },
+      "id": 2,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "zfs_pool_free_bytes",
+          "legendFormat": "{{instance}} {{pool}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Pool Free Bytes",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 8,
+        "x": 16,
+        "y": 0
+      },
+      "id": 3,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(20, zfs_dataset_used_bytes{type=\"filesystem\"})",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{name}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Top Filesystems by Used Bytes",
+      "type": "table"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ns"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 9,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "id": 4,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(20, zpool_iostat_total_wait_read_ns{vdev!=\"_pool\"})",
+          "legendFormat": "{{host}} {{pool}} {{vdev}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "ZFS Read Wait",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ns"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 9,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "id": 5,
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "topk(20, zpool_iostat_total_wait_write_ns{vdev!=\"_pool\"})",
+          "legendFormat": "{{host}} {{pool}} {{vdev}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "ZFS Write Wait",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "celsius"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 9,
+        "w": 12,
+        "x": 0,
+        "y": 17
+      },
+      "id": 6,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "smartctl_device_temperature{temperature_type=\"current\"}",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{device}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Disk Temperature",
+      "type": "table"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prom-main"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 9,
+        "w": 12,
+        "x": 12,
+        "y": 17
+      },
+      "id": 7,
+      "options": {
+        "cellHeight": "sm",
+        "showHeader": true,
+        "sortBy": [
+          {
+            "desc": false,
+            "displayName": "Value"
+          }
+        ]
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prom-main"
+          },
+          "editorMode": "code",
+          "expr": "smartctl_device_smart_status",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "{{instance}} {{device}}",
+          "refId": "A"
+        }
+      ],
+      "title": "SMART Health",
+      "type": "table"
+    }
+  ],
+  "refresh": "30s",
+  "schemaVersion": 39,
+  "style": "dark",
+  "tags": [
+    "monitoring",
+    "zfs"
+  ],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-24h",
+    "to": "now"
+  },
+  "timepicker": {},
+  "timezone": "",
+  "title": "Storage and ZFS",
+  "uid": "monitor-storage",
+  "version": 1,
+  "weekStart": ""
+}

systems/jeeves/monitoring/default.nix

@@ -0,0 +1,186 @@
+{
+  lib,
+  pkgs,
+  ...
+}:
+let
+  vars = import ../vars.nix;
+
+  prometheusDataRoot = "${vars.database}/prometheus";
+  mainPrometheusDataDir = "${prometheusDataRoot}/main";
+  pidPrometheusDataDir = "${prometheusDataRoot}/pid-short";
+
+  prometheusYaml = pkgs.formats.yaml { };
+
+  mkPrometheusConfig =
+    name: cfg:
+    let
+      configFile = prometheusYaml.generate "${name}.yaml" cfg;
+    in
+    pkgs.runCommand "${name}-checked.yaml"
+      {
+        nativeBuildInputs = [ pkgs.prometheus.cli ];
+      }
+      ''
+        promtool check config ${configFile}
+        cp ${configFile} $out
+      '';
+
+  mkTarget = host: address: {
+    targets = [ address ];
+    labels.instance = host;
+  };
+
+  mainPrometheusConfig = mkPrometheusConfig "prometheus-main" {
+    global = {
+      scrape_interval = "30s";
+      scrape_timeout = "10s";
+      evaluation_interval = "30s";
+    };
+    scrape_configs = [
+      {
+        job_name = "node";
+        static_configs = [
+          (mkTarget "jeeves" "192.168.90.40:9100")
+          (mkTarget "bob" "192.168.90.25:9100")
+        ];
+      }
+      {
+        job_name = "process_grouped";
+        static_configs = [
+          (mkTarget "jeeves" "192.168.90.40:9256")
+          (mkTarget "bob" "192.168.90.25:9256")
+        ];
+      }
+      {
+        job_name = "smartctl";
+        static_configs = [
+          (mkTarget "jeeves" "192.168.90.40:9633")
+          (mkTarget "bob" "192.168.90.25:9633")
+        ];
+      }
+      {
+        job_name = "zfs";
+        static_configs = [
+          (mkTarget "jeeves" "192.168.90.40:9134")
+          (mkTarget "bob" "192.168.90.25:9134")
+        ];
+      }
+    ];
+  };
+
+  pidPrometheusConfig = mkPrometheusConfig "prometheus-pid-short" {
+    global = {
+      scrape_interval = "15s";
+      scrape_timeout = "10s";
+      evaluation_interval = "15s";
+    };
+    scrape_configs = [
+      {
+        job_name = "process_pid";
+        static_configs = [
+          (mkTarget "jeeves" "192.168.90.40:9257")
+          (mkTarget "bob" "192.168.90.25:9257")
+        ];
+      }
+    ];
+  };
+
+  mkPrometheusService =
+    {
+      dataDir,
+      configFile,
+      port,
+      retention,
+    }:
+    {
+      after = [
+        "zfs-media-database-prometheus.mount"
+        "network.target"
+      ];
+      requires = [ "zfs-media-database-prometheus.mount" ];
+      wantedBy = [ "multi-user.target" ];
+      unitConfig.RequiresMountsFor = [ dataDir ];
+      serviceConfig = {
+        ExecStart = "${lib.getExe pkgs.prometheus} ${
+          lib.escapeShellArgs [
+            "--config.file=${configFile}"
+            "--storage.tsdb.path=${dataDir}"
+            "--storage.tsdb.retention.time=${retention}"
+            "--web.listen-address=127.0.0.1:${toString port}"
+          ]
+        }";
+        User = "prometheus";
+        Group = "prometheus";
+        Restart = "always";
+        RestartSec = "5s";
+        WorkingDirectory = dataDir;
+        ReadWritePaths = [ dataDir ];
+        CapabilityBoundingSet = [ "" ];
+        DeviceAllow = [ "/dev/null rw" ];
+        DevicePolicy = "strict";
+        LockPersonality = true;
+        MemoryDenyWriteExecute = true;
+        NoNewPrivileges = true;
+        PrivateDevices = true;
+        PrivateTmp = true;
+        ProtectClock = true;
+        ProtectControlGroups = true;
+        ProtectHome = true;
+        ProtectHostname = true;
+        ProtectKernelLogs = true;
+        ProtectKernelModules = true;
+        ProtectKernelTunables = true;
+        ProtectProc = "invisible";
+        ProtectSystem = "strict";
+        RemoveIPC = true;
+        RestrictAddressFamilies = [
+          "AF_INET"
+          "AF_INET6"
+          "AF_UNIX"
+        ];
+        RestrictNamespaces = true;
+        RestrictRealtime = true;
+        RestrictSUIDSGID = true;
+        SystemCallArchitectures = "native";
+        SystemCallFilter = [
+          "@system-service"
+          "~@privileged"
+        ];
+      };
+    };
+in
+{
+  users = {
+    groups.prometheus = { };
+    users.prometheus = {
+      isSystemUser = true;
+      group = "prometheus";
+      description = "Prometheus daemon user";
+    };
+  };
+
+  systemd = {
+    services = {
+      prometheus-main = mkPrometheusService {
+        configFile = mainPrometheusConfig;
+        dataDir = mainPrometheusDataDir;
+        port = 9090;
+        retention = "90d";
+      };
+
+      prometheus-pid-short = mkPrometheusService {
+        configFile = pidPrometheusConfig;
+        dataDir = pidPrometheusDataDir;
+        port = 9092;
+        retention = "10m";
+      };
+    };
+
+    tmpfiles.rules = [
+      "d ${prometheusDataRoot} 0755 root root - -"
+      "d ${mainPrometheusDataDir} 0750 prometheus prometheus - -"
+      "d ${pidPrometheusDataDir} 0750 prometheus prometheus - -"
+    ];
+  };
+}

systems/jeeves/networking.nix

@@ -1,4 +1,13 @@
 {
+  # Docker loads br_netfilter on jeeves. Disable bridge netfilter so
+  # br-nix-builder behaves like a pure L2 bridge and bridged traffic
+  # does not hit the host firewall/rpfilter path.
+  boot.kernel.sysctl = {
+    "net.bridge.bridge-nf-call-arptables" = 0;
+    "net.bridge.bridge-nf-call-ip6tables" = 0;
+    "net.bridge.bridge-nf-call-iptables" = 0;
+  };
+
   networking = {
     hostName = "jeeves";
     hostId = "0e15ce35";
@@ -34,11 +43,18 @@
       };
     };
     networks = {
-      "10-1GB_Primary" = {
-        matchConfig.Name = "enp97s0f1";
+      "10-Primary" = {
+        matchConfig.Name = "enp97s0";
         address = [ "192.168.99.14/24" ];
+        dns = [
+          "192.168.99.1"
+          "2600:4040:abfb:d700::1"
+        ];
         routes = [ { Gateway = "192.168.99.1"; } ];
         vlan = [ "internet-vlan" ];
+        dhcpV4Config.UseDNS = false;
+        dhcpV6Config.UseDNS = false;
+        ipv6AcceptRAConfig.UseDNS = false;
         linkConfig.RequiredForOnline = "routable";
       };
       "50-internet-vlan" = {
@@ -49,23 +65,10 @@
       "60-br-nix-builder" = {
         matchConfig.Name = "br-nix-builder";
         bridgeConfig = { };
-        address = [ "192.168.3.10/24" ];
-        routingPolicyRules = [
-          {
-            From = "192.168.3.0/24";
-            Table = 100;
-            Priority = 100;
-          }
-        ];
-        routes = [
-          {
-            Gateway = "192.168.3.1";
-            Table = 100;
-            GatewayOnLink = false;
-            Metric = 2048;
-            PreferredSource = "192.168.3.10";
-          }
-        ];
+        networkConfig = {
+          IPv6AcceptRA = false;
+          LinkLocalAddressing = "no";
+        };
         linkConfig.RequiredForOnline = "no";
       };
     };

systems/jeeves/programs.nix

@@ -3,5 +3,6 @@
   environment.systemPackages = with pkgs; [
     filebot
     docker-compose
+    ffmpeg
   ];
 }

systems/jeeves/runners/default.nix

@@ -1,20 +1,7 @@
-{ pkgs, ... }:
+{ ... }:
 {
   imports = [ ./nix_builder.nix ];
 
-  users = {
-    users.github-runners = {
-      shell = pkgs.bash;
-      isSystemUser = true;
-      group = "github-runners";
-      uid = 601;
-      openssh.authorizedKeys.keys = [
-        "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIA/S8i+BNX/12JNKg+5EKGX7Aqimt5KM+ve3wt/SyWuO github-runners" # cspell:disable-line
-      ];
-    };
-    groups.github-runners.gid = 601;
-  };
-
   services.nix_builder.containers = {
     nix-builder-00.enable = true;
     nix-builder-01.enable = true;

systems/jeeves/runners/nix_builder.nix

@@ -2,6 +2,7 @@
   config,
   lib,
   outputs,
+  utils,
   ...
 }:
 
@@ -9,6 +10,8 @@ with lib;
 let
   vars = import ../vars.nix;
   cfg = config.services.nix_builder;
+  runnerUsername = "gitea-runner";
+  runnerUserid = 601;
 in
 {
   options.services.nix_builder = {
@@ -23,37 +26,40 @@ in
         types.submodule (
           { name, ... }:
           {
-            options.enable = mkEnableOption "GitHub runner container";
+            options.enable = mkEnableOption "Gitea runner container";
           }
         )
       );
       default = { };
-      description = "GitHub runner container configurations";
+      description = "Gitea runner container configurations";
     };
   };
 
   config = {
+    users = {
+      users.${runnerUsername} = {
+        isSystemUser = true;
+        group = runnerUsername;
+        uid = runnerUserid;
+      };
+      groups.${runnerUsername}.gid = runnerUserid;
+    };
+
     containers = mapAttrs (
       name: containerCfg:
       mkIf containerCfg.enable {
         autoStart = true;
         privateNetwork = true;
         hostBridge = cfg.bridgeName;
-        ephemeral = true;
         bindMounts = {
-          storage = {
-            hostPath = "/zfs/media/github-runners/${name}";
-            mountPoint = "/zfs/media/github-runners/${name}";
-            isReadOnly = false;
-          };
           host-nix = {
             mountPoint = "/host-nix/var/nix/daemon-socket";
             hostPath = "/nix/var/nix/daemon-socket";
             isReadOnly = false;
           };
-          pat = {
-            hostPath = "${vars.secrets}/services/github-runners/runner_pat";
-            mountPoint = "${vars.secrets}/services/github-runners/runner_pat";
+          token = {
+            hostPath = "${vars.secrets}/services/gitea-runners";
+            mountPoint = "/run/secrets/gitea-runners";
             isReadOnly = true;
           };
         };
@@ -92,46 +98,69 @@ in
                 "nix-command"
               ];
               sandbox = true;
-              allowed-users = [ "github-runners" ];
+              allowed-users = [ "gitea-runner" ];
               trusted-users = [
                 "root"
-                "github-runners"
+                "gitea-runner"
               ];
             };
             nixpkgs = {
               overlays = builtins.attrValues outputs.overlays;
               config.allowUnfree = true;
             };
-            services.github-runners.${name} = {
+            users = {
+              users.${runnerUsername} = {
+                isSystemUser = true;
+                group = runnerUsername;
+                uid = runnerUserid;
+              };
+              groups.${runnerUsername}.gid = runnerUserid;
+            };
+            services.gitea-actions-runner.instances.${name} = {
               enable = true;
-              replace = true;
-              workDir = "/zfs/media/github-runners/${name}";
-              url = "https://github.com/RichieCahill/dotfiles";
-              extraLabels = [ "nixos" ];
-              tokenFile = "${vars.secrets}/services/github-runners/runner_pat";
-              user = "github-runners";
-              group = "github-runners";
-              extraPackages = with pkgs; [
+              name = "jeeves-${name}";
+              url = "http://192.168.99.14:6443/";
+              labels = [
+                "self-hosted:host"
+                "nixos:host"
+              ];
+              tokenFile = "/run/secrets/gitea-runners/registration-token";
+              hostPackages = with pkgs; [
+                bash
+                coreutils
+                curl
+                gawk
                 gitMinimal
-                gh
+                gnused
+                my_python
+                nix
                 nixfmt
                 nixos-rebuild
+                nodejs
                 treefmt
-                my_python
+                wget
               ];
             };
-            users = {
-              users.github-runners = {
-                shell = pkgs.bash;
-                isSystemUser = true;
-                group = "github-runners";
-                uid = 601;
+            systemd.services."gitea-runner-${utils.escapeSystemdPath name}" = {
+              serviceConfig = {
+                DynamicUser = mkForce false;
+                User = mkForce runnerUsername;
+                Group = mkForce runnerUsername;
               };
-              groups.github-runners.gid = 601;
             };
             system.stateVersion = "24.05";
           };
       }
     ) cfg.containers;
+
+    systemd.services = builtins.listToAttrs (
+      map (name: {
+        name = "container@${name}";
+        value = {
+          requires = [ "gitea.service" ];
+          after = [ "gitea.service" ];
+        };
+      }) (builtins.attrNames (filterAttrs (_: c: c.enable) cfg.containers))
+    );
   };
 }

systems/jeeves/scripts/zfs.sh

@@ -23,6 +23,7 @@ sudo zfs create media/secure/home_assistant -o compression=zstd-19
 sudo zfs create media/secure/notes -o copies=2
 sudo zfs create media/secure/postgres -o mountpoint=/zfs/media/database/postgres -o recordsize=16k -o primarycache=metadata
 sudo zfs create media/secure/postgres-wal -o mountpoint=/zfs/media/database/postgres-wal -o recordsize=32k -o primarycache=metadata -o special_small_blocks=32K -o compression=lz4 -o secondarycache=none -o logbias=latency
+sudo zfs create media/secure/prometheus -o mountpoint=/zfs/media/database/prometheus -o compression=lz4
 sudo zfs create media/secure/services -o compression=zstd-9
 sudo zfs create media/secure/share -o mountpoint=/zfs/media/share -o exec=off
 

systems/jeeves/services/audiobookshelf.nix

@@ -3,7 +3,10 @@ let
   vars = import ../vars.nix;
 in
 {
-  services.audiobookshelf.enable = true;
+  services.audiobookshelf = {
+    enable = true;
+    port = 8000;
+  };
   systemd.services.audiobookshelf.serviceConfig.WorkingDirectory =
     lib.mkForce "${vars.docker_configs}/audiobookshelf";
   users.users.audiobookshelf.home = lib.mkForce "${vars.docker_configs}/audiobookshelf";

systems/jeeves/services/camofox-browser.nix

@@ -0,0 +1,80 @@
+{
+  ...
+}:
+let
+  vars = import ../vars.nix;
+in
+{
+  systemd.tmpfiles.rules = [
+    "d ${vars.docker_configs}/camofox-browser 0750 root root - -"
+  ];
+
+  containers.camofox-browser = {
+    autoStart = true;
+    privateNetwork = false;
+    bindMounts = {
+      camofox-browser = {
+        hostPath = "${vars.docker_configs}/camofox-browser";
+        mountPoint = "/var/lib/camofox-browser";
+        isReadOnly = false;
+      };
+    };
+    config =
+      {
+        pkgs,
+        lib,
+        ...
+      }:
+      {
+        networking.hostName = "camofox-browser";
+
+        environment.systemPackages = with pkgs; [
+          ffmpeg
+          git
+          nodejs
+          python3Packages.yt-dlp
+        ];
+
+        systemd.services.camofox-browser = {
+          description = "Camofox browser server";
+          wantedBy = [ "multi-user.target" ];
+          after = [ "network.target" ];
+          environment = {
+            CAMOFOX_HOST = "127.0.0.1";
+            CAMOFOX_PORT = "9377";
+            HOME = "/var/lib/camofox-browser";
+          };
+          path = with pkgs; [
+            bash
+            coreutils
+            git
+            nodejs
+          ];
+          serviceConfig = {
+            Restart = "always";
+            RestartSec = "5s";
+            WorkingDirectory = "/var/lib/camofox-browser";
+          };
+          script = ''
+            set -eu
+
+            app_dir=/var/lib/camofox-browser/app
+
+            if [ ! -d "$app_dir/.git" ]; then
+              git clone --depth 1 https://github.com/jo-inc/camofox-browser "$app_dir"
+            fi
+
+            cd "$app_dir"
+
+            if [ ! -d node_modules ]; then
+              npm install
+            fi
+
+            exec npm start
+          '';
+        };
+
+        system.stateVersion = lib.mkDefault "24.05";
+      };
+  };
+}

systems/jeeves/services/gitea.nix

@@ -21,6 +21,10 @@ in
       createDatabase = false;
     };
     settings = {
+      actions = {
+        ENABLED = true;
+        DEFAULT_ACTIONS_URL = "github";
+      };
       service.DISABLE_REGISTRATION = true;
       server = {
         DOMAIN = "tmmworkshop.com";

systems/jeeves/services/grafana.nix

@@ -0,0 +1,80 @@
+{
+  ...
+}:
+let
+  vars = import ../vars.nix;
+  grafanaDataDir = "${vars.services}/grafana";
+in
+{
+  networking.firewall.allowedTCPPorts = [ 3000 ];
+
+  services.grafana = {
+    enable = true;
+    dataDir = grafanaDataDir;
+    settings = {
+      database.type = "sqlite3";
+      security = {
+        admin_password = "$__file{${vars.secrets}/services/grafana/admin_password}";
+        admin_user = "admin";
+        secret_key = "$__file{${vars.secrets}/services/grafana/secret_key}";
+      };
+      server = {
+        http_addr = "192.168.90.40";
+        http_port = 3000;
+        root_url = "http://192.168.90.40:3000/";
+      };
+    };
+    provision = {
+      enable = true;
+      dashboards.settings = {
+        apiVersion = 1;
+        providers = [
+          {
+            name = "monitoring";
+            folder = "Monitoring";
+            type = "file";
+            disableDeletion = false;
+            editable = false;
+            allowUiUpdates = false;
+            updateIntervalSeconds = 30;
+            options.path = ../monitoring/dashboards;
+          }
+        ];
+      };
+      datasources.settings = {
+        apiVersion = 1;
+        prune = true;
+        datasources = [
+          {
+            access = "proxy";
+            editable = false;
+            isDefault = true;
+            name = "prom-main";
+            type = "prometheus";
+            uid = "prom-main";
+            url = "http://127.0.0.1:9090";
+          }
+          {
+            access = "proxy";
+            editable = false;
+            name = "prom-pid-short";
+            type = "prometheus";
+            uid = "prom-pid-short";
+            url = "http://127.0.0.1:9092";
+          }
+        ];
+      };
+    };
+  };
+
+  systemd = {
+    services.grafana.after = [
+      "prometheus-main.service"
+      "prometheus-pid-short.service"
+    ];
+
+    tmpfiles.rules = [
+      "d ${grafanaDataDir} 0750 grafana grafana - -"
+    ];
+  };
+}

systems/jeeves/services/hedgedoc.nix

@@ -1,24 +0,0 @@
-{
-  services.hedgedoc = {
-    enable = true;
-    settings = {
-      host = "0.0.0.0";
-      port = 3000;
-      domain = "192.168.90.40";
-      urlAddPort = true;
-      protocolUseSSL = false;
-      db = {
-        dialect = "postgres";
-        database = "hedgedoc";
-        username = "hedgedoc";
-        host = "/run/postgresql";
-      };
-    };
-  };
-  networking.firewall.allowedTCPPorts = [ 3000 ];
-
-  systemd.services.hedgedoc = {
-    after = [ "postgresql.service" ];
-    requires = [ "postgresql.service" ];
-  };
-}

systems/jeeves/services/llms.nix

@@ -6,7 +6,7 @@ in
     user = "ollama";
     enable = true;
     host = "0.0.0.0";
-    syncModels = true;
+    syncModels = false;
     loadModels = [
       "codellama:7b"
       "deepscaler:1.5b"
@@ -30,6 +30,9 @@ in
       "ministral-3:14b"
       "nemotron-3-nano:30b"
       "qwen3-coder:30b"
+      "qwen3-embedding:0.6b"
+      "qwen3-embedding:4b"
+      "qwen3-embedding:8b"
       "qwen3-vl:32b"
       "qwen3:14b"
       "qwen3.5:35b"

systems/jeeves/services/nornsight.nix

@@ -0,0 +1,107 @@
+{ pkgs, ... }:
+let
+  vars = import ../vars.nix;
+  stateDir = "${vars.services}/nornsight";
+  appDir = "${stateDir}/app";
+  binPath = pkgs.lib.makeBinPath [
+    pkgs.binutils
+    pkgs.libpq
+    pkgs.postgresql
+    pkgs.stdenv.cc
+  ];
+  libraryPath = pkgs.lib.makeLibraryPath [
+    pkgs.libpq
+    pkgs.postgresql.lib
+  ];
+in
+{
+  systemd.tmpfiles.rules = [
+    "d ${stateDir} 0750 nornsight nornsight - -"
+  ];
+
+  users.users.nornsight = {
+    isSystemUser = true;
+    group = "nornsight";
+    home = stateDir;
+  };
+
+  systemd.services.nornsight = {
+    description = "Norn Sight";
+    after = [ "network-online.target" ];
+    wants = [ "network-online.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    environment = {
+      HOME = stateDir;
+      UV_CACHE_DIR = "${stateDir}/.cache/uv";
+      UV_PROJECT_ENVIRONMENT = "${appDir}/.venv";
+      UV_PYTHON = "${pkgs.python313}/bin/python3.13";
+      UV_PYTHON_DOWNLOADS = "never";
+      LD_LIBRARY_PATH = libraryPath;
+      LIBRARY_PATH = libraryPath;
+      PSYCOPG_IMPL = "python";
+    };
+
+    path = with pkgs; [
+      bash
+      coreutils
+      git
+      uv
+    ];
+
+    serviceConfig = {
+      Type = "simple";
+      User = "nornsight";
+      Group = "nornsight";
+      EnvironmentFile = "-${vars.secrets}/services/nornsight";
+      WorkingDirectory = stateDir;
+      Restart = "on-failure";
+      RestartSec = "5s";
+      StandardOutput = "journal";
+      StandardError = "journal";
+      NoNewPrivileges = true;
+      PrivateTmp = true;
+      ProtectHome = true;
+      ProtectSystem = "strict";
+      ReadWritePaths = [ stateDir ];
+    };
+
+    script = ''
+      set -eu
+      export PATH="${binPath}:$PATH"
+      export LD_LIBRARY_PATH="${libraryPath}:''${LD_LIBRARY_PATH:-}"
+      export LIBRARY_PATH="${libraryPath}:''${LIBRARY_PATH:-}"
+
+      : "''${NORN_SIGHT_REPO_URL:?NORN_SIGHT_REPO_URL is required}"
+      branch="''${NORN_SIGHT_BRANCH:-main}"
+
+      if [ -d "${appDir}/.git" ]; then
+        current_origin="$(git -C "${appDir}" remote get-url origin)"
+        if [ "$current_origin" != "$NORN_SIGHT_REPO_URL" ]; then
+          rm -rf "${appDir}"
+        fi
+      fi
+
+      if [ ! -d "${appDir}/.git" ]; then
+        git clone --branch "$branch" "$NORN_SIGHT_REPO_URL" "${appDir}"
+      else
+        cd "${appDir}"
+        git fetch origin "$branch"
+        git checkout "$branch"
+        git pull --ff-only origin "$branch"
+      fi
+
+      cd "${appDir}"
+      uv sync --upgrade
+      uv run python - <<'PY'
+      import ctypes.util
+      import os
+
+      print(f"LD_LIBRARY_PATH={os.environ.get('LD_LIBRARY_PATH')}")
+      print(f"LIBRARY_PATH={os.environ.get('LIBRARY_PATH')}")
+      print(f"libpq={ctypes.util.find_library('pq')}")
+      PY
+      exec uv run uvicorn pipelines.web.main:app --host 0.0.0.0 --port 8001
+    '';
+  };
+}

systems/jeeves/services/postgress.nix

@@ -38,9 +38,6 @@ in
       # signalbot
       local signalbot  signalbot   trust
 
-      # hedgedoc
-      local hedgedoc   hedgedoc    trust
-
       # math
       local postgres  math   trust
       host  postgres  math   127.0.0.1/32    trust
@@ -120,19 +117,11 @@ in
           login = true;
         };
       }
-      {
-        name = "hedgedoc";
-        ensureDBOwnership = true;
-        ensureClauses = {
-          login = true;
-        };
-      }
     ];
     ensureDatabases = [
       "data_science_dev"
       "hass"
       "gitea"
-      "hedgedoc"
       "math"
       "n8n"
       "richie"

systems/jeeves/services/signal_bot.nix

@@ -1,57 +0,0 @@
-{
-  pkgs,
-  inputs,
-  ...
-}:
-let
-  vars = import ../vars.nix;
-in
-{
-  users = {
-    users.signalbot = {
-      isSystemUser = true;
-      group = "signalbot";
-    };
-    groups.signalbot = { };
-  };
-
-  systemd.services.signal-bot = {
-    description = "Signal command and control bot";
-    after = [
-      "network.target"
-      "podman-signal_cli_rest_api.service"
-    ];
-    wants = [ "podman-signal_cli_rest_api.service" ];
-    wantedBy = [ "multi-user.target" ];
-
-    environment = {
-      PYTHONPATH = "${inputs.self}";
-      SIGNALBOT_DB = "signalbot";
-      SIGNALBOT_USER = "signalbot";
-      SIGNALBOT_HOST = "/run/postgresql";
-      SIGNALBOT_PORT = "5432";
-    };
-
-    serviceConfig = {
-      Type = "simple";
-      WorkingDirectory = "${inputs.self}";
-      User = "signalbot";
-      Group = "signalbot";
-      EnvironmentFile = "${vars.secrets}/services/signal-bot";
-      ExecStart = "${pkgs.my_python}/bin/python -m python.signal_bot.main";
-      StateDirectory = "signal-bot";
-      Restart = "on-failure";
-      RestartSec = "10s";
-      StandardOutput = "journal";
-      StandardError = "journal";
-      NoNewPrivileges = true;
-      ProtectSystem = "strict";
-      ProtectHome = "read-only";
-      PrivateTmp = true;
-      ReadWritePaths = [ "/var/lib/signal-bot" ];
-      ReadOnlyPaths = [
-        "${inputs.self}"
-      ];
-    };
-  };
-}

systems/jeeves/syncthing.nix

@@ -10,6 +10,14 @@ in
     settings = {
       devices.davids-server.id = "7GXTDGR-AOXFW2O-K6J7NM3-XYZNRRW-AKHAFWM-GBOWUPQ-OA6JIWD-ER7RDQL"; # cspell:disable-line
       folders = {
+        photos = {
+          path = "${vars.syncthing}/important";
+          devices = [
+            "rhapsody-in-green"
+            "phone"
+          ];
+          fsWatcherEnabled = true;
+        };
         "dotfiles" = {
           path = "/home/richie/dotfiles";
           devices = [

systems/jeeves/web_services/acme.nix

@@ -5,7 +5,6 @@ let
     "gitea"
     "jellyfin"
     "share"
-    "verilux"
   ];
   extraDomains = [ "www.norn-sight.com" ];
 

systems/jeeves/web_services/haproxy.cfg

@@ -28,7 +28,6 @@ frontend ContentSwitching
 
   # ACME challenge routing (must be first)
   acl is_acme path_beg /.well-known/acme-challenge/
-  use_backend acme_challenge if is_acme
 
   # tmmworkshop.com
   acl host_audiobookshelf  hdr(host) -i audiobookshelf.tmmworkshop.com
@@ -45,6 +44,7 @@ frontend ContentSwitching
   # Redirect all HTTP to HTTPS unless on the allow list or ACME challenge
   http-request redirect scheme https code 301 if !{ ssl_fc } !allow_http !is_acme
 
+  use_backend acme_challenge if is_acme
   use_backend audiobookshelf_nodes if host_audiobookshelf
   use_backend cache_nodes  if host_cache
   use_backend jellyfin if host_jellyfin
@@ -81,4 +81,4 @@ backend gitea
 
 backend norn_sight
   mode http
-  server server 192.168.90.49:8000
+  server server 127.0.0.1:8001

systems/rhapsody-in-green/default.nix

@@ -11,10 +11,9 @@
     "${inputs.self}/common/optional/yubikey.nix"
     "${inputs.self}/common/optional/zerotier.nix"
     ./hardware.nix
-    ./llms.nix
     ./open_webui.nix
+    ./programs.nix
     ./qmk.nix
-    ./sunshine.nix
     ./syncthing.nix
     inputs.nixos-hardware.nixosModules.framework-13-7040-amd
   ];
@@ -27,6 +26,7 @@
       allowedTCPPorts = [
         8000
         8080
+        8081
       ];
     };
     networkmanager.enable = true;

systems/rhapsody-in-green/llms.nix

@@ -1,29 +0,0 @@
-{
-  services.ollama = {
-    user = "ollama";
-    enable = true;
-    host = "127.0.0.1";
-    syncModels = true;
-    loadModels = [
-      "deepscaler:1.5b"
-      "deepseek-r1:8b"
-      "gemma3:12b"
-      "lfm2:24b"
-      "nemotron-3-nano:4b"
-      "qwen3:14b"
-      "qwen3.5:27b"
-    ];
-  };
-  systemd.services = {
-    ollama.serviceConfig = {
-      Nice = 19;
-      IOSchedulingPriority = 7;
-    };
-    ollama-model-loader.serviceConfig = {
-      Nice = 19;
-      CPUWeight = 50;
-      IOSchedulingClass = "idle";
-      IOSchedulingPriority = 7;
-    };
-  };
-}

systems/rhapsody-in-green/programs.nix

@@ -0,0 +1,6 @@
+{ pkgs, ... }:
+{
+  environment.systemPackages = with pkgs; [
+    ffmpeg
+  ];
+}

systems/rhapsody-in-green/sunshine.nix

@@ -1,28 +0,0 @@
-{ pkgs, ... }:
-{
-  services.sunshine = {
-    enable = true;
-    openFirewall = true;
-    capSysAdmin = true;
-  };
-  environment.systemPackages = [ pkgs.kdePackages.libkscreen ];
-
-  boot = {
-    kernelParams = [
-      "drm.edid_firmware=DP-4:edid/virtual-display.bin"
-      "video=DP-4:e"
-    ];
-  };
-
-  hardware.firmware = [
-    (pkgs.runCommandLocal "virtual-display-edid"
-      {
-        compressFirmware = false;
-      }
-      ''
-        mkdir -p $out/lib/firmware/edid
-        cp ${./edid/virtual-display.bin} $out/lib/firmware/edid/virtual-display.bin
-      ''
-    )
-  ];
-}

systems/rhapsody-in-green/syncthing.nix

@@ -39,6 +39,14 @@
       ];
       fsWatcherEnabled = true;
     };
+    photos = {
+      path = "/home/richie/photos";
+      devices = [
+        "jeeves"
+        "phone"
+      ];
+      fsWatcherEnabled = true;
+    };
     "projects" = {
       id = "vyma6-lqqrz"; # cspell:disable-line
       path = "/home/richie/projects";

tests/test_audiobook_catalog.py

@@ -0,0 +1,126 @@
+"""test_audiobook_catalog."""
+
+from __future__ import annotations
+
+import pytest
+from sqlalchemy import create_engine, select
+from sqlalchemy.orm import sessionmaker
+
+from python.orm.richie import AudiobookAuthor, AudiobookSeries, RichieBase
+from python.tools.audiobook import catalog
+
+
+@pytest.fixture
+def audiobook_session():
+    engine = create_engine("sqlite+pysqlite:///:memory:", future=True)
+    RichieBase.metadata.create_all(engine)
+    with sessionmaker(bind=engine, expire_on_commit=False, future=True)() as session:
+        yield session
+    engine.dispose()
+
+
+def test_upsert_catalog_csv_inserts_and_updates_authors_and_series(tmp_path, audiobook_session) -> None:
+    audiobook_session.add_all(
+        [
+            AudiobookAuthor(id=10, name="old_author"),
+            AudiobookAuthor(id=11, name="craig_alanson"),
+        ],
+    )
+    audiobook_session.commit()
+    authors_csv = tmp_path / "authors.csv"
+    series_csv = tmp_path / "series.csv"
+    authors_csv.write_text(
+        "name,id\n"
+        "glynn_stewart,\n"
+        "craig_alanson,\n"
+        "updated_author,10\n",
+        encoding="utf-8",
+    )
+    series_csv.write_text(
+        "name,author_name,id\n"
+        "starships_mage,glynn_stewart,\n"
+        "expeditionary_force,craig_alanson,\n",
+        encoding="utf-8",
+    )
+
+    author_count = catalog.upsert_authors_from_csv(audiobook_session, authors_csv)
+    series_count = catalog.upsert_series_from_csv(audiobook_session, series_csv)
+    audiobook_session.commit()
+
+    authors = audiobook_session.scalars(select(AudiobookAuthor).order_by(AudiobookAuthor.id)).all()
+    series = audiobook_session.scalars(select(AudiobookSeries).order_by(AudiobookSeries.name)).all()
+    assert author_count == 3
+    assert series_count == 2
+    assert [(author.id, author.name) for author in authors] == [
+        (10, "updated_author"),
+        (11, "craig_alanson"),
+        (12, "glynn_stewart"),
+    ]
+    assert [(row.name, row.author.name) for row in series] == [
+        ("expeditionary_force", "craig_alanson"),
+        ("starships_mage", "glynn_stewart"),
+    ]
+
+
+def test_upsert_series_csv_updates_series_by_id(tmp_path, audiobook_session) -> None:
+    author = AudiobookAuthor(id=1, name="glynn_stewart")
+    audiobook_session.add_all(
+        [
+            author,
+            AudiobookSeries(id=7, name="old_series", author=author),
+        ],
+    )
+    audiobook_session.commit()
+    series_csv = tmp_path / "series.csv"
+    series_csv.write_text(
+        "name,author_name,id\n"
+        "starships_mage,glynn_stewart,7\n",
+        encoding="utf-8",
+    )
+
+    count = catalog.upsert_series_from_csv(audiobook_session, series_csv)
+    audiobook_session.commit()
+
+    series = audiobook_session.get(AudiobookSeries, 7)
+    assert count == 1
+    assert series.name == "starships_mage"
+    assert series.author.name == "glynn_stewart"
+
+
+def test_upsert_csv_allows_missing_id_column(tmp_path, audiobook_session) -> None:
+    authors_csv = tmp_path / "authors.csv"
+    series_csv = tmp_path / "series.csv"
+    authors_csv.write_text(
+        "name\n"
+        "glynn_stewart\n",
+        encoding="utf-8",
+    )
+    series_csv.write_text(
+        "name,author_name\n"
+        "starships_mage,glynn_stewart\n",
+        encoding="utf-8",
+    )
+
+    author_count = catalog.upsert_authors_from_csv(audiobook_session, authors_csv)
+    series_count = catalog.upsert_series_from_csv(audiobook_session, series_csv)
+    audiobook_session.commit()
+
+    series = audiobook_session.scalar(select(AudiobookSeries))
+    assert author_count == 1
+    assert series_count == 1
+    assert series.name == "starships_mage"
+    assert series.author.name == "glynn_stewart"
+
+
+def test_upsert_series_csv_rejects_unknown_author(tmp_path, audiobook_session) -> None:
+    series_csv = tmp_path / "series.csv"
+    series_csv.write_text(
+        "name,author_name,id\n"
+        "starships_mage,glynn_stewart,\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(catalog.CatalogImportError) as error:
+        catalog.upsert_series_from_csv(audiobook_session, series_csv)
+
+    assert "author not found: glynn_stewart" in str(error.value)

tests/test_ebook_search_core.py

@@ -0,0 +1,423 @@
+"""Tests for EPUB search core helpers."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import UTC, datetime
+from os import environ
+from pathlib import Path
+from threading import Event
+from types import ModuleType
+
+import pytest
+from sqlalchemy import create_engine, select
+from sqlalchemy.orm import sessionmaker
+
+from python.ebook_search.answer import answer_query
+from python.ebook_search.bm25_corpus import (
+    BM25Corpus,
+    BM25CorpusUnavailableError,
+    BM25Manifest,
+    ensure_bm25_corpus,
+    fetch_bm25_corpus_records,
+    load_bm25_corpus,
+)
+from python.ebook_search.config import EbookSearchConfig, RerankConfig, load_config, normalize_embedding_model
+from python.ebook_search.embeddings import MODEL_DIMENSIONS, ensure_embedding_models
+from python.ebook_search.ingest import chunk_text, find_existing_source
+from python.ebook_search.search import (
+    SearchResponse,
+    SearchResult,
+    bm25_candidates,
+    reciprocal_rank_fusion,
+    retrieval_query_from_text,
+    search_ebooks,
+)
+from python.ebook_search.timing import RuntimeStep
+from python.orm.richie import EbookChapter, EbookChunk, EbookEmbeddingModel, EbookSource, RichieBase
+
+
+def test_chunk_text_uses_overlap() -> None:
+    chunks = chunk_text(" ".join(str(index) for index in range(100)), chunk_tokens=20, overlap_tokens=5)
+
+    assert len(chunks) > 1
+    assert chunks[0].token_start == 0
+    assert chunks[1].token_start == 15
+    assert all(chunk.token_count <= 20 for chunk in chunks)
+
+
+def test_reciprocal_rank_fusion_combines_vector_and_bm25_rankings() -> None:
+    vector_results = [
+        SearchResult(chunk_id=1, text="a", source_title="A", score=0.9, vector_score=0.9),
+        SearchResult(chunk_id=2, text="b", source_title="B", score=0.8, vector_score=0.8),
+    ]
+    lexical_results = [
+        SearchResult(chunk_id=2, text="b", source_title="B", score=4.2, bm25_score=4.2),
+        SearchResult(chunk_id=3, text="c", source_title="C", score=2.1, bm25_score=2.1),
+    ]
+
+    fused = reciprocal_rank_fusion(vector_results, lexical_results)
+
+    assert [result.chunk_id for result in fused] == [2, 1, 3]
+    assert fused[0].rank_source == "Hybrid"
+    assert fused[0].vector_score == 0.8
+    assert fused[0].bm25_score == 4.2
+    assert fused[0].fused_score == fused[0].score
+
+
+def test_find_existing_source_matches_path_or_hash() -> None:
+    engine = create_engine("sqlite+pysqlite:///:memory:", future=True)
+    RichieBase.metadata.create_all(engine)
+    with sessionmaker(bind=engine, expire_on_commit=False, future=True)() as session:
+        source = EbookSource(
+            title="Book",
+            author=None,
+            language=None,
+            publisher=None,
+            identifier=None,
+            file_path="/old/book.epub",
+            file_sha256="a" * 64,
+            file_mtime=datetime.now(tz=UTC),
+            file_size=10,
+        )
+        session.add(source)
+        session.commit()
+
+        assert find_existing_source(session, Path("/old/book.epub"), "b" * 64) == source
+        assert find_existing_source(session, Path("/new/book.epub"), "a" * 64) == source
+
+
+def test_bm25_corpus_uses_existing_search_text_without_duplicate_metadata() -> None:
+    engine = create_engine("sqlite+pysqlite:///:memory:", future=True)
+    RichieBase.metadata.create_all(engine)
+    with sessionmaker(bind=engine, expire_on_commit=False, future=True)() as session:
+        source = EbookSource(
+            title="Book",
+            author="Author",
+            language=None,
+            publisher=None,
+            identifier=None,
+            file_path="/book.epub",
+            file_sha256="a" * 64,
+            file_mtime=datetime.now(tz=UTC),
+            file_size=10,
+        )
+        session.add(source)
+        session.flush()
+        chapter = EbookChapter(source_id=source.id, spine_index=0, title="Chapter", href=None)
+        session.add(chapter)
+        session.flush()
+        session.add(
+            EbookChunk(
+                id=1,
+                source_id=source.id,
+                chapter_id=chapter.id,
+                chunk_index=0,
+                text="content",
+                token_start=0,
+                token_count=1,
+                page_label=None,
+                content_sha256="b" * 64,
+                search_text="Book Author Chapter content",
+            )
+        )
+        session.commit()
+
+        records = fetch_bm25_corpus_records(session)
+
+    assert records[0]["bm25_text"] == "Book Author Chapter content"
+
+
+def test_reciprocal_rank_fusion_marks_hybrid_source() -> None:
+    vector_results = [SearchResult(chunk_id=1, text="a", source_title="A")]
+    lexical_results = [SearchResult(chunk_id=2, text="b", source_title="B")]
+
+    fused = reciprocal_rank_fusion(vector_results, lexical_results)
+
+    assert {result.rank_source for result in fused} == {"Hybrid"}
+
+
+def test_search_response_sums_runtime_steps() -> None:
+    response = SearchResponse(
+        query="query",
+        results=[],
+        rank_label="Hybrid",
+        timings=(
+            RuntimeStep(name="A", duration_ms=1.25),
+            RuntimeStep(name="B", duration_ms=2.75),
+            RuntimeStep(name="Parallel detail", duration_ms=10.0, counts_toward_total=False),
+        ),
+    )
+
+    assert response.total_runtime_ms == 4.0
+
+
+def test_search_ebooks_runs_vector_and_bm25_in_parallel(monkeypatch) -> None:
+    engine = create_engine("sqlite+pysqlite:///:memory:", future=True)
+    vector_started = Event()
+    bm25_started = Event()
+    received_engines: list[object] = []
+
+    def fake_vector_candidates(received_engine, query, _config):
+        """Return vector candidates after confirming BM25 has started."""
+        received_engines.append(received_engine)
+        assert query == "what is parallel"
+        vector_started.set()
+        assert bm25_started.wait(timeout=2)
+        return [SearchResult(chunk_id=1, text="vector", source_title="Vector", vector_score=0.9)]
+
+    def fake_bm25_candidates(query, _config):
+        """Return BM25 candidates after confirming vector search has started."""
+        assert query == "parallel"
+        bm25_started.set()
+        assert vector_started.wait(timeout=2)
+        return [SearchResult(chunk_id=2, text="bm25", source_title="BM25", bm25_score=2.0)]
+
+    monkeypatch.setattr("python.ebook_search.search.vector_candidates", fake_vector_candidates)
+    monkeypatch.setattr("python.ebook_search.search.bm25_candidates", fake_bm25_candidates)
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False))
+
+    response = search_ebooks(engine, "what is parallel", config)
+
+    timings = {step.name: step for step in response.timings}
+    assert [result.chunk_id for result in response.results] == [1, 2]
+    assert timings["Embedding + vector search"].counts_toward_total is False
+    assert timings["BM25 search"].counts_toward_total is False
+    assert timings["Hybrid retrieval"].counts_toward_total is True
+    assert timings["BM25 query preparation"].counts_toward_total is True
+    assert received_engines == [engine]
+
+
+def test_retrieval_query_keeps_entity_and_series_terms() -> None:
+    assert retrieval_query_from_text("what does Damien Montgomery stand for in starship mage") == (
+        "damien montgomery stand starship mage"
+    )
+
+
+def test_bm25_candidates_scores_whole_corpus(monkeypatch) -> None:
+    record = {
+        "chunk_id": 2,
+        "text": "high",
+        "source_title": "B",
+        "source_author": None,
+        "chapter_title": None,
+        "page_label": None,
+        "bm25_text": "high",
+    }
+    manifest = BM25Manifest(created_at=datetime.now(tz=UTC), db_updated_at=None, chunk_count=1)
+    corpus = BM25Corpus(retriever=object(), records=(record,), manifest=manifest)
+    captured: dict[str, object] = {}
+
+    def fake_score_bm25_corpus(query, saved_corpus, *, limit):
+        captured["query"] = query
+        captured["corpus"] = saved_corpus
+        captured["limit"] = limit
+        return [(record, 1.5)]
+
+    monkeypatch.setattr("python.ebook_search.search.load_bm25_corpus", lambda _config: corpus)
+    monkeypatch.setattr("python.ebook_search.search.score_bm25_corpus", fake_score_bm25_corpus)
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False))
+
+    results = bm25_candidates("high", config)
+
+    assert captured["query"] == "high"
+    assert captured["corpus"] == corpus
+    assert captured["limit"] == 120
+    assert [result.chunk_id for result in results] == [2]
+    assert [result.bm25_score for result in results] == [1.5]
+
+
+def test_bm25_candidates_raises_when_corpus_is_unavailable(monkeypatch) -> None:
+    def fake_load_bm25_corpus(_config):
+        raise BM25CorpusUnavailableError
+
+    monkeypatch.setattr("python.ebook_search.search.load_bm25_corpus", fake_load_bm25_corpus)
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False))
+
+    with pytest.raises(BM25CorpusUnavailableError):
+        bm25_candidates("high", config)
+
+
+def test_load_bm25_corpus_caches_disk_load(monkeypatch, tmp_path) -> None:
+    load_bm25_corpus.cache_clear()
+    manifest = BM25Manifest(created_at=datetime.now(tz=UTC), db_updated_at=None, chunk_count=1)
+    record = {
+        "chunk_id": 2,
+        "text": "cached",
+        "source_title": "B",
+        "source_author": None,
+        "chapter_title": None,
+        "page_label": None,
+        "bm25_text": "cached",
+    }
+    load_count = 0
+
+    class FakeRetriever:
+        """Fake persisted BM25 retriever."""
+
+        corpus = (record,)
+
+    class FakeBM25:
+        """Fake BM25 class with observable load count."""
+
+        @staticmethod
+        def load(index_path, *, load_corpus, mmap):
+            nonlocal load_count
+            load_count += 1
+            assert index_path == tmp_path
+            assert load_corpus is True
+            assert mmap is True
+            return FakeRetriever()
+
+    fake_bm25s = ModuleType("bm25s")
+    fake_bm25s.BM25 = FakeBM25
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.read_bm25_manifest", lambda _path: manifest)
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.bm25_index_exists", lambda _path, _manifest: True)
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.bm25s", fake_bm25s)
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False), bm25_index_dir=str(tmp_path))
+
+    try:
+        first = load_bm25_corpus(config)
+        second = load_bm25_corpus(config)
+    finally:
+        load_bm25_corpus.cache_clear()
+
+    assert first is second
+    assert first is not None
+    assert first.records == (record,)
+    assert load_count == 1
+
+
+def test_load_bm25_corpus_raises_when_index_is_missing(monkeypatch, tmp_path) -> None:
+    load_bm25_corpus.cache_clear()
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.read_bm25_manifest", lambda _path: None)
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.bm25_index_exists", lambda _path, _manifest: False)
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False), bm25_index_dir=str(tmp_path))
+
+    try:
+        with pytest.raises(BM25CorpusUnavailableError, match="BM25 corpus is not available"):
+            load_bm25_corpus(config)
+    finally:
+        load_bm25_corpus.cache_clear()
+
+
+def test_ensure_bm25_corpus_refreshes_missing_index(monkeypatch) -> None:
+    refreshed: list[object] = []
+    db_updated_at = datetime.now(tz=UTC)
+
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.read_bm25_manifest", lambda _path: None)
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.bm25_index_exists", lambda _path, _manifest: False)
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.corpus_last_updated_at", lambda _session: db_updated_at)
+    monkeypatch.setattr(
+        "python.ebook_search.bm25_corpus.refresh_bm25_corpus",
+        lambda session, config, *, db_updated_at: refreshed.append((session, config, db_updated_at)),
+    )
+
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False))
+    session = object()
+
+    ensure_bm25_corpus(session, config)
+
+    assert refreshed == [(session, config, db_updated_at)]
+
+
+def test_ensure_bm25_corpus_refreshes_stale_index(monkeypatch) -> None:
+    refreshed: list[object] = []
+    created_at = datetime(2026, 1, 1, tzinfo=UTC)
+    db_updated_at = datetime(2026, 1, 2, tzinfo=UTC)
+    manifest = BM25Manifest(created_at=created_at, db_updated_at=created_at, chunk_count=10)
+
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.read_bm25_manifest", lambda _path: manifest)
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.bm25_index_exists", lambda _path, _manifest: True)
+    monkeypatch.setattr("python.ebook_search.bm25_corpus.corpus_last_updated_at", lambda _session: db_updated_at)
+    monkeypatch.setattr(
+        "python.ebook_search.bm25_corpus.refresh_bm25_corpus",
+        lambda session, config, *, db_updated_at: refreshed.append((session, config, db_updated_at)),
+    )
+
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False))
+    session = object()
+
+    ensure_bm25_corpus(session, config)
+
+    assert refreshed == [(session, config, db_updated_at)]
+
+
+def test_supported_embedding_models_match_service_names() -> None:
+    assert MODEL_DIMENSIONS == {
+        "qwen3-embedding-0.6b": 1024,
+        "qwen3-embedding-4b": 2560,
+        "qwen3-embedding-8b": 4096,
+    }
+
+
+def test_ensure_embedding_models_registers_service_names() -> None:
+    engine = create_engine("sqlite+pysqlite:///:memory:", future=True)
+    RichieBase.metadata.create_all(engine)
+    with sessionmaker(bind=engine, expire_on_commit=False, future=True)() as session:
+        ensure_embedding_models(session)
+        session.commit()
+
+        models = list(session.scalars(select(EbookEmbeddingModel).order_by(EbookEmbeddingModel.name)))
+
+    assert [(model.name, model.dimension) for model in models] == [
+        ("qwen3-embedding-0.6b", 1024),
+        ("qwen3-embedding-4b", 2560),
+        ("qwen3-embedding-8b", 4096),
+    ]
+
+
+def test_embedding_model_aliases_normalize_to_provider_names() -> None:
+    assert normalize_embedding_model() == "qwen3-embedding-0.6b"
+
+    environ["EBOOK_SEARCH_EMBEDDING_MODEL"] = "qwen3-embedding-0.6b"
+    assert normalize_embedding_model() == "qwen3-embedding-0.6b"
+
+    environ["EBOOK_SEARCH_EMBEDDING_MODEL"] = "Qwen3-Embedding-0.6B"
+    assert normalize_embedding_model() == "qwen3-embedding-0.6b"
+
+    environ["EBOOK_SEARCH_EMBEDDING_MODEL"] = "Qwen/Qwen3-Embedding-4B"
+
+    assert normalize_embedding_model() == "qwen3-embedding-4b"
+
+    environ["EBOOK_SEARCH_EMBEDDING_MODEL"] = "qwen3-embedding:8b"
+    assert normalize_embedding_model() == "qwen3-embedding-8b"
+
+    environ["EBOOK_SEARCH_EMBEDDING_MODEL"] = "qwen3-embedding-8b"
+    assert normalize_embedding_model() == "qwen3-embedding-8b"
+
+
+def test_answer_generation_is_enabled_by_default(monkeypatch) -> None:
+    monkeypatch.delenv("EBOOK_SEARCH_ANSWER_ENABLED", raising=False)
+
+    config = load_config()
+
+    assert config.answer_enabled is True
+
+
+def test_chat_defaults_use_ollama_cloud(monkeypatch) -> None:
+    monkeypatch.delenv("EBOOK_SEARCH_VLLM_BASE_URL", raising=False)
+    monkeypatch.delenv("EBOOK_SEARCH_CHAT_MODEL", raising=False)
+
+    config = load_config()
+
+    assert config.vllm_base_url == "https://ollama.com/v1"
+    assert config.chat_model == "deepseek-v4-flash"
+
+
+def test_chat_api_key_falls_back_to_ollama_api_key(monkeypatch) -> None:
+    monkeypatch.delenv("EBOOK_SEARCH_VLLM_API_KEY", raising=False)
+    monkeypatch.setenv("OLLAMA_API_KEY", "ollama-key")
+
+    config = load_config()
+
+    assert config.vllm_api_key == "ollama-key"
+
+
+def test_answer_query_does_not_call_model_when_disabled() -> None:
+    config = replace(load_config(), answer_enabled=False)
+    result = SearchResult(chunk_id=1, text="source text", source_title="Book")
+
+    answer = answer_query("question", [result], config)
+
+    assert "Answer generation is disabled" in answer

tests/test_ebook_search_http.py

@@ -0,0 +1,84 @@
+"""Tests for EPUB search HTTP model adapters."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from python.ebook_search.answer import answer_query
+from python.ebook_search.config import EbookSearchConfig, RerankConfig
+from python.ebook_search.embeddings import embed_texts
+from python.ebook_search.search import SearchResult
+
+
+def test_answer_query_uses_httpx_chat_completions(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_post(url: str, **kwargs: object) -> httpx.Response:
+        captured["url"] = url
+        captured["kwargs"] = kwargs
+        return httpx.Response(
+            200,
+            json={"choices": [{"message": {"content": "grounded answer"}}]},
+            request=httpx.Request("POST", url),
+        )
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+    config = EbookSearchConfig(
+        rerank=RerankConfig(enabled=False),
+        vllm_base_url="https://ollama.com/v1",
+        vllm_api_key="secret",
+        chat_model="deepseek-v4-flash",
+    )
+
+    answer = answer_query("question", [SearchResult(chunk_id=1, text="source", source_title="Book")], config)
+
+    assert answer == "grounded answer"
+    assert captured["url"] == "https://ollama.com/v1/chat/completions"
+    kwargs = captured["kwargs"]
+    assert isinstance(kwargs, dict)
+    assert kwargs["headers"] == {"Authorization": "Bearer secret"}
+    payload = kwargs["json"]
+    assert isinstance(payload, dict)
+    assert payload["model"] == "deepseek-v4-flash"
+
+
+def test_embed_texts_uses_httpx_embeddings(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+    vector = [0.0] * 1024
+
+    def fake_post(url: str, **kwargs: object) -> httpx.Response:
+        captured["url"] = url
+        captured["kwargs"] = kwargs
+        return httpx.Response(
+            200,
+            json={"data": [{"embedding": vector}]},
+            request=httpx.Request("POST", url),
+        )
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+    config = EbookSearchConfig(
+        rerank=RerankConfig(enabled=False),
+        embedding_base_url="http://bob:8000/v1",
+        embedding_model="qwen3-embedding-0.6b",
+    )
+
+    embeddings = embed_texts(["hello"], config)
+
+    assert embeddings == [vector]
+    assert captured["url"] == "http://bob:8000/v1/embeddings"
+    kwargs = captured["kwargs"]
+    assert isinstance(kwargs, dict)
+    assert kwargs["headers"] == {}
+    assert kwargs["json"] == {"model": "qwen3-embedding-0.6b", "input": ["hello"]}
+
+
+def test_embed_texts_rejects_bad_response_shape(monkeypatch) -> None:
+    def fake_post(url: str, **_kwargs: object) -> httpx.Response:
+        return httpx.Response(200, json={"data": [{}]}, request=httpx.Request("POST", url))
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False))
+
+    with pytest.raises(RuntimeError, match="Embedding request failed"):
+        embed_texts(["hello"], config)

tests/test_ebook_search_rerank.py

@@ -0,0 +1,150 @@
+"""Tests for EPUB search reranking."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from python.ebook_search.config import EbookSearchConfig, RerankConfig, load_rerank_config
+from python.ebook_search.rerank import rerank_chunks
+from python.ebook_search.search import SearchResult, apply_rerank, skip_rerank
+
+
+def candidates() -> list[SearchResult]:
+    return [
+        SearchResult(chunk_id=1, text="alpha", source_title="A", score=0.9),
+        SearchResult(chunk_id=2, text="beta", source_title="B", score=0.8),
+        SearchResult(chunk_id=3, text="gamma", source_title="C", score=0.7),
+    ]
+
+
+def rerank_response(payload: dict[str, object] | None = None, *, content: bytes | None = None) -> httpx.Response:
+    return httpx.Response(
+        200,
+        content=content,
+        json=payload,
+        request=httpx.Request("POST", "http://rerank.test/rerank"),
+    )
+
+
+def test_config_defaults_keep_reranking_optional(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("EBOOK_SEARCH_RERANK_ENABLED", raising=False)
+    monkeypatch.delenv("EBOOK_SEARCH_RERANK_BASE_URL", raising=False)
+    monkeypatch.delenv("EBOOK_SEARCH_RERANK_MODEL", raising=False)
+    monkeypatch.delenv("EBOOK_SEARCH_RERANK_CANDIDATES", raising=False)
+    monkeypatch.delenv("EBOOK_SEARCH_RERANK_TIMEOUT_SECONDS", raising=False)
+
+    config = load_rerank_config()
+
+    assert config.enabled is False
+    assert config.base_url == "http://192.168.90.25:8001"
+    assert config.model == "qwen3-reranker-06b"
+    assert config.candidates == 24
+    assert config.timeout_seconds == 30
+
+
+def test_reranking_disabled_returns_original_fused_order() -> None:
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False), top_k=2)
+
+    response = skip_rerank("query", candidates(), config)
+
+    assert response.rank_label == "Hybrid"
+    assert [result.chunk_id for result in response.results] == [1, 2]
+
+
+def test_reranking_enabled_reorders_candidates(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(_url: str, *, json: dict[str, object], timeout: float) -> httpx.Response:
+        assert timeout == 30
+        assert json == {
+            "model": "qwen3-reranker-06b",
+            "query": "query",
+            "documents": ["alpha", "beta", "gamma"],
+        }
+        return rerank_response(
+            {
+                "results": [
+                    {"index": 0, "relevance_score": 0.1},
+                    {"index": 1, "relevance_score": 0.9},
+                    {"index": 2, "relevance_score": 0.4},
+                ]
+            }
+        )
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+
+    results = rerank_chunks("query", candidates(), RerankConfig())
+
+    assert [result.chunk_id for result in results] == [2, 1, 3]
+    assert [round(result.score, 3) for result in results] == [0.78, 0.37, 0.28]
+    assert [result.rerank_score for result in results] == [0.9, 0.1, 0.4]
+
+
+def test_reranking_cannot_ignore_hybrid_score(monkeypatch: pytest.MonkeyPatch) -> None:
+    candidates = [
+        SearchResult(chunk_id=1, text="strong hybrid", source_title="A", score=1.0),
+        SearchResult(chunk_id=2, text="weak hybrid", source_title="B", score=0.1),
+    ]
+
+    def fake_post(_url: str, **_kwargs: object) -> httpx.Response:
+        return rerank_response(
+            {
+                "results": [
+                    {"index": 0, "relevance_score": 0.7},
+                    {"index": 1, "relevance_score": 1.0},
+                ]
+            }
+        )
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+
+    results = rerank_chunks("query", candidates, RerankConfig())
+
+    assert [result.chunk_id for result in results] == [1, 2]
+    assert results[0].score == pytest.approx(0.79)
+    assert results[1].score == 0.7
+    assert results[1].rerank_score == 1.0
+
+
+def test_vllm_rerank_timeout_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_rerank_chunks(
+        _query: str,
+        _candidates: list[SearchResult],
+        _config: RerankConfig,
+    ) -> list[SearchResult]:
+        message = "timeout"
+        raise httpx.TimeoutException(message)
+
+    monkeypatch.setattr("python.ebook_search.search.rerank_chunks", fake_rerank_chunks)
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=True), top_k=2)
+
+    with pytest.raises(httpx.TimeoutException, match="timeout"):
+        apply_rerank("query", candidates(), config)
+
+
+def test_malformed_vllm_rerank_json_does_not_crash_search(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(_url: str, **_kwargs: object) -> httpx.Response:
+        return rerank_response(content=b"not-json")
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+
+    results = rerank_chunks("query", candidates()[:1], RerankConfig())
+
+    assert results[0].score == 0.3
+
+
+def test_vllm_rerank_scores_are_clamped(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_post(_url: str, **_kwargs: object) -> httpx.Response:
+        return rerank_response(
+            {
+                "results": [
+                    {"index": 0, "relevance_score": -1},
+                    {"index": 1, "relevance_score": 2},
+                ]
+            }
+        )
+
+    monkeypatch.setattr(httpx, "post", fake_post)
+
+    results = rerank_chunks("query", candidates()[:2], RerankConfig())
+
+    assert {result.chunk_id: result.rerank_score for result in results} == {1: 0.0, 2: 1.0}

tests/test_ebook_search_ui.py

@@ -0,0 +1,303 @@
+"""Tests for EPUB search HTMX routes."""
+
+from __future__ import annotations
+
+from compression import zstd
+from fastapi.testclient import TestClient
+from sqlalchemy import create_engine
+
+from python.ebook_search.api.bm25_tasks import refresh_bm25_for_engine
+from python.ebook_search.api.main import create_app
+from python.ebook_search.config import EbookSearchConfig, RerankConfig
+from python.ebook_search.embeddings import EmbeddingModelStats
+from python.ebook_search.search import SearchResponse, SearchResult
+from python.ebook_search.timing import RuntimeStep
+
+
+def patch_app_runtime(monkeypatch):
+    """Patch app startup dependencies used by UI route tests."""
+    monkeypatch.setattr("python.ebook_search.api.main.get_postgres_engine", fake_get_postgres_engine)
+    monkeypatch.setattr("python.ebook_search.api.main.ensure_bm25_corpus", lambda _session, _config: None)
+
+
+def fake_get_postgres_engine(**_kwargs):
+    """Return an in-memory engine for route tests."""
+    return create_engine("sqlite+pysqlite:///:memory:", future=True)
+
+
+def test_search_page_uses_zstd_when_requested(monkeypatch) -> None:
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+    app.state.config = EbookSearchConfig(rerank=RerankConfig(enabled=False))
+
+    with TestClient(app) as client:
+        response = client.get("/", headers={"accept-encoding": "zstd"})
+
+    assert response.status_code == 200
+    assert response.headers["content-encoding"] == "zstd"
+    assert b"EPUB Search" in zstd.decompress(response.content)
+
+
+def test_ui_form_passes_rerank_flag_to_search_handler(monkeypatch) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_search_ebooks(_engine, query, config, *, rerank=False):
+        captured["query"] = query
+        captured["rerank"] = rerank
+        captured["config"] = config
+        return SearchResponse(query=query, results=[], rank_label="Hybrid + rerank")
+
+    monkeypatch.setattr("python.ebook_search.api.routes.search.search_ebooks", fake_search_ebooks)
+    monkeypatch.setattr(
+        "python.ebook_search.api.routes.search.answer_query",
+        lambda _query, _results, _config: "answer",
+    )
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+    app.state.config = EbookSearchConfig(rerank=RerankConfig(enabled=False), top_k=12, answer_enabled=True)
+
+    with TestClient(app) as client:
+        response = client.post("/search", data={"query": "where is the quote?", "rerank": "true"})
+
+    assert response.status_code == 200
+    assert "Hybrid + rerank" in response.text
+    assert captured["query"] == "where is the quote?"
+    assert captured["rerank"] is True
+
+
+def test_ui_search_failure_returns_visible_error(monkeypatch) -> None:
+    def fake_search_ebooks(_engine, _query, _config, *, rerank=False):
+        del rerank
+        msg = "search exploded"
+        raise RuntimeError(msg)
+
+    monkeypatch.setattr("python.ebook_search.api.routes.search.search_ebooks", fake_search_ebooks)
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+    app.state.config = EbookSearchConfig(rerank=RerankConfig(enabled=False), top_k=12)
+
+    with TestClient(app) as client:
+        response = client.post("/search", data={"query": "where is the quote?"})
+
+    assert response.status_code == 500
+    assert "search exploded" in response.text
+
+
+def test_ui_answer_failure_still_returns_sources(monkeypatch) -> None:
+    def fake_search_ebooks(_engine, query, _config, *, rerank=False):
+        del rerank
+        return SearchResponse(query=query, results=[], rank_label="Hybrid")
+
+    def fake_answer_query(_query, _results, _config):
+        msg = "answer exploded"
+        raise RuntimeError(msg)
+
+    monkeypatch.setattr("python.ebook_search.api.routes.search.search_ebooks", fake_search_ebooks)
+    monkeypatch.setattr("python.ebook_search.api.routes.search.answer_query", fake_answer_query)
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+    app.state.config = EbookSearchConfig(rerank=RerankConfig(enabled=False), top_k=12, answer_enabled=True)
+
+    with TestClient(app) as client:
+        response = client.post("/search", data={"query": "where is the quote?"})
+
+    assert response.status_code == 200
+    assert "Answer generation failed" in response.text
+
+
+def test_ui_skips_answer_when_disabled(monkeypatch) -> None:
+    called = False
+
+    def fake_search_ebooks(_engine, query, _config, *, rerank=False):
+        del rerank
+        return SearchResponse(query=query, results=[], rank_label="Hybrid")
+
+    def fake_answer_query(_query, _results, _config):
+        nonlocal called
+        called = True
+        return "answer"
+
+    monkeypatch.setattr("python.ebook_search.api.routes.search.search_ebooks", fake_search_ebooks)
+    monkeypatch.setattr("python.ebook_search.api.routes.search.answer_query", fake_answer_query)
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+    app.state.config = EbookSearchConfig(rerank=RerankConfig(enabled=False), answer_enabled=False)
+
+    with TestClient(app) as client:
+        response = client.post("/search", data={"query": "where is the quote?"})
+
+    assert response.status_code == 200
+    assert called is False
+    assert "Answer generation is disabled" in response.text
+
+
+def test_ui_shows_component_scores(monkeypatch) -> None:
+    def fake_search_ebooks(_engine, query, _config, *, rerank=False):
+        del rerank
+        return SearchResponse(
+            query=query,
+            rank_label="Hybrid + rerank",
+            results=[
+                SearchResult(
+                    chunk_id=1,
+                    text="source text",
+                    source_title="Book",
+                    score=0.9,
+                    rerank_score=0.9,
+                    vector_score=0.8,
+                    bm25_score=2.5,
+                    fused_score=0.03,
+                )
+            ],
+        )
+
+    monkeypatch.setattr("python.ebook_search.api.routes.search.search_ebooks", fake_search_ebooks)
+    monkeypatch.setattr(
+        "python.ebook_search.api.routes.search.answer_query",
+        lambda _query, _results, _config: "answer",
+    )
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+    app.state.config = EbookSearchConfig(rerank=RerankConfig(enabled=False), answer_enabled=True)
+
+    with TestClient(app) as client:
+        response = client.post("/search", data={"query": "where is the quote?"})
+
+    assert response.status_code == 200
+    assert "rerank" in response.text
+    assert "vector cosine" in response.text
+    assert "BM25" in response.text
+    assert "RRF" in response.text
+
+
+def test_ui_shows_search_runtime_chart(monkeypatch) -> None:
+    def fake_search_ebooks(_engine, query, _config, *, rerank=False):
+        del rerank
+        return SearchResponse(
+            query=query,
+            rank_label="Hybrid",
+            results=[],
+            timings=(
+                RuntimeStep(name="Embedding + vector search", duration_ms=12.5),
+                RuntimeStep(name="BM25 search", duration_ms=4.0),
+            ),
+        )
+
+    monkeypatch.setattr("python.ebook_search.api.routes.search.search_ebooks", fake_search_ebooks)
+    monkeypatch.setattr(
+        "python.ebook_search.api.routes.search.answer_query",
+        lambda _query, _results, _config: "answer",
+    )
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+    app.state.config = EbookSearchConfig(rerank=RerankConfig(enabled=False), answer_enabled=True)
+
+    with TestClient(app) as client:
+        response = client.post("/search", data={"query": "where is the quote?"})
+
+    assert response.status_code == 200
+    assert "Runtime" in response.text
+    assert "Total" in response.text
+    assert "Embedding + vector search" in response.text
+    assert "BM25 search" in response.text
+    assert "Answer generation" in response.text
+    assert "ms left" in response.text
+
+
+def test_ui_embed_all_batches_until_complete(monkeypatch) -> None:
+    counts = iter([32, 32, 5, 0])
+    batch_sizes: list[int] = []
+
+    def fake_embed_missing_chunks(_session, config):
+        batch_sizes.append(config.embedding_batch_size)
+        return next(counts)
+
+    monkeypatch.setattr("python.ebook_search.api.routes.admin.embed_missing_chunks", fake_embed_missing_chunks)
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+
+    with TestClient(app) as client:
+        response = client.post("/admin/embed-all")
+
+    assert response.status_code == 200
+    assert "Embedded 69 chunks in 3 batches of 32" in response.text
+    assert batch_sizes == [32, 32, 32, 32]
+
+
+def test_ui_scan_schedules_bm25_refresh_after_database_change(monkeypatch) -> None:
+    scheduled = False
+
+    def fake_ingest_configured_paths(_session, _config):
+        return 1
+
+    def fake_schedule_bm25_refresh(_app):
+        nonlocal scheduled
+        scheduled = True
+
+    monkeypatch.setattr("python.ebook_search.api.routes.admin.ingest_configured_paths", fake_ingest_configured_paths)
+    monkeypatch.setattr("python.ebook_search.api.routes.admin.schedule_bm25_refresh", fake_schedule_bm25_refresh)
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+
+    with TestClient(app) as client:
+        response = client.post("/admin/scan")
+
+    assert response.status_code == 200
+    assert "Indexed 1 EPUBs" in response.text
+    assert scheduled is True
+
+
+def test_bm25_refresh_clears_loaded_corpus_cache(monkeypatch) -> None:
+    refreshed: list[object] = []
+    cache_cleared = False
+
+    def fake_refresh_bm25_corpus(session, config):
+        refreshed.append((session, config))
+
+    def fake_cache_clear():
+        nonlocal cache_cleared
+        cache_cleared = True
+
+    monkeypatch.setattr("python.ebook_search.api.bm25_tasks.refresh_bm25_corpus", fake_refresh_bm25_corpus)
+    monkeypatch.setattr("python.ebook_search.api.bm25_tasks.load_bm25_corpus.cache_clear", fake_cache_clear)
+    engine = create_engine("sqlite+pysqlite:///:memory:", future=True)
+    config = EbookSearchConfig(rerank=RerankConfig(enabled=False))
+
+    refresh_bm25_for_engine(engine, config)
+
+    assert len(refreshed) == 1
+    assert refreshed[0][1] == config
+    assert cache_cleared is True
+
+
+def test_admin_page_shows_embedding_counts_by_model(monkeypatch) -> None:
+    def fake_embedding_model_stats(_session):
+        return [
+            EmbeddingModelStats(
+                model_name="qwen3-embedding-0.6b",
+                dimension=1024,
+                embedded_chunks=40,
+                total_chunks=64,
+            ),
+            EmbeddingModelStats(
+                model_name="qwen3-embedding-4b",
+                dimension=2560,
+                embedded_chunks=8,
+                total_chunks=64,
+            ),
+        ]
+
+    monkeypatch.setattr("python.ebook_search.api.routes.admin.embedding_model_stats", fake_embedding_model_stats)
+    patch_app_runtime(monkeypatch)
+    app = create_app()
+
+    with TestClient(app) as client:
+        response = client.get("/admin")
+
+    assert response.status_code == 200
+    assert "qwen3-embedding-0.6b" in response.text
+    assert "1024" in response.text
+    assert "40" in response.text
+    assert "24" in response.text
+    assert "qwen3-embedding-4b" in response.text
+    assert "2560" in response.text

tests/test_gitea_flake_lock.py

@@ -0,0 +1,113 @@
+"""Tests for Gitea flake.lock automation."""
+
+from __future__ import annotations
+
+from python.gitea import PullRequest
+from python.gitea_flake_lock import (
+    PR_CHECK_WORKFLOWS,
+    PR_LABELS,
+    dispatch_pull_request_checks,
+    ensure_flake_lock_pull_request,
+    find_flake_lock_pull_request,
+)
+
+
+def _pull_request(number=1, head_branch="automation/update-flake-lock"):
+    return PullRequest(
+        number=number,
+        title="Update flake.lock",
+        html_url=f"https://gitea.example.test/pulls/{number}",
+        labels=(),
+        head_branch=head_branch,
+        base_branch="main",
+    )
+
+
+class FakeGiteaClient:
+    def __init__(self, pull_requests=None):
+        self.pull_requests = pull_requests or []
+        self.dispatch_calls = []
+        self.list_calls = []
+        self.create_calls = []
+
+    def list_open_pull_requests(self, **kwargs):
+        self.list_calls.append(kwargs)
+        return self.pull_requests
+
+    def create_pull_request(self, **kwargs):
+        self.create_calls.append(kwargs)
+        return _pull_request()
+
+    def dispatch_workflow(self, **kwargs):
+        self.dispatch_calls.append(kwargs)
+
+
+def test_ensure_flake_lock_pull_request_finds_by_branch():
+    pull_request = _pull_request()
+    client = FakeGiteaClient([pull_request])
+
+    result = ensure_flake_lock_pull_request(
+        client,
+        owner="Richie",
+        repo="dotfiles",
+        branch="automation/update-flake-lock",
+        base="main",
+    )
+
+    assert result == pull_request
+    assert client.list_calls == [
+        {"owner": "Richie", "repo": "dotfiles", "head": "automation/update-flake-lock"},
+    ]
+    assert client.create_calls == []
+
+
+def test_ensure_flake_lock_pull_request_creates_with_labels():
+    client = FakeGiteaClient()
+
+    ensure_flake_lock_pull_request(
+        client,
+        owner="Richie",
+        repo="dotfiles",
+        branch="automation/update-flake-lock",
+        base="main",
+    )
+
+    assert client.create_calls == [
+        {
+            "owner": "Richie",
+            "repo": "dotfiles",
+            "title": "Update flake.lock",
+            "body": "Automated flake.lock update.",
+            "head": "automation/update-flake-lock",
+            "base": "main",
+            "labels": PR_LABELS,
+        },
+    ]
+
+
+def test_find_flake_lock_pull_request_finds_by_label():
+    pull_request = _pull_request()
+    client = FakeGiteaClient([pull_request])
+
+    result = find_flake_lock_pull_request(client, owner="Richie", repo="dotfiles")
+
+    assert result == pull_request
+    assert client.list_calls == [
+        {"owner": "Richie", "repo": "dotfiles", "labels": ["flake_lock_update"]},
+    ]
+
+
+def test_dispatch_pull_request_checks_runs_each_workflow():
+    client = FakeGiteaClient()
+
+    dispatch_pull_request_checks(client, owner="Richie", repo="dotfiles", branch="automation/update-flake-lock")
+
+    assert client.dispatch_calls == [
+        {
+            "owner": "Richie",
+            "repo": "dotfiles",
+            "workflow_id": workflow,
+            "ref": "automation/update-flake-lock",
+        }
+        for workflow in PR_CHECK_WORKFLOWS
+    ]