deleting data_science code

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/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

@@ -165,3 +165,10 @@ test.*
 
 # syncthing
 .stfolder
+
+# 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",
@@ -77,6 +76,7 @@
     "esphome",
     "extest",
     "fadvise",
+    "fastfetch",
     "fastforwardteam",
     "FASTFOX",
     "ffmpegthumbnailer",
@@ -166,7 +166,6 @@
     "mypy",
     "ncdu",
     "nemo",
-    "neofetch",
     "nerdfonts",
     "netdev",
     "netdevs",
@@ -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",
@@ -287,6 +289,7 @@
     "topstories",
     "treefmt",
     "twimg",
+    "typedmonarchmoney",
     "typer",
     "uaccess",
     "ubiquiti",
@@ -304,6 +307,8 @@
     "useragent",
     "usernamehw",
     "userprefs",
+    "vaninventory",
+    "vdev",
     "vfat",
     "victron",
     "virt",

AGENTS.md

@@ -1,5 +0,0 @@
-## Dev environment tips
-
-- use treefmt to format all files
-- make python code ruff compliant
-- use pytest to test python code

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

@@ -33,6 +33,9 @@ in
       ];
       warn-dirty = false;
       flake-registry = ""; # disable global flake registries
+      connect-timeout = 10;
+      download-buffer-size = 536870912;
+      fallback = true;
     };
 
     # Add each flake input as a registry and nix_path

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": 1766762570,
+        "lastModified": 1781150628,
-        "narHash": "sha256-Nevsj5NYurwp3I6nSMeh3uirwoinVSbCldqOXu4smms=",
+        "narHash": "sha256-b4mp8l3qWuSCyYYo9HSngDtcB3PpecYiOXjULrjwwlw=",
         "owner": "rycee",
         "repo": "nur-expressions",
