fastsft 0.1.0__py3-none-any.whl

fastsft/__init__.py

@@ -0,0 +1,3 @@
+"""FastSFT: distill a large LLM into a small one via synthetic-data generation, quality filtering, and LoRA/QLoRA fine-tuning."""
+
+__version__ = "0.1.0"

fastsft/constants.py

@@ -0,0 +1,36 @@
+"""Constants used directly by the pipeline entry points (main.py, pipeline.py).
+
+Model-mechanics constants live in model/constants.py and data-generation
+tuning in data/constants.py.
+"""
+
+# Base directory holding `datasets/` and `modelsets/`. Overridable via the
+# OUTPUT_DIR_ENV_VAR env var or the --output-dir CLI flag, so an installed
+# fastsft can write outside the current directory (resolved by helper.py's
+# datasets_dir()/modelsets_dir()). Empty/unset means the current directory, so
+# running from the repo is unchanged.
+OUTPUT_DIR_ENV_VAR = "FASTSFT_OUTPUT_DIR"
+DEFAULT_OUTPUT_DIR = "datasets"
+RAW_OUTPUT_SUBDIR = "raw"
+FORMATTED_OUTPUT_SUBDIR = "formatted"
+MODELSETS_OUTPUT_DIR = "modelsets"
+# One evalsets/<run_id>/ folder per eval run: eval_prompts, eval_answers.json, eval_results.json.
+EVALSETS_OUTPUT_DIR = "evalsets"
+# Subfolder name for the eval prompt set within an evalsets run dir (see eval/prompt_set.py).
+EVAL_PROMPTS_SUBDIR = "eval_prompts"
+RUN_TIMESTAMP_FORMAT = "%Y%m%d_%H%M%S"
+
+# Sidecar (in a raw dataset run dir) recording the teacher that produced the
+# training data, so evaluation can reconstruct the true parent reference.
+TRAINING_METADATA_FILENAME = "training_metadata.json"
+
+DEFAULT_PARENT_MODEL = "meta-llama/llama-3.3-70b-instruct"
+
+# Different family from the parent, to avoid self-preference bias.
+DEFAULT_JUDGE_MODEL = "deepseek/deepseek-chat"
+
+# Must support tool calls (structured output).
+DEFAULT_GUIDE_MODEL = "qwen/qwen-2.5-7b-instruct"
+
+# Hugging Face repo id, not an OpenRouter model id.
+DEFAULT_CHILD_MODEL_ID = "Qwen/Qwen2.5-0.5B-Instruct"

fastsft/data/config.py

@@ -0,0 +1,34 @@
+"""Configuration for DataGenerator's generation-side models and tuning."""
+
+from dataclasses import dataclass, field
+
+from fastsft.constants import (
+    DEFAULT_GUIDE_MODEL,
+    DEFAULT_JUDGE_MODEL,
+    DEFAULT_PARENT_MODEL,
+)
+from fastsft.data.constants import (
+    BREADTH_EXPONENT,
+    DEFAULT_NUM_SAMPLES,
+    DEFAULT_PARENT_TEMPERATURE,
+)
+from fastsft.model.constants import DEFAULT_MAX_TOKENS, DEFAULT_SCORE_THRESHOLD
+
+
+@dataclass
+class ParentGenerationConfig:
+    """Tuning for the parent model's own generation calls."""
+
+    temperature: float = DEFAULT_PARENT_TEMPERATURE
+    max_tokens: int = DEFAULT_MAX_TOKENS
+
+
+@dataclass
+class DataGenerationConfig:
+    guide_model: str = DEFAULT_GUIDE_MODEL
+    parent_model: str = DEFAULT_PARENT_MODEL
+    judge_model: str = DEFAULT_JUDGE_MODEL
+    num_samples: int = DEFAULT_NUM_SAMPLES
+    breadth_exponent: float = BREADTH_EXPONENT
+    score_threshold: float = DEFAULT_SCORE_THRESHOLD
+    parent_generation: ParentGenerationConfig = field(default_factory=ParentGenerationConfig)

fastsft/data/constants.py

