Add stylometry package

.coveragerc

@@ -0,0 +1,3 @@
+[run]
+omit =
+    */plotting.py

.github/workflows/tests.yaml

@@ -0,0 +1,39 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Create venv
+        run: uv venv
+
+      - name: Install dependencies
+        run: uv pip install -e .[dev]
+
+      - name: Run tests (push)
+        if: github.event_name == 'push'
+        run: uv run pytest
+
+      - name: Run tests + coverage gate (PR into main)
+        if: github.event_name == 'pull_request' && github.base_ref == 'main'
+        run: uv run pytest --cov=voice --cov-report=term-missing --cov-fail-under=90

.gitignore

@@ -52,3 +52,6 @@ htmlcov/
 # Local configs
 .env
 *.local
+
+# Notebooks
+**.ipynb

.pre-commit-config.yaml

@@ -58,25 +58,31 @@ repos:
     hooks:
       - id: isort
 
-  # Type checking
+  # Type checking (keep for src; exclude tests)
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.13.0
     hooks:
       - id: mypy
         args: ["--config-file", "pyproject.toml"]
+        exclude: ^tests/
 
-  # Docstring correctness (sphinx convention)
+  # Docstring correctness (sphinx convention) (keep for src; exclude tests)
   - repo: https://github.com/jsh9/pydoclint
     rev: 0.7.6
     hooks:
       - id: pydoclint
         args: ["--config=pyproject.toml"]
+        exclude: ^tests/
 
-  # Cognitive complexity limit via flake8-cognitive-complexity
+  # Cognitive complexity limit via flake8-cognitive-complexity (keep for src; exclude tests)
   - repo: https://github.com/pycqa/flake8
     rev: 7.3.0
     hooks:
       - id: flake8
         additional_dependencies:
           - flake8-cognitive-complexity
-        args: ["--max-cognitive-complexity=10"]
+        args:
+          - --max-line-length=79
+          - --extend-ignore=E203
+          - --max-cognitive-complexity=10
+        exclude: ^tests/

cspell.json

@@ -28,6 +28,7 @@
     "cspell/**",
     "LICENSE",
     ".secrets.baseline",
-    "*.egg-info/"
+    "*.egg-info/",
+    "**/*.ipynb"
   ]
 }

cspell/library-words.txt

@@ -0,0 +1,10 @@
+huggingface
+resp
+passthrough
+figsize
+whitegrid
+kdeplot
+xlabel
+ylabel
+frameon
+allclose

cspell/project-words.txt

@@ -0,0 +1,13 @@
+hapax
+dis
+tri
+legomenon
+legomena
+MATTR
+TTR
+ngram
+prov
+wasserstein
+bonf
+bonferroni
+aeiou

pyproject.toml

@@ -4,7 +4,14 @@ version = "0.1.0"
 description = "Fine-tuning for stylistic fidelity"
 readme = "README.md"
 requires-python = ">=3.12"
-dependencies = []
+dependencies = [
+    "datasets>=4.5.0",
+    "dotenv>=0.9.9",
+    "huggingface-hub>=1.4.1",
+    "matplotlib>=3.10.8",
+    "scipy>=1.17.0",
+    "seaborn>=0.13.2",
+]
 
 [build-system]
 requires = ["setuptools>=68", "wheel"]
@@ -20,15 +27,19 @@ dev = [
     "flake8-cognitive-complexity>=0.1.0",
     "isort>=7.0.0",
     "mypy>=1.19.1",
+    "notebook>=7.5.3",
     "pre-commit>=4.5.1",
     "pydoclint>=0.8.3",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
     "ruff>=0.14.14",
 ]
 
 [tool.ruff]
-line-length = 88
+line-length = 79
 target-version = "py312"
 force-exclude = true
