docs: add missing module-level docstrings

builders/server/core/api/routes.py

@@ -1,3 +1,5 @@
+"""HTTP endpoint handlers for the public and authenticated routers."""
+
 from datetime import datetime
 
 import structlog

builders/server/core/calendars/definitions/always_open.py

@@ -1,3 +1,5 @@
+"""AlwaysOpenCalendar: accepts any timestamp regardless of date or time."""
+
 from datetime import datetime, timedelta
 
 from core.calendars.interface import Calendar

builders/server/core/calendars/definitions/everyday.py

@@ -1,3 +1,5 @@
+"""EverydayCalendar ('everyday'): accepts every day; the default calendar."""
+
 from datetime import datetime, timedelta
 
 from core.calendars.interface import Calendar

builders/server/core/calendars/definitions/nyse_daily.py

@@ -1,3 +1,5 @@
+"""NyseDailyCalendar: registered as 'nyse-daily', accepts NYSE trading days only."""
+
 from datetime import datetime, timedelta
 
 import exchange_calendars as xcals

builders/server/core/calendars/definitions/weekday.py

@@ -1,3 +1,5 @@
+"""WeekdayCalendar: registered as 'weekday', accepts Monday through Friday only."""
+
 from datetime import datetime, timedelta
 
 from core.calendars.interface import Calendar

builders/server/core/calendars/interface.py

@@ -1,3 +1,5 @@
+"""The Calendar ABC defining which timestamps are valid for a dataset."""
+
 from abc import ABC, abstractmethod
 from datetime import datetime, timedelta
 

builders/server/core/calendars/registry.py

@@ -1,3 +1,5 @@
+"""CALENDARS_MAP: registry mapping calendar name to Calendar instance."""
+
 from core.calendars.definitions.always_open import AlwaysOpenCalendar
 from core.calendars.definitions.everyday import EverydayCalendar
 from core.calendars.definitions.nyse_daily import NyseDailyCalendar

builders/server/core/calendars/utils.py

@@ -1,3 +1,5 @@
+"""Shared helpers for calendar implementations."""
+
 from datetime import datetime
 
 

builders/server/core/db/connection.py

@@ -1,3 +1,5 @@
+"""Postgres connection pool lifecycle and per-request connection access."""
+
 import structlog
 from psycopg_pool import ConnectionPool
 

builders/server/core/db/datasets.py

@@ -1,3 +1,5 @@
+"""SQL queries for the datasets table: existence, reads, and bulk insert."""
+
 from collections import defaultdict
 from datetime import datetime
 

builders/server/core/runtime/config.py

@@ -1,3 +1,5 @@
+"""Parses and validates config.toml into DatasetConfig; owns SCRIPTS_DIR resolution."""
+
 import os
 import re
 from dataclasses import dataclass

builders/server/core/runtime/loader.py

@@ -1,3 +1,5 @@
+"""Dynamically imports a builder module from its script directory."""
+
 import importlib.util
 import sys
 from collections.abc import Callable

builders/server/core/runtime/registry.py

@@ -1,3 +1,5 @@
+"""Startup config preload + in-memory registry; validates the dependency graph."""
+
 import tomllib
 from collections.abc import Generator
 from pathlib import Path

builders/server/core/runtime/runner.py

@@ -1,3 +1,5 @@
+"""Runs a builder in an isolated subprocess with retry, using its venv if present."""
+
 import subprocess
 import sys
 import time

builders/server/core/runtime/validator.py

@@ -1,3 +1,5 @@
+"""Validates builder output rows against the dataset's [schema] declaration."""
+
 from core.runtime.config import SchemaType
 
 

builders/server/core/service/builder.py

@@ -1,3 +1,5 @@
+"""Public build API: build_dataset() and get_data(); selects the store."""
+
 from dataclasses import dataclass
 from datetime import datetime
 

builders/server/core/service/catalog.py

@@ -1,3 +1,5 @@
+"""list_datasets(): registered datasets annotated with DB data presence."""
+
 from dataclasses import dataclass
 
 import core.db.datasets

builders/server/core/service/locks.py

@@ -1,3 +1,5 @@
+"""Per-dataset build lock registry serializing concurrent builds of the same dataset."""
+
 import threading
 
 _lock_map: dict[tuple[str, str], threading.Lock] = {}

builders/server/core/service/models.py

@@ -1,3 +1,5 @@
+"""Build data types: JobDescriptor, JobResult, and BuildPlan."""
+
 from dataclasses import dataclass
 from datetime import datetime
 

builders/server/core/utils/retry.py

@@ -1,3 +1,5 @@
+"""Generic retry-with-exponential-backoff helper used to wrap flaky operations."""
+
 import time
 from collections.abc import Callable
 

builders/server/core/utils/semver.py

@@ -1,3 +1,5 @@
+"""SemVer parsing and comparison (strict major.minor.patch, no leading zeros)."""
+
 import re
 from dataclasses import dataclass
 

builders/server/main.py

@@ -1,3 +1,5 @@
+"""FastAPI entrypoint: builds the app, mounts routers, runs the lifespan."""
+
 import os
 import uuid
 from collections.abc import AsyncIterator