@@ -0,0 +1,33 @@
+"""Constants for the data package (synthetic-data generation and refinement)."""
+
+# Default dataset size when the caller doesn't specify.
+DEFAULT_NUM_SAMPLES = 100
+
+# Default sampling temperature for the parent model's generations -- high, to
+# keep the synthetic dataset varied. (The Model base class's own default is
+# separate; the model layer can't depend on data/ without inverting the layers.)
+DEFAULT_PARENT_TEMPERATURE = 0.9
+
+# Breadth (distinct seed topics) = ceil(N ** BREADTH_EXPONENT); >0.5 favors
+# breadth over depth (breadth:depth = N^exp : N^(1-exp)). Set high (0.85) to
+# actively favor topic diversity over per-topic complexity depth -- e.g. for
+# N=200: ~83 topics x ~2-3 complexity-varied instructions each.
+BREADTH_EXPONENT = 0.85
+
+# Extra guide-output budget per seed, so many-seed requests don't truncate.
+GUIDE_TOKENS_PER_SEED = 64
+
+# Max passes to top up under-delivered prompt generations to num_samples.
+MAX_PROMPT_ATTEMPTS = 5
+
+MAX_REFINE_ITERATIONS = 5
+
+# System prompt for the parent model when generating user instructions.
+PROMPT_GENERATOR_INSTRUCTION = (
+    "You generate user questions for a synthetic dataset. Given a seed question "
+    "and a requested count, produce that many DISTINCT user questions on the same "
+    "topic, spanning a range of complexity -- the simplest a plain question, the "
+    "most complex adding multiple constraints, sub-parts, or multi-step reasoning. "
+    "Each must be a natural, concrete question a real user would type. None may "
+    "mention answer style, persona, tone, or format."
+)

fastsft/data/prompt_generator.py

@@ -0,0 +1,97 @@
+"""Generates the dataset's user instructions directly via the parent model.
+
+Seeds provide breadth (distinct topics); each seed is expanded into depth
+(complexity-varied) instructions.
+"""
+
+import math
+
+from pydantic import BaseModel
+
+from fastsft.data.constants import (
+    BREADTH_EXPONENT,
+    MAX_PROMPT_ATTEMPTS,
+    PROMPT_GENERATOR_INSTRUCTION,
+)
+from fastsft.model.base import Model
+
+
+def seed_count(num_samples: int, breadth_exponent: float = BREADTH_EXPONENT) -> int:
+    """Breadth: number of distinct seed topics for `num_samples`
+    (ceil(N ** breadth_exponent), clamped to [1, num_samples])."""
+    # math.pow (not `**`) so the result types as float, not Any -- `**` on two
+    # numbers is typed Any in typeshed (a negative base + fractional exponent
+    # can return complex), which isn't a real concern for this always-positive
+    # breadth calculation.
+    return max(1, min(num_samples, math.ceil(math.pow(num_samples, breadth_exponent))))
+
+
+class GeneratedPrompts(BaseModel):
+    prompts: list[str]
+
+
+class PromptGenerator:
+    """Expands seed topics into exactly `num_samples` user instructions: each
+    seed is turned into its allotted number of questions spanning simple to
+    complex.
+    """
+
+    def __init__(self, model: Model, num_samples: int):
+        self._model = model
+        self._num_samples = num_samples
+
+    def generate(self, seeds: list[str]) -> list[str]:
+        """Returns exactly `num_samples` instructions spread across `seeds`."""
+        if not seeds:
+            raise ValueError("PromptGenerator.generate() requires at least one seed.")
+
+        # Each row is capped at its requested count, so a pass yields at most
+        # the deficit -- top up whatever a model under-delivers.
+        prompts: list[str] = []
+        for _ in range(MAX_PROMPT_ATTEMPTS):
+            deficit = self._num_samples - len(prompts)
+            if deficit == 0:
+                break
+            prompts.extend(self._generate(self._allocate(seeds, deficit)))
+        else:
+            raise RuntimeError(
+                f"PromptGenerator produced {len(prompts)}/{self._num_samples} "
+                f"instructions after {MAX_PROMPT_ATTEMPTS} attempts."
+            )
+        return prompts
+
+    def _generate(self, allocation: list[tuple[str, int]]) -> list[str]:
+        """Generates the capped prompts for one (seed, count) allocation."""
+        data = [
+            {"instruction": self._row_prompt(seed, count), "count": count}
+            for seed, count in allocation
+        ]
+        distiset = self._model.run_pipeline(
+            data,
+            PROMPT_GENERATOR_INSTRUCTION,
+            structured_output={"schema": GeneratedPrompts, "format": "json"},
+            name="prompt-generation",
+        )
+
+        prompts: list[str] = []
+        for row in distiset["default"]["train"]:
+            generation = self._model.assert_structured_output(row["generation"])
+            parsed = GeneratedPrompts.model_validate_json(generation)
+            prompts.extend(parsed.prompts[: row["count"]])
+        return prompts
+
+    def _allocate(self, seeds: list[str], n: int) -> list[tuple[str, int]]:
+        """Distributes `n` instructions as evenly as possible across `seeds`,
+        dropping any seed that would get zero."""
+        base, extra = divmod(n, len(seeds))
+        counts = (
+            (seed, base + (1 if i < extra else 0)) for i, seed in enumerate(seeds)
+        )
+        return [(seed, count) for seed, count in counts if count > 0]
+
+    def _row_prompt(self, seed: str, count: int) -> str:
+        return (
+            f"Seed question: {seed}\n\n"
+            f"Produce exactly {count} distinct user questions on this same topic, "
+            f"ordered from the simplest to the most complex."
+        )

