ran treefmt

frontend/.gitignore

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

overlays/default.nix

@@ -38,7 +38,6 @@
         ruff
         scalene
         sqlalchemy
-        sqlalchemy
         tenacity
         textual
         tiktoken

pyproject.toml

@@ -3,7 +3,7 @@ name = "system_tools"
 version = "0.1.0"
 description = ""
 authors = [{ name = "Richie Cahill", email = "richie@tmmworkshop.com" }]
-requires-python = "~=3.13.0"
+requires-python = "~=3.14.0"
 readme = "README.md"
 license = "MIT"
 # these dependencies are a best effort and aren't guaranteed to work
@@ -12,20 +12,22 @@ dependencies = [
     "alembic",
     "apprise",
     "apscheduler",
+    "fastapi",
+    "fastapi-cli",
     "httpx",
-    "python-multipart",
     "polars",
     "psycopg[binary]",
     "pydantic",
-    "pyyaml",
+    "python-multipart",
     "sqlalchemy",
+    "tenacity",
+    "tinytuya",
     "typer",
     "websockets",
 ]
 
 [project.scripts]
 database = "python.database_cli:app"
-van-inventory = "python.van_inventory.main:serve"
 whisper-transcribe = "python.tools.whisper.transcribe:main"
 
 [dependency-groups]
