setting up bluesky firehose

Flake lock file updates:

• Updated input 'firefox-addons':
    'gitlab:rycee/nur-expressions/07e1616?dir=pkgs/firefox-addons' (2026-03-06)
  → 'gitlab:rycee/nur-expressions/81e28f4?dir=pkgs/firefox-addons' (2026-03-20)
• Updated input 'home-manager':
    'github:nix-community/home-manager/daa2c22' (2026-03-06)
  → 'github:nix-community/home-manager/9670de2' (2026-03-20)
• Updated input 'nixos-hardware':
    'github:nixos/nixos-hardware/41c6b42' (2026-02-24)
  → 'github:nixos/nixos-hardware/2d4b471' (2026-03-20)
• Updated input 'nixpkgs':
    'github:nixos/nixpkgs/80bdc1e' (2026-03-04)
  → 'github:nixos/nixpkgs/b40629e' (2026-03-18)
• Updated input 'nixpkgs-master':
    'github:nixos/nixpkgs/af5157a' (2026-03-07)
  → 'github:nixos/nixpkgs/8620c0b' (2026-03-21)
• Updated input 'sops-nix':
    'github:Mic92/sops-nix/1d9b98a' (2026-03-02)
  → 'github:Mic92/sops-nix/29b6519' (2026-03-19)

.github/workflows/build_systems.yml

@@ -25,4 +25,4 @@ jobs:
       - name: Build default package
         run: "nixos-rebuild build --flake ./#${{ matrix.system }}"
       - name: copy to nix-cache
-        run: nix copy --to ssh://jeeves .#nixosConfigurations.${{ matrix.system }}.config.system.build.toplevel
+        run: nix copy --accept-flake-config --to unix:///host-nix/var/nix/daemon-socket/socket .#nixosConfigurations.${{ matrix.system }}.config.system.build.toplevel

.github/workflows/fix_eval_warnings.yml

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

.gitignore

@@ -165,3 +165,7 @@ test.*
 
 # syncthing
 .stfolder
+
+# Frontend build output
+frontend/dist/
+frontend/node_modules/

.vscode/settings.json

@@ -77,11 +77,11 @@
     "esphome",
     "extest",
     "fadvise",
+    "fastfetch",
     "fastforwardteam",
     "FASTFOX",
     "ffmpegthumbnailer",
     "filebot",
-    "filebrowser",
     "fileroller",
     "findbar",
     "Fira",
@@ -98,6 +98,7 @@
     "getch",
     "getmaxyx",
     "ghdeploy",
+    "gitea",
     "globalprivacycontrol",
     "gparted",
     "gtts",
@@ -116,7 +117,9 @@
     "httpchk",
     "hurlenko",
     "hwloc",
+    "ical",
     "ignorelist",
+    "improv",
     "INITDB",
     "iocharset",
     "ioit",
@@ -126,6 +129,8 @@
     "jnoortheen",
     "jsbc",
     "kagi",
+    "keyformat",
+    "keylocation",
     "kuma",
     "lazer",
     "levelname",
@@ -162,7 +167,6 @@
     "mypy",
     "ncdu",
     "nemo",
-    "neofetch",
     "nerdfonts",
     "netdev",
     "netdevs",
@@ -225,12 +229,10 @@
     "pylint",
     "pymetno",
     "pymodbus",
+    "pyopenweathermap",
     "pyownet",
     "pytest",
-    "qbit",
-    "qbittorrent",
-    "qbittorrentvpn",
-    "qbitvpn",
+    "qalculate",
     "quicksuggest",
     "radarr",
     "readahead",
@@ -255,6 +257,7 @@
     "sessionmaker",
     "sessionstore",
     "shellcheck",
+    "signalbot",
     "signon",
     "Signons",
     "skia",
@@ -286,11 +289,14 @@
     "topstories",
     "treefmt",
     "twimg",
+    "typedmonarchmoney",
     "typer",
     "uaccess",
+    "ubiquiti",
     "ublock",
     "uiprotect",
     "uitour",
+    "unifi",
     "unrar",
     "unsubmitted",
     "uptimekuma",
@@ -301,6 +307,7 @@
     "useragent",
     "usernamehw",
     "userprefs",
+    "vaninventory",
     "vfat",
     "victron",
     "virt",

AGENTS.md

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

common/global/default.nix

@@ -22,23 +22,8 @@
 
   boot = {
     tmp.useTmpfs = true;
-    kernelPackages = lib.mkDefault (
-      pkgs.linuxPackages_6_12.extend (
-        self: super: {
-          kernel = super.kernel.override {
-            argsOverride = {
-              version = "6.12.52";
-              modDirVersion = "6.12.52";
-              src = pkgs.fetchurl {
-                url = "https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.12.52.tar.xz";
-                sha256 = "sha256-tIUM9nCgMscPOLcTon1iBGxfdHyvAoxfULGPmGBqnrE=";
-              };
-            };
-          };
-        }
-      )
-    );
-    zfs.package = lib.mkDefault pkgs.zfs_2_3;
+    kernelPackages = lib.mkDefault pkgs.linuxPackages_6_12;
+    zfs.package = lib.mkDefault pkgs.zfs_2_4;
   };
 
   hardware.enableRedistributableFirmware = true;

common/global/nix.nix

@@ -33,6 +33,8 @@ in
       ];
       warn-dirty = false;
       flake-registry = ""; # disable global flake registries
+      connect-timeout = 10;
+      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/desktop.nix

