updated series_index to float and added UniqueConstraint to audiobook and audiobook_author

this code was moved to https://gitea.tmmworkshop.com/Nornsight/weave

.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: |
+        run: >-
-          pr_number=$(gh pr list --state open --author RichieCahill --label flake_lock_update --json number --jq '.[0].number')
+          nix develop .#devShells.x86_64-linux.default -c
-          echo "pr_number=$pr_number" >> $GITHUB_ENV
+          python -m python.gitea_flake_lock merge
-          if [ -n "$pr_number" ]; then
+          --repo "${{ github.repository }}"
-            gh pr merge "$pr_number" --rebase
-          else
-            echo "No open PR found with label flake_lock_update"
-          fi
         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
+        run: nix flake update
-        with:
+      - name: Create or update flake.lock PR
-          token: ${{ secrets.GH_TOKEN_FOR_UPDATES }}
+        env:
-          pr-title: "Update flake.lock"
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-          pr-labels: |
+          GITEA_URL: https://gitea.tmmworkshop.com
-            dependencies
+        run: >-
-            automated
+          nix develop .#devShells.x86_64-linux.default -c
-            flake_lock_update
+          python -m python.gitea_flake_lock update
+          --repo "${{ github.repository }}"

.gitignore

@@ -169,3 +169,6 @@ test.*
 # Frontend build output
 frontend/dist/
 frontend/node_modules/