@@ -41,7 +43,7 @@ dev = [
 
 [tool.ruff]
 
-target-version = "py313"
+target-version = "py314"
 
 line-length = 120
 

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

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

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

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

python/api/dependencies.py

@@ -1,11 +1,15 @@
 """FastAPI dependencies."""
 
-from collections.abc import Iterator
-from typing import Annotated
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
 
 from fastapi import Depends, Request
 from sqlalchemy.orm import Session
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
 
 def get_db(request: Request) -> Iterator[Session]:
     """Get database session from app state."""

python/api/main.py

@@ -1,9 +1,10 @@
 """FastAPI interface for Contact database."""
 
+from __future__ import annotations
+
 import logging
-from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
-from typing import Annotated
+from typing import TYPE_CHECKING, Annotated
 
 import typer
 import uvicorn
@@ -14,6 +15,9 @@ from python.api.routers import contact_router, views_router
 from python.common import configure_logger
 from python.orm.common import get_postgres_engine
 
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
 logger = logging.getLogger(__name__)
 
 

python/api/middleware.py

@@ -1,10 +1,14 @@
 """Middleware for the FastAPI application."""
 
 from compression import zstd
+from typing import TYPE_CHECKING
+
 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
-from starlette.requests import Request
 from starlette.responses import Response
 
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
 MINIMUM_RESPONSE_SIZE = 500
 
 

python/api/routers/contact.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.orm import selectinload
 
-from python.api.dependencies import DbSession
+from python.api.dependencies import DbSession  # noqa: TC001 this is a FastAPI needed at runtime
 from python.orm.richie.contact import Contact, ContactRelationship, Need, RelationshipType
 
 TEMPLATES_DIR = Path(__file__).parent.parent / "templates"

python/api/routers/views.py

@@ -9,7 +9,7 @@ from fastapi.templating import Jinja2Templates
 from sqlalchemy import select
 from sqlalchemy.orm import Session, selectinload
 
-from python.api.dependencies import DbSession
+from python.api.dependencies import DbSession  # noqa: TC001 this is a FastAPI needed at runtime
 from python.orm.richie.contact import Contact, ContactRelationship, Need, RelationshipType
 
 TEMPLATES_DIR = Path(__file__).parent.parent / "templates"

python/database_cli.py

@@ -4,12 +4,10 @@ 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
+    database richie downgrade head-1
+    database richie revision --autogenerate -m "add meals table"
 """
 
 from __future__ import annotations
@@ -48,10 +46,7 @@ class DatabaseConfig:
 
     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 = Config()
         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", ".")
@@ -76,13 +71,6 @@ DATABASES: dict[str, DatabaseConfig] = {
         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",
-    ),
 }
 
 

python/heater/main.py

@@ -1,9 +1,10 @@
 """FastAPI heater control service."""
 
+from __future__ import annotations
+
 import logging
-from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
-from typing import Annotated
+from typing import TYPE_CHECKING, Annotated
 
 import typer
 import uvicorn
@@ -13,6 +14,9 @@ from python.common import configure_logger
 from python.heater.controller import HeaterController
 from python.heater.models import ActionResult, DeviceConfig, HeaterStatus
 
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
 logger = logging.getLogger(__name__)
 
 

python/installer/__main__.py

@@ -262,6 +262,7 @@ def installer(
             ):
                 run(command, check=True, stdin=test.stdout)
 
+    # Fixed mount point for the new system; the installer runs as root on a fresh disk
     mnt_dir = "/tmp/nix_install"  # noqa: S108
 
     Path(mnt_dir).mkdir(parents=True, exist_ok=True)

python/installer/old_installer.py

@@ -16,9 +16,13 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
+logger = logging.getLogger(__name__)
+ESCAPE_KEY = 27
+
 
 def configure_logger(level: str = "INFO") -> None:
     """Configure the logger.
+
     Args:
         level (str, optional): The logging level. Defaults to "INFO".
     """
@@ -32,15 +36,17 @@ def configure_logger(level: str = "INFO") -> None:
 
 def bash_wrapper(command: str) -> str:
     """Execute a bash command and capture the output.
+
     Args:
         command (str): The bash command to be executed.
+
     Returns:
         Tuple[str, int]: A tuple containing the output of the command (stdout) as a string,
         the error output (stderr) as a string (optional), and the return code as an integer.
     """
-    logging.debug(f"running {command=}")
+    logger.debug(f"running {command=}")
     # This is a acceptable risk
-    process = Popen(command.split(), stdout=PIPE, stderr=PIPE)  # noqa: S603
+    process = Popen(command.split(), stdout=PIPE, stderr=PIPE)
     output, _ = process.communicate()
     if process.returncode != 0:
         error = f"Failed to run command {command=} return code {process.returncode=}"
@@ -51,6 +57,7 @@ def bash_wrapper(command: str) -> str:
 
 def partition_disk(disk: str, swap_size: int, reserve: int = 0) -> None:
     """Partition a disk.
+
     Args:
         disk (str): The disk to partition.
         swap_size (int): The size of the swap partition in GB.
@@ -58,7 +65,7 @@ def partition_disk(disk: str, swap_size: int, reserve: int = 0) -> None:
         reserve (int, optional): The size of the reserve partition in GB. Defaults to 0.
             minimum value is 0.
     """
-    logging.info(f"partitioning {disk=}")
+    logger.info(f"partitioning {disk=}")
     swap_size = max(swap_size, 1)
     reserve = max(reserve, 0)
 
@@ -66,16 +73,16 @@ def partition_disk(disk: str, swap_size: int, reserve: int = 0) -> None:
 
     if reserve > 0:
         msg = f"Creating swap partition on {disk=} with size {swap_size=}GiB and reserve {reserve=}GiB"
-        logging.info(msg)
+        logger.info(msg)
 
         swap_start = swap_size + reserve
         swap_partition = f"mkpart swap -{swap_start}GiB -{reserve}GiB "
     else:
-        logging.info(f"Creating swap partition on {disk=} with size {swap_size=}GiB")
+        logger.info(f"Creating swap partition on {disk=} with size {swap_size=}GiB")
         swap_start = swap_size
         swap_partition = f"mkpart swap -{swap_start}GiB 100% "
 
-    logging.debug(f"{swap_partition=}")
+    logger.debug(f"{swap_partition=}")
 
     create_partitions = (
         f"parted --script --align=optimal {disk} -- "
@@ -87,13 +94,14 @@ def partition_disk(disk: str, swap_size: int, reserve: int = 0) -> None:
     )
     bash_wrapper(create_partitions)
 
-    logging.info(f"{disk=} successfully partitioned")
+    logger.info(f"{disk=} successfully partitioned")
 
 
 def create_zfs_pool(pool_disks: Sequence[str], mnt_dir: str) -> None:
     """Create a ZFS pool.
+
     Args:
-        disks (Sequence[str]): A tuple of disks to use for the pool.
+        pool_disks (Sequence[str]): A tuple of disks to use for the pool.
         mnt_dir (str): The mount directory.
     """
     if len(pool_disks) <= 0:
@@ -125,13 +133,12 @@ def create_zfs_pool(pool_disks: Sequence[str], mnt_dir: str) -> None:
     bash_wrapper(zpool_create)
     zpools = bash_wrapper("zpool list -o name")
     if "root_pool" not in zpools.splitlines():
-        logging.critical("Failed to create root_pool")
+        logger.critical("Failed to create root_pool")
         sys.exit(1)
 
 
 def create_zfs_datasets() -> None:
     """Create ZFS datasets."""
-
     bash_wrapper("zfs create -o canmount=noauto -o reservation=10G root_pool/root")
     bash_wrapper("zfs create root_pool/home")
     bash_wrapper("zfs create root_pool/var -o reservation=1G")
@@ -146,7 +153,7 @@ def create_zfs_datasets() -> None:
     }
     missing_datasets = expected_datasets.difference(datasets.splitlines())
     if missing_datasets:
-        logging.critical(f"Failed to create pools {missing_datasets}")
+        logger.critical(f"Failed to create pools {missing_datasets}")
         sys.exit(1)
 
 
@@ -159,6 +166,8 @@ def get_cpu_manufacturer() -> str:
     for line in output.splitlines():
         if "vendor_id" in line:
             return id_vendor[line.split(": ")[1].strip()]
+    error = "Failed to get CPU manufacturer"
+    raise RuntimeError(error)
 
 
 def get_boot_drive_id(disk: str) -> str:
@@ -167,9 +176,8 @@ def get_boot_drive_id(disk: str) -> str:
     return output.splitlines()[1]
 
 
-def create_nix_hardware_file(mnt_dir: str, disks: Sequence[str], encrypt: bool) -> None:
+def create_nix_hardware_file(mnt_dir: str, disks: Sequence[str], *, encrypt: bool) -> None:
     """Create a NixOS hardware file."""
-
     cpu_manufacturer = get_cpu_manufacturer()
 
     devices = ""
@@ -193,7 +201,15 @@ def create_nix_hardware_file(mnt_dir: str, disks: Sequence[str], encrypt: bool)
         '  imports = [ (modulesPath + "/installer/scan/not-detected.nix") ];\n\n'
         "  boot = {\n"
         "    initrd = {\n"
-        '      availableKernelModules = [ \n        "ahci"\n        "ehci_pci"\n        "nvme"\n        "sd_mod"\n        "usb_storage"\n        "usbhid"\n        "xhci_pci"\n      ];\n'
+        "      availableKernelModules = [ \n"
+        '        "ahci"\n'
+        '        "ehci_pci"\n'
+        '        "nvme"\n'
+        '        "sd_mod"\n'
+        '        "usb_storage"\n'
+        '        "usbhid"\n'
+        '        "xhci_pci"\n'
+        "      ];\n"
         "      kernelModules = [ ];\n"
         f" {devices}"
         "    };\n"
@@ -207,11 +223,18 @@ def create_nix_hardware_file(mnt_dir: str, disks: Sequence[str], encrypt: bool)
         '    "/nix" = {\n      device = "root_pool/nix";\n      fsType = "zfs";\n    };\n\n'
         '    "/boot" = {\n'
         f'      device = "/dev/disk/by-uuid/{get_boot_drive_id(disks[0])}";\n'
-        '      fsType = "vfat";\n      options = [\n        "fmask=0077"\n        "dmask=0077"\n      ];\n    };\n  };\n\n'
+        '      fsType = "vfat";\n'
+        "      options = [\n"
+        '        "fmask=0077"\n'
+        '        "dmask=0077"\n'
+        "      ];\n"
+        "    };\n"
+        "  };\n\n"
         "  swapDevices = [ ];\n\n"
         "  networking.useDHCP = lib.mkDefault true;\n\n"
         '  nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";\n'
-        f"  hardware.cpu.{cpu_manufacturer}.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware;\n"
+        f"  hardware.cpu.{cpu_manufacturer}.updateMicrocode = lib.mkDefault "
+        "config.hardware.enableRedistributableFirmware;\n"
         f'  networking.hostId = "{host_id}";\n'
         "}\n"
     )
@@ -219,7 +242,7 @@ def create_nix_hardware_file(mnt_dir: str, disks: Sequence[str], encrypt: bool)
     Path(f"{mnt_dir}/etc/nixos/hardware-configuration.nix").write_text(nix_hardware)
 
 
-def install_nixos(mnt_dir: str, disks: Sequence[str], encrypt: bool) -> None:
+def install_nixos(mnt_dir: str, disks: Sequence[str], *, encrypt: bool) -> None:
     """Install NixOS."""
     bash_wrapper(f"mount -o X-mount.mkdir -t zfs root_pool/root {mnt_dir}")
     bash_wrapper(f"mount -o X-mount.mkdir -t zfs root_pool/home {mnt_dir}/home")
@@ -230,14 +253,16 @@ def install_nixos(mnt_dir: str, disks: Sequence[str], encrypt: bool) -> None:
         bash_wrapper(f"mkfs.vfat -n EFI {disk}-part1")
 
     # set up mirroring afterwards if more than one disk
-    boot_partition = f"mount -t vfat -o fmask=0077,dmask=0077,iocharset=iso8859-1,X-mount.mkdir {disks[0]}-part1 {mnt_dir}/boot"
+    boot_partition = (
+        f"mount -t vfat -o fmask=0077,dmask=0077,iocharset=iso8859-1,X-mount.mkdir {disks[0]}-part1 {mnt_dir}/boot"
+    )
     bash_wrapper(boot_partition)
 
     bash_wrapper(f"nixos-generate-config --root {mnt_dir}")
 
-    create_nix_hardware_file(mnt_dir, disks, encrypt)
+    create_nix_hardware_file(mnt_dir, disks, encrypt=encrypt)
 
-    run(("nixos-install", "--root", mnt_dir), check=True)  # noqa: S603
+    run(("nixos-install", "--root", mnt_dir), check=True)
 
 
 def installer(
@@ -247,27 +272,38 @@ def installer(
     encrypt_key: str | None,
 ) -> None:
     """Main."""
-    logging.info("Starting installation")
+    logger.info("Starting installation")
 
     for disk in disks:
         partition_disk(disk, swap_size, reserve)
 
         if encrypt_key:
             sleep(1)
-            for command in (
-                f'printf "{encrypt_key}" | cryptsetup luksFormat --type luks2 {disk}-part2 -',
-                f'printf "{encrypt_key}" | cryptsetup luksOpen {disk}-part2 luks-root-pool-{disk.split("/")[-1]}-part2 -',
-            ):
-                run(command, shell=True, check=True)
+            key_input = encrypt_key.encode()
+            run(
+                ("cryptsetup", "luksFormat", "--type", "luks2", f"{disk}-part2", "-"),
+                input=key_input,
+                check=True,
+            )
+            run(
+                (
+                    "cryptsetup",
+                    "luksOpen",
+                    f"{disk}-part2",
+                    f"luks-root-pool-{disk.split('/')[-1]}-part2",
+                    "-",
+                ),
+                input=key_input,
+                check=True,
+            )
 
+    # Fixed mount point for the new system; the installer runs as root on a fresh disk
     mnt_dir = "/tmp/nix_install"  # noqa: S108
 
     Path(mnt_dir).mkdir(parents=True, exist_ok=True)
 
     if encrypt_key:
-        pool_disks = [
-            f"/dev/mapper/luks-root-pool-{disk.split('/')[-1]}-part2" for disk in disks
-        ]
+        pool_disks = [f"/dev/mapper/luks-root-pool-{disk.split('/')[-1]}-part2" for disk in disks]
     else:
         pool_disks = [f"{disk}-part2" for disk in disks]
 
@@ -275,57 +311,73 @@ def installer(
 
     create_zfs_datasets()
 
-    install_nixos(mnt_dir, disks, encrypt_key)
+    install_nixos(mnt_dir, disks, encrypt=bool(encrypt_key))
 
-    logging.info("Installation complete")
+    logger.info("Installation complete")
 
 
 class Cursor:
-    def __init__(self):
+    """Track cursor position and constrain movement to screen bounds."""
+
+    def __init__(self) -> None:
+        """Initialize cursor position and screen dimensions."""
         self.x_position = 0
         self.y_position = 0
         self.height = 0
         self.width = 0
 
-    def set_height(self, height: int):
+    def set_height(self, height: int) -> None:
+        """Set the maximum screen height."""
         self.height = height
 
-    def set_width(self, width: int):
+    def set_width(self, width: int) -> None:
+        """Set the maximum screen width."""
         self.width = width
 
     def x_bounce_check(self, cursor: int) -> int:
+        """Clamp an x position to the screen width."""
         cursor = max(0, cursor)
         return min(self.width - 1, cursor)
 
     def y_bounce_check(self, cursor: int) -> int:
+        """Clamp a y position to the screen height."""
         cursor = max(0, cursor)
         return min(self.height - 1, cursor)
 
-    def set_x(self, x: int):
+    def set_x(self, x: int) -> None:
+        """Set the cursor x position."""
         self.x_position = self.x_bounce_check(x)
 
-    def set_y(self, y: int):
+    def set_y(self, y: int) -> None:
+        """Set the cursor y position."""
         self.y_position = self.y_bounce_check(y)
 
     def get_x(self) -> int:
+        """Get the cursor x position."""
         return self.x_position
 
     def get_y(self) -> int:
+        """Get the cursor y position."""
         return self.y_position
 
-    def move_up(self):
+    def move_up(self) -> None:
+        """Move the cursor up one row."""
         self.set_y(self.y_position - 1)
 
-    def move_down(self):
+    def move_down(self) -> None:
+        """Move the cursor down one row."""
         self.set_y(self.y_position + 1)
 
-    def move_left(self):
+    def move_left(self) -> None:
+        """Move the cursor left one column."""
         self.set_x(self.x_position - 1)
 
-    def move_right(self):
+    def move_right(self) -> None:
+        """Move the cursor right one column."""
         self.set_x(self.x_position + 1)
 
     def navigation(self, key: int) -> None:
+        """Move the cursor for a curses navigation key."""
         action = {
             curses.KEY_DOWN: self.move_down,
             curses.KEY_UP: self.move_up,
@@ -339,7 +391,8 @@ class Cursor:
 class State:
     """State class to store the state of the program."""
 
-    def __init__(self):
+    def __init__(self) -> None:
+        """Initialize installer menu state."""
         self.key = 0
         self.cursor = Cursor()
 
@@ -357,11 +410,9 @@ class State:
 
 
 def get_device(raw_device: str) -> dict[str, str]:
+    """Parse an lsblk key-value device row."""
     raw_device_components = raw_device.split(" ")
-    return {
-        thing.split("=")[0].lower(): thing.split("=")[1].strip('"')
-        for thing in raw_device_components
-    }
+    return {thing.split("=")[0].lower(): thing.split("=")[1].strip('"') for thing in raw_device_components}
 
 
 def get_devices() -> list[dict[str, str]]:
@@ -373,6 +424,7 @@ def get_devices() -> list[dict[str, str]]:
 
 def get_device_id_mapping() -> dict[str, set[str]]:
     """Get a list of device ids.
+
     Returns:
         list[str]: the list of device ids
     """
@@ -387,9 +439,8 @@ def get_device_id_mapping() -> dict[str, set[str]]:
     return device_id_mapping
 
 
-def calculate_device_menu_padding(
-    devices: list[dict[str, str]], column: str, padding: int = 0
-) -> int:
+def calculate_device_menu_padding(devices: list[dict[str, str]], column: str, padding: int = 0) -> int:
+    """Calculate the width needed for a device menu column."""
     return max(len(device[column]) for device in devices) + padding
 
 
@@ -401,6 +452,7 @@ def draw_device_ids(
     menu_width: list[int],
     device_ids: set[str],
 ) -> tuple[State, int]:
+    """Draw selectable device IDs for a device row."""
     for device_id in sorted(device_ids):
         row_number = row_number + 1
         if row_number == state.cursor.get_y() and state.cursor.get_x() in menu_width:
@@ -429,8 +481,9 @@ def draw_device_menu(
     state: State,
     menu_start_y: int = 0,
     menu_start_x: int = 0,
-) -> State:
-    """draw the device menu and handle user input
+) -> tuple[State, int]:
+    """Draw the device menu and handle user input.
+
     Args:
         std_screen (curses.window): the curses window to draw on
         devices (list[dict[str, str]]): the list of devices to draw
@@ -438,6 +491,7 @@ def draw_device_menu(
         state (State): the state object to update
         menu_start_y (int, optional): the y position to start drawing the menu. Defaults to 0.
         menu_start_x (int, optional): the x position to start drawing the menu. Defaults to 0.
+
     Returns:
         State: the updated state object
     """