@@ -1,8 +1,8 @@
 { pkgs, ... }:
 {
   boot = {
-    kernelPackages = pkgs.linuxPackages_6_17;
-    zfs.package = pkgs.zfs_unstable;
+    kernelPackages = pkgs.linuxPackages_6_18;
+    zfs.package = pkgs.zfs_2_4;
   };
 
   hardware.bluetooth = {

esphome/batteries.yml

@@ -1,129 +0,0 @@
-esphome:
-  name: batteries
-  friendly_name: batteries
-
-esp32:
-  board: esp32dev
-  framework:
-    type: arduino
-
-logger:
-
-api:
-  encryption:
-    key: !secret api_key
-
-external_components:
-  - source: github://syssi/esphome-jk-bms@main
-
-ota:
-  - platform: esphome
-    password: !secret ota_password
-
-wifi:
-  ssid: !secret wifi_ssid
-  password: !secret wifi_password
-
-captive_portal:
-
-esp32_ble_tracker:
-  scan_parameters:
-    interval: 1100ms
-    window: 1100ms
-    active: true
-
-ble_client:
-  - mac_address: "C8:47:80:29:0F:DB"
-    id: jk_ble0
-  - mac_address: "C8:47:80:37:9D:DD"
-    id: jk_ble1
-
-jk_bms_ble:
-  - ble_client_id: jk_ble0
-    protocol_version: JK02_32S
-    throttle: 1s
-    id: jk_bms0
-
-  - ble_client_id: jk_ble1
-    protocol_version: JK02_32S
-    throttle: 1s
-    id: jk_bms1
-
-sensor:
-  # BMS1 sensors
-  - platform: jk_bms_ble
-    jk_bms_ble_id: jk_bms0
-    total_voltage:
-      name: "JK0 Total Voltage"
-    current:
-      name: "JK0 Current"
-    state_of_charge:
-      name: "JK0 SoC"
-    power:
-      name: "JK0 Power"
-    temperature_sensor_1:
-      name: "JK0 Temp 1"
-    temperature_sensor_2:
-      name: "JK0 Temp 2"
-    balancing:
-      name: "JK0 balancing"
-    charging_cycles:
-      name: "JK0 charging cycles"
-    total_runtime:
-      name: "JK0 total runtime"
-    balancing_current:
-      name: "JK0 balancing current"
-
-  # BMS2 sensors
-  - platform: jk_bms_ble
-    jk_bms_ble_id: jk_bms1
-    total_voltage:
-      name: "JK1 Total Voltage"
-    current:
-      name: "JK1 Current"
-    state_of_charge:
-      name: "JK1 SoC"
-    power:
-      name: "Jk1 Power"
-    temperature_sensor_1:
-      name: "JK1 Temp 1"
-    temperature_sensor_2:
-      name: "Jk1 Temp 2"
-    balancing:
-      name: "JK1 balancing"
-    charging_cycles:
-      name: "JK1 charging cycles"
-    total_runtime:
-      name: "JK1 total runtime"
-    balancing_current:
-      name: "JK1 balancing current"
-
-text_sensor:
-  - platform: jk_bms_ble
-    jk_bms_ble_id: jk_bms0
-    errors:
-      name: "JK0 Errors"
-
-  - platform: jk_bms_ble
-    jk_bms_ble_id: jk_bms1
-    errors:
-      name: "JK1 Errors"
-
-switch:
-  - platform: jk_bms_ble
-    jk_bms_ble_id: jk_bms0
-    charging:
-      name: "JK0 Charging"
-    discharging:
-      name: "JK0 Discharging"
-    balancer:
-      name: "JK0 Balancing"
-
-  - platform: jk_bms_ble
-    jk_bms_ble_id: jk_bms1
-    charging:
-      name: "JK1 Charging"
-    discharging:
-      name: "JK1 Discharging"
-    balancer:
-      name: "JK1 Balancing"

esphome/battery0.yml

@@ -0,0 +1,132 @@
+esphome:
+  name: batteries
+  friendly_name: batteries
+
+esp32:
+  board: esp32dev
+  framework:
+    type: arduino
+
+logger:
+
+api:
+  encryption:
+    key: !secret api_key
+
+external_components:
+  - source: github://syssi/esphome-jk-bms@main
+
+ota:
+  - platform: esphome
+    password: !secret ota_password
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  fast_connect: on
+
+captive_portal:
+
+esp32_ble_tracker:
+  scan_parameters:
+    interval: 1100ms
+    window: 1100ms
+    active: true
+
+ble_client:
+  - mac_address: "C8:47:80:29:0F:DB"
+    id: jk_ble0
+
+jk_bms_ble:
+  - ble_client_id: jk_ble0
+    protocol_version: JK02_32S
+    throttle: 1s
+    id: jk_bms0
+
+button:
+  - platform: jk_bms_ble
+    retrieve_settings:
+      name: "JK0 retrieve settings"
+    retrieve_device_info:
+      name: "JK0 retrieve device info"
+
+sensor:
+  - platform: jk_bms_ble
+    jk_bms_ble_id: jk_bms0
+    total_voltage:
+      name: "JK0 Total Voltage"
+    state_of_charge:
+      name: "JK0 SoC"
+    charging_power:
+      name: "JK0 charging power"
+    discharging_power:
+      name: "JK0 discharging power"
+    temperature_sensor_1:
+      name: "JK0 Temp 1"
+    temperature_sensor_2:
+      name: "JK0 Temp 2"
+    balancing:
+      name: "JK0 balancing"
+    total_runtime:
+      name: "JK0 total runtime"
+    balancing_current:
+      name: "JK0 balancing current"
+    delta_cell_voltage:
+      name: "JK0 cell delta voltage"
+    average_cell_voltage:
+      name: "JK0 cell average voltage"
+    cell_voltage_1:
+      name: "JK0 cell voltage 1"
+    cell_voltage_2:
+      name: "JK0 cell voltage 2"
+    cell_voltage_3:
+      name: "JK0 cell voltage 3"
+    cell_voltage_4:
+      name: "JK0 cell voltage 4"
+    cell_voltage_5:
+      name: "JK0 cell voltage 5"
+    cell_voltage_6:
+      name: "JK0 cell voltage 6"
+    cell_voltage_7:
+      name: "JK0 cell voltage 7"
+    cell_voltage_8:
+      name: "JK0 cell voltage 8"
+    cell_resistance_1:
+      name: "JK0 cell resistance 1"
+    cell_resistance_2:
+      name: "JK0 cell resistance 2"
+    cell_resistance_3:
+      name: "JK0 cell resistance 3"
+    cell_resistance_4:
+      name: "JK0 cell resistance 4"
+    cell_resistance_5:
+      name: "JK0 cell resistance 5"
+    cell_resistance_6:
+      name: "JK0 cell resistance 6"
+    cell_resistance_7:
+      name: "JK0 cell resistance 7"
+    cell_resistance_8:
+      name: "JK0 cell resistance 8"
+    total_charging_cycle_capacity:
+      name: "JK0 total charging cycle capacity"
+
+text_sensor:
+  - platform: jk_bms_ble
+    jk_bms_ble_id: jk_bms0
+    errors:
+      name: "JK0 Errors"
+
+switch:
+  - platform: jk_bms_ble
+    jk_bms_ble_id: jk_bms0
+    charging:
+      name: "JK0 Charging"
+    discharging:
+      name: "JK0 Discharging"
+    balancer:
+      name: "JK0 Balancing"
+
+  - platform: ble_client
+    ble_client_id: jk_ble0
+    name: "JK0 enable bluetooth connection"
+    id: ble_client_switch0

esphome/battery1.yml

@@ -0,0 +1,132 @@
+esphome:
+  name: battery1
+  friendly_name: battery1
+
+esp32:
+  board: esp32dev
+  framework:
+    type: arduino
+
+logger:
+
+api:
+  encryption:
+    key: !secret api_key
+
+external_components:
+  - source: github://syssi/esphome-jk-bms@main
+
+ota:
+  - platform: esphome
+    password: !secret ota_password
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  fast_connect: on
+
+captive_portal:
+
+esp32_ble_tracker:
+  scan_parameters:
+    interval: 1100ms
+    window: 1100ms
+    active: true
+
+ble_client:
+  - mac_address: "C8:47:80:37:9D:DD"
+    id: jk_ble1
+
+jk_bms_ble:
+  - ble_client_id: jk_ble1
+    protocol_version: JK02_32S
+    throttle: 1s
+    id: jk_bms1
+
+button:
+  - platform: jk_bms_ble
+    retrieve_settings:
+      name: "JK1 retrieve settings"
+    retrieve_device_info:
+      name: "JK1 retrieve device info"
+
+sensor:
+  - platform: jk_bms_ble
+    jk_bms_ble_id: jk_bms1
+    total_voltage:
+      name: "JK1 Total Voltage"
+    state_of_charge:
+      name: "JK1 SoC"
+    charging_power:
+      name: "JK1 charging power"
+    discharging_power:
+      name: "JK1 discharging power"
+    temperature_sensor_1:
+      name: "JK1 Temp 1"
+    temperature_sensor_2:
+      name: "JK1 Temp 2"
+    balancing:
+      name: "JK1 balancing"
+    total_runtime:
+      name: "JK1 total runtime"
+    balancing_current:
+      name: "JK1 balancing current"
+    delta_cell_voltage:
+      name: "JK1 cell delta voltage"
+    average_cell_voltage:
+      name: "JK1 cell average voltage"
+    cell_voltage_1:
+      name: "JK1 cell voltage 1"
+    cell_voltage_2:
+      name: "JK1 cell voltage 2"
+    cell_voltage_3:
+      name: "JK1 cell voltage 3"
+    cell_voltage_4:
+      name: "JK1 cell voltage 4"
+    cell_voltage_5:
+      name: "JK1 cell voltage 5"
+    cell_voltage_6:
+      name: "JK1 cell voltage 6"
+    cell_voltage_7:
+      name: "JK1 cell voltage 7"
+    cell_voltage_8:
+      name: "JK1 cell voltage 8"
+    cell_resistance_1:
+      name: "JK1 cell resistance 1"
+    cell_resistance_2:
+      name: "JK1 cell resistance 2"
+    cell_resistance_3:
+      name: "JK1 cell resistance 3"
+    cell_resistance_4:
+      name: "JK1 cell resistance 4"
+    cell_resistance_5:
+      name: "JK1 cell resistance 5"
+    cell_resistance_6:
+      name: "JK1 cell resistance 6"
+    cell_resistance_7:
+      name: "JK1 cell resistance 7"
+    cell_resistance_8:
+      name: "JK1 cell resistance 8"
+    total_charging_cycle_capacity:
+      name: "JK1 total charging cycle capacity"
+
+text_sensor:
+  - platform: jk_bms_ble
+    jk_bms_ble_id: jk_bms1
+    errors:
+      name: "JK1 Errors"
+
+switch:
+  - platform: jk_bms_ble
+    jk_bms_ble_id: jk_bms1
+    charging:
+      name: "JK1 Charging"
+    discharging:
+      name: "JK1 Discharging"
+    balancer:
+      name: "JK1 Balancing"
+
+  - platform: ble_client
+    ble_client_id: jk_ble1
+    name: "JK1 enable bluetooth connection"
+    id: ble_client_switch0

esphome/environment.yml

@@ -0,0 +1,48 @@
+esphome:
+  name: "environment"
+  friendly_name: "environment"
+
+esp32:
+  board: esp32dev
+  framework:
+    type: arduino
+
+i2c:
+  sda: GPIO21
+  scl: GPIO22
+  scan: True
+  id: bus_a
+
+sensor:
+  - platform: aht10
+    i2c_id: bus_a
+    address: 0x38
+    variant: AHT20
+    temperature:
+      name: "environment Temperature"
+      id: aht10_temperature
+    humidity:
+      name: "environment Humidity"
+      id: aht10_humidity
+    update_interval: 5s
+
+web_server:
+  port: 80
+
+logger:
+  level: DEBUG
+
+api:
+  encryption:
+    key: !secret api_key
+
+ota:
+  - platform: esphome
+    password: !secret ota_password
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  fast_connect: on
+
+captive_portal:

flake.lock

@@ -8,11 +8,11 @@
       },
       "locked": {
         "dir": "pkgs/firefox-addons",
-        "lastModified": 1763697825,
-        "narHash": "sha256-AgCCcVPOi1tuzuW5/StlwqBjRWSX62oL97qWuxrq5UA=",
+        "lastModified": 1773979456,
+        "narHash": "sha256-9kBMJ5IvxqNlkkj/swmE8uK1Sc7TL/LIRUI958m7uBM=",
         "owner": "rycee",
         "repo": "nur-expressions",
-        "rev": "cefce78793603231be226fa77e7ad58e0e4899b8",
+        "rev": "81e28f47ac18d9e89513929c77e711e657b64851",
         "type": "gitlab"
       },
       "original": {
@@ -29,11 +29,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1763748372,
-        "narHash": "sha256-AUc78Qv3sWir0hvbmfXoZ7Jzq9VVL97l+sP9Jgms+JU=",
+        "lastModified": 1774007980,
+        "narHash": "sha256-FOnZjElEI8pqqCvB6K/1JRHTE8o4rer8driivTpq2uo=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "d10a9b16b2a3ee28433f3d1c603f4e9f1fecb8e1",
+        "rev": "9670de2921812bc4e0452f6e3efd8c859696c183",
         "type": "github"
       },
       "original": {
@@ -44,11 +44,11 @@
     },
     "nixos-hardware": {
       "locked": {
-        "lastModified": 1762847253,
-        "narHash": "sha256-BWWnUUT01lPwCWUvS0p6Px5UOBFeXJ8jR+ZdLX8IbrU=",
+        "lastModified": 1774018263,
+        "narHash": "sha256-HHYEwK1A22aSaxv2ibhMMkKvrDGKGlA/qObG4smrSqc=",
         "owner": "nixos",
         "repo": "nixos-hardware",
-        "rev": "899dc449bc6428b9ee6b3b8f771ca2b0ef945ab9",
+        "rev": "2d4b4717b2534fad5c715968c1cece04a172b365",
         "type": "github"
       },
       "original": {
@@ -60,11 +60,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1763421233,
-        "narHash": "sha256-Stk9ZYRkGrnnpyJ4eqt9eQtdFWRRIvMxpNRf4sIegnw=",
+        "lastModified": 1773821835,
+        "narHash": "sha256-TJ3lSQtW0E2JrznGVm8hOQGVpXjJyXY2guAxku2O9A4=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "89c2b2330e733d6cdb5eae7b899326930c2c0648",
+        "rev": "b40629efe5d6ec48dd1efba650c797ddbd39ace0",
         "type": "github"
       },
       "original": {
@@ -74,29 +74,13 @@
         "type": "github"
       }
     },
-    "nixpkgs-linux-firmware-20251011": {
-      "locked": {
-        "lastModified": 1760099975,
-        "narHash": "sha256-/fXH2TIVxVgmBbPouQNMsEPfUFB8Z9n6T9t40HMeC/k=",
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "rev": "f9430900368d5a7346e30e6ecc7b26c9f7cc35cf",
-        "type": "github"
-      },
-      "original": {
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "rev": "f9430900368d5a7346e30e6ecc7b26c9f7cc35cf",
-        "type": "github"
-      }
-    },
     "nixpkgs-master": {
       "locked": {
-        "lastModified": 1763774007,
-        "narHash": "sha256-PPeHfKA11P09kBkBD5pS3tIAFjnG5muHQnODQGTY87g=",
+        "lastModified": 1774051532,
+        "narHash": "sha256-d3CGMweyYIcPuTj5BKq+1Lx4zwlgL31nVtN647tOZKo=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "8a7cf7e9e18384533d9ecd0bfbcf475ac1dc497e",
+        "rev": "8620c0b5cc8fbe76502442181be1d0514bc3a1b7",
         "type": "github"
       },
       "original": {
@@ -128,7 +112,6 @@
         "home-manager": "home-manager",
         "nixos-hardware": "nixos-hardware",
         "nixpkgs": "nixpkgs",
-        "nixpkgs-linux-firmware-20251011": "nixpkgs-linux-firmware-20251011",
         "nixpkgs-master": "nixpkgs-master",
         "nixpkgs-stable": "nixpkgs-stable",
         "sops-nix": "sops-nix",
@@ -142,11 +125,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1763607916,
-        "narHash": "sha256-VefBA1JWRXM929mBAFohFUtQJLUnEwZ2vmYUNkFnSjE=",
+        "lastModified": 1773889674,
+        "narHash": "sha256-+ycaiVAk3MEshJTg35cBTUa0MizGiS+bgpYw/f8ohkg=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "877bb495a6f8faf0d89fc10bd142c4b7ed2bcc0b",
+        "rev": "29b6519f3e0780452bca0ac0be4584f04ac16cc5",
         "type": "github"
       },
       "original": {

flake.nix

@@ -19,8 +19,6 @@
     nixpkgs-master.url = "github:nixos/nixpkgs/master";
     systems.url = "github:nix-systems/default-linux";
 
-    nixpkgs-linux-firmware-20251011.url = "github:NixOS/nixpkgs/f9430900368d5a7346e30e6ecc7b26c9f7cc35cf";
-
     nixos-hardware.url = "github:nixos/nixos-hardware/master";
 
     home-manager = {
@@ -84,7 +82,6 @@
         jeeves = lib.nixosSystem {
           modules = [
             ./systems/jeeves
-            ./systems/jeeves/linux-firmware-20251011.nix
           ];
           specialArgs = { inherit inputs outputs; };
         };

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

@@ -3,36 +3,48 @@
   # When applied, the stable nixpkgs set (declared in the flake inputs) will be accessible through 'pkgs.stable'
   stable = final: _prev: {
     stable = import inputs.nixpkgs-stable {
-      system = final.system;
+      system = final.stdenv.hostPlatform.system;
       config.allowUnfree = true;
     };
   };
   # When applied, the master nixpkgs set (declared in the flake inputs) will be accessible through 'pkgs.master'
   master = final: _prev: {
     master = import inputs.nixpkgs-master {
-      system = final.system;
+      system = final.stdenv.hostPlatform.system;
       config.allowUnfree = true;
     };
   };
 
   python-env = final: _prev: {
-    my_python = final.python313.withPackages (
+    my_python = final.python314.withPackages (
       ps: with ps; [
+        alembic
         apprise
         apscheduler
+        confluent-kafka
+        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
+        tinytuya
         typer
-        types-requests
+        websockets
       ]
     );
   };

pyproject.toml

@@ -7,7 +7,25 @@ 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"
 
 [dependency-groups]
 dev = [
@@ -18,7 +36,6 @@ dev = [
     "pytest-xdist",
     "pytest",
     "ruff",
-    "types-requests",
 ]
 
 [tool.ruff]
@@ -38,15 +55,38 @@ lint.ignore = [
 [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/eval_warnings/**" = [
+    "S607", # (perm) gh and git are expected on PATH in the runner environment
+]
+"python/alembic/**" = [
+    "INP001", # (perm) this creates LSP issues for alembic
+]
+"python/signal_bot/**" = [
+    "D107", # (perm) class docstrings cover __init__
+]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -70,4 +110,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/data_science_dev/versions/2026_03_24-adding_failedingestion_2f43120e3ffc.py

@@ -0,0 +1,50 @@
+"""adding FailedIngestion.
+
+Revision ID: 2f43120e3ffc
+Revises: f99be864fe69
+Create Date: 2026-03-24 23:46:17.277897
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sqlalchemy as sa
+from alembic import op
+
+from python.orm import DataScienceDevBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "2f43120e3ffc"
+down_revision: str | None = "f99be864fe69"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = DataScienceDevBase.schema_name
+
+
+def upgrade() -> None:
+    """Upgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "failed_ingestion",
+        sa.Column("raw_line", sa.Text(), nullable=False),
+        sa.Column("error", sa.Text(), 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_failed_ingestion")),
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("failed_ingestion", schema=schema)
+    # ### end Alembic commands ###

python/alembic/data_science_dev/versions/2026_03_25-attach_partitions_to_posts.py

@@ -0,0 +1,80 @@
+"""Attach all partition tables to the posts parent table.
+
+Alembic autogenerate creates partition tables as standalone tables but does not
+emit the ALTER TABLE ... ATTACH PARTITION statements needed for PostgreSQL to
+route inserts to the correct partition.
+
+Revision ID: a1b2c3d4e5f6
+Revises: 605b1794838f
+Create Date: 2026-03-25 10:00:00.000000
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from alembic import op
+from sqlalchemy import text
+
+from python.orm import DataScienceDevBase
+from python.orm.data_science_dev.posts.partitions import (
+    PARTITION_END_YEAR,
+    PARTITION_START_YEAR,
+    iso_weeks_in_year,
+    week_bounds,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "a1b2c3d4e5f6"
+down_revision: str | None = "605b1794838f"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = DataScienceDevBase.schema_name
+
+ALREADY_ATTACHED_QUERY = text("""
+    SELECT inhrelid::regclass::text
+    FROM pg_inherits
+    WHERE inhparent = :parent::regclass
+""")
+
+
+def upgrade() -> None:
+    """Attach all weekly partition tables to the posts parent table."""
+    connection = op.get_bind()
+    already_attached = {
+        row[0]
+        for row in connection.execute(
+            ALREADY_ATTACHED_QUERY, {"parent": f"{schema}.posts"}
+        )
+    }
+
+    for year in range(PARTITION_START_YEAR, PARTITION_END_YEAR + 1):
+        for week in range(1, iso_weeks_in_year(year) + 1):
+            table_name = f"posts_{year}_{week:02d}"
+            qualified_name = f"{schema}.{table_name}"
+            if qualified_name in already_attached:
+                continue
+            start, end = week_bounds(year, week)
+            start_str = start.strftime("%Y-%m-%d %H:%M:%S")
+            end_str = end.strftime("%Y-%m-%d %H:%M:%S")
+            op.execute(
+                f"ALTER TABLE {schema}.posts "
+                f"ATTACH PARTITION {qualified_name} "
+                f"FOR VALUES FROM ('{start_str}') TO ('{end_str}')"
+            )
+
+
+def downgrade() -> None:
+    """Detach all weekly partition tables from the posts parent table."""
+    for year in range(PARTITION_START_YEAR, PARTITION_END_YEAR + 1):
+        for week in range(1, iso_weeks_in_year(year) + 1):
+            table_name = f"posts_{year}_{week:02d}"
+            op.execute(
+                f"ALTER TABLE {schema}.posts "
+                f"DETACH PARTITION {schema}.{table_name}"
+            )

python/alembic/env.py

@@ -0,0 +1,123 @@
+"""Alembic."""
+
+from __future__ import annotations
+
+import logging
+import re
+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/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/signal_bot/versions/2026_03_17-seprating_signal_bot_database_6eaf696e07a5.py

@@ -0,0 +1,100 @@
+"""seprating signal_bot database.
+
+Revision ID: 6eaf696e07a5
+Revises:
+Create Date: 2026-03-17 21:35:37.612672
+
+"""
+
+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 SignalBotBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "6eaf696e07a5"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = SignalBotBase.schema_name
+
+
+def upgrade() -> None:
+    """Upgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    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,
+    )
+    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(
+        "signal_device",
+        sa.Column("phone_number", sa.String(length=50), nullable=False),
+        sa.Column("safety_number", sa.String(), nullable=True),
+        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,
+    )
+    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("signal_device", schema=schema)
+    op.drop_table("role", schema=schema)
+    op.drop_table("dead_letter_message", schema=schema)
+    # ### end Alembic commands ###

python/alembic/signal_bot/versions/2026_03_18-test_66bdd532bcab.py

@@ -0,0 +1,72 @@
+"""test.
+
+Revision ID: 66bdd532bcab
+Revises: 6eaf696e07a5
+Create Date: 2026-03-18 19:21:14.561568
+
+"""
+
+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 SignalBotBase
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "66bdd532bcab"
+down_revision: str | None = "6eaf696e07a5"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+schema = SignalBotBase.schema_name
+
+
+def upgrade() -> None:
+    """Upgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column(
+        "dead_letter_message",
+        "status",
+        existing_type=postgresql.ENUM("UNPROCESSED", "PROCESSED", name="message_status", schema=schema),
+        type_=sa.Enum("UNPROCESSED", "PROCESSED", name="message_status", native_enum=False),
+        existing_nullable=False,
+        schema=schema,
+    )
+    op.alter_column(
+        "signal_device",
+        "trust_level",
+        existing_type=postgresql.ENUM("VERIFIED", "UNVERIFIED", "BLOCKED", name="trust_level", schema=schema),
+        type_=sa.Enum("VERIFIED", "UNVERIFIED", "BLOCKED", name="trust_level", native_enum=False),
+        existing_nullable=False,
+        schema=schema,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column(
+        "signal_device",
+        "trust_level",
+        existing_type=sa.Enum("VERIFIED", "UNVERIFIED", "BLOCKED", name="trust_level", native_enum=False),
+        type_=postgresql.ENUM("VERIFIED", "UNVERIFIED", "BLOCKED", name="trust_level", schema=schema),
+        existing_nullable=False,
+        schema=schema,
+    )
+    op.alter_column(
+        "dead_letter_message",
+        "status",
+        existing_type=sa.Enum("UNPROCESSED", "PROCESSED", name="message_status", native_enum=False),
+        type_=postgresql.ENUM("UNPROCESSED", "PROCESSED", name="message_status", schema=schema),
+        existing_nullable=False,
+        schema=schema,
+    )
+    # ### end Alembic commands ###

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

@@ -0,0 +1,3 @@
+"""Data science CLI tools."""
+
+from __future__ import annotations

python/data_science/bluesky_ids.py

@@ -0,0 +1,104 @@
+"""Utilities for converting Bluesky identifiers to numeric database IDs.
+
+Handles DID-to-user_id hashing, TID-to-post_id decoding, and AT-URI parsing.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+TID_CHARSET = "234567abcdefghijklmnopqrstuvwxyz"
+_TID_LENGTH = 13
+_BIGINT_MASK = 0x7FFFFFFFFFFFFFFF
+_AT_URI_SEGMENT_COUNT = 3
+
+
+def did_to_user_id(did: str) -> int:
+    """Convert a DID string to a deterministic 63-bit integer for user_id.
+
+    Uses SHA-256, truncated to 63 bits (positive signed BigInteger range).
+    Collision probability is negligible at Bluesky's scale (~tens of millions of users).
+
+    Args:
+        did: A Bluesky DID string, e.g. "did:plc:abc123".
+
+    Returns:
+        A positive 63-bit integer suitable for BigInteger storage.
+    """
+    digest = hashlib.sha256(did.encode()).digest()
+    return int.from_bytes(digest[:8], "big") & _BIGINT_MASK
+
+
+def tid_to_integer(tid: str) -> int:
+    """Decode a Bluesky TID (base32-sortbase) into a 64-bit integer for post_id.
+
+    TIDs are 13-character, base32-sortbase encoded identifiers that encode a
+    microsecond timestamp plus a clock ID. They are globally unique by construction.
+
+    Args:
+        tid: A 13-character TID string, e.g. "3abc2defghijk".
+
+    Returns:
+        A positive integer suitable for BigInteger storage.
+
+    Raises:
+        ValueError: If the TID is malformed (wrong length or invalid characters).
+    """
+    if len(tid) != _TID_LENGTH:
+        message = f"TID must be {_TID_LENGTH} characters, got {len(tid)}: {tid!r}"
+        raise ValueError(message)
+
+    result = 0
+    for char in tid:
+        index = TID_CHARSET.find(char)
+        if index == -1:
+            message = f"Invalid character {char!r} in TID {tid!r}"
+            raise ValueError(message)
+        result = result * 32 + index
+    return result
+
+
+def parse_at_uri(uri: str) -> tuple[str, str, str]:
+    """Parse an AT-URI into its components.
+
+    Args:
+        uri: An AT-URI string, e.g. "at://did:plc:abc123/app.bsky.feed.post/3abc2defghijk".
+
+    Returns:
+        A tuple of (did, collection, rkey).
+
+    Raises:
+        ValueError: If the URI doesn't have the expected format.
+    """
+    stripped = uri.removeprefix("at://")
+    parts = stripped.split("/", maxsplit=2)
+    if len(parts) != _AT_URI_SEGMENT_COUNT:
+        message = f"Expected {_AT_URI_SEGMENT_COUNT} path segments in AT-URI, got {len(parts)}: {uri!r}"
+        raise ValueError(message)
+    return parts[0], parts[1], parts[2]
+
+
+def post_id_from_uri(uri: str) -> int:
+    """Extract and decode the post_id (TID) from an AT-URI.
+
+    Args:
+        uri: An AT-URI pointing to a post.
+
+    Returns:
+        The post_id as an integer.
+    """
+    _did, _collection, rkey = parse_at_uri(uri)
+    return tid_to_integer(rkey)
+
+
+def user_id_from_uri(uri: str) -> int:
+    """Extract and hash the user_id (DID) from an AT-URI.
+
+    Args:
+        uri: An AT-URI pointing to a post.
+
+    Returns:
+        The user_id as an integer.
+    """
+    did, _collection, _rkey = parse_at_uri(uri)
+    return did_to_user_id(did)

python/data_science/bluesky_transform.py

@@ -0,0 +1,143 @@
+"""Transform Bluesky Jetstream messages into rows matching the Posts table schema."""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+
+from python.data_science.bluesky_ids import (
+    did_to_user_id,
+    post_id_from_uri,
+    tid_to_integer,
+    user_id_from_uri,
+)
+
+logger = logging.getLogger(__name__)
+
+INSTANCE = "bsky"
+POST_COLLECTION = "app.bsky.feed.post"
+EMBED_RECORD_TYPE = "app.bsky.embed.record"
+EMBED_RECORD_WITH_MEDIA_TYPE = "app.bsky.embed.recordWithMedia"
+
+
+def transform_jetstream_post(message: dict) -> dict:
+    """Transform a Jetstream commit message into a dict matching Posts table columns.
+
+    Expects a Jetstream message with kind=commit, operation=create,
+    collection=app.bsky.feed.post.
+
+    Args:
+        message: The full Jetstream JSON message.
+
+    Returns:
+        A dict with keys matching the Posts table columns.
+    """
+    did = message["did"]
+    commit = message["commit"]
+    record = commit["record"]
+
+    row: dict = {
+        "post_id": tid_to_integer(commit["rkey"]),
+        "user_id": did_to_user_id(did),
+        "instance": INSTANCE,
+        "date": datetime.fromisoformat(record["createdAt"]),
+        "text": record.get("text", ""),
+        "langs": _extract_langs(record),
+        "like_count": 0,
+        "reply_count": 0,
+        "repost_count": 0,
+        "reply_to": None,
+        "replied_author": None,
+        "thread_root": None,
+        "thread_root_author": None,
+        "repost_from": None,
+        "reposted_author": None,
+        "quotes": None,
+        "quoted_author": None,
+        "labels": _extract_labels(record),
+        "sent_label": None,
+        "sent_score": None,
+    }
+
+    _extract_reply_refs(record, row)
+    _extract_quote_refs(record, row)
+
+    return row
+
+
+def is_post_create(message: dict) -> bool:
+    """Check if a Jetstream message is a post creation event.
+
+    Args:
+        message: The full Jetstream JSON message.
+
+    Returns:
+        True if this is a create commit for app.bsky.feed.post.
+    """
+    if message.get("kind") != "commit":
+        return False
+    commit = message.get("commit", {})
+    return commit.get("operation") == "create" and commit.get("collection") == POST_COLLECTION
+
+
+def _extract_langs(record: dict) -> str | None:
+    """Extract langs array as a JSON string, or None if absent."""
+    langs = record.get("langs")
+    if langs is None:
+        return None
+    return json.dumps(langs)
+
+
+def _extract_labels(record: dict) -> str | None:
+    """Extract self-labels as a JSON string, or None if absent."""
+    labels_obj = record.get("labels")
+    if labels_obj is None:
+        return None
+    values = labels_obj.get("values", [])
+    if not values:
+        return None
+    label_strings = [label.get("val", "") for label in values]
+    return json.dumps(label_strings)
+
+
+def _extract_reply_refs(record: dict, row: dict) -> None:
+    """Populate reply_to, replied_author, thread_root, thread_root_author from record.reply."""
+    reply = record.get("reply")
+    if reply is None:
+        return
+
+    parent = reply.get("parent", {})
+    parent_uri = parent.get("uri")
+    if parent_uri:
+        row["reply_to"] = post_id_from_uri(parent_uri)
+        row["replied_author"] = user_id_from_uri(parent_uri)
+
+    root = reply.get("root", {})
+    root_uri = root.get("uri")
+    if root_uri:
+        row["thread_root"] = post_id_from_uri(root_uri)
+        row["thread_root_author"] = user_id_from_uri(root_uri)
+
+
+def _extract_quote_refs(record: dict, row: dict) -> None:
+    """Populate quotes and quoted_author from embed record references."""
+    embed = record.get("embed")
+    if embed is None:
+        return
+
+    embed_type = embed.get("$type", "")
+
+    if embed_type == EMBED_RECORD_TYPE:
+        _set_quote_from_record(embed.get("record", {}), row)
+    elif embed_type == EMBED_RECORD_WITH_MEDIA_TYPE:
+        inner_record = embed.get("record", {}).get("record", {})
+        _set_quote_from_record(inner_record, row)
+
+
+def _set_quote_from_record(record_ref: dict, row: dict) -> None:
+    """Set quotes and quoted_author from a record reference object."""
+    uri = record_ref.get("uri")
+    if uri and POST_COLLECTION in uri:
+        row["quotes"] = post_id_from_uri(uri)
+        row["quoted_author"] = user_id_from_uri(uri)

python/data_science/firehose_consumer.py

@@ -0,0 +1,203 @@
+"""Kafka consumer that ingests Bluesky posts into the partitioned Posts table.
+
+Consumes Jetstream messages from Kafka, transforms them into Posts rows,
+and batch-inserts them into PostgreSQL with manual offset commits.
+
+Usage:
+    firehose-consumer
+    firehose-consumer --kafka-servers kafka:9092 --batch-size 500
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import signal
+from os import getenv
+from threading import Event
+from typing import Annotated
+
+import typer
+from confluent_kafka import Consumer, KafkaError, KafkaException
+from sqlalchemy.orm import Session
+
+from python.data_science.bluesky_transform import is_post_create, transform_jetstream_post
+from python.data_science.ingest_posts import ingest_batch
+from python.orm.common import get_postgres_engine
+from python.orm.data_science_dev.posts.failed_ingestion import FailedIngestion
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TOPIC = "bluesky.firehose.posts"
+DEFAULT_KAFKA_SERVERS = "localhost:9092"
+DEFAULT_GROUP_ID = "bluesky-posts-ingestor"
+DEFAULT_BATCH_SIZE = 500
+POLL_TIMEOUT_SECONDS = 5.0
+
+shutdown_event = Event()
+
+app = typer.Typer(help="Consume Bluesky posts from Kafka and ingest into PostgreSQL.")
+
+
+@app.command()
+def main(
+    kafka_servers: Annotated[str, typer.Option(help="Kafka bootstrap servers")] = "",
+    topic: Annotated[str, typer.Option(help="Kafka topic to consume from")] = "",
+    group_id: Annotated[str, typer.Option(help="Kafka consumer group ID")] = "",
+    batch_size: Annotated[int, typer.Option(help="Messages per DB insert batch")] = DEFAULT_BATCH_SIZE,
+) -> None:
+    """Consume Bluesky posts from Kafka and ingest into the partitioned posts table."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    servers = kafka_servers or getenv("KAFKA_BOOTSTRAP_SERVERS", DEFAULT_KAFKA_SERVERS)
+    topic_name = topic or getenv("BLUESKY_FIREHOSE_TOPIC", DEFAULT_TOPIC)
+    group = group_id or getenv("KAFKA_GROUP_ID", DEFAULT_GROUP_ID)
+
+    signal.signal(signal.SIGTERM, _handle_shutdown)
+    signal.signal(signal.SIGINT, _handle_shutdown)
+
+    consumer = _create_consumer(servers, group)
+    consumer.subscribe([topic_name])
+
+    engine = get_postgres_engine(name="DATA_SCIENCE_DEV")
+    total_inserted = 0
+
+    logger.info("Starting firehose consumer: topic=%s group=%s batch_size=%d", topic_name, group, batch_size)
+
+    try:
+        with Session(engine) as session:
+            while not shutdown_event.is_set():
+                inserted = _consume_batch(consumer, session, batch_size)
+                total_inserted += inserted
+                if inserted > 0:
+                    logger.info("Batch inserted %d rows (total: %d)", inserted, total_inserted)
+    except KafkaException:
+        logger.exception("Fatal Kafka error")
+    finally:
+        logger.info("Closing consumer (total inserted: %d)", total_inserted)
+        consumer.close()
+
+
+def _consume_batch(consumer: Consumer, session: Session, batch_size: int) -> int:
+    """Poll a batch of messages, transform, and insert into the database.
+
+    Args:
+        consumer: The Kafka consumer instance.
+        session: SQLAlchemy database session.
+        batch_size: Maximum number of messages to consume per batch.
+
+    Returns:
+        Number of rows successfully inserted.
+    """
+    messages = consumer.consume(num_messages=batch_size, timeout=POLL_TIMEOUT_SECONDS)
+    if not messages:
+        return 0
+
+    rows: list[dict] = []
+    for message in messages:
+        error = message.error()
+        if error is not None:
+            if error.code() == KafkaError._PARTITION_EOF:  # noqa: SLF001 — confluent-kafka exposes this as a pseudo-private constant; no public alternative exists
+                continue
+            logger.error("Consumer error: %s", error)
+            continue
+
+        row = _safe_transform(message.value(), session)
+        if row is not None:
+            rows.append(row)
+
+    if not rows:
+        consumer.commit(asynchronous=False)
+        return 0
+
+    inserted = ingest_batch(session, rows)
+    consumer.commit(asynchronous=False)
+    return inserted
+
+
+def _safe_transform(raw_value: bytes | None, session: Session) -> dict | None:
+    """Transform a Kafka message value into a Posts row, logging failures.
+
+    Args:
+        raw_value: Raw message bytes from Kafka.
+        session: SQLAlchemy session for logging failures.
+
+    Returns:
+        A transformed row dict, or None if transformation failed.
+    """
+    if raw_value is None:
+        return None
+
+    try:
+        message = json.loads(raw_value)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        logger.exception("Failed to decode Kafka message")
+        _log_failed_ingestion(session, raw_value, "JSON decode error")
+        return None
+
+    if not is_post_create(message):
+        return None
+
+    try:
+        return transform_jetstream_post(message)
+    except (KeyError, ValueError, TypeError):
+        logger.exception("Failed to transform Jetstream message")
+        _log_failed_ingestion(session, raw_value, "Transform error")
+        return None
+
+
+def _log_failed_ingestion(session: Session, raw_value: bytes, error: str) -> None:
+    """Log a failed ingestion to the FailedIngestion table.
+
+    Args:
+        session: SQLAlchemy session.
+        raw_value: The raw message bytes.
+        error: Description of the error.
+    """
+    try:
+        session.add(
+            FailedIngestion(
+                raw_line=raw_value.decode(errors="replace")[:10000],
+                error=error,
+            )
+        )
+        session.commit()
+    except Exception:
+        session.rollback()
+        logger.exception("Failed to log ingestion failure")
+
+
+def _create_consumer(servers: str, group: str) -> Consumer:
+    """Create a configured Kafka consumer.
+
+    Args:
+        servers: Kafka bootstrap servers string.
+        group: Consumer group ID.
+
+    Returns:
+        A configured confluent_kafka.Consumer.
+    """
+    config = {
+        "bootstrap.servers": servers,
+        "group.id": group,
+        "auto.offset.reset": "earliest",
+        "enable.auto.commit": False,
+        "max.poll.interval.ms": 300000,
+        "fetch.min.bytes": 1024,
+        "session.timeout.ms": 30000,
+    }
+    return Consumer(config)
+
+
+def _handle_shutdown(_signum: int, _frame: object) -> None:
+    """Signal handler to trigger graceful shutdown."""
+    logger.info("Shutdown signal received")
+    shutdown_event.set()
+
+
+if __name__ == "__main__":
+    app()

python/data_science/firehose_producer.py

@@ -0,0 +1,230 @@
+"""Bluesky Jetstream firehose to Kafka producer.
+
+Connects to the Bluesky Jetstream WebSocket API with zstd compression,
+filters for post creation events, and produces them to a Kafka topic.
+
+Usage:
+    firehose-producer
+    firehose-producer --kafka-servers kafka:9092 --topic bluesky.firehose.posts
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import signal
+from os import getenv
+from threading import Event
+from typing import Annotated
+
+import typer
+from compression import zstd
+from confluent_kafka import KafkaError, KafkaException, Producer
+from websockets.exceptions import ConnectionClosed
+from websockets.sync.client import connect
+
+logger = logging.getLogger(__name__)
+
+JETSTREAM_URL = "wss://jetstream2.us-east.bsky.network/subscribe"
+DEFAULT_TOPIC = "bluesky.firehose.posts"
+DEFAULT_KAFKA_SERVERS = "localhost:9092"
+POLL_INTERVAL = 100
+POST_COLLECTION = "app.bsky.feed.post"
+
+shutdown_event = Event()
+
+app = typer.Typer(help="Stream Bluesky firehose posts into Kafka.")
+
+
+@app.command()
+def main(
+    kafka_servers: Annotated[str, typer.Option(help="Kafka bootstrap servers")] = "",
+    topic: Annotated[str, typer.Option(help="Kafka topic to produce to")] = "",
+    collections: Annotated[str, typer.Option(help="Comma-separated collections to subscribe to")] = POST_COLLECTION,
+) -> None:
+    """Connect to Bluesky Jetstream and produce post events to Kafka."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    servers = kafka_servers or getenv("KAFKA_BOOTSTRAP_SERVERS", DEFAULT_KAFKA_SERVERS)
+    topic_name = topic or getenv("BLUESKY_FIREHOSE_TOPIC", DEFAULT_TOPIC)
+
+    signal.signal(signal.SIGTERM, _handle_shutdown)
+    signal.signal(signal.SIGINT, _handle_shutdown)
+
+    producer = _create_producer(servers)
+    cursor: int | None = None
+
+    logger.info("Starting firehose producer → %s on %s", topic_name, servers)
+
+    while not shutdown_event.is_set():
+        try:
+            cursor = _stream_loop(producer, topic_name, collections, cursor)
+        except (ConnectionClosed, OSError):
+            logger.exception("WebSocket disconnected, reconnecting")
+        except KafkaException:
+            logger.exception("Kafka error, reconnecting")
+
+        if not shutdown_event.is_set():
+            logger.info("Reconnecting in 5 seconds (cursor=%s)", cursor)
+            shutdown_event.wait(timeout=5)
+
+    logger.info("Shutting down, flushing producer")
+    producer.flush(timeout=30)
+    logger.info("Producer shutdown complete")
+
+
+def _stream_loop(
+    producer: Producer,
+    topic: str,
+    collections: str,
+    cursor: int | None,
+) -> int | None:
+    """Connect to Jetstream and stream messages to Kafka until disconnected.
+
+    Args:
+        producer: The Kafka producer instance.
+        topic: Kafka topic name.
+        collections: Comma-separated AT Protocol collections to subscribe to.
+        cursor: Optional microsecond timestamp to resume from.
+
+    Returns:
+        The last processed time_us cursor value.
+    """
+    url = _build_jetstream_url(collections, cursor)
+    logger.info("Connecting to %s", url)
+
+    message_count = 0
+    last_cursor = cursor
+
+    with connect(url, additional_headers={"Accept-Encoding": "zstd"}) as websocket:
+        logger.info("Connected to Jetstream")
+
+        while not shutdown_event.is_set():
+            try:
+                raw_frame = websocket.recv(timeout=10)
+            except TimeoutError:
+                producer.poll(0)
+                continue
+
+            text = _decode_frame(raw_frame)
+            message = json.loads(text)
+
+            time_us = message.get("time_us")
+            if time_us is not None:
+                last_cursor = time_us
+
+            if not _is_post_create(message):
+                continue
+
+            did = message.get("did", "")
+
+            try:
+                producer.produce(
+                    topic,
+                    key=did.encode(),
+                    value=text.encode() if isinstance(text, str) else text,
+                    callback=_delivery_callback,
+                )
+            except BufferError:
+                logger.warning("Producer buffer full, flushing")
+                producer.flush(timeout=10)
+                producer.produce(
+                    topic,
+                    key=did.encode(),
+                    value=text.encode() if isinstance(text, str) else text,
+                    callback=_delivery_callback,
+                )
+
+            message_count += 1
+            if message_count % POLL_INTERVAL == 0:
+                producer.poll(0)
+
+            if message_count % 10000 == 0:
+                logger.info("Produced %d messages (cursor=%s)", message_count, last_cursor)
+
+    return last_cursor
+
+
+def _build_jetstream_url(collections: str, cursor: int | None) -> str:
+    """Build the Jetstream WebSocket URL with query parameters.
+
+    Args:
+        collections: Comma-separated collection names.
+        cursor: Optional microsecond timestamp for resumption.
+
+    Returns:
+        The full WebSocket URL.
+    """
+    params = ["compress=true"]
+    for raw_collection in collections.split(","):
+        cleaned = raw_collection.strip()
+        if cleaned:
+            params.append(f"wantedCollections={cleaned}")
+    if cursor is not None:
+        params.append(f"cursor={cursor}")
+    return f"{JETSTREAM_URL}?{'&'.join(params)}"
+
+
+def _decode_frame(frame: str | bytes) -> str:
+    """Decode a WebSocket frame, decompressing zstd if binary.
+
+    Jetstream with compress=true sends zstd-compressed binary frames.
+
+    Args:
+        frame: Raw WebSocket frame data.
+
+    Returns:
+        The decoded JSON string.
+    """
+    if isinstance(frame, bytes):
+        return zstd.decompress(frame).decode()
+    return frame
+
+
+def _is_post_create(message: dict) -> bool:
+    """Check if a Jetstream message is a post creation commit."""
+    if message.get("kind") != "commit":
+        return False
+    commit = message.get("commit", {})
+    return commit.get("operation") == "create" and commit.get("collection") == POST_COLLECTION
+
+
+def _create_producer(servers: str) -> Producer:
+    """Create a configured Kafka producer.
+
+    Args:
+        servers: Kafka bootstrap servers string.
+
+    Returns:
+        A configured confluent_kafka.Producer.
+    """
+    config = {
+        "bootstrap.servers": servers,
+        "linger.ms": 50,
+        "batch.size": 65536,
+        "compression.type": "zstd",
+        "acks": "all",
+        "retries": 5,
+        "retry.backoff.ms": 500,
+    }
+    return Producer(config)
+
+
+def _delivery_callback(error: KafkaError | None, _message: object) -> None:
+    """Log delivery failures from the Kafka producer."""
+    if error is not None:
+        logger.error("Kafka delivery failed: %s", error)
+
+
+def _handle_shutdown(_signum: int, _frame: object) -> None:
+    """Signal handler to trigger graceful shutdown."""
+    logger.info("Shutdown signal received")
+    shutdown_event.set()
+
+
+if __name__ == "__main__":
+    app()

python/data_science/ingest_posts.py

@@ -0,0 +1,247 @@
+"""Ingestion pipeline for loading JSONL post files into the weekly-partitioned posts table.
+
+Usage:
+    ingest-posts /path/to/files/
+    ingest-posts /path/to/single_file.jsonl
+    ingest-posts /data/dir/ --workers 4 --batch-size 5000
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from pathlib import Path  # noqa: TC003 this is needed for typer
+from typing import TYPE_CHECKING, Annotated
+
+import orjson
+import psycopg
+import typer
+
+from python.common import configure_logger
+from python.orm.common import get_connection_info
+from python.parallelize import parallelize_process
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+logger = logging.getLogger(__name__)
+
+
+app = typer.Typer(help="Ingest JSONL post files into the partitioned posts table.")
+
+
+@app.command()
+def main(
+    path: Annotated[Path, typer.Argument(help="Directory containing JSONL files, or a single JSONL file")],
+    batch_size: Annotated[int, typer.Option(help="Rows per INSERT batch")] = 10000,
+    workers: Annotated[int, typer.Option(help="Parallel workers for multi-file ingestion")] = 4,
+    pattern: Annotated[str, typer.Option(help="Glob pattern for JSONL files")] = "*.jsonl",
+) -> None:
+    """Ingest JSONL post files into the weekly-partitioned posts table."""
+    configure_logger(level="INFO")
+
+    logger.info("starting ingest-posts")
+    logger.info("path=%s batch_size=%d workers=%d pattern=%s", path, batch_size, workers, pattern)
+    if path.is_file():
+        ingest_file(path, batch_size=batch_size)
+    elif path.is_dir():
+        ingest_directory(path, batch_size=batch_size, max_workers=workers, pattern=pattern)
+    else:
+        typer.echo(f"Path does not exist: {path}", err=True)
+        raise typer.Exit(code=1)
+
+    logger.info("ingest-posts done")
+
+
+def ingest_directory(
+    directory: Path,
+    *,
+    batch_size: int,
+    max_workers: int,
+    pattern: str = "*.jsonl",
+) -> None:
+    """Ingest all JSONL files in a directory using parallel workers."""
+    files = sorted(directory.glob(pattern))
+    if not files:
+        logger.warning("No JSONL files found in %s", directory)
+        return
+
+    logger.info("Found %d JSONL files to ingest", len(files))
+
+    kwargs_list = [{"path": fp, "batch_size": batch_size} for fp in files]
+    parallelize_process(ingest_file, kwargs_list, max_workers=max_workers)
+
+
+SCHEMA = "main"
+
+COLUMNS = (
+    "post_id",
+    "user_id",
+    "instance",
+    "date",
+    "text",
+    "langs",
+    "like_count",
+    "reply_count",
+    "repost_count",
+    "reply_to",
+    "replied_author",
+    "thread_root",
+    "thread_root_author",
+    "repost_from",
+    "reposted_author",
+    "quotes",
+    "quoted_author",
+    "labels",
+    "sent_label",
+    "sent_score",
+)
+
+INSERT_FROM_STAGING = f"""
+    INSERT INTO {SCHEMA}.posts ({", ".join(COLUMNS)})
+    SELECT {", ".join(COLUMNS)} FROM pg_temp.staging
+    ON CONFLICT (post_id, date) DO NOTHING
+"""  # noqa: S608
+
+FAILED_INSERT = f"""
+    INSERT INTO {SCHEMA}.failed_ingestion (raw_line, error)
+    VALUES (%(raw_line)s, %(error)s)
+"""  # noqa: S608
+
+
+def get_psycopg_connection() -> psycopg.Connection:
+    """Create a raw psycopg3 connection from environment variables."""
+    database, host, port, username, password = get_connection_info("DATA_SCIENCE_DEV")
+    return psycopg.connect(
+        dbname=database,
+        host=host,
+        port=int(port),
+        user=username,
+        password=password,
+        autocommit=False,
+    )
+
+
+def ingest_file(path: Path, *, batch_size: int) -> None:
+    """Ingest a single JSONL file into the posts table."""
+    log_trigger = max(100_000 // batch_size, 1)
+    failed_lines: list[dict] = []
+    try:
+        with get_psycopg_connection() as connection:
+            for index, batch in enumerate(read_jsonl_batches(path, batch_size, failed_lines), 1):
+                ingest_batch(connection, batch)
+                if index % log_trigger == 0:
+                    logger.info("Ingested %d batches (%d rows) from %s", index, index * batch_size, path)
+
+            if failed_lines:
+                logger.warning("Recording %d malformed lines from %s", len(failed_lines), path.name)
+                with connection.cursor() as cursor:
+                    cursor.executemany(FAILED_INSERT, failed_lines)
+                connection.commit()
+    except Exception:
+        logger.exception("Failed to ingest file: %s", path)
+        raise
+
+
+def ingest_batch(connection: psycopg.Connection, batch: list[dict]) -> None:
+    """COPY batch into a temp staging table, then INSERT ... ON CONFLICT into posts."""
+    if not batch:
+        return
+
+    try:
+        with connection.cursor() as cursor:
+            cursor.execute(f"""
+                CREATE TEMP TABLE IF NOT EXISTS staging
+                (LIKE {SCHEMA}.posts INCLUDING DEFAULTS)
+                ON COMMIT DELETE ROWS
+            """)
+            cursor.execute("TRUNCATE pg_temp.staging")
+
+            with cursor.copy(f"COPY pg_temp.staging ({', '.join(COLUMNS)}) FROM STDIN") as copy:
+                for row in batch:
+                    copy.write_row(tuple(row.get(column) for column in COLUMNS))
+
+            cursor.execute(INSERT_FROM_STAGING)
+        connection.commit()
+    except Exception as error:
+        connection.rollback()
+
+        if len(batch) == 1:
+            logger.exception("Skipping bad row post_id=%s", batch[0].get("post_id"))
+            with connection.cursor() as cursor:
+                cursor.execute(
+                    FAILED_INSERT,
+                    {
+                        "raw_line": orjson.dumps(batch[0], default=str).decode(),
+                        "error": str(error),
+                    },
+                )
+            connection.commit()
+            return
+
+        midpoint = len(batch) // 2
+        ingest_batch(connection, batch[:midpoint])
+        ingest_batch(connection, batch[midpoint:])
+
+
+def read_jsonl_batches(file_path: Path, batch_size: int, failed_lines: list[dict]) -> Iterator[list[dict]]:
+    """Stream a JSONL file and yield batches of transformed rows."""
+    batch: list[dict] = []
+    with file_path.open("r", encoding="utf-8") as handle:
+        for raw_line in handle:
+            line = raw_line.strip()
+            if not line:
+                continue
+            batch.extend(parse_line(line, file_path, failed_lines))
+            if len(batch) >= batch_size:
+                yield batch
+                batch = []
+    if batch:
+        yield batch
+
+
+def parse_line(line: str, file_path: Path, failed_lines: list[dict]) -> Iterator[dict]:
+    """Parse a JSONL line, handling concatenated JSON objects."""
+    try:
+        yield transform_row(orjson.loads(line))
+    except orjson.JSONDecodeError:
+        if "}{" not in line:
+            logger.warning("Skipping malformed line in %s: %s", file_path.name, line[:120])
+            failed_lines.append({"raw_line": line, "error": "malformed JSON"})
+            return
+        fragments = line.replace("}{", "}\n{").split("\n")
+        for fragment in fragments:
+            try:
+                yield transform_row(orjson.loads(fragment))
+            except (orjson.JSONDecodeError, KeyError, ValueError) as error:
+                logger.warning("Skipping malformed fragment in %s: %s", file_path.name, fragment[:120])
+                failed_lines.append({"raw_line": fragment, "error": str(error)})
+    except Exception as error:
+        logger.exception("Skipping bad row in %s: %s", file_path.name, line[:120])
+        failed_lines.append({"raw_line": line, "error": str(error)})
+
+
+def transform_row(raw: dict) -> dict:
+    """Transform a raw JSONL row into a dict matching the Posts table columns."""
+    raw["date"] = parse_date(raw["date"])
+    if raw.get("langs") is not None:
+        raw["langs"] = orjson.dumps(raw["langs"])
+    if raw.get("text") is not None:
+        raw["text"] = raw["text"].replace("\x00", "")
+    return raw
+
+
+def parse_date(raw_date: int) -> datetime:
+    """Parse compact YYYYMMDDHHmm integer into a naive datetime (input is UTC by spec)."""
+    return datetime(
+        raw_date // 100000000,
+        (raw_date // 1000000) % 100,
+        (raw_date // 10000) % 100,
+        (raw_date // 100) % 100,
+        raw_date % 100,
+        tzinfo=UTC,
+    )
+
+
+if __name__ == "__main__":
+    app()

python/database_cli.py

@@ -0,0 +1,129 @@
+"""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",
+    ),
+    "signal_bot": DatabaseConfig(
+        env_prefix="SIGNALBOT",
+        version_location="python/alembic/signal_bot/versions",
+        base_module="python.orm.signal_bot.base",
+        base_class_name="SignalBotBase",
+        models_module="python.orm.signal_bot.models",
+    ),
+    "data_science_dev": DatabaseConfig(
+        env_prefix="DATA_SCIENCE_DEV",
+        version_location="python/alembic/data_science_dev/versions",
+        base_module="python.orm.data_science_dev.base",
+        base_class_name="DataScienceDevBase",
+        models_module="python.orm.data_science_dev.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/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,13 @@
+"""ORM package exports."""
+
+from python.orm.data_science_dev.base import DataScienceDevBase
+from python.orm.richie.base import RichieBase
+from python.orm.signal_bot.base import SignalBotBase
+from python.orm.van_inventory.base import VanInventoryBase
+
+__all__ = [
+    "DataScienceDevBase",
+    "RichieBase",
+    "SignalBotBase",
+    "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/data_science_dev/__init__.py

@@ -0,0 +1,11 @@
+"""Data science dev database ORM exports."""
+
+from __future__ import annotations
+
+from python.orm.data_science_dev.base import DataScienceDevBase, DataScienceDevTableBase, DataScienceDevTableBaseBig
+
+__all__ = [
+    "DataScienceDevBase",
+    "DataScienceDevTableBase",
+    "DataScienceDevTableBaseBig",
+]

python/orm/data_science_dev/base.py

@@ -0,0 +1,52 @@
+"""Data science dev database ORM base."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import BigInteger, 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 DataScienceDevBase(DeclarativeBase):
+    """Base class for data_science_dev 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 DataScienceDevTableBase(_TableMixin, AbstractConcreteBase, DataScienceDevBase):
+    """Table with Integer primary key."""
+
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+
+
+class DataScienceDevTableBaseBig(_TableMixin, AbstractConcreteBase, DataScienceDevBase):
+    """Table with BigInteger primary key."""
+
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)

python/orm/data_science_dev/models.py

@@ -0,0 +1,10 @@
+"""Data science dev database ORM models."""
+
+from __future__ import annotations
+
+from python.orm.data_science_dev.posts import partitions  # noqa: F401 — registers partition classes in metadata
+from python.orm.data_science_dev.posts.tables import Posts
+
+__all__ = [
+    "Posts",
+]

python/orm/data_science_dev/posts/__init__.py

@@ -0,0 +1,11 @@
+"""Posts module — weekly-partitioned posts table and partition ORM models."""
+
+from __future__ import annotations
+
+from python.orm.data_science_dev.posts.failed_ingestion import FailedIngestion
+from python.orm.data_science_dev.posts.tables import Posts
+
+__all__ = [
+    "FailedIngestion",
+    "Posts",
+]

python/orm/data_science_dev/posts/columns.py

@@ -0,0 +1,33 @@
+"""Shared column definitions for the posts partitioned table family."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import BigInteger, SmallInteger, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class PostsColumns:
+    """Mixin providing all posts columns. Used by both the parent table and partitions."""
+
+    post_id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    user_id: Mapped[int] = mapped_column(BigInteger)
+    instance: Mapped[str]
+    date: Mapped[datetime] = mapped_column(primary_key=True)
+    text: Mapped[str] = mapped_column(Text)
+    langs: Mapped[str | None]
+    like_count: Mapped[int]
+    reply_count: Mapped[int]
+    repost_count: Mapped[int]
+    reply_to: Mapped[int | None] = mapped_column(BigInteger)
+    replied_author: Mapped[int | None] = mapped_column(BigInteger)
+    thread_root: Mapped[int | None] = mapped_column(BigInteger)
+    thread_root_author: Mapped[int | None] = mapped_column(BigInteger)
+    repost_from: Mapped[int | None] = mapped_column(BigInteger)
+    reposted_author: Mapped[int | None] = mapped_column(BigInteger)
+    quotes: Mapped[int | None] = mapped_column(BigInteger)
+    quoted_author: Mapped[int | None] = mapped_column(BigInteger)
+    labels: Mapped[str | None]
+    sent_label: Mapped[int | None] = mapped_column(SmallInteger)
+    sent_score: Mapped[float | None]

python/orm/data_science_dev/posts/failed_ingestion.py

@@ -0,0 +1,17 @@
+"""Table for storing JSONL lines that failed during post ingestion."""
+
+from __future__ import annotations
+
+from sqlalchemy import Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from python.orm.data_science_dev.base import DataScienceDevTableBase
+
+
+class FailedIngestion(DataScienceDevTableBase):
+    """Stores raw JSONL lines and their error messages when ingestion fails."""
+
+    __tablename__ = "failed_ingestion"
+
+    raw_line: Mapped[str] = mapped_column(Text)
+    error: Mapped[str] = mapped_column(Text)

python/orm/data_science_dev/posts/partitions.py

@@ -0,0 +1,71 @@
+"""Dynamically generated ORM classes for each weekly partition of the posts table.
+
+Each class maps to a PostgreSQL partition table (e.g. posts_2024_01).
+These are real ORM models tracked by Alembic autogenerate.
+
+Uses ISO week numbering (datetime.isocalendar().week). ISO years can have
+52 or 53 weeks, and week boundaries are always Monday to Monday.
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import UTC, datetime
+
+from python.orm.data_science_dev.base import DataScienceDevBase
+from python.orm.data_science_dev.posts.columns import PostsColumns
+
+PARTITION_START_YEAR = 2023
+PARTITION_END_YEAR = 2026
+
+_current_module = sys.modules[__name__]
+
+
+def iso_weeks_in_year(year: int) -> int:
+    """Return the number of ISO weeks in a given year (52 or 53)."""
+    dec_28 = datetime(year, 12, 28, tzinfo=UTC)
+    return dec_28.isocalendar().week
+
+
+def week_bounds(year: int, week: int) -> tuple[datetime, datetime]:
+    """Return (start, end) datetimes for an ISO week.
+
+    Start = Monday 00:00:00 UTC of the given ISO week.
+    End   = Monday 00:00:00 UTC of the following ISO week.
+    """
+    start = datetime.fromisocalendar(year, week, 1).replace(tzinfo=UTC)
+    if week < iso_weeks_in_year(year):
+        end = datetime.fromisocalendar(year, week + 1, 1).replace(tzinfo=UTC)
+    else:
+        end = datetime.fromisocalendar(year + 1, 1, 1).replace(tzinfo=UTC)
+    return start, end
+
+
+def _build_partition_classes() -> dict[str, type]:
+    """Generate one ORM class per ISO week partition."""
+    classes: dict[str, type] = {}
+
+    for year in range(PARTITION_START_YEAR, PARTITION_END_YEAR + 1):
+        for week in range(1, iso_weeks_in_year(year) + 1):
+            class_name = f"PostsWeek{year}W{week:02d}"
+            table_name = f"posts_{year}_{week:02d}"
+
+            partition_class = type(
+                class_name,
+                (PostsColumns, DataScienceDevBase),
+                {
+                    "__tablename__": table_name,
+                    "__table_args__": ({"implicit_returning": False},),
+                },
+            )
+
+            classes[class_name] = partition_class
+
+    return classes
+
+
+# Generate all partition classes and register them on this module
+_partition_classes = _build_partition_classes()
+for _name, _cls in _partition_classes.items():
+    setattr(_current_module, _name, _cls)
+__all__ = list(_partition_classes.keys())

python/orm/data_science_dev/posts/tables.py

@@ -0,0 +1,13 @@
+"""Posts parent table with PostgreSQL weekly range partitioning on date column."""
+
+from __future__ import annotations
+
+from python.orm.data_science_dev.base import DataScienceDevBase
+from python.orm.data_science_dev.posts.columns import PostsColumns
+
+
+class Posts(PostsColumns, DataScienceDevBase):
+    """Parent partitioned table for posts, partitioned by week on `date`."""
+
+    __tablename__ = "posts"
+    __table_args__ = ({"postgresql_partition_by": "RANGE (date)"},)

python/orm/richie/__init__.py

@@ -0,0 +1,29 @@
+"""Richie database ORM exports."""
+
+from __future__ import annotations
+
+from python.orm.richie.base import RichieBase, TableBase, TableBaseBig, TableBaseSmall
+from python.orm.richie.congress import Bill, Legislator, Vote, VoteRecord
+from python.orm.richie.contact import (
+    Contact,
+    ContactNeed,
+    ContactRelationship,
+    Need,
+    RelationshipType,
+)
+
+__all__ = [
+    "Bill",
+    "Contact",
+    "ContactNeed",
+    "ContactRelationship",
+    "Legislator",
+    "Need",
+    "RelationshipType",
+    "RichieBase",
+    "TableBase",
+    "TableBaseBig",
+    "TableBaseSmall",
+    "Vote",
+    "VoteRecord",
+]

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

@@ -0,0 +1,150 @@
+"""Congress Tracker database models."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from sqlalchemy import ForeignKey, Index, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from python.orm.richie.base import RichieBase, TableBase
+
+
+class Legislator(TableBase):
+    """Legislator model - members of Congress."""
+
+    __tablename__ = "legislator"
+
+    # Natural key - bioguide ID is the authoritative identifier
+    bioguide_id: Mapped[str] = mapped_column(Text, unique=True, index=True)
+
+    # Other IDs for cross-referencing
+    thomas_id: Mapped[str | None]
+    lis_id: Mapped[str | None]
+    govtrack_id: Mapped[int | None]
+    opensecrets_id: Mapped[str | None]
+    fec_ids: Mapped[str | None]  # JSON array stored as string
+
+    # Name info
+    first_name: Mapped[str]
+    last_name: Mapped[str]
+    official_full_name: Mapped[str | None]
+    nickname: Mapped[str | None]
+
+    # Bio
+    birthday: Mapped[date | None]
+    gender: Mapped[str | None]  # M/F
+
+    # Current term info (denormalized for query efficiency)
+    current_party: Mapped[str | None]
+    current_state: Mapped[str | None]
+    current_district: Mapped[int | None]  # House only
+    current_chamber: Mapped[str | None]  # rep/sen
+
+    # Relationships
+    vote_records: Mapped[list[VoteRecord]] = relationship(
+        "VoteRecord",
+        back_populates="legislator",
+        cascade="all, delete-orphan",
+    )
+
+
+class Bill(TableBase):
+    """Bill model - legislation introduced in Congress."""
+
+    __tablename__ = "bill"
+
+    # Composite natural key: congress + bill_type + number
+    congress: Mapped[int]
+    bill_type: Mapped[str]  # hr, s, hres, sres, hjres, sjres
+    number: Mapped[int]
+
+    # Bill info
+    title: Mapped[str | None]
+    title_short: Mapped[str | None]
+    official_title: Mapped[str | None]
+
+    # Status
+    status: Mapped[str | None]
+    status_at: Mapped[date | None]
+
+    # Sponsor
+    sponsor_bioguide_id: Mapped[str | None]
+
+    # Subjects
+    subjects_top_term: Mapped[str | None]
+
+    # Relationships
+    votes: Mapped[list[Vote]] = relationship(
+        "Vote",
+        back_populates="bill",
+    )
+
+    __table_args__ = (
+        UniqueConstraint("congress", "bill_type", "number", name="uq_bill_congress_type_number"),
+        Index("ix_bill_congress", "congress"),
+    )
+
+
+class Vote(TableBase):
+    """Vote model - roll call votes in Congress."""
+
+    __tablename__ = "vote"
+
+    # Composite natural key: congress + chamber + session + number
+    congress: Mapped[int]
+    chamber: Mapped[str]  # house/senate
+    session: Mapped[int]
+    number: Mapped[int]
+
+    # Vote details
+    vote_type: Mapped[str | None]
+    question: Mapped[str | None]
+    result: Mapped[str | None]
+    result_text: Mapped[str | None]
+
+    # Timing
+    vote_date: Mapped[date]
+
+    # Vote counts (denormalized for efficiency)
+    yea_count: Mapped[int | None]
+    nay_count: Mapped[int | None]
+    not_voting_count: Mapped[int | None]
+    present_count: Mapped[int | None]
+
+    # Related bill (optional - not all votes are on bills)
+    bill_id: Mapped[int | None] = mapped_column(ForeignKey("main.bill.id"))
+
+    # Relationships
+    bill: Mapped[Bill | None] = relationship("Bill", back_populates="votes")
+    vote_records: Mapped[list[VoteRecord]] = relationship(
+        "VoteRecord",
+        back_populates="vote",
+        cascade="all, delete-orphan",
+    )
+
+    __table_args__ = (
+        UniqueConstraint("congress", "chamber", "session", "number", name="uq_vote_congress_chamber_session_number"),
+        Index("ix_vote_date", "vote_date"),
+        Index("ix_vote_congress_chamber", "congress", "chamber"),
+    )
+
+
+class VoteRecord(RichieBase):
+    """Association table: Vote <-> Legislator with position."""
+
+    __tablename__ = "vote_record"
+
+    vote_id: Mapped[int] = mapped_column(
+        ForeignKey("main.vote.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    legislator_id: Mapped[int] = mapped_column(
+        ForeignKey("main.legislator.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    position: Mapped[str]  # Yea, Nay, Not Voting, Present
+
+    # Relationships
+    vote: Mapped[Vote] = relationship("Vote", back_populates="vote_records")
+    legislator: Mapped[Legislator] = relationship("Legislator", back_populates="vote_records")

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

@@ -0,0 +1,16 @@
+"""Signal bot database ORM exports."""
+
+from __future__ import annotations
+
+from python.orm.signal_bot.base import SignalBotBase, SignalBotTableBase, SignalBotTableBaseSmall
+from python.orm.signal_bot.models import DeadLetterMessage, DeviceRole, RoleRecord, SignalDevice
+
+__all__ = [
+    "DeadLetterMessage",
+    "DeviceRole",
+    "RoleRecord",
+    "SignalBotBase",
+    "SignalBotTableBase",
+    "SignalBotTableBaseSmall",
+    "SignalDevice",
+]

python/orm/signal_bot/base.py

@@ -0,0 +1,52 @@
+"""Signal bot database ORM base."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import 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 SignalBotBase(DeclarativeBase):
+    """Base class for signal_bot 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 SignalBotTableBaseSmall(_TableMixin, AbstractConcreteBase, SignalBotBase):
+    """Table with SmallInteger primary key."""
+
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(SmallInteger, primary_key=True)
+
+
+class SignalBotTableBase(_TableMixin, AbstractConcreteBase, SignalBotBase):
+    """Table with Integer primary key."""
+
+    __abstract__ = True
+
+    id: Mapped[int] = mapped_column(primary_key=True)

python/orm/signal_bot/models.py

@@ -0,0 +1,62 @@
+"""Signal bot device, role, and dead letter ORM models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Enum, ForeignKey, SmallInteger, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from python.orm.signal_bot.base import SignalBotTableBase, SignalBotTableBaseSmall
+from python.signal_bot.models import MessageStatus, TrustLevel
+
+
+class RoleRecord(SignalBotTableBaseSmall):
+    """Lookup table for RBAC roles, keyed by smallint."""
+
+    __tablename__ = "role"
+
+    name: Mapped[str] = mapped_column(String(50), unique=True)
+
+
+class DeviceRole(SignalBotTableBase):
+    """Association between a device and a role."""
+
+    __tablename__ = "device_role"
+    __table_args__ = (
+        UniqueConstraint("device_id", "role_id", name="uq_device_role_device_role"),
+        {"schema": "main"},
+    )
+
+    device_id: Mapped[int] = mapped_column(ForeignKey("main.signal_device.id"))
+    role_id: Mapped[int] = mapped_column(SmallInteger, ForeignKey("main.role.id"))
+
+
+class SignalDevice(SignalBotTableBase):
+    """A Signal device tracked by phone number and safety number."""
+
+    __tablename__ = "signal_device"
+
+    phone_number: Mapped[str] = mapped_column(String(50), unique=True)
+    safety_number: Mapped[str | None]
+    trust_level: Mapped[TrustLevel] = mapped_column(
+        Enum(TrustLevel, name="trust_level", create_constraint=False, native_enum=False),
+        default=TrustLevel.UNVERIFIED,
+    )
+    last_seen: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    roles: Mapped[list[RoleRecord]] = relationship(secondary=DeviceRole.__table__)
+
+
+class DeadLetterMessage(SignalBotTableBase):
+    """A Signal message that failed processing and was sent to the dead letter queue."""
+
+    __tablename__ = "dead_letter_message"
+
+    source: Mapped[str]
+    message: Mapped[str] = mapped_column(Text)
+    received_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    status: Mapped[MessageStatus] = mapped_column(
+        Enum(MessageStatus, name="message_status", create_constraint=False, native_enum=False),
+        default=MessageStatus.UNPROCESSED,
+    )

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

@@ -0,0 +1 @@
+"""Signal command and control bot."""

python/signal_bot/commands/__init__.py

@@ -0,0 +1 @@
+"""Signal bot commands."""

python/signal_bot/commands/inventory.py

@@ -0,0 +1,137 @@
+"""Van inventory command — parse receipts and item lists via LLM, push to API."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from python.signal_bot.models import InventoryItem, InventoryUpdate
+
+if TYPE_CHECKING:
+    from python.signal_bot.llm_client import LLMClient
+    from python.signal_bot.models import SignalMessage
+    from python.signal_bot.signal_client import SignalClient
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT = """\
+You are an inventory assistant. Extract items from the input and return ONLY
+a JSON array. Each element must have these fields:
+  - "name": item name (string)
+  - "quantity": numeric count or amount (default 1)
+  - "unit": unit of measure (e.g. "each", "lb", "oz", "gallon", "bag", "box")
+  - "category": category like "food", "tools", "supplies", etc.
+  - "notes": any extra detail (empty string if none)
+
+Example output:
+[{"name": "water bottles", "quantity": 6, "unit": "gallon", "category": "supplies", "notes": "1 gallon each"}]
+
+Return ONLY the JSON array, no other text.\
+"""
+
+IMAGE_PROMPT = "Extract all items from this receipt or inventory photo."
+TEXT_PROMPT = "Extract all items from this inventory list."
+
+
+def parse_llm_response(raw: str) -> list[InventoryItem]:
+    """Parse the LLM JSON response into InventoryItem list."""
+    text = raw.strip()
+    # Strip markdown code fences if present
+    if text.startswith("```"):
+        lines = text.split("\n")
+        lines = [line for line in lines if not line.startswith("```")]
+        text = "\n".join(lines)
+
+    items_data: list[dict[str, Any]] = json.loads(text)
+    return [InventoryItem.model_validate(item) for item in items_data]
+
+
+def _upsert_item(api_url: str, item: InventoryItem) -> None:
+    """Create or update an item via the van_inventory API.
+
+    Fetches existing items, and if one with the same name exists,
+    patches its quantity (summing). Otherwise creates a new item.
+    """
+    base = api_url.rstrip("/")
+    response = httpx.get(f"{base}/api/items", timeout=10)
+    response.raise_for_status()
+    existing: list[dict[str, Any]] = response.json()
+
+    match = next((e for e in existing if e["name"].lower() == item.name.lower()), None)
+
+    if match:
+        new_qty = match["quantity"] + item.quantity
+        patch = {"quantity": new_qty}
+        if item.category:
+            patch["category"] = item.category
+        response = httpx.patch(f"{base}/api/items/{match['id']}", json=patch, timeout=10)
+        response.raise_for_status()
+        return
+    payload = {
+        "name": item.name,
+        "quantity": item.quantity,
+        "unit": item.unit,
+        "category": item.category or None,
+    }
+    response = httpx.post(f"{base}/api/items", json=payload, timeout=10)
+    response.raise_for_status()
+
+
+def handle_inventory_update(
+    message: SignalMessage,
+    signal: SignalClient,
+    llm: LLMClient,
+    api_url: str,
+) -> InventoryUpdate:
+    """Process an inventory update from a Signal message.
+
+    Accepts either an image (receipt photo) or text list.
+    Uses the LLM to extract structured items, then pushes to the van_inventory API.
+    """
+    try:
+        logger.info(f"Processing inventory update from {message.source}")
+        if message.attachments:
+            image_data = signal.get_attachment(message.attachments[0])
+            raw_response = llm.chat(
+                IMAGE_PROMPT,
+                image_data=image_data,
+                system=SYSTEM_PROMPT,
+            )
+            source_type = "receipt_photo"
+        elif message.message.strip():
+            raw_response = llm.chat(
+                f"{TEXT_PROMPT}\n\n{message.message}",
+                system=SYSTEM_PROMPT,
+            )
+            source_type = "text_list"
+        else:
+            signal.reply(message, "Send a photo of a receipt or a text list of items to update inventory.")
+            return InventoryUpdate()
+
+        logger.info(f"{raw_response=}")
+
+        new_items = parse_llm_response(raw_response)
+
+        logger.info(f"{new_items=}")
+
+        for item in new_items:
+            _upsert_item(api_url, item)
+
+        summary = _format_summary(new_items)
+        signal.reply(message, f"Inventory updated with {len(new_items)} item(s):\n{summary}")
+
+        return InventoryUpdate(items=new_items, raw_response=raw_response, source_type=source_type)
+
+    except Exception:
+        logger.exception("Failed to process inventory update")
+        signal.reply(message, "Failed to process inventory update. Check logs for details.")
+        return InventoryUpdate()
+
+
+def _format_summary(items: list[InventoryItem]) -> str:
+    """Format items into a readable summary."""
+    lines = [f"  - {item.name} x{item.quantity} {item.unit} [{item.category}]" for item in items]
+    return "\n".join(lines)

python/signal_bot/commands/location.py

@@ -0,0 +1,64 @@
+"""Location command for the Signal bot."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from python.signal_bot.models import SignalMessage
+    from python.signal_bot.signal_client import SignalClient
+
+logger = logging.getLogger(__name__)
+
+
+def _get_entity_state(ha_url: str, ha_token: str, entity_id: str) -> dict[str, Any]:
+    """Fetch an entity's state from Home Assistant."""
+    entity_url = f"{ha_url}/api/states/{entity_id}"
+    logger.debug(f"Fetching {entity_url=}")
+    response = httpx.get(
+        entity_url,
+        headers={"Authorization": f"Bearer {ha_token}"},
+        timeout=30,
+    )
+    response.raise_for_status()
+    return response.json()
+
+
+def _format_location(latitude: str, longitude: str) -> str:
+    """Render a friendly location response."""
+    return f"Van location: {latitude}, {longitude}\nhttps://maps.google.com/?q={latitude},{longitude}"
+
+
+def handle_location_request(
+    message: SignalMessage,
+    signal: SignalClient,
+    ha_url: str | None,
+    ha_token: str | None,
+) -> None:
+    """Reply with van location from Home Assistant."""
+    if ha_url is None or ha_token is None:
+        signal.reply(message, "Location command is not configured (missing HA_URL or HA_TOKEN).")
+        return
+
+    lat_payload = None
+    lon_payload = None
+    try:
+        lat_payload = _get_entity_state(ha_url, ha_token, "sensor.van_last_known_latitude")
+        lon_payload = _get_entity_state(ha_url, ha_token, "sensor.van_last_known_longitude")
+    except httpx.HTTPError:
+        logger.exception("Couldn't fetch van location from Home Assistant right now.")
+        logger.debug(f"{ha_url=} {lat_payload=} {lon_payload=}")
+        signal.reply(message, "Couldn't fetch van location from Home Assistant right now.")
+        return
+
+    latitude = lat_payload.get("state", "")
+    longitude = lon_payload.get("state", "")
+
+    if not latitude or not longitude or latitude == "unavailable" or longitude == "unavailable":
+        signal.reply(message, "Van location is unavailable in Home Assistant right now.")
+        return
+
+    signal.reply(message, _format_location(latitude, longitude))

python/signal_bot/device_registry.py

@@ -0,0 +1,286 @@
+"""Device registry — tracks verified/unverified devices by safety number."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, NamedTuple
+
+from sqlalchemy import delete, select
+from sqlalchemy.orm import Session
+
+from python.common import utcnow
+from python.orm.signal_bot.models import RoleRecord, SignalDevice
+from python.signal_bot.models import Role, TrustLevel
+
+if TYPE_CHECKING:
+    from sqlalchemy.engine import Engine
+
+    from python.signal_bot.signal_client import SignalClient
+
+logger = logging.getLogger(__name__)
+
+_BLOCKED_TTL = timedelta(minutes=60)
+_DEFAULT_TTL = timedelta(minutes=5)
+
+
+class _CacheEntry(NamedTuple):
+    expires: datetime
+    trust_level: TrustLevel
+    has_safety_number: bool
+    safety_number: str | None
+    roles: list[Role]
+
+
+class DeviceRegistry:
+    """Manage device trust based on Signal safety numbers.
+
+    Devices start as UNVERIFIED. An admin verifies them over SSH by calling
+    ``verify(phone_number)`` which marks the device VERIFIED and also tells
+    signal-cli to trust the identity.
+
+    Only VERIFIED devices may execute commands.
+    """
+
+    def __init__(self, signal_client: SignalClient, engine: Engine) -> None:
+        self.signal_client = signal_client
+        self.engine = engine
+        self._contact_cache: dict[str, _CacheEntry] = {}
+
+    def is_verified(self, phone_number: str) -> bool:
+        """Check if a phone number is verified."""
+        if entry := self._cached(phone_number):
+            return entry.trust_level == TrustLevel.VERIFIED
+        device = self._load_device(phone_number)
+        return device is not None and device.trust_level == TrustLevel.VERIFIED
+
+    def record_contact(self, phone_number: str, safety_number: str | None = None) -> None:
+        """Record seeing a device. Creates entry if new, updates last_seen."""
+        now = utcnow()
+
+        entry = self._cached(phone_number)
+        if entry and entry.safety_number == safety_number:
+            return
+
+        with Session(self.engine) as session:
+            device = session.execute(
+                select(SignalDevice).where(SignalDevice.phone_number == phone_number)
+            ).scalar_one_or_none()
+
+            if device:
+                if device.safety_number != safety_number and device.trust_level != TrustLevel.BLOCKED:
+                    logger.warning(f"Safety number changed for {phone_number}, resetting to UNVERIFIED")
+                    device.safety_number = safety_number
+                    device.trust_level = TrustLevel.UNVERIFIED
+                device.last_seen = now
+            else:
+                device = SignalDevice(
+                    phone_number=phone_number,
+                    safety_number=safety_number,
+                    trust_level=TrustLevel.UNVERIFIED,
+                    last_seen=now,
+                )
+                session.add(device)
+                logger.info(f"New device registered: {phone_number}")
+
+            session.commit()
+            self._update_cache(phone_number, device)
+
+    def has_safety_number(self, phone_number: str) -> bool:
+        """Check if a device has a safety number on file."""
+        if entry := self._cached(phone_number):
+            return entry.has_safety_number
+        device = self._load_device(phone_number)
+        return device is not None and device.safety_number is not None
+
+    def verify(self, phone_number: str) -> bool:
+        """Mark a device as verified. Called by admin over SSH.
+
+        Returns True if the device was found and verified.
+        """
+        with Session(self.engine) as session:
+            device = session.execute(
+                select(SignalDevice).where(SignalDevice.phone_number == phone_number)
+            ).scalar_one_or_none()
+
+            if not device:
+                logger.warning(f"Cannot verify unknown device: {phone_number}")
+                return False
+
+            device.trust_level = TrustLevel.VERIFIED
+            self.signal_client.trust_identity(phone_number, trust_all_known_keys=True)
+            session.commit()
+            self._update_cache(phone_number, device)
+            logger.info(f"Device verified: {phone_number}")
+            return True
+
+    def block(self, phone_number: str) -> bool:
+        """Block a device."""
+        return self._set_trust(phone_number, TrustLevel.BLOCKED, "Device blocked")
+
+    def unverify(self, phone_number: str) -> bool:
+        """Reset a device to unverified."""
+        return self._set_trust(phone_number, TrustLevel.UNVERIFIED)
+
+    # -- role management ------------------------------------------------------
+
+    def get_roles(self, phone_number: str) -> list[Role]:
+        """Return the roles for a device, defaulting to empty."""
+        if entry := self._cached(phone_number):
+            return entry.roles
+        device = self._load_device(phone_number)
+        return _extract_roles(device) if device else []
+
+    def has_role(self, phone_number: str, role: Role) -> bool:
+        """Check if a device has a specific role or is admin."""
+        roles = self.get_roles(phone_number)
+        return Role.ADMIN in roles or role in roles
+
+    def grant_role(self, phone_number: str, role: Role) -> bool:
+        """Add a role to a device. Called by admin over SSH."""
+        with Session(self.engine) as session:
+            device = session.execute(
+                select(SignalDevice).where(SignalDevice.phone_number == phone_number)
+            ).scalar_one_or_none()
+
+            if not device:
+                logger.warning(f"Cannot grant role for unknown device: {phone_number}")
+                return False
+
+            if any(record.name == role for record in device.roles):
+                return True
+
+            role_record = session.execute(select(RoleRecord).where(RoleRecord.name == role)).scalar_one_or_none()
+
+            if not role_record:
+                logger.warning(f"Unknown role: {role}")
+                return False
+
+            device.roles.append(role_record)
+            session.commit()
+            self._update_cache(phone_number, device)
+            logger.info(f"Device {phone_number} granted role {role}")
+            return True
+
+    def revoke_role(self, phone_number: str, role: Role) -> bool:
+        """Remove a role from a device. Called by admin over SSH."""
+        with Session(self.engine) as session:
+            device = session.execute(
+                select(SignalDevice).where(SignalDevice.phone_number == phone_number)
+            ).scalar_one_or_none()
+
+            if not device:
+                logger.warning(f"Cannot revoke role for unknown device: {phone_number}")
+                return False
+
+            device.roles = [record for record in device.roles if record.name != role]
+            session.commit()
+            self._update_cache(phone_number, device)
+            logger.info(f"Device {phone_number} revoked role {role}")
+            return True
+
+    def set_roles(self, phone_number: str, roles: list[Role]) -> bool:
+        """Replace all roles for a device. Called by admin over SSH."""
+        with Session(self.engine) as session:
+            device = session.execute(
+                select(SignalDevice).where(SignalDevice.phone_number == phone_number)
+            ).scalar_one_or_none()
+
+            if not device:
+                logger.warning(f"Cannot set roles for unknown device: {phone_number}")
+                return False
+
+            role_names = [str(role) for role in roles]
+            records = list(session.execute(select(RoleRecord).where(RoleRecord.name.in_(role_names))).scalars().all())
+            device.roles = records
+            session.commit()
+            self._update_cache(phone_number, device)
+            logger.info(f"Device {phone_number} roles set to {role_names}")
+            return True
+
+    # -- queries --------------------------------------------------------------
+
+    def list_devices(self) -> list[SignalDevice]:
+        """Return all known devices."""
+        with Session(self.engine) as session:
+            return list(session.execute(select(SignalDevice)).scalars().all())
+
+    def sync_identities(self) -> None:
+        """Pull identity list from signal-cli and record any new ones."""
+        identities = self.signal_client.get_identities()
+        for identity in identities:
+            number = identity.get("number", "")
+            safety = identity.get("safety_number", identity.get("fingerprint", ""))
+            if number:
+                self.record_contact(number, safety)
+
+    # -- internals ------------------------------------------------------------
+
+    def _cached(self, phone_number: str) -> _CacheEntry | None:
+        """Return the cache entry if it exists and hasn't expired."""
+        entry = self._contact_cache.get(phone_number)
+        if entry and utcnow() < entry.expires:
+            return entry
+        return None
+
+    def _load_device(self, phone_number: str) -> SignalDevice | None:
+        """Fetch a device by phone number (with joined roles)."""
+        with Session(self.engine) as session:
+            return session.execute(
+                select(SignalDevice).where(SignalDevice.phone_number == phone_number)
+            ).scalar_one_or_none()
+
+    def _update_cache(self, phone_number: str, device: SignalDevice) -> None:
+        """Refresh the cache entry for a device."""
+        ttl = _BLOCKED_TTL if device.trust_level == TrustLevel.BLOCKED else _DEFAULT_TTL
+        self._contact_cache[phone_number] = _CacheEntry(
+            expires=utcnow() + ttl,
+            trust_level=device.trust_level,
+            has_safety_number=device.safety_number is not None,
+            safety_number=device.safety_number,
+            roles=_extract_roles(device),
+        )
+
+    def _set_trust(self, phone_number: str, level: str, log_msg: str | None = None) -> bool:
+        """Update the trust level for a device."""
+        with Session(self.engine) as session:
+            device = session.execute(
+                select(SignalDevice).where(SignalDevice.phone_number == phone_number)
+            ).scalar_one_or_none()
+
+            if not device:
+                return False
+
+            device.trust_level = level
+            session.commit()
+            self._update_cache(phone_number, device)
+            if log_msg:
+                logger.info(f"{log_msg}: {phone_number}")
+            return True
+
+
+def _extract_roles(device: SignalDevice) -> list[Role]:
+    """Convert a device's RoleRecord objects to a list of Role enums."""
+    return [Role(record.name) for record in device.roles]
+
+
+def sync_roles(engine: Engine) -> None:
+    """Sync the Role enum to the role table, adding new and removing stale entries."""
+    expected = {role.value for role in Role}
+
+    with Session(engine) as session:
+        existing = {record.name for record in session.execute(select(RoleRecord)).scalars().all()}
+
+        to_add = expected - existing
+        to_remove = existing - expected
+
+        for name in to_add:
+            session.add(RoleRecord(name=name))
+            logger.info(f"Role added: {name}")
+
+        if to_remove:
+            session.execute(delete(RoleRecord).where(RoleRecord.name.in_(to_remove)))
+            for name in to_remove:
+                logger.info(f"Role removed: {name}")
+
+        session.commit()

python/signal_bot/llm_client.py

@@ -0,0 +1,80 @@
+"""Flexible LLM client for ollama backends."""
+
+from __future__ import annotations
+
+import base64
+import logging
+from typing import Any, Self
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class LLMClient:
+    """Talk to an ollama instance.
+
+    Args:
+        model: Ollama model name.
+        host: Ollama host.
+        port: Ollama port.
+        temperature: Sampling temperature.
+    """
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        host: str,
+        port: int = 11434,
+        temperature: float = 0.1,
+        timeout: int = 300,
+    ) -> None:
+        self.model = model
+        self.temperature = temperature
+        self._client = httpx.Client(base_url=f"http://{host}:{port}", timeout=timeout)
+
+    def chat(self, prompt: str, image_data: bytes | None = None, system: str | None = None) -> str:
+        """Send a text prompt and return the response."""
+        messages: list[dict[str, Any]] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+
+        user_msg = {"role": "user", "content": prompt}
+        if image_data:
+            user_msg["images"] = [base64.b64encode(image_data).decode()]
+
+        messages.append(user_msg)
+        return self._generate(messages)
+
+    def _generate(self, messages: list[dict[str, Any]]) -> str:
+        """Call the ollama chat API."""
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "stream": False,
+            "options": {"temperature": self.temperature},
+        }
+        logger.info(f"LLM request to {self.model}")
+        response = self._client.post("/api/chat", json=payload)
+        response.raise_for_status()
+        data = response.json()
+        return data["message"]["content"]
+
+    def list_models(self) -> list[str]:
+        """List available models on the ollama instance."""
+        response = self._client.get("/api/tags")
+        response.raise_for_status()
+        return [m["name"] for m in response.json().get("models", [])]
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Close the HTTP client on exit."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()

python/signal_bot/main.py

@@ -0,0 +1,239 @@
+"""Signal command and control bot — main entry point."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from os import getenv
+from typing import TYPE_CHECKING, Annotated
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+import typer
+from alembic.command import upgrade
+from sqlalchemy.orm import Session
+from tenacity import before_sleep_log, retry, stop_after_attempt, wait_exponential
+
+from python.common import configure_logger, utcnow
+from python.database_cli import DATABASES
+from python.orm.common import get_postgres_engine
+from python.orm.signal_bot.models import DeadLetterMessage
+from python.signal_bot.commands.inventory import handle_inventory_update
+from python.signal_bot.commands.location import handle_location_request
+from python.signal_bot.device_registry import DeviceRegistry, sync_roles
+from python.signal_bot.llm_client import LLMClient
+from python.signal_bot.models import BotConfig, MessageStatus, Role, SignalMessage
+from python.signal_bot.signal_client import SignalClient
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    """A registered bot command."""
+
+    action: Callable[[SignalMessage, str], None]
+    help_text: str
+    role: Role | None  # None = no role required (always allowed)
+
+
+class Bot:
+    """Holds shared resources and dispatches incoming messages to command handlers."""
+
+    def __init__(
+        self,
+        signal: SignalClient,
+        llm: LLMClient,
+        registry: DeviceRegistry,
+        config: BotConfig,
+    ) -> None:
+        self.signal = signal
+        self.llm = llm
+        self.registry = registry
+        self.config = config
+        self.commands: dict[str, Command] = {
+            "help": Command(action=self._help, help_text="show this help message", role=None),
+            "status": Command(action=self._status, help_text="show bot status", role=Role.STATUS),
+            "inventory": Command(
+                action=self._inventory,
+                help_text="update van inventory from a text list or receipt photo",
+                role=Role.INVENTORY,
+            ),
+            "location": Command(
+                action=self._location,
+                help_text="get current van location",
+                role=Role.LOCATION,
+            ),
+        }
+
+    # -- actions --------------------------------------------------------------
+
+    def _help(self, message: SignalMessage, _cmd: str) -> None:
+        """Return help text filtered to the sender's roles."""
+        self.signal.reply(message, self._build_help(self.registry.get_roles(message.source)))
+
+    def _status(self, message: SignalMessage, _cmd: str) -> None:
+        """Return the status of the bot."""
+        models = self.llm.list_models()
+        model_list = ", ".join(models[:10])
+        device_count = len(self.registry.list_devices())
+        self.signal.reply(
+            message,
+            f"Bot online.\nLLM: {self.llm.model}\nAvailable models: {model_list}\nKnown devices: {device_count}",
+        )
+
+    def _inventory(self, message: SignalMessage, _cmd: str) -> None:
+        """Process an inventory update."""
+        handle_inventory_update(message, self.signal, self.llm, self.config.inventory_api_url)
+
+    def _location(self, message: SignalMessage, _cmd: str) -> None:
+        """Reply with current van location."""
+        handle_location_request(message, self.signal, self.config.ha_url, self.config.ha_token)
+
+    # -- dispatch -------------------------------------------------------------
+
+    def _build_help(self, roles: list[Role]) -> str:
+        """Build help text showing only the commands the user can access."""
+        is_admin = Role.ADMIN in roles
+        lines = ["Available commands:"]
+        for name, cmd in self.commands.items():
+            if cmd.role is None or is_admin or cmd.role in roles:
+                lines.append(f"  {name:20s} — {cmd.help_text}")
+        return "\n".join(lines)
+
+    def dispatch(self, message: SignalMessage) -> None:
+        """Route an incoming message to the right command handler."""
+        source = message.source
+
+        if not self.registry.is_verified(source):
+            logger.info(f"Device {source} not verified, ignoring message")
+            return
+
+        if not self.registry.has_safety_number(source) and self.registry.has_role(source, Role.ADMIN):
+            logger.warning(f"Admin device {source} missing safety number, ignoring message")
+            return
+
+        text = message.message.strip()
+        parts = text.split()
+
+        if not parts and not message.attachments:
+            return
+
+        cmd = parts[0].lower() if parts else ""
+
+        logger.info(f"f{source=} running {cmd=} with {message=}")
+
+        command = self.commands.get(cmd)
+        if command is None:
+            if message.attachments:
+                command = self.commands["inventory"]
+                cmd = "inventory"
+            else:
+                return
+
+        if command.role is not None and not self.registry.has_role(source, command.role):
+            logger.warning(f"Device {source} denied access to {cmd!r}")
+            self.signal.reply(message, f"Permission denied: you do not have the '{command.role}' role.")
+            return
+
+        command.action(message, cmd)
+
+    def process_message(self, message: SignalMessage) -> None:
+        """Process a single message, sending it to the dead letter queue after repeated failures."""
+        max_attempts = self.config.max_message_attempts
+        for attempt in range(1, max_attempts + 1):
+            try:
+                safety_number = self.signal.get_safety_number(message.source)
+                self.registry.record_contact(message.source, safety_number)
+                self.dispatch(message)
+            except Exception:
+                logger.exception(f"Failed to process message (attempt {attempt}/{max_attempts})")
+            else:
+                return
+
+        logger.error(f"Message from {message.source} failed {max_attempts} times, sending to dead letter queue")
+        with Session(self.config.engine) as session:
+            session.add(
+                DeadLetterMessage(
+                    source=message.source,
+                    message=message.message,
+                    received_at=utcnow(),
+                    status=MessageStatus.UNPROCESSED,
+                )
+            )
+            session.commit()
+
+    def run(self) -> None:
+        """Listen for messages via WebSocket, reconnecting on failure."""
+        logger.info("Bot started — listening via WebSocket")
+
+        @retry(
+            stop=stop_after_attempt(self.config.max_retries),
+            wait=wait_exponential(multiplier=self.config.reconnect_delay, max=self.config.max_reconnect_delay),
+            before_sleep=before_sleep_log(logger, logging.WARNING),
+            reraise=True,
+        )
+        def _listen() -> None:
+            for message in self.signal.listen():
+                logger.info(f"Message from {message.source}: {message.message[:80]}")
+                self.process_message(message)
+
+        try:
+            _listen()
+        except Exception:
+            logger.critical("Max retries exceeded, shutting down")
+            raise
+
+
+def main(
+    log_level: Annotated[str, typer.Option()] = "DEBUG",
+    llm_timeout: Annotated[int, typer.Option()] = 600,
+) -> None:
+    """Run the Signal command and control bot."""
+    configure_logger(log_level)
+    signal_api_url = getenv("SIGNAL_API_URL")
+    phone_number = getenv("SIGNAL_PHONE_NUMBER")
+    inventory_api_url = getenv("INVENTORY_API_URL")
+
+    if signal_api_url is None:
+        error = "SIGNAL_API_URL environment variable not set"
+        raise ValueError(error)
+    if phone_number is None:
+        error = "SIGNAL_PHONE_NUMBER environment variable not set"
+        raise ValueError(error)
+    if inventory_api_url is None:
+        error = "INVENTORY_API_URL environment variable not set"
+        raise ValueError(error)
+
+    signal_bot_config = DATABASES["signal_bot"].alembic_config()
+    upgrade(signal_bot_config, "head")
+    engine = get_postgres_engine(name="SIGNALBOT")
+    sync_roles(engine)
+    config = BotConfig(
+        signal_api_url=signal_api_url,
+        phone_number=phone_number,
+        inventory_api_url=inventory_api_url,
+        ha_url=getenv("HA_URL"),
+        ha_token=getenv("HA_TOKEN"),
+        engine=engine,
+    )
+
+    llm_host = getenv("LLM_HOST")
+    llm_model = getenv("LLM_MODEL", "qwen3-vl:32b")
+    llm_port = int(getenv("LLM_PORT", "11434"))
+    if llm_host is None:
+        error = "LLM_HOST environment variable not set"
+        raise ValueError(error)
+
+    with (
+        SignalClient(config.signal_api_url, config.phone_number) as signal,
+        LLMClient(model=llm_model, host=llm_host, port=llm_port, timeout=llm_timeout) as llm,
+    ):
+        registry = DeviceRegistry(signal, engine)
+        bot = Bot(signal, llm, registry, config)
+        bot.run()
+
+
+if __name__ == "__main__":
+    typer.run(main)

python/signal_bot/models.py

@@ -0,0 +1,97 @@
+"""Models for the Signal command and control bot."""
+
+from __future__ import annotations
+
+from datetime import datetime  # noqa: TC003 - pydantic needs this at runtime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy.engine import Engine  # noqa: TC002 - pydantic needs this at runtime
+
+
+class TrustLevel(StrEnum):
+    """Device trust level."""
+
+    VERIFIED = "verified"
+    UNVERIFIED = "unverified"
+    BLOCKED = "blocked"
+
+
+class Role(StrEnum):
+    """RBAC roles — one per command, plus admin which grants all."""
+
+    ADMIN = "admin"
+    STATUS = "status"
+    INVENTORY = "inventory"
+    LOCATION = "location"
+
+
+class MessageStatus(StrEnum):
+    """Dead letter queue message status."""
+
+    UNPROCESSED = "unprocessed"
+    PROCESSED = "processed"
+
+
+class Device(BaseModel):
+    """A registered device tracked by safety number."""
+
+    phone_number: str
+    safety_number: str
+    trust_level: TrustLevel = TrustLevel.UNVERIFIED
+    first_seen: datetime
+    last_seen: datetime
+
+
+class SignalMessage(BaseModel):
+    """An incoming Signal message."""
+
+    source: str
+    timestamp: int
+    message: str = ""
+    attachments: list[str] = []
+    group_id: str | None = None
+    is_receipt: bool = False
+
+
+class SignalEnvelope(BaseModel):
+    """Raw envelope from signal-cli-rest-api."""
+
+    envelope: dict[str, Any]
+    account: str | None = None
+
+
+class InventoryItem(BaseModel):
+    """An item in the van inventory."""
+
+    name: str
+    quantity: float = 1
+    unit: str = "each"
+    category: str = ""
+    notes: str = ""
+
+
+class InventoryUpdate(BaseModel):
+    """Result of processing an inventory update."""
+
+    items: list[InventoryItem] = []
+    raw_response: str = ""
+    source_type: str = ""  # "receipt_photo" or "text_list"
+
+
+class BotConfig(BaseModel):
+    """Top-level bot configuration."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    signal_api_url: str
+    phone_number: str
+    inventory_api_url: str
+    ha_url: str | None = None
+    ha_token: str | None = None
+    engine: Engine
+    reconnect_delay: int = 5
+    max_reconnect_delay: int = 300
+    max_retries: int = 10
+    max_message_attempts: int = 3

python/signal_bot/signal_client.py

@@ -0,0 +1,141 @@
+"""Client for the signal-cli-rest-api."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any, Self
+
+import httpx
+import websockets.sync.client
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+from python.signal_bot.models import SignalMessage
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_envelope(envelope: dict[str, Any]) -> SignalMessage | None:
+    """Parse a signal-cli envelope into a SignalMessage, or None if not a data message."""
+    data_message = envelope.get("dataMessage")
+    if not data_message:
+        return None
+
+    attachment_ids = [att["id"] for att in data_message.get("attachments", []) if "id" in att]
+
+    group_info = data_message.get("groupInfo")
+    group_id = group_info.get("groupId") if group_info else None
+
+    return SignalMessage(
+        source=envelope.get("source", ""),
+        timestamp=envelope.get("timestamp", 0),
+        message=data_message.get("message", "") or "",
+        attachments=attachment_ids,
+        group_id=group_id,
+    )
+
+
+class SignalClient:
+    """Communicate with signal-cli-rest-api.
+
+    Args:
+        base_url: URL of the signal-cli-rest-api (e.g. http://localhost:8989).
+        phone_number: The registered phone number to send/receive as.
+    """
+
+    def __init__(self, base_url: str, phone_number: str) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.phone_number = phone_number
+        self._client = httpx.Client(base_url=self.base_url, timeout=30)
+
+    def _ws_url(self) -> str:
+        """Build the WebSocket URL from the base HTTP URL."""
+        url = self.base_url.replace("http://", "ws://").replace("https://", "wss://")
+        return f"{url}/v1/receive/{self.phone_number}"
+
+    def listen(self) -> Generator[SignalMessage]:
+        """Connect via WebSocket and yield messages as they arrive."""
+        ws_url = self._ws_url()
+        logger.info(f"Connecting to WebSocket: {ws_url}")
+
+        with websockets.sync.client.connect(ws_url) as ws:
+            for raw in ws:
+                try:
+                    data = json.loads(raw)
+                    envelope = data.get("envelope", {})
+                    message = _parse_envelope(envelope)
+                    if message:
+                        yield message
+                except json.JSONDecodeError:
+                    logger.warning(f"Non-JSON WebSocket frame: {raw[:200]}")
+
+    def send(self, recipient: str, message: str) -> None:
+        """Send a text message."""
+        payload = {
+            "message": message,
+            "number": self.phone_number,
+            "recipients": [recipient],
+        }
+        response = self._client.post("/v2/send", json=payload)
+        response.raise_for_status()
+
+    def send_to_group(self, group_id: str, message: str) -> None:
+        """Send a message to a group."""
+        payload = {
+            "message": message,
+            "number": self.phone_number,
+            "recipients": [group_id],
+        }
+        response = self._client.post("/v2/send", json=payload)
+        response.raise_for_status()
+
+    def get_attachment(self, attachment_id: str) -> bytes:
+        """Download an attachment by ID."""
+        response = self._client.get(f"/v1/attachments/{attachment_id}")
+        response.raise_for_status()
+        return response.content
+
+    def get_identities(self) -> list[dict[str, Any]]:
+        """List known identities and their trust levels."""
+        response = self._client.get(f"/v1/identities/{self.phone_number}")
+        response.raise_for_status()
+        return response.json()
+
+    def get_safety_number(self, phone_number: str) -> str | None:
+        """Look up the safety number for a contact from signal-cli's local store."""
+        for identity in self.get_identities():
+            if identity.get("number") == phone_number:
+                return identity.get("safety_number", identity.get("fingerprint", ""))
+        return None
+
+    def trust_identity(self, number_to_trust: str, *, trust_all_known_keys: bool = False) -> None:
+        """Trust an identity (verify safety number)."""
+        payload: dict[str, Any] = {}
+        if trust_all_known_keys:
+            payload["trust_all_known_keys"] = True
+        response = self._client.put(
+            f"/v1/identities/{self.phone_number}/trust/{number_to_trust}",
+            json=payload,
+        )
+        response.raise_for_status()
+
+    def reply(self, message: SignalMessage, text: str) -> None:
+        """Reply to a message, routing to group or individual."""
+        if message.group_id:
+            self.send_to_group(message.group_id, text)
+        else:
+            self.send(message.source, text)
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Close the HTTP client on exit."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()

python/splendor/.gitignore

@@ -0,0 +1 @@
+game_data/

python/splendor/base.py

@@ -0,0 +1,675 @@
+"""Base logic for the Splendor game."""
+
+from __future__ import annotations
+
+import itertools
+import json
+import random
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+GemColor = Literal["white", "blue", "green", "red", "black", "gold"]
+
+GEM_COLORS: tuple[GemColor, ...] = (
+    "white",
+    "blue",
+    "green",
+    "red",
+    "black",
+    "gold",
+)
+BASE_COLORS: tuple[GemColor, ...] = (
+    "white",
+    "blue",
+    "green",
+    "red",
+    "black",
+)
+
+GEM_ORDER: list[GemColor] = list(GEM_COLORS)
+GEM_INDEX: dict[GemColor, int] = {c: i for i, c in enumerate(GEM_ORDER)}
+BASE_INDEX: dict[GemColor, int] = {c: i for i, c in enumerate(BASE_COLORS)}
+
+
+@dataclass(frozen=True)
+class Card:
+    """Development card: gives points + a permanent gem discount."""
+
+    tier: int
+    points: int
+    color: GemColor
+    cost: dict[GemColor, int]
+
+
+@dataclass(frozen=True)
+class Noble:
+    """Noble tile: gives points if you have enough bonuses."""
+
+    name: str
+    points: int
+    requirements: dict[GemColor, int]
+
+
+@dataclass
+class PlayerState:
+    """State of a player in the game."""
+
+    strategy: Strategy
+    tokens: dict[GemColor, int] = field(default_factory=lambda: dict.fromkeys(GEM_COLORS, 0))
+    discounts: dict[GemColor, int] = field(default_factory=lambda: dict.fromkeys(GEM_COLORS, 0))
+    cards: list[Card] = field(default_factory=list)
+    reserved: list[Card] = field(default_factory=list)
+    nobles: list[Noble] = field(default_factory=list)
+    card_score: int = 0
+    noble_score: int = 0
+
+    def total_tokens(self) -> int:
+        """Total tokens in player's bank."""
+        return sum(self.tokens.values())
+
+    def add_noble(self, noble: Noble) -> None:
+        """Add a noble to the player."""
+        self.nobles.append(noble)
+        self.noble_score = sum(noble.points for noble in self.nobles)
+
+    def add_card(self, card: Card) -> None:
+        """Add a card to the player."""
+        self.cards.append(card)
+        self.card_score = sum(card.points for card in self.cards)
+
+    @property
+    def score(self) -> int:
+        """Total points in player's cards + nobles."""
+        return self.card_score + self.noble_score
+
+    def can_afford(self, card: Card) -> bool:
+        """Check if player can afford card, using discounts + gold."""
+        missing = 0
+        gold = self.tokens["gold"]
+
+        for color, cost in card.cost.items():
+            missing += max(0, cost - self.discounts.get(color, 0) - self.tokens.get(color, 0))
+            if missing > gold:
+                return False
+
+        return True
+
+    def pay_for_card(self, card: Card) -> dict[GemColor, int]:
+        """Pay tokens for card, move card to tableau, return payment for bank."""
+        if not self.can_afford(card):
+            msg = f"cannot afford card {card}"
+            raise ValueError(msg)
+
+        payment: dict[GemColor, int] = dict.fromkeys(GEM_COLORS, 0)
+        gold_available = self.tokens["gold"]
+
+        for color in BASE_COLORS:
+            cost = card.cost.get(color, 0)
+            effective_cost = max(0, cost - self.discounts.get(color, 0))
+
+            use = min(self.tokens[color], effective_cost)
+            self.tokens[color] -= use
+            payment[color] += use
+
+            remaining = effective_cost - use
+            if remaining > 0:
+                use_gold = min(gold_available, remaining)
+                gold_available -= use_gold
+                self.tokens["gold"] -= use_gold
+                payment["gold"] += use_gold
+
+        self.add_card(card)
+        self.discounts[card.color] += 1
+        return payment
+
+
+def get_default_starting_tokens(player_count: int) -> dict[GemColor, int]:
+    """get_default_starting_tokens."""
+    token_count = (player_count * player_count - 3 * player_count + 10) // 2
+    return {
+        "white": token_count,
+        "blue": token_count,
+        "green": token_count,
+        "red": token_count,
+        "black": token_count,
+        "gold": 5,
+    }
+
+
+@dataclass
+class GameConfig:
+    """Game configuration: gems, bank, cards, nobles, etc."""
+
+    win_score: int = 15
+    table_cards_per_tier: int = 4
+    reserve_limit: int = 3
+    token_limit: int = 10
+    turn_limit: int = 1000
+    minimum_tokens_to_buy_2: int = 4
+    max_token_take: int = 3
+
+    cards: list[Card] = field(default_factory=list)
+    nobles: list[Noble] = field(default_factory=list)
+
+
+class GameState:
+    """Game state: players, bank, decks, table, available nobles, etc."""
+
+    def __init__(
+        self,
+        config: GameConfig,
+        players: list[PlayerState],
+        bank: dict[GemColor, int],
+        decks_by_tier: dict[int, list[Card]],
+        table_by_tier: dict[int, list[Card]],
+        available_nobles: list[Noble],
+    ) -> None:
+        """Game state."""
+        self.config = config
+        self.players = players
+        self.bank = bank
+        self.decks_by_tier = decks_by_tier
+        self.table_by_tier = table_by_tier
+        self.available_nobles = available_nobles
+        self.noble_min_requirements = 0
+        self.get_noble_min_requirements()
+        self.current_player_index = 0
+        self.finished = False
+
+    def get_noble_min_requirements(self) -> None:
+        """Find the minimum requirement for all available nobles."""
+        test = 0
+
+        for noble in self.available_nobles:
+            test = max(test, min(foo for foo in noble.requirements.values()))
+
+        self.noble_min_requirements = test
+
+    def next_player(self) -> None:
+        """Advance to the next player."""
+        self.current_player_index = (self.current_player_index + 1) % len(self.players)
+
+    @property
+    def current_player(self) -> PlayerState:
+        """Current player."""
+        return self.players[self.current_player_index]
+
+    def refill_table(self) -> None:
+        """Refill face-up cards from decks."""
+        for tier, deck in self.decks_by_tier.items():
+            table = self.table_by_tier[tier]
+            while len(table) < self.config.table_cards_per_tier and deck:
+                table.append(deck.pop())
+
+    def check_winner_simple(self) -> PlayerState | None:
+        """Simplified: end immediately when someone hits win_score."""
+        eligible = [player for player in self.players if player.score >= self.config.win_score]
+        if not eligible:
+            return None
+        eligible.sort(
+            key=lambda p: (p.score, -len(p.cards)),
+            reverse=True,
+        )
+        self.finished = True
+        return eligible[0]
+
+
+class Action:
+    """Marker protocol for actions."""
+
+
+@dataclass
+class TakeDifferent(Action):
+    """Take up to 3 different gem colors."""
+
+    colors: list[GemColor]
+
+
+@dataclass
+class TakeDouble(Action):
+    """Take two of the same color."""
+
+    color: GemColor
+
+
+@dataclass
+class BuyCard(Action):
+    """Buy a face-up card."""
+
+    tier: int
+    index: int
+
+
+@dataclass
+class BuyCardReserved(Action):
+    """Buy a face-up card."""
+
+    index: int
+
+
+@dataclass
+class ReserveCard(Action):
+    """Reserve a face-up card."""
+
+    tier: int
+    index: int | None = None
+    from_deck: bool = False
+
+
+class Strategy(Protocol):
+    """Implement this to make a bot or human controller."""
+
+    def __init__(self, name: str) -> None:
+        """Initialize a strategy."""
+        self.name = name
+
+    def choose_action(self, game: GameState, player: PlayerState) -> Action | None:
+        """Return an Action, or None to concede/end."""
+        raise NotImplementedError
+
+    def choose_discard(
+        self,
+        game: GameState,  # noqa: ARG002
+        player: PlayerState,
+        excess: int,
+    ) -> dict[GemColor, int]:
+        """Called if player has more than token_limit tokens after an action.
+
+        Default: naive auto-discard.
+        """
+        return auto_discard_tokens(player, excess)
+
+    def choose_noble(
+        self,
+        game: GameState,  # noqa: ARG002
+        player: PlayerState,  # noqa: ARG002
+        nobles: list[Noble],
+    ) -> Noble:
+        """Called if player qualifies for multiple nobles. Default: first."""
+        return nobles[0]
+
+
+def auto_discard_tokens(player: PlayerState, excess: int) -> dict[GemColor, int]:
+    """Very dumb discard logic: discard from colors you have the most of."""
+    to_discard: dict[GemColor, int] = dict.fromkeys(GEM_COLORS, 0)
+    remaining = excess
+    while remaining > 0:
+        color = max(player.tokens, key=lambda c: player.tokens[c])
+        if player.tokens[color] == 0:
+            break
+        player.tokens[color] -= 1
+        to_discard[color] += 1
+        remaining -= 1
+    return to_discard
+
+
+def enforce_token_limit(
+    game: GameState,
+    strategy: Strategy,
+    player: PlayerState,
+) -> None:
+    """If player has more than token_limit tokens, force discards."""
+    limit = game.config.token_limit
+    total = player.total_tokens()
+    if total <= limit:
+        return
+    excess = total - limit
+    discards = strategy.choose_discard(game, player, excess)
+    for color, amount in discards.items():
+        available = player.tokens[color]
+        to_remove = min(amount, available)
+        if to_remove <= 0:
+            continue
+        player.tokens[color] -= to_remove
+        game.bank[color] += to_remove
+    remaining = player.total_tokens() - limit
+    if remaining > 0:
+        auto = auto_discard_tokens(player, remaining)
+        for color, amount in auto.items():
+            game.bank[color] += amount
+
+
+def _check_nobles_for_player(player: PlayerState, noble: Noble) -> bool:
+    # this rule is slower
+    for color, cost in noble.requirements.items():  # noqa: SIM110
+        if player.discounts[color] < cost:
+            return False
+    return True
+
+
+def check_nobles_for_player(
+    game: GameState,
+    strategy: Strategy,
+    player: PlayerState,
+) -> None:
+    """Award at most one noble to player if they qualify."""
+    if game.noble_min_requirements > max(player.discounts.values()):
+        return
+
+    candidates = [noble for noble in game.available_nobles if _check_nobles_for_player(player, noble)]
+
+    if not candidates:
+        return
+
+    chosen = candidates[0] if len(candidates) == 1 else strategy.choose_noble(game, player, candidates)
+
+    if chosen not in game.available_nobles:
+        return
+    game.available_nobles.remove(chosen)
+    game.get_noble_min_requirements()
+
+    player.add_noble(chosen)
+
+
+def apply_take_different(game: GameState, strategy: Strategy, action: TakeDifferent) -> None:
+    """Mutate game state according to action."""
+    player = game.current_player
+
+    colors = [color for color in action.colors if color in BASE_COLORS and game.bank[color] > 0]
+    if not (1 <= len(colors) <= game.config.max_token_take):
+        return
+
+    for color in colors:
+        game.bank[color] -= 1
+        player.tokens[color] += 1
+
+    enforce_token_limit(game, strategy, player)
+
+
+def apply_take_double(game: GameState, strategy: Strategy, action: TakeDouble) -> None:
+    """Mutate game state according to action."""
+    player = game.current_player
+    color = action.color
+    if color not in BASE_COLORS:
+        return
+    if game.bank[color] < game.config.minimum_tokens_to_buy_2:
+        return
+    game.bank[color] -= 2
+    player.tokens[color] += 2
+    enforce_token_limit(game, strategy, player)
+
+
+def apply_buy_card(game: GameState, _strategy: Strategy, action: BuyCard) -> None:
+    """Mutate game state according to action."""
+    player = game.current_player
+
+    row = game.table_by_tier.get(action.tier)
+    if row is None or not (0 <= action.index < len(row)):
+        return
+    card = row[action.index]
+    if not player.can_afford(card):
+        return
+    row.pop(action.index)
+    payment = player.pay_for_card(card)
+    for color, amount in payment.items():
+        game.bank[color] += amount
+    game.refill_table()
+
+
+def apply_buy_card_reserved(game: GameState, _strategy: Strategy, action: BuyCardReserved) -> None:
+    """Mutate game state according to action."""
+    player = game.current_player
+    if not (0 <= action.index < len(player.reserved)):
+        return
+    card = player.reserved[action.index]
+    if not player.can_afford(card):
+        return
+    player.reserved.pop(action.index)
+    payment = player.pay_for_card(card)
+    for color, amount in payment.items():
+        game.bank[color] += amount
+
+
+def apply_reserve_card(game: GameState, strategy: Strategy, action: ReserveCard) -> None:
+    """Mutate game state according to action."""
+    player = game.current_player
+
+    if len(player.reserved) >= game.config.reserve_limit:
+        return
+
+    card: Card | None = None
+    if action.from_deck:
+        deck = game.decks_by_tier.get(action.tier)
+        if deck:
+            card = deck.pop()
+    else:
+        row = game.table_by_tier.get(action.tier)
+        if row is None:
+            return
+        if action.index is None or not (0 <= action.index < len(row)):
+            return
+        card = row.pop(action.index)
+        game.refill_table()
+
+    if card is None:
+        return
+    player.reserved.append(card)
+
+    if game.bank["gold"] > 0:
+        game.bank["gold"] -= 1
+        player.tokens["gold"] += 1
+        enforce_token_limit(game, strategy, player)
+
+
+def apply_action(game: GameState, strategy: Strategy, action: Action) -> None:
+    """Mutate game state according to action."""
+    actions = {
+        TakeDifferent: apply_take_different,
+        TakeDouble: apply_take_double,
+        BuyCard: apply_buy_card,
+        ReserveCard: apply_reserve_card,
+        BuyCardReserved: apply_buy_card_reserved,
+    }
+    action_func = actions.get(type(action))
+    if action_func is None:
+        msg = f"Unknown action type: {type(action)}"
+        raise ValueError(msg)
+    action_func(game, strategy, action)
+
+
+# not sure how to simplify this yet
+def get_legal_actions(  # noqa: C901
+    game: GameState,
+    player: PlayerState | None = None,
+) -> list[Action]:
+    """Enumerate all syntactically legal actions for the given player.
+
+    This enforces:
+    - token-taking rules
+    - reserve limits
+    - affordability for buys
+    """
+    if player is None:
+        player = game.players[game.current_player_index]
+
+    actions: list[Action] = []
+
+    colors_available = [c for c in BASE_COLORS if game.bank[c] > 0]
+    for r in (1, 2, 3):
+        actions.extend(TakeDifferent(colors=list(combo)) for combo in itertools.combinations(colors_available, r))
+
+    actions.extend(
+        TakeDouble(color=color) for color in BASE_COLORS if game.bank[color] >= game.config.minimum_tokens_to_buy_2
+    )
+
+    for tier, row in game.table_by_tier.items():
+        for idx, card in enumerate(row):
+            if player.can_afford(card):
+                actions.append(BuyCard(tier=tier, index=idx))
+
+    for idx, card in enumerate(player.reserved):
+        if player.can_afford(card):
+            actions.append(BuyCardReserved(index=idx))
+
+    if len(player.reserved) < game.config.reserve_limit:
+        for tier, row in game.table_by_tier.items():
+            for idx, _ in enumerate(row):
+                actions.append(
+                    ReserveCard(tier=tier, index=idx, from_deck=False),
+                )
+        for tier, deck in game.decks_by_tier.items():
+            if deck:
+                actions.append(
+                    ReserveCard(tier=tier, index=None, from_deck=True),
+                )
+
+    return actions
+
+
+def create_random_cards_tier(
+    tier: int,
+    card_count: int,
+    cost_choices: list[int],
+    point_choices: list[int],
+) -> list[Card]:
+    """Create a random set of cards for a given tier."""
+    cards: list[Card] = []
+
+    for color in BASE_COLORS:
+        for _ in range(card_count):
+            cost = dict.fromkeys(GEM_COLORS, 0)
+            for c in BASE_COLORS:
+                if c == color:
+                    continue
+                cost[c] = random.choice(cost_choices)
+            points = random.choice(point_choices)
+            cards.append(Card(tier=tier, points=points, color=color, cost=cost))
+
+    return cards
+
+
+def create_random_cards() -> list[Card]:
+    """Generate a generic but Splendor-ish set of cards.
+
+    This is not the official deck, but structured similarly enough for play.
+    """
+    cards: list[Card] = []
+    cards.extend(
+        create_random_cards_tier(
+            tier=1,
+            card_count=5,
+            cost_choices=[0, 1, 1, 2],
+            point_choices=[0, 0, 1],
+        )
+    )
+    cards.extend(
+        create_random_cards_tier(
+            tier=2,
+            card_count=4,
+            cost_choices=[2, 3, 4],
+            point_choices=[1, 2, 2, 3],
+        )
+    )
+    cards.extend(
+        create_random_cards_tier(
+            tier=3,
+            card_count=3,
+            cost_choices=[4, 5, 6],
+            point_choices=[3, 4, 5],
+        )
+    )
+
+    random.shuffle(cards)
+    return cards
+
+
+def create_random_nobles() -> list[Noble]:
+    """A small set of noble tiles, roughly Splendor-ish."""
+    nobles: list[Noble] = []
+
+    base_requirements: list[dict[GemColor, int]] = [
+        {"white": 3, "blue": 3, "green": 3},
+        {"blue": 3, "green": 3, "red": 3},
+        {"green": 3, "red": 3, "black": 3},
+        {"red": 3, "black": 3, "white": 3},
+        {"black": 3, "white": 3, "blue": 3},
+        {"white": 4, "blue": 4},
+        {"green": 4, "red": 4},
+        {"blue": 4, "black": 4},
+    ]
+
+    for idx, req in enumerate(base_requirements, start=1):
+        nobles.append(
+            Noble(
+                name=f"Noble {idx}",
+                points=3,
+                requirements=dict(req.items()),
+            ),
+        )
+    return nobles
+
+
+def load_nobles(file: Path) -> list[Noble]:
+    """Load nobles from a file."""
+    nobles = json.loads(file.read_text())
+    return [Noble(**noble) for noble in nobles]
+
+
+def load_cards(file: Path) -> list[Card]:
+    """Load cards from a file."""
+    cards = json.loads(file.read_text())
+    return [Card(**card) for card in cards]
+
+
+def new_game(
+    strategies: Sequence[Strategy],
+    config: GameConfig,
+) -> GameState:
+    """Create a new game state from a config + list of players."""
+    num_players = len(strategies)
+    bank = get_default_starting_tokens(num_players)
+
+    decks_by_tier: dict[int, list[Card]] = {1: [], 2: [], 3: []}
+    for card in config.cards:
+        decks_by_tier.setdefault(card.tier, []).append(card)
+    for deck in decks_by_tier.values():
+        random.shuffle(deck)
+
+    table_by_tier: dict[int, list[Card]] = {1: [], 2: [], 3: []}
+    players = [PlayerState(strategy=strategy) for strategy in strategies]
+
+    nobles = list(config.nobles)
+    random.shuffle(nobles)
+    nobles = nobles[: num_players + 1]
+
+    game = GameState(
+        config=config,
+        players=players,
+        bank=bank,
+        decks_by_tier=decks_by_tier,
+        table_by_tier=table_by_tier,
+        available_nobles=nobles,
+    )
+    game.refill_table()
+    return game
+
+
+def run_game(game: GameState) -> tuple[PlayerState, int]:
+    """Run a full game loop until someone wins or a player returns None."""
+    turn_count = 0
+    while not game.finished:
+        turn_count += 1
+        player = game.current_player
+        strategy = player.strategy
+        action = strategy.choose_action(game, player)
+        if action is None:
+            game.finished = True
+            break
+
+        apply_action(game, strategy, action)
+        check_nobles_for_player(game, strategy, player)
+
+        winner = game.check_winner_simple()
+        if winner is not None:
+            return winner, turn_count
+
+        game.next_player()
+        if turn_count >= game.config.turn_limit:
+            break
+
+    fallback = max(game.players, key=lambda player: player.score)
+    return fallback, turn_count

python/splendor/bot.py

@@ -0,0 +1,288 @@
+"""Bot for Splendor game."""
+
+from __future__ import annotations
+
+import random
+
+from .base import (
+    BASE_COLORS,
+    Action,
+    BuyCard,
+    BuyCardReserved,
+    Card,
+    GameState,
+    GemColor,
+    PlayerState,
+    ReserveCard,
+    Strategy,
+    TakeDifferent,
+    TakeDouble,
+    auto_discard_tokens,
+    get_legal_actions,
+)
+
+
+def can_bot_afford(player: PlayerState, card: Card) -> bool:
+    """Check if player can afford card, using discounts + gold."""
+    missing = 0
+    gold = player.tokens["gold"]
+    for color, cost in card.cost.items():
+        missing += max(0, cost - player.discounts.get(color, 0) - player.tokens.get(color, 0))
+        if missing > gold:
+            return False
+
+    return True
+
+
+class RandomBot(Strategy):
+    """Dumb bot that follows rules but doesn't think."""
+
+    def __init__(self, name: str) -> None:
+        """Initialize the bot."""
+        super().__init__(name=name)
+
+    def choose_action(self, game: GameState, player: PlayerState) -> Action | None:
+        """Choose an action for the current player."""
+        affordable: list[tuple[int, int]] = []
+        for tier, row in game.table_by_tier.items():
+            for idx, card in enumerate(row):
+                if can_bot_afford(player, card):
+                    affordable.append((tier, idx))
+        if affordable and random.random() < 0.5:
+            tier, idx = random.choice(affordable)
+            return BuyCard(tier=tier, index=idx)
+
+        if random.random() < 0.2:
+            tier = random.choice([1, 2, 3])
+            row = game.table_by_tier.get(tier, [])
+            if row:
+                idx = random.randrange(len(row))
+                return ReserveCard(tier=tier, index=idx, from_deck=False)
+
+        if random.random() < 0.5:
+            colors_for_double = [c for c in BASE_COLORS if game.bank[c] >= 4]
+            if colors_for_double:
+                return TakeDouble(color=random.choice(colors_for_double))
+
+        colors_for_diff = [c for c in BASE_COLORS if game.bank[c] > 0]
+        random.shuffle(colors_for_diff)
+        return TakeDifferent(colors=colors_for_diff[:3])
+
+    def choose_discard(
+        self,
+        game: GameState,  # noqa: ARG002
+        player: PlayerState,
+        excess: int,
+    ) -> dict[GemColor, int]:
+        """Choose how many tokens to discard."""
+        return auto_discard_tokens(player, excess)
+
+
+def check_cards_in_tier(row: list[Card], player: PlayerState) -> list[int]:
+    """Check if player can afford card, using discounts + gold."""
+    return [index for index, card in enumerate(row) if can_bot_afford(player, card)]
+
+
+class PersonalizedBot(Strategy):
+    """PersonalizedBot."""
+
+    """Dumb bot that follows rules but doesn't think."""
+
+    def __init__(self, name: str) -> None:
+        """Initialize the bot."""
+        super().__init__(name=name)
+
+    def choose_action(self, game: GameState, player: PlayerState) -> Action | None:
+        """Choose an action for the current player."""
+        for tier in (1, 2, 3):
+            row = game.table_by_tier[tier]
+            if affordable := check_cards_in_tier(row, player):
+                index = random.choice(affordable)
+                return BuyCard(tier=tier, index=index)
+
+        colors_for_diff = [c for c in BASE_COLORS if game.bank[c] > 0]
+        random.shuffle(colors_for_diff)
+        return TakeDifferent(colors=colors_for_diff[:3])
+
+    def choose_discard(
+        self,
+        game: GameState,  # noqa: ARG002
+        player: PlayerState,
+        excess: int,
+    ) -> dict[GemColor, int]:
+        """Choose how many tokens to discard."""
+        return auto_discard_tokens(player, excess)
+
+
+class PersonalizedBot2(Strategy):
+    """PersonalizedBot2."""
+
+    """Dumb bot that follows rules but doesn't think."""
+
+    def __init__(self, name: str) -> None:
+        """Initialize the bot."""
+        super().__init__(name=name)
+
+    def choose_action(self, game: GameState, player: PlayerState) -> Action | None:
+        """Choose an action for the current player."""
+        tiers = (1, 2, 3)
+        for tier in tiers:
+            row = game.table_by_tier[tier]
+            if affordable := check_cards_in_tier(row, player):
+                index = random.choice(affordable)
+                return BuyCard(tier=tier, index=index)
+
+        if affordable := check_cards_in_tier(player.reserved, player):
+            index = random.choice(affordable)
+            return BuyCardReserved(index=index)
+
+        colors_for_diff = [c for c in BASE_COLORS if game.bank[c] > 0]
+        if len(colors_for_diff) >= 3:
+            random.shuffle(colors_for_diff)
+            return TakeDifferent(colors=colors_for_diff[:3])
+
+        for tier in tiers:
+            len_deck = len(game.decks_by_tier[tier])
+            if len_deck:
+                return ReserveCard(tier=tier, index=None, from_deck=True)
+
+        return TakeDifferent(colors=colors_for_diff[:3])
+
+    def choose_discard(
+        self,
+        game: GameState,  # noqa: ARG002
+        player: PlayerState,
+        excess: int,
+    ) -> dict[GemColor, int]:
+        """Choose how many tokens to discard."""
+        return auto_discard_tokens(player, excess)
+
+
+def buy_card_reserved(player: PlayerState) -> Action | None:
+    """Buy a card reserved."""
+    if affordable := check_cards_in_tier(player.reserved, player):
+        index = random.choice(affordable)
+        return BuyCardReserved(index=index)
+    return None
+
+
+def buy_card(game: GameState, player: PlayerState) -> Action | None:
+    """Buy a card."""
+    for tier in (1, 2, 3):
+        row = game.table_by_tier[tier]
+        if affordable := check_cards_in_tier(row, player):
+            index = random.choice(affordable)
+            return BuyCard(tier=tier, index=index)
+    return None
+
+
+def take_tokens(game: GameState) -> Action | None:
+    """Take tokens."""
+    colors_for_diff = [color for color in BASE_COLORS if game.bank[color] > 0]
+    if len(colors_for_diff) >= 3:
+        random.shuffle(colors_for_diff)
+        return TakeDifferent(colors=colors_for_diff[: game.config.max_token_take])
+    return None
+
+
+class PersonalizedBot3(Strategy):
+    """PersonalizedBot3."""
+
+    """Dumb bot that follows rules but doesn't think."""
+
+    def __init__(self, name: str) -> None:
+        """Initialize the bot."""
+        super().__init__(name=name)
+
+    def choose_action(self, game: GameState, player: PlayerState) -> Action | None:
+        """Choose an action for the current player."""
+        print(len(get_legal_actions(game, player)))
+        print(get_legal_actions(game, player))
+        if action := buy_card_reserved(player):
+            return action
+        if action := buy_card(game, player):
+            return action
+
+        colors_for_diff = [color for color in BASE_COLORS if game.bank[color] > 0]
+        if len(colors_for_diff) >= 3:
+            random.shuffle(colors_for_diff)
+            return TakeDifferent(colors=colors_for_diff[:3])
+
+        for tier in (1, 2, 3):
+            len_deck = len(game.decks_by_tier[tier])
+            if len_deck:
+                return ReserveCard(tier=tier, index=None, from_deck=True)
+
+        return TakeDifferent(colors=colors_for_diff[:3])
+
+    def choose_discard(
+        self,
+        game: GameState,  # noqa: ARG002
+        player: PlayerState,
+        excess: int,
+    ) -> dict[GemColor, int]:
+        """Choose how many tokens to discard."""
+        return auto_discard_tokens(player, excess)
+
+
+def estimate_value_of_card(game: GameState, player: PlayerState, color: GemColor) -> int:
+    """Estimate value of a color in the player's bank."""
+    return game.bank[color] - player.discounts.get(color, 0)
+
+
+def estimate_value_of_token(game: GameState, player: PlayerState, color: GemColor) -> int:
+    """Estimate value of a color in the player's bank."""
+    return game.bank[color] - player.discounts.get(color, 0)
+
+
+class PersonalizedBot4(Strategy):
+    """PersonalizedBot4."""
+
+    def __init__(self, name: str) -> None:
+        """Initialize the bot."""
+        super().__init__(name=name)
+
+    def filter_actions(self, actions: list[Action]) -> list[Action]:
+        """Filter actions to only take different."""
+        return [
+            action
+            for action in actions
+            if (isinstance(action, TakeDifferent) and len(action.colors) == 3) or not isinstance(action, TakeDifferent)
+        ]
+
+    def choose_action(self, game: GameState, player: PlayerState) -> Action | None:
+        """Choose an action for the current player."""
+        legal_actions = get_legal_actions(game, player)
+        print(len(legal_actions))
+
+        good_actions = self.filter_actions(legal_actions)
+        print(len(good_actions))
+
+        print(good_actions)
+
+        print(len(get_legal_actions(game, player)))
+        if action := buy_card_reserved(player):
+            return action
+        if action := buy_card(game, player):
+            return action
+
+        colors_for_diff = [color for color in BASE_COLORS if game.bank[color] > 0]
+        if len(colors_for_diff) >= 3:
+            random.shuffle(colors_for_diff)
+            return TakeDifferent(colors=colors_for_diff[:3])
+
+        for tier in (1, 2, 3):
+            len_deck = len(game.decks_by_tier[tier])
+            if len_deck:
+                return ReserveCard(tier=tier, index=None, from_deck=True)
+
+        return TakeDifferent(colors=colors_for_diff[:3])
+
+    def choose_discard(
+        self,
+        game: GameState,  # noqa: ARG002
+        player: PlayerState,
+        excess: int,
+    ) -> dict[GemColor, int]:
+        """Choose how many tokens to discard."""
+        return auto_discard_tokens(player, excess)

python/splendor/human.py

@@ -0,0 +1,724 @@
+"""Splendor game."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.widget import Widget
+from textual.widgets import Footer, Header, Input, Static
+
+from .base import (
+    BASE_COLORS,
+    GEM_COLORS,
+    Action,
+    BuyCard,
+    BuyCardReserved,
+    Card,
+    GameState,
+    GemColor,
+    Noble,
+    PlayerState,
+    ReserveCard,
+    Strategy,
+    TakeDifferent,
+    TakeDouble,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+# Abbreviations used when rendering costs
+COST_ABBR: dict[GemColor, str] = {
+    "white": "W",
+    "blue": "B",
+    "green": "G",
+    "red": "R",
+    "black": "K",
+    "gold": "O",
+}
+
+# Abbreviations players can type on the command line
+COLOR_ABBR_TO_FULL: dict[str, GemColor] = {
+    "w": "white",
+    "b": "blue",
+    "g": "green",
+    "r": "red",
+    "k": "black",
+    "o": "gold",
+}
+
+
+def parse_color_token(raw: str) -> GemColor:
+    """Convert user input into a GemColor.
+
+    Supports:
+      - full names:  white, blue, green, red, black, gold
+      - abbreviations: w, b, g, r, k, o
+    """
+    key = raw.lower()
+
+    # full color names first
+    if key in BASE_COLORS:
+        return key  # type: ignore[return-value]
+
+    # abbreviations
+    if key in COLOR_ABBR_TO_FULL:
+        return COLOR_ABBR_TO_FULL[key]
+
+    error = f"Unknown color: {raw}"
+    raise ValueError(error)
+
+
+def format_cost(cost: Mapping[GemColor, int]) -> str:
+    """Format a cost/requirements dict as colored tokens like 'B:2, R:1'.
+
+    Uses `color_token` internally so colors are guaranteed to match your bank.
+    """
+    parts: list[str] = []
+    for color in GEM_COLORS:
+        n = cost.get(color, 0)
+        if not n:
+            continue
+
+        # color_token gives us e.g. "[blue]blue: 3[/]"
+        token = color_token(color, n)
+
+        # Turn the leading color name into the abbreviation (blue: 3 → B:3)
+        # We only replace the first occurrence.
+        full = f"{color}:"
+        abbr = f"{COST_ABBR[color]}:"
+        token = token.replace(full, abbr, 1)
+
+        parts.append(token)
+
+    return ", ".join(parts) if parts else "-"
+
+
+def format_card(card: Card) -> str:
+    """Readable card line using dataclass fields instead of __str__."""
+    color_abbr = COST_ABBR[card.color]
+    header = f"T{card.tier} {color_abbr} P{card.points}"
+    cost_str = format_cost(card.cost)
+    return f"{header} ({cost_str})"
+
+
+def format_noble(noble: Noble) -> str:
+    """Readable noble line using dataclass fields instead of __str__."""
+    cost_str = format_cost(noble.requirements)
+    return f"{noble.name} +{noble.points} ({cost_str})"
+
+
+def format_tokens(tokens: Mapping[GemColor, int]) -> str:
+    """Colored 'color: n' list for a token dict."""
+    return " ".join(color_token(c, tokens.get(c, 0)) for c in GEM_COLORS)
+
+
+def format_discounts(discounts: Mapping[GemColor, int]) -> str:
+    """Colored discounts, skipping zeros."""
+    parts: list[str] = []
+    for c in GEM_COLORS:
+        n = discounts.get(c, 0)
+        if not n:
+            continue
+        abbr = COST_ABBR[c]
+        fg, bg = COLOR_STYLE[c]
+        parts.append(f"[{fg} on {bg}]{abbr}:{n}[/{fg} on {bg}]")
+    return ", ".join(parts) if parts else "-"
+
+
+COLOR_STYLE: dict[GemColor, tuple[str, str]] = {
+    "white": ("black", "white"),  # fg, bg
+    "blue": ("bright_white", "blue"),
+    "green": ("bright_white", "sea_green4"),
+    "red": ("white", "red3"),
+    "black": ("white", "grey0"),
+    "gold": ("black", "yellow3"),
+}
+
+
+def fmt_gem(color: GemColor) -> str:
+    """Render gem name with fg/bg matching real token color."""
+    fg, bg = COLOR_STYLE[color]
+    return f"[{fg} on {bg}] {color} [/{fg} on {bg}]"
+
+
+def fmt_number(value: int) -> str:
+    """Return a Rich-markup colored 'value' string."""
+    return f"[bold cyan]{value}[/]"
+
+
+def color_token(name: GemColor, amount: int) -> str:
+    """Return a Rich-markup colored 'name: n' string."""
+    # Map Splendor colors -> terminal colors
+    color_map: Mapping[GemColor, str] = {
+        "white": "white",
+        "blue": "blue",
+        "green": "green",
+        "red": "red",
+        "black": "grey70",  # 'black' is unreadable on dark backgrounds
+        "gold": "yellow",
+    }
+    style = color_map.get(name, "white")
+    return f"[{style}]{name}: {amount}[/]"
+
+
+class Board(Widget):
+    """Big board widget with the layout you sketched."""
+
+    def __init__(self, game: GameState, me: PlayerState, **kwargs: Any) -> None:  # noqa: ANN401
+        """Initialize the board widget."""
+        super().__init__(**kwargs)
+        self.game = game
+        self.me = me
+
+    def compose(self) -> ComposeResult:
+        """Compose the board widget."""
+        # Structure:
+        # ┌ bank row
+        # ├ middle row (tiers | nobles)
+        # └ players row
+        with Vertical(id="board_root"):
+            yield Static(id="bank_box")
+            with Horizontal(id="middle_row"):
+                with Vertical(id="tiers_box"):
+                    yield Static(id="tier1_box")
+                    yield Static(id="tier2_box")
+                    yield Static(id="tier3_box")
+                yield Static(id="nobles_box")
+            yield Static(id="players_box")
+
+    def on_mount(self) -> None:
+        """Refresh the board content."""
+        self.refresh_content()
+
+    def refresh_content(self) -> None:
+        """Refresh the board content."""
+        self._render_bank()
+        self._render_tiers()
+        self._render_nobles()
+        self._render_players()
+
+    # --- sections ----------------------------------------------------
+
+    def _render_bank(self) -> None:
+        bank = self.game.bank
+        parts: list[str] = ["[b]Bank:[/b]"]
+        # One line, all tokens colored
+        parts.append(format_tokens(bank))
+        self.query_one("#bank_box", Static).update("\n".join(parts))
+
+    def _render_tiers(self) -> None:
+        for tier in (1, 2, 3):
+            box = self.query_one(f"#tier{tier}_box", Static)
+            cards: list[Card] = self.game.table_by_tier.get(tier, [])
+            lines: list[str] = [f"[b]Tier {tier} cards:[/b]"]
+            if not cards:
+                lines.append("  (none)")
+            else:
+                for idx, card in enumerate(cards):
+                    lines.append(f"  [{idx}] {format_card(card)}")
+            box.update("\n".join(lines))
+
+    def _render_nobles(self) -> None:
+        nobles_box = self.query_one("#nobles_box", Static)
+        lines: list[str] = ["[b]Nobles[/b]"]
+        if not self.game.available_nobles:
+            lines.append("  (none)")
+        else:
+            lines.extend("  - " + format_noble(noble) for noble in self.game.available_nobles)
+        nobles_box.update("\n".join(lines))
+
+    def _render_players(self) -> None:
+        players_box = self.query_one("#players_box", Static)
+        lines: list[str] = ["[b]Players:[/b]", ""]
+        for player in self.game.players:
+            mark = "*" if player is self.me else " "
+            token_str = format_tokens(player.tokens)
+            discount_str = format_discounts(player.discounts)
+
+            lines.append(
+                f"{mark} {player.name:10}  Score={player.score:2d}  Discounts={discount_str}",
+            )
+            lines.append(f"    Tokens: {token_str}")
+
+            if player.nobles:
+                noble_names = ", ".join(n.name for n in player.nobles)
+                lines.append(f"    Nobles: {noble_names}")
+
+            # Optional: show counts of cards / reserved
+            if player.cards:
+                lines.append(f"    Cards: {len(player.cards)}")
+            if player.reserved:
+                lines.append(f"    Reserved: {len(player.reserved)}")
+
+            lines.append("")
+        players_box.update("\n".join(lines))
+
+
+class ActionApp(App[None]):
+    """Textual app that asks for a single action command and returns an Action."""
+
+    CSS = """
+    Screen {
+        /* 3 rows: command zone, board, footer */
+        layout: grid;
+        grid-size: 1 3;
+        grid-rows: auto 1fr auto;
+    }
+
+    /* Top area with input + instructions */
+    #command_zone {
+        grid-columns: 1;
+        grid-rows: 1;
+        padding: 1 1;
+    }
+
+    /* Board sits in the middle row and can grow */
+    #board {
+        grid-columns: 1;
+        grid-rows: 2;
+        padding: 0 1 1 1;
+    }
+
+    Footer {
+        grid-columns: 1;
+        grid-rows: 3;
+    }
+
+    Input {
+        border: round $accent;
+    }
+
+    /* === Board layout === */
+
+    #board_root {
+        /* outer frame around the whole board area */
+        border: heavy white;
+        padding: 0 1;
+    }
+
+    /* Bank row: full width */
+    #bank_box {
+        border: heavy white;
+        padding: 0 1;
+    }
+
+    /* Middle row: tiers (left) + nobles (right) */
+    #middle_row {
+        layout: horizontal;
+    }
+
+    #tiers_box {
+        border: heavy white;
+        padding: 0 1;
+        width: 70%;
+    }
+
+    #tier1_box,
+    #tier2_box,
+    #tier3_box {
+        border-bottom: heavy white;
+        padding: 0 0 1 0;
+        margin-bottom: 1;
+    }
+
+    #nobles_box {
+        border: heavy white;
+        padding: 0 1;
+        width: 30%;
+    }
+
+    /* Players row: full width at bottom */
+    #players_box {
+        border: heavy white;
+        padding: 0 1;
+    }
+    """
+
+    def __init__(self, game: GameState, player: PlayerState) -> None:
+        """Initialize the action app."""
+        super().__init__()
+        self.game = game
+        self.player = player
+        self.result: Action | None = None
+        self.message: str = ""
+
+    def compose(self) -> ComposeResult:
+        """Compose the action app."""
+        # Row 1: input + Actions text
+        with Vertical(id="command_zone"):
+            yield Input(
+                placeholder="Enter command, e.g. '1 white blue red' or '1 w b r' or 'q'",
+                id="input_line",
+            )
+            yield Static("", id="prompt")
+
+        # Row 2: board
+        yield Board(self.game, self.player, id="board")
+
+        # Row 3: footer
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Mount the action app."""
+        self._update_prompt()
+        self.query_one(Input).focus()
+
+    def _update_prompt(self) -> None:
+        lines: list[str] = []
+        lines.append("[bold underline]Actions:[/]")
+        lines.append(
+            " [bold green]1[/] <colors...>  - Take up to 3 different gem colors "
+            "(e.g. [cyan]1 white blue red[/] or [cyan]1 w b r[/])",
+        )
+        lines.append(
+            f" [bold green]2[/] <color>      - Take 2 of the same color (needs {fmt_number(4)} in bank, "
+            "e.g. [cyan]2 blue[/] or [cyan]2 b[/])",
+        )
+        lines.append(
+            " [bold green]3[/] <tier> <idx> - Buy a face-up card (e.g. [cyan]3 1 0[/] for tier 1, index 0)",
+        )
+        lines.append(" [bold green]4[/] <idx>        - Buy a reserved card")
+        lines.append(" [bold green]5[/] <tier> <idx> - Reserve a face-up card")
+        lines.append(" [bold green]6[/] <tier>       - Reserve top card of a deck")
+        lines.append(" [bold red]q[/]                - Quit game")
+        if self.message:
+            lines.append("")
+            lines.append(f"[bold red]Message:[/] {self.message}")
+        self.query_one("#prompt", Static).update("\n".join(lines))
+
+    def _cmd_1(self, parts: list[str]) -> str | None:
+        """Take up to 3 different gem colors: 1 white blue red  OR  1 w b r."""
+        color_names = parts[1:]
+        if not color_names:
+            return "Need at least one color (full name or abbreviation)."
+        colors: list[GemColor] = []
+        for name in color_names:
+            color = parse_color_token(name)
+            if self.game.bank[color] <= 0:
+                return f"No tokens left for color: {color}"
+            colors.append(color)
+        self.result = TakeDifferent(colors=colors[:3])
+        self.exit()
+        return None
+
+    def _cmd_2(self, parts: list[str]) -> str | None:
+        """Take two of the same color."""
+        if len(parts) < 2:
+            return "Usage: 2 <color>"
+        color = parse_color_token(parts[1])
+        if self.game.bank[color] < self.game.config.minimum_tokens_to_buy_2:
+            return "Bank must have at least 4 of that color."
+        self.result = TakeDouble(color=color)
+        self.exit()
+        return None
+
+    def _cmd_3(self, parts: list[str]) -> str | None:
+        """Buy face-up card."""
+        if len(parts) < 3:
+            return "Usage: 3 <tier> <index>"
+        tier = int(parts[1])
+        idx = int(parts[2])
+        self.result = BuyCard(tier=tier, index=idx)
+        self.exit()
+        return None
+
+    def _cmd_4(self, parts: list[str]) -> str | None:
+        """Buy reserved card."""
+        if len(parts) < 2:
+            return "Usage: 4 <reserved_index>"
+        idx = int(parts[1])
+        if not (0 <= idx < len(self.player.reserved)):
+            return "Reserved index out of range."
+        self.result = BuyCardReserved(tier=0, index=idx)
+        self.exit()
+        return None
+
+    def _cmd_5(self, parts: list[str]) -> str | None:
+        """Reserve face-up card."""
+        if len(parts) < 3:
+            return "Usage: 5 <tier> <index>"
+        tier = int(parts[1])
+        idx = int(parts[2])
+        self.result = ReserveCard(tier=tier, index=idx, from_deck=False)
+        self.exit()
+        return None
+
+    def _cmd_6(self, parts: list[str]) -> str | None:
+        """Reserve top of deck."""
+        if len(parts) < 2:
+            return "Usage: 6 <tier>"
+        tier = int(parts[1])
+        self.result = ReserveCard(tier=tier, index=None, from_deck=True)
+        self.exit()
+        return None
+
+    def _unknown_cmd(self, _parts: list[str]) -> str:
+        return "Unknown command."
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Handle user input."""
+        text = (event.value or "").strip()
+        event.input.value = ""
+        if not text:
+            return
+        if text.lower() in {"q", "quit", "0"}:
+            self.result = None
+            self.exit()
+            return
+
+        parts = text.split()
+
+        cmds = {
+            "1": self._cmd_1,
+            "2": self._cmd_2,
+            "3": self._cmd_3,
+            "4": self._cmd_4,
+            "5": self._cmd_5,
+            "6": self._cmd_6,
+        }
+        cmd = parts[0]
+
+        error = cmds.get(cmd, self._unknown_cmd)(parts)
+
+        if error:
+            self.message = error
+            self._update_prompt()
+            return
+
+
+class DiscardApp(App[None]):
+    """Textual app to choose discards when over token limit."""
+
+    CSS = """
+    Screen {
+        layout: vertical;
+    }
+
+    #command_zone {
+        padding: 1 1;
+    }
+
+    #board {
+        padding: 0 1 1 1;
+    }
+
+    Input {
+        border: round $accent;
+    }
+    """
+
+    def __init__(self, game: GameState, player: PlayerState) -> None:
+        """Initialize the discard app."""
+        super().__init__()
+        self.game = game
+        self.player = player
+        self.discards: dict[GemColor, int] = dict.fromkeys(GEM_COLORS, 0)
+        self.message: str = ""
+
+    def compose(self) -> ComposeResult:  # type: ignore[override]
+        """Compose the discard app."""
+        yield Header(show_clock=False)
+
+        with Vertical(id="command_zone"):
+            yield Input(
+                placeholder="Enter color to discard, e.g. 'blue' or 'b'",
+                id="input_line",
+            )
+            yield Static("", id="prompt")
+
+        # Board directly under the command zone
+        yield Board(self.game, self.player, id="board")
+
+        yield Footer()
+
+    def on_mount(self) -> None:  # type: ignore[override]
+        """Mount the discard app."""
+        self._update_prompt()
+        self.query_one(Input).focus()
+
+    def _remaining_to_discard(self) -> int:
+        return self.player.total_tokens() - sum(self.discards.values()) - self.game.config.token_limit
+
+    def _update_prompt(self) -> None:
+        remaining = max(self._remaining_to_discard(), 0)
+        lines: list[str] = []
+        lines.append(
+            "You must discard "
+            f"{fmt_number(remaining)} token(s) "
+            f"to get down to {fmt_number(self.game.config.token_limit)}.",
+        )
+        disc_str = ", ".join(f"{fmt_gem(c)}={fmt_number(self.discards[c])}" for c in GEM_COLORS)
+        lines.append(f"Current planned discards: {{ {disc_str} }}")
+        lines.append(
+            "Type a color name or abbreviation (e.g. 'blue' or 'b') to discard one token.",
+        )
+        if self.message:
+            lines.append("")
+            lines.append(f"[bold red]Message:[/] {self.message}")
+        self.query_one("#prompt", Static).update("\n".join(lines))
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:  # type: ignore[override]
+        """Handle user input."""
+        raw = (event.value or "").strip()
+        event.input.value = ""
+        if not raw:
+            return
+
+        try:
+            color = parse_color_token(raw)
+        except ValueError:
+            self.message = f"Unknown color: {raw}"
+            self._update_prompt()
+            return
+
+        available = self.player.tokens[color] - self.discards[color]
+        if available <= 0:
+            self.message = f"No more {color} tokens available to discard."
+            self._update_prompt()
+            return
+
+        self.discards[color] += 1
+        if self._remaining_to_discard() <= 0:
+            self.exit()
+            return
+
+        self.message = ""
+        self._update_prompt()
+
+
+# ---------------------------------------------------------------------------
+# Noble choice app
+# ---------------------------------------------------------------------------
+
+
+class NobleChoiceApp(App[None]):
+    """Textual app to choose one noble."""
+
+    CSS = """
+    Screen {
+        layout: vertical;
+    }
+
+    #command_zone {
+        padding: 1 1;
+    }
+
+    #board {
+        padding: 0 1 1 1;
+    }
+
+    Input {
+        border: round $accent;
+    }
+    """
+
+    def __init__(
+        self,
+        game: GameState,
+        player: PlayerState,
+        nobles: list[Noble],
+    ) -> None:
+        """Initialize the noble choice app."""
+        super().__init__()
+        self.game = game
+        self.player = player
+        self.nobles = nobles
+        self.result: Noble | None = None
+        self.message: str = ""
+
+    def compose(self) -> ComposeResult:  # type: ignore[override]
+        """Compose the noble choice app."""
+        yield Header(show_clock=False)
+
+        with Vertical(id="command_zone"):
+            yield Input(
+                placeholder="Enter noble index, e.g. '0'",
+                id="input_line",
+            )
+            yield Static("", id="prompt")
+
+        # Board directly under the command zone
+        yield Board(self.game, self.player, id="board")
+
+        yield Footer()
+
+    def on_mount(self) -> None:  # type: ignore[override]
+        """Mount the noble choice app."""
+        self._update_prompt()
+        self.query_one(Input).focus()
+
+    def _update_prompt(self) -> None:
+        lines: list[str] = []
+        lines.append("[bold underline]You qualify for nobles:[/]")
+        for i, noble in enumerate(self.nobles):
+            lines.append(f" [bright_cyan]{i})[/] {format_noble(noble)}")
+        lines.append("Enter the index of the noble you want.")
+        if self.message:
+            lines.append("")
+            lines.append(f"[bold red]Message:[/] {self.message}")
+        self.query_one("#prompt", Static).update("\n".join(lines))
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:  # type: ignore[override]
+        """Handle user input."""
+        raw = (event.value or "").strip()
+        event.input.value = ""
+        if not raw:
+            return
+        try:
+            idx = int(raw)
+        except ValueError:
+            self.message = "Please enter a valid integer index."
+            self._update_prompt()
+            return
+        if not (0 <= idx < len(self.nobles)):
+            self.message = "Index out of range."
+            self._update_prompt()
+            return
+        self.result = self.nobles[idx]
+        self.exit()
+
+
+class TuiHuman(Strategy):
+    """Textual-based human player Strategy with colorful board."""
+
+    def choose_action(
+        self,
+        game: GameState,
+        player: PlayerState,
+    ) -> Action | None:
+        """Choose an action for the player."""
+        if not sys.stdout.isatty():
+            return None
+        app = ActionApp(game, player)
+        app.run()
+        return app.result
+
+    def choose_discard(
+        self,
+        game: GameState,
+        player: PlayerState,
+        excess: int,  # noqa: ARG002
+    ) -> dict[GemColor, int]:
+        """Choose tokens to discard."""
+        if not sys.stdout.isatty():
+            return dict.fromkeys(GEM_COLORS, 0)
+        app = DiscardApp(game, player)
+        app.run()
+        return app.discards
+
+    def choose_noble(
+        self,
+        game: GameState,
+        player: PlayerState,
+        nobles: list[Noble],
+    ) -> Noble:
+        """Choose a noble for the player."""
+        if not sys.stdout.isatty():
+            return nobles[0]
+        app = NobleChoiceApp(game, player, nobles)
+        app.run()
+        return app.result

python/splendor/main.py

@@ -0,0 +1,19 @@
+"""Main entry point for Splendor game."""
+
+from __future__ import annotations
+
+from .base import new_game, run_game
+from .bot import RandomBot
+from .human import TuiHuman
+
+
+def main() -> None:
+    """Main entry point."""
+    human = TuiHuman()
+    bot = RandomBot()
+    game_state = new_game(["You", "Bot A"])
+    run_game(game_state, [human, bot])
+
+
+if __name__ == "__main__":
+    main()