refactor: Drop distillation task; allow per Task.distill() only. (#173)

* refactor: Drop distillation task; allow per `Task.distill()` only.

* refactor: Drop `train_frac` in distill().

* fix: Remove `train_frac` specs.

---------

Co-authored-by: Raphael Mitsch <[email protected]>

Author: rmitsch

AGENTS.md

@@ -42,7 +42,7 @@ Key packages and concepts: `sieves.data.Doc`, `sieves.pipeline.Pipeline`, `sieve
 
 ## Environments & Installation
 
-Supported Python: `>=3.10` (tests and typing target 3.11).
+Supported Python: `>=3.12`.
 
 Using `uv` (preferred):
 - Base: `uv sync`
@@ -92,7 +92,7 @@ Notes for agents:
 - Type checking: mypy strict (`[tool.mypy]` in `pyproject.toml`)
 - Linting: ruff (E, F, I, UP), isort via ruff
 - Formatting: black (line length 120)
-- Python target version: 3.10 for style/format; 3.11 for mypy config
+- Python target version: 3.12
 - Avoid one‑letter variable names; keep changes minimal and focused
 
 ## Development Commands

sieves/engines/engine_import.py

@@ -1,5 +1,7 @@
-"""
-Imports 3rd-party libraries required for engines. If library can't be found, placeholder engines is imported instead.
+"""Import 3rd-party libraries required for engines.
+
+If library can't be found, placeholder engines is imported instead.
+
 This allows us to import everything downstream without having to worry about optional dependencies. If a user specifies
 an engine/model from a non-installed library, we terminate with an error.
 """
@@ -93,8 +95,8 @@
     _missing_dependencies.append("vllm")
 
 warnings.warn(
-    "Warning: engine dependencies [{deps}] could not be imported. The corresponding engines won't work "
-    "unless this dependency has been installed.".format(deps=", ".join(_missing_dependencies))
+    "Warning: structured generation dependencies [{deps}] could not be imported. Generating with them requires them to"
+    " be installed.".format(deps=", ".join(_missing_dependencies))
 )
 
 

sieves/pipeline/core.py

@@ -4,7 +4,6 @@
 
 import copy
 import itertools
-import typing
 from collections.abc import Iterable, Iterator, Sized
 from pathlib import Path
 from typing import Any
@@ -13,7 +12,7 @@
 
 from sieves.data import Doc
 from sieves.serialization import Attribute, Config, Serializable
-from sieves.tasks import Distillation, PredictiveTask, Task
+from sieves.tasks import Task
 
 
 class Pipeline:
@@ -36,7 +35,6 @@ def __init__(
         self._cache: dict[int, Doc] = {}
         self._cache_stats: dict[str, int] = {"total": 0, "unique": 0, "hits": 0, "misses": 0}
         self._validate_tasks()
-        self._set_distillation_targets()
 
     def add_tasks(self, tasks: Iterable[Task]) -> None:
         """Add tasks to pipeline. Revalidates pipeline.
@@ -45,7 +43,6 @@ def add_tasks(self, tasks: Iterable[Task]) -> None:
         """
         self._tasks.extend(tasks)
         self._validate_tasks()
-        self._set_distillation_targets()
 
     @property
     def tasks(self) -> list[Task]:
@@ -75,17 +72,6 @@ def _validate_tasks(self) -> None:
                 raise ValueError(f"Task with duplicate ID {task.id}. Ensure unique task IDs.")
             task_ids.add(task.id)
 
-    def _set_distillation_targets(self) -> None:
-        """Set target task references fpr distillation tasks, if there are any.
-
-        This is necessary because distillation tasks have a lazily initialized required attribute.
-        """
-        for task in self._tasks:
-            if isinstance(task, Distillation):
-                target_task = self[task.target_task_id]
-                assert issubclass(type(target_task), PredictiveTask)
-                task.target_task = typing.cast(PredictiveTask, target_task)  # type: ignore[type-arg]
-
     def _get_unseen_unique_docs(self, docs: Iterable[Doc]) -> Iterable[Doc]:
         """Yield unseen, unique docs.
 
@@ -273,5 +259,5 @@ def __iadd__(self, other: Task | Pipeline) -> Pipeline:
         else:
             raise TypeError(f"Can only add Task or Pipeline to Pipeline with +=, got {type(other).__name__}")
         self._validate_tasks()
-        self._set_distillation_targets()
+
         return self

sieves/tasks/__init__.py

@@ -2,7 +2,7 @@
 
 from . import predictive, preprocessing
 from .core import Task
-from .postprocessing import Distillation, DistillationFramework
+from .postprocessing import DistillationFramework
 from .predictive import (
     NER,
     Classification,
@@ -19,7 +19,6 @@
 __all__ = [
     "Chunking",
     "Classification",
-    "Distillation",
     "DistillationFramework",
     "NER",
     "InformationExtraction",

sieves/tasks/postprocessing/__init__.py

@@ -1,3 +1,5 @@
-from .distillation import Distillation, DistillationFramework
+"""Postprocessing tasks."""
 
-__all__ = ["Distillation", "DistillationFramework"]
+from .distillation import DistillationFramework
+
+__all__ = ["DistillationFramework"]

sieves/tasks/postprocessing/distillation/__init__.py

@@ -1,4 +1,5 @@
-from .core import Distillation
+"""Distillation."""
+
 from .types import DistillationFramework, DistillationFrameworkLiteral
 
-__all__ = ["Distillation", "DistillationFramework", "DistillationFrameworkLiteral"]
+__all__ = ["DistillationFramework", "DistillationFrameworkLiteral"]

sieves/tasks/postprocessing/distillation/core.py

@@ -1,6 +1,7 @@
-"""
-Imports 3rd-party libraries required for distillation. If library can't be found, placeholder engines is imported
-instead.
+"""Import 3rd-party libraries required for distillation.
+
+If library can't be found, placeholder engines is imported instead.
+
 This allows us to import everything downstream without having to worry about optional dependencies. If a user specifies
 a non-installed distillation framework, we terminate with an error.
 """
@@ -9,34 +10,34 @@
 
 import warnings
 
-_MISSING_WARNING = (
-    "Warning: engine dependency `{missing_dependency}` could not be imported. The corresponding engines won't work "
-    "unless this dependency has been installed."
-)
+_missing_dependencies: list[str] = []
 
 
 try:
     import sentence_transformers
 except ModuleNotFoundError:
     sentence_transformers = None
 
-    warnings.warn(_MISSING_WARNING.format(missing_dependency="sentence_transformers"))
-
+    _missing_dependencies.append("sentence_transformers")
 
 try:
     import setfit
 except ModuleNotFoundError:
     setfit = None
 
-    warnings.warn(_MISSING_WARNING.format(missing_dependency="setfit"))
+    _missing_dependencies.append("setfit")
 
 try:
     import model2vec
     import model2vec.train
 except ModuleNotFoundError:
     model2vec = None
 
-    warnings.warn(_MISSING_WARNING.format(missing_dependency="model2vec"))
+    _missing_dependencies.append("model2vec")
 
+warnings.warn(
+    "Warning: distillation dependency [{deps}] could not be imported. Distilling with these tools requires them to "
+    "be installed.".format(deps=", ".join(_missing_dependencies))
+)
 
 __all__ = ["model2vec", "sentence_transformers", "setfit"]