@@ -448,7 +502,9 @@ def draw_device_menu(
     type_padding = calculate_device_menu_padding(devices, "type", padding)
     mountpoints_padding = calculate_device_menu_padding(devices, "mountpoints", padding)
 
-    device_header = f"{'Name':{name_padding}}{'Size':{size_padding}}{'Type':{type_padding}}{'Mountpoints':{mountpoints_padding}}"
+    device_header = (
+        f"{'Name':{name_padding}}{'Size':{size_padding}}{'Type':{type_padding}}{'Mountpoints':{mountpoints_padding}}"
+    )
 
     menu_width = range(menu_start_x, len(device_header) + menu_start_x)
 
@@ -481,8 +537,9 @@ def draw_device_menu(
 
 
 def debug_menu(std_screen: curses.window, key: int) -> None:
+    """Draw debug information for the current curses screen."""
     height, width = std_screen.getmaxyx()
-    width_height = "Width: {}, Height: {}".format(width, height)
+    width_height = f"Width: {width}, Height: {height}"
     std_screen.addstr(height - 4, 0, width_height, curses.color_pair(5))
 
     key_pressed = f"Last key pressed: {key}"[: width - 1]
@@ -490,7 +547,7 @@ def debug_menu(std_screen: curses.window, key: int) -> None:
         key_pressed = "No key press detected..."[: width - 1]
     std_screen.addstr(height - 3, 0, key_pressed)
 
-    for i in range(0, 8):
+    for i in range(8):
         std_screen.addstr(height - 2, i * 3, f"{i}██", curses.color_pair(i))
 
 
@@ -500,12 +557,11 @@ def status_bar(
     width: int,
     height: int,
 ) -> None:
+    """Draw the footer status bar."""
     std_screen.attron(curses.A_REVERSE)
     std_screen.attron(curses.color_pair(3))
 
-    status_bar = (
-        f"Press 'q' to exit | STATUS BAR | Pos: {cursor.get_x()}, {cursor.get_y()}"
-    )
+    status_bar = f"Press 'q' to exit | STATUS BAR | Pos: {cursor.get_x()}, {cursor.get_y()}"
     std_screen.addstr(height - 1, 0, status_bar)
     std_screen.addstr(height - 1, len(status_bar), " " * (width - len(status_bar) - 1))
 
@@ -514,13 +570,15 @@ def status_bar(
 
 
 def set_color() -> None:
+    """Initialize curses color pairs."""
     curses.start_color()
     curses.use_default_colors()
-    for i in range(0, curses.COLORS):
+    for i in range(curses.COLORS):
         curses.init_pair(i + 1, i, -1)
 
 
 def get_text_input(std_screen: curses.window, prompt: str, y: int, x: int) -> str:
+    """Read text input from a curses screen."""
     curses.echo()
     std_screen.addstr(y, x, prompt)
     input_str = ""
@@ -528,10 +586,10 @@ def get_text_input(std_screen: curses.window, prompt: str, y: int, x: int) -> st
         key = std_screen.getch()
         if key == ord("\n"):
             break
-        elif key == 27:  # ESC key
+        if key == ESCAPE_KEY:
             input_str = ""
             break
-        elif key in (curses.KEY_BACKSPACE, ord("\b"), 127):
+        if key in (curses.KEY_BACKSPACE, ord("\b"), 127):
             input_str = input_str[:-1]
             std_screen.addstr(y, x + len(prompt), input_str + " ")
         else:
@@ -546,6 +604,7 @@ def swap_size_input(
     state: State,
     swap_offset: int,
 ) -> State:
+    """Handle swap size input."""
     swap_size_text = "Swap size (GB): "
     std_screen.addstr(swap_offset, 0, f"{swap_size_text}{state.swap_size}")
     if state.key == ord("\n") and state.cursor.get_y() == swap_offset:
@@ -557,9 +616,7 @@ def swap_size_input(
             state.swap_size = int(swap_size_str)
             state.show_swap_input = False
         except ValueError:
-            std_screen.addstr(
-                swap_offset, 0, "Invalid input. Press any key to continue."
-            )
+            std_screen.addstr(swap_offset, 0, "Invalid input. Press any key to continue.")
             std_screen.getch()
             state.show_swap_input = False
 
@@ -571,22 +628,19 @@ def reserve_size_input(
     state: State,
     reserve_offset: int,
 ) -> State:
+    """Handle reserve size input."""
     reserve_size_text = "reserve size (GB): "
     std_screen.addstr(reserve_offset, 0, f"{reserve_size_text}{state.reserve_size}")
     if state.key == ord("\n") and state.cursor.get_y() == reserve_offset:
         state.show_reserve_input = True
 
     if state.show_reserve_input:
-        reserve_size_str = get_text_input(
-            std_screen, reserve_size_text, reserve_offset, 0
-        )
+        reserve_size_str = get_text_input(std_screen, reserve_size_text, reserve_offset, 0)
         try:
             state.reserve_size = int(reserve_size_str)
             state.show_reserve_input = False
         except ValueError:
-            std_screen.addstr(
-                reserve_offset, 0, "Invalid input. Press any key to continue."
-            )
+            std_screen.addstr(reserve_offset, 0, "Invalid input. Press any key to continue.")
             std_screen.getch()
             state.show_reserve_input = False
 
@@ -594,9 +648,11 @@ def reserve_size_input(
 
 
 def draw_menu(std_screen: curses.window) -> State:
-    """draw the menu and handle user input
+    """Draw the menu and handle user input.
+
     Args:
         std_screen (curses.window): the curses window to draw on
+
     Returns:
         State: the state object
     """
@@ -656,17 +712,18 @@ def draw_menu(std_screen: curses.window) -> State:
 
 
 def main() -> None:
+    """Run the installer menu and start installation."""
     configure_logger("DEBUG")
 
     state = curses.wrapper(draw_menu)
 
     encrypt_key = getenv("ENCRYPT_KEY")
 
-    logging.info("installing_nixos")
-    logging.info(f"disks: {state.selected_device_ids}")
-    logging.info(f"swap_size: {state.swap_size}")
-    logging.info(f"reserve: {state.reserve_size}")
-    logging.info(f"encrypted: {bool(encrypt_key)}")
+    logger.info("installing_nixos")
+    logger.info(f"disks: {state.selected_device_ids}")
+    logger.info(f"swap_size: {state.swap_size}")
+    logger.info(f"reserve: {state.reserve_size}")
+    logger.info(f"encrypted: {bool(encrypt_key)}")
 
     sleep(3)
 

python/orm/__init__.py

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

python/orm/richie/__init__.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from python.orm.richie.audiobook import Audiobook, AudiobookAuthor, AudiobookSeries
 from python.orm.richie.base import RichieBase, TableBase, TableBaseBig, TableBaseSmall
 from python.orm.richie.contact import (
     Contact,
@@ -12,6 +13,9 @@ from python.orm.richie.contact import (
 )
 
 __all__ = [
+    "Audiobook",
+    "AudiobookAuthor",
+    "AudiobookSeries",
     "Contact",
     "ContactNeed",
     "ContactRelationship",

python/orm/richie/audiobook.py

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

python/orm/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/splendor/.gitignore

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

python/splendor/__init__.py

@@ -1 +0,0 @@
-"""init."""

python/splendor/base.py

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

python/splendor/bot.py

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

python/splendor/human.py

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

python/splendor/main.py

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

python/splendor/public_state.py

@@ -1,111 +0,0 @@
-"""Public state for RL/search."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from .base import (
-    BASE_COLORS,
-    BASE_INDEX,
-    GEM_ORDER,
-    Card,
-    GameState,
-    Noble,
-    PlayerState,
-)
-
-
-@dataclass(frozen=True)
-class ObsCard:
-    """Numeric-ish card view for RL/search."""
-
-    tier: int
-    points: int
-    color_index: int
-    cost: list[int]
-
-
-@dataclass(frozen=True)
-class ObsNoble:
-    """Numeric-ish noble view for RL/search."""
-
-    points: int
-    requirements: list[int]
-
-
-@dataclass(frozen=True)
-class ObsPlayer:
-    """Numeric-ish player view for RL/search."""
-
-    tokens: list[int]
-    discounts: list[int]
-    score: int
-    cards: list[ObsCard]
-    reserved: list[ObsCard]
-    nobles: list[ObsNoble]
-
-
-@dataclass(frozen=True)
-class Observation:
-    """Full public state for RL/search."""
-
-    current_player: int
-    bank: list[int]
-    players: list[ObsPlayer]
-    table_by_tier: dict[int, list[ObsCard]]
-    decks_remaining: dict[int, int]
-    available_nobles: list[ObsNoble]
-
-
-def _encode_card(card: Card) -> ObsCard:
-    color_index = BASE_INDEX.get(card.color, -1)
-    cost_vec = [card.cost.get(c, 0) for c in BASE_COLORS]
-    return ObsCard(
-        tier=card.tier,
-        points=card.points,
-        color_index=color_index,
-        cost=cost_vec,
-    )
-
-
-def _encode_noble(noble: Noble) -> ObsNoble:
-    req_vec = [noble.requirements.get(c, 0) for c in BASE_COLORS]
-    return ObsNoble(
-        points=noble.points,
-        requirements=req_vec,
-    )
-
-
-def _encode_player(player: PlayerState) -> ObsPlayer:
-    tokens_vec = [player.tokens[c] for c in GEM_ORDER]
-    discounts_vec = [player.discounts[c] for c in GEM_ORDER]
-    cards_enc = [_encode_card(c) for c in player.cards]
-    reserved_enc = [_encode_card(c) for c in player.reserved]
-    nobles_enc = [_encode_noble(n) for n in player.nobles]
-    return ObsPlayer(
-        tokens=tokens_vec,
-        discounts=discounts_vec,
-        score=player.score,
-        cards=cards_enc,
-        reserved=reserved_enc,
-        nobles=nobles_enc,
-    )
-
-
-def to_observation(game: GameState) -> Observation:
-    """Create a structured observation of the full public state."""
-    bank_vec = [game.bank[c] for c in GEM_ORDER]
-    players_enc = [_encode_player(p) for p in game.players]
-    table_enc: dict[int, list[ObsCard]] = {
-        tier: [_encode_card(c) for c in row] for tier, row in game.table_by_tier.items()
-    }
-    decks_remaining = {tier: len(deck) for tier, deck in game.decks_by_tier.items()}
-    nobles_enc = [_encode_noble(n) for n in game.available_nobles]
-    return Observation(
-        current_player=game.current_player_index,
-        bank=bank_vec,
-        players=players_enc,
-        table_by_tier=table_enc,
-        decks_remaining=decks_remaining,
-        available_nobles=nobles_enc,
-    )

python/splendor/sim.py

@@ -1,36 +0,0 @@
-"""Simulate a step in the game."""
-
-from __future__ import annotations
-
-import copy
-
-from .base import Action, GameState, PlayerState, apply_action, check_nobles_for_player
-from .bot import RandomBot
-
-
-class SimStrategy(RandomBot):
-    """Strategy used in simulate_step.
-
-    We never call choose_action here (caller chooses actions),
-    but we reuse discard/noble-selection logic.
-    """
-
-    def choose_action(self, game: GameState, player: PlayerState) -> Action | None:  # noqa: ARG002
-        """Choose an action for the current player."""
-        msg = "SimStrategy.choose_action should not be used in simulate_step"
-        raise RuntimeError(msg)
-
-
-def simulate_step(game: GameState, action: Action) -> GameState:
-    """Return a deep-copied next state after applying action for the current player.
-
-    Useful for tree search / MCTS:
-
-        next_state = simulate_step(state, action)
-    """
-    next_state = copy.deepcopy(game)
-    sim_strategy = SimStrategy()
-    apply_action(next_state, sim_strategy, action)
-    check_nobles_for_player(next_state, sim_strategy, next_state.current_player)
-    next_state.next_player()
-    return next_state

python/splendor/simulat.py

@@ -1,50 +0,0 @@
-"""Simulator for Splendor game."""
-
-from __future__ import annotations
-
-from collections import defaultdict
-from pathlib import Path
-from statistics import mean
-
-from .base import GameConfig, load_cards, load_nobles, new_game, run_game
-from .bot import PersonalizedBot4, RandomBot
-
-
-def main() -> None:
-    """Main entry point."""
-    turn_limit = 1000
-    good_games = 0
-    games = 1
-    winners: dict[str, list] = defaultdict(list)
-    game_data = Path(__file__).parent / "game_data"
-
-    cards = load_cards(game_data / "cards/default.json")
-    nobles = load_nobles(game_data / "nobles/default.json")
-
-    for _ in range(games):
-        bot_a = RandomBot("bot_a")
-        bot_b = RandomBot("bot_b")
-        bot_c = RandomBot("bot_c")
-        bot_d = PersonalizedBot4("my_bot")
-        config = GameConfig(
-            cards=cards,
-            nobles=nobles,
-            turn_limit=turn_limit,
-        )
-        players = (bot_a, bot_b, bot_c, bot_d)
-        game_state = new_game(players, config)
-        winner, turns = run_game(game_state)
-        if turns < turn_limit:
-            good_games += 1
-            winners[winner.strategy.name].append(turns)
-
-    print(
-        f"out of {games} {turn_limit} turn games with {len(players)}"
-        f"random bots there where {good_games} games where a bot won"
-    )
-    for name, turns in winners.items():
-        print(f"{name} won {len(turns)} games in {mean(turns):.2f} turns")
-
-
-if __name__ == "__main__":
-    main()

python/system_tests/validate_system.py

@@ -4,7 +4,7 @@ import logging
 import sys
 import tomllib
 from os import environ
-from pathlib import Path
+from pathlib import Path  # noqa: TC003 This is required for the typer CLI
 from socket import gethostname
 
 import typer

python/tools/audiobook/__init__.py

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

python/tools/audiobook/audible_convert.py

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

python/tools/audiobook/catalog.py

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

python/tools/audiobook/llm_tool_calling.py

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

python/tools/audiobook/metadata_agent.py

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

python/van_inventory/__init__.py

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

python/van_inventory/dependencies.py

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

python/van_inventory/main.py

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

python/van_inventory/routers/__init__.py

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

python/van_inventory/routers/api.py

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

python/van_inventory/routers/frontend.py

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

python/van_inventory/static/style.css

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

python/van_inventory/templates/availability.html

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

python/van_inventory/templates/base.html

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

python/van_inventory/templates/items.html

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

python/van_inventory/templates/meal_detail.html

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

python/van_inventory/templates/meals.html

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

python/van_inventory/templates/partials/ingredient_rows.html

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

python/van_inventory/templates/partials/item_rows.html

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

python/van_inventory/templates/partials/meal_rows.html

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

python/van_weather/main.py

@@ -257,7 +257,7 @@ def update_weather(config: Config) -> None:
 
     logger.info(f"Masked location: {masked_lat}, {masked_lon}")
 
-    weather = fetch_weather(config.pirate_weather_api_key, lat, lon)
+    weather = fetch_weather(config.pirate_weather_api_key, masked_lat, masked_lon)
     logger.info(f"Weather: {weather.temperature}°F, {weather.condition}")
 
     post_to_ha(config.ha_url, config.ha_token, weather)

python/van_weather/models.py

@@ -1,6 +1,8 @@
 """Models for van weather service."""
 
-from datetime import datetime
+from __future__ import annotations
+
+from datetime import datetime  # noqa: TC003 This is required for pydantic
 
 from pydantic import BaseModel, field_serializer
 

python/zfs/dataset.py

@@ -108,7 +108,7 @@ class Dataset:
         self.written = int(properties["written"]["value"])
         self.xattr = properties["xattr"]["value"]
 
-    def get_snapshots(self) -> list[Snapshot] | None:
+    def get_snapshots(self) -> list[Snapshot]:
         """Get all snapshots from zfs and process then is test dicts of sets."""
         snapshots_data = _zfs_list(f"zfs list -t snapshot -pHj {self.name} -o all")
 
@@ -125,10 +125,10 @@ class Dataset:
         if return_code == 0:
             return "snapshot created"
 
-        if snapshots := self.get_snapshots():
-            snapshot_names = {snapshot.name for snapshot in snapshots}
-            if snapshot_name in snapshot_names:
-                return f"Snapshot {snapshot_name} already exists for {self.name}"
+        snapshots = self.get_snapshots()
+        snapshot_names = {snapshot.name for snapshot in snapshots}
+        if snapshot_name in snapshot_names:
+            return f"Snapshot {snapshot_name} already exists for {self.name}"
 
         return f"Failed to create snapshot {snapshot_name} for {self.name}"
 

systems/brain/services/van_inventory.nix

@@ -1,50 +0,0 @@
-{
-  pkgs,
-  inputs,
-  ...
-}:
-{
-  networking.firewall.allowedTCPPorts = [ 8001 ];
-
-  users = {
-    users.vaninventory = {
-      isSystemUser = true;
-      group = "vaninventory";
-    };
-    groups.vaninventory = { };
-  };
-
-  systemd.services.van_inventory = {
-    description = "Van Inventory API";
-    after = [
-      "network.target"
-      "postgresql.service"
-    ];
-    requires = [ "postgresql.service" ];
-    wantedBy = [ "multi-user.target" ];
-
-    environment = {
-      PYTHONPATH = "${inputs.self}/";
-      VAN_INVENTORY_DB = "vaninventory";
-      VAN_INVENTORY_USER = "vaninventory";
-      VAN_INVENTORY_HOST = "/run/postgresql";
-      VAN_INVENTORY_PORT = "5432";
-    };
-
-    serviceConfig = {
-      Type = "simple";
-      User = "vaninventory";
-      Group = "vaninventory";
-      ExecStart = "${pkgs.my_python}/bin/python -m python.van_inventory.main --host 0.0.0.0 --port 8001";
-      Restart = "on-failure";
-      RestartSec = "5s";
-      StandardOutput = "journal";
-      StandardError = "journal";
-      NoNewPrivileges = true;
-      ProtectSystem = "strict";
-      ProtectHome = "read-only";
-      PrivateTmp = true;
-      ReadOnlyPaths = [ "${inputs.self}" ];
-    };
-  };
-}

tests/test_audiobook_catalog.py

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

tests/test_parallelize.py

@@ -19,7 +19,7 @@ if TYPE_CHECKING:
 class MockFuture(Future):
     """MockFuture."""
 
-    def __init__(self, result: Any) -> None:  # noqa: ANN401
+    def __init__(self, result: Any) -> None:
         """Init."""
         super().__init__()
         self._result = result
@@ -31,7 +31,7 @@ class MockFuture(Future):
         logging.debug(f"{timeout}=")
         return self._exception
 
-    def result(self, timeout: float | None = None) -> Any:  # noqa: ANN401
+    def result(self, timeout: float | None = None) -> Any:
         """Result."""
         logging.debug(f"{timeout}=")
         return self._result
@@ -40,11 +40,11 @@ class MockFuture(Future):
 class MockPoolExecutor(ThreadPoolExecutor):
     """MockPoolExecutor."""
 
-    def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         """Initializes a new ThreadPoolExecutor instance."""
         super().__init__(*args, **kwargs)
 
-    def submit(self, fn: Callable[..., Any], /, *args: Any, **kwargs: Any) -> Future:  # noqa: ANN401
+    def submit(self, fn: Callable[..., Any], /, *args: Any, **kwargs: Any) -> Future:
         """Submits a callable to be executed with the given arguments.
 
         Args: