beetkeeper 0.0.1__py3-none-any.whl

beetkeeper/__init__.py

@@ -0,0 +1,5 @@
+# beetkeeper: A highly configurable, self-hosted app for beets music library management. Supports both automated and manual workflows.
+# Copyright (C) 2026 Zach Gottesman
+# This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+# This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+# You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

beetkeeper/_version.py

@@ -0,0 +1,3 @@
+"""This is the canonical source of truth for the `beetkeeper` version."""
+
+__version__ = "0.0.1"

beetkeeper/api/__init__.py

@@ -0,0 +1,8 @@
+"""
+This module contains the components necessary for defining `FastAPI` app instance, along with its composite
+subrouters, and any static files / HTML templates.
+"""
+
+from beetkeeper.api.fastapi_app import beetkeeper_app
+
+__all__ = ["beetkeeper_app"]

beetkeeper/api/api_models/__init__.py

@@ -0,0 +1,23 @@
+from beetkeeper.api.api_models.events_api_models import (
+    AlbumEventBody,
+    APIAlbum,
+    APIEventType,
+    APITrack,
+    EventIngestResponse,
+    ImportTaskFilesEventBody,
+    MultiItemEventIngestResponse,
+    TrackEventBody,
+)
+from beetkeeper.api.api_models.import_api_models import ImportSubmitRequest
+
+__all__ = [
+    "APIAlbum",
+    "APIEventType",
+    "APITrack",
+    "AlbumEventBody",
+    "EventIngestResponse",
+    "ImportSubmitRequest",
+    "ImportTaskFilesEventBody",
+    "MultiItemEventIngestResponse",
+    "TrackEventBody",
+]

beetkeeper/api/api_models/events_api_models.py