-        "rev": "03d7d310ea91d6e4b47ed70aa86c781fcc5b38e1",
+        "rev": "753319310f4673a2dabbfab87482187b40bf9bac",
         "type": "gitlab"
       },
       "original": {
@@ -29,11 +29,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1766682973,
+        "lastModified": 1781189114,
-        "narHash": "sha256-GKO35onS711ThCxwWcfuvbIBKXwriahGqs+WZuJ3v9E=",
+        "narHash": "sha256-5inaamLgUMWy+MOBE9ChF9QAF1o/74LFuHkI0W/9rqc=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "91cdb0e2d574c64fae80d221f4bf09d5592e9ec2",
+        "rev": "486595d2cf49cfcd649b58a284fa11ac0e34da22",
         "type": "github"
       },
       "original": {
@@ -43,12 +43,15 @@
       }
     },
     "nixos-hardware": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      },
       "locked": {
-        "lastModified": 1766568855,
+        "lastModified": 1781168557,
-        "narHash": "sha256-UXVtN77D7pzKmzOotFTStgZBqpOcf8cO95FcupWp4Zo=",
+        "narHash": "sha256-LOnLQ2tpYF9gqIDDr3+j3DbpJJr/QCH6zPRT2GzEUOE=",
         "owner": "nixos",
         "repo": "nixos-hardware",
-        "rev": "c5db9569ac9cc70929c268ac461f4003e3e5ca80",
+        "rev": "6358ff76821101c178e3ab4919a62799bfe3652e",
         "type": "github"
       },
       "original": {
@@ -60,27 +63,24 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1766651565,
+        "lastModified": 1767892417,
-        "narHash": "sha256-QEhk0eXgyIqTpJ/ehZKg9IKS7EtlWxF3N7DXy42zPfU=",
+        "narHash": "sha256-8bW3q88CEg2u4hSP66Vf4lpbLonHz7hqDNBMcCY7E9U=",
-        "owner": "nixos",
+        "rev": "3497aa5c9457a9d88d71fa93a4a8368816fbeeba",
-        "repo": "nixpkgs",
+        "type": "tarball",
-        "rev": "3e2499d5539c16d0d173ba53552a4ff8547f4539",
+        "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": 1766794443,
+        "lastModified": 1781229721,
-        "narHash": "sha256-Q8IyTQ3Lu8vX/iqO3U+E4pjLbP1NsqFih6uElf8OYrQ=",
+        "narHash": "sha256-ORvqDbb/LYxiJljGIejapjkc/kJbVote2N1WSb9W45I=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "088b069b8270ee36d83533c86b9f91d924d185d9",
+        "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": 1766289575,
+        "lastModified": 1780547341,
-        "narHash": "sha256-BOKCwOQQIP4p9z8DasT5r+qjri3x7sPCOq+FTjY8Z+o=",
+        "narHash": "sha256-Gq8KNx5A7hBB3uGJaj6eQfLDIz5YdLu92gqBcvHvoUo=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "9836912e37aef546029e48c8749834735a6b9dad",
+        "rev": "9ed65852b6257fbeae4355bc24ecfea307ca759a",
         "type": "github"
       },
       "original": {

frontend/.gitignore

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

overlays/default.nix

@@ -16,25 +16,35 @@
   };
 
   python-env = final: _prev: {
-    my_python = final.python313.withPackages (
+    my_python = final.python314.withPackages (
       ps: with ps; [
+        alembic
         apprise
         apscheduler
+        fastapi
+        fastapi-cli
+        httpx
         mypy
+        orjson
         polars
         psycopg
+        pydantic
         pyfakefs
         pytest
         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", "polars", "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,26 +51,39 @@ 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/**" = [
-    "S101", # (perm) pytest needs asserts
+    "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/random/**" = [
+"python/stuff/**" = [
     "T201", # (perm) I don't care about print statements dir
 ]
 "python/testing/**" = [
     "T201",   # (perm) I don't care about print statements dir
     "ERA001", # (perm) I don't care about print statements dir
 ]
-
 "python/splendor/**" = [
     "S311",    # (perm) there is no security issue here
     "T201",    # (perm) I don't care about print statements dir
     "PLR2004", # (temps) need to think about this
 ]
+"python/orm/**" = [
+    "TC003", # (perm) this creates issues because sqlalchemy uses these at runtime
+]
+"python/congress_tracker/**" = [
+    "TC003", # (perm) this creates issues because sqlalchemy uses these at runtime
+]
+
+"python/alembic/**" = [
+    "INP001", # (perm) this creates LSP issues for alembic
+]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -76,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/env.py

@@ -0,0 +1,122 @@
+"""Alembic."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+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.common import get_postgres_engine
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+    from sqlalchemy.orm import DeclarativeBase
+
+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 = base_class.metadata
+logging.basicConfig(
+    level="DEBUG",
+    datefmt="%Y-%m-%dT%H:%M:%S%z",
+    format="%(asctime)s %(levelname)s %(filename)s:%(lineno)d - %(message)s",
+    handlers=[logging.StreamHandler(sys.stdout)],
+)
+
+
+@write_hooks.register("dynamic_schema")
+def dynamic_schema(filename: str, _options: dict[Any, Any]) -> None:
+    """Dynamic schema."""
+    original_file = Path(filename).read_text()
+    schema_name = base_class.schema_name
+    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."""
+    bash_wrapper(f"ruff check --fix {filename}")
+    bash_wrapper(f"ruff format {filename}")
+
+
+def include_name(
+    name: str | None,
+    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:
+    """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 (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
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    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=schema,
+            include_name=include_name,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+        connection.commit()
+
+
+run_migrations_online()

python/alembic/richie/versions/2026_01_11-created_contact_api_edd7dd61a3d2.py

@@ -0,0 +1,113 @@
+"""created contact api.
+
+Revision ID: edd7dd61a3d2
+Revises:
+Create Date: 2026-01-11 15:45:59.909266
+
+"""
+
+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 = "edd7dd61a3d2"
+down_revision: str | None = None
+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(
+        "contact",
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("age", sa.Integer(), nullable=True),
+        sa.Column("bio", sa.String(), nullable=True),
+        sa.Column("current_job", sa.String(), nullable=True),
+        sa.Column("gender", sa.String(), nullable=True),
+        sa.Column("goals", sa.String(), nullable=True),
+        sa.Column("legal_name", sa.String(), nullable=True),
+        sa.Column("profile_pic", sa.String(), nullable=True),
+        sa.Column("safe_conversation_starters", sa.String(), nullable=True),
+        sa.Column("self_sufficiency_score", sa.Integer(), nullable=True),
+        sa.Column("social_structure_style", sa.String(), nullable=True),
+        sa.Column("ssn", sa.String(), nullable=True),
+        sa.Column("suffix", sa.String(), nullable=True),
+        sa.Column("timezone", sa.String(), nullable=True),
+        sa.Column("topics_to_avoid", 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_contact")),
+        schema=schema,
+    )
+    op.create_table(
+        "need",
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("description", 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_need")),
+        schema=schema,
+    )
+    op.create_table(
+        "contact_need",
+        sa.Column("contact_id", sa.Integer(), nullable=False),
+        sa.Column("need_id", sa.Integer(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["contact_id"],
+            [f"{schema}.contact.id"],
+            name=op.f("fk_contact_need_contact_id_contact"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["need_id"], [f"{schema}.need.id"], name=op.f("fk_contact_need_need_id_need"), ondelete="CASCADE"
+        ),
+        sa.PrimaryKeyConstraint("contact_id", "need_id", name=op.f("pk_contact_need")),
+        schema=schema,
+    )
+    op.create_table(
+        "contact_relationship",
+        sa.Column("contact_id", sa.Integer(), nullable=False),
+        sa.Column("related_contact_id", sa.Integer(), nullable=False),
+        sa.Column("relationship_type", sa.String(length=100), nullable=False),
+        sa.Column("closeness_weight", sa.Integer(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["contact_id"],
+            [f"{schema}.contact.id"],
+            name=op.f("fk_contact_relationship_contact_id_contact"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["related_contact_id"],
+            [f"{schema}.contact.id"],
+            name=op.f("fk_contact_relationship_related_contact_id_contact"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("contact_id", "related_contact_id", name=op.f("pk_contact_relationship")),
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("contact_relationship", schema=schema)
+    op.drop_table("contact_need", schema=schema)
+    op.drop_table("need", schema=schema)
+    op.drop_table("contact", schema=schema)
+    # ### end Alembic commands ###

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

@@ -0,0 +1,36 @@
+"""${message}.
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+
+from alembic import op
+from python.orm import ${config.attributes["base"].__name__}
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+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=${config.attributes["base"].__name__}.schema_name
+
+def upgrade() -> None:
+    """Upgrade."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    ${downgrades if downgrades else "pass"}

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

@@ -0,0 +1 @@
+"""FastAPI applications."""

python/api/dependencies.py

@@ -0,0 +1,16 @@
+"""FastAPI dependencies."""
+
+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/api/main.py

@@ -0,0 +1,52 @@
+"""FastAPI interface for Contact database."""
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+import typer
+import uvicorn
+from fastapi import FastAPI
+
+from python.api.middleware import ZstdMiddleware
+from python.api.routers import contact_router, views_router
+from python.common import configure_logger
+from python.orm.common import get_postgres_engine
+
+logger = logging.getLogger(__name__)
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        """Manage application lifespan."""
+        app.state.engine = get_postgres_engine()
+        yield
+        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)
+
+    return app
+
+
+def serve(
+    host: Annotated[str, typer.Option("--host", "-h", help="Host to bind to")],
+    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)
+
+    app = create_app()
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    typer.run(serve)

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

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

python/api/routers/contact.py

@@ -0,0 +1,481 @@
+"""Contact API router."""
+
+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.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):
+    """Base schema for Need."""
+
+    name: str
+    description: str | None = None
+
+
+class NeedCreate(NeedBase):
+    """Schema for creating a Need."""
+
+
+class NeedResponse(NeedBase):
+    """Schema for Need response."""
+
+    id: int
+
+    model_config = {"from_attributes": True}
+
+
+class ContactRelationshipCreate(BaseModel):
+    """Schema for creating a contact relationship."""
+
+    related_contact_id: int
+    relationship_type: RelationshipType
+    closeness_weight: int | None = None
+
+
+class ContactRelationshipUpdate(BaseModel):
+    """Schema for updating a contact relationship."""
+
+    relationship_type: RelationshipType | None = None
+    closeness_weight: int | None = None
+
+
+class ContactRelationshipResponse(BaseModel):
+    """Schema for contact relationship response."""
+
+    contact_id: int
+    related_contact_id: int
+    relationship_type: str
+    closeness_weight: int
+
+    model_config = {"from_attributes": True}
+
+
+class RelationshipTypeInfo(BaseModel):
+    """Information about a relationship type."""
+
+    value: str
+    display_name: str
+    default_weight: int
+
+
+class GraphNode(BaseModel):
+    """Node in the relationship graph."""
+
+    id: int
+    name: str
+    current_job: str | None = None
+
+
+class GraphEdge(BaseModel):
+    """Edge in the relationship graph."""
+
+    source: int
+    target: int
+    relationship_type: str
+    closeness_weight: int
+
+
+class GraphData(BaseModel):
+    """Complete graph data for visualization."""
+
+    nodes: list[GraphNode]
+    edges: list[GraphEdge]
+
+
+class ContactBase(BaseModel):
+    """Base schema for Contact."""
+
+    name: str
+    age: int | None = None
+    bio: str | None = None
+    current_job: str | None = None
+    gender: str | None = None
+    goals: str | None = None
+    legal_name: str | None = None
+    profile_pic: str | None = None
+    safe_conversation_starters: str | None = None
+    self_sufficiency_score: int | None = None
+    social_structure_style: str | None = None
+    ssn: str | None = None
+    suffix: str | None = None
+    timezone: str | None = None
+    topics_to_avoid: str | None = None
+
+
+class ContactCreate(ContactBase):
+    """Schema for creating a Contact."""
+
+    need_ids: list[int] = []
+
+
+class ContactUpdate(BaseModel):
+    """Schema for updating a Contact."""
+
+    name: str | None = None
+    age: int | None = None
+    bio: str | None = None
+    current_job: str | None = None
+    gender: str | None = None
+    goals: str | None = None
+    legal_name: str | None = None
+    profile_pic: str | None = None
+    safe_conversation_starters: str | None = None
+    self_sufficiency_score: int | None = None
+    social_structure_style: str | None = None
+    ssn: str | None = None
+    suffix: str | None = None
+    timezone: str | None = None
+    topics_to_avoid: str | None = None
+    need_ids: list[int] | None = None
+
+
+class ContactResponse(ContactBase):
+    """Schema for Contact response with relationships."""
+
+    id: int
+    needs: list[NeedResponse] = []
+    related_to: list[ContactRelationshipResponse] = []
+    related_from: list[ContactRelationshipResponse] = []
+
+    model_config = {"from_attributes": True}
+
+
+class ContactListResponse(ContactBase):
+    """Schema for Contact list response."""
+
+    id: int
+
+    model_config = {"from_attributes": True}
+
+
+router = APIRouter(prefix="/api", tags=["contacts"])
+
+
+@router.post("/needs", response_model=NeedResponse)
+def create_need(need: NeedCreate, db: DbSession) -> Need:
+    """Create a new need."""
+    db_need = Need(name=need.name, description=need.description)
+    db.add(db_need)
+    db.commit()
+    db.refresh(db_need)
+    return db_need
+
+
+@router.get("/needs", response_model=list[NeedResponse])
+def list_needs(db: DbSession) -> list[Need]:
+    """List all needs."""
+    return list(db.scalars(select(Need)).all())
+
+
+@router.get("/needs/{need_id}", response_model=NeedResponse)
+def get_need(need_id: int, db: DbSession) -> Need:
+    """Get a need by ID."""
+    need = db.get(Need, need_id)
+    if not need:
+        raise HTTPException(status_code=404, detail="Need not found")
+    return need
+
+
+@router.delete("/needs/{need_id}", response_model=None)
+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}
+
+
+@router.post("/contacts", response_model=ContactResponse)
+def create_contact(contact: ContactCreate, db: DbSession) -> Contact:
+    """Create a new contact."""
+    need_ids = contact.need_ids
+    contact_data = contact.model_dump(exclude={"need_ids"})
+    db_contact = Contact(**contact_data)
+
+    if need_ids:
+        needs = list(db.scalars(select(Need).where(Need.id.in_(need_ids))).all())
+        db_contact.needs = needs
+
+    db.add(db_contact)
+    db.commit()
+    db.refresh(db_contact)
+    return db_contact
+
+
+@router.get("/contacts", response_model=list[ContactListResponse])
+def list_contacts(
+    db: DbSession,
+    skip: int = 0,
+    limit: int = 100,
+) -> list[Contact]:
+    """List all contacts with pagination."""
+    return list(db.scalars(select(Contact).offset(skip).limit(limit)).all())
+
+
+@router.get("/contacts/{contact_id}", response_model=ContactResponse)
+def get_contact(contact_id: int, db: DbSession) -> Contact:
+    """Get a contact by ID with all relationships."""
+    contact = db.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")
+    return contact
+
+
+@router.patch("/contacts/{contact_id}", response_model=ContactResponse)
+def update_contact(
+    contact_id: int,
+    contact: ContactUpdate,
+    db: DbSession,
+) -> Contact:
+    """Update a contact by ID."""
+    db_contact = db.get(Contact, contact_id)
+    if not db_contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    update_data = contact.model_dump(exclude_unset=True)
+    need_ids = update_data.pop("need_ids", None)
+
+    for key, value in update_data.items():
+        setattr(db_contact, key, value)
+
+    if need_ids is not None:
+        needs = list(db.scalars(select(Need).where(Need.id.in_(need_ids))).all())
+        db_contact.needs = needs
+
+    db.commit()
+    db.refresh(db_contact)
+    return db_contact
+
+
+@router.delete("/contacts/{contact_id}", response_model=None)
+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}
+
+
+@router.post("/contacts/{contact_id}/needs/{need_id}")
+def add_need_to_contact(
+    contact_id: int,
+    need_id: int,
+    db: DbSession,
+) -> dict[str, bool]:
+    """Add a need to a contact."""
+    contact = db.get(Contact, contact_id)
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    need = db.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)
+        db.commit()
+
+    return {"added": True}
+
+
+@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] | HTMLResponse:
+    """Remove a need from a contact."""
+    contact = db.get(Contact, contact_id)
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    need = db.get(Need, need_id)
+    if not need:
+        raise HTTPException(status_code=404, detail="Need not found")
+
+    if need in contact.needs:
+        contact.needs.remove(need)
+        db.commit()
+
+    if _is_htmx(request):
+        return HTMLResponse("")
+    return {"removed": True}
+
+
+@router.post(
+    "/contacts/{contact_id}/relationships",
+    response_model=ContactRelationshipResponse,
+)
+def add_contact_relationship(
+    contact_id: int,
+    relationship: ContactRelationshipCreate,
+    db: DbSession,
+) -> ContactRelationship:
+    """Add a relationship between two contacts."""
+    contact = db.get(Contact, contact_id)
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    related_contact = db.get(Contact, relationship.related_contact_id)
+    if not related_contact:
+        raise HTTPException(status_code=404, detail="Related contact not found")
+
+    if contact_id == relationship.related_contact_id:
+        raise HTTPException(status_code=400, detail="Cannot relate contact to itself")
+
+    # Use provided weight or default from relationship type
+    weight = relationship.closeness_weight
+    if weight is None:
+        weight = relationship.relationship_type.default_weight
+
+    db_relationship = ContactRelationship(
+        contact_id=contact_id,
+        related_contact_id=relationship.related_contact_id,
+        relationship_type=relationship.relationship_type.value,
+        closeness_weight=weight,
+    )
+    db.add(db_relationship)
+    db.commit()
+    db.refresh(db_relationship)
+    return db_relationship
+
+
+@router.get(
+    "/contacts/{contact_id}/relationships",
+    response_model=list[ContactRelationshipResponse],
+)
+def get_contact_relationships(
+    contact_id: int,
+    db: DbSession,
+) -> list[ContactRelationship]:
+    """Get all relationships for a contact."""
+    contact = db.get(Contact, contact_id)
+    if not contact:
+        raise HTTPException(status_code=404, detail="Contact not found")
+
+    outgoing = list(db.scalars(select(ContactRelationship).where(ContactRelationship.contact_id == contact_id)).all())
+    incoming = list(
+        db.scalars(select(ContactRelationship).where(ContactRelationship.related_contact_id == contact_id)).all()
+    )
+    return outgoing + incoming
+
+
+@router.patch(
+    "/contacts/{contact_id}/relationships/{related_contact_id}",
+    response_model=ContactRelationshipResponse,
+)
+def update_contact_relationship(
+    contact_id: int,
+    related_contact_id: int,
+    update: ContactRelationshipUpdate,
+    db: DbSession,
+) -> ContactRelationship:
+    """Update a relationship between two contacts."""
+    relationship = db.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")
+
+    if update.relationship_type is not None:
+        relationship.relationship_type = update.relationship_type.value
+    if update.closeness_weight is not None:
+        relationship.closeness_weight = update.closeness_weight
+
+    db.commit()
+    db.refresh(relationship)
+    return relationship
+
+
+@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] | HTMLResponse:
+    """Remove a relationship between two contacts."""
+    relationship = db.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")
+
+    db.delete(relationship)
+    db.commit()
+    if _is_htmx(request):
+        return HTMLResponse("")
+    return {"deleted": True}
+
+
+@router.get("/relationship-types")
+def list_relationship_types() -> list[RelationshipTypeInfo]:
+    """List all available relationship types with their default weights."""
+    return [
+        RelationshipTypeInfo(
+            value=rt.value,
+            display_name=rt.display_name,
+            default_weight=rt.default_weight,
+        )
+        for rt in RelationshipType
+    ]
+
+
+@router.get("/graph")
+def get_relationship_graph(db: DbSession) -> GraphData:
+    """Get all contacts and relationships as graph data for visualization."""
+    contacts = list(db.scalars(select(Contact)).all())
+    relationships = list(db.scalars(select(ContactRelationship)).all())
+
+    nodes = [GraphNode(id=c.id, name=c.name, current_job=c.current_job) for c in contacts]
+
+    edges = [
+        GraphEdge(
+            source=rel.contact_id,
+            target=rel.related_contact_id,
+            relationship_type=rel.relationship_type,
+            closeness_weight=rel.closeness_weight,
+        )
+        for rel in relationships
+    ]
+
+    return GraphData(nodes=nodes, edges=edges)

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

@@ -0,0 +1 @@
+"""Detect Nix evaluation warnings from build logs and create PRs with LLM-suggested fixes."""

python/eval_warnings/main.py

@@ -0,0 +1,449 @@
+"""Detect Nix evaluation warnings and create PRs with LLM-suggested fixes."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+import subprocess
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import Path
+from typing import Annotated
+from zipfile import ZipFile
+
+import typer
+from httpx import HTTPError, post
+
+from python.common import configure_logger
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class EvalWarning:
+    """A single Nix evaluation warning."""
+
+    system: str
+    message: str
+
+
+@dataclass
+class FileChange:
+    """A file change suggested by the LLM."""
+
+    file_path: str
+    original: str
+    fixed: str
+
+
+def run_cmd(cmd: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess command and return the result.
+
+    Args:
+        cmd: Command and arguments.
+        check: Whether to raise on non-zero exit.
+
+    Returns:
+        CompletedProcess with captured stdout/stderr.
+    """
+    logger.debug("Running: %s", " ".join(cmd))
+    return subprocess.run(cmd, capture_output=True, text=True, check=check)
+
+
+def download_logs(run_id: str, repo: str) -> dict[str, str]:
+    """Download build logs for a GitHub Actions run.
+
+    Args:
+        run_id: The workflow run ID.
+        repo: The GitHub repository (owner/repo).
+
+    Returns:
+        Dict mapping zip entry names to their text content, filtered to build log files.
+
+    Raises:
+        RuntimeError: If log download fails.
+    """
+    result = subprocess.run(
+        ["gh", "api", f"repos/{repo}/actions/runs/{run_id}/logs"],
+        capture_output=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        msg = f"Failed to download logs: {result.stderr.decode(errors='replace')}"
+        raise RuntimeError(msg)
+
+    logs: dict[str, str] = {}
+    with ZipFile(BytesIO(result.stdout)) as zip_file:
+        for name in zip_file.namelist():
+            if name.startswith("build-") and name.endswith(".txt"):
+                logs[name] = zip_file.read(name).decode(errors="replace")
+
+    return logs
+
+
+def parse_warnings(logs: dict[str, str]) -> set[EvalWarning]:
+    """Parse Nix evaluation warnings from build log contents.
+
+    Args:
+        logs: Dict mapping zip entry names (e.g. "build-bob/2_Build.txt") to their text.
+
+    Returns:
+        Deduplicated set of warnings.
+    """
+    warnings: set[EvalWarning] = set()
+    warning_pattern = re.compile(r"(?:^[\d\-T:.Z]+ )?(warning:|trace: warning:)")
+    timestamp_prefix = re.compile(r"^[\d\-T:.Z]+ ")
+
+    for name, content in sorted(logs.items()):
+        system = name.split("/")[0].removeprefix("build-")
+        for line in content.splitlines():
+            if warning_pattern.search(line):
+                message = timestamp_prefix.sub("", line).strip()
+                if message.startswith("warning: ignoring untrusted flake configuration setting"):
+                    continue
+                logger.debug(f"Found warning: {line}")
+                warnings.add(EvalWarning(system=system, message=message))
+
+    logger.info("Found %d unique warnings", len(warnings))
+    return warnings
+
+
+def extract_referenced_files(warnings: set[EvalWarning]) -> dict[str, str]:
+    """Extract file paths referenced in warnings and read their contents.
+
+    Args:
+        warnings: List of parsed warnings.
+
+    Returns:
+        Dict mapping repo-relative file paths to their contents.
+    """
+    paths: set[str] = set()
+    warning_text = "\n".join(w.message for w in warnings)
+
+    nix_store_path = re.compile(r"/nix/store/[^/]+-source/([^:]+\.nix)")
+    for match in nix_store_path.finditer(warning_text):
+        paths.add(match.group(1))
+
+    repo_relative_path = re.compile(r"(?<![/\w])(systems|common|users|overlays)/[^:\s]+\.nix")
+    for match in repo_relative_path.finditer(warning_text):
+        paths.add(match.group(0))
+
+    files: dict[str, str] = {}
+    for path_str in sorted(paths):
+        path = Path(path_str)
+        if path.is_file():
+            files[path_str] = path.read_text()
+
+    if not files and Path("flake.nix").is_file():
+        files["flake.nix"] = Path("flake.nix").read_text()
+
+    logger.info("Extracted %d referenced files", len(files))
+    return files
+
+
+def compute_warning_hash(warnings: set[EvalWarning]) -> str:
+    """Compute a short hash of the warning set for deduplication.
+
+    Args:
+        warnings: List of warnings.
+
+    Returns:
+        8-character hex hash.
+    """
+    text = "\n".join(sorted(f"[{w.system}] {w.message}" for w in warnings))
+    return hashlib.sha256(text.encode()).hexdigest()[:8]
+
+
+def check_duplicate_pr(warning_hash: str) -> bool:
+    """Check if an open PR already exists for this warning hash.
+
+    Args:
+        warning_hash: The hash to check.
+
+    Returns:
+        True if a duplicate PR exists.
+
+    Raises:
+        RuntimeError: If the gh CLI call fails.
+    """
+    result = run_cmd(
+        [
+            "gh",
+            "pr",
+            "list",
+            "--state",
+            "open",
+            "--label",
+            "eval-warning-fix",
+            "--json",
+            "title",
+            "--jq",
+            ".[].title",
+        ],
+        check=False,
+    )
+    if result.returncode != 0:
+        msg = f"Failed to check for duplicate PRs: {result.stderr}"
+        raise RuntimeError(msg)
+
+    for title in result.stdout.splitlines():
+        if warning_hash in title:
+            logger.info("Duplicate PR found for hash %s", warning_hash)
+            return True
+    return False
+
+
+def query_ollama(
+    warnings: set[EvalWarning],
+    files: dict[str, str],
+    ollama_url: str,
+) -> str | None:
+    """Query Ollama for a fix suggestion.
+
+    Args:
+        warnings: List of warnings.
+        files: Referenced file contents.
+        ollama_url: Ollama API base URL.
+
+    Returns:
+        LLM response text, or None on failure.
+    """
+    warning_text = "\n".join(f"[{w.system}] {w.message}" for w in warnings)
+    file_context = "\n".join(f"--- FILE: {path} ---\n{content}\n--- END FILE ---" for path, content in files.items())
+
+    prompt = f"""You are a NixOS configuration expert. \
+Analyze the following Nix evaluation warnings and suggest fixes.
+
+## Warnings
+{warning_text}
+
+## Referenced Files
+{file_context}
+
+## Instructions
+- Identify the root cause of each warning
+- Provide the exact file changes needed to fix the warnings
+- Output your response in two clearly separated sections:
+  1. **REASONING**: Brief explanation of what causes each warning and how to fix it
+  2. **CHANGES**: For each file that needs changes, output a block like:
+     FILE: path/to/file.nix
+     <<<<<<< ORIGINAL
+     the original lines to replace
+     =======
+     the replacement lines
+     >>>>>>> FIXED
+- Only suggest changes for files that exist in the repository
+- Do not add unnecessary complexity
+- Preserve the existing code style
+- If a warning comes from upstream nixpkgs and cannot be fixed in this repo, \
+say so in REASONING and do not suggest changes"""
+
+    try:
+        response = post(
+            f"{ollama_url}/api/generate",
+            json={
+                "model": "qwen3-coder:30b",
+                "prompt": prompt,
+                "stream": False,
+                "options": {"num_predict": 4096},
+            },
+            timeout=300,
+        )
+        response.raise_for_status()
+    except HTTPError:
+        logger.exception("Ollama request failed")
+        return None
+
+    return response.json().get("response")
+
+
+def parse_changes(response: str) -> list[FileChange]:
+    """Parse file changes from the **CHANGES** section of the LLM response.
+
+    Expects blocks in the format:
+        FILE: path/to/file.nix
+        <<<<<<< ORIGINAL
+        ...
+        =======
+        ...
+        >>>>>>> FIXED
+
+    Args:
+        response: Raw LLM response text.
+
+    Returns:
+        List of parsed file changes.
+    """
+    if "**CHANGES**" not in response:
+        logger.warning("LLM response missing **CHANGES** section")
+        return []
+
+    changes_section = response.split("**CHANGES**", 1)[1]
+
+    changes: list[FileChange] = []
+    current_file = ""
+    section: str | None = None
+    original_lines: list[str] = []
+    fixed_lines: list[str] = []
+
+    for line in changes_section.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("FILE:"):
+            current_file = stripped.removeprefix("FILE:").strip()
+        elif stripped == "<<<<<<< ORIGINAL":
+            section = "original"
+            original_lines = []
+        elif stripped == "=======" and section == "original":
+            section = "fixed"
+            fixed_lines = []
+        elif stripped == ">>>>>>> FIXED" and section == "fixed":
+            section = None
+            if current_file:
+                changes.append(FileChange(current_file, "\n".join(original_lines), "\n".join(fixed_lines)))
+        elif section == "original":
+            original_lines.append(line)
+        elif section == "fixed":
+            fixed_lines.append(line)
+
+    logger.info("Parsed %d file changes", len(changes))
+    return changes
+
+
+def apply_changes(changes: list[FileChange]) -> int:
+    """Apply file changes to the working directory.
+
+    Args:
+        changes: List of changes to apply.
+
+    Returns:
+        Number of changes successfully applied.
+    """
+    applied = 0
+    cwd = Path.cwd().resolve()
+    for change in changes:
+        path = Path(change.file_path).resolve()
+        if not path.is_relative_to(cwd):
+            logger.warning("Path traversal blocked: %s", change.file_path)
+            continue
+        if not path.is_file():
+            logger.warning("File not found: %s", change.file_path)
+            continue
+
+        content = path.read_text()
+        if change.original not in content:
+            logger.warning("Original text not found in %s", change.file_path)
+            continue
+
+        path.write_text(content.replace(change.original, change.fixed, 1))
+        logger.info("Applied fix to %s", change.file_path)
+        applied += 1
+
+    return applied
+
+
+def create_pr(
+    warning_hash: str,
+    warnings: set[EvalWarning],
+    llm_response: str,
+    run_url: str,
+) -> None:
+    """Create a git branch and PR with the applied fixes.
+
+    Args:
+        warning_hash: Short hash for branch naming and deduplication.
+        warnings: Original warnings for the PR body.
+        llm_response: Full LLM response for extracting reasoning.
+        run_url: URL to the triggering build run.
+    """
+    branch = f"fix/eval-warning-{warning_hash}"
+    warning_text = "\n".join(f"[{w.system}] {w.message}" for w in warnings)
+
+    if "**REASONING**" not in llm_response:
+        logger.warning("LLM response missing **REASONING** section")
+        reasoning = ""
+    else:
+        _, after = llm_response.split("**REASONING**", 1)
+        reasoning = "\n".join(after.split("**CHANGES**", 1)[0].strip().splitlines()[:50])
+
+    run_cmd(["git", "config", "user.name", "github-actions[bot]"])
+    run_cmd(["git", "config", "user.email", "github-actions[bot]@users.noreply.github.com"])
+    run_cmd(["git", "checkout", "-b", branch])
+    run_cmd(["git", "add", "-A"])
+
+    diff_result = run_cmd(["git", "diff", "--cached", "--quiet"], check=False)
+    if diff_result.returncode == 0:
+        logger.info("No file changes to commit")
+        return
+
+    run_cmd(["git", "commit", "-m", f"fix: resolve nix evaluation warnings ({warning_hash})"])
+    run_cmd(["git", "push", "origin", branch, "--force"])
+
+    body = f"""## Nix Evaluation Warnings
+
+Detected in [build_systems run]({run_url}):
+
+```
+{warning_text}
+```
+
+## LLM Analysis (qwen3-coder:30b)
+
+{reasoning}
+
+---
+*Auto-generated by fix_eval_warnings. Review carefully before merging.*"""
+
+    run_cmd(
+        [
+            "gh",
+            "pr",
+            "create",
+            "--title",
+            f"fix: resolve nix eval warnings ({warning_hash})",
+            "--label",
+            "automated",
+            "--label",
+            "eval-warning-fix",
+            "--body",
+            body,
+        ]
+    )
+    logger.info("PR created on branch %s", branch)
+
+
+def main(
+    run_id: Annotated[str, typer.Option("--run-id", help="GitHub Actions run ID")],
+    repo: Annotated[str, typer.Option("--repo", help="GitHub repository (owner/repo)")],
+    ollama_url: Annotated[str, typer.Option("--ollama-url", help="Ollama API base URL")],
+    run_url: Annotated[str, typer.Option("--run-url", help="URL to the triggering build run")],
+    log_level: Annotated[str, typer.Option("--log-level", "-l", help="Log level")] = "INFO",
+) -> None:
+    """Detect Nix evaluation warnings and create PRs with LLM-suggested fixes."""
+    configure_logger(log_level)
+
+    logs = download_logs(run_id, repo)
+    warnings = parse_warnings(logs)
+    if not warnings:
+        return
+
+    warning_hash = compute_warning_hash(warnings)
+    if check_duplicate_pr(warning_hash):
+        return
+
+    files = extract_referenced_files(warnings)
+    llm_response = query_ollama(warnings, files, ollama_url)
+    if not llm_response:
+        return
+
+    changes = parse_changes(llm_response)
+    applied = apply_changes(changes)
+    if applied == 0:
+        logger.info("No changes could be applied")
+        return
+
+    create_pr(warning_hash, warnings, llm_response, run_url)
+
+
+if __name__ == "__main__":
+    typer.run(main)

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

@@ -0,0 +1 @@
+"""Tuya heater control service."""

python/heater/controller.py

@@ -0,0 +1,69 @@
+"""TinyTuya device controller for heater."""
+
+import logging
+
+import tinytuya
+
+from python.heater.models import ActionResult, DeviceConfig, HeaterStatus
+
+logger = logging.getLogger(__name__)
+
+# DPS mapping for heater
+DPS_POWER = "1"  # bool: on/off
+DPS_SETPOINT = "101"  # int: target temp (read-only)
+DPS_STATE = "102"  # str: "Stop", "Heat", etc.
+DPS_UNKNOWN = "104"  # int: unknown
+DPS_ERROR = "108"  # int: last error code
+
+
+class HeaterController:
+    """Controls a Tuya heater device via local network."""
+
+    def __init__(self, config: DeviceConfig) -> None:
+        """Initialize the controller."""
+        self.device = tinytuya.Device(config.device_id, config.ip, config.local_key)
+        self.device.set_version(config.version)
+        self.device.set_socketTimeout(0.5)
+        self.device.set_socketRetryLimit(1)
+
+    def status(self) -> HeaterStatus:
+        """Get current heater status."""
+        data = self.device.status()
+
+        if "Error" in data:
+            logger.error("Device error: %s", data)
+            return HeaterStatus(power=False, raw_dps={"error": data["Error"]})
+
+        dps = data.get("dps", {})
+        return HeaterStatus(
+            power=bool(dps.get(DPS_POWER, False)),
+            setpoint=dps.get(DPS_SETPOINT),
+            state=dps.get(DPS_STATE),
+            error_code=dps.get(DPS_ERROR),
+            raw_dps=dps,
+        )
+
+    def turn_on(self) -> ActionResult:
+        """Turn heater on."""
+        try:
+            self.device.set_value(index=DPS_POWER, value=True)
+            return ActionResult(success=True, action="on", power=True)
+        except Exception as error:
+            logger.exception("Failed to turn on")
+            return ActionResult(success=False, action="on", error=str(error))
+
+    def turn_off(self) -> ActionResult:
+        """Turn heater off."""
+        try:
+            self.device.set_value(index=DPS_POWER, value=False)
+            return ActionResult(success=True, action="off", power=False)
+        except Exception as error:
+            logger.exception("Failed to turn off")
+            return ActionResult(success=False, action="off", error=str(error))
+
+    def toggle(self) -> ActionResult:
+        """Toggle heater power state."""
+        status = self.status()
+        if status.power:
+            return self.turn_off()
+        return self.turn_on()

python/heater/main.py

@@ -0,0 +1,85 @@
+"""FastAPI heater control service."""
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+import typer
+import uvicorn
+from fastapi import FastAPI, HTTPException
+
+from python.common import configure_logger
+from python.heater.controller import HeaterController
+from python.heater.models import ActionResult, DeviceConfig, HeaterStatus
+
+logger = logging.getLogger(__name__)
+
+
+def create_app(config: DeviceConfig) -> FastAPI:
+    """Create FastAPI application."""
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        app.state.controller = HeaterController(config)
+        yield
+
+    app = FastAPI(
+        title="Heater Control API",
+        description="Fast local control for Tuya heater",
+        lifespan=lifespan,
+    )
+
+    @app.get("/status")
+    def get_status() -> HeaterStatus:
+        return app.state.controller.status()
+
+    @app.post("/on")
+    def heater_on() -> ActionResult:
+        result = app.state.controller.turn_on()
+        if not result.success:
+            raise HTTPException(status_code=500, detail=result.error)
+        return result
+
+    @app.post("/off")
+    def heater_off() -> ActionResult:
+        result = app.state.controller.turn_off()
+        if not result.success:
+            raise HTTPException(status_code=500, detail=result.error)
+        return result
+
+    @app.post("/toggle")
+    def heater_toggle() -> ActionResult:
+        result = app.state.controller.toggle()
+        if not result.success:
+            raise HTTPException(status_code=500, detail=result.error)
+        return result
+
+    return app
+
+
+def serve(
+    host: Annotated[str, typer.Option("--host", "-h", help="Host to bind to")],
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to bind to")] = 8124,
+    log_level: Annotated[str, typer.Option("--log-level", "-l", help="Log level")] = "INFO",
+    device_id: Annotated[str | None, typer.Option("--device-id", envvar="TUYA_DEVICE_ID")] = None,
+    device_ip: Annotated[str | None, typer.Option("--device-ip", envvar="TUYA_DEVICE_IP")] = None,
+    local_key: Annotated[str | None, typer.Option("--local-key", envvar="TUYA_LOCAL_KEY")] = None,
+) -> None:
+    """Start the heater control API server."""
+    configure_logger(log_level)
+
+    logger.info("Starting heater control API server")
+
+    if not device_id or not device_ip or not local_key:
+        error = "Must provide device ID, IP, and local key"
+        raise typer.Exit(error)
+
+    config = DeviceConfig(device_id=device_id, ip=device_ip, local_key=local_key)
+
+    app = create_app(config)
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    typer.run(serve)

python/heater/models.py

@@ -0,0 +1,31 @@
+"""Pydantic models for heater API."""
+
+from pydantic import BaseModel, Field
+
+
+class DeviceConfig(BaseModel):
+    """Tuya device configuration."""
+
+    device_id: str
+    ip: str
+    local_key: str
+    version: float = 3.5
+
+
+class HeaterStatus(BaseModel):
+    """Current heater status."""
+
+    power: bool
+    setpoint: int | None = None
+    state: str | None = None  # "Stop", "Heat", etc.
+    error_code: int | None = None
+    raw_dps: dict[str, object] = Field(default_factory=dict)
+
+
+class ActionResult(BaseModel):
+    """Result of a heater action."""
+
+    success: bool
+    action: str
+    power: bool | None = None
+    error: str | None = None

python/orm/__init__.py

@@ -0,0 +1,9 @@
+"""ORM package exports."""
+
+from python.orm.richie.base import RichieBase
+from python.orm.van_inventory.base import VanInventoryBase
+
+__all__ = [
+    "RichieBase",
+    "VanInventoryBase",
+]

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,24 @@
+"""Richie database ORM exports."""
+
+from __future__ import annotations
+
+from python.orm.richie.base import RichieBase, TableBase, TableBaseBig, TableBaseSmall
+from python.orm.richie.contact import (
+    Contact,
+    ContactNeed,
+    ContactRelationship,
+    Need,
+    RelationshipType,
+)
+
+__all__ = [
+    "Contact",
+    "ContactNeed",
+    "ContactRelationship",
+    "Need",
+    "RelationshipType",
+    "RichieBase",
+    "TableBase",
+    "TableBaseBig",
+    "TableBaseSmall",
+]

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

@@ -0,0 +1,168 @@
+"""Contact database models."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from python.orm.richie.base import RichieBase, TableBase
+
+
+class RelationshipType(StrEnum):
+    """Relationship types with default closeness weights.
+
+    Default weight is an integer 1-10 where 10 = closest relationship.
+    Users can override this per-relationship in the UI.
+    """
+
+    SPOUSE = "spouse"
+    PARTNER = "partner"
+    PARENT = "parent"
+    CHILD = "child"
+    SIBLING = "sibling"
+    BEST_FRIEND = "best_friend"
+    GRANDPARENT = "grandparent"
+    GRANDCHILD = "grandchild"
+    AUNT_UNCLE = "aunt_uncle"
+    NIECE_NEPHEW = "niece_nephew"
+    COUSIN = "cousin"
+    IN_LAW = "in_law"
+    CLOSE_FRIEND = "close_friend"
+    FRIEND = "friend"
+    MENTOR = "mentor"
+    MENTEE = "mentee"
+    BUSINESS_PARTNER = "business_partner"
+    COLLEAGUE = "colleague"
+    MANAGER = "manager"
+    DIRECT_REPORT = "direct_report"
+    CLIENT = "client"
+    ACQUAINTANCE = "acquaintance"
+    NEIGHBOR = "neighbor"
+    EX = "ex"
+    OTHER = "other"
+
+    @property
+    def default_weight(self) -> int:
+        """Return the default closeness weight (1-10) for this relationship type."""
+        weights = {
+            RelationshipType.SPOUSE: 10,
+            RelationshipType.PARTNER: 10,
+            RelationshipType.PARENT: 9,
+            RelationshipType.CHILD: 9,
+            RelationshipType.SIBLING: 9,
+            RelationshipType.BEST_FRIEND: 8,
+            RelationshipType.GRANDPARENT: 7,
+            RelationshipType.GRANDCHILD: 7,
+            RelationshipType.AUNT_UNCLE: 7,
+            RelationshipType.NIECE_NEPHEW: 7,
+            RelationshipType.COUSIN: 7,
+            RelationshipType.IN_LAW: 7,
+            RelationshipType.CLOSE_FRIEND: 6,
+            RelationshipType.FRIEND: 6,
+            RelationshipType.MENTOR: 5,
+            RelationshipType.MENTEE: 5,
+            RelationshipType.BUSINESS_PARTNER: 5,
+            RelationshipType.COLLEAGUE: 4,
+            RelationshipType.MANAGER: 4,
+            RelationshipType.DIRECT_REPORT: 4,
+            RelationshipType.CLIENT: 4,
+            RelationshipType.ACQUAINTANCE: 3,
+            RelationshipType.NEIGHBOR: 3,
+            RelationshipType.EX: 2,
+            RelationshipType.OTHER: 2,
+        }
+        return weights.get(self, 5)
+
+    @property
+    def display_name(self) -> str:
+        """Return a human-readable display name."""
+        return self.value.replace("_", " ").title()
+
+
+class ContactNeed(RichieBase):
+    """Association table: Contact <-> Need."""
+
+    __tablename__ = "contact_need"
+
+    contact_id: Mapped[int] = mapped_column(
+        ForeignKey("main.contact.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    need_id: Mapped[int] = mapped_column(
+        ForeignKey("main.need.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+
+
+class ContactRelationship(RichieBase):
+    """Association table: Contact <-> Contact with relationship type and weight."""
+
+    __tablename__ = "contact_relationship"
+
+    contact_id: Mapped[int] = mapped_column(
+        ForeignKey("main.contact.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    related_contact_id: Mapped[int] = mapped_column(
+        ForeignKey("main.contact.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    relationship_type: Mapped[str] = mapped_column(String(100))
+    closeness_weight: Mapped[int] = mapped_column(default=5)
+
+
+class Contact(TableBase):
+    """Contact model."""
+
+    __tablename__ = "contact"
+
+    name: Mapped[str]
+
+    age: Mapped[int | None]
+    bio: Mapped[str | None]
+    current_job: Mapped[str | None]
+    gender: Mapped[str | None]
+    goals: Mapped[str | None]
+    legal_name: Mapped[str | None]
+    profile_pic: Mapped[str | None]
+    safe_conversation_starters: Mapped[str | None]
+    self_sufficiency_score: Mapped[int | None]
+    social_structure_style: Mapped[str | None]
+    ssn: Mapped[str | None]
+    suffix: Mapped[str | None]
+    timezone: Mapped[str | None]
+    topics_to_avoid: Mapped[str | None]
+
+    needs: Mapped[list[Need]] = relationship(
+        "Need",
+        secondary=ContactNeed.__table__,
+        back_populates="contacts",
+    )
+
+    related_to: Mapped[list[ContactRelationship]] = relationship(
+        "ContactRelationship",
+        foreign_keys=[ContactRelationship.contact_id],
+        cascade="all, delete-orphan",
+    )
+    related_from: Mapped[list[ContactRelationship]] = relationship(
+        "ContactRelationship",
+        foreign_keys=[ContactRelationship.related_contact_id],
+        cascade="all, delete-orphan",
+    )
+
+
+class Need(TableBase):
+    """Need/accommodation model (e.g., light sensitive, ADHD)."""
+
+    __tablename__ = "need"
+
+    name: Mapped[str]
+    description: Mapped[str | None]
+
+    contacts: Mapped[list[Contact]] = relationship(
+        "Contact",
+        secondary=ContactNeed.__table__,
+        back_populates="needs",
+    )

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/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)

python/van_inventory/routers/__init__.py

@@ -0,0 +1,6 @@
+"""Van inventory API routers."""
+
+from python.van_inventory.routers.api import router as api_router
+from python.van_inventory.routers.frontend import router as frontend_router
+
+__all__ = ["api_router", "frontend_router"]

python/van_inventory/routers/api.py

@@ -0,0 +1,314 @@
+"""Van inventory API router."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+from sqlalchemy.orm import selectinload
+
+from python.orm.van_inventory.models import Item, Meal, MealIngredient
+
+if TYPE_CHECKING:
+    from python.van_inventory.dependencies import DbSession
+
+
+# --- Schemas ---
+
+
+class ItemCreate(BaseModel):
+    """Schema for creating an item."""
+
+    name: str
+    quantity: float = Field(default=0, ge=0)
+    unit: str
+    category: str | None = None
+
+
+class ItemUpdate(BaseModel):
+    """Schema for updating an item."""
+
+    name: str | None = None
+    quantity: float | None = Field(default=None, ge=0)
+    unit: str | None = None
+    category: str | None = None
+
+
+class ItemResponse(BaseModel):
+    """Schema for item response."""
+
+    id: int
+    name: str
+    quantity: float
+    unit: str
+    category: str | None
+
+    model_config = {"from_attributes": True}
+
+
+class IngredientCreate(BaseModel):
+    """Schema for adding an ingredient to a meal."""
+
+    item_id: int
+    quantity_needed: float = Field(gt=0)
+
+
+class MealCreate(BaseModel):
+    """Schema for creating a meal."""
+
+    name: str
+    instructions: str | None = None
+    ingredients: list[IngredientCreate] = []
+
+
+class MealUpdate(BaseModel):
+    """Schema for updating a meal."""
+
+    name: str | None = None
+    instructions: str | None = None
+
+
+class IngredientResponse(BaseModel):
+    """Schema for ingredient response."""
+
+    item_id: int
+    item_name: str
+    quantity_needed: float
+    unit: str
+
+    model_config = {"from_attributes": True}
+
+
+class MealResponse(BaseModel):
+    """Schema for meal response."""
+
+    id: int
+    name: str
+    instructions: str | None
+    ingredients: list[IngredientResponse] = []
+
+    model_config = {"from_attributes": True}
+
+    @classmethod
+    def from_meal(cls, meal: Meal) -> MealResponse:
+        """Build a MealResponse from an ORM Meal with loaded ingredients."""
+        return cls(
+            id=meal.id,
+            name=meal.name,
+            instructions=meal.instructions,
+            ingredients=[
+                IngredientResponse(
+                    item_id=mi.item_id,
+                    item_name=mi.item.name,
+                    quantity_needed=mi.quantity_needed,
+                    unit=mi.item.unit,
+                )
+                for mi in meal.ingredients
+            ],
+        )
+
+
+class ShoppingItem(BaseModel):
+    """An item needed for a meal that is short on stock."""
+
+    item_name: str
+    unit: str
+    needed: float
+    have: float
+    short: float
+
+
+class MealAvailability(BaseModel):
+    """Availability status for a meal."""
+
+    meal_id: int
+    meal_name: str
+    can_make: bool
+    missing: list[ShoppingItem] = []
+
+
+# --- Routes ---
+
+router = APIRouter(prefix="/api", tags=["van_inventory"])
+
+
+# Items
+
+
+@router.post("/items", response_model=ItemResponse)
+def create_item(item: ItemCreate, db: DbSession) -> Item:
+    """Create a new inventory item."""
+    db_item = Item(**item.model_dump())
+    db.add(db_item)
+    db.commit()
+    db.refresh(db_item)
+    return db_item
+
+
+@router.get("/items", response_model=list[ItemResponse])
+def list_items(db: DbSession) -> list[Item]:
+    """List all inventory items."""
+    return list(db.scalars(select(Item).order_by(Item.name)).all())
+
+
+@router.get("/items/{item_id}", response_model=ItemResponse)
+def get_item(item_id: int, db: DbSession) -> Item:
+    """Get an item by ID."""
+    item = db.get(Item, item_id)
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    return item
+
+
+@router.patch("/items/{item_id}", response_model=ItemResponse)
+def update_item(item_id: int, item: ItemUpdate, db: DbSession) -> Item:
+    """Update an item by ID."""
+    db_item = db.get(Item, item_id)
+    if not db_item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    for key, value in item.model_dump(exclude_unset=True).items():
+        setattr(db_item, key, value)
+    db.commit()
+    db.refresh(db_item)
+    return db_item
+
+
+@router.delete("/items/{item_id}")
+def delete_item(item_id: int, db: DbSession) -> dict[str, bool]:
+    """Delete an item by ID."""
+    item = db.get(Item, item_id)
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    db.delete(item)
+    db.commit()
+    return {"deleted": True}
+
+
+# Meals
+
+
+@router.post("/meals", response_model=MealResponse)
+def create_meal(meal: MealCreate, db: DbSession) -> MealResponse:
+    """Create a new meal with optional ingredients."""
+    for ing in meal.ingredients:
+        if not db.get(Item, ing.item_id):
+            raise HTTPException(status_code=422, detail=f"Item {ing.item_id} not found")
+    db_meal = Meal(name=meal.name, instructions=meal.instructions)
+    db.add(db_meal)
+    db.flush()
+    for ing in meal.ingredients:
+        db.add(MealIngredient(meal_id=db_meal.id, item_id=ing.item_id, quantity_needed=ing.quantity_needed))
+    db.commit()
+    db_meal = db.scalar(
+        select(Meal)
+        .where(Meal.id == db_meal.id)
+        .options(selectinload(Meal.ingredients).selectinload(MealIngredient.item))
+    )
+    return MealResponse.from_meal(db_meal)
+
+
+@router.get("/meals", response_model=list[MealResponse])
+def list_meals(db: DbSession) -> list[MealResponse]:
+    """List all meals with ingredients."""
+    meals = list(
+        db.scalars(
+            select(Meal).options(selectinload(Meal.ingredients).selectinload(MealIngredient.item)).order_by(Meal.name)
+        ).all()
+    )
+    return [MealResponse.from_meal(m) for m in meals]
+
+
+@router.get("/meals/availability", response_model=list[MealAvailability])
+def check_all_meals(db: DbSession) -> list[MealAvailability]:
+    """Check which meals can be made with current inventory."""
+    meals = list(
+        db.scalars(select(Meal).options(selectinload(Meal.ingredients).selectinload(MealIngredient.item))).all()
+    )
+    return [_check_meal(m) for m in meals]
+
+
+@router.get("/meals/{meal_id}", response_model=MealResponse)
+def get_meal(meal_id: int, db: DbSession) -> MealResponse:
+    """Get a meal by ID with ingredients."""
+    meal = db.scalar(
+        select(Meal).where(Meal.id == meal_id).options(selectinload(Meal.ingredients).selectinload(MealIngredient.item))
+    )
+    if not meal:
+        raise HTTPException(status_code=404, detail="Meal not found")
+    return MealResponse.from_meal(meal)
+
+
+@router.delete("/meals/{meal_id}")
+def delete_meal(meal_id: int, db: DbSession) -> dict[str, bool]:
+    """Delete a meal by ID."""
+    meal = db.get(Meal, meal_id)
+    if not meal:
+        raise HTTPException(status_code=404, detail="Meal not found")
+    db.delete(meal)
+    db.commit()
+    return {"deleted": True}
+
+
+@router.post("/meals/{meal_id}/ingredients", response_model=MealResponse)
+def add_ingredient(meal_id: int, ingredient: IngredientCreate, db: DbSession) -> MealResponse:
+    """Add an ingredient to a meal."""
+    meal = db.get(Meal, meal_id)
+    if not meal:
+        raise HTTPException(status_code=404, detail="Meal not found")
+    if not db.get(Item, ingredient.item_id):
+        raise HTTPException(status_code=422, detail="Item not found")
+    existing = db.scalar(
+        select(MealIngredient).where(MealIngredient.meal_id == meal_id, MealIngredient.item_id == ingredient.item_id)
+    )
+    if existing:
+        raise HTTPException(status_code=409, detail="Ingredient already exists for this meal")
+    db.add(MealIngredient(meal_id=meal_id, item_id=ingredient.item_id, quantity_needed=ingredient.quantity_needed))
+    db.commit()
+    meal = db.scalar(
+        select(Meal).where(Meal.id == meal_id).options(selectinload(Meal.ingredients).selectinload(MealIngredient.item))
+    )
+    return MealResponse.from_meal(meal)
+
+
+@router.delete("/meals/{meal_id}/ingredients/{item_id}")
+def remove_ingredient(meal_id: int, item_id: int, db: DbSession) -> dict[str, bool]:
+    """Remove an ingredient from a meal."""
+    mi = db.scalar(select(MealIngredient).where(MealIngredient.meal_id == meal_id, MealIngredient.item_id == item_id))
+    if not mi:
+        raise HTTPException(status_code=404, detail="Ingredient not found")
+    db.delete(mi)
+    db.commit()
+    return {"deleted": True}
+
+
+@router.get("/meals/{meal_id}/availability", response_model=MealAvailability)
+def check_meal(meal_id: int, db: DbSession) -> MealAvailability:
+    """Check if a specific meal can be made and what's missing."""
+    meal = db.scalar(
+        select(Meal).where(Meal.id == meal_id).options(selectinload(Meal.ingredients).selectinload(MealIngredient.item))
+    )
+    if not meal:
+        raise HTTPException(status_code=404, detail="Meal not found")
+    return _check_meal(meal)
+
+
+def _check_meal(meal: Meal) -> MealAvailability:
+    missing = [
+        ShoppingItem(
+            item_name=mi.item.name,
+            unit=mi.item.unit,
+            needed=mi.quantity_needed,
+            have=mi.item.quantity,
+            short=mi.quantity_needed - mi.item.quantity,
+        )
+        for mi in meal.ingredients
+        if mi.item.quantity < mi.quantity_needed
+    ]
+    return MealAvailability(
+        meal_id=meal.id,
+        meal_name=meal.name,
+        can_make=len(missing) == 0,
+        missing=missing,
+    )

python/van_inventory/routers/frontend.py

@@ -0,0 +1,198 @@
+"""HTMX frontend routes for van inventory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Form, HTTPException, Request
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+from sqlalchemy import select
+from sqlalchemy.orm import selectinload
+
+from python.orm.van_inventory.models import Item, Meal, MealIngredient
+
+# FastAPI needs DbSession at runtime to resolve the Depends() annotation
+from python.van_inventory.dependencies import DbSession  # noqa: TC001
+from python.van_inventory.routers.api import _check_meal
+
+TEMPLATE_DIR = Path(__file__).resolve().parent.parent / "templates"
+templates = Jinja2Templates(directory=TEMPLATE_DIR)
+
+router = APIRouter(tags=["frontend"])
+
+
+# --- Items ---
+
+
+@router.get("/", response_class=HTMLResponse)
+def items_page(request: Request, db: DbSession) -> HTMLResponse:
+    """Render the inventory page."""
+    items = list(db.scalars(select(Item).order_by(Item.name)).all())
+    return templates.TemplateResponse(request, "items.html", {"items": items})
+
+
+@router.post("/items", response_class=HTMLResponse)
+def htmx_create_item(
+    request: Request,
+    db: DbSession,
+    name: Annotated[str, Form()],
+    quantity: Annotated[float, Form()] = 0,
+    unit: Annotated[str, Form()] = "",
+    category: Annotated[str | None, Form()] = None,
+) -> HTMLResponse:
+    """Create an item and return updated item rows."""
+    if quantity < 0:
+        raise HTTPException(status_code=422, detail="Quantity must not be negative")
+    db.add(Item(name=name, quantity=quantity, unit=unit, category=category or None))
+    db.commit()
+    items = list(db.scalars(select(Item).order_by(Item.name)).all())
+    return templates.TemplateResponse(request, "partials/item_rows.html", {"items": items})
+
+
+@router.patch("/items/{item_id}", response_class=HTMLResponse)
+def htmx_update_item(
+    request: Request,
+    item_id: int,
+    db: DbSession,
+    quantity: Annotated[float, Form()],
+) -> HTMLResponse:
+    """Update an item's quantity and return updated item rows."""
+    if quantity < 0:
+        raise HTTPException(status_code=422, detail="Quantity must not be negative")
+    item = db.get(Item, item_id)
+    if item:
+        item.quantity = quantity
+        db.commit()
+    items = list(db.scalars(select(Item).order_by(Item.name)).all())
+    return templates.TemplateResponse(request, "partials/item_rows.html", {"items": items})
+
+
+@router.delete("/items/{item_id}", response_class=HTMLResponse)
+def htmx_delete_item(request: Request, item_id: int, db: DbSession) -> HTMLResponse:
+    """Delete an item and return updated item rows."""
+    item = db.get(Item, item_id)
+    if item:
+        db.delete(item)
+        db.commit()
+    items = list(db.scalars(select(Item).order_by(Item.name)).all())
+    return templates.TemplateResponse(request, "partials/item_rows.html", {"items": items})
+
+
+# --- Meals ---
+
+
+def _load_meals(db: DbSession) -> list[Meal]:
+    return list(
+        db.scalars(
+            select(Meal).options(selectinload(Meal.ingredients).selectinload(MealIngredient.item)).order_by(Meal.name)
+        ).all()
+    )
+
+
+@router.get("/meals", response_class=HTMLResponse)
+def meals_page(request: Request, db: DbSession) -> HTMLResponse:
+    """Render the meals page."""
+    meals = _load_meals(db)
+    return templates.TemplateResponse(request, "meals.html", {"meals": meals})
+
+
+@router.post("/meals", response_class=HTMLResponse)
+def htmx_create_meal(
+    request: Request,
+    db: DbSession,
+    name: Annotated[str, Form()],
+    instructions: Annotated[str | None, Form()] = None,
+) -> HTMLResponse:
+    """Create a meal and return updated meal rows."""
+    db.add(Meal(name=name, instructions=instructions or None))
+    db.commit()
+    meals = _load_meals(db)
+    return templates.TemplateResponse(request, "partials/meal_rows.html", {"meals": meals})
+
+
+@router.delete("/meals/{meal_id}", response_class=HTMLResponse)
+def htmx_delete_meal(request: Request, meal_id: int, db: DbSession) -> HTMLResponse:
+    """Delete a meal and return updated meal rows."""
+    meal = db.get(Meal, meal_id)
+    if meal:
+        db.delete(meal)
+        db.commit()
+    meals = _load_meals(db)
+    return templates.TemplateResponse(request, "partials/meal_rows.html", {"meals": meals})
+
+
+# --- Meal detail ---
+
+
+def _load_meal(db: DbSession, meal_id: int) -> Meal | None:
+    return db.scalar(
+        select(Meal).where(Meal.id == meal_id).options(selectinload(Meal.ingredients).selectinload(MealIngredient.item))
+    )
+
+
+@router.get("/meals/{meal_id}", response_class=HTMLResponse)
+def meal_detail_page(request: Request, meal_id: int, db: DbSession) -> HTMLResponse:
+    """Render the meal detail page."""
+    meal = _load_meal(db, meal_id)
+    if not meal:
+        raise HTTPException(status_code=404, detail="Meal not found")
+    items = list(db.scalars(select(Item).order_by(Item.name)).all())
+    return templates.TemplateResponse(request, "meal_detail.html", {"meal": meal, "items": items})
+
+
+@router.post("/meals/{meal_id}/ingredients", response_class=HTMLResponse)
+def htmx_add_ingredient(
+    request: Request,
+    meal_id: int,
+    db: DbSession,
+    item_id: Annotated[int, Form()],
+    quantity_needed: Annotated[float, Form()],
+) -> HTMLResponse:
+    """Add an ingredient to a meal and return updated ingredient rows."""
+    if quantity_needed <= 0:
+        raise HTTPException(status_code=422, detail="Quantity must be positive")
+    meal = db.get(Meal, meal_id)
+    if not meal:
+        raise HTTPException(status_code=404, detail="Meal not found")
+    if not db.get(Item, item_id):
+        raise HTTPException(status_code=422, detail="Item not found")
+    existing = db.scalar(
+        select(MealIngredient).where(MealIngredient.meal_id == meal_id, MealIngredient.item_id == item_id)
+    )
+    if existing:
+        raise HTTPException(status_code=409, detail="Ingredient already exists for this meal")
+    db.add(MealIngredient(meal_id=meal_id, item_id=item_id, quantity_needed=quantity_needed))
+    db.commit()
+    meal = _load_meal(db, meal_id)
+    return templates.TemplateResponse(request, "partials/ingredient_rows.html", {"meal": meal})
+
+
+@router.delete("/meals/{meal_id}/ingredients/{item_id}", response_class=HTMLResponse)
+def htmx_remove_ingredient(
+    request: Request,
+    meal_id: int,
+    item_id: int,
+    db: DbSession,
+) -> HTMLResponse:
+    """Remove an ingredient from a meal and return updated ingredient rows."""
+    mi = db.scalar(select(MealIngredient).where(MealIngredient.meal_id == meal_id, MealIngredient.item_id == item_id))
+    if mi:
+        db.delete(mi)
+        db.commit()
+    meal = _load_meal(db, meal_id)
+    return templates.TemplateResponse(request, "partials/ingredient_rows.html", {"meal": meal})
+
+
+# --- Availability ---
+
+
+@router.get("/availability", response_class=HTMLResponse)
+def availability_page(request: Request, db: DbSession) -> HTMLResponse:
+    """Render the meal availability page."""
+    meals = list(
+        db.scalars(select(Meal).options(selectinload(Meal.ingredients).selectinload(MealIngredient.item))).all()
+    )
+    availability = [_check_meal(m) for m in meals]
+    return templates.TemplateResponse(request, "availability.html", {"availability": availability})

python/van_inventory/static/style.css

@@ -0,0 +1,212 @@
+:root {
+    --neon-pink: #ff2a6d;
+    --neon-cyan: #05d9e8;
+    --neon-yellow: #f9f002;
+    --neon-purple: #d300c5;
+    --bg-dark: #0a0a0f;
+    --bg-panel: #0d0d1a;
+    --bg-input: #111128;
+    --border: #1a1a3e;
+    --text: #c0c0d0;
+    --text-dim: #8e8ea0;
+}
+
+* { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+    font-family: 'Share Tech Mono', monospace;
+    max-width: 900px;
+    margin: 0 auto;
+    padding: 1rem;
+    background: var(--bg-dark);
+    color: var(--text);
+    position: relative;
+}
+
+/* Scanline overlay */
+body::before {
+    content: '';
+    position: fixed;
+    top: 0; left: 0; right: 0; bottom: 0;
+    background: repeating-linear-gradient(
+        0deg,
+        transparent,
+        transparent 2px,
+        rgba(0, 0, 0, 0.08) 2px,
+        rgba(0, 0, 0, 0.08) 4px
+    );
+    pointer-events: none;
+    z-index: 9999;
+}
+
+h1, h2, h3 {
+    font-family: 'Orbitron', sans-serif;
+    margin-bottom: 0.5rem;
+    color: var(--neon-cyan);
+    text-shadow: 0 0 10px rgba(5, 217, 232, 0.5), 0 0 40px rgba(5, 217, 232, 0.2);
+    text-transform: uppercase;
+    letter-spacing: 2px;
+}
+
+a { color: var(--neon-pink); text-decoration: none; transition: all 0.2s; }
+a:hover {
+    text-shadow: 0 0 8px rgba(255, 42, 109, 0.8), 0 0 20px rgba(255, 42, 109, 0.4);
+}
+
+nav {
+    display: flex;
+    gap: 1.5rem;
+    padding: 1rem 0;
+    border-bottom: 1px solid var(--border);
+    margin-bottom: 1.5rem;
+    position: relative;
+}
+nav::after {
+    content: '';
+    position: absolute;
+    bottom: -1px;
+    left: 0;
+    right: 0;
+    height: 1px;
+    background: linear-gradient(90deg, var(--neon-pink), var(--neon-cyan), var(--neon-purple));
+    opacity: 0.6;
+}
+nav a {
+    font-family: 'Orbitron', sans-serif;
+    font-weight: 700;
+    font-size: 0.85rem;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+    padding: 0.3rem 0;
+    border-bottom: 2px solid transparent;
+    transition: all 0.2s;
+}
+nav a:hover {
+    border-bottom-color: var(--neon-pink);
+    text-shadow: 0 0 8px rgba(255, 42, 109, 0.8);
+}
+
+table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 1rem 0;
+    border: 1px solid var(--border);
+}
+th, td {
+    text-align: left;
+    padding: 0.6rem 0.75rem;
+    border-bottom: 1px solid var(--border);
+}
+th {
+    font-family: 'Orbitron', sans-serif;
+    color: var(--neon-cyan);
+    font-size: 0.7rem;
+    text-transform: uppercase;
+    letter-spacing: 2px;
+    background: var(--bg-panel);
+    border-bottom: 1px solid var(--neon-cyan);
+    text-shadow: 0 0 6px rgba(5, 217, 232, 0.3);
+}
+tr:hover td {
+    background: rgba(5, 217, 232, 0.03);
+}
+
+form {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    align-items: end;
+    margin: 1rem 0;
+    padding: 1rem;
+    border: 1px solid var(--border);
+    background: var(--bg-panel);
+}
+
+input, select {
+    padding: 0.5rem 0.6rem;
+    border: 1px solid var(--border);
+    border-radius: 2px;
+    background: var(--bg-input);
+    color: var(--neon-cyan);
+    font-family: 'Share Tech Mono', monospace;
+    transition: all 0.2s;
+}
+input:focus, select:focus {
+    outline: none;
+    border-color: var(--neon-cyan);
+    box-shadow: 0 0 8px rgba(5, 217, 232, 0.3), inset 0 0 8px rgba(5, 217, 232, 0.05);
+}
+
+button {
+    padding: 0.5rem 1.2rem;
+    border: 1px solid var(--neon-pink);
+    border-radius: 2px;
+    background: transparent;
+    color: var(--neon-pink);
+    cursor: pointer;
+    font-family: 'Orbitron', sans-serif;
+    font-weight: 700;
+    font-size: 0.7rem;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+    transition: all 0.2s;
+}
+button:hover {
+    background: var(--neon-pink);
+    color: var(--bg-dark);
+    box-shadow: 0 0 15px rgba(255, 42, 109, 0.5), 0 0 30px rgba(255, 42, 109, 0.2);
+}
+button.danger {
+    border-color: var(--text-dim);
+    color: var(--text-dim);
+}
+button.danger:hover {
+    border-color: var(--neon-pink);
+    background: var(--neon-pink);
+    color: var(--bg-dark);
+    box-shadow: 0 0 15px rgba(255, 42, 109, 0.5);
+}
+
+.badge {
+    display: inline-block;
+    padding: 0.2rem 0.6rem;
+    border-radius: 2px;
+    font-family: 'Orbitron', sans-serif;
+    font-size: 0.65rem;
+    font-weight: 700;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+}
+.badge.yes {
+    background: rgba(5, 217, 232, 0.1);
+    color: var(--neon-cyan);
+    border: 1px solid var(--neon-cyan);
+    text-shadow: 0 0 6px rgba(5, 217, 232, 0.5);
+}
+.badge.no {
+    background: rgba(255, 42, 109, 0.1);
+    color: var(--neon-pink);
+    border: 1px solid var(--neon-pink);
+    text-shadow: 0 0 6px rgba(255, 42, 109, 0.5);
+}
+
+.missing-list { font-size: 0.85rem; color: var(--text-dim); }
+
+label {
+    font-size: 0.75rem;
+    color: var(--text-dim);
+    display: flex;
+    flex-direction: column;
+    gap: 0.2rem;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+}
+
+.flash {
+    padding: 0.5rem 1rem;
+    margin: 0.5rem 0;
+    border-radius: 2px;
+    background: rgba(5, 217, 232, 0.1);
+    color: var(--neon-cyan);
+    border: 1px solid var(--neon-cyan);
+}

python/van_inventory/templates/availability.html

@@ -0,0 +1,30 @@
+{% extends "base.html" %}
+{% block title %}What Can I Make? - Van{% endblock %}
+{% block content %}
+<h1>What Can I Make?</h1>
+
+<table>
+    <thead>
+        <tr><th>Meal</th><th>Status</th><th>Missing</th></tr>
+    </thead>
+    <tbody>
+    {% for meal in availability %}
+        <tr>
+            <td><a href="/meals/{{ meal.meal_id }}">{{ meal.meal_name }}</a></td>
+            <td>
+                {% if meal.can_make %}
+                    <span class="badge yes">Ready</span>
+                {% else %}
+                    <span class="badge no">Missing items</span>
+                {% endif %}
+            </td>
+            <td class="missing-list">
+                {% for m in meal.missing %}
+                    {{ m.item_name }}: need {{ m.short }} more {{ m.unit }}{% if not loop.last %}, {% endif %}
+                {% endfor %}
+            </td>
+        </tr>
+    {% endfor %}
+    </tbody>
+</table>
+{% endblock %}

python/van_inventory/templates/base.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}Van Inventory{% endblock %}</title>
+    <script src="https://unpkg.com/htmx.org@2.0.4"></script>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link href="https://fonts.googleapis.com/css2?family=Orbitron:wght@400;700;900&family=Share+Tech+Mono&display=swap" rel="stylesheet">
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <nav>
+        <a href="/">Inventory</a>
+        <a href="/meals">Meals</a>
+        <a href="/availability">What Can I Make?</a>
+    </nav>
+    {% block content %}{% endblock %}
+</body>
+</html>

python/van_inventory/templates/items.html

@@ -0,0 +1,17 @@
+{% extends "base.html" %}
+{% block title %}Inventory - Van{% endblock %}
+{% block content %}
+<h1>Van Inventory</h1>
+
+<form hx-post="/items" hx-target="#item-list" hx-swap="innerHTML" hx-on::after-request="if(event.detail.successful) this.reset()">
+    <label>Name <input type="text" name="name" required></label>
+    <label>Qty <input type="number" name="quantity" step="any" value="0" min="0" required></label>
+    <label>Unit <input type="text" name="unit" required placeholder="lbs, cans, etc"></label>
+    <label>Category <input type="text" name="category" placeholder="optional"></label>
+    <button type="submit">Add Item</button>
+</form>
+
+<div id="item-list">
+    {% include "partials/item_rows.html" %}
+</div>
+{% endblock %}

python/van_inventory/templates/meal_detail.html

@@ -0,0 +1,24 @@
+{% extends "base.html" %}
+{% block title %}{{ meal.name }} - Van{% endblock %}
+{% block content %}
+<h1>{{ meal.name }}</h1>
+{% if meal.instructions %}<p>{{ meal.instructions }}</p>{% endif %}
+
+<h2>Ingredients</h2>
+<form hx-post="/meals/{{ meal.id }}/ingredients" hx-target="#ingredient-list" hx-swap="innerHTML" hx-on::after-request="if(event.detail.successful) this.reset()">
+    <label>Item
+        <select name="item_id" required>
+            <option value="">--</option>
+            {% for item in items %}
+            <option value="{{ item.id }}">{{ item.name }} ({{ item.unit }})</option>
+            {% endfor %}
+        </select>
+    </label>
+    <label>Qty needed <input type="number" name="quantity_needed" step="any" min="0.01" required></label>
+    <button type="submit">Add</button>
+</form>
+
+<div id="ingredient-list">
+    {% include "partials/ingredient_rows.html" %}
+</div>
+{% endblock %}

python/van_inventory/templates/meals.html

@@ -0,0 +1,15 @@
+{% extends "base.html" %}
+{% block title %}Meals - Van{% endblock %}
+{% block content %}
+<h1>Meals</h1>
+
+<form hx-post="/meals" hx-target="#meal-list" hx-swap="innerHTML" hx-on::after-request="if(event.detail.successful) this.reset()">
+    <label>Name <input type="text" name="name" required></label>
+    <label>Instructions <input type="text" name="instructions" placeholder="optional"></label>
+    <button type="submit">Add Meal</button>
+</form>
+
+<div id="meal-list">
+    {% include "partials/meal_rows.html" %}
+</div>
+{% endblock %}

python/van_inventory/templates/partials/ingredient_rows.html

@@ -0,0 +1,16 @@
+<table>
+    <thead>
+        <tr><th>Item</th><th>Needed</th><th>Have</th><th>Unit</th><th></th></tr>
+    </thead>
+    <tbody>
+    {% for mi in meal.ingredients %}
+        <tr>
+            <td>{{ mi.item.name }}</td>
+            <td>{{ mi.quantity_needed }}</td>
+            <td>{{ mi.item.quantity }}</td>
+            <td>{{ mi.item.unit }}</td>
+            <td><button class="danger" hx-delete="/meals/{{ meal.id }}/ingredients/{{ mi.item_id }}" hx-target="#ingredient-list" hx-swap="innerHTML" hx-confirm="Remove {{ mi.item.name }}?">X</button></td>
+        </tr>
+    {% endfor %}
+    </tbody>
+</table>

python/van_inventory/templates/partials/item_rows.html

@@ -0,0 +1,21 @@
+<table>
+    <thead>
+        <tr><th>Name</th><th>Qty</th><th>Unit</th><th>Category</th><th></th></tr>
+    </thead>
+    <tbody>
+    {% for item in items %}
+        <tr>
+            <td>{{ item.name }}</td>
+            <td>
+                <form hx-patch="/items/{{ item.id }}" hx-target="#item-list" hx-swap="innerHTML" style="display:inline; margin:0;">
+                    <input type="number" name="quantity" value="{{ item.quantity }}" step="any" min="0" style="width:5rem">
+                    <button type="submit" style="padding:0.2rem 0.5rem; font-size:0.8rem;">Update</button>
+                </form>
+            </td>
+            <td>{{ item.unit }}</td>
+            <td>{{ item.category or "" }}</td>
+            <td><button class="danger" hx-delete="/items/{{ item.id }}" hx-target="#item-list" hx-swap="innerHTML" hx-confirm="Delete {{ item.name }}?">X</button></td>
+        </tr>
+    {% endfor %}
+    </tbody>
+</table>

python/van_inventory/templates/partials/meal_rows.html

@@ -0,0 +1,15 @@
+<table>
+    <thead>
+        <tr><th>Name</th><th>Ingredients</th><th>Instructions</th><th></th></tr>
+    </thead>
+    <tbody>
+    {% for meal in meals %}
+        <tr>
+            <td><a href="/meals/{{ meal.id }}">{{ meal.name }}</a></td>
+            <td>{{ meal.ingredients | length }}</td>
+            <td>{{ (meal.instructions or "")[:50] }}</td>
+            <td><button class="danger" hx-delete="/meals/{{ meal.id }}" hx-target="#meal-list" hx-swap="innerHTML" hx-confirm="Delete {{ meal.name }}?">X</button></td>
+        </tr>
+    {% endfor %}
+    </tbody>
+</table>

python/van_weather/__init__.py

@@ -0,0 +1 @@
+"""Van weather service - fetches weather with masked GPS location."""

python/van_weather/main.py

@@ -0,0 +1,293 @@
+"""Van weather service - fetches weather with masked GPS for privacy."""
+
+import logging
+from datetime import UTC, datetime
+from typing import Annotated, Any
+
+import httpx
+import typer
+from apscheduler.schedulers.blocking import BlockingScheduler
+from tenacity import before_sleep_log, retry, stop_after_attempt, wait_fixed
+
+from python.common import configure_logger
+from python.van_weather.models import Config, DailyForecast, HourlyForecast, Weather
+
+# Map Pirate Weather icons to Home Assistant conditions
+CONDITION_MAP = {
+    "clear-day": "sunny",
+    "clear-night": "clear-night",
+    "rain": "rainy",
+    "snow": "snowy",
+    "sleet": "snowy-rainy",
+    "wind": "windy",
+    "fog": "fog",
+    "cloudy": "cloudy",
+    "partly-cloudy-day": "partlycloudy",
+    "partly-cloudy-night": "partlycloudy",
+}
+
+logger = logging.getLogger(__name__)
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_fixed(5),
+    before_sleep=before_sleep_log(logger, logging.WARNING),
+    reraise=True,
+)
+def get_ha_state(url: str, token: str, entity_id: str) -> float:
+    """Get numeric state from Home Asasistant entity."""
+    response = httpx.get(
+        f"{url}/api/states/{entity_id}",
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=30,
+    )
+    response.raise_for_status()
+    state = response.json()["state"]
+    if state in ("unavailable", "unknown"):
+        error = f"{entity_id} is {state}"
+        raise ValueError(error)
+    return float(state)
+
+
+def parse_daily_forecast(data: dict[str, dict[str, Any]]) -> list[DailyForecast]:
+    """Parse daily forecast from Pirate Weather API."""
+    daily = data.get("daily", {}).get("data", [])
+    daily_forecasts = []
+    for day in daily[:8]:  # Up to 8 days
+        time_stamp = day.get("time")
+        if time_stamp:
+            date_time = datetime.fromtimestamp(time_stamp, tz=UTC).isoformat()
+            daily_forecasts.append(
+                DailyForecast(
+                    date_time=date_time,
+                    condition=CONDITION_MAP.get(day.get("icon", ""), "cloudy"),
+                    temperature=day.get("temperatureHigh"),
+                    templow=day.get("temperatureLow"),
+                    precipitation_probability=day.get("precipProbability"),
+                    moon_phase=day.get("moonPhase"),
+                    wind_gust=day.get("windGust"),
+                    cloud_cover=day.get("cloudCover"),
+                )
+            )
+
+    return daily_forecasts
+
+
+def parse_hourly_forecast(data: dict[str, dict[str, Any]]) -> list[HourlyForecast]:
+    """Parse hourly forecast from Pirate Weather API."""
+    hourly = data.get("hourly", {}).get("data", [])
+    hourly_forecasts = []
+    for hour in hourly[:48]:  # Up to 48 hours
+        time_stamp = hour.get("time")
+        if time_stamp:
+            date_time = datetime.fromtimestamp(time_stamp, tz=UTC).isoformat()
+            hourly_forecasts.append(
+                HourlyForecast(
+                    date_time=date_time,
+                    condition=CONDITION_MAP.get(hour.get("icon", ""), "cloudy"),
+                    temperature=hour.get("temperature"),
+                    precipitation_probability=hour.get("precipProbability"),
+                )
+            )
+    return hourly_forecasts
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_fixed(5),
+    before_sleep=before_sleep_log(logger, logging.WARNING),
+    reraise=True,
+)
+def fetch_weather(api_key: str, lat: float, lon: float) -> Weather:
+    """Fetch weather from Pirate Weather API."""
+    url = f"https://api.pirateweather.net/forecast/{api_key}/{lat},{lon}"
+    response = httpx.get(url, params={"units": "us"}, timeout=30)
+    response.raise_for_status()
+    data = response.json()
+
+    daily_forecasts = parse_daily_forecast(data)
+    hourly_forecasts = parse_hourly_forecast(data)
+
+    current = data.get("currently", {})
+    icon = current.get("icon", "")
+    return Weather(
+        temperature=current.get("temperature"),
+        feels_like=current.get("apparentTemperature"),
+        humidity=current.get("humidity"),
+        wind_speed=current.get("windSpeed"),
+        wind_bearing=current.get("windBearing"),
+        condition=CONDITION_MAP.get(icon, "cloudy"),
+        summary=current.get("summary"),
+        pressure=current.get("pressure"),
+        visibility=current.get("visibility"),
+        uv_index=current.get("uvIndex"),
+        ozone=current.get("ozone"),
+        nearest_storm_distance=current.get("nearestStormDistance"),
+        nearest_storm_bearing=current.get("nearestStormBearing"),
+        precip_probability=current.get("precipProbability"),
+        cloud_cover=current.get("cloudCover"),
+        daily_forecasts=daily_forecasts,
+        hourly_forecasts=hourly_forecasts,
+    )
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_fixed(5),
+    before_sleep=before_sleep_log(logger, logging.WARNING),
+    reraise=True,
+)
+def post_to_ha(url: str, token: str, weather: Weather) -> None:
+    """Post weather data to Home Assistant as sensor entities."""
+    headers = {"Authorization": f"Bearer {token}"}
+
+    # Post current weather as individual sensors
+    sensors = {
+        "sensor.van_weather_condition": {
+            "state": weather.condition or "unknown",
+            "attributes": {"friendly_name": "Van Weather Condition"},
+        },
+        "sensor.van_weather_temperature": {
+            "state": weather.temperature,
+            "attributes": {"unit_of_measurement": "°F", "device_class": "temperature"},
+        },
+        "sensor.van_weather_apparent_temperature": {
+            "state": weather.feels_like,
+            "attributes": {"unit_of_measurement": "°F", "device_class": "temperature"},
+        },
+        "sensor.van_weather_humidity": {
+            "state": int((weather.humidity or 0) * 100),
+            "attributes": {"unit_of_measurement": "%", "device_class": "humidity"},
+        },
+        "sensor.van_weather_pressure": {
+            "state": weather.pressure,
+            "attributes": {"unit_of_measurement": "mbar", "device_class": "pressure"},
+        },
+        "sensor.van_weather_wind_speed": {
+            "state": weather.wind_speed,
+            "attributes": {"unit_of_measurement": "mph", "device_class": "wind_speed"},
+        },
+        "sensor.van_weather_wind_bearing": {
+            "state": weather.wind_bearing,
+            "attributes": {"unit_of_measurement": "°"},
+        },
+        "sensor.van_weather_visibility": {
+            "state": weather.visibility,
+            "attributes": {"unit_of_measurement": "mi"},
+        },
+        "sensor.van_weather_uv_index": {
+            "state": weather.uv_index,
+            "attributes": {"friendly_name": "Van Weather UV Index", "icon": "mdi:sun-wireless"},
+        },
+        "sensor.van_weather_ozone": {
+            "state": weather.ozone,
+            "attributes": {"unit_of_measurement": "DU", "icon": "mdi:earth"},
+        },
+        "sensor.van_weather_nearest_storm_distance": {
+            "state": weather.nearest_storm_distance,
+            "attributes": {"unit_of_measurement": "mi", "icon": "mdi:weather-lightning"},
+        },
+        "sensor.van_weather_nearest_storm_bearing": {
+            "state": weather.nearest_storm_bearing,
+            "attributes": {"unit_of_measurement": "°", "icon": "mdi:weather-lightning"},
+        },
+        "sensor.van_weather_precip_probability": {
+            "state": int((weather.precip_probability or 0) * 100),
+            "attributes": {"unit_of_measurement": "%", "icon": "mdi:weather-rainy"},
+        },
+        "sensor.van_weather_cloud_cover": {
+            "state": int((weather.cloud_cover or 0) * 100),
+            "attributes": {"unit_of_measurement": "%", "icon": "mdi:weather-cloudy"},
+        },
+    }
+
+    for entity_id, data in sensors.items():
+        if data["state"] is not None:
+            response = httpx.post(f"{url}/api/states/{entity_id}", headers=headers, json=data, timeout=30)
+            response.raise_for_status()
+
+    # Post daily forecast as JSON attribute sensor
+    daily_forecast = [
+        {
+            "datetime": daily_forecast.date_time.isoformat(),
+            "condition": daily_forecast.condition,
+            "temperature": daily_forecast.temperature,
+            "templow": daily_forecast.templow,
+            "precipitation_probability": int((daily_forecast.precipitation_probability or 0) * 100),
+        }
+        for daily_forecast in weather.daily_forecasts
+    ]
+
+    response = httpx.post(
+        f"{url}/api/states/sensor.van_weather_forecast_daily",
+        headers=headers,
+        json={"state": len(daily_forecast), "attributes": {"forecast": daily_forecast}},
+        timeout=30,
+    )
+    response.raise_for_status()
+
+    # Post hourly forecast as JSON attribute sensor
+    hourly_forecast = [
+        {
+            "datetime": hourly_forecast.date_time.isoformat(),
+            "condition": hourly_forecast.condition,
+            "temperature": hourly_forecast.temperature,
+            "precipitation_probability": int((hourly_forecast.precipitation_probability or 0) * 100),
+        }
+        for hourly_forecast in weather.hourly_forecasts
+    ]
+
+    response = httpx.post(
+        f"{url}/api/states/sensor.van_weather_forecast_hourly",
+        headers=headers,
+        json={"state": len(hourly_forecast), "attributes": {"forecast": hourly_forecast}},
+        timeout=30,
+    )
+    response.raise_for_status()
+
+
+def update_weather(config: Config) -> None:
+    """Fetch weather using last-known location, post to HA."""
+    lat = get_ha_state(config.ha_url, config.ha_token, config.lat_entity)
+    lon = get_ha_state(config.ha_url, config.ha_token, config.lon_entity)
+
+    masked_lat = round(lat, config.mask_decimals)
+    masked_lon = round(lon, config.mask_decimals)
+
+    logger.info(f"Masked location: {masked_lat}, {masked_lon}")
+
+    weather = fetch_weather(config.pirate_weather_api_key, lat, lon)
+    logger.info(f"Weather: {weather.temperature}°F, {weather.condition}")
+
+    post_to_ha(config.ha_url, config.ha_token, weather)
+    logger.info("Posted weather to HA")
+
+
+def main(
+    ha_url: Annotated[str, typer.Option(envvar="HA_URL")],
+    ha_token: Annotated[str, typer.Option(envvar="HA_TOKEN")],
+    api_key: Annotated[str, typer.Option(envvar="PIRATE_WEATHER_API_KEY")],
+    interval: Annotated[int, typer.Option(help="Poll interval in seconds")] = 900,
+    log_level: Annotated[str, typer.Option()] = "INFO",
+) -> None:
+    """Fetch weather for van using masked GPS location."""
+    configure_logger(log_level)
+
+    config = Config(ha_url=ha_url, ha_token=ha_token, pirate_weather_api_key=api_key)
+
+    logger.info(f"Starting van weather service, polling every {interval}s")
+
+    scheduler = BlockingScheduler()
+    scheduler.add_job(
+        update_weather,
+        "interval",
+        seconds=interval,
+        args=[config],
+        next_run_time=datetime.now(UTC),
+    )
+    scheduler.start()
+
+
+if __name__ == "__main__":
+    typer.run(main)