fastsft/data/refiner.py

@@ -0,0 +1,72 @@
+"""Refines a Distiset by regenerating samples that fail the judge's quality bar."""
+
+
+from datasets import Dataset, concatenate_datasets
+from distilabel.distiset import Distiset
+
+from fastsft.data.constants import MAX_REFINE_ITERATIONS
+from fastsft.data.response_generator import ResponseGenerator
+from fastsft.helper import convert_to_distiset
+from fastsft.model.base import Model
+from fastsft.model.constants import DEFAULT_SCORE_THRESHOLD
+from fastsft.model.judge import Judge
+
+
+class DataRefiner:
+    """Re-answers low-scoring samples, keeping their instructions and the
+    count constant, up to MAX_REFINE_ITERATIONS times or until nothing fails.
+    """
+
+    def __init__(self, parent_model: Model, judge_model: Judge):
+        self._parent_model = parent_model
+        self._judge_model = judge_model
+
+    def refine(
+        self, distiset: Distiset, threshold: float = DEFAULT_SCORE_THRESHOLD
+    ) -> Distiset:
+        train = distiset["default"]["train"]
+
+        # Score the initial batch once; thereafter score only fresh rows.
+        scores = self._score(train)
+        for _ in range(MAX_REFINE_ITERATIONS):
+            if self._judge_model.failed_sample_count(scores, threshold=threshold) == 0:
+                break
+
+            failed_instructions = self._failed_instructions(train, scores, threshold)
+            train, scores = self._drop_failed(train, scores, threshold)
+            replacements = self._regenerate(failed_instructions)
+            train = concatenate_datasets([train, replacements])
+            scores = scores + self._score(replacements)
+
+        return convert_to_distiset(train)
+
+    def _score(self, train: Dataset) -> list[float]:
+        """Scores every row in `train`, returned aligned to row order."""
+        samples = {str(i): row["generation"] for i, row in enumerate(train)}
+        scores_by_id = self._judge_model.score_samples(samples)
+        return [scores_by_id[str(i)] for i in range(len(train))]
+
+    def _failed_instructions(
+        self, train: Dataset, scores: list[float], threshold: float
+    ) -> list[str]:
+        """Instructions of the rows scoring below `threshold`."""
+        return [
+            train[i]["instruction"]
+            for i in range(len(train))
+            if scores[i] < threshold
+        ]
+
+    def _drop_failed(
+        self, train: Dataset, scores: list[float], threshold: float
+    ) -> tuple[Dataset, list[float]]:
+        """Returns `train` and `scores` with every row scoring below
+        `threshold` removed, kept in alignment."""
+        keep_indices = [i for i in range(len(train)) if scores[i] >= threshold]
+        return train.select(keep_indices), [scores[i] for i in keep_indices]
+
+    def _regenerate(self, instructions: list[str]) -> Dataset:
+        """Generates fresh answers for `instructions`."""
+        replacements = ResponseGenerator(model=self._parent_model).generate(
+            instructions
+        )
+        return replacements["default"]["train"]

fastsft/data/response_generator.py