@@ -0,0 +1,231 @@
+"""Define any custom FastAPI request or response pydantic models for the `/api/events` subrouter here."""
+
+from enum import StrEnum, unique
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+
+@unique
+class APIEventType(StrEnum):
+    """
+    Subset of beets listener `event_type`s which the API accepts from our plugin client.
+    See also:
+        https://beets.readthedocs.io/en/stable/dev/plugins/events.html
+    """
+
+    ALBUM_IMPORTED = "album_imported"
+    ALBUM_REMOVED = "album_removed"
+    IMPORT_TASK_FILES = "import_task_files"
+    TRACK_IMPORTED = "item_imported"
+    TRACK_REMOVED = "item_removed"
+
+
+class _BaseEventResponse(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    event_type: APIEventType
+
+
+class EventIngestResponse(_BaseEventResponse):
+    ingested_id: int | None = Field(
+        default=None, description="The beets db ID of the processed album / item, if successful."
+    )
+    error_msg: str | None = Field(None, description="Error message to return to the client, if any.")
+
+
+class MultiItemEventIngestResponse(_BaseEventResponse):
+    event_ingest_responses: list[EventIngestResponse] = Field(default_factory=list)
+
+
+class _BaseEventBody(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="allow")
+    event_type: APIEventType
+    pushed_at: AwareDatetime
+
+
+class AlbumEventBody(_BaseEventBody):
+    """
+    A post request payload expected from the plugin's listener for the `beetsplug.beetkeeper_plugin.event_listener`
+    client's `album_imported` event pushes.
+    """
+
+    album_fields: APIAlbum
+
+
+class TrackEventBody(AlbumEventBody):
+    """
+    A post request payload expected from the plugin's listener for the `beetsplug.beetkeeper_plugin.event_listener`
+    client's `item_imported` (track imported) event pushes.
+    """
+
+    track_fields: APITrack
+
+
+# TODO[later]: add submodels corresponding to relevant parts of the following beets event models:
+#  `beets.importer.ImportSession`, `beets.importer.ImportTask`, `beets.autotag.AlbumMatch`
+
+
+class ImportTaskFilesEventBody(_BaseEventBody):
+    choice_flag: str | None
+    imported_items: list[TrackEventBody]
+
+
+class APIAlbum(BaseModel):
+    """
+    Model for the relevant parts of a `beets.library.Album` instance. used during beets plugin client push events
+    for an event tied to a given album. For simplicity, we only mark `id` as required, with all other fields as
+    optional (which might not be the case for beets internals).
+
+    NOTE: This was generated from `build_scripts/code_gen/pydantic_field_info_from_beets_model.py`.
+    """
+
+    id: int
+    added: float | None = Field(default=None)
+    album: str = Field(default="")
+    albumartist: str = Field(default="")
+    albumartist_credit: str = Field(default="")
+    albumartist_sort: str = Field(default="")
+    albumartists: list | None = Field(default=None)
+    albumartists_credit: list | None = Field(default=None)
+    albumartists_sort: list | None = Field(default=None)
+    albumdisambig: str = Field(default="")
+    albumstatus: str = Field(default="")
+    albumtype: str = Field(default="")
+    albumtypes: list | None = Field(default=None)
+    artpath: bytes = Field(default=b"")
+    asin: str = Field(default="")
+    barcode: str = Field(default="")
+    catalognum: str = Field(default="")
+    comp: bool = Field(default=False)
+    country: str = Field(default="")
+    day: int | None = Field(default=None)
+    discogs_albumid: int | None = Field(default=None)
+    discogs_artistid: int | None = Field(default=None)
+    discogs_labelid: int | None = Field(default=None)
+    disctotal: int | None = Field(default=None)
+    genres: list | None = Field(default=None)
+    label: str = Field(default="")
+    language: str = Field(default="")
+    mb_albumartistid: str = Field(default="")
+    mb_albumartistids: list | None = Field(default=None)
+    mb_albumid: str = Field(default="")
+    mb_releasegroupid: str = Field(default="")
+    month: int | None = Field(default=None)
+    original_day: int | None = Field(default=None)
+    original_month: int | None = Field(default=None)
+    original_year: int | None = Field(default=None)
+    r128_album_gain: float | None = Field(default=None)
+    release_group_title: str = Field(default="")
+    releasegroupdisambig: str = Field(default="")
+    rg_album_gain: float | None = Field(default=None)
+    rg_album_peak: float | None = Field(default=None)
+    script: str = Field(default="")
+    style: str = Field(default="")
+    year: int | None = Field(default=None)
+
+
+class APITrack(BaseModel):
+    """
+    Model for the relevant parts of a `beets.library.Item` (track) instance. used during beets plugin client push events
+    for an event tied to a single track ('Item'). For simplicity, we only mark `id` as required, with all other fields as
+    optional (which might not be the case for beets internals).
+
+    NOTE: This was generated from `build_scripts/code_gen/pydantic_field_info_from_beets_model.py`.
+    """
+
+    id: int
+    acoustid_fingerprint: str = Field(default="")
+    acoustid_id: str = Field(default="")
+    added: float | None = Field(default=None)
+    album: str = Field(default="")
+    album_id: int | None = Field(default=None)
+    albumartist: str = Field(default="")
+    albumartist_credit: str = Field(default="")
+    albumartist_sort: str = Field(default="")
+    albumartists: list | None = Field(default=None)
+    albumartists_credit: list | None = Field(default=None)
+    albumartists_sort: list | None = Field(default=None)
+    albumdisambig: str = Field(default="")
+    albumstatus: str = Field(default="")
+    albumtype: str = Field(default="")
+    albumtypes: list | None = Field(default=None)
+    arrangers: list | None = Field(default=None)
+    arrangers_ids: list | None = Field(default=None)
+    artist: str = Field(default="")
+    artist_credit: str = Field(default="")
+    artist_sort: str = Field(default="")
+    artists: list | None = Field(default=None)
+    artists_credit: list | None = Field(default=None)
+    artists_ids: list | None = Field(default=None)
+    artists_sort: list | None = Field(default=None)
+    asin: str = Field(default="")
+    barcode: str = Field(default="")
+    bitdepth: int | None = Field(default=None)
+    bitrate: int | None = Field(default=None)
+    bitrate_mode: str = Field(default="")
+    bpm: int | None = Field(default=None)
+    catalognum: str = Field(default="")
+    channels: int | None = Field(default=None)
+    comments: str = Field(default="")
+    comp: bool = Field(default=False)
+    composer_sort: str = Field(default="")
+    composers: list | None = Field(default=None)
+    composers_ids: list | None = Field(default=None)
+    country: str = Field(default="")
+    day: int | None = Field(default=None)
+    disc: int | None = Field(default=None)
+    discogs_albumid: int | None = Field(default=None)
+    discogs_artistid: int | None = Field(default=None)
+    discogs_labelid: int | None = Field(default=None)
+    disctitle: str = Field(default="")
+    disctotal: int | None = Field(default=None)
+    encoder: str = Field(default="")
+    encoder_info: str = Field(default="")
+    encoder_settings: str = Field(default="")
+    format: str = Field(default="")
+    genres: list | None = Field(default=None)
+    grouping: str = Field(default="")
+    initial_key: str = Field(default="")
+    isrc: str = Field(default="")
+    label: str = Field(default="")
+    language: str = Field(default="")
+    length: float | None = Field(default=None)
+    lyricists: list | None = Field(default=None)
+    lyricists_ids: list | None = Field(default=None)
+    lyrics: str = Field(default="")
+    mb_albumartistid: str = Field(default="")
+    mb_albumartistids: list | None = Field(default=None)
+    mb_albumid: str = Field(default="")
+    mb_artistid: str = Field(default="")
+    mb_artistids: list | None = Field(default=None)
+    mb_releasegroupid: str = Field(default="")
+    mb_releasetrackid: str = Field(default="")
+    mb_trackid: str = Field(default="")
+    mb_workid: str = Field(default="")
+    media: str = Field(default="")
+    month: int | None = Field(default=None)
+    mtime: float | None = Field(default=None)
+    original_day: int | None = Field(default=None)
+    original_month: int | None = Field(default=None)
+    original_year: int | None = Field(default=None)
+    path: bytes = Field(default=b"")
+    r128_album_gain: float | None = Field(default=None)
+    r128_track_gain: float | None = Field(default=None)
+    release_group_title: str = Field(default="")
+    releasegroupdisambig: str = Field(default="")
+    remixers: list | None = Field(default=None)
+    remixers_ids: list | None = Field(default=None)
+    rg_album_gain: float | None = Field(default=None)
+    rg_album_peak: float | None = Field(default=None)
+    rg_track_gain: float | None = Field(default=None)
+    rg_track_peak: float | None = Field(default=None)
+    samplerate: int | None = Field(default=None)
+    script: str = Field(default="")
+    style: str = Field(default="")
+    subtitle: str = Field(default="")
+    title: str = Field(default="")
+    track: int | None = Field(default=None)
+    trackdisambig: str = Field(default="")
+    tracktotal: int | None = Field(default=None)
+    work: str = Field(default="")
+    work_disambig: str = Field(default="")
+    year: int | None = Field(default=None)

beetkeeper/api/api_models/import_api_models.py

@@ -0,0 +1,17 @@
+"""Request/response models for the `/api/import` endpoints (see `beetkeeper.core.import_worker`)."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ImportSubmitRequest(BaseModel):
+    """Body for starting an import: the filesystem path(s) beets should import."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    paths: list[str] = Field(min_length=1, description="One or more paths (files/dirs) to import.")
+    quiet: bool = Field(
+        default=False,
+        description=(
+            "Run non-interactively (like `beet import -q`): never prompt. Strong matches are applied "
+            "automatically; anything else falls back to beets' `quiet_fallback` config (skip by default)."
+        ),
+    )

beetkeeper/api/api_routes/__init__.py

@@ -0,0 +1,21 @@
+"""
+Aggregates the JSON `APIRouter`s (grouped per functional domain) under the `/api` prefix.
+
+The HTML-serving `ui_routes` router is aggregated separately and mounted (not under `/api`) in
+`beetkeeper.api.fastapi_app`.
+"""
+
+from fastapi import APIRouter
+
+from beetkeeper.api.api_routes.events_router import events_router
+from beetkeeper.api.api_routes.health_router import health_router
+from beetkeeper.api.api_routes.import_router import import_router
+from beetkeeper.api.api_routes.query_router import query_router
+
+api_router = APIRouter(prefix="/api")
+api_router.include_router(events_router)
+api_router.include_router(health_router)
+api_router.include_router(import_router)
+api_router.include_router(query_router)
+
+__all__ = ["api_router"]

beetkeeper/api/api_routes/events_router.py

@@ -0,0 +1,80 @@
+"""
+Event endpoints which the `beetsplug.beetkeeper_plugin.event_listener.BeetKeeperClient` will push beets events to.
+
+Each push is recorded as one `ListenerEvent` row plus its per-entity child rows (`AlbumEvent` / `TrackEvent`),
+written through the async `SessionDep` dependency (see `beetkeeper.db.session`).
+See also:
+    https://beets.readthedocs.io/en/stable/dev/plugins/events.html
+    `src/beetsplug/beetkeeper_plugin/event_listener.py`
+"""
+
+import logging
+from datetime import datetime
+from typing import cast
+
+from fastapi import APIRouter, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from beetkeeper.api.api_models import (
+    AlbumEventBody,
+    EventIngestResponse,
+    ImportTaskFilesEventBody,
+    MultiItemEventIngestResponse,
+    TrackEventBody,
+)
+from beetkeeper.api.api_models.events_api_models import APIEventType
+from beetkeeper.db.models import AlbumEvent, ListenerEvent, TrackEvent
+from beetkeeper.db.session import SessionDep
+
+_LOGGER = logging.getLogger(__name__)
+events_router = APIRouter(prefix="/events")
+
+
+async def _record_listener_event(session: AsyncSession, event_type: APIEventType, pushed_at: datetime) -> int:
+    """Inserts the parent `ListenerEvent` and flushes to obtain its generated `event_id` for child FKs."""
+    listener_event = ListenerEvent(event_type=event_type, pushed_at=pushed_at)
+    session.add(listener_event)
+    await session.flush()  # populates the autoincrement `event_id` used as the child rows' FK
+    return cast("int", listener_event.event_id)
+
+
+@events_router.post("/album", status_code=status.HTTP_201_CREATED)
+async def album(album_event: AlbumEventBody, session: SessionDep) -> EventIngestResponse:
+    _LOGGER.debug("Processing album event type: %s ...", album_event.event_type)
+    listener_event_id = await _record_listener_event(session, album_event.event_type, album_event.pushed_at)
+    session.add(AlbumEvent(listener_event_id=listener_event_id, beets_album_id=album_event.album_fields.id))
+    await session.commit()
+    return EventIngestResponse(event_type=album_event.event_type, ingested_id=album_event.album_fields.id)
+
+
+@events_router.post("/track", status_code=status.HTTP_201_CREATED)
+async def track(track_event: TrackEventBody, session: SessionDep) -> EventIngestResponse:
+    _LOGGER.debug("Processing track event type: %s ...", track_event.event_type)
+    listener_event_id = await _record_listener_event(session, track_event.event_type, track_event.pushed_at)
+    session.add(
+        TrackEvent(
+            listener_event_id=listener_event_id,
+            beets_item_id=track_event.track_fields.id,
+            beets_album_id=track_event.album_fields.id,
+        )
+    )
+    await session.commit()
+    return EventIngestResponse(event_type=track_event.event_type, ingested_id=track_event.track_fields.id)
+
+
+@events_router.post("/filesystem", status_code=status.HTTP_201_CREATED)
+async def filesystem(fs_event: ImportTaskFilesEventBody, session: SessionDep) -> MultiItemEventIngestResponse:
+    _LOGGER.debug("Processing filesystem event type: %s ...", fs_event.event_type)
+    listener_event_id = await _record_listener_event(session, fs_event.event_type, fs_event.pushed_at)
+    ingest_responses: list[EventIngestResponse] = []
+    for item in fs_event.imported_items:
+        session.add(
+            TrackEvent(
+                listener_event_id=listener_event_id,
+                beets_item_id=item.track_fields.id,
+                beets_album_id=item.album_fields.id,
+            )
+        )
+        ingest_responses.append(EventIngestResponse(event_type=item.event_type, ingested_id=item.track_fields.id))
+    await session.commit()
+    return MultiItemEventIngestResponse(event_type=fs_event.event_type, event_ingest_responses=ingest_responses)

beetkeeper/api/api_routes/health_router.py

@@ -0,0 +1,47 @@
+"""
+Health / diagnostics endpoint.
+
+Reports the serving process's pid and the current import-leader (the `import_lock` holder). With
+`server_workers > 1` this makes the multi-worker behaviour observable: requests are served by different
+pids, but exactly one process is the import leader, and all share the same DB-backed job state.
+"""
+
+import logging
+import os
+import socket
+
+from fastapi import APIRouter
+from pydantic import BaseModel, ConfigDict
+
+from beetkeeper.api.dependencies import ImportStoreDep
+
+_LOGGER = logging.getLogger(__name__)
+health_router = APIRouter(prefix="/health")
+
+
+class HealthInfo(BaseModel):
+    """Per-process health snapshot."""
+
+    model_config = ConfigDict(frozen=True)
+    process_pid: int
+    hostname: str
+    import_lock_holder: str | None
+    is_import_leader: bool
+    job_count: int
+
+
+@health_router.get("")
+async def health(store: ImportStoreDep) -> HealthInfo:
+    """Report this process's pid, the current import leader (lock holder), and the shared job count."""
+    pid = os.getpid()
+    hostname = socket.gethostname()
+    holder = await store.lock_holder()
+    jobs = await store.list()
+    return HealthInfo(
+        process_pid=pid,
+        hostname=hostname,
+        import_lock_holder=holder,
+        # The worker id is "<hostname>:<pid>:<uuid>"; this process is the leader iff it holds the lock.
+        is_import_leader=holder is not None and holder.startswith(f"{hostname}:{pid}:"),
+        job_count=len(jobs),
+    )

beetkeeper/api/api_routes/import_router.py

@@ -0,0 +1,63 @@
+"""
+RESTful (JSON) endpoints to drive interactive beets imports.
+
+Job state lives in the cross-process DB-backed `ImportStore`; the leader-elected `ImportWorker`
+(`beetkeeper.core.import_worker`) runs the actual beets import. These routes only read/write the store, so
+they work on any uvicorn process. HTML/HTMX equivalents live in `ui_routes.import_ui_fragments_router`.
+"""
+
+import logging
+
+from fastapi import APIRouter, HTTPException, status
+
+from beetkeeper.api.api_models import ImportSubmitRequest
+from beetkeeper.api.dependencies import ImportStoreDep
+from beetkeeper.core import ImportDecision, ImportJob
+
+_LOGGER = logging.getLogger(__name__)
+import_router = APIRouter(prefix="/import")
+
+
+@import_router.post("", status_code=status.HTTP_201_CREATED)
+async def start_import(body: ImportSubmitRequest, store: ImportStoreDep) -> ImportJob:
+    """Enqueue an import of the given paths and return the created (PENDING) job.
+
+    Set `quiet=true` to import non-interactively (the `beet import -q` equivalent): no decision prompts.
+    """
+    return await store.create(body.paths, quiet=body.quiet)
+
+
+@import_router.get("")
+async def list_imports(store: ImportStoreDep) -> list[ImportJob]:
+    """List all known import jobs."""
+    return await store.list()
+
+
+@import_router.get("/{job_id}")
+async def get_import(job_id: str, store: ImportStoreDep) -> ImportJob:
+    """Return a single import job (poll this for status / the pending decision)."""
+    return await _require_job(store, job_id)
+
+
+@import_router.post("/{job_id}/decision")
+async def decide_import(job_id: str, decision: ImportDecision, store: ImportStoreDep) -> ImportJob:
+    """Answer the decision an import is parked on; 409 if it isn't awaiting one."""
+    await _require_job(store, job_id)
+    if not await store.submit_decision(job_id, decision):
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Job is not awaiting a decision.")
+    return await _require_job(store, job_id)
+
+
+@import_router.post("/{job_id}/abort")
+async def abort_import(job_id: str, store: ImportStoreDep) -> ImportJob:
+    """Request cooperative cancellation of an in-flight import."""
+    await _require_job(store, job_id)
+    await store.request_abort(job_id)
+    return await _require_job(store, job_id)
+
+
+async def _require_job(store: ImportStoreDep, job_id: str) -> ImportJob:
+    job = await store.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"No import job '{job_id}'.")
+    return job

