robotframework-testselection 0.1.0__py3-none-any.whl

TestSelection/pipeline/select.py

@@ -0,0 +1,183 @@
+"""Stage 2 orchestrator: load artifacts, filter, select, and output."""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import numpy as np
+
+from TestSelection.pipeline.artifacts import ArtifactManager
+from TestSelection.pipeline.errors import SelectionError
+from TestSelection.selection.filtering import filter_by_tags
+from TestSelection.selection.registry import default_registry
+from TestSelection.selection.strategy import (
+    DiversityMetrics,
+    SelectedTest,
+    SelectionResult,
+    TagFilter,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def run_select(
+    artifact_dir: Path,
+    k: int,
+    strategy: str = "fps",
+    output_file: Path | None = None,
+    include_tags: list[str] | None = None,
+    exclude_tags: list[str] | None = None,
+    seed: int = 42,
+    include_datadriver: bool = True,
+) -> SelectionResult:
+    """Run the selection stage.
+
+    Returns SelectionResult. Raises SelectionError on failure.
+    """
+    try:
+        manager = ArtifactManager(artifact_dir)
+
+        # Validate artifacts
+        valid, message = manager.validate_artifacts()
+        if not valid:
+            raise SelectionError(f"Artifact validation failed: {message}")
+
+        manifest = manager.load_manifest()
+        vectors = manager.load_vectors()
+
+        logger.info(
+            "[DIVERSE-SELECT] stage=select event=artifacts_loaded "
+            "tests=%d dim=%d",
+            manifest.test_count,
+            manifest.embedding_dim,
+        )
+
+        # Build tag filter
+        tag_filter = TagFilter(
+            include_tags=frozenset(
+                t.lower() for t in (include_tags or [])
+            ),
+            exclude_tags=frozenset(
+                t.lower() for t in (exclude_tags or [])
+            ),
+            include_datadriver=include_datadriver,
+        )
+
+        # Filter entries
+        filtered_indices = filter_by_tags(manifest.tests, tag_filter)
+        filtered_count = len(filtered_indices)
+
+        if filtered_count == 0:
+            raise SelectionError(
+                "No tests remain after tag filtering"
+            )
+
+        filtered_vectors = vectors[filtered_indices]
+        actual_k = min(k, filtered_count)
+
+        logger.info(
+            "[DIVERSE-SELECT] stage=select event=filter_complete "
+            "total=%d filtered=%d k=%d",
+            manifest.test_count,
+            filtered_count,
+            actual_k,
+        )
+
+        # Get strategy and run selection
+        algo = default_registry.get(strategy)
+        selected_indices = algo.select(filtered_vectors, actual_k, seed=seed)
+
+        # Map back to manifest entries
+        selected_entries = []
+        for idx in selected_indices:
+            original_idx = filtered_indices[idx]
+            entry = manifest.tests[original_idx]
+            selected_entries.append(
+                SelectedTest(
+                    name=entry.name,
+                    id=entry.id,
+                    suite=entry.suite,
+                    is_datadriver=entry.is_datadriver,
+                )
+            )
+
+        # Compute diversity metrics
+        selected_vectors = filtered_vectors[selected_indices]
+        metrics = _compute_diversity_metrics(
+            selected_vectors, selected_entries, manifest
+        )
+
+        result = SelectionResult(
+            strategy=strategy,
+            k=actual_k,
+            seed=seed,
+            total_tests=manifest.test_count,
+            filtered_tests=filtered_count,
+            selected=tuple(selected_entries),
+            diversity_metrics=metrics,
+        )
+
+        # Write output
+        out_path = output_file or manager.selection_path
+        result.to_json(out_path)
+
+        logger.info(
+            "[DIVERSE-SELECT] stage=select event=complete "
+            "strategy=%s k=%d avg_dist=%.4f min_dist=%.4f "
+            "suite_coverage=%d/%d",
+            strategy,
+            actual_k,
+            metrics.avg_pairwise_distance,
+            metrics.min_pairwise_distance,
+            metrics.suite_coverage,
+            metrics.suite_total,
+        )
+
+        return result
+
+    except SelectionError:
+        raise
+    except KeyError as exc:
+        logger.warning(
+            "[DIVERSE-SELECT] stage=select event=error error=%s",
+            str(exc),
+        )
+        raise SelectionError(str(exc)) from exc
+    except Exception as exc:
+        logger.warning(
+            "[DIVERSE-SELECT] stage=select event=error error=%s",
+            str(exc),
+        )
+        raise SelectionError(str(exc)) from exc
+
+
+def _compute_diversity_metrics(
+    selected_vectors: np.ndarray,
+    selected_entries: list[SelectedTest],
+    manifest,
+) -> DiversityMetrics:
+    """Compute pairwise cosine distance metrics for selected tests."""
+    from sklearn.metrics.pairwise import cosine_distances
+
+    n = selected_vectors.shape[0]
+    if n < 2:
+        return DiversityMetrics(
+            avg_pairwise_distance=0.0,
+            min_pairwise_distance=0.0,
+            suite_coverage=len({e.suite for e in selected_entries}),
+            suite_total=len({e.suite for e in manifest.tests}),
+        )
+
+    pairwise = cosine_distances(selected_vectors, selected_vectors)
+    mask = np.triu(np.ones_like(pairwise, dtype=bool), k=1)
+    upper_dists = pairwise[mask]
+
+    all_suites = {e.suite for e in manifest.tests}
+    selected_suites = {e.suite for e in selected_entries}
+
+    return DiversityMetrics(
+        avg_pairwise_distance=float(np.mean(upper_dists)),
+        min_pairwise_distance=float(np.min(upper_dists)),
+        suite_coverage=len(selected_suites),
+        suite_total=len(all_suites),
+    )

TestSelection/pipeline/vectorize.py

@@ -0,0 +1,190 @@
+"""Stage 1 orchestrator: parse, embed, and store test vectors."""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from TestSelection.pipeline.artifacts import ArtifactManager
+from TestSelection.pipeline.cache import CacheInvalidator
+from TestSelection.pipeline.errors import VectorizationError
+
+logger = logging.getLogger(__name__)
+
+
+def run_vectorize(
+    suite_path: Path,
+    artifact_dir: Path,
+    model_name: str = "all-MiniLM-L6-v2",
+    resolve_depth: int = 0,
+    force: bool = False,
+    datadriver_csvs: list[Path] | None = None,
+) -> bool:
+    """Run the vectorization stage.
+
+    Returns True if indexing was performed, False if skipped (cache hit).
+    Raises VectorizationError on failure.
+    """
+    try:
+        manager = ArtifactManager(artifact_dir)
+        cache = CacheInvalidator(manager.hash_store_path)
+
+        if (
+            not force
+            and not cache.has_changes(suite_path)
+            and manager.has_embedding_artifacts()
+        ):
+            logger.info(
+                "[DIVERSE-SELECT] stage=vectorize event=skipped "
+                "reason=no_changes"
+            )
+            return False
+
+        # Parse suite
+        from TestSelection.parsing.suite_collector import RobotApiAdapter
+
+        adapter = RobotApiAdapter()
+        raw_tests, kw_map = adapter.parse_suite(suite_path)
+        logger.info(
+            "[DIVERSE-SELECT] stage=vectorize event=parse_complete "
+            "tests_found=%d",
+            len(raw_tests),
+        )
+
+        # Build text representations
+        from TestSelection.parsing.keyword_resolver import (
+            KeywordTreeResolver,
+        )
+        from TestSelection.parsing.text_builder import (
+            TextRepresentationBuilder,
+        )
+        from TestSelection.shared.config import TextBuilderConfig
+        from TestSelection.shared.types import (
+            SuitePath,
+            Tag,
+            TestCaseId,
+            TestCaseRecord,
+        )
+
+        resolver = KeywordTreeResolver(kw_map)
+        config = TextBuilderConfig(resolve_depth=resolve_depth)
+        builder = TextRepresentationBuilder(resolver, config)
+
+        records: list[TestCaseRecord] = []
+        for test_dict in raw_tests:
+            tags = frozenset(Tag(value=t) for t in test_dict.get("tags", []))
+            text_rep = builder.build(
+                test_name=test_dict["name"],
+                tags=tags,
+                body_items=test_dict.get("body", []),
+            )
+            test_id = TestCaseId.from_source_and_name(
+                test_dict["source"], test_dict["name"]
+            )
+            records.append(
+                TestCaseRecord(
+                    test_id=test_id,
+                    name=test_dict["name"],
+                    tags=tags,
+                    suite_source=SuitePath(Path(test_dict["source"])),
+                    suite_name=test_dict.get("suite_name", ""),
+                    text_representation=text_rep,
+                )
+            )
+
+        # Handle DataDriver CSVs
+        if datadriver_csvs:
+            from TestSelection.parsing.datadriver_reader import (
+                read_datadriver_csv,
+            )
+            from TestSelection.shared.types import TextRepresentation
+
+            for csv_path in datadriver_csvs:
+                dd_tests = read_datadriver_csv(csv_path, template_name="Template")
+                for dd in dd_tests:
+                    test_id = TestCaseId.from_source_and_name(
+                        dd["source"], dd["name"]
+                    )
+                    records.append(
+                        TestCaseRecord(
+                            test_id=test_id,
+                            name=dd["name"],
+                            tags=frozenset(),
+                            suite_source=SuitePath(Path(dd["source"])),
+                            suite_name="DataDriver",
+                            text_representation=TextRepresentation(
+                                text=dd["description"]
+                            ),
+                            is_datadriver=True,
+                        )
+                    )
+
+        if not records:
+            raise VectorizationError("No test cases found to vectorize")
+
+        # Encode via embedding model
+        try:
+            from TestSelection.embedding.embedder import (
+                SentenceTransformerAdapter,
+            )
+        except ImportError as exc:
+            raise VectorizationError(
+                "sentence-transformers is required for vectorization. "
+                "Install with: pip install testcase-selection[vectorize]"
+            ) from exc
+
+        model = SentenceTransformerAdapter(model_name)
+        texts = [r.text_representation.text for r in records]
+        vectors = model.encode(texts)
+
+        logger.info(
+            "[DIVERSE-SELECT] stage=vectorize event=embed_complete "
+            "model=%s dim=%d tests=%d",
+            model.model_name,
+            model.embedding_dim,
+            len(texts),
+        )
+
+        # Build EmbeddingMatrix and save artifacts
+        from TestSelection.embedding.models import (
+            EmbeddingMatrix,
+            ManifestEntry,
+        )
+
+        test_ids = tuple(r.test_id.value for r in records)
+        matrix = EmbeddingMatrix(
+            model_name=model.model_name,
+            embedding_dim=model.embedding_dim,
+            vectors=vectors,
+            test_ids=test_ids,
+        )
+
+        manifest_entries = tuple(
+            ManifestEntry(
+                id=r.test_id.value,
+                name=r.name,
+                tags=tuple(t.value for t in r.tags),
+                suite=str(r.suite_source.value),
+                suite_name=r.suite_name,
+                is_datadriver=r.is_datadriver,
+            )
+            for r in records
+        )
+
+        matrix.to_artifact(artifact_dir, manifest_entries, resolve_depth)
+        cache.save_hashes(suite_path)
+
+        logger.info(
+            "[DIVERSE-SELECT] stage=vectorize event=complete "
+            "tests_indexed=%d",
+            len(records),
+        )
+        return True
+
+    except VectorizationError:
+        raise
+    except Exception as exc:
+        logger.warning(
+            "[DIVERSE-SELECT] stage=vectorize event=error error=%s",
+            str(exc),
+        )
+        raise VectorizationError(str(exc)) from exc

TestSelection/selection/__init__.py

@@ -0,0 +1,25 @@
+"""Selection bounded context: diversity-based test subset selection algorithms."""
+
+from TestSelection.selection.filtering import filter_by_tags
+from TestSelection.selection.fps import FarthestPointSampling, FPSMultiStart
+from TestSelection.selection.registry import StrategyRegistry, default_registry
+from TestSelection.selection.strategy import (
+    DiversityMetrics,
+    SelectedTest,
+    SelectionResult,
+    SelectionStrategy,
+    TagFilter,
+)
+
+__all__ = [
+    "DiversityMetrics",
+    "FPSMultiStart",
+    "FarthestPointSampling",
+    "SelectedTest",
+    "SelectionResult",
+    "SelectionStrategy",
+    "StrategyRegistry",
+    "TagFilter",
+    "default_registry",
+    "filter_by_tags",
+]

TestSelection/selection/dpp.py

@@ -0,0 +1,31 @@
+"""Determinantal Point Process selection strategy (requires dppy)."""
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class DPPSelection:
+    """Determinantal Point Process for probabilistic diverse sampling.
+
+    Produces genuinely random diverse subsets.
+    Useful for nightly CI runs that collectively cover more ground.
+    Requires: pip install dppy
+    """
+
+    name = "dpp"
+
+    def select(
+        self, vectors: NDArray[np.float32], k: int, seed: int = 42
+    ) -> list[int]:
+        from dppy.finite_dpps import FiniteDPP
+        from sklearn.preprocessing import normalize
+
+        rng = np.random.RandomState(seed)
+        np.random.seed(rng.randint(2**31))
+        x_norm = normalize(vectors, norm="l2")
+        kernel = x_norm @ x_norm.T
+        kernel = (kernel + kernel.T) / 2
+        dpp = FiniteDPP("likelihood", **{"L": kernel})
+        dpp.sample_exact_k_dpp(size=k)
+        return list(dpp.list_of_samples[-1])

TestSelection/selection/facility.py

@@ -0,0 +1,25 @@
+"""Facility location selection strategy (requires apricot-select)."""
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class FacilityLocationSelection:
+    """Submodular facility location for representative selection.
+
+    (1-1/e) ~ 0.632 approximation guarantee.
+    Ensures no cluster goes unrepresented.
+    Requires: pip install apricot-select
+    """
+
+    name = "facility"
+
+    def select(
+        self, vectors: NDArray[np.float32], k: int, seed: int = 42
+    ) -> list[int]:
+        from apricot import FacilityLocationSelection as ApricotFL
+
+        selector = ApricotFL(k, metric="cosine", verbose=False)
+        selector.fit(vectors)
+        return list(selector.ranking)

TestSelection/selection/filtering.py

@@ -0,0 +1,21 @@
+"""Tag-based filtering for test manifest entries."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from TestSelection.selection.strategy import TagFilter
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def filter_by_tags(
+    manifest_entries: Sequence[Any],
+    tag_filter: TagFilter,
+) -> list[int]:
+    """Return indices of manifest entries that match the tag filter."""
+    return [
+        i
+        for i, entry in enumerate(manifest_entries)
+        if tag_filter.matches(frozenset(entry.tags), entry.is_datadriver)
+    ]

TestSelection/selection/fps.py

@@ -0,0 +1,67 @@
+"""Farthest Point Sampling selection strategies."""
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class FarthestPointSampling:
+    """Greedy farthest-first traversal for maximum dispersion.
+
+    2-approximation guarantee for max-min dispersion (Gonzalez, 1985).
+    Time: O(N * k * d). Deterministic given seed.
+    """
+
+    name = "fps"
+
+    def select(
+        self, vectors: NDArray[np.float32], k: int, seed: int = 42
+    ) -> list[int]:
+        from sklearn.metrics.pairwise import cosine_distances
+
+        n = vectors.shape[0]
+        k = min(k, n)
+        rng = np.random.RandomState(seed)
+        initial = rng.randint(n)
+        selected = [initial]
+        min_distances = cosine_distances(vectors[initial : initial + 1], vectors)[0]
+        min_distances[initial] = -np.inf
+        for _ in range(k - 1):
+            next_idx = int(np.argmax(min_distances))
+            selected.append(next_idx)
+            new_dists = cosine_distances(vectors[next_idx : next_idx + 1], vectors)[0]
+            min_distances = np.minimum(min_distances, new_dists)
+            min_distances[next_idx] = -np.inf
+        return selected
+
+
+class FPSMultiStart:
+    """FPS from multiple starting points, keeps best result.
+
+    'Best' = maximizes minimum pairwise distance in selected set.
+    Mitigates initial-point sensitivity.
+    """
+
+    name = "fps_multi"
+
+    def __init__(self, n_starts: int = 5) -> None:
+        self._n_starts = n_starts
+
+    def select(
+        self, vectors: NDArray[np.float32], k: int, seed: int = 42
+    ) -> list[int]:
+        from sklearn.metrics.pairwise import cosine_distances
+
+        fps = FarthestPointSampling()
+        best_selected: list[int] | None = None
+        best_min_dist = -1.0
+        for i in range(self._n_starts):
+            selected = fps.select(vectors, k, seed=seed + i)
+            sel_vectors = vectors[selected]
+            pairwise = cosine_distances(sel_vectors, sel_vectors)
+            np.fill_diagonal(pairwise, np.inf)
+            min_dist = float(pairwise.min())
+            if min_dist > best_min_dist:
+                best_min_dist = min_dist
+                best_selected = selected
+        return best_selected  # type: ignore[return-value]

TestSelection/selection/kmedoids.py

@@ -0,0 +1,32 @@
+"""k-Medoids selection strategy (requires sklearn-extra)."""
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class KMedoidsSelection:
+    """Cluster representatives via k-medoids (PAM algorithm).
+
+    Optimizes representativeness, not dispersion.
+    Each medoid is a real data point.
+    Requires: pip install scikit-learn-extra
+    """
+
+    name = "kmedoids"
+
+    def select(
+        self, vectors: NDArray[np.float32], k: int, seed: int = 42
+    ) -> list[int]:
+        from sklearn_extra.cluster import KMedoids
+
+        kmed = KMedoids(
+            n_clusters=k,
+            metric="cosine",
+            method="pam",
+            init="k-medoids++",
+            random_state=seed,
+            max_iter=300,
+        )
+        kmed.fit(vectors)
+        return list(kmed.medoid_indices_)

TestSelection/selection/registry.py

@@ -0,0 +1,70 @@
+"""Strategy registry for selection algorithms."""
+from __future__ import annotations
+
+from typing import Any
+
+from TestSelection.selection.fps import FarthestPointSampling, FPSMultiStart
+from TestSelection.selection.strategy import SelectionStrategy
+
+
+class StrategyRegistry:
+    """Registry mapping strategy names to their implementation classes."""
+
+    def __init__(self) -> None:
+        self._strategies: dict[str, Any] = {}
+
+    def register(self, strategy_class: Any) -> None:
+        """Register a strategy class by its name attribute."""
+        self._strategies[strategy_class.name] = strategy_class
+
+    def get(self, name: str) -> SelectionStrategy:
+        """Instantiate and return a strategy by name."""
+        if name not in self._strategies:
+            available = ", ".join(sorted(self._strategies))
+            msg = (
+                f"Unknown strategy {name!r}. "
+                f"Available: {available}"
+            )
+            raise KeyError(msg)
+        return self._strategies[name]()
+
+    def available(self) -> list[str]:
+        """Return names of all registered strategies."""
+        return sorted(self._strategies)
+
+    def is_available(self, name: str) -> bool:
+        """Check if a strategy is registered."""
+        return name in self._strategies
+
+
+def _build_default_registry() -> StrategyRegistry:
+    """Build the default registry with core + optional strategies."""
+    registry = StrategyRegistry()
+    registry.register(FarthestPointSampling)
+    registry.register(FPSMultiStart)
+
+    try:
+        from TestSelection.selection.kmedoids import KMedoidsSelection
+
+        registry.register(KMedoidsSelection)
+    except ImportError:
+        pass
+
+    try:
+        from TestSelection.selection.dpp import DPPSelection
+
+        registry.register(DPPSelection)
+    except ImportError:
+        pass
+
+    try:
+        from TestSelection.selection.facility import FacilityLocationSelection
+
+        registry.register(FacilityLocationSelection)
+    except ImportError:
+        pass
+
+    return registry
+
+
+default_registry = _build_default_registry()