fix: resolve PLR2004 magic number lint violations in splendor code

Replace magic numbers in bot.py with existing GameConfig values
(max_token_take, minimum_tokens_to_buy_2) and named probability
constants. Add inline noqa for argument-count checks in human.py.
Remove temporary PLR2004 suppression from pyproject.toml.

https://claude.ai/code/session_01C17fUuuiYc8zrwpnw2cgpr

.vscode/settings.json

@@ -232,7 +232,6 @@
     "pyopenweathermap",
     "pyownet",
     "pytest",
-    "qalculate",
     "quicksuggest",
     "radarr",
     "readahead",
@@ -257,7 +256,6 @@
     "sessionmaker",
     "sessionstore",
     "shellcheck",
-    "signalbot",
     "signon",
     "Signons",
     "skia",
@@ -307,7 +305,6 @@
     "useragent",
     "usernamehw",
     "userprefs",
-    "vaninventory",
     "vfat",
     "victron",
     "virt",

common/optional/brain_substituter.nix

@@ -1,6 +0,0 @@
-{
-  nix.settings = {
-    trusted-substituters = [ "http://192.168.95.35:5000" ];
-    substituters = [ "http://192.168.95.35:5000/?priority=1&want-mass-query=true" ];
-  };
-}

flake.lock

@@ -8,11 +8,11 @@
       },
       "locked": {
         "dir": "pkgs/firefox-addons",
-        "lastModified": 1773979456,
+        "lastModified": 1772824881,
-        "narHash": "sha256-9kBMJ5IvxqNlkkj/swmE8uK1Sc7TL/LIRUI958m7uBM=",
+        "narHash": "sha256-NqX+JCA8hRV3GoYrsqnHB2IWKte1eQ8NK2WVbJkORcw=",
         "owner": "rycee",
         "repo": "nur-expressions",
-        "rev": "81e28f47ac18d9e89513929c77e711e657b64851",
+        "rev": "07e1616c9b13fe4794dad4bcc33cd7088c554465",
         "type": "gitlab"
       },
       "original": {
@@ -29,11 +29,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1774007980,
+        "lastModified": 1772807318,
-        "narHash": "sha256-FOnZjElEI8pqqCvB6K/1JRHTE8o4rer8driivTpq2uo=",
+        "narHash": "sha256-Qjw6ILt8cb2HQQpCmWNLMZZ63wEo1KjTQt+1BcQBr7k=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "9670de2921812bc4e0452f6e3efd8c859696c183",
+        "rev": "daa2c221320809f5514edde74d0ad0193ad54ed8",
         "type": "github"
       },
       "original": {
@@ -44,11 +44,11 @@
     },
     "nixos-hardware": {
       "locked": {
-        "lastModified": 1774018263,
+        "lastModified": 1771969195,
-        "narHash": "sha256-HHYEwK1A22aSaxv2ibhMMkKvrDGKGlA/qObG4smrSqc=",
+        "narHash": "sha256-qwcDBtrRvJbrrnv1lf/pREQi8t2hWZxVAyeMo7/E9sw=",
         "owner": "nixos",
         "repo": "nixos-hardware",
-        "rev": "2d4b4717b2534fad5c715968c1cece04a172b365",
+        "rev": "41c6b421bdc301b2624486e11905c9af7b8ec68e",
         "type": "github"
       },
       "original": {
@@ -60,11 +60,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1773821835,
+        "lastModified": 1772624091,
-        "narHash": "sha256-TJ3lSQtW0E2JrznGVm8hOQGVpXjJyXY2guAxku2O9A4=",
+        "narHash": "sha256-QKyJ0QGWBn6r0invrMAK8dmJoBYWoOWy7lN+UHzW1jc=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "b40629efe5d6ec48dd1efba650c797ddbd39ace0",
+        "rev": "80bdc1e5ce51f56b19791b52b2901187931f5353",
         "type": "github"
       },
       "original": {
@@ -76,11 +76,11 @@
     },
     "nixpkgs-master": {
       "locked": {
-        "lastModified": 1774051532,
+        "lastModified": 1772842888,
-        "narHash": "sha256-d3CGMweyYIcPuTj5BKq+1Lx4zwlgL31nVtN647tOZKo=",
+        "narHash": "sha256-bQRYIwRb9xuEMHTLd5EzjHhYMKzbUbIo7abFV84iUjM=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "8620c0b5cc8fbe76502442181be1d0514bc3a1b7",
+        "rev": "af5157af67f118e13172750f63012f199b61e3a1",
         "type": "github"
       },
       "original": {
@@ -125,11 +125,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1773889674,
+        "lastModified": 1772495394,
-        "narHash": "sha256-+ycaiVAk3MEshJTg35cBTUa0MizGiS+bgpYw/f8ohkg=",
+        "narHash": "sha256-hmIvE/slLKEFKNEJz27IZ8BKlAaZDcjIHmkZ7GCEjfw=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "29b6519f3e0780452bca0ac0be4584f04ac16cc5",
+        "rev": "1d9b98a29a45abe9c4d3174bd36de9f28755e3ff",
         "type": "github"
       },
       "original": {

frontend/README.md

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

frontend/eslint.config.js

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

frontend/index.html

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

frontend/package.json

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

frontend/public/vite.svg

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

frontend/src/App.css

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

frontend/src/App.tsx

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

frontend/src/api/client.ts

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

frontend/src/assets/react.svg

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

frontend/src/components/ContactDetail.tsx

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

frontend/src/components/ContactForm.tsx

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

frontend/src/components/ContactList.tsx

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

frontend/src/components/NeedList.tsx

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

frontend/src/components/RelationshipGraph.tsx

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

frontend/src/index.css

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

frontend/src/main.tsx

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

frontend/src/types/index.ts

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

frontend/tsconfig.app.json

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

frontend/tsconfig.json

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

frontend/tsconfig.node.json

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

frontend/vite.config.ts

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

overlays/default.nix

@@ -21,12 +21,10 @@
         alembic
         apprise
         apscheduler
-        confluent-kafka
         fastapi
         fastapi-cli
         httpx
         mypy
-        orjson
         polars
         psycopg
         pydantic
@@ -35,16 +33,15 @@
         pytest-cov
         pytest-mock
         pytest-xdist
-        python-multipart
+        requests
         ruff
         scalene
         sqlalchemy
         sqlalchemy
-        tenacity
         textual
         tinytuya
         typer
-        websockets
+        types-requests
       ]
     );
   };