+
+# data from testing llms
+data/*

.vscode/settings.json

@@ -40,7 +40,6 @@
     "cgroupdriver",
     "charliermarsh",
     "Checkpointing",
-    "cloudflared",
     "codellama",
     "codezombiech",
     "compactmode",
@@ -204,6 +203,7 @@
     "peerconnection",
     "PESKYFOX",
     "PGID",
+    "pgvector",
     "pipewire",
     "pkgs",
     "plugdev",
@@ -232,6 +232,7 @@
     "pyopenweathermap",
     "pyownet",
     "pytest",
+    "qalculate",
     "quicksuggest",
     "radarr",
     "readahead",
@@ -256,6 +257,7 @@
     "sessionmaker",
     "sessionstore",
     "shellcheck",
+    "signalbot",
     "signon",
     "Signons",
     "skia",
@@ -305,6 +307,8 @@
     "useragent",
     "usernamehw",
     "userprefs",
+    "vaninventory",
+    "vdev",
     "vfat",
     "victron",
     "virt",

AGENTS.md

@@ -1,12 +0,0 @@
-## Dev environment tips
-
-- use treefmt to format all files
-- make python code ruff compliant
-- use pytest to test python code
-- always use the minimum amount of complexity
-- if judgment calls are easy to reverse make them. if not ask me first
-- Match existing code style.
-- Use builtin helpers getenv() over os.environ.get.
-- Prefer single-purpose functions over “do everything” helpers.
-- Avoid compatibility branches like PG_USER and POSTGRESQL_URL unless requested.
-- Keep helpers only if reused or they simplify the code otherwise inline.

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/global/nix.nix

@@ -34,6 +34,7 @@ in
       warn-dirty = false;
       flake-registry = ""; # disable global flake registries
       connect-timeout = 10;
+      download-buffer-size = 536870912;
       fallback = true;
     };
 

common/optional/brain_substituter.nix

@@ -0,0 +1,6 @@
+{
+  nix.settings = {
+    trusted-substituters = [ "http://192.168.95.35:5000" ];
+    substituters = [ "http://192.168.95.35:5000/?priority=1&want-mass-query=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/syncthing_base.nix

@@ -12,7 +12,7 @@
       brain.id = "SSCGIPI-IV3VYKB-TRNIJE3-COV4T2H-CDBER7F-I2CGHYA-NWOEUDU-3T5QAAN"; # cspell:disable-line
       ipad.id = "KI76T3X-SFUGV2L-VSNYTKR-TSIUV5L-SHWD3HE-GQRGRCN-GY4UFMD-CW6Z6AX"; # cspell:disable-line
       jeeves.id = "ICRHXZW-ECYJCUZ-I4CZ64R-3XRK7CG-LL2HAAK-FGOHD22-BQA4AI6-5OAL6AG"; # cspell:disable-line
-      phone.id = "TBRULKD-7DZPGGZ-F6LLB7J-MSO54AY-7KLPBIN-QOFK6PX-W2HBEWI-PHM2CQI"; # cspell:disable-line
+      phone.id = "JPVQKQW-CFXOJXT-Q5G5F3H-QIDHDRE-GKHPTQB-GXZUQSP-U7FR7F7-INP3AAH"; # cspell:disable-line
       rhapsody-in-green.id = "ASL3KC4-3XEN6PA-7BQBRKE-A7JXLI6-DJT43BY-Q4WPOER-7UALUAZ-VTPQ6Q4"; # cspell:disable-line
     };
   };

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": 1772824881,
+        "lastModified": 1781150628,
-        "narHash": "sha256-NqX+JCA8hRV3GoYrsqnHB2IWKte1eQ8NK2WVbJkORcw=",
+        "narHash": "sha256-b4mp8l3qWuSCyYYo9HSngDtcB3PpecYiOXjULrjwwlw=",
         "owner": "rycee",
         "repo": "nur-expressions",
-        "rev": "07e1616c9b13fe4794dad4bcc33cd7088c554465",
+        "rev": "753319310f4673a2dabbfab87482187b40bf9bac",
         "type": "gitlab"
       },
       "original": {
@@ -29,11 +29,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1772807318,
+        "lastModified": 1781189114,
-        "narHash": "sha256-Qjw6ILt8cb2HQQpCmWNLMZZ63wEo1KjTQt+1BcQBr7k=",
+        "narHash": "sha256-5inaamLgUMWy+MOBE9ChF9QAF1o/74LFuHkI0W/9rqc=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "daa2c221320809f5514edde74d0ad0193ad54ed8",
+        "rev": "486595d2cf49cfcd649b58a284fa11ac0e34da22",
         "type": "github"
       },
       "original": {
@@ -43,12 +43,15 @@
       }
     },
     "nixos-hardware": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      },
       "locked": {
-        "lastModified": 1771969195,
+        "lastModified": 1781168557,
-        "narHash": "sha256-qwcDBtrRvJbrrnv1lf/pREQi8t2hWZxVAyeMo7/E9sw=",
+        "narHash": "sha256-LOnLQ2tpYF9gqIDDr3+j3DbpJJr/QCH6zPRT2GzEUOE=",
         "owner": "nixos",
         "repo": "nixos-hardware",
-        "rev": "41c6b421bdc301b2624486e11905c9af7b8ec68e",
+        "rev": "6358ff76821101c178e3ab4919a62799bfe3652e",
         "type": "github"
       },
       "original": {
@@ -60,27 +63,24 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1772624091,
+        "lastModified": 1767892417,
-        "narHash": "sha256-QKyJ0QGWBn6r0invrMAK8dmJoBYWoOWy7lN+UHzW1jc=",
+        "narHash": "sha256-8bW3q88CEg2u4hSP66Vf4lpbLonHz7hqDNBMcCY7E9U=",
-        "owner": "nixos",
+        "rev": "3497aa5c9457a9d88d71fa93a4a8368816fbeeba",
-        "repo": "nixpkgs",
+        "type": "tarball",
-        "rev": "80bdc1e5ce51f56b19791b52b2901187931f5353",
+        "url": "https://releases.nixos.org/nixos/unstable/nixos-26.05pre924538.3497aa5c9457/nixexprs.tar.xz"
-        "type": "github"
       },
       "original": {
-        "owner": "nixos",
+        "type": "tarball",
-        "ref": "nixos-unstable",
+        "url": "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz"
-        "repo": "nixpkgs",
-        "type": "github"
       }
     },
     "nixpkgs-master": {
       "locked": {
-        "lastModified": 1772842888,
+        "lastModified": 1781229721,
-        "narHash": "sha256-bQRYIwRb9xuEMHTLd5EzjHhYMKzbUbIo7abFV84iUjM=",
+        "narHash": "sha256-ORvqDbb/LYxiJljGIejapjkc/kJbVote2N1WSb9W45I=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "af5157af67f118e13172750f63012f199b61e3a1",
+        "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": 1772495394,
+        "lastModified": 1780547341,
-        "narHash": "sha256-hmIvE/slLKEFKNEJz27IZ8BKlAaZDcjIHmkZ7GCEjfw=",
+        "narHash": "sha256-Gq8KNx5A7hBB3uGJaj6eQfLDIz5YdLu92gqBcvHvoUo=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "1d9b98a29a45abe9c4d3174bd36de9f28755e3ff",
+        "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?

frontend/README.md

@@ -1,73 +0,0 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```

frontend/eslint.config.js

@@ -1,23 +0,0 @@
-import js from '@eslint/js'
-import globals from 'globals'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
-import tseslint from 'typescript-eslint'
-import { defineConfig, globalIgnores } from 'eslint/config'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      js.configs.recommended,
-      tseslint.configs.recommended,
-      reactHooks.configs.flat.recommended,
-      reactRefresh.configs.vite,
-    ],
-    languageOptions: {
-      ecmaVersion: 2020,
-      globals: globals.browser,
-    },
-  },
-])

frontend/index.html

@@ -1,13 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>frontend</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

frontend/package.json

@@ -1,31 +0,0 @@
-{
-  "name": "frontend",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc -b && vite build",
-    "lint": "eslint .",
-    "preview": "vite preview"
-  },
-  "dependencies": {
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-router-dom": "^7.12.0"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^24.10.1",
-    "@types/react": "^19.2.5",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.1",
-    "eslint": "^9.39.1",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.4.24",
-    "globals": "^16.5.0",
-    "typescript": "~5.9.3",
-    "typescript-eslint": "^8.46.4",
-    "vite": "^7.2.4"
-  }
-}

frontend/public/vite.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

frontend/src/App.css

@@ -1,654 +0,0 @@
-* {
-  box-sizing: border-box;
-}
-
-body {
-  margin: 0;
-  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-  background: var(--color-bg);
-  color: var(--color-text);
-}
-
-.app {
-  max-width: 1000px;
-  margin: 0 auto;
-  padding: 20px;
-}
-
-nav {
-  display: flex;
-  align-items: center;
-  gap: 20px;
-  padding: 15px 0;
-  border-bottom: 1px solid var(--color-border);
-  margin-bottom: 20px;
-}
-
-.theme-toggle {
-  margin-left: auto;
-}
-
-nav a {
-  color: var(--color-primary);
-  text-decoration: none;
-  font-weight: 500;
-}
-
-nav a:hover {
-  text-decoration: underline;
-}
-
-main {
-  background: var(--color-bg-card);
-  padding: 20px;
-  border-radius: 8px;
-  box-shadow: var(--shadow);
-}
-
-.header {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  margin-bottom: 20px;
-}
-
-.header h1 {
-  margin: 0;
-}
-
-.btn {
-  display: inline-block;
-  padding: 8px 16px;
-  border: 1px solid var(--color-border);
-  border-radius: 4px;
-  background: var(--color-bg-card);
-  color: var(--color-text);
-  text-decoration: none;
-  cursor: pointer;
-  font-size: 14px;
-  margin-left: 8px;
-}
-
-.btn:hover {
-  background: var(--color-bg-hover);
-}
-
-.btn-primary {
-  background: var(--color-primary);
-  border-color: var(--color-primary);
-  color: white;
-}
-
-.btn-primary:hover {
-  background: var(--color-primary-hover);
-}
-
-.btn-danger {
-  background: var(--color-danger);
-  border-color: var(--color-danger);
-  color: white;
-}
-
-.btn-danger:hover {
-  background: var(--color-danger-hover);
-}
-
-.btn-small {
-  padding: 4px 8px;
-  font-size: 12px;
-}
-
-.btn:disabled {
-  opacity: 0.6;
-  cursor: not-allowed;
-}
-
-table {
-  width: 100%;
-  border-collapse: collapse;
-}
-
-th,
-td {
-  padding: 12px;
-  text-align: left;
-  border-bottom: 1px solid var(--color-border-light);
-}
-
-th {
-  font-weight: 600;
-  background: var(--color-bg-muted);
-}
-
-tr:hover {
-  background: var(--color-bg-muted);
-}
-
-.error {
-  background: var(--color-bg-error);
-  color: var(--color-text-error);
-  padding: 10px;
-  border-radius: 4px;
-  margin-bottom: 20px;
-}
-
-.info-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
-  gap: 10px;
-  margin-bottom: 20px;
-}
-
-.section {
-  margin-top: 30px;
-  padding-top: 20px;
-  border-top: 1px solid var(--color-border-light);
-}
-
-.section h3 {
-  margin-top: 0;
-  margin-bottom: 15px;
-}
-
-.section h4 {
-  margin: 15px 0 10px;
-  font-size: 14px;
-  color: var(--color-text-muted);
-}
-
-.section ul {
-  list-style: none;
-  padding: 0;
-  margin: 0;
-}
-
-.section li {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  padding: 8px 0;
-  border-bottom: 1px solid var(--color-border-lighter);
-}
-
-.tag {
-  display: inline-block;
-  background: var(--color-tag-bg);
-  padding: 2px 8px;
-  border-radius: 12px;
-  font-size: 12px;
-  color: var(--color-text-muted);
-}
-
-.add-form {
-  display: flex;
-  gap: 10px;
-  margin-top: 15px;
-  flex-wrap: wrap;
-}
-
-.add-form select,
-.add-form input {
-  padding: 8px;
-  border: 1px solid var(--color-border);
-  border-radius: 4px;
-  min-width: 200px;
-  background: var(--color-bg-card);
-  color: var(--color-text);
-}
-
-.form-group {
-  margin-bottom: 20px;
-}
-
-.form-group label {
-  display: block;
-  font-weight: 500;
-  margin-bottom: 5px;
-}
-
-.form-group input,
-.form-group textarea,
-.form-group select {
-  width: 100%;
-  padding: 10px;
-  border: 1px solid var(--color-border);
-  border-radius: 4px;
-  font-size: 14px;
-  background: var(--color-bg-card);
-  color: var(--color-text);
-}
-
-.form-group textarea {
-  resize: vertical;
-}
-
-.form-row {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 20px;
-}
-
-.checkbox-group {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 15px;
-}
-
-.checkbox-label {
-  display: flex;
-  align-items: center;
-  gap: 5px;
-  cursor: pointer;
-}
-
-.form-actions {
-  display: flex;
-  gap: 10px;
-  margin-top: 30px;
-  padding-top: 20px;
-  border-top: 1px solid var(--color-border-light);
-}
-
-.need-list .header {
-  margin-bottom: 20px;
-}
-
-.need-form {
-  background: var(--color-bg-muted);
-  padding: 20px;
-  border-radius: 4px;
-  margin-bottom: 20px;
-}
-
-.need-items {
-  list-style: none;
-  padding: 0;
-}
-
-.need-items li {
-  display: flex;
-  justify-content: space-between;
-  align-items: flex-start;
-  padding: 15px;
-  border: 1px solid var(--color-border-light);
-  border-radius: 4px;
-  margin-bottom: 10px;
-}
-
-.need-info p {
-  margin: 5px 0 0;
-  color: var(--color-text-muted);
-  font-size: 14px;
-}
-
-a {
-  color: var(--color-primary);
-}
-
-a:hover {
-  text-decoration: underline;
-}
-
-/* Graph styles */
-.graph-container {
-  width: 100%;
-}
-
-.graph-hint {
-  color: var(--color-text-muted);
-  font-size: 14px;
-  margin-bottom: 15px;
-}
-
-.selected-info {
-  margin-top: 15px;
-  padding: 15px;
-  background: var(--color-bg-muted);
-  border-radius: 8px;
-}
-
-.selected-info h3 {
-  margin: 0 0 10px;
-}
-
-.selected-info p {
-  margin: 5px 0;
-  color: var(--color-text-muted);
-}
-
-.legend {
-  margin-top: 20px;
-  padding: 15px;
-  background: var(--color-bg-muted);
-  border-radius: 8px;
-}
-
-.legend h4 {
-  margin: 0 0 10px;
-  font-size: 14px;
-}
-
-.legend-items {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 15px;
-}
-
-.legend-item {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  font-size: 12px;
-  color: var(--color-text-muted);
-}
-
-.legend-line {
-  width: 30px;
-  border-radius: 2px;
-}
-
-/* Weight control styles */
-.weight-control {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  font-size: 12px;
-  color: var(--color-text-muted);
-}
-
-.weight-control input[type="range"] {
-  width: 80px;
-  cursor: pointer;
-}
-
-.weight-value {
-  min-width: 20px;
-  text-align: center;
-  font-weight: 600;
-}
-
-.weight-display {
-  font-size: 12px;
-  color: var(--color-text-muted);
-  margin-left: auto;
-}
-
-/* ID Card Styles */
-.id-card {
-  width: 100%;
-}
-
-.id-card-inner {
-  background: linear-gradient(135deg, #0a0a0f 0%, #1a1a2e 50%, #0a0a0f 100%);
-  background-image:
-    radial-gradient(white 1px, transparent 1px),
-    linear-gradient(135deg, #0a0a0f 0%, #1a1a2e 50%, #0a0a0f 100%);
-  background-size: 50px 50px, 100% 100%;
-  background-position: 0 0, 0 0;
-  color: #fff;
-  border-radius: 12px;
-  padding: 25px;
-  min-height: 500px;
-  position: relative;
-  overflow: hidden;
-}
-
-.id-card-header {
-  display: flex;
-  justify-content: space-between;
-  align-items: flex-start;
-  margin-bottom: 15px;
-}
-
-.id-card-header-left {
-  flex: 1;
-}
-
-.id-card-header-right {
-  display: flex;
-  flex-direction: column;
-  align-items: flex-end;
-  gap: 10px;
-}
-
-.id-card-title {
-  font-size: 2.5rem;
-  font-weight: 700;
-  margin: 0;
-  color: #fff;
-  text-shadow: 2px 2px 4px rgba(0,0,0,0.5);
-}
-
-.id-profile-pic {
-  width: 80px;
-  height: 80px;
-  border-radius: 8px;
-  object-fit: cover;
-  border: 2px solid rgba(255,255,255,0.3);
-}
-
-.id-profile-placeholder {
-  width: 80px;
-  height: 80px;
-  border-radius: 8px;
-  background: linear-gradient(135deg, #4ecdc4 0%, #44a8a0 100%);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  border: 2px solid rgba(255,255,255,0.3);
-}
-
-.id-profile-placeholder span {
-  font-size: 2rem;
-  font-weight: 700;
-  color: #fff;
-  text-shadow: 1px 1px 2px rgba(0,0,0,0.3);
-}
-
-.id-card-actions {
-  display: flex;
-  gap: 8px;
-}
-
-.id-card-actions .btn {
-  background: rgba(255,255,255,0.1);
-  border-color: rgba(255,255,255,0.3);
-  color: #fff;
-}
-
-.id-card-actions .btn:hover {
-  background: rgba(255,255,255,0.2);
-}
-
-.id-card-body {
-  display: grid;
-  grid-template-columns: 1fr 1.5fr;
-  gap: 30px;
-}
-
-.id-card-left {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-
-.id-field {
-  font-size: 1rem;
-  line-height: 1.4;
-}
-
-.id-field-block {
-  margin-top: 15px;
-  font-size: 0.95rem;
-  line-height: 1.5;
-}
-
-.id-label {
-  color: #4ecdc4;
-  font-weight: 500;
-}
-
-.id-card-right {
-  display: flex;
-  flex-direction: column;
-  gap: 20px;
-}
-
-.id-bio {
-  font-size: 0.9rem;
-  line-height: 1.6;
-  color: #e0e0e0;
-}
-
-.id-relationships {
-  margin-top: 10px;
-}
-
-.id-section-title {
-  font-size: 1.5rem;
-  margin: 0 0 15px;
-  color: #fff;
-  border-bottom: 1px solid rgba(255,255,255,0.2);
-  padding-bottom: 8px;
-}
-
-.id-rel-group {
-  margin-bottom: 12px;
-  font-size: 0.9rem;
-  line-height: 1.6;
-}
-
-.id-rel-label {
-  color: #a0a0a0;
-}
-
-.id-rel-group a {
-  color: #4ecdc4;
-  text-decoration: none;
-}
-
-.id-rel-group a:hover {
-  text-decoration: underline;
-}
-
-.id-rel-type {
-  color: #888;
-  font-size: 0.85em;
-}
-
-.id-card-warnings {
-  margin-top: 30px;
-  padding-top: 20px;
-  border-top: 1px solid rgba(255,255,255,0.2);
-  display: flex;
-  flex-wrap: wrap;
-  gap: 20px;
-}
-
-.id-warning {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  font-size: 0.9rem;
-  color: #ff6b6b;
-}
-
-.warning-dot {
-  width: 8px;
-  height: 8px;
-  background: #ff6b6b;
-  border-radius: 50%;
-  flex-shrink: 0;
-}
-
-.warning-desc {
-  color: #ccc;
-}
-
-/* Management section */
-.id-card-manage {
-  margin-top: 20px;
-  background: var(--color-bg-muted);
-  border-radius: 8px;
-  padding: 15px;
-}
-
-.id-card-manage summary {
-  cursor: pointer;
-  font-weight: 600;
-  font-size: 1.1rem;
-  padding: 5px 0;
-}
-
-.id-card-manage[open] summary {
-  margin-bottom: 15px;
-  border-bottom: 1px solid var(--color-border-light);
-  padding-bottom: 10px;
-}
-
-.manage-section {
-  margin-bottom: 25px;
-}
-
-.manage-section h3 {
-  margin: 0 0 15px;
-  font-size: 1rem;
-}
-
-.manage-relationships {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-  margin-bottom: 15px;
-}
-
-.manage-rel-item {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  padding: 10px;
-  background: var(--color-bg-card);
-  border-radius: 6px;
-  flex-wrap: wrap;
-}
-
-.manage-rel-item a {
-  font-weight: 500;
-  min-width: 120px;
-}
-
-.manage-needs-list {
-  list-style: none;
-  padding: 0;
-  margin: 0 0 15px;
-}
-
-.manage-needs-list li {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  padding: 10px;
-  background: var(--color-bg-card);
-  border-radius: 6px;
-  margin-bottom: 8px;
-}
-
-.manage-needs-list li .btn {
-  margin-left: auto;
-}
-
-/* Responsive adjustments */
-@media (max-width: 768px) {
-  .id-card-body {
-    grid-template-columns: 1fr;
-  }
-
-  .id-card-title {
-    font-size: 1.8rem;
-  }
-
-  .id-card-header {
-    flex-direction: column;
-    gap: 15px;
-  }
-}

frontend/src/App.tsx

@@ -1,50 +0,0 @@
-import { useEffect, useState } from "react";
-import { Link, Route, Routes } from "react-router-dom";
-import { ContactDetail } from "./components/ContactDetail";
-import { ContactForm } from "./components/ContactForm";
-import { ContactList } from "./components/ContactList";
-import { NeedList } from "./components/NeedList";
-import { RelationshipGraph } from "./components/RelationshipGraph";
-import "./App.css";
-
-function App() {
-  const [theme, setTheme] = useState<"light" | "dark">(() => {
-    return (localStorage.getItem("theme") as "light" | "dark") || "light";
-  });
-
-  useEffect(() => {
-    document.documentElement.setAttribute("data-theme", theme);
-    localStorage.setItem("theme", theme);
-  }, [theme]);
-
-  const toggleTheme = () => {
-    setTheme((prev) => (prev === "light" ? "dark" : "light"));
-  };
-
-  return (
-    <div className="app">
-      <nav>
-        <Link to="/contacts">Contacts</Link>
-        <Link to="/graph">Graph</Link>
-        <Link to="/needs">Needs</Link>
-        <button className="btn btn-small theme-toggle" onClick={toggleTheme}>
-          {theme === "light" ? "Dark" : "Light"}
-        </button>
-      </nav>
-
-      <main>
-        <Routes>
-          <Route path="/" element={<ContactList />} />
-          <Route path="/contacts" element={<ContactList />} />
-          <Route path="/contacts/new" element={<ContactForm />} />
-          <Route path="/contacts/:id" element={<ContactDetail />} />
-          <Route path="/contacts/:id/edit" element={<ContactForm />} />
-          <Route path="/graph" element={<RelationshipGraph />} />
-          <Route path="/needs" element={<NeedList />} />
-        </Routes>
-      </main>
-    </div>
-  );
-}
-
-export default App;

frontend/src/api/client.ts

@@ -1,105 +0,0 @@
-import type {
-  Contact,
-  ContactCreate,
-  ContactListItem,
-  ContactRelationship,
-  ContactRelationshipCreate,
-  ContactRelationshipUpdate,
-  ContactUpdate,
-  GraphData,
-  Need,
-  NeedCreate,
-} from "../types";
-
-const API_BASE = "";
-
-async function request<T>(
-  endpoint: string,
-  options?: RequestInit
-): Promise<T> {
-  const response = await fetch(`${API_BASE}${endpoint}`, {
-    ...options,
-    headers: {
-      "Content-Type": "application/json",
-      ...options?.headers,
-    },
-  });
-
-  if (!response.ok) {
-    const error = await response.json().catch(() => ({}));
-    throw new Error(error.detail || `HTTP ${response.status}`);
-  }
-
-  return response.json();
-}
-
-export const api = {
-  // Needs
-  needs: {
-    list: () => request<Need[]>("/api/needs"),
-    get: (id: number) => request<Need>(`/api/needs/${id}`),
-    create: (data: NeedCreate) =>
-      request<Need>("/api/needs", {
-        method: "POST",
-        body: JSON.stringify(data),
-      }),
-    delete: (id: number) =>
-      request<{ deleted: boolean }>(`/api/needs/${id}`, { method: "DELETE" }),
-  },
-
-  // Contacts
-  contacts: {
-    list: (skip = 0, limit = 100) =>
-      request<ContactListItem[]>(`/api/contacts?skip=${skip}&limit=${limit}`),
-    get: (id: number) => request<Contact>(`/api/contacts/${id}`),
-    create: (data: ContactCreate) =>
-      request<Contact>("/api/contacts", {
-        method: "POST",
-        body: JSON.stringify(data),
-      }),
-    update: (id: number, data: ContactUpdate) =>
-      request<Contact>(`/api/contacts/${id}`, {
-        method: "PATCH",
-        body: JSON.stringify(data),
-      }),
-    delete: (id: number) =>
-      request<{ deleted: boolean }>(`/api/contacts/${id}`, { method: "DELETE" }),
-
-    // Contact-Need relationships
-    addNeed: (contactId: number, needId: number) =>
-      request<{ added: boolean }>(`/api/contacts/${contactId}/needs/${needId}`, {
-        method: "POST",
-      }),
-    removeNeed: (contactId: number, needId: number) =>
-      request<{ removed: boolean }>(`/api/contacts/${contactId}/needs/${needId}`, {
-        method: "DELETE",
-      }),
-
-    // Contact-Contact relationships
-    getRelationships: (contactId: number) =>
-      request<ContactRelationship[]>(`/api/contacts/${contactId}/relationships`),
-    addRelationship: (contactId: number, data: ContactRelationshipCreate) =>
-      request<ContactRelationship>(`/api/contacts/${contactId}/relationships`, {
-        method: "POST",
-        body: JSON.stringify(data),
-      }),
-    updateRelationship: (contactId: number, relatedContactId: number, data: ContactRelationshipUpdate) =>
-      request<ContactRelationship>(
-        `/api/contacts/${contactId}/relationships/${relatedContactId}`,
-        {
-          method: "PATCH",
-          body: JSON.stringify(data),
-        }
-      ),
-    removeRelationship: (contactId: number, relatedContactId: number) =>
-      request<{ deleted: boolean }>(
-        `/api/contacts/${contactId}/relationships/${relatedContactId}`,
-        { method: "DELETE" }
-      ),
-  },
-
-  // Graph
-  graph: {
-    get: () => request<GraphData>("/api/graph"),
-  },
-};

frontend/src/assets/react.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="35.93" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 228"><path fill="#00D8FF" d="M210.483 73.824a171.49 171.49 0 0 0-8.24-2.597c.465-1.9.893-3.777 1.273-5.621c6.238-30.281 2.16-54.676-11.769-62.708c-13.355-7.7-35.196.329-57.254 19.526a171.23 171.23 0 0 0-6.375 5.848a155.866 155.866 0 0 0-4.241-3.917C100.759 3.829 77.587-4.822 63.673 3.233C50.33 10.957 46.379 33.89 51.995 62.588a170.974 170.974 0 0 0 1.892 8.48c-3.28.932-6.445 1.924-9.474 2.98C17.309 83.498 0 98.307 0 113.668c0 15.865 18.582 31.778 46.812 41.427a145.52 145.52 0 0 0 6.921 2.165a167.467 167.467 0 0 0-2.01 9.138c-5.354 28.2-1.173 50.591 12.134 58.266c13.744 7.926 36.812-.22 59.273-19.855a145.567 145.567 0 0 0 5.342-4.923a168.064 168.064 0 0 0 6.92 6.314c21.758 18.722 43.246 26.282 56.54 18.586c13.731-7.949 18.194-32.003 12.4-61.268a145.016 145.016 0 0 0-1.535-6.842c1.62-.48 3.21-.974 4.76-1.488c29.348-9.723 48.443-25.443 48.443-41.52c0-15.417-17.868-30.326-45.517-39.844Zm-6.365 70.984c-1.4.463-2.836.91-4.3 1.345c-3.24-10.257-7.612-21.163-12.963-32.432c5.106-11 9.31-21.767 12.459-31.957c2.619.758 5.16 1.557 7.61 2.4c23.69 8.156 38.14 20.213 38.14 29.504c0 9.896-15.606 22.743-40.946 31.14Zm-10.514 20.834c2.562 12.94 2.927 24.64 1.23 33.787c-1.524 8.219-4.59 13.698-8.382 15.893c-8.067 4.67-25.32-1.4-43.927-17.412a156.726 156.726 0 0 1-6.437-5.87c7.214-7.889 14.423-17.06 21.459-27.246c12.376-1.098 24.068-2.894 34.671-5.345a134.17 134.17 0 0 1 1.386 6.193ZM87.276 214.515c-7.882 2.783-14.16 2.863-17.955.675c-8.075-4.657-11.432-22.636-6.853-46.752a156.923 156.923 0 0 1 1.869-8.499c10.486 2.32 22.093 3.988 34.498 4.994c7.084 9.967 14.501 19.128 21.976 27.15a134.668 134.668 0 0 1-4.877 4.492c-9.933 8.682-19.886 14.842-28.658 17.94ZM50.35 144.747c-12.483-4.267-22.792-9.812-29.858-15.863c-6.35-5.437-9.555-10.836-9.555-15.216c0-9.322 13.897-21.212 37.076-29.293c2.813-.98 5.757-1.905 8.812-2.773c3.204 10.42 7.406 21.315 12.477 32.332c-5.137 11.18-9.399 22.249-12.634 32.792a134.718 134.718 0 0 1-6.318-1.979Zm12.378-84.26c-4.811-24.587-1.616-43.134 6.425-47.789c8.564-4.958 27.502 2.111 47.463 19.835a144.318 144.318 0 0 1 3.841 3.545c-7.438 7.987-14.787 17.08-21.808 26.988c-12.04 1.116-23.565 2.908-34.161 5.309a160.342 160.342 0 0 1-1.76-7.887Zm110.427 27.268a347.8 347.8 0 0 0-7.785-12.803c8.168 1.033 15.994 2.404 23.343 4.08c-2.206 7.072-4.956 14.465-8.193 22.045a381.151 381.151 0 0 0-7.365-13.322Zm-45.032-43.861c5.044 5.465 10.096 11.566 15.065 18.186a322.04 322.04 0 0 0-30.257-.006c4.974-6.559 10.069-12.652 15.192-18.18ZM82.802 87.83a323.167 323.167 0 0 0-7.227 13.238c-3.184-7.553-5.909-14.98-8.134-22.152c7.304-1.634 15.093-2.97 23.209-3.984a321.524 321.524 0 0 0-7.848 12.897Zm8.081 65.352c-8.385-.936-16.291-2.203-23.593-3.793c2.26-7.3 5.045-14.885 8.298-22.6a321.187 321.187 0 0 0 7.257 13.246c2.594 4.48 5.28 8.868 8.038 13.147Zm37.542 31.03c-5.184-5.592-10.354-11.779-15.403-18.433c4.902.192 9.899.29 14.978.29c5.218 0 10.376-.117 15.453-.343c-4.985 6.774-10.018 12.97-15.028 18.486Zm52.198-57.817c3.422 7.8 6.306 15.345 8.596 22.52c-7.422 1.694-15.436 3.058-23.88 4.071a382.417 382.417 0 0 0 7.859-13.026a347.403 347.403 0 0 0 7.425-13.565Zm-16.898 8.101a358.557 358.557 0 0 1-12.281 19.815a329.4 329.4 0 0 1-23.444.823c-7.967 0-15.716-.248-23.178-.732a310.202 310.202 0 0 1-12.513-19.846h.001a307.41 307.41 0 0 1-10.923-20.627a310.278 310.278 0 0 1 10.89-20.637l-.001.001a307.318 307.318 0 0 1 12.413-19.761c7.613-.576 15.42-.876 23.31-.876H128c7.926 0 15.743.303 23.354.883a329.357 329.357 0 0 1 12.335 19.695a358.489 358.489 0 0 1 11.036 20.54a329.472 329.472 0 0 1-11 20.722Zm22.56-122.124c8.572 4.944 11.906 24.881 6.52 51.026c-.344 1.668-.73 3.367-1.15 5.09c-10.622-2.452-22.155-4.275-34.23-5.408c-7.034-10.017-14.323-19.124-21.64-27.008a160.789 160.789 0 0 1 5.888-5.4c18.9-16.447 36.564-22.941 44.612-18.3ZM128 90.808c12.625 0 22.86 10.235 22.86 22.86s-10.235 22.86-22.86 22.86s-22.86-10.235-22.86-22.86s10.235-22.86 22.86-22.86Z"></path></svg>

frontend/src/components/ContactDetail.tsx

@@ -1,456 +0,0 @@
-import { useEffect, useState } from "react";
-import { Link, useParams } from "react-router-dom";
-import { api } from "../api/client";
-import type { Contact, ContactListItem, Need, RelationshipTypeValue } from "../types";
-import { RELATIONSHIP_TYPES } from "../types";
-
-export function ContactDetail() {
-  const { id } = useParams<{ id: string }>();
-  const [contact, setContact] = useState<Contact | null>(null);
-  const [allNeeds, setAllNeeds] = useState<Need[]>([]);
-  const [allContacts, setAllContacts] = useState<ContactListItem[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  const [newNeedId, setNewNeedId] = useState<number | "">("");
-  const [newRelContactId, setNewRelContactId] = useState<number | "">("");
-  const [newRelType, setNewRelType] = useState<RelationshipTypeValue | "">("");
-
-  useEffect(() => {
-    if (!id) return;
-    Promise.all([
-      api.contacts.get(Number(id)),
-      api.needs.list(),
-      api.contacts.list(),
-    ])
-      .then(([c, n, contacts]) => {
-        setContact(c);
-        setAllNeeds(n);
-        setAllContacts(contacts.filter((ct) => ct.id !== Number(id)));
-      })
-      .catch((err) => setError(err.message))
-      .finally(() => setLoading(false));
-  }, [id]);
-
-  const handleAddNeed = async () => {
-    if (!contact || newNeedId === "") return;
-    try {
-      await api.contacts.addNeed(contact.id, Number(newNeedId));
-      const updated = await api.contacts.get(contact.id);
-      setContact(updated);
-      setNewNeedId("");
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Failed to add need");
-    }
-  };
-
-  const handleRemoveNeed = async (needId: number) => {
-    if (!contact) return;
-    try {
-      await api.contacts.removeNeed(contact.id, needId);
-      const updated = await api.contacts.get(contact.id);
-      setContact(updated);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Failed to remove need");
-    }
-  };
-
-  const handleAddRelationship = async () => {
-    if (!contact || newRelContactId === "" || newRelType === "") return;
-    try {
-      await api.contacts.addRelationship(contact.id, {
-        related_contact_id: Number(newRelContactId),
-        relationship_type: newRelType,
-      });
-      const updated = await api.contacts.get(contact.id);
-      setContact(updated);
-      setNewRelContactId("");
-      setNewRelType("");
-    } catch (err) {
-      setError(
-        err instanceof Error ? err.message : "Failed to add relationship"
-      );
-    }
-  };
-
-  const handleRemoveRelationship = async (relatedContactId: number) => {
-    if (!contact) return;
-    try {
-      await api.contacts.removeRelationship(contact.id, relatedContactId);
-      const updated = await api.contacts.get(contact.id);
-      setContact(updated);
-    } catch (err) {
-      setError(
-        err instanceof Error ? err.message : "Failed to remove relationship"
-      );
-    }
-  };
-
-  const handleUpdateWeight = async (relatedContactId: number, newWeight: number) => {
-    if (!contact) return;
-    try {
-      await api.contacts.updateRelationship(contact.id, relatedContactId, {
-        closeness_weight: newWeight,
-      });
-      const updated = await api.contacts.get(contact.id);
-      setContact(updated);
-    } catch (err) {
-      setError(
-        err instanceof Error ? err.message : "Failed to update weight"
-      );
-    }
-  };
-
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div className="error">Error: {error}</div>;
-  if (!contact) return <div>Contact not found</div>;
-
-  const availableNeeds = allNeeds.filter(
-    (n) => !contact.needs.some((cn) => cn.id === n.id)
-  );
-
-  const getContactName = (contactId: number) => {
-    const c = allContacts.find((ct) => ct.id === contactId);
-    return c?.name || `Contact #${contactId}`;
-  };
-
-  const getRelationshipDisplayName = (type: string) => {
-    const rt = RELATIONSHIP_TYPES.find((r) => r.value === type);
-    return rt?.displayName || type;
-  };
-
-  // Group relationships by category for display
-  const groupRelationships = () => {
-    const familial: typeof contact.related_to = [];
-    const friends: typeof contact.related_to = [];
-    const partners: typeof contact.related_to = [];
-    const professional: typeof contact.related_to = [];
-    const other: typeof contact.related_to = [];
-
-    const familialTypes = ['parent', 'child', 'sibling', 'grandparent', 'grandchild', 'aunt_uncle', 'niece_nephew', 'cousin', 'in_law'];
-    const friendTypes = ['best_friend', 'close_friend', 'friend', 'acquaintance', 'neighbor'];
-    const partnerTypes = ['spouse', 'partner'];
-    const professionalTypes = ['mentor', 'mentee', 'business_partner', 'colleague', 'manager', 'direct_report', 'client'];
-
-    for (const rel of contact.related_to) {
-      if (familialTypes.includes(rel.relationship_type)) {
-        familial.push(rel);
-      } else if (friendTypes.includes(rel.relationship_type)) {
-        friends.push(rel);
-      } else if (partnerTypes.includes(rel.relationship_type)) {
-        partners.push(rel);
-      } else if (professionalTypes.includes(rel.relationship_type)) {
-        professional.push(rel);
-      } else {
-        other.push(rel);
-      }
-    }
-
-    return { familial, friends, partners, professional, other };
-  };
-
-  const relationshipGroups = groupRelationships();
-
-  return (
-    <div className="id-card">
-      <div className="id-card-inner">
-        {/* Header with name and profile pic */}
-        <div className="id-card-header">
-          <div className="id-card-header-left">
-            <h1 className="id-card-title">I.D.: {contact.name}</h1>
-          </div>
-          <div className="id-card-header-right">
-            {contact.profile_pic ? (
-              <img
-                src={contact.profile_pic}
-                alt={`${contact.name}'s profile`}
-                className="id-profile-pic"
-              />
-            ) : (
-              <div className="id-profile-placeholder">
-                <span>{contact.name.charAt(0).toUpperCase()}</span>
-              </div>
-            )}
-            <div className="id-card-actions">
-              <Link to={`/contacts/${contact.id}/edit`} className="btn btn-small">
-                Edit
-              </Link>
-              <Link to="/contacts" className="btn btn-small">
-                Back
-              </Link>
-            </div>
-          </div>
-        </div>
-
-        <div className="id-card-body">
-          {/* Left column - Basic info */}
-          <div className="id-card-left">
-            {contact.legal_name && (
-              <div className="id-field">Legal name: {contact.legal_name}</div>
-            )}
-            {contact.suffix && (
-              <div className="id-field">Suffix: {contact.suffix}</div>
-            )}
-            {contact.gender && (
-              <div className="id-field">Gender: {contact.gender}</div>
-            )}
-            {contact.age && (
-              <div className="id-field">Age: {contact.age}</div>
-            )}
-            {contact.current_job && (
-              <div className="id-field">Job: {contact.current_job}</div>
-            )}
-            {contact.social_structure_style && (
-              <div className="id-field">Social style: {contact.social_structure_style}</div>
-            )}
-            {contact.self_sufficiency_score !== null && (
-              <div className="id-field">Self-Sufficiency: {contact.self_sufficiency_score}</div>
-            )}
-            {contact.timezone && (
-              <div className="id-field">Timezone: {contact.timezone}</div>
-            )}
-
-            {contact.safe_conversation_starters && (
-              <div className="id-field-block">
-                <span className="id-label">Safe con starters:</span> {contact.safe_conversation_starters}
-              </div>
-            )}
-
-            {contact.topics_to_avoid && (
-              <div className="id-field-block">
-                <span className="id-label">Topics to avoid:</span> {contact.topics_to_avoid}
-              </div>
-            )}
-
-            {contact.goals && (
-              <div className="id-field-block">
-                <span className="id-label">Goals:</span> {contact.goals}
-              </div>
-            )}
-          </div>
-
-          {/* Right column - Bio and Relationships */}
-          <div className="id-card-right">
-            {contact.bio && (
-              <div className="id-bio">
-                <span className="id-label">Bio:</span> {contact.bio}
-              </div>
-            )}
-
-            <div className="id-relationships">
-              <h2 className="id-section-title">Relationships</h2>
-
-              {relationshipGroups.familial.length > 0 && (
-                <div className="id-rel-group">
-                  <span className="id-rel-label">Familial:</span>{" "}
-                  {relationshipGroups.familial.map((rel, i) => (
-                    <span key={rel.related_contact_id}>
-                      <Link to={`/contacts/${rel.related_contact_id}`}>
-                        {getContactName(rel.related_contact_id)}
-                      </Link>
-                      <span className="id-rel-type">({getRelationshipDisplayName(rel.relationship_type)})</span>
-                      {i < relationshipGroups.familial.length - 1 && ", "}
-                    </span>
-                  ))}
-                </div>
-              )}
-
-              {relationshipGroups.partners.length > 0 && (
-                <div className="id-rel-group">
-                  <span className="id-rel-label">Partners:</span>{" "}
-                  {relationshipGroups.partners.map((rel, i) => (
-                    <span key={rel.related_contact_id}>
-                      <Link to={`/contacts/${rel.related_contact_id}`}>
-                        {getContactName(rel.related_contact_id)}
-                      </Link>
-                      {i < relationshipGroups.partners.length - 1 && ", "}
-                    </span>
-                  ))}
-                </div>
-              )}
-
-              {relationshipGroups.friends.length > 0 && (
-                <div className="id-rel-group">
-                  <span className="id-rel-label">Friends:</span>{" "}
-                  {relationshipGroups.friends.map((rel, i) => (
-                    <span key={rel.related_contact_id}>
-                      <Link to={`/contacts/${rel.related_contact_id}`}>
-                        {getContactName(rel.related_contact_id)}
-                      </Link>
-                      {i < relationshipGroups.friends.length - 1 && ", "}
-                    </span>
-                  ))}
-                </div>
-              )}
-
-              {relationshipGroups.professional.length > 0 && (
-                <div className="id-rel-group">
-                  <span className="id-rel-label">Professional:</span>{" "}
-                  {relationshipGroups.professional.map((rel, i) => (
-                    <span key={rel.related_contact_id}>
-                      <Link to={`/contacts/${rel.related_contact_id}`}>
-                        {getContactName(rel.related_contact_id)}
-                      </Link>
-                      <span className="id-rel-type">({getRelationshipDisplayName(rel.relationship_type)})</span>
-                      {i < relationshipGroups.professional.length - 1 && ", "}
-                    </span>
-                  ))}
-                </div>
-              )}
-
-              {relationshipGroups.other.length > 0 && (
-                <div className="id-rel-group">
-                  <span className="id-rel-label">Other:</span>{" "}
-                  {relationshipGroups.other.map((rel, i) => (
-                    <span key={rel.related_contact_id}>
-                      <Link to={`/contacts/${rel.related_contact_id}`}>
-                        {getContactName(rel.related_contact_id)}
-                      </Link>
-                      <span className="id-rel-type">({getRelationshipDisplayName(rel.relationship_type)})</span>
-                      {i < relationshipGroups.other.length - 1 && ", "}
-                    </span>
-                  ))}
-                </div>
-              )}
-
-              {contact.related_from.length > 0 && (
-                <div className="id-rel-group">
-                  <span className="id-rel-label">Known by:</span>{" "}
-                  {contact.related_from.map((rel, i) => (
-                    <span key={rel.contact_id}>
-                      <Link to={`/contacts/${rel.contact_id}`}>
-                        {getContactName(rel.contact_id)}
-                      </Link>
-                      {i < contact.related_from.length - 1 && ", "}
-                    </span>
-                  ))}
-                </div>
-              )}
-            </div>
-          </div>
-        </div>
-
-        {/* Needs/Warnings at bottom */}
-        {contact.needs.length > 0 && (
-          <div className="id-card-warnings">
-            {contact.needs.map((need) => (
-              <div key={need.id} className="id-warning">
-                <span className="warning-dot"></span>
-                Warning: {need.name}
-                {need.description && <span className="warning-desc"> - {need.description}</span>}
-              </div>
-            ))}
-          </div>
-        )}
-      </div>
-
-      {/* Management section (expandable) */}
-      <details className="id-card-manage">
-        <summary>Manage Contact</summary>
-
-        <div className="manage-section">
-          <h3>Manage Relationships</h3>
-          <div className="manage-relationships">
-            {contact.related_to.map((rel) => (
-              <div key={rel.related_contact_id} className="manage-rel-item">
-                <Link to={`/contacts/${rel.related_contact_id}`}>
-                  {getContactName(rel.related_contact_id)}
-                </Link>
-                <span className="tag">{getRelationshipDisplayName(rel.relationship_type)}</span>
-                <label className="weight-control">
-                  <span>Closeness:</span>
-                  <input
-                    type="range"
-                    min="1"
-                    max="10"
-                    value={rel.closeness_weight}
-                    onChange={(e) => handleUpdateWeight(rel.related_contact_id, Number(e.target.value))}
-                  />
-                  <span className="weight-value">{rel.closeness_weight}</span>
-                </label>
-                <button
-                  onClick={() => handleRemoveRelationship(rel.related_contact_id)}
-                  className="btn btn-small btn-danger"
-                >
-                  Remove
-                </button>
-              </div>
-            ))}
-          </div>
-
-          {allContacts.length > 0 && (
-            <div className="add-form">
-              <select
-                value={newRelContactId}
-                onChange={(e) =>
-                  setNewRelContactId(
-                    e.target.value ? Number(e.target.value) : ""
-                  )
-                }
-              >
-                <option value="">Select contact...</option>
-                {allContacts.map((c) => (
-                  <option key={c.id} value={c.id}>
-                    {c.name}
-                  </option>
-                ))}
-              </select>
-              <select
-                value={newRelType}
-                onChange={(e) => setNewRelType(e.target.value as RelationshipTypeValue | "")}
-              >
-                <option value="">Select relationship type...</option>
-                {RELATIONSHIP_TYPES.map((rt) => (
-                  <option key={rt.value} value={rt.value}>
-                    {rt.displayName}
-                  </option>
-                ))}
-              </select>
-              <button onClick={handleAddRelationship} className="btn btn-primary">
-                Add Relationship
-              </button>
-            </div>
-          )}
-        </div>
-
-        <div className="manage-section">
-          <h3>Manage Needs/Warnings</h3>
-          <ul className="manage-needs-list">
-            {contact.needs.map((need) => (
-              <li key={need.id}>
-                <strong>{need.name}</strong>
-                {need.description && <span> - {need.description}</span>}
-                <button
-                  onClick={() => handleRemoveNeed(need.id)}
-                  className="btn btn-small btn-danger"
-                >
-                  Remove
-                </button>
-              </li>
-            ))}
-          </ul>
-          {availableNeeds.length > 0 && (
-            <div className="add-form">
-              <select
-                value={newNeedId}
-                onChange={(e) =>
-                  setNewNeedId(e.target.value ? Number(e.target.value) : "")
-                }
-              >
-                <option value="">Select a need...</option>
-                {availableNeeds.map((n) => (
-                  <option key={n.id} value={n.id}>
-                    {n.name}
-                  </option>
-                ))}
-              </select>
-              <button onClick={handleAddNeed} className="btn btn-primary">
-                Add Need
-              </button>
-            </div>
-          )}
-        </div>
-      </details>
-    </div>
-  );
-}

frontend/src/components/ContactForm.tsx

@@ -1,325 +0,0 @@
-import { useEffect, useState } from "react";
-import { useNavigate, useParams } from "react-router-dom";
-import { api } from "../api/client";
-import type { ContactCreate, Need } from "../types";
-
-export function ContactForm() {
-  const { id } = useParams<{ id: string }>();
-  const navigate = useNavigate();
-  const isEdit = Boolean(id);
-
-  const [allNeeds, setAllNeeds] = useState<Need[]>([]);
-  const [loading, setLoading] = useState(isEdit);
-  const [error, setError] = useState<string | null>(null);
-  const [submitting, setSubmitting] = useState(false);
-
-  const [form, setForm] = useState<ContactCreate>({
-    name: "",
-    age: null,
-    bio: null,
-    current_job: null,
-    gender: null,
-    goals: null,
-    legal_name: null,
-    profile_pic: null,
-    safe_conversation_starters: null,
-    self_sufficiency_score: null,
-    social_structure_style: null,
-    ssn: null,
-    suffix: null,
-    timezone: null,
-    topics_to_avoid: null,
-    need_ids: [],
-  });
-
-  useEffect(() => {
-    const loadData = async () => {
-      try {
-        const needs = await api.needs.list();
-        setAllNeeds(needs);
-
-        if (id) {
-          const contact = await api.contacts.get(Number(id));
-          setForm({
-            name: contact.name,
-            age: contact.age,
-            bio: contact.bio,
-            current_job: contact.current_job,
-            gender: contact.gender,
-            goals: contact.goals,
-            legal_name: contact.legal_name,
-            profile_pic: contact.profile_pic,
-            safe_conversation_starters: contact.safe_conversation_starters,
-            self_sufficiency_score: contact.self_sufficiency_score,
-            social_structure_style: contact.social_structure_style,
-            ssn: contact.ssn,
-            suffix: contact.suffix,
-            timezone: contact.timezone,
-            topics_to_avoid: contact.topics_to_avoid,
-            need_ids: contact.needs.map((n) => n.id),
-          });
-        }
-      } catch (err) {
-        setError(err instanceof Error ? err.message : "Failed to load data");
-      } finally {
-        setLoading(false);
-      }
-    };
-    loadData();
-  }, [id]);
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setSubmitting(true);
-    setError(null);
-
-    try {
-      if (isEdit) {
-        await api.contacts.update(Number(id), form);
-        navigate(`/contacts/${id}`);
-      } else {
-        const created = await api.contacts.create(form);
-        navigate(`/contacts/${created.id}`);
-      }
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Save failed");
-      setSubmitting(false);
-    }
-  };
-
-  const updateField = <K extends keyof ContactCreate>(
-    field: K,
-    value: ContactCreate[K]
-  ) => {
-    setForm((prev) => ({ ...prev, [field]: value }));
-  };
-
-  const toggleNeed = (needId: number) => {
-    setForm((prev) => ({
-      ...prev,
-      need_ids: prev.need_ids?.includes(needId)
-        ? prev.need_ids.filter((id) => id !== needId)
-        : [...(prev.need_ids || []), needId],
-    }));
-  };
-
-  if (loading) return <div>Loading...</div>;
-
-  return (
-    <div className="contact-form">
-      <h1>{isEdit ? "Edit Contact" : "New Contact"}</h1>
-
-      {error && <div className="error">{error}</div>}
-
-      <form onSubmit={handleSubmit}>
-        <div className="form-group">
-          <label htmlFor="name">Name *</label>
-          <input
-            id="name"
-            type="text"
-            value={form.name}
-            onChange={(e) => updateField("name", e.target.value)}
-            required
-          />
-        </div>
-
-        <div className="form-row">
-          <div className="form-group">
-            <label htmlFor="legal_name">Legal Name</label>
-            <input
-              id="legal_name"
-              type="text"
-              value={form.legal_name || ""}
-              onChange={(e) =>
-                updateField("legal_name", e.target.value || null)
-              }
-            />
-          </div>
-          <div className="form-group">
-            <label htmlFor="suffix">Suffix</label>
-            <input
-              id="suffix"
-              type="text"
-              value={form.suffix || ""}
-              onChange={(e) => updateField("suffix", e.target.value || null)}
-            />
-          </div>
-        </div>
-
-        <div className="form-row">
-          <div className="form-group">
-            <label htmlFor="age">Age</label>
-            <input
-              id="age"
-              type="number"
-              value={form.age ?? ""}
-              onChange={(e) =>
-                updateField("age", e.target.value ? Number(e.target.value) : null)
-              }
-            />
-          </div>
-          <div className="form-group">
-            <label htmlFor="gender">Gender</label>
-            <input
-              id="gender"
-              type="text"
-              value={form.gender || ""}
-              onChange={(e) => updateField("gender", e.target.value || null)}
-            />
-          </div>
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="current_job">Current Job</label>
-          <input
-            id="current_job"
-            type="text"
-            value={form.current_job || ""}
-            onChange={(e) =>
-              updateField("current_job", e.target.value || null)
-            }
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="timezone">Timezone</label>
-          <input
-            id="timezone"
-            type="text"
-            value={form.timezone || ""}
-            onChange={(e) => updateField("timezone", e.target.value || null)}
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="profile_pic">Profile Picture URL</label>
-          <input
-            id="profile_pic"
-            type="url"
-            placeholder="https://example.com/photo.jpg"
-            value={form.profile_pic || ""}
-            onChange={(e) => updateField("profile_pic", e.target.value || null)}
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="bio">Bio</label>
-          <textarea
-            id="bio"
-            value={form.bio || ""}
-            onChange={(e) => updateField("bio", e.target.value || null)}
-            rows={3}
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="goals">Goals</label>
-          <textarea
-            id="goals"
-            value={form.goals || ""}
-            onChange={(e) => updateField("goals", e.target.value || null)}
-            rows={3}
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="social_structure_style">Social Structure Style</label>
-          <input
-            id="social_structure_style"
-            type="text"
-            value={form.social_structure_style || ""}
-            onChange={(e) =>
-              updateField("social_structure_style", e.target.value || null)
-            }
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="self_sufficiency_score">
-            Self-Sufficiency Score (1-10)
-          </label>
-          <input
-            id="self_sufficiency_score"
-            type="number"
-            min="1"
-            max="10"
-            value={form.self_sufficiency_score ?? ""}
-            onChange={(e) =>
-              updateField(
-                "self_sufficiency_score",
-                e.target.value ? Number(e.target.value) : null
-              )
-            }
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="safe_conversation_starters">
-            Safe Conversation Starters
-          </label>
-          <textarea
-            id="safe_conversation_starters"
-            value={form.safe_conversation_starters || ""}
-            onChange={(e) =>
-              updateField("safe_conversation_starters", e.target.value || null)
-            }
-            rows={2}
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="topics_to_avoid">Topics to Avoid</label>
-          <textarea
-            id="topics_to_avoid"
-            value={form.topics_to_avoid || ""}
-            onChange={(e) =>
-              updateField("topics_to_avoid", e.target.value || null)
-            }
-            rows={2}
-          />
-        </div>
-
-        <div className="form-group">
-          <label htmlFor="ssn">SSN</label>
-          <input
-            id="ssn"
-            type="text"
-            value={form.ssn || ""}
-            onChange={(e) => updateField("ssn", e.target.value || null)}
-          />
-        </div>
-
-        {allNeeds.length > 0 && (
-          <div className="form-group">
-            <label>Needs/Accommodations</label>
-            <div className="checkbox-group">
-              {allNeeds.map((need) => (
-                <label key={need.id} className="checkbox-label">
-                  <input
-                    type="checkbox"
-                    checked={form.need_ids?.includes(need.id) || false}
-                    onChange={() => toggleNeed(need.id)}
-                  />
-                  {need.name}
-                </label>
-              ))}
-            </div>
-          </div>
-        )}
-
-        <div className="form-actions">
-          <button type="submit" className="btn btn-primary" disabled={submitting}>
-            {submitting ? "Saving..." : "Save"}
-          </button>
-          <button
-            type="button"
-            className="btn"
-            onClick={() => navigate(isEdit ? `/contacts/${id}` : "/contacts")}
-          >
-            Cancel
-          </button>
-        </div>
-      </form>
-    </div>
-  );
-}

frontend/src/components/ContactList.tsx

@@ -1,79 +0,0 @@
-import { useEffect, useState } from "react";
-import { Link } from "react-router-dom";
-import { api } from "../api/client";
-import type { ContactListItem } from "../types";
-
-export function ContactList() {
-  const [contacts, setContacts] = useState<ContactListItem[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    api.contacts
-      .list()
-      .then(setContacts)
-      .catch((err) => setError(err.message))
-      .finally(() => setLoading(false));
-  }, []);
-
-  const handleDelete = async (id: number) => {
-    if (!confirm("Delete this contact?")) return;
-    try {
-      await api.contacts.delete(id);
-      setContacts((prev) => prev.filter((c) => c.id !== id));
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Delete failed");
-    }
-  };
-
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div className="error">Error: {error}</div>;
-
-  return (
-    <div className="contact-list">
-      <div className="header">
-        <h1>Contacts</h1>
-        <Link to="/contacts/new" className="btn btn-primary">
-          Add Contact
-        </Link>
-      </div>
-
-      {contacts.length === 0 ? (
-        <p>No contacts yet.</p>
-      ) : (
-        <table>
-          <thead>
-            <tr>
-              <th>Name</th>
-              <th>Job</th>
-              <th>Timezone</th>
-              <th>Actions</th>
-            </tr>
-          </thead>
-          <tbody>
-            {contacts.map((contact) => (
-              <tr key={contact.id}>
-                <td>
-                  <Link to={`/contacts/${contact.id}`}>{contact.name}</Link>
-                </td>
-                <td>{contact.current_job || "-"}</td>
-                <td>{contact.timezone || "-"}</td>
-                <td>
-                  <Link to={`/contacts/${contact.id}/edit`} className="btn">
-                    Edit
-                  </Link>
-                  <button
-                    onClick={() => handleDelete(contact.id)}
-                    className="btn btn-danger"
-                  >
-                    Delete
-                  </button>
-                </td>
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      )}
-    </div>
-  );
-}

frontend/src/components/NeedList.tsx

@@ -1,117 +0,0 @@
-import { useEffect, useState } from "react";
-import { api } from "../api/client";
-import type { Need, NeedCreate } from "../types";
-
-export function NeedList() {
-  const [needs, setNeeds] = useState<Need[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [showForm, setShowForm] = useState(false);
-  const [form, setForm] = useState<NeedCreate>({ name: "", description: null });
-  const [submitting, setSubmitting] = useState(false);
-
-  useEffect(() => {
-    api.needs
-      .list()
-      .then(setNeeds)
-      .catch((err) => setError(err.message))
-      .finally(() => setLoading(false));
-  }, []);
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    if (!form.name.trim()) return;
-
-    setSubmitting(true);
-    try {
-      const created = await api.needs.create(form);
-      setNeeds((prev) => [...prev, created]);
-      setForm({ name: "", description: null });
-      setShowForm(false);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Create failed");
-    } finally {
-      setSubmitting(false);
-    }
-  };
-
-  const handleDelete = async (id: number) => {
-    if (!confirm("Delete this need?")) return;
-    try {
-      await api.needs.delete(id);
-      setNeeds((prev) => prev.filter((n) => n.id !== id));
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Delete failed");
-    }
-  };
-
-  if (loading) return <div>Loading...</div>;
-
-  return (
-    <div className="need-list">
-      <div className="header">
-        <h1>Needs / Accommodations</h1>
-        <button
-          onClick={() => setShowForm(!showForm)}
-          className="btn btn-primary"
-        >
-          {showForm ? "Cancel" : "Add Need"}
-        </button>
-      </div>
-
-      {error && <div className="error">{error}</div>}
-
-      {showForm && (
-        <form onSubmit={handleSubmit} className="need-form">
-          <div className="form-group">
-            <label htmlFor="name">Name *</label>
-            <input
-              id="name"
-              type="text"
-              value={form.name}
-              onChange={(e) => setForm({ ...form, name: e.target.value })}
-              placeholder="e.g., Light Sensitive, ADHD"
-              required
-            />
-          </div>
-          <div className="form-group">
-            <label htmlFor="description">Description</label>
-            <textarea
-              id="description"
-              value={form.description || ""}
-              onChange={(e) =>
-                setForm({ ...form, description: e.target.value || null })
-              }
-              placeholder="Optional description..."
-              rows={2}
-            />
-          </div>
-          <button type="submit" className="btn btn-primary" disabled={submitting}>
-            {submitting ? "Creating..." : "Create"}
-          </button>
-        </form>
-      )}
-
-      {needs.length === 0 ? (
-        <p>No needs defined yet.</p>
-      ) : (
-        <ul className="need-items">
-          {needs.map((need) => (
-            <li key={need.id}>
-              <div className="need-info">
-                <strong>{need.name}</strong>
-                {need.description && <p>{need.description}</p>}
-              </div>
-              <button
-                onClick={() => handleDelete(need.id)}
-                className="btn btn-danger"
-              >
-                Delete
-              </button>
-            </li>
-          ))}
-        </ul>
-      )}
-    </div>
-  );
-}

frontend/src/components/RelationshipGraph.tsx

@@ -1,330 +0,0 @@
-import { useEffect, useRef, useState } from "react";
-import { api } from "../api/client";
-import type { GraphData, GraphEdge, GraphNode } from "../types";
-import { RELATIONSHIP_TYPES } from "../types";
-
-interface SimNode extends GraphNode {
-  x: number;
-  y: number;
-  vx: number;
-  vy: number;
-}
-
-interface SimEdge extends GraphEdge {
-  sourceNode: SimNode;
-  targetNode: SimNode;
-}
-
-export function RelationshipGraph() {
-  const canvasRef = useRef<HTMLCanvasElement>(null);
-  const [data, setData] = useState<GraphData | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [selectedNode, setSelectedNode] = useState<SimNode | null>(null);
-  const nodesRef = useRef<SimNode[]>([]);
-  const edgesRef = useRef<SimEdge[]>([]);
-  const dragNodeRef = useRef<SimNode | null>(null);
-  const animationRef = useRef<number>(0);
-
-  useEffect(() => {
-    api.graph.get()
-      .then(setData)
-      .catch((err) => setError(err.message))
-      .finally(() => setLoading(false));
-  }, []);
-
-  useEffect(() => {
-    if (!data || !canvasRef.current) return;
-
-    const canvas = canvasRef.current;
-    const maybeCtx = canvas.getContext("2d");
-    if (!maybeCtx) return;
-    const ctx: CanvasRenderingContext2D = maybeCtx;
-
-    const width = canvas.width;
-    const height = canvas.height;
-    const centerX = width / 2;
-    const centerY = height / 2;
-
-    // Initialize nodes with random positions
-    const nodes: SimNode[] = data.nodes.map((node) => ({
-      ...node,
-      x: centerX + (Math.random() - 0.5) * 300,
-      y: centerY + (Math.random() - 0.5) * 300,
-      vx: 0,
-      vy: 0,
-    }));
-    nodesRef.current = nodes;
-
-    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
-
-    // Create edges with node references
-    const edges: SimEdge[] = data.edges
-      .map((edge) => {
-        const sourceNode = nodeMap.get(edge.source);
-        const targetNode = nodeMap.get(edge.target);
-        if (!sourceNode || !targetNode) return null;
-        return { ...edge, sourceNode, targetNode };
-      })
-      .filter((e): e is SimEdge => e !== null);
-    edgesRef.current = edges;
-
-    // Force simulation parameters
-    const repulsion = 5000;
-    const springStrength = 0.05;
-    const baseSpringLength = 150;
-    const damping = 0.9;
-    const centerPull = 0.01;
-
-    function simulate() {
-      const nodes = nodesRef.current;
-      const edges = edgesRef.current;
-
-      // Reset forces
-      for (const node of nodes) {
-        node.vx = 0;
-        node.vy = 0;
-      }
-
-      // Repulsion between all nodes
-      for (let i = 0; i < nodes.length; i++) {
-        for (let j = i + 1; j < nodes.length; j++) {
-          const dx = nodes[j].x - nodes[i].x;
-          const dy = nodes[j].y - nodes[i].y;
-          const dist = Math.sqrt(dx * dx + dy * dy) || 1;
-          const force = repulsion / (dist * dist);
-          const fx = (dx / dist) * force;
-          const fy = (dy / dist) * force;
-          nodes[i].vx -= fx;
-          nodes[i].vy -= fy;
-          nodes[j].vx += fx;
-          nodes[j].vy += fy;
-        }
-      }
-
-      // Spring forces for edges - closer relationships = shorter springs
-      // Weight is 1-10, normalize to 0-1 for calculations
-      for (const edge of edges) {
-        const dx = edge.targetNode.x - edge.sourceNode.x;
-        const dy = edge.targetNode.y - edge.sourceNode.y;
-        const dist = Math.sqrt(dx * dx + dy * dy) || 1;
-        // Higher weight (1-10) = shorter ideal length
-        // Normalize: weight 10 -> 0.5x length, weight 1 -> 1.4x length
-        const normalizedWeight = edge.closeness_weight / 10;
-        const idealLength = baseSpringLength * (1.5 - normalizedWeight);
-        const displacement = dist - idealLength;
-        const force = springStrength * displacement;
-        const fx = (dx / dist) * force;
-        const fy = (dy / dist) * force;
-        edge.sourceNode.vx += fx;
-        edge.sourceNode.vy += fy;
-        edge.targetNode.vx -= fx;
-        edge.targetNode.vy -= fy;
-      }
-
-      // Pull toward center
-      for (const node of nodes) {
-        node.vx += (centerX - node.x) * centerPull;
-        node.vy += (centerY - node.y) * centerPull;
-      }
-
-      // Apply velocities with damping (skip dragged node)
-      for (const node of nodes) {
-        if (node === dragNodeRef.current) continue;
-        node.x += node.vx * damping;
-        node.y += node.vy * damping;
-        // Keep within bounds
-        node.x = Math.max(30, Math.min(width - 30, node.x));
-        node.y = Math.max(30, Math.min(height - 30, node.y));
-      }
-    }
-
-    function getEdgeColor(weight: number): string {
-      // Interpolate from light gray (distant) to dark blue (close)
-      // weight is 1-10, normalize to 0-1
-      const normalized = weight / 10;
-      const hue = 220;
-      const saturation = 70;
-      const lightness = 80 - normalized * 40;
-      return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
-    }
-
-    function draw(context: CanvasRenderingContext2D) {
-      const nodes = nodesRef.current;
-      const edges = edgesRef.current;
-
-      context.clearRect(0, 0, width, height);
-
-      // Draw edges
-      for (const edge of edges) {
-        // Weight is 1-10, scale line width accordingly
-        const lineWidth = 1 + (edge.closeness_weight / 10) * 3;
-        context.strokeStyle = getEdgeColor(edge.closeness_weight);
-        context.lineWidth = lineWidth;
-        context.beginPath();
-        context.moveTo(edge.sourceNode.x, edge.sourceNode.y);
-        context.lineTo(edge.targetNode.x, edge.targetNode.y);
-        context.stroke();
-
-        // Draw relationship type label at midpoint
-        const midX = (edge.sourceNode.x + edge.targetNode.x) / 2;
-        const midY = (edge.sourceNode.y + edge.targetNode.y) / 2;
-        context.fillStyle = "#666";
-        context.font = "10px sans-serif";
-        context.textAlign = "center";
-        const typeInfo = RELATIONSHIP_TYPES.find(t => t.value === edge.relationship_type);
-        const label = typeInfo?.displayName || edge.relationship_type;
-        context.fillText(label, midX, midY - 5);
-      }
-
-      // Draw nodes
-      for (const node of nodes) {
-        const isSelected = node === selectedNode;
-        const radius = isSelected ? 25 : 20;
-
-        // Node circle
-        context.beginPath();
-        context.arc(node.x, node.y, radius, 0, Math.PI * 2);
-        context.fillStyle = isSelected ? "#0066cc" : "#fff";
-        context.fill();
-        context.strokeStyle = "#0066cc";
-        context.lineWidth = 2;
-        context.stroke();
-
-        // Node label
-        context.fillStyle = isSelected ? "#fff" : "#333";
-        context.font = "12px sans-serif";
-        context.textAlign = "center";
-        context.textBaseline = "middle";
-        const name = node.name.length > 10 ? node.name.slice(0, 9) + "…" : node.name;
-        context.fillText(name, node.x, node.y);
-      }
-    }
-
-    function animate() {
-      simulate();
-      draw(ctx);
-      animationRef.current = requestAnimationFrame(animate);
-    }
-
-    animate();
-
-    return () => {
-      cancelAnimationFrame(animationRef.current);
-    };
-  }, [data, selectedNode]);
-
-  // Mouse interaction handlers
-  useEffect(() => {
-    const canvas = canvasRef.current;
-    if (!canvas) return;
-
-    function getNodeAtPosition(x: number, y: number): SimNode | null {
-      for (const node of nodesRef.current) {
-        const dx = x - node.x;
-        const dy = y - node.y;
-        if (dx * dx + dy * dy < 400) {
-          return node;
-        }
-      }
-      return null;
-    }
-
-    function handleMouseDown(e: MouseEvent) {
-      const rect = canvas!.getBoundingClientRect();
-      const x = e.clientX - rect.left;
-      const y = e.clientY - rect.top;
-      const node = getNodeAtPosition(x, y);
-      if (node) {
-        dragNodeRef.current = node;
-        setSelectedNode(node);
-      }
-    }
-
-    function handleMouseMove(e: MouseEvent) {
-      if (!dragNodeRef.current) return;
-      const rect = canvas!.getBoundingClientRect();
-      dragNodeRef.current.x = e.clientX - rect.left;
-      dragNodeRef.current.y = e.clientY - rect.top;
-    }
-
-    function handleMouseUp() {
-      dragNodeRef.current = null;
-    }
-
-    canvas.addEventListener("mousedown", handleMouseDown);
-    canvas.addEventListener("mousemove", handleMouseMove);
-    canvas.addEventListener("mouseup", handleMouseUp);
-    canvas.addEventListener("mouseleave", handleMouseUp);
-
-    return () => {
-      canvas.removeEventListener("mousedown", handleMouseDown);
-      canvas.removeEventListener("mousemove", handleMouseMove);
-      canvas.removeEventListener("mouseup", handleMouseUp);
-      canvas.removeEventListener("mouseleave", handleMouseUp);
-    };
-  }, []);
-
-  if (loading) return <p>Loading graph...</p>;
-  if (error) return <div className="error">{error}</div>;
-  if (!data) return <p>No data available</p>;
-
-  return (
-    <div className="graph-container">
-      <div className="header">
-        <h1>Relationship Graph</h1>
-      </div>
-      <p className="graph-hint">
-        Drag nodes to reposition. Closer relationships have shorter, darker edges.
-      </p>
-      <canvas
-        ref={canvasRef}
-        width={900}
-        height={600}
-        style={{
-          border: "1px solid var(--color-border)",
-          borderRadius: "8px",
-          background: "var(--color-bg)",
-          cursor: "grab",
-        }}
-      />
-      {selectedNode && (
-        <div className="selected-info">
-          <h3>{selectedNode.name}</h3>
-          {selectedNode.current_job && <p>Job: {selectedNode.current_job}</p>}
-          <a href={`/contacts/${selectedNode.id}`}>View details</a>
-        </div>
-      )}
-      <div className="legend">
-        <h4>Relationship Closeness (1-10)</h4>
-        <div className="legend-items">
-          <div className="legend-item">
-            <span className="legend-line" style={{ background: getEdgeColorCSS(10), height: "4px" }}></span>
-            <span>10 - Very Close (Spouse, Partner)</span>
-          </div>
-          <div className="legend-item">
-            <span className="legend-line" style={{ background: getEdgeColorCSS(7), height: "3px" }}></span>
-            <span>7 - Close (Family, Best Friend)</span>
-          </div>
-          <div className="legend-item">
-            <span className="legend-line" style={{ background: getEdgeColorCSS(4), height: "2px" }}></span>
-            <span>4 - Moderate (Friend, Colleague)</span>
-          </div>
-          <div className="legend-item">
-            <span className="legend-line" style={{ background: getEdgeColorCSS(2), height: "1px" }}></span>
-            <span>2 - Distant (Acquaintance)</span>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-function getEdgeColorCSS(weight: number): string {
-  // weight is 1-10, normalize to 0-1
-  const normalized = weight / 10;
-  const hue = 220;
-  const saturation = 70;
-  const lightness = 80 - normalized * 40;
-  return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
-}

frontend/src/index.css

@@ -1,62 +0,0 @@
-:root {
-  /* Light theme (default) */
-  --color-bg: #f5f5f5;
-  --color-bg-card: #ffffff;
-  --color-bg-hover: #f0f0f0;
-  --color-bg-muted: #f9f9f9;
-  --color-bg-error: #ffe0e0;
-
-  --color-text: #333333;
-  --color-text-muted: #666666;
-  --color-text-error: #cc0000;
-
-  --color-border: #dddddd;
-  --color-border-light: #eeeeee;
-  --color-border-lighter: #f0f0f0;
-
-  --color-primary: #0066cc;
-  --color-primary-hover: #0055aa;
-
-  --color-danger: #cc3333;
-  --color-danger-hover: #aa2222;
-
-  --color-tag-bg: #e0e0e0;
-
-  --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
-
-  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-  line-height: 1.5;
-  font-weight: 400;
-  color: var(--color-text);
-  background-color: var(--color-bg);
-  font-synthesis: none;
-  text-rendering: optimizeLegibility;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-
-[data-theme="dark"] {
-  --color-bg: #1a1a1a;
-  --color-bg-card: #2d2d2d;
-  --color-bg-hover: #3d3d3d;
-  --color-bg-muted: #252525;
-  --color-bg-error: #4a2020;
-
-  --color-text: #e0e0e0;
-  --color-text-muted: #a0a0a0;
-  --color-text-error: #ff6b6b;
-
-  --color-border: #404040;
-  --color-border-light: #353535;
-  --color-border-lighter: #303030;
-
-  --color-primary: #4da6ff;
-  --color-primary-hover: #7dbfff;
-
-  --color-danger: #ff6b6b;
-  --color-danger-hover: #ff8a8a;
-
-  --color-tag-bg: #404040;
-
-  --shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
-}

frontend/src/main.tsx

@@ -1,13 +0,0 @@
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import { BrowserRouter } from "react-router-dom";
-import App from "./App.tsx";
-import "./index.css";
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <BrowserRouter>
-      <App />
-    </BrowserRouter>
-  </StrictMode>
-);

frontend/src/types/index.ts

@@ -1,155 +0,0 @@
-export interface Need {
-  id: number;
-  name: string;
-  description: string | null;
-}
-
-export interface NeedCreate {
-  name: string;
-  description?: string | null;
-}
-
-export const RELATIONSHIP_TYPES = [
-  { value: 'spouse', displayName: 'Spouse', defaultWeight: 10 },
-  { value: 'partner', displayName: 'Partner', defaultWeight: 10 },
-  { value: 'parent', displayName: 'Parent', defaultWeight: 9 },
-  { value: 'child', displayName: 'Child', defaultWeight: 9 },
-  { value: 'sibling', displayName: 'Sibling', defaultWeight: 9 },
-  { value: 'best_friend', displayName: 'Best Friend', defaultWeight: 8 },
-  { value: 'grandparent', displayName: 'Grandparent', defaultWeight: 7 },
-  { value: 'grandchild', displayName: 'Grandchild', defaultWeight: 7 },
-  { value: 'aunt_uncle', displayName: 'Aunt/Uncle', defaultWeight: 7 },
-  { value: 'niece_nephew', displayName: 'Niece/Nephew', defaultWeight: 7 },
-  { value: 'cousin', displayName: 'Cousin', defaultWeight: 7 },
-  { value: 'in_law', displayName: 'In-Law', defaultWeight: 7 },
-  { value: 'close_friend', displayName: 'Close Friend', defaultWeight: 6 },
-  { value: 'friend', displayName: 'Friend', defaultWeight: 6 },
-  { value: 'mentor', displayName: 'Mentor', defaultWeight: 5 },
-  { value: 'mentee', displayName: 'Mentee', defaultWeight: 5 },
-  { value: 'business_partner', displayName: 'Business Partner', defaultWeight: 5 },
-  { value: 'colleague', displayName: 'Colleague', defaultWeight: 4 },
-  { value: 'manager', displayName: 'Manager', defaultWeight: 4 },
-  { value: 'direct_report', displayName: 'Direct Report', defaultWeight: 4 },
-  { value: 'client', displayName: 'Client', defaultWeight: 4 },
-  { value: 'acquaintance', displayName: 'Acquaintance', defaultWeight: 3 },
-  { value: 'neighbor', displayName: 'Neighbor', defaultWeight: 3 },
-  { value: 'ex', displayName: 'Ex', defaultWeight: 2 },
-  { value: 'other', displayName: 'Other', defaultWeight: 2 },
-] as const;
-
-export type RelationshipTypeValue = typeof RELATIONSHIP_TYPES[number]['value'];
-
-export interface ContactRelationship {
-  contact_id: number;
-  related_contact_id: number;
-  relationship_type: string;
-  closeness_weight: number;
-}
-
-export interface ContactRelationshipCreate {
-  related_contact_id: number;
-  relationship_type: RelationshipTypeValue;
-  closeness_weight?: number;
-}
-
-export interface ContactRelationshipUpdate {
-  relationship_type?: RelationshipTypeValue;
-  closeness_weight?: number;
-}
-
-export interface GraphNode {
-  id: number;
-  name: string;
-  current_job: string | null;
-}
-
-export interface GraphEdge {
-  source: number;
-  target: number;
-  relationship_type: string;
-  closeness_weight: number;
-}
-
-export interface GraphData {
-  nodes: GraphNode[];
-  edges: GraphEdge[];
-}
-
-export interface Contact {
-  id: number;
-  name: string;
-  age: number | null;
-  bio: string | null;
-  current_job: string | null;
-  gender: string | null;
-  goals: string | null;
-  legal_name: string | null;
-  profile_pic: string | null;
-  safe_conversation_starters: string | null;
-  self_sufficiency_score: number | null;
-  social_structure_style: string | null;
-  ssn: string | null;
-  suffix: string | null;
-  timezone: string | null;
-  topics_to_avoid: string | null;
-  needs: Need[];
-  related_to: ContactRelationship[];
-  related_from: ContactRelationship[];
-}
-
-export interface ContactListItem {
-  id: number;
-  name: string;
-  age: number | null;
-  bio: string | null;
-  current_job: string | null;
-  gender: string | null;
-  goals: string | null;
-  legal_name: string | null;
-  profile_pic: string | null;
-  safe_conversation_starters: string | null;
-  self_sufficiency_score: number | null;
-  social_structure_style: string | null;
-  ssn: string | null;
-  suffix: string | null;
-  timezone: string | null;
-  topics_to_avoid: string | null;
-}
-
-export interface ContactCreate {
-  name: string;
-  age?: number | null;
-  bio?: string | null;
-  current_job?: string | null;
-  gender?: string | null;
-  goals?: string | null;
-  legal_name?: string | null;
-  profile_pic?: string | null;
-  safe_conversation_starters?: string | null;
-  self_sufficiency_score?: number | null;
-  social_structure_style?: string | null;
-  ssn?: string | null;
-  suffix?: string | null;
-  timezone?: string | null;
-  topics_to_avoid?: string | null;
-  need_ids?: number[];
-}
-
-export interface ContactUpdate {
-  name?: string | null;
-  age?: number | null;
-  bio?: string | null;
-  current_job?: string | null;
-  gender?: string | null;
-  goals?: string | null;
-  legal_name?: string | null;
-  profile_pic?: string | null;
-  safe_conversation_starters?: string | null;
-  self_sufficiency_score?: number | null;
-  social_structure_style?: string | null;
-  ssn?: string | null;
-  suffix?: string | null;
-  timezone?: string | null;
-  topics_to_avoid?: string | null;
-  need_ids?: number[] | null;
-}

frontend/tsconfig.app.json

@@ -1,28 +0,0 @@
-{
-  "compilerOptions": {
-    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
-    "target": "ES2022",
-    "useDefineForClassFields": true,
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "types": ["vite/client"],
-    "skipLibCheck": true,
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "moduleDetection": "force",
-    "noEmit": true,
-    "jsx": "react-jsx",
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "erasableSyntaxOnly": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true
-  },
-  "include": ["src"]
-}

frontend/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "files": [],
-  "references": [
-    { "path": "./tsconfig.app.json" },
-    { "path": "./tsconfig.node.json" }
-  ]
-}

frontend/tsconfig.node.json

@@ -1,26 +0,0 @@
-{
-  "compilerOptions": {
-    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
-    "target": "ES2023",
-    "lib": ["ES2023"],
-    "module": "ESNext",
-    "types": ["node"],
-    "skipLibCheck": true,
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "moduleDetection": "force",
-    "noEmit": true,
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "erasableSyntaxOnly": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true
-  },
-  "include": ["vite.config.ts"]
-}

frontend/vite.config.ts

@@ -1,11 +0,0 @@
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-
-export default defineConfig({
-  plugins: [react()],
-  server: {
-    proxy: {
-      "/api": "http://localhost:8000",
-    },
-  },
-});

overlays/default.nix

@@ -25,6 +25,7 @@
         fastapi-cli
         httpx
         mypy
+        orjson
         polars
         psycopg
         pydantic
@@ -33,15 +34,17 @@
         pytest-cov
         pytest-mock
         pytest-xdist
-        requests
+        python-multipart
         ruff
         scalene
         sqlalchemy
         sqlalchemy
+        tenacity
         textual
+        tiktoken
         tinytuya
         typer
-        types-requests
+        websockets
       ]
     );
   };

pyproject.toml

@@ -7,7 +7,26 @@ requires-python = "~=3.13.0"
 readme = "README.md"
 license = "MIT"
 # these dependencies are a best effort and aren't guaranteed to work
-dependencies = ["apprise", "apscheduler", "httpx", "polars", "pydantic", "pyyaml", "requests", "typer"]
+# for up-to-date dependencies, see overlays/default.nix
+dependencies = [
+    "alembic",
+    "apprise",
+    "apscheduler",
+    "httpx",
+    "python-multipart",
+    "polars",
+    "psycopg[binary]",
+    "pydantic",
+    "pyyaml",
+    "sqlalchemy",
+    "typer",
+    "websockets",
+]
+
+[project.scripts]
+database = "python.database_cli:app"
+van-inventory = "python.van_inventory.main:serve"
+whisper-transcribe = "python.tools.whisper.transcribe:main"
 
 [dependency-groups]
 dev = [
@@ -18,7 +37,6 @@ dev = [
     "pytest-xdist",
     "pytest",
     "ruff",
-    "types-requests",
 ]
 
 [tool.ruff]
@@ -33,11 +51,15 @@ lint.ignore = [
     "COM812", # (TEMP) conflicts when used with the formatter
     "ISC001", # (TEMP) conflicts when used with the formatter
     "S603",   # (PERM) This is known to cause a false positive
+    "S607",   # (PERM) This is becoming a consistent annoyance
 ]
 
 [tool.ruff.lint.per-file-ignores]
 
 "tests/**" = [
+    "ANN",     # (perm) type annotations not needed in tests
+    "D",       # (perm) docstrings not needed in tests
+    "PLR2004", # (perm) magic values are fine in test assertions
     "S101",    # (perm) pytest needs asserts
 ]
 "python/stuff/**" = [
@@ -58,9 +80,7 @@ lint.ignore = [
 "python/congress_tracker/**" = [
     "TC003", # (perm) this creates issues because sqlalchemy uses these at runtime
 ]
-"python/eval_warnings/**" = [
+
-    "S607", # (perm) gh and git are expected on PATH in the runner environment
-]
 "python/alembic/**" = [
     "INP001", # (perm) this creates LSP issues for alembic
 ]
@@ -87,4 +107,5 @@ exclude_lines = [
 
 [tool.pytest.ini_options]
 addopts = "-n auto -ra"
+testpaths = ["tests"]
 # --cov=system_tools --cov-report=term-missing --cov-report=xml --cov-report=html --cov-branch

python/alembic.ini

@@ -1,109 +0,0 @@
-# A generic, single database configuration.
-
-[alembic]
-# path to migration scripts
-# Use forward slashes (/) also on windows to provide an os agnostic path
-script_location = python/alembic
-
-# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
-# Uncomment the line below if you want the files to be prepended with date and time
-# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
-# for all available tokens
-file_template = %%(year)d_%%(month).2d_%%(day).2d-%%(slug)s_%%(rev)s
-
-# sys.path path, will be prepended to sys.path if present.
-# defaults to the current working directory.
-prepend_sys_path = .
-
-# timezone to use when rendering the date within the migration file
-# as well as the filename.
-# If specified, requires the python>=3.9 or backports.zoneinfo library and tzdata library.
-# Any required deps can installed by adding `alembic[tz]` to the pip requirements
-# string value is passed to ZoneInfo()
-# leave blank for localtime
-# timezone =
-
-# max length of characters to apply to the "slug" field
-# truncate_slug_length = 40
-
-# set to 'true' to run the environment during
-# the 'revision' command, regardless of autogenerate
-# revision_environment = false
-
-# set to 'true' to allow .pyc and .pyo files without
-# a source .py file to be detected as revisions in the
-# versions/ directory
-# sourceless = false
-
-# version location specification; This defaults
-# to alembic/versions.  When using multiple version
-# directories, initial revisions must be specified with --version-path.
-# The path separator used here should be the separator specified by "version_path_separator" below.
-# version_locations = %(here)s/bar:%(here)s/bat:alembic/versions
-
-# version path separator; As mentioned above, this is the character used to split
-# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
-# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
-# Valid values for version_path_separator are:
-#
-# version_path_separator = :
-# version_path_separator = ;
-# version_path_separator = space
-# version_path_separator = newline
-#
-# Use os.pathsep. Default configuration used for new projects.
-version_path_separator = os
-
-# set to 'true' to search source files recursively
-# in each "version_locations" directory
-# new in Alembic version 1.10
-# recursive_version_locations = false
-
-# the output encoding used when revision files
-# are written from script.py.mako
-# output_encoding = utf-8
-
-sqlalchemy.url = driver://user:pass@localhost/dbname
-
-revision_environment = true
-
-[post_write_hooks]
-
-hooks = dynamic_schema,ruff
-dynamic_schema.type = dynamic_schema
-
-ruff.type = ruff
-
-[loggers]
-keys = root,sqlalchemy,alembic
-
-[handlers]
-keys = console
-
-[formatters]
-keys = generic
-
-[logger_root]
-level = WARNING
-handlers = console
-qualname =
-
-[logger_sqlalchemy]
-level = WARNING
-handlers =
-qualname = sqlalchemy.engine
-
-[logger_alembic]
-level = INFO
-handlers =
-qualname = alembic
-
-[handler_console]
-class = StreamHandler
-args = (sys.stderr,)
-level = NOTSET
-formatter = generic
-
-[formatter_generic]
-format = %(levelname)-5.5s [%(name)s] %(message)s
-datefmt = %H:%M:%S

python/alembic/env.py

@@ -9,20 +9,24 @@ from typing import TYPE_CHECKING, Any, Literal
 
 from alembic import context
 from alembic.script import write_hooks
+from sqlalchemy.schema import CreateSchema
 
 from python.common import bash_wrapper
-from python.orm import RichieBase
+from python.orm.common import get_postgres_engine
-from python.orm.base import get_postgres_engine
 
 if TYPE_CHECKING:
     from collections.abc import MutableMapping
 
-# this is the Alembic Config object, which provides
+    from sqlalchemy.orm import DeclarativeBase
-# access to the values within the .ini file in use.
+
 config = context.config
 
+base_class: type[DeclarativeBase] = config.attributes.get("base")
+if base_class is None:
+    error = "No base class provided. Use the database CLI to run alembic commands."
+    raise RuntimeError(error)
 
-target_metadata = RichieBase.metadata
+target_metadata = base_class.metadata
 logging.basicConfig(
     level="DEBUG",
     datefmt="%Y-%m-%dT%H:%M:%S%z",
@@ -35,11 +39,24 @@ logging.basicConfig(
 def dynamic_schema(filename: str, _options: dict[Any, Any]) -> None:
     """Dynamic schema."""
     original_file = Path(filename).read_text()
-    dynamic_schema_file_part1 = original_file.replace(f"schema='{RichieBase.schema_name}'", "schema=schema")
+    schema_name = base_class.schema_name
-    dynamic_schema_file = dynamic_schema_file_part1.replace(f"'{RichieBase.schema_name}.", "f'{schema}.")
+    dynamic_schema_file_part1 = original_file.replace(f"schema='{schema_name}'", "schema=schema")
+    dynamic_schema_file = dynamic_schema_file_part1.replace(f"'{schema_name}.", "f'{schema}.")
     Path(filename).write_text(dynamic_schema_file)
 
 
+@write_hooks.register("import_postgresql")
+def import_postgresql(filename: str, _options: dict[Any, Any]) -> None:
+    """Add postgresql dialect import when postgresql types are used."""
+    content = Path(filename).read_text()
+    if "postgresql." in content and "from sqlalchemy.dialects import postgresql" not in content:
+        content = content.replace(
+            "import sqlalchemy as sa\n",
+            "import sqlalchemy as sa\nfrom sqlalchemy.dialects import postgresql\n",
+        )
+        Path(filename).write_text(content)
+
+
 @write_hooks.register("ruff")
 def ruff_check_and_format(filename: str, _options: dict[Any, Any]) -> None:
     """Docstring for ruff_check_and_format."""
@@ -52,18 +69,19 @@ def include_name(
     type_: Literal["schema", "table", "column", "index", "unique_constraint", "foreign_key_constraint"],
     _parent_names: MutableMapping[Literal["schema_name", "table_name", "schema_qualified_table_name"], str | None],
 ) -> bool:
-    """This filter table to be included in the migration.
+    """Filter tables to be included in the migration.
 
     Args:
         name (str): The name of the table.
         type_ (str): The type of the table.
-        parent_names (list[str]): The names of the parent tables.
+        _parent_names (MutableMapping): The names of the parent tables.
 
     Returns:
         bool: True if the table should be included, False otherwise.
 
     """
     if type_ == "schema":
+        # allows a database with multiple schemas to have separate alembic revisions
         return name == target_metadata.schema
     return True
 
@@ -75,19 +93,30 @@ def run_migrations_online() -> None:
     and associate a connection with the context.
 
     """
-    connectable = get_postgres_engine()
+    env_prefix = config.attributes.get("env_prefix", "POSTGRES")
+    connectable = get_postgres_engine(name=env_prefix)
 
     with connectable.connect() as connection:
+        schema = base_class.schema_name
+        if not connectable.dialect.has_schema(connection, schema):
+            answer = input(f"Schema {schema!r} does not exist. Create it? [y/N] ")
+            if answer.lower() != "y":
+                error = f"Schema {schema!r} does not exist. Exiting."
+                raise SystemExit(error)
+            connection.execute(CreateSchema(schema))
+            connection.commit()
+
         context.configure(
             connection=connection,
             target_metadata=target_metadata,
             include_schemas=True,
-            version_table_schema=RichieBase.schema_name,
+            version_table_schema=schema,
             include_name=include_name,
         )
 
         with context.begin_transaction():
             context.run_migrations()
+        connection.commit()
 
 
 run_migrations_online()

python/alembic/richie/versions/2026_02_12-add_congress_tracker_tables_3f71565e38de.py

@@ -0,0 +1,135 @@
+"""add congress tracker tables.
+
+Revision ID: 3f71565e38de
+Revises: edd7dd61a3d2
+Create Date: 2026-02-12 16:36:09.457303
+
+"""
+
+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 = "3f71565e38de"
+down_revision: str | None = "edd7dd61a3d2"
+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(
+        "bill",
+        sa.Column("congress", sa.Integer(), nullable=False),
+        sa.Column("bill_type", sa.String(), nullable=False),
+        sa.Column("number", sa.Integer(), nullable=False),
+        sa.Column("title", sa.String(), nullable=True),
+        sa.Column("title_short", sa.String(), nullable=True),
+        sa.Column("official_title", sa.String(), nullable=True),
+        sa.Column("status", sa.String(), nullable=True),
+        sa.Column("status_at", sa.Date(), nullable=True),
+        sa.Column("sponsor_bioguide_id", sa.String(), nullable=True),
+        sa.Column("subjects_top_term", 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.PrimaryKeyConstraint("id", name=op.f("pk_bill")),
+        sa.UniqueConstraint("congress", "bill_type", "number", name="uq_bill_congress_type_number"),
+        schema=schema,
+    )
+    op.create_index("ix_bill_congress", "bill", ["congress"], unique=False, schema=schema)
+    op.create_table(
+        "legislator",
+        sa.Column("bioguide_id", sa.Text(), nullable=False),
+        sa.Column("thomas_id", sa.String(), nullable=True),
+        sa.Column("lis_id", sa.String(), nullable=True),
+        sa.Column("govtrack_id", sa.Integer(), nullable=True),
+        sa.Column("opensecrets_id", sa.String(), nullable=True),
+        sa.Column("fec_ids", sa.String(), nullable=True),
+        sa.Column("first_name", sa.String(), nullable=False),
+        sa.Column("last_name", sa.String(), nullable=False),
+        sa.Column("official_full_name", sa.String(), nullable=True),
+        sa.Column("nickname", sa.String(), nullable=True),
+        sa.Column("birthday", sa.Date(), nullable=True),
+        sa.Column("gender", sa.String(), nullable=True),
+        sa.Column("current_party", sa.String(), nullable=True),
+        sa.Column("current_state", sa.String(), nullable=True),
+        sa.Column("current_district", sa.Integer(), nullable=True),
+        sa.Column("current_chamber", 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.PrimaryKeyConstraint("id", name=op.f("pk_legislator")),
+        schema=schema,
+    )
+    op.create_index(op.f("ix_legislator_bioguide_id"), "legislator", ["bioguide_id"], unique=True, schema=schema)
+    op.create_table(
+        "vote",
+        sa.Column("congress", sa.Integer(), nullable=False),
+        sa.Column("chamber", sa.String(), nullable=False),
+        sa.Column("session", sa.Integer(), nullable=False),
+        sa.Column("number", sa.Integer(), nullable=False),
+        sa.Column("vote_type", sa.String(), nullable=True),
+        sa.Column("question", sa.String(), nullable=True),
+        sa.Column("result", sa.String(), nullable=True),
+        sa.Column("result_text", sa.String(), nullable=True),
+        sa.Column("vote_date", sa.Date(), nullable=False),
+        sa.Column("yea_count", sa.Integer(), nullable=True),
+        sa.Column("nay_count", sa.Integer(), nullable=True),
+        sa.Column("not_voting_count", sa.Integer(), nullable=True),
+        sa.Column("present_count", sa.Integer(), nullable=True),
+        sa.Column("bill_id", sa.Integer(), 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(["bill_id"], [f"{schema}.bill.id"], name=op.f("fk_vote_bill_id_bill")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_vote")),
+        sa.UniqueConstraint("congress", "chamber", "session", "number", name="uq_vote_congress_chamber_session_number"),
+        schema=schema,
+    )
+    op.create_index("ix_vote_congress_chamber", "vote", ["congress", "chamber"], unique=False, schema=schema)
+    op.create_index("ix_vote_date", "vote", ["vote_date"], unique=False, schema=schema)
+    op.create_table(
+        "vote_record",
+        sa.Column("vote_id", sa.Integer(), nullable=False),
+        sa.Column("legislator_id", sa.Integer(), nullable=False),
+        sa.Column("position", sa.String(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["legislator_id"],
+            [f"{schema}.legislator.id"],
+            name=op.f("fk_vote_record_legislator_id_legislator"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["vote_id"], [f"{schema}.vote.id"], name=op.f("fk_vote_record_vote_id_vote"), ondelete="CASCADE"
+        ),
+        sa.PrimaryKeyConstraint("vote_id", "legislator_id", name=op.f("pk_vote_record")),
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("vote_record", schema=schema)
+    op.drop_index("ix_vote_date", table_name="vote", schema=schema)
+    op.drop_index("ix_vote_congress_chamber", table_name="vote", schema=schema)
+    op.drop_table("vote", schema=schema)
+    op.drop_index(op.f("ix_legislator_bioguide_id"), table_name="legislator", schema=schema)
+    op.drop_table("legislator", schema=schema)
+    op.drop_index("ix_bill_congress", table_name="bill", schema=schema)
+    op.drop_table("bill", schema=schema)
+    # ### end Alembic commands ###

python/alembic/richie/versions/2026_03_09-adding_signaldevice_for_deviceregistry__4c410c16e39c.py

@@ -0,0 +1,58 @@
+"""adding SignalDevice for DeviceRegistry for signal bot.
+
+Revision ID: 4c410c16e39c
+Revises: 3f71565e38de
+Create Date: 2026-03-09 14:51:24.228976
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+from python.orm import RichieBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "4c410c16e39c"
+down_revision: str | None = "3f71565e38de"
+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(
+        "signal_device",
+        sa.Column("phone_number", sa.String(length=50), nullable=False),
+        sa.Column("safety_number", sa.String(), nullable=False),
+        sa.Column(
+            "trust_level",
+            postgresql.ENUM("VERIFIED", "UNVERIFIED", "BLOCKED", name="trust_level", schema=schema),
+            nullable=False,
+        ),
+        sa.Column("last_seen", sa.DateTime(timezone=True), 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_signal_device")),
+        sa.UniqueConstraint("phone_number", name=op.f("uq_signal_device_phone_number")),
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("signal_device", schema=schema)
+    # ### end Alembic commands ###

python/alembic/richie/versions/2026_03_09-fixed_safety_number_logic_99fec682516c.py

@@ -0,0 +1,41 @@
+"""fixed safety number logic.
+
+Revision ID: 99fec682516c
+Revises: 4c410c16e39c
+Create Date: 2026-03-09 16:25:25.085806
+
+"""
+
+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 = "99fec682516c"
+down_revision: str | None = "4c410c16e39c"
+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("signal_device", "safety_number", existing_type=sa.VARCHAR(), nullable=True, schema=schema)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column("signal_device", "safety_number", existing_type=sa.VARCHAR(), nullable=False, schema=schema)
+    # ### end Alembic commands ###

python/alembic/richie/versions/2026_03_10-add_dead_letter_message_table_a1b2c3d4e5f6.py

@@ -0,0 +1,54 @@
+"""add dead_letter_message table.
+
+Revision ID: a1b2c3d4e5f6
+Revises: 99fec682516c
+Create Date: 2026-03-10 12:00:00.000000
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+from python.orm import RichieBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "a1b2c3d4e5f6"
+down_revision: str | None = "99fec682516c"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = RichieBase.schema_name
+
+
+def upgrade() -> None:
+    """Upgrade."""
+    op.create_table(
+        "dead_letter_message",
+        sa.Column("source", sa.String(), nullable=False),
+        sa.Column("message", sa.Text(), nullable=False),
+        sa.Column("received_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column(
+            "status",
+            postgresql.ENUM("UNPROCESSED", "PROCESSED", name="message_status", schema=schema),
+            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_dead_letter_message")),
+        schema=schema,
+    )
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    op.drop_table("dead_letter_message", schema=schema)
+    op.execute(sa.text(f"DROP TYPE IF EXISTS {schema}.message_status"))

python/alembic/richie/versions/2026_03_16-adding_roles_to_signal_devices_2ef7ba690159.py

@@ -0,0 +1,66 @@
+"""adding roles to signal devices.
+
+Revision ID: 2ef7ba690159
+Revises: a1b2c3d4e5f6
+Create Date: 2026-03-16 19:22:38.020350
+
+"""
+
+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 = "2ef7ba690159"
+down_revision: str | None = "a1b2c3d4e5f6"
+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(
+        "role",
+        sa.Column("name", sa.String(length=50), nullable=False),
+        sa.Column("id", sa.SmallInteger(), 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_role")),
+        sa.UniqueConstraint("name", name=op.f("uq_role_name")),
+        schema=schema,
+    )
+    op.create_table(
+        "device_role",
+        sa.Column("device_id", sa.Integer(), nullable=False),
+        sa.Column("role_id", sa.SmallInteger(), 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(
+            ["device_id"], [f"{schema}.signal_device.id"], name=op.f("fk_device_role_device_id_signal_device")
+        ),
+        sa.ForeignKeyConstraint(["role_id"], [f"{schema}.role.id"], name=op.f("fk_device_role_role_id_role")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_device_role")),
+        sa.UniqueConstraint("device_id", "role_id", name="uq_device_role_device_role"),
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("device_role", schema=schema)
+    op.drop_table("role", schema=schema)
+    # ### end Alembic commands ###

python/alembic/richie/versions/2026_03_18-seprating_signal_bot_database_6b275323f435.py

@@ -0,0 +1,171 @@
+"""seprating signal_bot database.
+
+Revision ID: 6b275323f435
+Revises: 2ef7ba690159
+Create Date: 2026-03-18 08:34:28.785885
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+from python.orm import RichieBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "6b275323f435"
+down_revision: str | None = "2ef7ba690159"
+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.drop_table("device_role", schema=schema)
+    op.drop_table("signal_device", schema=schema)
+    op.drop_table("role", schema=schema)
+    op.drop_table("dead_letter_message", schema=schema)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "dead_letter_message",
+        sa.Column("source", sa.VARCHAR(), autoincrement=False, nullable=False),
+        sa.Column("message", sa.TEXT(), autoincrement=False, nullable=False),
+        sa.Column("received_at", postgresql.TIMESTAMP(timezone=True), autoincrement=False, nullable=False),
+        sa.Column(
+            "status",
+            postgresql.ENUM("UNPROCESSED", "PROCESSED", name="message_status", schema=schema),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column("id", sa.INTEGER(), autoincrement=True, nullable=False),
+        sa.Column(
+            "created",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column(
+            "updated",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_dead_letter_message")),
+        schema=schema,
+    )
+    op.create_table(
+        "role",
+        sa.Column("name", sa.VARCHAR(length=50), autoincrement=False, nullable=False),
+        sa.Column(
+            "id",
+            sa.SMALLINT(),
+            server_default=sa.text(f"nextval('{schema}.role_id_seq'::regclass)"),
+            autoincrement=True,
+            nullable=False,
+        ),
+        sa.Column(
+            "created",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column(
+            "updated",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_role")),
+        sa.UniqueConstraint(
+            "name", name=op.f("uq_role_name"), postgresql_include=[], postgresql_nulls_not_distinct=False
+        ),
+        schema=schema,
+    )
+    op.create_table(
+        "signal_device",
+        sa.Column("phone_number", sa.VARCHAR(length=50), autoincrement=False, nullable=False),
+        sa.Column("safety_number", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column(
+            "trust_level",
+            postgresql.ENUM("VERIFIED", "UNVERIFIED", "BLOCKED", name="trust_level", schema=schema),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column("last_seen", postgresql.TIMESTAMP(timezone=True), autoincrement=False, nullable=False),
+        sa.Column("id", sa.INTEGER(), autoincrement=True, nullable=False),
+        sa.Column(
+            "created",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column(
+            "updated",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_signal_device")),
+        sa.UniqueConstraint(
+            "phone_number",
+            name=op.f("uq_signal_device_phone_number"),
+            postgresql_include=[],
+            postgresql_nulls_not_distinct=False,
+        ),
+        schema=schema,
+    )
+    op.create_table(
+        "device_role",
+        sa.Column("device_id", sa.INTEGER(), autoincrement=False, nullable=False),
+        sa.Column("role_id", sa.SMALLINT(), autoincrement=False, nullable=False),
+        sa.Column("id", sa.INTEGER(), autoincrement=True, nullable=False),
+        sa.Column(
+            "created",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column(
+            "updated",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["device_id"], [f"{schema}.signal_device.id"], name=op.f("fk_device_role_device_id_signal_device")
+        ),
+        sa.ForeignKeyConstraint(["role_id"], [f"{schema}.role.id"], name=op.f("fk_device_role_role_id_role")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_device_role")),
+        sa.UniqueConstraint(
+            "device_id",
+            "role_id",
+            name=op.f("uq_device_role_device_role"),
+            postgresql_include=[],
+            postgresql_nulls_not_distinct=False,
+        ),
+        schema=schema,
+    )
+    # ### end Alembic commands ###

python/alembic/richie/versions/2026_03_29-removed_ds_table_from_richie_db_c8a794340928.py

@@ -0,0 +1,187 @@
+"""removed ds table from richie DB.
+
+Revision ID: c8a794340928
+Revises: 6b275323f435
+Create Date: 2026-03-29 15:29:23.643146
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+from python.orm import RichieBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "c8a794340928"
+down_revision: str | None = "6b275323f435"
+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.drop_table("vote_record", schema=schema)
+    op.drop_index(op.f("ix_vote_congress_chamber"), table_name="vote", schema=schema)
+    op.drop_index(op.f("ix_vote_date"), table_name="vote", schema=schema)
+    op.drop_index(op.f("ix_legislator_bioguide_id"), table_name="legislator", schema=schema)
+    op.drop_table("legislator", schema=schema)
+    op.drop_table("vote", schema=schema)
+    op.drop_index(op.f("ix_bill_congress"), table_name="bill", schema=schema)
+    op.drop_table("bill", schema=schema)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "vote",
+        sa.Column("congress", sa.INTEGER(), autoincrement=False, nullable=False),
+        sa.Column("chamber", sa.VARCHAR(), autoincrement=False, nullable=False),
+        sa.Column("session", sa.INTEGER(), autoincrement=False, nullable=False),
+        sa.Column("number", sa.INTEGER(), autoincrement=False, nullable=False),
+        sa.Column("vote_type", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("question", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("result", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("result_text", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("vote_date", sa.DATE(), autoincrement=False, nullable=False),
+        sa.Column("yea_count", sa.INTEGER(), autoincrement=False, nullable=True),
+        sa.Column("nay_count", sa.INTEGER(), autoincrement=False, nullable=True),
+        sa.Column("not_voting_count", sa.INTEGER(), autoincrement=False, nullable=True),
+        sa.Column("present_count", sa.INTEGER(), autoincrement=False, nullable=True),
+        sa.Column("bill_id", sa.INTEGER(), autoincrement=False, nullable=True),
+        sa.Column("id", sa.INTEGER(), autoincrement=True, nullable=False),
+        sa.Column(
+            "created",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column(
+            "updated",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(["bill_id"], [f"{schema}.bill.id"], name=op.f("fk_vote_bill_id_bill")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_vote")),
+        sa.UniqueConstraint(
+            "congress",
+            "chamber",
+            "session",
+            "number",
+            name=op.f("uq_vote_congress_chamber_session_number"),
+            postgresql_include=[],
+            postgresql_nulls_not_distinct=False,
+        ),
+        schema=schema,
+    )
+    op.create_index(op.f("ix_vote_date"), "vote", ["vote_date"], unique=False, schema=schema)
+    op.create_index(op.f("ix_vote_congress_chamber"), "vote", ["congress", "chamber"], unique=False, schema=schema)
+    op.create_table(
+        "vote_record",
+        sa.Column("vote_id", sa.INTEGER(), autoincrement=False, nullable=False),
+        sa.Column("legislator_id", sa.INTEGER(), autoincrement=False, nullable=False),
+        sa.Column("position", sa.VARCHAR(), autoincrement=False, nullable=False),
+        sa.ForeignKeyConstraint(
+            ["legislator_id"],
+            [f"{schema}.legislator.id"],
+            name=op.f("fk_vote_record_legislator_id_legislator"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["vote_id"], [f"{schema}.vote.id"], name=op.f("fk_vote_record_vote_id_vote"), ondelete="CASCADE"
+        ),
+        sa.PrimaryKeyConstraint("vote_id", "legislator_id", name=op.f("pk_vote_record")),
+        schema=schema,
+    )
+    op.create_table(
+        "legislator",
+        sa.Column("bioguide_id", sa.TEXT(), autoincrement=False, nullable=False),
+        sa.Column("thomas_id", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("lis_id", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("govtrack_id", sa.INTEGER(), autoincrement=False, nullable=True),
+        sa.Column("opensecrets_id", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("fec_ids", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("first_name", sa.VARCHAR(), autoincrement=False, nullable=False),
+        sa.Column("last_name", sa.VARCHAR(), autoincrement=False, nullable=False),
+        sa.Column("official_full_name", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("nickname", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("birthday", sa.DATE(), autoincrement=False, nullable=True),
+        sa.Column("gender", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("current_party", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("current_state", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("current_district", sa.INTEGER(), autoincrement=False, nullable=True),
+        sa.Column("current_chamber", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("id", sa.INTEGER(), autoincrement=True, nullable=False),
+        sa.Column(
+            "created",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column(
+            "updated",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_legislator")),
+        schema=schema,
+    )
+    op.create_index(op.f("ix_legislator_bioguide_id"), "legislator", ["bioguide_id"], unique=True, schema=schema)
+    op.create_table(
+        "bill",
+        sa.Column("congress", sa.INTEGER(), autoincrement=False, nullable=False),
+        sa.Column("bill_type", sa.VARCHAR(), autoincrement=False, nullable=False),
+        sa.Column("number", sa.INTEGER(), autoincrement=False, nullable=False),
+        sa.Column("title", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("title_short", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("official_title", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("status", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("status_at", sa.DATE(), autoincrement=False, nullable=True),
+        sa.Column("sponsor_bioguide_id", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("subjects_top_term", sa.VARCHAR(), autoincrement=False, nullable=True),
+        sa.Column("id", sa.INTEGER(), autoincrement=True, nullable=False),
+        sa.Column(
+            "created",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.Column(
+            "updated",
+            postgresql.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            autoincrement=False,
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_bill")),
+        sa.UniqueConstraint(
+            "congress",
+            "bill_type",
+            "number",
+            name=op.f("uq_bill_congress_type_number"),
+            postgresql_include=[],
+            postgresql_nulls_not_distinct=False,
+        ),
+        schema=schema,
+    )
+    op.create_index(op.f("ix_bill_congress"), "bill", ["congress"], unique=False, schema=schema)
+    # ### end Alembic commands ###

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-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/alembic/script.py.mako

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING
 import sqlalchemy as sa
 
 from alembic import op
-from python.orm import RichieBase
+from python.orm import ${config.attributes["base"].__name__}
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -24,7 +24,7 @@ down_revision: str | None = ${repr(down_revision)}
 branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
 depends_on: str | Sequence[str] | None = ${repr(depends_on)}
 
-schema=RichieBase.schema_name
+schema=${config.attributes["base"].__name__}.schema_name
 
 def upgrade() -> None:
     """Upgrade."""

python/alembic/van_inventory/versions/2026_03_08-starting_van_invintory_15e733499804.py

@@ -0,0 +1,80 @@
+"""starting van invintory.
+
+Revision ID: 15e733499804
+Revises:
+Create Date: 2026-03-08 00:18:20.759720
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+
+from python.orm import VanInventoryBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "15e733499804"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = VanInventoryBase.schema_name
+
+
+def upgrade() -> None:
+    """Upgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "items",
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("quantity", sa.Float(), nullable=False),
+        sa.Column("unit", sa.String(), nullable=False),
+        sa.Column("category", 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.PrimaryKeyConstraint("id", name=op.f("pk_items")),
+        sa.UniqueConstraint("name", name=op.f("uq_items_name")),
+        schema=schema,
+    )
+    op.create_table(
+        "meals",
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("instructions", 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.PrimaryKeyConstraint("id", name=op.f("pk_meals")),
+        sa.UniqueConstraint("name", name=op.f("uq_meals_name")),
+        schema=schema,
+    )
+    op.create_table(
+        "meal_ingredients",
+        sa.Column("meal_id", sa.Integer(), nullable=False),
+        sa.Column("item_id", sa.Integer(), nullable=False),
+        sa.Column("quantity_needed", sa.Float(), 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(["item_id"], [f"{schema}.items.id"], name=op.f("fk_meal_ingredients_item_id_items")),
+        sa.ForeignKeyConstraint(["meal_id"], [f"{schema}.meals.id"], name=op.f("fk_meal_ingredients_meal_id_meals")),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_meal_ingredients")),
+        sa.UniqueConstraint("meal_id", "item_id", name=op.f("uq_meal_ingredients_meal_id")),
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("meal_ingredients", schema=schema)
+    op.drop_table("meals", schema=schema)
+    op.drop_table("items", schema=schema)
+    # ### end Alembic commands ###

python/api/main.py

@@ -1,27 +1,23 @@
 """FastAPI interface for Contact database."""
 
 import logging
-import shutil
-import subprocess
-import tempfile
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
-from os import environ
-from pathlib import Path
 from typing import Annotated
 
 import typer
 import uvicorn
 from fastapi import FastAPI
 
-from python.api.routers import contact_router, create_frontend_router
+from python.api.middleware import ZstdMiddleware
+from python.api.routers import contact_router, views_router
 from python.common import configure_logger
-from python.orm.base import get_postgres_engine
+from python.orm.common import get_postgres_engine
 
 logger = logging.getLogger(__name__)
 
 
-def create_app(frontend_dir: Path | None = None) -> FastAPI:
+def create_app() -> FastAPI:
     """Create and configure the FastAPI application."""
 
     @asynccontextmanager
@@ -32,84 +28,23 @@ def create_app(frontend_dir: Path | None = None) -> FastAPI:
         app.state.engine.dispose()
 
     app = FastAPI(title="Contact Database API", lifespan=lifespan)
+    app.add_middleware(ZstdMiddleware)
 
     app.include_router(contact_router)
-
+    app.include_router(views_router)
-    if frontend_dir:
-        logger.info(f"Serving frontend from {frontend_dir}")
-        frontend_router = create_frontend_router(frontend_dir)
-        app.include_router(frontend_router)
 
     return app
 
 
-def build_frontend(source_dir: Path | None, cache_dir: Path | None = None) -> Path | None:
-    """Run npm build and copy output to a temp directory.
-
-    Works even if source_dir is read-only by copying to a temp directory first.
-
-    Args:
-        source_dir: Frontend source directory.
-        cache_dir: Optional npm cache directory for faster repeated builds.
-
-    Returns:
-        Path to frontend build directory, or None if no source_dir provided.
-    """
-    if not source_dir:
-        return None
-
-    if not source_dir.exists():
-        error = f"Frontend directory {source_dir} does not exist"
-        raise FileExistsError(error)
-
-    logger.info("Building frontend from %s...", source_dir)
-
-    # Copy source to a writable temp directory
-    build_dir = Path(tempfile.mkdtemp(prefix="contact_frontend_build_"))
-    shutil.copytree(source_dir, build_dir, dirs_exist_ok=True)
-
-    env = dict(environ)
-    if cache_dir:
-        cache_dir.mkdir(parents=True, exist_ok=True)
-        env["npm_config_cache"] = str(cache_dir)
-
-    subprocess.run(["npm", "install"], cwd=build_dir, env=env, check=True)  # noqa: S607
-    subprocess.run(["npm", "run", "build"], cwd=build_dir, env=env, check=True)  # noqa: S607
-
-    dist_dir = build_dir / "dist"
-    if not dist_dir.exists():
-        error = f"Build output not found at {dist_dir}"
-        raise FileNotFoundError(error)
-
-    output_dir = Path(tempfile.mkdtemp(prefix="contact_frontend_"))
-    shutil.copytree(dist_dir, output_dir, dirs_exist_ok=True)
-    logger.info(f"Frontend built and copied to {output_dir}")
-
-    shutil.rmtree(build_dir)
-
-    return output_dir
-
-
 def serve(
     host: Annotated[str, typer.Option("--host", "-h", help="Host to bind to")],
-    frontend_dir: Annotated[
-        Path | None,
-        typer.Option(
-            "--frontend-dir",
-            "-f",
-            help="Frontend source directory. If provided, runs npm build and serves from temp dir.",
-        ),
-    ] = None,
     port: Annotated[int, typer.Option("--port", "-p", help="Port to bind to")] = 8000,
     log_level: Annotated[str, typer.Option("--log-level", "-l", help="Log level")] = "INFO",
 ) -> None:
     """Start the Contact API server."""
     configure_logger(log_level)
 
-    cache_dir = Path(environ["HOME"]) / ".npm"
+    app = create_app()
-    serve_dir = build_frontend(frontend_dir, cache_dir=cache_dir)
-
-    app = create_app(frontend_dir=serve_dir)
     uvicorn.run(app, host=host, port=port)
 
 

python/api/middleware.py

@@ -0,0 +1,49 @@
+"""Middleware for the FastAPI application."""
+
+from compression import zstd
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+MINIMUM_RESPONSE_SIZE = 500
+
+
+class ZstdMiddleware(BaseHTTPMiddleware):
+    """Middleware that compresses responses with zstd when the client supports it."""
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        """Compress the response with zstd if the client accepts it."""
+        accepted_encodings = request.headers.get("accept-encoding", "")
+        if "zstd" not in accepted_encodings:
+            return await call_next(request)
+
+        response = await call_next(request)
+
+        if response.headers.get("content-encoding") or "text/event-stream" in response.headers.get("content-type", ""):
+            return response
+
+        body = b""
+        async for chunk in response.body_iterator:
+            body += chunk if isinstance(chunk, bytes) else chunk.encode()
+
+        if len(body) < MINIMUM_RESPONSE_SIZE:
+            return Response(
+                content=body,
+                status_code=response.status_code,
+                headers=dict(response.headers),
+                media_type=response.media_type,
+            )
+
+        compressed = zstd.compress(body)
+
+        headers = dict(response.headers)
+        headers["content-encoding"] = "zstd"
+        headers["content-length"] = str(len(compressed))
+        headers.pop("transfer-encoding", None)
+
+        return Response(
+            content=compressed,
+            status_code=response.status_code,
+            headers=headers,
+            media_type=response.media_type,
+        )

python/api/routers/__init__.py

@@ -1,6 +1,6 @@
 """API routers."""
 
 from python.api.routers.contact import router as contact_router
-from python.api.routers.frontend import create_frontend_router
+from python.api.routers.views import router as views_router
 
-__all__ = ["contact_router", "create_frontend_router"]
+__all__ = ["contact_router", "views_router"]

python/api/routers/contact.py

@@ -1,12 +1,24 @@
 """Contact API router."""
 
-from fastapi import APIRouter, HTTPException
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
 from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.orm import selectinload
 
 from python.api.dependencies import DbSession
-from python.orm.contact import Contact, ContactRelationship, Need, RelationshipType
+from python.orm.richie.contact import Contact, ContactRelationship, Need, RelationshipType
+
+TEMPLATES_DIR = Path(__file__).parent.parent / "templates"
+templates = Jinja2Templates(directory=TEMPLATES_DIR)
+
+
+def _is_htmx(request: Request) -> bool:
+    """Check if the request is from HTMX."""
+    return request.headers.get("HX-Request") == "true"
 
 
 class NeedBase(BaseModel):
@@ -180,14 +192,16 @@ def get_need(need_id: int, db: DbSession) -> Need:
     return need
 
 
-@router.delete("/needs/{need_id}")
+@router.delete("/needs/{need_id}", response_model=None)
-def delete_need(need_id: int, db: DbSession) -> dict[str, bool]:
+def delete_need(need_id: int, request: Request, db: DbSession) -> dict[str, bool] | HTMLResponse:
     """Delete a need by ID."""
     need = db.get(Need, need_id)
     if not need:
         raise HTTPException(status_code=404, detail="Need not found")
     db.delete(need)
     db.commit()
+    if _is_htmx(request):
+        return HTMLResponse("")
     return {"deleted": True}
 
 
@@ -261,14 +275,16 @@ def update_contact(
     return db_contact
 
 
-@router.delete("/contacts/{contact_id}")
+@router.delete("/contacts/{contact_id}", response_model=None)
-def delete_contact(contact_id: int, db: DbSession) -> dict[str, bool]:
+def delete_contact(contact_id: int, request: Request, db: DbSession) -> dict[str, bool] | HTMLResponse:
     """Delete a contact by ID."""
     contact = db.get(Contact, contact_id)
     if not contact:
         raise HTTPException(status_code=404, detail="Contact not found")
     db.delete(contact)
     db.commit()
+    if _is_htmx(request):
+        return HTMLResponse("")
     return {"deleted": True}
 
 
@@ -294,12 +310,13 @@ def add_need_to_contact(
     return {"added": True}
 
 
-@router.delete("/contacts/{contact_id}/needs/{need_id}")
+@router.delete("/contacts/{contact_id}/needs/{need_id}", response_model=None)
 def remove_need_from_contact(
     contact_id: int,
     need_id: int,
+    request: Request,
     db: DbSession,
-) -> dict[str, bool]:
+) -> dict[str, bool] | HTMLResponse:
     """Remove a need from a contact."""
     contact = db.get(Contact, contact_id)
     if not contact:
@@ -313,6 +330,8 @@ def remove_need_from_contact(
         contact.needs.remove(need)
         db.commit()
 
+    if _is_htmx(request):
+        return HTMLResponse("")
     return {"removed": True}
 
 
@@ -404,12 +423,13 @@ def update_contact_relationship(
     return relationship
 
 
-@router.delete("/contacts/{contact_id}/relationships/{related_contact_id}")
+@router.delete("/contacts/{contact_id}/relationships/{related_contact_id}", response_model=None)
 def remove_contact_relationship(
     contact_id: int,
     related_contact_id: int,
+    request: Request,
     db: DbSession,
-) -> dict[str, bool]:
+) -> dict[str, bool] | HTMLResponse:
     """Remove a relationship between two contacts."""
     relationship = db.scalar(
         select(ContactRelationship).where(
@@ -422,6 +442,8 @@ def remove_contact_relationship(
 
     db.delete(relationship)
     db.commit()
+    if _is_htmx(request):
+        return HTMLResponse("")
     return {"deleted": True}
 
 

python/api/routers/frontend.py

@@ -1,24 +0,0 @@
-"""Frontend SPA router."""
-
-from pathlib import Path
-
-from fastapi import APIRouter
-from fastapi.responses import FileResponse
-from fastapi.staticfiles import StaticFiles
-
-
-def create_frontend_router(frontend_dir: Path) -> APIRouter:
-    """Create a router for serving the frontend SPA."""
-    router = APIRouter(tags=["frontend"])
-
-    router.mount("/assets", StaticFiles(directory=frontend_dir / "assets"), name="assets")
-
-    @router.get("/{full_path:path}")
-    async def serve_spa(full_path: str) -> FileResponse:
-        """Serve React SPA for all non-API routes."""
-        file_path = frontend_dir / full_path
-        if file_path.is_file():
-            return FileResponse(file_path)
-        return FileResponse(frontend_dir / "index.html")
-
-    return router

python/api/routers/views.py

@@ -0,0 +1,345 @@
+"""HTMX server-rendered view router."""
+
+from pathlib import Path
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Form, HTTPException, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.templating import Jinja2Templates
+from sqlalchemy import select
+from sqlalchemy.orm import Session, selectinload
+
+from python.api.dependencies import DbSession
+from python.orm.richie.contact import Contact, ContactRelationship, Need, RelationshipType
+
+TEMPLATES_DIR = Path(__file__).parent.parent / "templates"
+templates = Jinja2Templates(directory=TEMPLATES_DIR)
+
+router = APIRouter(tags=["views"])
+
+FAMILIAL_TYPES = {
+    "parent",
+    "child",
+    "sibling",
+    "grandparent",
+    "grandchild",
+    "aunt_uncle",
+    "niece_nephew",
+    "cousin",
+    "in_law",
+}
+FRIEND_TYPES = {"best_friend", "close_friend", "friend", "acquaintance", "neighbor"}
+PARTNER_TYPES = {"spouse", "partner"}
+PROFESSIONAL_TYPES = {"mentor", "mentee", "business_partner", "colleague", "manager", "direct_report", "client"}
+
+CONTACT_STRING_FIELDS = (
+    "name",
+    "legal_name",
+    "suffix",
+    "gender",
+    "current_job",
+    "timezone",
+    "profile_pic",
+    "bio",
+    "goals",
+    "social_structure_style",
+    "safe_conversation_starters",
+    "topics_to_avoid",
+    "ssn",
+)
+
+CONTACT_INT_FIELDS = ("age", "self_sufficiency_score")
+
+
+def _group_relationships(relationships: list[ContactRelationship]) -> dict[str, list[ContactRelationship]]:
+    """Group relationships by category."""
+    groups: dict[str, list[ContactRelationship]] = {
+        "familial": [],
+        "partners": [],
+        "friends": [],
+        "professional": [],
+        "other": [],
+    }
+    for rel in relationships:
+        if rel.relationship_type in FAMILIAL_TYPES:
+            groups["familial"].append(rel)
+        elif rel.relationship_type in PARTNER_TYPES:
+            groups["partners"].append(rel)
+        elif rel.relationship_type in FRIEND_TYPES:
+            groups["friends"].append(rel)
+        elif rel.relationship_type in PROFESSIONAL_TYPES:
+            groups["professional"].append(rel)
+        else:
+            groups["other"].append(rel)
+    return groups
+
+
+def _build_contact_name_map(database: Session, contact: Contact) -> dict[int, str]:
+    """Build a mapping of contact IDs to names for relationship display."""
+    related_ids = {rel.related_contact_id for rel in contact.related_to}
+    related_ids |= {rel.contact_id for rel in contact.related_from}
+    related_ids.discard(contact.id)
+
+    if not related_ids:
+        return {}
+
+    related_contacts = list(database.scalars(select(Contact).where(Contact.id.in_(related_ids))).all())
+    return {related.id: related.name for related in related_contacts}
+
+
+def _get_relationship_type_display() -> dict[str, str]:
+    """Build a mapping of relationship type values to display names."""
+    return {rel_type.value: rel_type.display_name for rel_type in RelationshipType}
+
+
+async def _parse_contact_form(request: Request) -> dict[str, Any]:
+    """Parse contact form data from a multipart/form request."""
+    form_data = await request.form()
+    result: dict[str, Any] = {}
+
+    for field in CONTACT_STRING_FIELDS:
+        value = form_data.get(field, "")
+        result[field] = str(value) if value else None
+
+    for field in CONTACT_INT_FIELDS:
+        value = form_data.get(field, "")
+        result[field] = int(value) if value else None
+
+    result["need_ids"] = [int(value) for value in form_data.getlist("need_ids")]
+    return result
+
+
+def _save_contact_from_form(database: Session, contact: Contact, form_result: dict[str, Any]) -> None:
+    """Apply parsed form data to a Contact and save associated needs."""
+    need_ids = form_result.pop("need_ids")
+
+    for key, value in form_result.items():
+        setattr(contact, key, value)
+
+    if need_ids:
+        contact.needs = list(database.scalars(select(Need).where(Need.id.in_(need_ids))).all())
+    else:
+        contact.needs = []
+
+
+@router.get("/", response_class=HTMLResponse)
+@router.get("/contacts", response_class=HTMLResponse)
+def contact_list_page(request: Request, database: DbSession) -> HTMLResponse:
+    """Render the contacts list page."""
+    contacts = list(database.scalars(select(Contact)).all())
+    return templates.TemplateResponse(request, "contact_list.html", {"contacts": contacts})
+
+
+@router.get("/contacts/new", response_class=HTMLResponse)
+def new_contact_page(request: Request, database: DbSession) -> HTMLResponse:
+    """Render the new contact form page."""
+    all_needs = list(database.scalars(select(Need)).all())
+    return templates.TemplateResponse(request, "contact_form.html", {"contact": None, "all_needs": all_needs})
+
+
+@router.post("/htmx/contacts/new")
+async def create_contact_form(request: Request, database: DbSession) -> RedirectResponse:
+    """Handle the create contact form submission."""
+    form_result = await _parse_contact_form(request)
+    contact = Contact()
+    _save_contact_from_form(database, contact, form_result)
+
+    database.add(contact)
+    database.commit()
+    database.refresh(contact)
+    return RedirectResponse(url=f"/contacts/{contact.id}", status_code=303)
+
+
+@router.get("/contacts/{contact_id}", response_class=HTMLResponse)
+def contact_detail_page(contact_id: int, request: Request, database: DbSession) -> HTMLResponse:
+    """Render the contact detail page."""
+    contact = database.scalar(
+        select(Contact)
+        .where(Contact.id == contact_id)
+        .options(
+            selectinload(Contact.needs),
+            selectinload(Contact.related_to),
+            selectinload(Contact.related_from),
+        )
+    )
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    contact_names = _build_contact_name_map(database, contact)
+    grouped_relationships = _group_relationships(contact.related_to)
+    all_contacts = list(database.scalars(select(Contact)).all())
+    all_needs = list(database.scalars(select(Need)).all())
+    available_needs = [need for need in all_needs if need not in contact.needs]
+
+    return templates.TemplateResponse(
+        request,
+        "contact_detail.html",
+        {
+            "contact": contact,
+            "contact_names": contact_names,
+            "grouped_relationships": grouped_relationships,
+            "all_contacts": all_contacts,
+            "available_needs": available_needs,
+            "relationship_types": list(RelationshipType),
+        },
+    )
+
+
+@router.get("/contacts/{contact_id}/edit", response_class=HTMLResponse)
+def edit_contact_page(contact_id: int, request: Request, database: DbSession) -> HTMLResponse:
+    """Render the edit contact form page."""
+    contact = database.scalar(select(Contact).where(Contact.id == contact_id).options(selectinload(Contact.needs)))
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    all_needs = list(database.scalars(select(Need)).all())
+    return templates.TemplateResponse(request, "contact_form.html", {"contact": contact, "all_needs": all_needs})
+
+
+@router.post("/htmx/contacts/{contact_id}/edit")
+async def update_contact_form(contact_id: int, request: Request, database: DbSession) -> RedirectResponse:
+    """Handle the edit contact form submission."""
+    contact = database.get(Contact, contact_id)
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    form_result = await _parse_contact_form(request)
+    _save_contact_from_form(database, contact, form_result)
+
+    database.commit()
+    return RedirectResponse(url=f"/contacts/{contact_id}", status_code=303)
+
+
+@router.post("/htmx/contacts/{contact_id}/add-need", response_class=HTMLResponse)
+def add_need_to_contact_htmx(
+    contact_id: int,
+    request: Request,
+    database: DbSession,
+    need_id: Annotated[int, Form()],
+) -> HTMLResponse:
+    """Add a need to a contact and return updated manage-needs partial."""
+    contact = database.scalar(select(Contact).where(Contact.id == contact_id).options(selectinload(Contact.needs)))
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    need = database.get(Need, need_id)
+    if not need:
+        raise HTTPException(status_code=404, detail="Need not found")
+
+    if need not in contact.needs:
+        contact.needs.append(need)
+        database.commit()
+        database.refresh(contact)
+
+    return templates.TemplateResponse(request, "partials/manage_needs.html", {"contact": contact})
+
+
+@router.post("/htmx/contacts/{contact_id}/add-relationship", response_class=HTMLResponse)
+def add_relationship_htmx(
+    contact_id: int,
+    request: Request,
+    database: DbSession,
+    related_contact_id: Annotated[int, Form()],
+    relationship_type: Annotated[str, Form()],
+) -> HTMLResponse:
+    """Add a relationship and return updated manage-relationships partial."""
+    contact = database.scalar(select(Contact).where(Contact.id == contact_id).options(selectinload(Contact.related_to)))
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    related_contact = database.get(Contact, related_contact_id)
+    if not related_contact:
+        raise HTTPException(status_code=404, detail="Related contact not found")
+
+    rel_type = RelationshipType(relationship_type)
+    weight = rel_type.default_weight
+
+    relationship = ContactRelationship(
+        contact_id=contact_id,
+        related_contact_id=related_contact_id,
+        relationship_type=relationship_type,
+        closeness_weight=weight,
+    )
+    database.add(relationship)
+    database.commit()
+    database.refresh(contact)
+
+    contact_names = _build_contact_name_map(database, contact)
+    return templates.TemplateResponse(
+        request,
+        "partials/manage_relationships.html",
+        {"contact": contact, "contact_names": contact_names},
+    )
+
+
+@router.post("/htmx/contacts/{contact_id}/relationships/{related_contact_id}/weight")
+def update_relationship_weight_htmx(
+    contact_id: int,
+    related_contact_id: int,
+    database: DbSession,
+    closeness_weight: Annotated[int, Form()],
+) -> HTMLResponse:
+    """Update a relationship's closeness weight from HTMX range input."""
+    relationship = database.scalar(
+        select(ContactRelationship).where(
+            ContactRelationship.contact_id == contact_id,
+            ContactRelationship.related_contact_id == related_contact_id,
+        )
+    )
+    if not relationship:
+        raise HTTPException(status_code=404, detail="Relationship not found")
+
+    relationship.closeness_weight = closeness_weight
+    database.commit()
+    return HTMLResponse("")
+
+
+@router.post("/htmx/needs", response_class=HTMLResponse)
+def create_need_htmx(
+    request: Request,
+    database: DbSession,
+    name: Annotated[str, Form()],
+    description: Annotated[str, Form()] = "",
+) -> HTMLResponse:
+    """Create a need via form data and return updated needs list."""
+    need = Need(name=name, description=description or None)
+    database.add(need)
+    database.commit()
+    needs = list(database.scalars(select(Need)).all())
+    return templates.TemplateResponse(request, "partials/need_items.html", {"needs": needs})
+
+
+@router.get("/needs", response_class=HTMLResponse)
+def needs_page(request: Request, database: DbSession) -> HTMLResponse:
+    """Render the needs list page."""
+    needs = list(database.scalars(select(Need)).all())
+    return templates.TemplateResponse(request, "need_list.html", {"needs": needs})
+
+
+@router.get("/graph", response_class=HTMLResponse)
+def graph_page(request: Request, database: DbSession) -> HTMLResponse:
+    """Render the relationship graph page."""
+    contacts = list(database.scalars(select(Contact)).all())
+    relationships = list(database.scalars(select(ContactRelationship)).all())
+
+    graph_data = {
+        "nodes": [{"id": contact.id, "name": contact.name, "current_job": contact.current_job} for contact in contacts],
+        "edges": [
+            {
+                "source": rel.contact_id,
+                "target": rel.related_contact_id,
+                "relationship_type": rel.relationship_type,
+                "closeness_weight": rel.closeness_weight,
+            }
+            for rel in relationships
+        ],
+    }
+
+    return templates.TemplateResponse(
+        request,
+        "graph.html",
+        {
+            "graph_data": graph_data,
+            "relationship_type_display": _get_relationship_type_display(),
+        },
+    )

python/api/templates/base.html

@@ -0,0 +1,198 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}Contact Database{% endblock %}</title>
+    <script src="https://unpkg.com/htmx.org@2.0.4"></script>
+    <style>
+        :root {
+            --color-bg: #f5f5f5;
+            --color-bg-card: #ffffff;
+            --color-bg-hover: #f0f0f0;
+            --color-bg-muted: #f9f9f9;
+            --color-bg-error: #ffe0e0;
+            --color-text: #333333;
+            --color-text-muted: #666666;
+            --color-text-error: #cc0000;
+            --color-border: #dddddd;
+            --color-border-light: #eeeeee;
+            --color-border-lighter: #f0f0f0;
+            --color-primary: #0066cc;
+            --color-primary-hover: #0055aa;
+            --color-danger: #cc3333;
+            --color-danger-hover: #aa2222;
+            --color-tag-bg: #e0e0e0;
+            --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            line-height: 1.5;
+            color: var(--color-text);
+            background-color: var(--color-bg);
+        }
+        [data-theme="dark"] {
+            --color-bg: #1a1a1a;
+            --color-bg-card: #2d2d2d;
+            --color-bg-hover: #3d3d3d;
+            --color-bg-muted: #252525;
+            --color-bg-error: #4a2020;
+            --color-text: #e0e0e0;
+            --color-text-muted: #a0a0a0;
+            --color-text-error: #ff6b6b;
+            --color-border: #404040;
+            --color-border-light: #353535;
+            --color-border-lighter: #303030;
+            --color-primary: #4da6ff;
+            --color-primary-hover: #7dbfff;
+            --color-danger: #ff6b6b;
+            --color-danger-hover: #ff8a8a;
+            --color-tag-bg: #404040;
+            --shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
+        }
+        * { box-sizing: border-box; }
+        body { margin: 0; background: var(--color-bg); color: var(--color-text); }
+        .app { max-width: 1000px; margin: 0 auto; padding: 20px; }
+        nav { display: flex; align-items: center; gap: 20px; padding: 15px 0; border-bottom: 1px solid var(--color-border); margin-bottom: 20px; }
+        nav a { color: var(--color-primary); text-decoration: none; font-weight: 500; }
+        nav a:hover { text-decoration: underline; }
+        .theme-toggle { margin-left: auto; }
+        main { background: var(--color-bg-card); padding: 20px; border-radius: 8px; box-shadow: var(--shadow); }
+        .header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 20px; }
+        .header h1 { margin: 0; }
+        a { color: var(--color-primary); }
+        a:hover { text-decoration: underline; }
+
+        .btn { display: inline-block; padding: 8px 16px; border: 1px solid var(--color-border); border-radius: 4px; background: var(--color-bg-card); color: var(--color-text); text-decoration: none; cursor: pointer; font-size: 14px; margin-left: 8px; }
+        .btn:hover { background: var(--color-bg-hover); }
+        .btn-primary { background: var(--color-primary); border-color: var(--color-primary); color: white; }
+        .btn-primary:hover { background: var(--color-primary-hover); }
+        .btn-danger { background: var(--color-danger); border-color: var(--color-danger); color: white; }
+        .btn-danger:hover { background: var(--color-danger-hover); }
+        .btn-small { padding: 4px 8px; font-size: 12px; }
+        .btn:disabled { opacity: 0.6; cursor: not-allowed; }
+
+        table { width: 100%; border-collapse: collapse; }
+        th, td { padding: 12px; text-align: left; border-bottom: 1px solid var(--color-border-light); }
+        th { font-weight: 600; background: var(--color-bg-muted); }
+        tr:hover { background: var(--color-bg-muted); }
+
+        .error { background: var(--color-bg-error); color: var(--color-text-error); padding: 10px; border-radius: 4px; margin-bottom: 20px; }
+        .tag { display: inline-block; background: var(--color-tag-bg); padding: 2px 8px; border-radius: 12px; font-size: 12px; color: var(--color-text-muted); }
+
+        .add-form { display: flex; gap: 10px; margin-top: 15px; flex-wrap: wrap; }
+        .add-form select, .add-form input { padding: 8px; border: 1px solid var(--color-border); border-radius: 4px; min-width: 200px; background: var(--color-bg-card); color: var(--color-text); }
+
+        .form-group { margin-bottom: 20px; }
+        .form-group label { display: block; font-weight: 500; margin-bottom: 5px; }
+        .form-group input, .form-group textarea, .form-group select { width: 100%; padding: 10px; border: 1px solid var(--color-border); border-radius: 4px; font-size: 14px; background: var(--color-bg-card); color: var(--color-text); }
+        .form-group textarea { resize: vertical; }
+        .form-row { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }
+        .checkbox-group { display: flex; flex-wrap: wrap; gap: 15px; }
+        .checkbox-label { display: flex; align-items: center; gap: 5px; cursor: pointer; }
+        .form-actions { display: flex; gap: 10px; margin-top: 30px; padding-top: 20px; border-top: 1px solid var(--color-border-light); }
+
+        .need-form { background: var(--color-bg-muted); padding: 20px; border-radius: 4px; margin-bottom: 20px; }
+        .need-items { list-style: none; padding: 0; }
+        .need-items li { display: flex; justify-content: space-between; align-items: flex-start; padding: 15px; border: 1px solid var(--color-border-light); border-radius: 4px; margin-bottom: 10px; }
+        .need-info p { margin: 5px 0 0; color: var(--color-text-muted); font-size: 14px; }
+
+        .graph-container { width: 100%; }
+        .graph-hint { color: var(--color-text-muted); font-size: 14px; margin-bottom: 15px; }
+        .selected-info { margin-top: 15px; padding: 15px; background: var(--color-bg-muted); border-radius: 8px; }
+        .selected-info h3 { margin: 0 0 10px; }
+        .selected-info p { margin: 5px 0; color: var(--color-text-muted); }
+        .legend { margin-top: 20px; padding: 15px; background: var(--color-bg-muted); border-radius: 8px; }
+        .legend h4 { margin: 0 0 10px; font-size: 14px; }
+        .legend-items { display: flex; flex-wrap: wrap; gap: 15px; }
+        .legend-item { display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--color-text-muted); }
+        .legend-line { width: 30px; border-radius: 2px; }
+
+        .id-card { width: 100%; }
+        .id-card-inner { background: linear-gradient(135deg, #0a0a0f 0%, #1a1a2e 50%, #0a0a0f 100%); background-image: radial-gradient(white 1px, transparent 1px), linear-gradient(135deg, #0a0a0f 0%, #1a1a2e 50%, #0a0a0f 100%); background-size: 50px 50px, 100% 100%; color: #fff; border-radius: 12px; padding: 25px; min-height: 500px; position: relative; overflow: hidden; }
+        .id-card-header { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 15px; }
+        .id-card-header-left { flex: 1; }
+        .id-card-header-right { display: flex; flex-direction: column; align-items: flex-end; gap: 10px; }
+        .id-card-title { font-size: 2.5rem; font-weight: 700; margin: 0; color: #fff; text-shadow: 2px 2px 4px rgba(0,0,0,0.5); }
+        .id-profile-pic { width: 80px; height: 80px; border-radius: 8px; object-fit: cover; border: 2px solid rgba(255,255,255,0.3); }
+        .id-profile-placeholder { width: 80px; height: 80px; border-radius: 8px; background: linear-gradient(135deg, #4ecdc4 0%, #44a8a0 100%); display: flex; align-items: center; justify-content: center; border: 2px solid rgba(255,255,255,0.3); }
+        .id-profile-placeholder span { font-size: 2rem; font-weight: 700; color: #fff; text-shadow: 1px 1px 2px rgba(0,0,0,0.3); }
+        .id-card-actions { display: flex; gap: 8px; }
+        .id-card-actions .btn { background: rgba(255,255,255,0.1); border-color: rgba(255,255,255,0.3); color: #fff; }
+        .id-card-actions .btn:hover { background: rgba(255,255,255,0.2); }
+        .id-card-body { display: grid; grid-template-columns: 1fr 1.5fr; gap: 30px; }
+        .id-card-left { display: flex; flex-direction: column; gap: 8px; }
+        .id-field { font-size: 1rem; line-height: 1.4; }
+        .id-field-block { margin-top: 15px; font-size: 0.95rem; line-height: 1.5; }
+        .id-label { color: #4ecdc4; font-weight: 500; }
+        .id-card-right { display: flex; flex-direction: column; gap: 20px; }
+        .id-bio { font-size: 0.9rem; line-height: 1.6; color: #e0e0e0; }
+        .id-relationships { margin-top: 10px; }
+        .id-section-title { font-size: 1.5rem; margin: 0 0 15px; color: #fff; border-bottom: 1px solid rgba(255,255,255,0.2); padding-bottom: 8px; }
+        .id-rel-group { margin-bottom: 12px; font-size: 0.9rem; line-height: 1.6; }
+        .id-rel-label { color: #a0a0a0; }
+        .id-rel-group a { color: #4ecdc4; text-decoration: none; }
+        .id-rel-group a:hover { text-decoration: underline; }
+        .id-rel-type { color: #888; font-size: 0.85em; }
+        .id-card-warnings { margin-top: 30px; padding-top: 20px; border-top: 1px solid rgba(255,255,255,0.2); display: flex; flex-wrap: wrap; gap: 20px; }
+        .id-warning { display: flex; align-items: center; gap: 8px; font-size: 0.9rem; color: #ff6b6b; }
+        .warning-dot { width: 8px; height: 8px; background: #ff6b6b; border-radius: 50%; flex-shrink: 0; }
+        .warning-desc { color: #ccc; }
+
+        .id-card-manage { margin-top: 20px; background: var(--color-bg-muted); border-radius: 8px; padding: 15px; }
+        .id-card-manage summary { cursor: pointer; font-weight: 600; font-size: 1.1rem; padding: 5px 0; }
+        .id-card-manage[open] summary { margin-bottom: 15px; border-bottom: 1px solid var(--color-border-light); padding-bottom: 10px; }
+        .manage-section { margin-bottom: 25px; }
+        .manage-section h3 { margin: 0 0 15px; font-size: 1rem; }
+        .manage-relationships { display: flex; flex-direction: column; gap: 10px; margin-bottom: 15px; }
+        .manage-rel-item { display: flex; align-items: center; gap: 12px; padding: 10px; background: var(--color-bg-card); border-radius: 6px; flex-wrap: wrap; }
+        .manage-rel-item a { font-weight: 500; min-width: 120px; }
+        .weight-control { display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--color-text-muted); }
+        .weight-control input[type="range"] { width: 80px; cursor: pointer; }
+        .weight-value { min-width: 20px; text-align: center; font-weight: 600; }
+        .manage-needs-list { list-style: none; padding: 0; margin: 0 0 15px; }
+        .manage-needs-list li { display: flex; align-items: center; gap: 12px; padding: 10px; background: var(--color-bg-card); border-radius: 6px; margin-bottom: 8px; }
+        .manage-needs-list li .btn { margin-left: auto; }
+
+        .htmx-indicator { display: none; }
+        .htmx-request .htmx-indicator { display: inline; }
+        .htmx-request.htmx-indicator { display: inline; }
+
+        @media (max-width: 768px) {
+            .id-card-body { grid-template-columns: 1fr; }
+            .id-card-title { font-size: 1.8rem; }
+            .id-card-header { flex-direction: column; gap: 15px; }
+        }
+    </style>
+</head>
+<body>
+    <div class="app">
+        <nav>
+            <a href="/contacts">Contacts</a>
+            <a href="/graph">Graph</a>
+            <a href="/needs">Needs</a>
+            <button class="btn btn-small theme-toggle" onclick="toggleTheme()">
+                <span id="theme-label">Dark</span>
+            </button>
+        </nav>
+
+        <main id="main-content">
+            {% block content %}{% endblock %}
+        </main>
+    </div>
+
+    <script>
+        function toggleTheme() {
+            const html = document.documentElement;
+            const current = html.getAttribute('data-theme');
+            const next = current === 'light' ? 'dark' : 'light';
+            html.setAttribute('data-theme', next);
+            localStorage.setItem('theme', next);
+            document.getElementById('theme-label').textContent = next === 'light' ? 'Dark' : 'Light';
+        }
+        (function() {
+            const saved = localStorage.getItem('theme') || 'light';
+            document.documentElement.setAttribute('data-theme', saved);
+            document.getElementById('theme-label').textContent = saved === 'light' ? 'Dark' : 'Light';
+        })();
+    </script>
+</body>
+</html>

python/api/templates/contact_detail.html

@@ -0,0 +1,204 @@
+{% extends "base.html" %}
+{% block title %}{{ contact.name }}{% endblock %}
+{% block content %}
+<div class="id-card">
+    <div class="id-card-inner">
+        <div class="id-card-header">
+            <div class="id-card-header-left">
+                <h1 class="id-card-title">I.D.: {{ contact.name }}</h1>
+            </div>
+            <div class="id-card-header-right">
+                {% if contact.profile_pic %}
+                <img src="{{ contact.profile_pic }}" alt="{{ contact.name }}'s profile" class="id-profile-pic">
+                {% else %}
+                <div class="id-profile-placeholder">
+                    <span>{{ contact.name[0]|upper }}</span>
+                </div>
+                {% endif %}
+                <div class="id-card-actions">
+                    <a href="/contacts/{{ contact.id }}/edit" class="btn btn-small">Edit</a>
+                    <a href="/contacts" class="btn btn-small">Back</a>
+                </div>
+            </div>
+        </div>
+
+        <div class="id-card-body">
+            <div class="id-card-left">
+                {% if contact.legal_name %}
+                <div class="id-field">Legal name: {{ contact.legal_name }}</div>
+                {% endif %}
+                {% if contact.suffix %}
+                <div class="id-field">Suffix: {{ contact.suffix }}</div>
+                {% endif %}
+                {% if contact.gender %}
+                <div class="id-field">Gender: {{ contact.gender }}</div>
+                {% endif %}
+                {% if contact.age %}
+                <div class="id-field">Age: {{ contact.age }}</div>
+                {% endif %}
+                {% if contact.current_job %}
+                <div class="id-field">Job: {{ contact.current_job }}</div>
+                {% endif %}
+                {% if contact.social_structure_style %}
+                <div class="id-field">Social style: {{ contact.social_structure_style }}</div>
+                {% endif %}
+                {% if contact.self_sufficiency_score is not none %}
+                <div class="id-field">Self-Sufficiency: {{ contact.self_sufficiency_score }}</div>
+                {% endif %}
+                {% if contact.timezone %}
+                <div class="id-field">Timezone: {{ contact.timezone }}</div>
+                {% endif %}
+                {% if contact.safe_conversation_starters %}
+                <div class="id-field-block">
+                    <span class="id-label">Safe con starters:</span> {{ contact.safe_conversation_starters }}
+                </div>
+                {% endif %}
+                {% if contact.topics_to_avoid %}
+                <div class="id-field-block">
+                    <span class="id-label">Topics to avoid:</span> {{ contact.topics_to_avoid }}
+                </div>
+                {% endif %}
+                {% if contact.goals %}
+                <div class="id-field-block">
+                    <span class="id-label">Goals:</span> {{ contact.goals }}
+                </div>
+                {% endif %}
+            </div>
+
+            <div class="id-card-right">
+                {% if contact.bio %}
+                <div class="id-bio">
+                    <span class="id-label">Bio:</span> {{ contact.bio }}
+                </div>
+                {% endif %}
+
+                <div class="id-relationships">
+                    <h2 class="id-section-title">Relationships</h2>
+
+                    {% if grouped_relationships.familial %}
+                    <div class="id-rel-group">
+                        <span class="id-rel-label">Familial:</span>
+                        {% for rel in grouped_relationships.familial %}
+                        <a href="/contacts/{{ rel.related_contact_id }}">{{ contact_names[rel.related_contact_id] }}</a><span class="id-rel-type">({{ rel.relationship_type|replace("_", " ")|title }})</span>{% if not loop.last %}, {% endif %}
+                        {% endfor %}
+                    </div>
+                    {% endif %}
+
+                    {% if grouped_relationships.partners %}
+                    <div class="id-rel-group">
+                        <span class="id-rel-label">Partners:</span>
+                        {% for rel in grouped_relationships.partners %}
+                        <a href="/contacts/{{ rel.related_contact_id }}">{{ contact_names[rel.related_contact_id] }}</a>{% if not loop.last %}, {% endif %}
+                        {% endfor %}
+                    </div>
+                    {% endif %}
+
+                    {% if grouped_relationships.friends %}
+                    <div class="id-rel-group">
+                        <span class="id-rel-label">Friends:</span>
+                        {% for rel in grouped_relationships.friends %}
+                        <a href="/contacts/{{ rel.related_contact_id }}">{{ contact_names[rel.related_contact_id] }}</a>{% if not loop.last %}, {% endif %}
+                        {% endfor %}
+                    </div>
+                    {% endif %}
+
+                    {% if grouped_relationships.professional %}
+                    <div class="id-rel-group">
+                        <span class="id-rel-label">Professional:</span>
+                        {% for rel in grouped_relationships.professional %}
+                        <a href="/contacts/{{ rel.related_contact_id }}">{{ contact_names[rel.related_contact_id] }}</a><span class="id-rel-type">({{ rel.relationship_type|replace("_", " ")|title }})</span>{% if not loop.last %}, {% endif %}
+                        {% endfor %}
+                    </div>
+                    {% endif %}
+
+                    {% if grouped_relationships.other %}
+                    <div class="id-rel-group">
+                        <span class="id-rel-label">Other:</span>
+                        {% for rel in grouped_relationships.other %}
+                        <a href="/contacts/{{ rel.related_contact_id }}">{{ contact_names[rel.related_contact_id] }}</a><span class="id-rel-type">({{ rel.relationship_type|replace("_", " ")|title }})</span>{% if not loop.last %}, {% endif %}
+                        {% endfor %}
+                    </div>
+                    {% endif %}
+
+                    {% if contact.related_from %}
+                    <div class="id-rel-group">
+                        <span class="id-rel-label">Known by:</span>
+                        {% for rel in contact.related_from %}
+                        <a href="/contacts/{{ rel.contact_id }}">{{ contact_names[rel.contact_id] }}</a>{% if not loop.last %}, {% endif %}
+                        {% endfor %}
+                    </div>
+                    {% endif %}
+                </div>
+            </div>
+        </div>
+
+        {% if contact.needs %}
+        <div class="id-card-warnings">
+            {% for need in contact.needs %}
+            <div class="id-warning">
+                <span class="warning-dot"></span>
+                Warning: {{ need.name }}
+                {% if need.description %}<span class="warning-desc"> - {{ need.description }}</span>{% endif %}
+            </div>
+            {% endfor %}
+        </div>
+        {% endif %}
+    </div>
+
+    <details class="id-card-manage">
+        <summary>Manage Contact</summary>
+
+        <div class="manage-section">
+            <h3>Manage Relationships</h3>
+            <div id="manage-relationships" class="manage-relationships">
+                {% include "partials/manage_relationships.html" %}
+            </div>
+
+            {% if all_contacts %}
+            <form hx-post="/htmx/contacts/{{ contact.id }}/add-relationship"
+                  hx-target="#manage-relationships"
+                  hx-swap="innerHTML"
+                  class="add-form">
+                <select name="related_contact_id" required>
+                    <option value="">Select contact...</option>
+                    {% for other in all_contacts %}
+                    {% if other.id != contact.id %}
+                    <option value="{{ other.id }}">{{ other.name }}</option>
+                    {% endif %}
+                    {% endfor %}
+                </select>
+                <select name="relationship_type" required>
+                    <option value="">Select relationship type...</option>
+                    {% for rel_type in relationship_types %}
+                    <option value="{{ rel_type.value }}">{{ rel_type.display_name }}</option>
+                    {% endfor %}
+                </select>
+                <button type="submit" class="btn btn-primary">Add Relationship</button>
+            </form>
+            {% endif %}
+        </div>
+
+        <div class="manage-section">
+            <h3>Manage Needs/Warnings</h3>
+            <div id="manage-needs">
+                {% include "partials/manage_needs.html" %}
+            </div>
+
+            {% if available_needs %}
+            <form hx-post="/htmx/contacts/{{ contact.id }}/add-need"
+                  hx-target="#manage-needs"
+                  hx-swap="innerHTML"
+                  class="add-form">
+                <select name="need_id" required>
+                    <option value="">Select a need...</option>
+                    {% for need in available_needs %}
+                    <option value="{{ need.id }}">{{ need.name }}</option>
+                    {% endfor %}
+                </select>
+                <button type="submit" class="btn btn-primary">Add Need</button>
+            </form>
+            {% endif %}
+        </div>
+    </details>
+</div>
+{% endblock %}

python/api/templates/contact_form.html

@@ -0,0 +1,115 @@
+{% extends "base.html" %}
+{% block title %}{{ "Edit " + contact.name if contact else "New Contact" }}{% endblock %}
+{% block content %}
+<div class="contact-form">
+    <h1>{{ "Edit Contact" if contact else "New Contact" }}</h1>
+
+    {% if contact %}
+    <form method="post" action="/htmx/contacts/{{ contact.id }}/edit">
+    {% else %}
+    <form method="post" action="/htmx/contacts/new">
+    {% endif %}
+
+        <div class="form-group">
+            <label for="name">Name *</label>
+            <input id="name" name="name" type="text" value="{{ contact.name if contact else '' }}" required>
+        </div>
+
+        <div class="form-row">
+            <div class="form-group">
+                <label for="legal_name">Legal Name</label>
+                <input id="legal_name" name="legal_name" type="text" value="{{ contact.legal_name or '' }}">
+            </div>
+            <div class="form-group">
+                <label for="suffix">Suffix</label>
+                <input id="suffix" name="suffix" type="text" value="{{ contact.suffix or '' }}">
+            </div>
+        </div>
+
+        <div class="form-row">
+            <div class="form-group">
+                <label for="age">Age</label>
+                <input id="age" name="age" type="number" value="{{ contact.age if contact and contact.age is not none else '' }}">
+            </div>
+            <div class="form-group">
+                <label for="gender">Gender</label>
+                <input id="gender" name="gender" type="text" value="{{ contact.gender or '' }}">
+            </div>
+        </div>
+
+        <div class="form-group">
+            <label for="current_job">Current Job</label>
+            <input id="current_job" name="current_job" type="text" value="{{ contact.current_job or '' }}">
+        </div>
+
+        <div class="form-group">
+            <label for="timezone">Timezone</label>
+            <input id="timezone" name="timezone" type="text" value="{{ contact.timezone or '' }}">
+        </div>
+
+        <div class="form-group">
+            <label for="profile_pic">Profile Picture URL</label>
+            <input id="profile_pic" name="profile_pic" type="url" placeholder="https://example.com/photo.jpg" value="{{ contact.profile_pic or '' }}">
+        </div>
+
+        <div class="form-group">
+            <label for="bio">Bio</label>
+            <textarea id="bio" name="bio" rows="3">{{ contact.bio or '' }}</textarea>
+        </div>
+
+        <div class="form-group">
+            <label for="goals">Goals</label>
+            <textarea id="goals" name="goals" rows="3">{{ contact.goals or '' }}</textarea>
+        </div>
+
+        <div class="form-group">
+            <label for="social_structure_style">Social Structure Style</label>
+            <input id="social_structure_style" name="social_structure_style" type="text" value="{{ contact.social_structure_style or '' }}">
+        </div>
+
+        <div class="form-group">
+            <label for="self_sufficiency_score">Self-Sufficiency Score (1-10)</label>
+            <input id="self_sufficiency_score" name="self_sufficiency_score" type="number" min="1" max="10" value="{{ contact.self_sufficiency_score if contact and contact.self_sufficiency_score is not none else '' }}">
+        </div>
+
+        <div class="form-group">
+            <label for="safe_conversation_starters">Safe Conversation Starters</label>
+            <textarea id="safe_conversation_starters" name="safe_conversation_starters" rows="2">{{ contact.safe_conversation_starters or '' }}</textarea>
+        </div>
+
+        <div class="form-group">
+            <label for="topics_to_avoid">Topics to Avoid</label>
+            <textarea id="topics_to_avoid" name="topics_to_avoid" rows="2">{{ contact.topics_to_avoid or '' }}</textarea>
+        </div>
+
+        <div class="form-group">
+            <label for="ssn">SSN</label>
+            <input id="ssn" name="ssn" type="text" value="{{ contact.ssn or '' }}">
+        </div>
+
+        {% if all_needs %}
+        <div class="form-group">
+            <label>Needs/Accommodations</label>
+            <div class="checkbox-group">
+                {% for need in all_needs %}
+                <label class="checkbox-label">
+                    <input type="checkbox" name="need_ids" value="{{ need.id }}"
+                           {% if contact and need in contact.needs %}checked{% endif %}>
+                    {{ need.name }}
+                </label>
+                {% endfor %}
+            </div>
+        </div>
+        {% endif %}
+
+        <div class="form-actions">
+            <button type="submit" class="btn btn-primary">Save</button>
+            {% if contact %}
+            <a href="/contacts/{{ contact.id }}" class="btn">Cancel</a>
+            {% else %}
+            <a href="/contacts" class="btn">Cancel</a>
+            {% endif %}
+        </div>
+    </form>
+</div>
+{% endblock %}

python/api/templates/contact_list.html

@@ -0,0 +1,14 @@
+{% extends "base.html" %}
+{% block title %}Contacts{% endblock %}
+{% block content %}
+<div class="contact-list">
+    <div class="header">
+        <h1>Contacts</h1>
+        <a href="/contacts/new" class="btn btn-primary">Add Contact</a>
+    </div>
+
+    <div id="contact-table">
+        {% include "partials/contact_table.html" %}
+    </div>
+</div>
+{% endblock %}

python/api/templates/graph.html

@@ -0,0 +1,198 @@
+{% extends "base.html" %}
+{% block title %}Relationship Graph{% endblock %}
+{% block content %}
+<div class="graph-container">
+    <div class="header">
+        <h1>Relationship Graph</h1>
+    </div>
+    <p class="graph-hint">Drag nodes to reposition. Closer relationships have shorter, darker edges.</p>
+    <canvas id="graph-canvas" width="900" height="600"
+            style="border: 1px solid var(--color-border); border-radius: 8px; background: var(--color-bg); cursor: grab;">
+    </canvas>
+    <div id="selected-info"></div>
+    <div class="legend">
+        <h4>Relationship Closeness (1-10)</h4>
+        <div class="legend-items">
+            <div class="legend-item">
+                <span class="legend-line" style="background: hsl(220, 70%, 40%); height: 4px; display: inline-block;"></span>
+                <span>10 - Very Close (Spouse, Partner)</span>
+            </div>
+            <div class="legend-item">
+                <span class="legend-line" style="background: hsl(220, 70%, 52%); height: 3px; display: inline-block;"></span>
+                <span>7 - Close (Family, Best Friend)</span>
+            </div>
+            <div class="legend-item">
+                <span class="legend-line" style="background: hsl(220, 70%, 64%); height: 2px; display: inline-block;"></span>
+                <span>4 - Moderate (Friend, Colleague)</span>
+            </div>
+            <div class="legend-item">
+                <span class="legend-line" style="background: hsl(220, 70%, 72%); height: 1px; display: inline-block;"></span>
+                <span>2 - Distant (Acquaintance)</span>
+            </div>
+        </div>
+    </div>
+</div>
+
+<script>
+(function() {
+    const RELATIONSHIP_DISPLAY = {{ relationship_type_display|tojson }};
+    const graphData = {{ graph_data|tojson }};
+
+    const canvas = document.getElementById('graph-canvas');
+    const ctx = canvas.getContext('2d');
+    const width = canvas.width;
+    const height = canvas.height;
+    const centerX = width / 2;
+    const centerY = height / 2;
+
+    const nodes = graphData.nodes.map(function(node) {
+        return Object.assign({}, node, {
+            x: centerX + (Math.random() - 0.5) * 300,
+            y: centerY + (Math.random() - 0.5) * 300,
+            vx: 0,
+            vy: 0
+        });
+    });
+
+    const nodeMap = new Map(nodes.map(function(node) { return [node.id, node]; }));
+
+    const edges = graphData.edges.map(function(edge) {
+        const sourceNode = nodeMap.get(edge.source);
+        const targetNode = nodeMap.get(edge.target);
+        if (!sourceNode || !targetNode) return null;
+        return Object.assign({}, edge, { sourceNode: sourceNode, targetNode: targetNode });
+    }).filter(function(edge) { return edge !== null; });
+
+    let dragNode = null;
+    let selectedNode = null;
+
+    const repulsion = 5000;
+    const springStrength = 0.05;
+    const baseSpringLength = 150;
+    const damping = 0.9;
+    const centerPull = 0.01;
+
+    function simulate() {
+        for (const node of nodes) { node.vx = 0; node.vy = 0; }
+        for (let i = 0; i < nodes.length; i++) {
+            for (let j = i + 1; j < nodes.length; j++) {
+                const dx = nodes[j].x - nodes[i].x;
+                const dy = nodes[j].y - nodes[i].y;
+                const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+                const force = repulsion / (dist * dist);
+                const fx = (dx / dist) * force;
+                const fy = (dy / dist) * force;
+                nodes[i].vx -= fx; nodes[i].vy -= fy;
+                nodes[j].vx += fx; nodes[j].vy += fy;
+            }
+        }
+        for (const edge of edges) {
+            const dx = edge.targetNode.x - edge.sourceNode.x;
+            const dy = edge.targetNode.y - edge.sourceNode.y;
+            const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+            const normalizedWeight = edge.closeness_weight / 10;
+            const idealLength = baseSpringLength * (1.5 - normalizedWeight);
+            const displacement = dist - idealLength;
+            const force = springStrength * displacement;
+            const fx = (dx / dist) * force;
+            const fy = (dy / dist) * force;
+            edge.sourceNode.vx += fx; edge.sourceNode.vy += fy;
+            edge.targetNode.vx -= fx; edge.targetNode.vy -= fy;
+        }
+        for (const node of nodes) {
+            node.vx += (centerX - node.x) * centerPull;
+            node.vy += (centerY - node.y) * centerPull;
+        }
+        for (const node of nodes) {
+            if (node === dragNode) continue;
+            node.x += node.vx * damping;
+            node.y += node.vy * damping;
+            node.x = Math.max(30, Math.min(width - 30, node.x));
+            node.y = Math.max(30, Math.min(height - 30, node.y));
+        }
+    }
+
+    function getEdgeColor(weight) {
+        const normalized = weight / 10;
+        return 'hsl(220, 70%, ' + (80 - normalized * 40) + '%)';
+    }
+
+    function draw() {
+        ctx.clearRect(0, 0, width, height);
+        for (const edge of edges) {
+            const lineWidth = 1 + (edge.closeness_weight / 10) * 3;
+            ctx.strokeStyle = getEdgeColor(edge.closeness_weight);
+            ctx.lineWidth = lineWidth;
+            ctx.beginPath();
+            ctx.moveTo(edge.sourceNode.x, edge.sourceNode.y);
+            ctx.lineTo(edge.targetNode.x, edge.targetNode.y);
+            ctx.stroke();
+            const midX = (edge.sourceNode.x + edge.targetNode.x) / 2;
+            const midY = (edge.sourceNode.y + edge.targetNode.y) / 2;
+            ctx.fillStyle = '#666';
+            ctx.font = '10px sans-serif';
+            ctx.textAlign = 'center';
+            const label = RELATIONSHIP_DISPLAY[edge.relationship_type] || edge.relationship_type;
+            ctx.fillText(label, midX, midY - 5);
+        }
+        for (const node of nodes) {
+            const isSelected = node === selectedNode;
+            const radius = isSelected ? 25 : 20;
+            ctx.beginPath();
+            ctx.arc(node.x, node.y, radius, 0, Math.PI * 2);
+            ctx.fillStyle = isSelected ? '#0066cc' : '#fff';
+            ctx.fill();
+            ctx.strokeStyle = '#0066cc';
+            ctx.lineWidth = 2;
+            ctx.stroke();
+            ctx.fillStyle = isSelected ? '#fff' : '#333';
+            ctx.font = '12px sans-serif';
+            ctx.textAlign = 'center';
+            ctx.textBaseline = 'middle';
+            const name = node.name.length > 10 ? node.name.slice(0, 9) + '\u2026' : node.name;
+            ctx.fillText(name, node.x, node.y);
+        }
+    }
+
+    function animate() {
+        simulate();
+        draw();
+        requestAnimationFrame(animate);
+    }
+    animate();
+
+    function getNodeAt(x, y) {
+        for (const node of nodes) {
+            const dx = x - node.x;
+            const dy = y - node.y;
+            if (dx * dx + dy * dy < 400) return node;
+        }
+        return null;
+    }
+
+    canvas.addEventListener('mousedown', function(event) {
+        const rect = canvas.getBoundingClientRect();
+        const node = getNodeAt(event.clientX - rect.left, event.clientY - rect.top);
+        if (node) {
+            dragNode = node;
+            selectedNode = node;
+            const infoDiv = document.getElementById('selected-info');
+            let html = '<div class="selected-info"><h3>' + node.name + '</h3>';
+            if (node.current_job) html += '<p>Job: ' + node.current_job + '</p>';
+            html += '<a href="/contacts/' + node.id + '">View details</a></div>';
+            infoDiv.innerHTML = html;
+        }
+    });
+
+    canvas.addEventListener('mousemove', function(event) {
+        if (!dragNode) return;
+        const rect = canvas.getBoundingClientRect();
+        dragNode.x = event.clientX - rect.left;
+        dragNode.y = event.clientY - rect.top;
+    });
+
+    canvas.addEventListener('mouseup', function() { dragNode = null; });
+    canvas.addEventListener('mouseleave', function() { dragNode = null; });
+})();
+</script>
+{% endblock %}

python/api/templates/need_list.html

@@ -0,0 +1,31 @@
+{% extends "base.html" %}
+{% block title %}Needs{% endblock %}
+{% block content %}
+<div class="need-list">
+    <div class="header">
+        <h1>Needs / Accommodations</h1>
+        <button class="btn btn-primary" onclick="document.getElementById('need-form').toggleAttribute('hidden')">Add Need</button>
+    </div>
+
+    <form id="need-form" hidden
+          hx-post="/htmx/needs"
+          hx-target="#need-items"
+          hx-swap="innerHTML"
+          hx-on::after-request="if(event.detail.successful) this.reset()"
+          class="need-form">
+        <div class="form-group">
+            <label for="name">Name *</label>
+            <input id="name" name="name" type="text" placeholder="e.g., Light Sensitive, ADHD" required>
+        </div>
+        <div class="form-group">
+            <label for="description">Description</label>
+            <textarea id="description" name="description" placeholder="Optional description..." rows="2"></textarea>
+        </div>
+        <button type="submit" class="btn btn-primary">Create</button>
+    </form>
+
+    <div id="need-items">
+        {% include "partials/need_items.html" %}
+    </div>
+</div>
+{% endblock %}

python/api/templates/partials/contact_table.html

@@ -0,0 +1,33 @@
+{% if contacts %}
+<table>
+    <thead>
+        <tr>
+            <th>Name</th>
+            <th>Job</th>
+            <th>Timezone</th>
+            <th>Actions</th>
+        </tr>
+    </thead>
+    <tbody>
+        {% for contact in contacts %}
+        <tr id="contact-row-{{ contact.id }}">
+            <td><a href="/contacts/{{ contact.id }}">{{ contact.name }}</a></td>
+            <td>{{ contact.current_job or "-" }}</td>
+            <td>{{ contact.timezone or "-" }}</td>
+            <td>
+                <a href="/contacts/{{ contact.id }}/edit" class="btn">Edit</a>
+                <button class="btn btn-danger"
+                        hx-delete="/api/contacts/{{ contact.id }}"
+                        hx-target="#contact-row-{{ contact.id }}"
+                        hx-swap="outerHTML"
+                        hx-confirm="Delete this contact?">
+                    Delete
+                </button>
+            </td>
+        </tr>
+        {% endfor %}
+    </tbody>
+</table>
+{% else %}
+<p>No contacts yet.</p>
+{% endif %}

python/api/templates/partials/manage_needs.html

@@ -0,0 +1,14 @@
+<ul class="manage-needs-list">
+    {% for need in contact.needs %}
+    <li id="contact-need-{{ need.id }}">
+        <strong>{{ need.name }}</strong>
+        {% if need.description %}<span> - {{ need.description }}</span>{% endif %}
+        <button class="btn btn-small btn-danger"
+                hx-delete="/api/contacts/{{ contact.id }}/needs/{{ need.id }}"
+                hx-target="#contact-need-{{ need.id }}"
+                hx-swap="outerHTML">
+            Remove
+        </button>
+    </li>
+    {% endfor %}
+</ul>

python/api/templates/partials/manage_relationships.html

@@ -0,0 +1,23 @@
+{% for rel in contact.related_to %}
+<div class="manage-rel-item" id="rel-{{ contact.id }}-{{ rel.related_contact_id }}">
+    <a href="/contacts/{{ rel.related_contact_id }}">{{ contact_names[rel.related_contact_id] }}</a>
+    <span class="tag">{{ rel.relationship_type|replace("_", " ")|title }}</span>
+    <label class="weight-control">
+        <span>Closeness:</span>
+        <input type="range" min="1" max="10" value="{{ rel.closeness_weight }}"
+               hx-post="/htmx/contacts/{{ contact.id }}/relationships/{{ rel.related_contact_id }}/weight"
+               hx-trigger="change"
+               hx-include="this"
+               name="closeness_weight"
+               hx-swap="none"
+               oninput="this.nextElementSibling.textContent = this.value">
+        <span class="weight-value">{{ rel.closeness_weight }}</span>
+    </label>
+    <button class="btn btn-small btn-danger"
+            hx-delete="/api/contacts/{{ contact.id }}/relationships/{{ rel.related_contact_id }}"
+            hx-target="#rel-{{ contact.id }}-{{ rel.related_contact_id }}"
+            hx-swap="outerHTML">
+        Remove
+    </button>
+</div>
+{% endfor %}

python/api/templates/partials/need_items.html

@@ -0,0 +1,21 @@
+{% if needs %}
+<ul class="need-items">
+    {% for need in needs %}
+    <li id="need-item-{{ need.id }}">
+        <div class="need-info">
+            <strong>{{ need.name }}</strong>
+            {% if need.description %}<p>{{ need.description }}</p>{% endif %}
+        </div>
+        <button class="btn btn-danger"
+                hx-delete="/api/needs/{{ need.id }}"
+                hx-target="#need-item-{{ need.id }}"
+                hx-swap="outerHTML"
+                hx-confirm="Delete this need?">
+            Delete
+        </button>
+    </li>
+    {% endfor %}
+</ul>
+{% else %}
+<p>No needs defined yet.</p>
+{% endif %}

python/database_cli.py

@@ -0,0 +1,115 @@
+"""CLI wrapper around alembic for multi-database support.
+
+Usage:
+    database <db_name> <command> [args...]
+
+Examples:
+    database van_inventory upgrade head
+    database van_inventory downgrade head-1
+    database van_inventory revision --autogenerate -m "add meals table"
+    database van_inventory check
+    database richie check
+    database richie upgrade head
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import import_module
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from alembic.config import CommandLine, Config
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import DeclarativeBase
+
+
+@dataclass(frozen=True)
+class DatabaseConfig:
+    """Configuration for a database."""
+
+    env_prefix: str
+    version_location: str
+    base_module: str
+    base_class_name: str
+    models_module: str
+    script_location: str = "python/alembic"
+    file_template: str = "%%(year)d_%%(month).2d_%%(day).2d-%%(slug)s_%%(rev)s"
+
+    def get_base(self) -> type[DeclarativeBase]:
+        """Import and return the Base class."""
+        module = import_module(self.base_module)
+        return getattr(module, self.base_class_name)
+
+    def import_models(self) -> None:
+        """Import ORM models so alembic autogenerate can detect them."""
+        import_module(self.models_module)
+
+    def alembic_config(self) -> Config:
+        """Build an alembic Config for this database."""
+        # Runtime import needed — Config is in TYPE_CHECKING for the return type annotation
+        from alembic.config import Config as AlembicConfig  # noqa: PLC0415
+
+        cfg = AlembicConfig()
+        cfg.set_main_option("script_location", self.script_location)
+        cfg.set_main_option("file_template", self.file_template)
+        cfg.set_main_option("prepend_sys_path", ".")
+        cfg.set_main_option("version_path_separator", "os")
+        cfg.set_main_option("version_locations", self.version_location)
+        cfg.set_main_option("revision_environment", "true")
+        cfg.set_section_option("post_write_hooks", "hooks", "dynamic_schema,import_postgresql,ruff")
+        cfg.set_section_option("post_write_hooks", "dynamic_schema.type", "dynamic_schema")
+        cfg.set_section_option("post_write_hooks", "import_postgresql.type", "import_postgresql")
+        cfg.set_section_option("post_write_hooks", "ruff.type", "ruff")
+        cfg.attributes["base"] = self.get_base()
+        cfg.attributes["env_prefix"] = self.env_prefix
+        self.import_models()
+        return cfg
+
+
+DATABASES: dict[str, DatabaseConfig] = {
+    "richie": DatabaseConfig(
+        env_prefix="RICHIE",
+        version_location="python/alembic/richie/versions",
+        base_module="python.orm.richie.base",
+        base_class_name="RichieBase",
+        models_module="python.orm.richie",
+    ),
+    "van_inventory": DatabaseConfig(
+        env_prefix="VAN_INVENTORY",
+        version_location="python/alembic/van_inventory/versions",
+        base_module="python.orm.van_inventory.base",
+        base_class_name="VanInventoryBase",
+        models_module="python.orm.van_inventory.models",
+    ),
+}
+
+
+app = typer.Typer(help="Multi-database alembic wrapper.")
+
+
+@app.command(
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def main(
+    ctx: typer.Context,
+    db_name: Annotated[str, typer.Argument(help=f"Database name. Options: {', '.join(DATABASES)}")],
+    command: Annotated[str, typer.Argument(help="Alembic command (upgrade, downgrade, revision, check, etc.)")],
+) -> None:
+    """Run an alembic command against the specified database."""
+    db_config = DATABASES.get(db_name)
+    if not db_config:
+        typer.echo(f"Unknown database: {db_name!r}. Available: {', '.join(DATABASES)}", err=True)
+        raise typer.Exit(code=1)
+
+    alembic_cfg = db_config.alembic_config()
+
+    cmd_line = CommandLine()
+    options = cmd_line.parser.parse_args([command, *ctx.args])
+    cmd_line.run_cmd(alembic_cfg, options)
+
+
+if __name__ == "__main__":
+    app()
+

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/__init__.py

@@ -1,22 +1,9 @@
 """ORM package exports."""
 
-from __future__ import annotations
+from python.orm.richie.base import RichieBase
-
+from python.orm.van_inventory.base import VanInventoryBase
-from python.orm.base import RichieBase, TableBase
-from python.orm.contact import (
-    Contact,
-    ContactNeed,
-    ContactRelationship,
-    Need,
-    RelationshipType,
-)
 
 __all__ = [
-    "Contact",
-    "ContactNeed",
-    "ContactRelationship",
-    "Need",
-    "RelationshipType",
     "RichieBase",
-    "TableBase",
+    "VanInventoryBase",
 ]

python/orm/base.py

@@ -1,80 +0,0 @@
-"""Base ORM definitions."""
-
-from __future__ import annotations
-
-from datetime import datetime
-from os import getenv
-from typing import cast
-
-from sqlalchemy import DateTime, MetaData, create_engine, func
-from sqlalchemy.engine import URL, Engine
-from sqlalchemy.ext.declarative import AbstractConcreteBase
-from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
-
-
-class RichieBase(DeclarativeBase):
-    """Base class for all ORM models."""
-
-    schema_name = "main"
-
-    metadata = MetaData(
-        schema=schema_name,
-        naming_convention={
-            "ix": "ix_%(table_name)s_%(column_0_name)s",
-            "uq": "uq_%(table_name)s_%(column_0_name)s",
-            "ck": "ck_%(table_name)s_%(constraint_name)s",
-            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
-            "pk": "pk_%(table_name)s",
-        },
-    )
-
-
-class TableBase(AbstractConcreteBase, RichieBase):
-    """Abstract concrete base for tables with IDs and timestamps."""
-
-    __abstract__ = True
-
-    id: Mapped[int] = mapped_column(primary_key=True)
-    created: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        server_default=func.now(),
-    )
-    updated: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        server_default=func.now(),
-        onupdate=func.now(),
-    )
-
-
-def get_connection_info() -> tuple[str, str, str, str, str | None]:
-    """Get connection info from environment variables."""
-    database = getenv("POSTGRES_DB")
-    host = getenv("POSTGRES_HOST")
-    port = getenv("POSTGRES_PORT")
-    username = getenv("POSTGRES_USER")
-    password = getenv("POSTGRES_PASSWORD")
-
-    if None in (database, host, port, username):
-        error = f"Missing environment variables for Postgres connection.\n{database=}\n{host=}\n{port=}\n{username=}\n"
-        raise ValueError(error)
-    return cast("tuple[str, str, str, str, str | None]", (database, host, port, username, password))
-
-
-def get_postgres_engine(*, pool_pre_ping: bool = True) -> Engine:
-    """Create a SQLAlchemy engine from environment variables."""
-    database, host, port, username, password = get_connection_info()
-
-    url = URL.create(
-        drivername="postgresql+psycopg",
-        username=username,
-        password=password,
-        host=host,
-        port=int(port),
-        database=database,
-    )
-
-    return create_engine(
-        url=url,
-        pool_pre_ping=pool_pre_ping,
-        pool_recycle=1800,
-    )

python/orm/common.py

@@ -0,0 +1,51 @@
+"""Shared ORM definitions."""
+
+from __future__ import annotations
+
+from os import getenv
+from typing import cast
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import URL, Engine
+
+NAMING_CONVENTION = {
+    "ix": "ix_%(table_name)s_%(column_0_name)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+
+def get_connection_info(name: str) -> tuple[str, str, str, str, str | None]:
+    """Get connection info from environment variables."""
+    database = getenv(f"{name}_DB")
+    host = getenv(f"{name}_HOST")
+    port = getenv(f"{name}_PORT")
+    username = getenv(f"{name}_USER")
+    password = getenv(f"{name}_PASSWORD")
+
+    if None in (database, host, port, username):
+        error = f"Missing environment variables for Postgres connection.\n{database=}\n{host=}\n{port=}\n{username=}\n"
+        raise ValueError(error)
+    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."""
+    database, host, port, username, password = get_connection_info(name)
+
+    url = URL.create(
+        drivername="postgresql+psycopg",
+        username=username,
+        password=password,
+        host=host,
+        port=int(port),
+        database=database,
+    )
+
+    return create_engine(
+        url=url,
+        pool_pre_ping=pool_pre_ping,
+        pool_recycle=1800,
+    )

python/orm/richie/__init__.py

@@ -0,0 +1,28 @@
+"""Richie database ORM exports."""
+
+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,
+    ContactNeed,
+    ContactRelationship,
+    Need,
+    RelationshipType,
+)
+
+__all__ = [
+    "Audiobook",
+    "AudiobookAuthor",
+    "AudiobookSeries",
+    "Contact",
+    "ContactNeed",
+    "ContactRelationship",
+    "Need",
+    "RelationshipType",
+    "RichieBase",
+    "TableBase",
+    "TableBaseBig",
+    "TableBaseSmall",
+]

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/base.py

@@ -0,0 +1,60 @@
+"""Richie database ORM base."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import BigInteger, DateTime, MetaData, SmallInteger, func
+from sqlalchemy.ext.declarative import AbstractConcreteBase
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from python.orm.common import NAMING_CONVENTION
+
+
+class RichieBase(DeclarativeBase):
+    """Base class for richie database ORM models."""
+
+    schema_name = "main"
+
+    metadata = MetaData(
+        schema=schema_name,
+        naming_convention=NAMING_CONVENTION,
+    )
+
+
+class _TableMixin:
+    """Shared timestamp columns for all table bases."""
+
+    created: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+    )
+    updated: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+
+class TableBaseSmall(_TableMixin, AbstractConcreteBase, RichieBase):
+    """Table with SmallInteger primary key."""
+
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(SmallInteger, primary_key=True)
+
+
+class TableBase(_TableMixin, AbstractConcreteBase, RichieBase):
+    """Table with Integer primary key."""
+
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+
+
+class TableBaseBig(_TableMixin, AbstractConcreteBase, RichieBase):
+    """Table with BigInteger primary key."""
+
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)

python/orm/richie/contact.py

@@ -2,15 +2,15 @@
 
 from __future__ import annotations
 
-from enum import Enum
+from enum import StrEnum
 
 from sqlalchemy import ForeignKey, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
-from python.orm.base import RichieBase, TableBase
+from python.orm.richie.base import RichieBase, TableBase
 
 
-class RelationshipType(str, Enum):
+class RelationshipType(StrEnum):
     """Relationship types with default closeness weights.
 
     Default weight is an integer 1-10 where 10 = closest relationship.

python/orm/van_inventory/__init__.py

@@ -0,0 +1 @@
+"""Van inventory database ORM exports."""

python/orm/van_inventory/base.py

@@ -0,0 +1,39 @@
+"""Van inventory database ORM base."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, MetaData, func
+from sqlalchemy.ext.declarative import AbstractConcreteBase
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from python.orm.common import NAMING_CONVENTION
+
+
+class VanInventoryBase(DeclarativeBase):
+    """Base class for van_inventory database ORM models."""
+
+    schema_name = "main"
+
+    metadata = MetaData(
+        schema=schema_name,
+        naming_convention=NAMING_CONVENTION,
+    )
+
+
+class VanTableBase(AbstractConcreteBase, VanInventoryBase):
+    """Abstract concrete base for van_inventory tables with IDs and timestamps."""
+
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    created: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+    )
+    updated: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )

python/orm/van_inventory/models.py

@@ -0,0 +1,46 @@
+"""Van inventory ORM models."""
+
+from __future__ import annotations
+
+from sqlalchemy import ForeignKey, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from python.orm.van_inventory.base import VanTableBase
+
+
+class Item(VanTableBase):
+    """A food item in the van."""
+
+    __tablename__ = "items"
+
+    name: Mapped[str] = mapped_column(unique=True)
+    quantity: Mapped[float] = mapped_column(default=0)
+    unit: Mapped[str]
+    category: Mapped[str | None]
+
+    meal_ingredients: Mapped[list[MealIngredient]] = relationship(back_populates="item")
+
+
+class Meal(VanTableBase):
+    """A meal that can be made from items in the van."""
+
+    __tablename__ = "meals"
+
+    name: Mapped[str] = mapped_column(unique=True)
+    instructions: Mapped[str | None]
+
+    ingredients: Mapped[list[MealIngredient]] = relationship(back_populates="meal")
+
+
+class MealIngredient(VanTableBase):
+    """Links a meal to the items it requires, with quantities."""
+
+    __tablename__ = "meal_ingredients"
+    __table_args__ = (UniqueConstraint("meal_id", "item_id"),)
+
+    meal_id: Mapped[int] = mapped_column(ForeignKey("meals.id"))
+    item_id: Mapped[int] = mapped_column(ForeignKey("items.id"))
+    quantity_needed: Mapped[float]
+
+    meal: Mapped[Meal] = relationship(back_populates="ingredients")
+    item: Mapped[Item] = relationship(back_populates="meal_ingredients")

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/snapshot_manager.py

@@ -34,8 +34,9 @@ def main(config_file: Path) -> None:
                 logger.error(msg)
                 signal_alert(msg)
                 continue
-
+            count_lookup = get_count_lookup(config_file, dataset.name)
-            get_snapshots_to_delete(dataset, get_count_lookup(config_file, dataset.name))
+            logger.info(f"using {count_lookup} for {dataset.name}")
+            get_snapshots_to_delete(dataset, count_lookup)
     except Exception:
         logger.exception("snapshot_manager failed")
         signal_alert("snapshot_manager failed")
@@ -99,6 +100,7 @@ def get_snapshots_to_delete(
     """
     snapshots = dataset.get_snapshots()
 
+    logger.info(f"calculating snapshots for {dataset.name} to be deleted")
     if not snapshots:
         logger.info(f"{dataset.name} has no snapshots")
         return

python/tools/whisper/Dockerfile

@@ -0,0 +1,17 @@
+FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 python3-pip ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip3 install --no-cache-dir --upgrade pip \
+    && pip3 install --no-cache-dir faster-whisper requests
+
+WORKDIR /app
+COPY python/tools/whisper/inference.py /app/inference.py
+
+ENTRYPOINT ["python3", "/app/inference.py"]

python/tools/whisper/Dockerfile.dockerignore

@@ -0,0 +1,2 @@
+*
+!python/tools/whisper/inference.py

python/tools/whisper/__init__.py

@@ -0,0 +1 @@
+"""Whisper transcription tools (host orchestrator and container entrypoint)."""

python/tools/whisper/inference.py

@@ -0,0 +1,136 @@
+"""Container entrypoint that transcribes a directory of audio files with faster-whisper.
+
+Run inside the whisper-transcribe docker image; segment timestamps are grouped
+into one-minute buckets so the output reads as ``[HH:MM:00] text``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+
+from faster_whisper import WhisperModel
+
+logger = logging.getLogger(__name__)
+
+AUDIO_EXTENSIONS = {".mp3", ".wav", ".m4a", ".flac", ".ogg", ".opus", ".mp4", ".mkv", ".webm", ".aac"}
+BUCKET_SECONDS = 60
+BEAM_SIZE = 5
+SECONDS_PER_HOUR = 3600
+SECONDS_PER_MINUTE = 60
+
+
+def format_timestamp(total_seconds: float) -> str:
+    """Render a whole-minute timestamp as ``HH:MM:00``.
+
+    Args:
+        total_seconds: Offset in seconds from the start of the audio.
+
+    Returns:
+        A zero-padded ``HH:MM:00`` string.
+    """
+    hours = int(total_seconds // SECONDS_PER_HOUR)
+    minutes = int((total_seconds % SECONDS_PER_HOUR) // SECONDS_PER_MINUTE)
+    return f"{hours:02d}:{minutes:02d}:00"
+
+
+def transcribe_file(model: WhisperModel, audio_path: Path, output_path: Path) -> None:
+    """Transcribe one audio file and write the bucketed transcript to disk.
+
+    Args:
+        model: Loaded faster-whisper model.
+        audio_path: Source audio file.
+        output_path: Destination ``.txt`` path.
+    """
+    logger.info("Transcribing %s", audio_path)
+    segments, info = model.transcribe(
+        str(audio_path),
+        language="en",
+        beam_size=BEAM_SIZE,
+        vad_filter=True,
+    )
+    logger.info("Duration %.1fs", info.duration)
+
+    buckets: dict[int, list[str]] = {}
+    for segment in segments:
+        bucket = int(segment.start // BUCKET_SECONDS)
+        buckets.setdefault(bucket, []).append(segment.text.strip())
+
+    lines = [f"[{format_timestamp(bucket * BUCKET_SECONDS)}] {' '.join(buckets[bucket])}" for bucket in sorted(buckets)]
+    output_path.write_text("\n\n".join(lines) + "\n", encoding="utf-8")
+    logger.info("Wrote %s", output_path)
+
+
+def find_audio_files(input_directory: Path) -> list[Path]:
+    """Collect every audio file under ``input_directory``.
+
+    Args:
+        input_directory: Directory to walk recursively.
+
+    Returns:
+        Sorted list of audio file paths.
+    """
+    return sorted(
+        path for path in input_directory.rglob("*") if path.is_file() and path.suffix.lower() in AUDIO_EXTENSIONS
+    )
+
+
+def configure_container_logger() -> None:
+    """Configure logging for the container (stdout, INFO)."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(message)s",
+    )
+
+
+def parse_arguments() -> argparse.Namespace:
+    """Parse CLI arguments for the container entrypoint.
+
+    Returns:
+        Parsed argparse namespace.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--input", type=Path, default=Path("/audio"))
+    parser.add_argument("--output", type=Path, default=Path("/output"))
+    parser.add_argument("--model", default="large-v3")
+    parser.add_argument(
+        "--download-only",
+        action="store_true",
+        help="Download the model into the cache volume and exit without transcribing.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    """Load the model, then either exit (download-only) or transcribe the directory."""
+    configure_container_logger()
+    arguments = parse_arguments()
+
+    logger.info("Loading model %s on CUDA", arguments.model)
+    model = WhisperModel(arguments.model, device="cuda", compute_type="float16")
+
+    if arguments.download_only:
+        logger.info("Model ready; exiting (download-only mode)")
+        return
+
+    arguments.output.mkdir(parents=True, exist_ok=True)
+
+    audio_files = find_audio_files(arguments.input)
+    if not audio_files:
+        logger.warning("No audio files found in %s", arguments.input)
+        return
+
+    logger.info("Found %d audio file(s)", len(audio_files))
+    for audio_path in audio_files:
+        relative = audio_path.relative_to(arguments.input)
+        output_path = arguments.output / relative.with_suffix(".txt")
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        if output_path.exists():
+            logger.info("Skip %s (already transcribed)", relative)
+            continue
+        transcribe_file(model, audio_path, output_path)
+
+
+if __name__ == "__main__":
+    main()

python/tools/whisper/transcribe.py

@@ -0,0 +1,167 @@
+"""Build and run the whisper transcription docker container on demand.
+
+The container is started fresh for each invocation and removed on exit
+(``docker run --rm``). The model is cached in a named docker volume so
+only the first run pays the download cost.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from python.common import configure_logger
+
+logger = logging.getLogger(__name__)
+
+
+class Config:
+    """Paths and names for the whisper-transcribe Docker workflow."""
+
+    image_tag = "whisper-transcribe:latest"
+    model_volume = "whisper-models"
+    repo_root = Path(__file__).resolve().parents[3]
+    dockerfile = Path(__file__).resolve().parent / "Dockerfile"
+    huggingface_cache = "/root/.cache/huggingface"
+
+
+def run_docker(arguments: list[str]) -> None:
+    """Run a docker subcommand, streaming output and raising on failure.
+
+    Args:
+        arguments: Arguments to pass to the ``docker`` binary.
+
+    Raises:
+        subprocess.CalledProcessError: If docker exits non-zero.
+    """
+    logger.info("docker %s", " ".join(arguments))
+    subprocess.run(["docker", *arguments], check=True)
+
+
+def build_image() -> None:
+    """Build the whisper-transcribe image using the repo root as build context."""
+    logger.info("Building image %s", Config.image_tag)
+    run_docker(
+        [
+            "build",
+            "--tag",
+            Config.image_tag,
+            "--file",
+            str(Config.dockerfile),
+            str(Config.repo_root),
+        ],
+    )
+
+
+def model_cache_present(model: str) -> bool:
+    """Check whether the given model is already downloaded in the cache volume.
+
+    Args:
+        model: faster-whisper model name (e.g. ``large-v3``).
+
+    Returns:
+        True if the HuggingFace cache directory for the model exists in the volume.
+    """
+    cache_directory = f"hub/models--Systran--faster-whisper-{model}"
+    completed = subprocess.run(
+        [
+            "docker",
+            "run",
+            "--rm",
+            "--volume",
+            f"{Config.model_volume}:/cache",
+            "alpine",
+            "test",
+            "-d",
+            f"/cache/{cache_directory}",
+        ],
+        check=False,
+    )
+    return completed.returncode == 0
+
+
+def download_model(model: str) -> None:
+    """Download the model into the cache volume and exit.
+
+    Args:
+        model: faster-whisper model name.
+    """
+    logger.info("Downloading model %s into volume %s", model, Config.model_volume)
+    run_docker(
+        [
+            "run",
+            "--rm",
+            "--device=nvidia.com/gpu=all",
+            "--ipc=host",
+            "--volume",
+            f"{Config.model_volume}:{Config.huggingface_cache}",
+            Config.image_tag,
+            "--model",
+            model,
+            "--download-only",
+        ],
+    )
+
+
+def transcribe(input_directory: Path, output_directory: Path, model: str) -> None:
+    """Run transcription on every audio file under ``input_directory``.
+
+    Args:
+        input_directory: Host path containing audio files (mounted read-only).
+        output_directory: Host path for ``.txt`` transcripts.
+        model: faster-whisper model name.
+    """
+    logger.info("Transcribing %s -> %s (model=%s)", input_directory, output_directory, model)
+    run_docker(
+        [
+            "run",
+            "--rm",
+            "--device=nvidia.com/gpu=all",
+            "--ipc=host",
+            "--volume",
+            f"{input_directory}:/audio:ro",
+            "--volume",
+            f"{output_directory}:/output",
+            "--volume",
+            f"{Config.model_volume}:{Config.huggingface_cache}",
+            Config.image_tag,
+            "--model",
+            model,
+        ],
+    )
+
+
+def main(
+    input_directory: Annotated[Path, typer.Argument(help="Directory of audio files to transcribe.")],
+    output_directory: Annotated[Path, typer.Argument(help="Directory to write .txt transcripts to.")],
+    model: Annotated[str, typer.Option(help="faster-whisper model name.")] = "large-v3",
+    *,
+    force_download: Annotated[
+        bool,
+        typer.Option("--force-download", help="Re-download the model even if already cached."),
+    ] = False,
+) -> None:
+    """Build the image, ensure the model is cached, then transcribe and stop."""
+    configure_logger()
+
+    resolved_input = input_directory.resolve(strict=True)
+    output_directory.mkdir(parents=True, exist_ok=True)
+    resolved_output = output_directory.resolve()
+
+    build_image()
+
+    if force_download or not model_cache_present(model):
+        download_model(model)
+    else:
+        logger.info("Model %s already cached in volume %s", model, Config.model_volume)
+
+    transcribe(resolved_input, resolved_output, model)
+    logger.info("Done. Container stopped.")
+
+
+if __name__ == "__main__":
+    typer.run(main)

python/van_inventory/__init__.py

@@ -0,0 +1 @@
+"""Van inventory FastAPI application."""

python/van_inventory/dependencies.py

@@ -0,0 +1,16 @@
+"""FastAPI dependencies for van inventory."""
+
+from collections.abc import Iterator
+from typing import Annotated
+
+from fastapi import Depends, Request
+from sqlalchemy.orm import Session
+
+
+def get_db(request: Request) -> Iterator[Session]:
+    """Get database session from app state."""
+    with Session(request.app.state.engine) as session:
+        yield session
+
+
+DbSession = Annotated[Session, Depends(get_db)]

python/van_inventory/main.py

@@ -0,0 +1,56 @@
+"""FastAPI app for van inventory."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+import uvicorn
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from python.common import configure_logger
+from python.orm.common import get_postgres_engine
+from python.van_inventory.routers import api_router, frontend_router
+
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+logger = logging.getLogger(__name__)
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        app.state.engine = get_postgres_engine(name="VAN_INVENTORY")
+        yield
+        app.state.engine.dispose()
+
+    app = FastAPI(title="Van Inventory", lifespan=lifespan)
+    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+    app.include_router(api_router)
+    app.include_router(frontend_router)
+    return app
+
+
+def serve(
+    # Intentionally binds all interfaces — this is a LAN-only van server
+    host: Annotated[str, typer.Option("--host", "-h", help="Host to bind to")] = "0.0.0.0",  # noqa: S104
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to bind to")] = 8001,
+    log_level: Annotated[str, typer.Option("--log-level", "-l", help="Log level")] = "INFO",
+) -> None:
+    """Start the Van Inventory server."""
+    configure_logger(log_level)
+    app = create_app()
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    typer.run(serve)