python/van_weather/models.py

@@ -0,0 +1,70 @@
+"""Models for van weather service."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, field_serializer
+
+
+class Config(BaseModel):
+    """Service configuration."""
+
+    ha_url: str
+    ha_token: str
+    pirate_weather_api_key: str
+    lat_entity: str = "sensor.van_last_known_latitude"
+    lon_entity: str = "sensor.van_last_known_longitude"
+    mask_decimals: int = 1  # ~11km accuracy
+
+
+class DailyForecast(BaseModel):
+    """Daily forecast entry."""
+
+    date_time: datetime
+    condition: str | None = None
+    temperature: float | None = None  # High
+    templow: float | None = None  # Low
+    precipitation_probability: float | None = None
+    moon_phase: float | None = None
+    wind_gust: float | None = None
+    cloud_cover: float | None = None
+
+    @field_serializer("date_time")
+    def serialize_date_time(self, date_time: datetime) -> str:
+        """Serialize datetime to ISO format."""
+        return date_time.isoformat()
+
+
+class HourlyForecast(BaseModel):
+    """Hourly forecast entry."""
+
+    date_time: datetime
+    condition: str | None = None
+    temperature: float | None = None
+    precipitation_probability: float | None = None
+
+    @field_serializer("date_time")
+    def serialize_date_time(self, date_time: datetime) -> str:
+        """Serialize datetime to ISO format."""
+        return date_time.isoformat()
+
+
+class Weather(BaseModel):
+    """Weather data from Pirate Weather."""
+
+    temperature: float | None = None
+    feels_like: float | None = None
+    humidity: float | None = None
+    wind_speed: float | None = None
+    wind_bearing: float | None = None
+    condition: str | None = None
+    summary: str | None = None
+    pressure: float | None = None
+    visibility: float | None = None
+    uv_index: float | None = None
+    ozone: float | None = None
+    nearest_storm_distance: float | None = None
+    nearest_storm_bearing: float | None = None
+    precip_probability: float | None = None
+    cloud_cover: float | None = None
+    daily_forecasts: list[DailyForecast] = []
+    hourly_forecasts: list[HourlyForecast] = []

systems/bob/default.nix

@@ -1,12 +1,13 @@
-{ inputs, ... }:
+{ inputs, pkgs, ... }:
 {
   imports = [
+    "${inputs.self}/users/math"
     "${inputs.self}/users/richie"
-    "${inputs.self}/users/gaming"
+    "${inputs.self}/users/steve"
     "${inputs.self}/common/global"
-    "${inputs.self}/common/optional/desktop.nix"
     "${inputs.self}/common/optional/docker.nix"
     "${inputs.self}/common/optional/scanner.nix"
+    "${inputs.self}/common/optional/monitoring-agent.nix"
     "${inputs.self}/common/optional/steam.nix"
     "${inputs.self}/common/optional/syncthing_base.nix"
     "${inputs.self}/common/optional/systemd-boot.nix"
@@ -19,23 +20,24 @@
     ./llms.nix
   ];
 
+  boot = {
+    kernelPackages = pkgs.linuxPackages_6_18;
+    zfs.package = pkgs.zfs_2_4;
+  };
+
   networking = {
     hostName = "bob";
     hostId = "7c678a41";
-    firewall.enable = true;
+    firewall = {
+      enable = true;
+      allowedTCPPorts = [
+        8000
+      ];
+    };
     networkmanager.enable = true;
   };
 
   services = {
-    displayManager = {
-      enable = true;
-      autoLogin = {
-        user = "gaming";
-        enable = true;
-      };
-      defaultSession = "plasma";
-    };
-
     openssh.ports = [ 262 ];
 
     snapshot_manager.path = ./snapshot_config.toml;

systems/bob/hardware.nix

@@ -28,9 +28,13 @@
         allowDiscards = true;
         keyFileSize = 4096;
         keyFile = "/dev/disk/by-id/usb-Samsung_Flash_Drive_FIT_0374620080067131-0:0";
-        fallbackToPassword = true;
       };
     };
+
+    zfs.extraPools = [
+      "storage"
+    ];
+
     kernelModules = [ "kvm-amd" ];
     extraModulePackages = [ ];
   };

systems/bob/llms.nix

@@ -1,27 +1,55 @@
 {
-  services = {
+  services.ollama = {
-    ollama = {
+    user = "ollama";
-      user = "ollama";
+    host = "0.0.0.0";
-      enable = true;
+    enable = true;
-      loadModels = [
+
-        "codellama:7b"
+    syncModels = true;
-        "deepseek-r1:8b"
+    loadModels = [
-        "deepseek-r1:14b"
+      "codellama:7b"
-        "deepseek-r1:32b"
+      "deepscaler:1.5b"
-        "llama3.2:3b"
+      "deepseek-r1:14b"
-        "llama2-uncensored:7b"
+      "deepseek-r1:32b"
-        "mistral-nemo:12b"
+      "deepseek-r1:8b"
-        "dolphin-mixtral:8x7b"
+      "devstral-small-2:24b"
-        "qwq:32b"
+      "dolphin-llama3:8b"
-        "Qihoo360-Light-R1-32B"
+      "functiongemma:270m"
-      ];
+      "gemma3:12b"
-      models = "/zfs/models";
+      "gemma3:27b"
-      openFirewall = true;
+      "glm-4.7-flash:q4_K_M"
-    };
+      "gpt-oss:20b"
-    # open-webui = {
+      "huihui_ai/dolphin3-abliterated:8b"
-    #   enable = true;
+      "lfm2:24b"
-    #   openFirewall = true;
+      "magistral:24b"
-    #   host = "0.0.0.0";
+      "ministral-3:14b"
-    # };
+      "nemotron-3-nano:30b"
+      "nemotron-3-nano:4b"
+      "nemotron-cascade-2:30b"
+      "qwen3-coder:30b"
+      "qwen3-embedding:0.6b"
+      "qwen3-embedding:4b"
+      "qwen3-embedding:8b"
+      "qwen3-vl:2b"
+      "qwen3-vl:32b"
+      "qwen3-vl:4b"
+      "qwen3-vl:8b"
+      "qwen3:0.6b"
+      "qwen3:1.7b"
+      "qwen3:14b"
+      "qwen3:30b"
+      "qwen3:32b"
+      "qwen3:4b"
+      "qwen3:8b"
+      "qwen3.5:27b"
+      "qwen3.5:35b"
+      "qwen3.6:27b"
+      "qwen3.6:35b"
+      "rinex20/translategemma3:12b"
+      "translategemma:12b"
+      "translategemma:27b"
+      "translategemma:4b"
+    ];
+    models = "/zfs/storage/models";
+    openFirewall = true;
   };
 }

systems/bob/syncthing.nix

@@ -31,5 +31,15 @@
       ];
       fsWatcherEnabled = true;
     };
+    "recordings" = {
+      path = "/home/richie/recordings";
+      devices = [
+        "jeeves"
+        "phone"
+        "rhapsody-in-green"
+      ];
+      fsWatcherEnabled = true;
+    };
+
   };
 }

systems/brain/hardware.nix

@@ -26,7 +26,6 @@
         allowDiscards = true;
         keyFileSize = 4096;
         keyFile = "/dev/disk/by-id/usb-USB_SanDisk_3.2Gen1_03021630090925173333-0:0";
-        fallbackToPassword = true;
       };
     };
     kernelModules = [ "kvm-intel" ];

systems/brain/services/heater.nix

@@ -0,0 +1,33 @@
+{
+  pkgs,
+  inputs,
+  ...
+}:
+{
+  networking.firewall.allowedTCPPorts = [ 8124 ];
+
+  systemd.services.heater-api = {
+    description = "Tuya Heater Control API";
+    after = [ "network.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    environment = {
+      PYTHONPATH = "${inputs.self}/";
+    };
+
+    serviceConfig = {
+      Type = "simple";
+      ExecStart = "${pkgs.my_python}/bin/python -m python.heater.main --host 0.0.0.0 --port 8124";
+      EnvironmentFile = "/etc/heater.env";
+      Restart = "on-failure";
+      RestartSec = "5s";
+      StandardOutput = "journal";
+      StandardError = "journal";
+      NoNewPrivileges = true;
+      ProtectSystem = "strict";
+      ProtectHome = "read-only";
+      PrivateTmp = true;
+      ReadOnlyPaths = [ "${inputs.self}" ];
+    };
+  };
+}

systems/brain/services/home_assistant.nix

@@ -1,3 +1,4 @@
+{ pkgs, ... }:
 {
   users = {
     users.hass = {
@@ -12,14 +13,7 @@
       enable = true;
       openFirewall = true;
       config = {
-        http = {
+        http.server_port = 8123;
-          server_port = 8123;
-          server_host = [
-            "192.168.90.35"
-            "192.168.95.35"
-            "127.0.0.1"
-          ];
-        };
         homeassistant = {
           time_zone = "America/New_York";
           unit_system = "us_customary";
@@ -27,6 +21,10 @@
           packages = {
             victron_modbuss = "!include ${./home_assistant/victron_modbuss.yaml}";
             battery_sensors = "!include ${./home_assistant/battery_sensors.yaml}";
+            gps_location = "!include ${./home_assistant/gps_location.yaml}";
+            heater = "!include ${./home_assistant/heater.yaml}";
+            van_weather = "!include ${./home_assistant/van_weather_template.yaml}";
+            status_indicator = "!include ${./home_assistant/status_indicator.yaml}";
           };
         };
         recorder = {
@@ -72,10 +70,17 @@
           py-improv-ble-client # for esphome
           pymodbus # for modbus
           pyopenweathermap # for weather
+          pymetno # for met.no weather
           uiprotect # for ubiquiti integration
           unifi-discovery # for ubiquiti integration
+          jsonpath # for rest sensors
+          typedmonarchmoney # for monarch
         ];
       extraComponents = [ "isal" ];
+      customComponents = with pkgs.home-assistant-custom-components; [
+        pirate-weather
+      ];
+
     };
     esphome = {
       enable = true;

systems/brain/services/home_assistant/dashboard_overview.yaml

@@ -0,0 +1,122 @@
+title: Van Overview
+views:
+  - title: Overview
+    path: overview
+    type: sections
+    sections:
+      # Battery Status Section
+      - type: grid
+        title: Battery Status
+        cards:
+          - type: gauge
+            entity: sensor.jk0_soc
+            name: Battery 0
+            min: 0
+            max: 100
+            severity:
+              green: 50
+              yellow: 20
+              red: 0 
+            needle: true
+
+          - type: gauge
+            entity: sensor.jk1_soc
+            name: Battery 1
+            min: 0
+            max: 100
+            severity:
+              green: 50
+              yellow: 20
+              red: 0
+            needle: true
+
+          - type: entity
+            entity: sensor.jk0_total_voltage
+            name: Batt 0 Voltage
+
+          - type: entity
+            entity: sensor.jk1_total_voltage
+            name: Batt 1 Voltage
+
+      # Solar Production Section
+      - type: grid
+        title: Solar Production
+        cards:
+          - type: gauge
+            entity: sensor.solar_wattage
+            name: Solar Now
+            min: 0
+            max: 400
+            severity:
+              green: 100
+              yellow: 50
+              red: 0
+            needle: true
+
+          - type: entity
+            entity: sensor.solar_yield_today
+            name: Today's Yield
+
+          - type: entity
+            entity: sensor.estimated_energy_production_today
+            name: Forecast Today
+
+          - type: entity
+            entity: sensor.estimated_energy_production_tomorrow
+            name: Forecast Tomorrow
+
+      # Environment Section
+      - type: grid
+        title: Van Environment
+        cards:
+          - type: entity
+            entity: sensor.environment_temperature
+            name: Inside Temp
+
+          - type: entity
+            entity: sensor.environment_humidity
+            name: Inside Humidity
+
+          - type: entity
+            entity: sensor.current_weather_temperature
+            name: Outside Temp
+
+          - type: entity
+            entity: sensor.current_weather_humidity
+            name: Outside Humidity
+
+          - type: entity
+            entity: sensor.current_weather_condition
+            name: Weather
+
+      # Charger Status Section
+      - type: grid
+        title: Charger
+        cards:
+          - type: entity
+            entity: sensor.charger_dc_wattage
+            name: Charging Power
+
+          - type: entity
+            entity: sensor.charger_charge_state
+            name: Charge State
+
+          - type: entity
+            entity: sensor.charger_dc_wattage_daily
+            name: Charged Today
+
+      # Location Section
+      - type: grid
+        title: Location
+        cards:
+          - type: entity
+            entity: sensor.gps_location
+            name: Current Location
+
+          - type: entity
+            entity: sensor.gps_speed
+            name: Speed
+
+          - type: entity
+            entity: binary_sensor.gps_fix_available
+            name: GPS Fix