@@ -0,0 +1,21 @@
+"""Generates the assistant answers for a set of instructions."""
+
+
+from distilabel.distiset import Distiset
+
+from fastsft.model.base import Model
+
+
+class ResponseGenerator:
+    """Generates one styled answer per instruction via the parent model,
+    one API call per instruction (not the `n` param, which many providers ignore).
+    """
+
+    def __init__(self, model: Model | None = None):
+        self._model = model or Model()
+
+    def generate(self, instructions: list[str]) -> Distiset:
+        data = [{"instruction": instruction} for instruction in instructions]
+        return self._model.run_pipeline(
+            data, self._model.get_instruction(), name="response-generation"
+        )

fastsft/data/viewer.py

@@ -0,0 +1,93 @@
+"""View samples from a saved synthetic dataset in the terminal."""
+
+import fastsft.warnings_filter  # noqa: F401
+
+import argparse
+import os
+
+from rich.console import Console
+from rich.panel import Panel
+
+from fastsft.constants import (
+    DEFAULT_OUTPUT_DIR,
+    FORMATTED_OUTPUT_SUBDIR,
+    RAW_OUTPUT_SUBDIR,
+)
+from fastsft.helper import datasets_dir, latest_run_path, load_data
+
+console = Console()
+
+_ROLE_COLORS = {"user": "cyan", "assistant": "magenta"}
+
+
+def _format_message(message: dict) -> str:
+    role = message.get("role", "?")
+    color = _ROLE_COLORS.get(role, "white")
+    return f"[bold {color}]{role}[/bold {color}]: {message.get('content', '')}"
+
+
+class DataViewer:
+    """Loads a saved `Distiset` and previews samples."""
+
+    def __init__(self, path: str | None = None, kind: str = "raw"):
+        if path is None:
+            subdir = FORMATTED_OUTPUT_SUBDIR if kind == "formatted" else RAW_OUTPUT_SUBDIR
+            path = latest_run_path(os.path.join(datasets_dir(), subdir))
+        distiset = load_data(path)
+        assert distiset is not None, f"No dataset found at '{path}'."
+        self.dataset = distiset["default"]["train"]
+
+    def raw_samples(self, n: int = 5) -> None:
+        """Prints the first `n` raw samples' `messages` as generated."""
+        for i, row in enumerate(self.dataset.select(range(min(n, len(self.dataset))))):
+            messages = row.get("messages", [])
+            body = "\n\n".join(_format_message(m) for m in messages)
+            console.print(
+                Panel(
+                    body,
+                    title=f"[bold cyan][{i}][/bold cyan]",
+                    border_style="cyan",
+                    expand=False,
+                )
+            )
+
+    def formatted_samples(self, n: int = 5) -> None:
+        """Prints the first `n` samples' `text` column."""
+        for i, row in enumerate(self.dataset.select(range(min(n, len(self.dataset))))):
+            console.print(
+                Panel(
+                    row.get("text", ""),
+                    title=f"[bold cyan][{i}][/bold cyan]",
+                    border_style="cyan",
+                    expand=False,
+                )
+            )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Preview samples from a saved distilabel dataset.")
+    parser.add_argument(
+        "--input-path",
+        default=None,
+        help=f"Directory the dataset was saved to (default: latest run under "
+        f"{DEFAULT_OUTPUT_DIR}/{RAW_OUTPUT_SUBDIR}/ or {DEFAULT_OUTPUT_DIR}/"
+        f"{FORMATTED_OUTPUT_SUBDIR}/, depending on --formatted).",
+    )
+    parser.add_argument("--num-samples", type=int, default=5, help="Number of samples to display.")
+    parser.add_argument(
+        "--formatted",
+        action="store_true",
+        help="Show the DataFormatter-rendered 'text' column instead of raw 'messages'.",
+    )
+    args = parser.parse_args()
+
+    kind = "formatted" if args.formatted else "raw"
+    viewer = DataViewer(args.input_path, kind=kind)
+    if args.formatted:
+        viewer.formatted_samples(args.num_samples)
+    else:
+        viewer.raw_samples(args.num_samples)
+
+
+if __name__ == "__main__":
+    main()

fastsft/device.py