beetkeeper/api/api_routes/query_router.py

@@ -0,0 +1,71 @@
+"""Read-only beets query routes (`list`, `stats`, `fields`), backed by `core.BeetsLibrary`."""
+
+import logging
+from pathlib import Path
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Query
+
+from beetkeeper.api.dependencies import BeetsLibraryDep
+
+_LOGGER = logging.getLogger(__name__)
+query_router = APIRouter(prefix="/query")
+
+
+# For each possible query param and its corresponding beets query search filter, see:
+# https://beets.readthedocs.io/en/v2.12.0/reference/query.html#combining-keywords
+# Some params are repeatable (multiple values per request) via the FastAPI `Query()` list pattern:
+# https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#query-parameter-list-multiple-values
+@query_router.get("/list")
+async def list_(  # trailing underscore: avoid shadowing the builtin `list` (used in annotations below).
+    library: BeetsLibraryDep,
+    albums: bool = False,
+    keyword: Annotated[list[str] | None, Query()] = None,
+    field: Annotated[list[str] | None, Query()] = None,
+    phrase: str | None = None,
+    filepath: Path | None = None,
+    sort_by: str | None = None,
+) -> list[dict[str, Any]]:
+    """Execute `beet list ...`: return matching tracks (or albums) as JSON objects.
+
+    Args:
+        library: injected beets library adapter.
+        albums: like `-a`; return albums instead of individual tracks.
+        keyword: repeatable bare-keyword query parts (substring match across default fields).
+        field: repeatable `field:value` parts (exact `=`, regex `::`, numeric/date ranges all supported).
+        phrase: a single multi-word phrase part.
+        filepath: a path within the beets library (becomes a path query).
+        sort_by: a beets sort token, e.g. `year+` or `artist-`.
+
+    See: https://beets.readthedocs.io/en/v2.12.0/reference/cli.html#list
+    """
+    query_parts: list[str] = []
+    if keyword:
+        query_parts.extend(keyword)
+    if field:
+        query_parts.extend(field)
+    if phrase:
+        query_parts.append(phrase)
+    if filepath:
+        query_parts.append(str(filepath))
+    if sort_by:
+        query_parts.append(sort_by)
+    return await library.query_albums(query_parts) if albums else await library.query_items(query_parts)
+
+
+@query_router.get("/stats")
+async def stats(library: BeetsLibraryDep) -> dict[str, Any]:
+    """Execute `beet stats`: track count, total time, approximate size, and artist/album counts.
+
+    See: https://beets.readthedocs.io/en/v2.12.0/reference/cli.html#stats
+    """
+    return await library.stats()
+
+
+@query_router.get("/fields")
+async def fields(library: BeetsLibraryDep) -> dict[str, list[str]]:
+    """Execute `beet fields`: the item/album query fields and flexible attributes available.
+
+    See: https://beets.readthedocs.io/en/v2.12.0/reference/cli.html#fields
+    """
+    return await library.fields()