pyproject.toml

@@ -7,25 +7,7 @@ requires-python = "~=3.13.0"
 readme = "README.md"
 license = "MIT"
 # these dependencies are a best effort and aren't guaranteed to work
-# for up-to-date dependencies, see overlays/default.nix
+dependencies = ["apprise", "apscheduler", "httpx", "polars", "pydantic", "pyyaml", "requests", "typer"]
-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 = [
@@ -36,6 +18,7 @@ dev = [
     "pytest-xdist",
     "pytest",
     "ruff",
+    "types-requests",
 ]
 
 [tool.ruff]
@@ -55,10 +38,7 @@ lint.ignore = [
 [tool.ruff.lint.per-file-ignores]
 
 "tests/**" = [
-    "ANN",     # (perm) type annotations not needed in tests
+    "S101", # (perm) pytest needs asserts
-    "D",       # (perm) docstrings not needed in tests
-    "PLR2004", # (perm) magic values are fine in test assertions
-    "S101",    # (perm) pytest needs asserts
 ]
 "python/stuff/**" = [
     "T201", # (perm) I don't care about print statements dir
@@ -68,9 +48,8 @@ lint.ignore = [
     "ERA001", # (perm) I don't care about print statements dir
 ]
 "python/splendor/**" = [
-    "S311",    # (perm) there is no security issue here
+    "S311", # (perm) there is no security issue here
-    "T201",    # (perm) I don't care about print statements dir
+    "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
@@ -84,9 +63,6 @@ lint.ignore = [
 "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"
@@ -110,5 +86,4 @@ exclude_lines = [
 
 [tool.pytest.ini_options]
 addopts = "-n auto -ra"
-testpaths = ["tests"]
 # --cov=system_tools --cov-report=term-missing --cov-report=xml --cov-report=html --cov-branch

python/alembic.ini

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

python/alembic/data_science_dev/versions/2026_03_24-adding_failedingestion_2f43120e3ffc.py

@@ -1,50 +0,0 @@
-"""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

@@ -1,80 +0,0 @@
-"""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

@@ -3,31 +3,26 @@
 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
+from python.orm import RichieBase
+from python.orm.base import get_postgres_engine
 
 if TYPE_CHECKING:
     from collections.abc import MutableMapping
 
-    from sqlalchemy.orm import DeclarativeBase
+# this is the Alembic Config object, which provides
-
+# access to the values within the .ini file in use.
 config = context.config
 
-base_class: type[DeclarativeBase] = config.attributes.get("base")
-if base_class is None:
-    error = "No base class provided. Use the database CLI to run alembic commands."
-    raise RuntimeError(error)
 
-target_metadata = base_class.metadata
+target_metadata = RichieBase.metadata
 logging.basicConfig(
     level="DEBUG",
     datefmt="%Y-%m-%dT%H:%M:%S%z",
@@ -40,24 +35,11 @@ logging.basicConfig(
 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='{RichieBase.schema_name}'", "schema=schema")
-    dynamic_schema_file_part1 = original_file.replace(f"schema='{schema_name}'", "schema=schema")
+    dynamic_schema_file = dynamic_schema_file_part1.replace(f"'{RichieBase.schema_name}.", "f'{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."""
@@ -70,19 +52,18 @@ def include_name(
     type_: Literal["schema", "table", "column", "index", "unique_constraint", "foreign_key_constraint"],
     _parent_names: MutableMapping[Literal["schema_name", "table_name", "schema_qualified_table_name"], str | None],
 ) -> bool:
-    """Filter tables to be included in the migration.
+    """This filter table 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.
+        parent_names (list[str]): 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
 
@@ -94,30 +75,19 @@ def run_migrations_online() -> None:
     and associate a connection with the context.
 
     """
-    env_prefix = config.attributes.get("env_prefix", "POSTGRES")
+    connectable = get_postgres_engine()
-    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,
+            version_table_schema=RichieBase.schema_name,
             include_name=include_name,
         )
 
         with context.begin_transaction():
             context.run_migrations()
-        connection.commit()
 
 
 run_migrations_online()

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

@@ -1,135 +0,0 @@
-"""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

@@ -1,58 +0,0 @@
-"""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

@@ -1,41 +0,0 @@
-"""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

@@ -1,54 +0,0 @@
-"""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

@@ -1,66 +0,0 @@
-"""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

@@ -1,171 +0,0 @@
-"""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

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

python/alembic/signal_bot/versions/2026_03_17-seprating_signal_bot_database_6eaf696e07a5.py

@@ -1,100 +0,0 @@
-"""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

@@ -1,72 +0,0 @@
-"""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

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

python/api/main.py

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

python/api/middleware.py

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

python/api/routers/__init__.py

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

python/api/routers/contact.py

@@ -1,24 +1,12 @@
 """Contact API router."""
 
-from pathlib import Path
+from fastapi import APIRouter, HTTPException
-
-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
+from python.orm.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):
@@ -192,16 +180,14 @@ def get_need(need_id: int, db: DbSession) -> Need:
     return need
 
 
-@router.delete("/needs/{need_id}", response_model=None)
+@router.delete("/needs/{need_id}")
-def delete_need(need_id: int, request: Request, db: DbSession) -> dict[str, bool] | HTMLResponse:
+def delete_need(need_id: int, db: DbSession) -> dict[str, bool]:
     """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}
 
 
@@ -275,16 +261,14 @@ def update_contact(
     return db_contact
 
 
-@router.delete("/contacts/{contact_id}", response_model=None)
+@router.delete("/contacts/{contact_id}")
-def delete_contact(contact_id: int, request: Request, db: DbSession) -> dict[str, bool] | HTMLResponse:
+def delete_contact(contact_id: int, db: DbSession) -> dict[str, bool]:
     """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}
 
 
@@ -310,13 +294,12 @@ def add_need_to_contact(
     return {"added": True}
 
 
-@router.delete("/contacts/{contact_id}/needs/{need_id}", response_model=None)
+@router.delete("/contacts/{contact_id}/needs/{need_id}")
 def remove_need_from_contact(
     contact_id: int,
     need_id: int,
-    request: Request,
     db: DbSession,
-) -> dict[str, bool] | HTMLResponse:
+) -> dict[str, bool]:
     """Remove a need from a contact."""
     contact = db.get(Contact, contact_id)
     if not contact:
@@ -330,8 +313,6 @@ def remove_need_from_contact(
         contact.needs.remove(need)
         db.commit()
 
-    if _is_htmx(request):
-        return HTMLResponse("")
     return {"removed": True}
 
 
@@ -423,13 +404,12 @@ def update_contact_relationship(
     return relationship
 
 
-@router.delete("/contacts/{contact_id}/relationships/{related_contact_id}", response_model=None)
+@router.delete("/contacts/{contact_id}/relationships/{related_contact_id}")
 def remove_contact_relationship(
     contact_id: int,
     related_contact_id: int,
-    request: Request,
     db: DbSession,
-) -> dict[str, bool] | HTMLResponse:
+) -> dict[str, bool]:
     """Remove a relationship between two contacts."""
     relationship = db.scalar(
         select(ContactRelationship).where(
@@ -442,8 +422,6 @@ def remove_contact_relationship(
 
     db.delete(relationship)
     db.commit()
-    if _is_htmx(request):
-        return HTMLResponse("")
     return {"deleted": True}
 
 

python/api/routers/frontend.py

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

python/api/routers/views.py

@@ -1,345 +0,0 @@
-"""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

@@ -1,198 +0,0 @@
-<!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

@@ -1,204 +0,0 @@
-{% 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

@@ -1,115 +0,0 @@
-{% 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

@@ -1,14 +0,0 @@
-{% 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

@@ -1,198 +0,0 @@
-{% 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

@@ -1,31 +0,0 @@
-{% 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

@@ -1,33 +0,0 @@
-{% 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

@@ -1,14 +0,0 @@
-<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

@@ -1,23 +0,0 @@
-{% 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

@@ -1,21 +0,0 @@
-{% 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

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

python/data_science/bluesky_ids.py

@@ -1,104 +0,0 @@
-"""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

@@ -1,143 +0,0 @@
-"""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

@@ -1,203 +0,0 @@
-"""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

@@ -1,230 +0,0 @@
-"""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

@@ -1,247 +0,0 @@
-"""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

@@ -1,129 +0,0 @@
-"""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/orm/__init__.py

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

python/orm/base.py

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

python/orm/common.py

@@ -1,51 +0,0 @@
-"""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/contact.py

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

python/orm/data_science_dev/__init__.py

@@ -1,11 +0,0 @@
-"""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

@@ -1,52 +0,0 @@
-"""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

@@ -1,10 +0,0 @@
-"""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

@@ -1,11 +0,0 @@
-"""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

@@ -1,33 +0,0 @@
-"""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

@@ -1,17 +0,0 @@
-"""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

@@ -1,71 +0,0 @@
-"""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

@@ -1,13 +0,0 @@
-"""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

@@ -1,29 +0,0 @@
-"""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

@@ -1,60 +0,0 @@
-"""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

@@ -1,150 +0,0 @@
-"""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/signal_bot/__init__.py

@@ -1,16 +0,0 @@
-"""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

@@ -1,52 +0,0 @@
-"""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

@@ -1,62 +0,0 @@
-"""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

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

python/orm/van_inventory/base.py

@@ -1,39 +0,0 @@
-"""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

@@ -1,46 +0,0 @@
-"""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

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

python/signal_bot/commands/__init__.py

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

python/signal_bot/commands/inventory.py

@@ -1,137 +0,0 @@
-"""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

@@ -1,64 +0,0 @@
-"""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

@@ -1,286 +0,0 @@
-"""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

@@ -1,80 +0,0 @@
-"""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

@@ -1,239 +0,0 @@
-"""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

@@ -1,97 +0,0 @@
-"""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

@@ -1,141 +0,0 @@
-"""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/bot.py

@@ -34,6 +34,11 @@ def can_bot_afford(player: PlayerState, card: Card) -> bool:
     return True
 
 
+_BUY_PROBABILITY = 0.5
+_RESERVE_PROBABILITY = 0.2
+_TAKE_DOUBLE_PROBABILITY = 0.5
+
+
 class RandomBot(Strategy):
     """Dumb bot that follows rules but doesn't think."""
 
@@ -48,19 +53,19 @@ class RandomBot(Strategy):
             for idx, card in enumerate(row):
                 if can_bot_afford(player, card):
                     affordable.append((tier, idx))
-        if affordable and random.random() < 0.5:
+        if affordable and random.random() < _BUY_PROBABILITY:
             tier, idx = random.choice(affordable)
             return BuyCard(tier=tier, index=idx)
 
-        if random.random() < 0.2:
+        if random.random() < _RESERVE_PROBABILITY:
             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:
+        if random.random() < _TAKE_DOUBLE_PROBABILITY:
-            colors_for_double = [c for c in BASE_COLORS if game.bank[c] >= 4]
+            colors_for_double = [c for c in BASE_COLORS if game.bank[c] >= game.config.minimum_tokens_to_buy_2]
             if colors_for_double:
                 return TakeDouble(color=random.choice(colors_for_double))
 
@@ -137,16 +142,16 @@ class PersonalizedBot2(Strategy):
             return BuyCardReserved(index=index)
 
         colors_for_diff = [c for c in BASE_COLORS if game.bank[c] > 0]
-        if len(colors_for_diff) >= 3:
+        if len(colors_for_diff) >= game.config.max_token_take:
             random.shuffle(colors_for_diff)
-            return TakeDifferent(colors=colors_for_diff[:3])
+            return TakeDifferent(colors=colors_for_diff[: game.config.max_token_take])
 
         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])
+        return TakeDifferent(colors=colors_for_diff[: game.config.max_token_take])
 
     def choose_discard(
         self,
@@ -179,7 +184,7 @@ def buy_card(game: GameState, player: PlayerState) -> Action | 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:
+    if len(colors_for_diff) >= game.config.max_token_take:
         random.shuffle(colors_for_diff)
         return TakeDifferent(colors=colors_for_diff[: game.config.max_token_take])
     return None
@@ -204,16 +209,16 @@ class PersonalizedBot3(Strategy):
             return action
 
         colors_for_diff = [color for color in BASE_COLORS if game.bank[color] > 0]
-        if len(colors_for_diff) >= 3:
+        if len(colors_for_diff) >= game.config.max_token_take:
             random.shuffle(colors_for_diff)
-            return TakeDifferent(colors=colors_for_diff[:3])
+            return TakeDifferent(colors=colors_for_diff[: game.config.max_token_take])
 
         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])
+        return TakeDifferent(colors=colors_for_diff[: game.config.max_token_take])
 
     def choose_discard(
         self,
@@ -242,12 +247,13 @@ class PersonalizedBot4(Strategy):
         """Initialize the bot."""
         super().__init__(name=name)
 
-    def filter_actions(self, actions: list[Action]) -> list[Action]:
+    def filter_actions(self, actions: list[Action], max_token_take: int) -> 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)
+            if (isinstance(action, TakeDifferent) and len(action.colors) == max_token_take)
+            or not isinstance(action, TakeDifferent)
         ]
 
     def choose_action(self, game: GameState, player: PlayerState) -> Action | None:
@@ -255,7 +261,7 @@ class PersonalizedBot4(Strategy):
         legal_actions = get_legal_actions(game, player)
         print(len(legal_actions))
 
-        good_actions = self.filter_actions(legal_actions)
+        good_actions = self.filter_actions(legal_actions, game.config.max_token_take)
         print(len(good_actions))
 
         print(good_actions)
@@ -267,16 +273,16 @@ class PersonalizedBot4(Strategy):
             return action
 
         colors_for_diff = [color for color in BASE_COLORS if game.bank[color] > 0]
-        if len(colors_for_diff) >= 3:
+        if len(colors_for_diff) >= game.config.max_token_take:
             random.shuffle(colors_for_diff)
-            return TakeDifferent(colors=colors_for_diff[:3])
+            return TakeDifferent(colors=colors_for_diff[: game.config.max_token_take])
 
         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])
+        return TakeDifferent(colors=colors_for_diff[: game.config.max_token_take])
 
     def choose_discard(
         self,

python/splendor/human.py

@@ -407,7 +407,7 @@ class ActionApp(App[None]):
 
     def _cmd_2(self, parts: list[str]) -> str | None:
         """Take two of the same color."""
-        if len(parts) < 2:
+        if len(parts) < 2:  # noqa: PLR2004
             return "Usage: 2 <color>"
         color = parse_color_token(parts[1])
         if self.game.bank[color] < self.game.config.minimum_tokens_to_buy_2:
@@ -418,7 +418,7 @@ class ActionApp(App[None]):
 
     def _cmd_3(self, parts: list[str]) -> str | None:
         """Buy face-up card."""
-        if len(parts) < 3:
+        if len(parts) < 3:  # noqa: PLR2004
             return "Usage: 3 <tier> <index>"
         tier = int(parts[1])
         idx = int(parts[2])
@@ -428,7 +428,7 @@ class ActionApp(App[None]):
 
     def _cmd_4(self, parts: list[str]) -> str | None:
         """Buy reserved card."""
-        if len(parts) < 2:
+        if len(parts) < 2:  # noqa: PLR2004
             return "Usage: 4 <reserved_index>"
         idx = int(parts[1])
         if not (0 <= idx < len(self.player.reserved)):
@@ -439,7 +439,7 @@ class ActionApp(App[None]):
 
     def _cmd_5(self, parts: list[str]) -> str | None:
         """Reserve face-up card."""
-        if len(parts) < 3:
+        if len(parts) < 3:  # noqa: PLR2004
             return "Usage: 5 <tier> <index>"
         tier = int(parts[1])
         idx = int(parts[2])
@@ -449,7 +449,7 @@ class ActionApp(App[None]):
 
     def _cmd_6(self, parts: list[str]) -> str | None:
         """Reserve top of deck."""
-        if len(parts) < 2:
+        if len(parts) < 2:  # noqa: PLR2004
             return "Usage: 6 <tier>"
         tier = int(parts[1])
         self.result = ReserveCard(tier=tier, index=None, from_deck=True)