@@ -0,0 +1,53 @@
+"""Local torch runtime detection, shared by training (training/local_trainer.py,
+stages/fine_tuner.py) and evaluation (eval/inference.py): which accelerator this
+machine has, and the dtype to load models in on it.
+
+Torch is imported lazily inside each function, so this module stays importable
+without torch (it lives only in the local-training / evaluation optional extras).
+The `TYPE_CHECKING` import below is erased at runtime -- it exists only so
+`dtype_for_device`'s return type is real, not `Any`.
+
+Also runnable directly to report what this machine offers:
+
+    uv run python -m fastsft.device
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import torch
+
+
+def detect_device() -> str:
+    """Detect 'cuda', 'mps', or 'cpu' on this machine."""
+    import torch
+
+    if torch.cuda.is_available():
+        return "cuda"
+    if torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+def dtype_for_device(device: str) -> "torch.dtype":
+    """Return torch dtype for device: bf16 on accelerators (cuda/mps), fp32 on cpu."""
+    import torch
+
+    return torch.bfloat16 if device in ("cuda", "mps") else torch.float32
+
+
+def main() -> None:
+    """Report detected device, dtype, and torch version."""
+    device = detect_device()
+    print(f"Device: {device}")
+    print(f"Dtype:  {dtype_for_device(device)}")
+
+    import torch
+
+    print(f"Torch:  {torch.__version__}")
+    if device == "cuda":
+        print(f"GPU:    {torch.cuda.get_device_name(0)}")
+
+
+if __name__ == "__main__":
+    main()

fastsft/eval/__init__.py

@@ -0,0 +1,7 @@
+"""Extrinsic, judge-based evaluation of a fine-tuned child adapter.
+
+Standalone (not a DistillationPipeline stage): runs *after* training against a
+saved adapter, loading the parent (via OpenRouter), the tuned child, and the
+untuned child at once. Entry point: `python -m fastsft.eval.run [adapter_dir]`;
+view a finished run with `python -m fastsft.eval.results_viewer`.
+"""

fastsft/eval/config.py

@@ -0,0 +1,40 @@
+"""Configuration for the evaluation run: which adapter to score, which parent/
+judge models to score it against, and the eval-set/inference tuning knobs."""
+
+from dataclasses import dataclass
+
+from fastsft.constants import DEFAULT_JUDGE_MODEL, DEFAULT_PARENT_MODEL
+from fastsft.data.constants import DEFAULT_PARENT_TEMPERATURE
+from fastsft.eval.constants import (
+    DEFAULT_EMBEDDING_MODEL,
+    DEFAULT_INFERENCE_BATCH_SIZE,
+    DEFAULT_MAX_NEW_TOKENS,
+    DEFAULT_NUM_EVAL_PROMPTS,
+    DEFAULT_SWAP_POSITIONS,
+)
+from fastsft.model.constants import DEFAULT_MAX_TOKENS
+
+
+@dataclass
+class EvalConfig:
+    """A single evaluation run against one saved adapter directory."""
+
+    adapter_dir: str
+    # This eval run's own id (names its evalsets_dir()/<run_id> folder), distinct from adapter_dir's.
+    run_id: str
+    parent_model: str = DEFAULT_PARENT_MODEL
+    judge_model: str = DEFAULT_JUDGE_MODEL
+    embedding_model: str = DEFAULT_EMBEDDING_MODEL
+    num_eval_prompts: int = DEFAULT_NUM_EVAL_PROMPTS
+    max_new_tokens: int = DEFAULT_MAX_NEW_TOKENS
+    inference_batch_size: int = DEFAULT_INFERENCE_BATCH_SIZE
+    swap_positions: bool = DEFAULT_SWAP_POSITIONS
+    # The parent's style system prompt, inferred from the run's training metadata
+    # by default (eval/run.py) to reconstruct the styled teacher; "" means no
+    # system prompt (e.g. a bring-your-own dataset with no metadata).
+    parent_instruction: str = ""
+    # The parent's generation recipe, also inferred from training metadata so the
+    # reference answers like the actual teacher (same length/sampling the data was
+    # generated with). Falls back to the pipeline's training defaults.
+    parent_max_tokens: int = DEFAULT_MAX_TOKENS
+    parent_temperature: float = DEFAULT_PARENT_TEMPERATURE

fastsft/eval/constants.py

@@ -0,0 +1,53 @@
+"""Constants for the eval package (extrinsic judge-based evaluation)."""
+
+# Default size of the held-out eval prompt set. Smaller than a training run --
+# every prompt costs three generations (parent, tuned, untuned) plus judging.
+DEFAULT_NUM_EVAL_PROMPTS = 50
+
+# Local Hugging Face sentence-embedding model for parent-similarity scoring.
+# Small and CPU-friendly; runs via sentence-transformers (evaluation extra).
+DEFAULT_EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+# Child-inference generation budget (new tokens per answer) and how many
+# prompts to feed the model at once.
+DEFAULT_MAX_NEW_TOKENS = 512
+DEFAULT_INFERENCE_BATCH_SIZE = 8
+
+# Compare each pair twice with A/B swapped to cancel the judge's position bias.
+DEFAULT_SWAP_POSITIONS = True
+
+# Eval results live in evalsets_dir()/<run_id>/, one folder per eval/run.py invocation.
+EVAL_RESULTS_FILENAME = "eval_results.json"
+
+# Raw per-prompt answers, written right after generation so a judging failure doesn't lose them.
+EVAL_ANSWERS_FILENAME = "eval_answers.json"
+
+# Rubric (judge system prompt) for the pairwise quality comparison. Deliberately
+# generic -- it drives both tuned-vs-untuned and tuned-vs-parent comparisons.
+COMPARISON_JUDGE_INSTRUCTION = (
+    "You are comparing two AI assistant responses, A and B, to the same user "
+    "question. Decide which response is higher quality overall -- more helpful, "
+    "accurate, relevant, and clearly written. Judge only on quality: ignore the "
+    "order in which the responses are presented, and do not prefer a response "
+    "merely for being longer. Respond with a single verdict: \"A\" if A is "
+    "better, \"B\" if B is better, or \"tie\" if they are of genuinely equal "
+    "quality."
+)
+
+# Rubric for the parent-likeness comparison: which candidate answer is more like
+# the reference (parent) in STYLE -- tone, voice, structure, formatting,
+# verbosity -- regardless of which is more correct. This is the metric aligned
+# with the phase-0 distillation objective (voice/tone transfer) that the
+# generic-quality rubric above doesn't capture; it excludes correctness (the
+# quality metric's job) so the two stay orthogonal.
+STYLE_JUDGE_INSTRUCTION = (
+    "You are given a user question, a REFERENCE response, and two candidate "
+    "responses, A and B. Decide which candidate more closely matches the "
+    "REFERENCE's STYLE -- its tone, voice, structure, formatting, verbosity, "
+    "and overall approach -- regardless of which candidate is more correct, "
+    "helpful, or better written. You are judging stylistic resemblance to the "
+    "reference, not quality. Ignore the order in which the candidates are "
+    "presented. Respond with a single verdict: \"A\" if A is more like the "
+    "reference, \"B\" if B is more like the reference, or \"tie\" if they "
+    "resemble it equally."
+)

fastsft/eval/embeddings.py

@@ -0,0 +1,44 @@
+"""Local sentence embeddings for the distillation-fidelity metric: how close the
+child's answers sit to the parent's in embedding space.
+
+Uses sentence-transformers (evaluation extra); the model runs locally, so no
+embedding API or key is involved.
+"""
+
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any
+
+from fastsft.eval.constants import DEFAULT_EMBEDDING_MODEL
+
+if TYPE_CHECKING:
+    from sentence_transformers import SentenceTransformer
+
+
+@lru_cache(maxsize=2)
+def _load_model(model_id: str) -> "SentenceTransformer":
+    """Loads and caches a SentenceTransformer (heavy import kept local)."""
+    from sentence_transformers import SentenceTransformer
+
+    return SentenceTransformer(model_id)
+
+
+def embed(texts: list[str], model_id: str = DEFAULT_EMBEDDING_MODEL) -> Any:
+    """L2-normalized embeddings for `texts` (one row each)."""
+    return _load_model(model_id).encode(list(texts), normalize_embeddings=True)
+
+
+def pairwise_similarities(
+    a_texts: list[str], b_texts: list[str], model_id: str = DEFAULT_EMBEDDING_MODEL
+) -> list[float]:
+    """Cosine similarity of each aligned (a, b) pair. Embeddings are normalized,
+    so cosine is a row-wise dot product."""
+    if len(a_texts) != len(b_texts):
+        raise ValueError(
+            f"pairwise_similarities needs aligned lists, got {len(a_texts)} vs "
+            f"{len(b_texts)}."
+        )
+    if not a_texts:
+        return []
+    a = embed(a_texts, model_id)
+    b = embed(b_texts, model_id)
+    return [float(sim) for sim in (a * b).sum(axis=1)]