beetkeeper/api/constants.py

@@ -0,0 +1,13 @@
+from pathlib import Path
+from typing import Final
+
+from starlette.templating import Jinja2Templates
+
+STATIC_DIRPATH: Final[Path] = Path(__file__).resolve().parent / "static"
+# TODO[Claude]: two things to resolve here:
+#   1. HTMX fragment rendering: this is a plain Starlette `Jinja2Templates`, but `jinja2-fragments` is a
+#      declared dependency. If routes need to return a single template block for an HTMX swap, switch to
+#      `jinja2_fragments.fastapi.Jinja2Blocks` (and standardize block usage). Decide and document.
+#   2. Templates live inside the publicly mounted `static/` tree, so raw `.html` template source is also reachable at
+#      `/static/html_templates/...`. If that exposure is unintended, relocate templates out of `static/`.
+TEMPLATES: Final[Jinja2Templates] = Jinja2Templates(directory=STATIC_DIRPATH / "html_templates")

beetkeeper/api/dependencies.py

@@ -0,0 +1,34 @@
+"""Shared FastAPI dependencies for the API + UI routers."""
+
+from typing import TYPE_CHECKING, Annotated, cast
+
+from fastapi import Depends, Request
+
+from beetkeeper.core import BeetsLibrary, ImportStore
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+    from beetkeeper.settings import UserConfig
+
+
+def get_beets_library(request: Request) -> BeetsLibrary:
+    """Return a `BeetsLibrary` adapter bound to the configured beets library (read from `UserConfig`)."""
+    user_config = cast("UserConfig", request.app.state.user_config)
+    return BeetsLibrary(user_config.beets_config_filepath)
+
+
+BeetsLibraryDep = Annotated[BeetsLibrary, Depends(get_beets_library)]
+
+
+def get_import_store(request: Request) -> ImportStore:
+    """Return a DB-backed `ImportStore` over the app's sessionmaker (created in the lifespan).
+
+    The store is the cross-process source of truth for import jobs, so route handlers use it (not the
+    per-process `ImportWorker`) to submit/poll/answer/abort — see `beetkeeper.api.fastapi_app`.
+    """
+    sessionmaker = cast("async_sessionmaker[AsyncSession]", request.app.state.db_sessionmaker)
+    return ImportStore(sessionmaker)
+
+
+ImportStoreDep = Annotated[ImportStore, Depends(get_import_store)]