+extend-ignore = ["D107"]
 
 [tool.ruff.lint]
 select = [
@@ -49,25 +60,53 @@ select = [
   "C901",
 ]
 
-ignore = [
-  "ANN101", "ANN102",
-]
+ignore = []
 
 [tool.ruff.lint.mccabe]
 max-complexity = 12
 
 [tool.ruff.lint.pydocstyle]
 convention = "pep257"
 
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "D",
+    "ANN",
+    "ARG001",
+    "ARG005",
+    "B007",
+]
+
 [tool.mypy]
 python_version = "3.12"
 strict = true
 warn_unused_configs = true
 no_implicit_optional = true
 
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = [
+    "datasets",
+    "datasets.*",
+    "huggingface_hub",
+    "huggingface_hub.*",
+    "numpy",
+    "numpy.*",
+    "scipy.stats",
+    "scipy.stats.*",
+    "seaborn",
+    "seaborn.*",
+    "matplotlib",
+    "matplotlib.*",
+]
+ignore_missing_imports = true
+
 [tool.isort]
 profile = "black"
-line_length = 88
+line_length = 79
 
 [tool.pydoclint]
 style = "sphinx"

src/voice/__init__.py

@@ -4,3 +4,13 @@
 This package provides tools for fine-tuning and evaluating
 LLMs for stylistic fidelity.
 """
+
+from voice.datasets import DatasetSpec, get_dataset
+from voice.stylometry import get_metrics, make_comparison
+
+__all__: list[str] = [
+    "DatasetSpec",
+    "get_metrics",
+    "get_dataset",
+    "make_comparison",
+]

src/voice/datasets/__init__.py

@@ -0,0 +1,15 @@
+"""
+Datasets package for VOICE.
+
+This package contains user-facing abstractions for dataset management,
+in particular we expose:
+
+- `DatasetSpec` - Lightweight, declarative specification of a dataset.
+- `VoiceDataset` - Split-aware wrapper around a Hugging Face dataset.
+- `get_dataset` - Entrypoint for materialising a dataset from a specification.
+"""
+
+from voice.datasets.dataset import DatasetSpec, VoiceDataset
+from voice.datasets.get_dataset import get_dataset
+
+__all__: list[str] = ["DatasetSpec", "VoiceDataset", "get_dataset"]

src/voice/datasets/_schema.py

@@ -0,0 +1,67 @@
+"""
+Dataset schema primitives.
+
+This module defines lightweight schema-level abstractions shared across
+the dataset loading pipeline.
+
+This module is private by convention and not part of the public API.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Split(str, Enum):
+    """
+    Enumeration of supported dataset splits.
+
+    .. attribute :: TRAIN
+
+        Name of the training split
+
+    .. attribute :: VALIDATION
+
+        Name of the validation split
+
+    .. attribute :: TEST
+
+        Name of the test split
+    """
+
+    TRAIN = "train"
+    VALIDATION = "validation"
+    TEST = "test"
+
+    def __repr__(self) -> str:
+        """
+        Return the split as a string.
+
+        :return: Readable string of the split
+        """
+        return f"'{self.value}'"
+
+    @classmethod
+    def parse(cls, value: Split | str) -> Split:
+        """
+        Parse a split value from a string or Split instance.
+
+        :param value: Split name or Split enum value
+        :return: Parsed Split enum value
+        :raises TypeError: If the value is not a Split or string
+        :raises ValueError: If the value does not correspond to a valid split
+        """
+        if isinstance(value, cls):
+            return value
+        if not isinstance(value, str):
+            raise TypeError(
+                f"`split` must be a Split or str, got {type(value).__name__}"
+            )
+        v = value.strip().lower()
+        try:
+            return cls(v)
+        except ValueError as e:
+            allowed = ", ".join(s.value for s in cls)
+            raise ValueError(
+                f"Invalid split {value!r}. Allowed: {allowed}"
+            ) from e

src/voice/datasets/_specs.py

@@ -0,0 +1,16 @@
+"""
+Pre-defined dataset specifications for testing.
+
+All specifications are of type `voice.datasets.DatasetSpec`.
+
+This module is private by convention and not part of the public API.
+"""
+
+from voice.datasets import DatasetSpec
+from voice.datasets._schema import Split
+
+BUSH_LATEST = DatasetSpec(
+    repo_id="AccelerateScience/bush-dataset",
+    revision="main",
+    splits=(Split.TRAIN, Split.VALIDATION, Split.TEST),
+)