mlsort 0.1.0__py3-none-any.whl

mlsort/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import os
+
+from .api import sort, select_algorithm
+from .config import get_artifacts_dir, get_env_bool, get_seed
+from .installer import train_thresholds, save_thresholds, load_thresholds
+from .optimize import gen_cases, optimize_cutoffs
+
+__all__ = ["sort", "select_algorithm", "features", "algorithms", "baseline", "model"]
+
+
+def _maybe_init_on_import() -> None:
+    if not get_env_bool("MLSORT_INIT_ON_IMPORT", False):
+        return
+    thr_path = os.path.join(get_artifacts_dir(), "thresholds.json")
+    if os.path.exists(thr_path):
+        return
+    os.makedirs(os.path.dirname(thr_path) or ".", exist_ok=True)
+    seed = get_seed()
+    th = train_thresholds(num_samples=600, max_n=120_000, seed=seed, max_depth=3)
+    save_thresholds(thr_path, th)
+    arrays = gen_cases(num_samples=250, max_n=120_000, seed=seed + 7)
+    res = optimize_cutoffs(th, arrays)
+    th.cutoff_n = int(res["best"]["cutoff_n"])  # type: ignore[attr-defined]
+    th.activation_n = int(res["best"]["activation_n"])  # type: ignore[attr-defined]
+    save_thresholds(thr_path, th)
+
+
+_maybe_init_on_import()

mlsort/algorithms.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import math
+import time
+from typing import Any, Dict, List, Sequence, Tuple
+
+import numpy as np
+
+
+ALG_TIMSORT = "timsort"
+ALG_NP_QUICK = "np_quick"
+ALG_NP_MERGE = "np_merge"
+ALG_COUNTING = "counting"
+ALG_RADIX = "radix"
+
+ALL_ALGOS = [ALG_TIMSORT, ALG_NP_QUICK, ALG_NP_MERGE, ALG_COUNTING, ALG_RADIX]
+
+
+def _as_numpy(arr: Sequence[Any]) -> np.ndarray:
+    if isinstance(arr, np.ndarray):
+        return arr
+    return np.asarray(arr)
+
+
+def _as_list(arr: Sequence[Any]) -> List[Any]:
+    if isinstance(arr, list):
+        return list(arr)
+    return list(arr)
+
+
+def sort_timsort(arr: Sequence[Any]) -> List[Any]:
+    a = _as_list(arr)
+    a.sort()
+    return a
+
+
+def sort_np(arr: Sequence[Any], kind: str) -> np.ndarray:
+    a = _as_numpy(arr)
+    return np.sort(a, kind=kind)
+
+
+def sort_counting(arr: Sequence[int]) -> List[int]:
+    a = _as_numpy(arr)
+    if not np.issubdtype(a.dtype, np.integer):
+        raise TypeError("counting sort requires integer dtype")
+    if a.size == 0:
+        return []
+    amin = int(a.min())
+    amax = int(a.max())
+    rng = amax - amin + 1
+    # Safety cap: avoid huge memory
+    if rng > 1_000_000:
+        raise ValueError("range too large for counting sort")
+    counts = np.zeros(rng, dtype=np.int64)
+    # Shift values to zero-based
+    shifted = (a - amin).astype(np.int64)
+    for v in shifted:
+        counts[v] += 1
+    # Build output
+    out = np.empty_like(shifted)
+    total = 0
+    for i in range(rng):
+        c = int(counts[i])
+        if c:
+            out[total: total + c] = i
+            total += c
+    # Shift back
+    out = (out + amin).astype(a.dtype, copy=False)
+    return out.tolist()
+
+
+def sort_radix_lsd(arr: Sequence[int], base: int = 256) -> List[int]:
+    a = _as_numpy(arr)
+    if not np.issubdtype(a.dtype, np.integer):
+        raise TypeError("radix sort requires integer dtype")
+    if a.size == 0:
+        return []
+    # Use 32-bit buckets for speed; bias signed to unsigned
+    dtype = a.dtype
+    bits = np.iinfo(dtype).bits
+    bias = 1 << (bits - 1)
+    u = (a.astype(np.int64) + bias).astype(np.uint64)
+    out = u.copy()
+    mask = base - 1
+    shift = 0
+    tmp = np.empty_like(out)
+    while shift < bits:
+        counts = np.zeros(base, dtype=np.int64)
+        # Count
+        for v in out:
+            counts[(v >> shift) & mask] += 1
+        # Prefix sums
+        total = 0
+        for i in range(base):
+            c = counts[i]
+            counts[i] = total
+            total += c
+        # Reorder
+        for v in out:
+            b = (v >> shift) & mask
+            tmp[counts[b]] = v
+            counts[b] += 1
+        out, tmp = tmp, out
+        shift += int(math.log2(base))
+    # Un-bias
+    res = (out.astype(np.int64) - bias).astype(dtype, copy=False)
+    return res.tolist()
+
+
+def available_algorithms_for(arr: Sequence[Any]) -> List[str]:
+    a = _as_numpy(arr)
+    algos = [ALG_TIMSORT, ALG_NP_QUICK, ALG_NP_MERGE]
+    if np.issubdtype(a.dtype, np.integer):
+        # counting only if range manageable
+        if a.size > 0:
+            amin = int(a.min())
+            amax = int(a.max())
+            rng = amax - amin + 1
+            if rng <= 100_000 and rng <= 8 * a.size:
+                algos.append(ALG_COUNTING)
+        algos.append(ALG_RADIX)
+    return algos
+
+
+def time_algorithm(arr: Sequence[Any], algo: str, repeats: int = 1) -> float:
+    start = time.perf_counter
+    best = float("inf")
+    for _ in range(repeats):
+        t0 = start()
+        if algo == ALG_TIMSORT:
+            sort_timsort(arr)
+        elif algo == ALG_NP_QUICK:
+            sort_np(arr, kind="quicksort")
+        elif algo == ALG_NP_MERGE:
+            sort_np(arr, kind="mergesort")
+        elif algo == ALG_COUNTING:
+            sort_counting(arr)
+        elif algo == ALG_RADIX:
+            sort_radix_lsd(arr)
+        else:
+            raise ValueError(f"unknown algo {algo}")
+        best = min(best, start() - t0)
+    return best
+
+
+def measure_best_algorithm(arr: Sequence[Any], repeats: int = 1):
+    algos = available_algorithms_for(arr)
+    times: Dict[str, float] = {}
+    for algo in algos:
+        try:
+            t = time_algorithm(arr, algo, repeats=repeats)
+            times[algo] = t
+        except Exception:
+            # skip invalid
+            continue
+    if not times:
+        # fallback
+        return ALG_TIMSORT, {ALG_TIMSORT: float("inf")}
+    best_algo = min(times.items(), key=lambda kv: kv[1])[0]
+    return best_algo, times

mlsort/api.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, Iterable, List, Sequence, Tuple
+
+import numpy as np
+
+from .config import get_artifacts_dir, get_env_bool, get_seed
+from .decision import decide
+from .installer import load_thresholds, train_thresholds, save_thresholds, Thresholds
+from .optimize import gen_cases, optimize_cutoffs
+from .algorithms import (
+    ALG_TIMSORT, ALG_NP_QUICK, ALG_NP_MERGE, ALG_COUNTING, ALG_RADIX,
+    sort_timsort, sort_np, sort_counting, sort_radix_lsd, available_algorithms_for
+)
+
+
+log = logging.getLogger("mlsort")
+
+
+def _ensure_thresholds(path: str) -> Thresholds:
+    # Lazy init: controlled by env flags
+    if os.path.exists(path):
+        return load_thresholds(path)
+    if not get_env_bool("MLSORT_ENABLE_INSTALL_BENCH", False):
+        # Safe default if benchmarks disabled
+        th = Thresholds(cutoff_n=1024, activation_n=98304, tree={"leaf": True, "label": ALG_NP_QUICK}, feature_names=[
+            "n","dtype_code","est_sortedness","est_dup_ratio","est_range","est_entropy","est_run_len"
+        ])
+        os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+        save_thresholds(path, th)
+        return th
+    # Run small-budget train+optimize
+    seed = get_seed()
+    th = train_thresholds(num_samples=600, max_n=120_000, seed=seed, max_depth=3)
+    save_thresholds(path, th)
+    arrays = gen_cases(num_samples=250, max_n=120_000, seed=seed + 7)
+    res = optimize_cutoffs(th, arrays)
+    th.cutoff_n = int(res["best"]["cutoff_n"])  # type: ignore[attr-defined]
+    th.activation_n = int(res["best"]["activation_n"])  # type: ignore[attr-defined]
+    save_thresholds(path, th)
+    return th
+
+
+def select_algorithm(arr: Sequence[Any], thresholds_path: str | None = None, *, key: Any = None, reverse: bool = False) -> str:
+    # Input validation
+    try:
+        n = len(arr)  # type: ignore[arg-type]
+    except Exception:
+        raise TypeError("arr must be a sequence with __len__ and indexable by int")
+    if n == 0:
+        return ALG_TIMSORT
+    # If a key function is provided, prefer builtin Timsort for correctness and stability
+    if key is not None:
+        return ALG_TIMSORT
+    # If data are strings or mixed/object types, default to Python's Timsort
+    try:
+        if isinstance(arr, np.ndarray):
+            if arr.dtype.kind in {"O", "U", "S"}:
+                return ALG_TIMSORT
+        else:
+            # Sample a subset to determine type categories
+            sample_count = min(n, 256)
+            idxs = range(sample_count)
+            cats = set()
+            for i in idxs:
+                v = arr[i]
+                if isinstance(v, str) or isinstance(v, bytes):
+                    cats.add("string")
+                elif isinstance(v, (int, float, np.integer, np.floating)):
+                    cats.add("number")
+                elif v is None:
+                    cats.add("other")
+                else:
+                    # Unknown/object type
+                    cats.add("other")
+                if len(cats) > 1:
+                    break
+            if "string" in cats:
+                return ALG_TIMSORT
+            if len(cats) > 1 or (cats and next(iter(cats)) == "other"):
+                return ALG_TIMSORT
+    except Exception:
+        # On any detection error, prefer safe fallback
+        return ALG_TIMSORT
+    # Ensure thresholds
+    thr_path = thresholds_path or os.path.join(get_artifacts_dir(), "thresholds.json")
+    os.makedirs(os.path.dirname(thr_path) or ".", exist_ok=True)
+    th = _ensure_thresholds(thr_path)
+    algo = decide(arr, th)
+    if get_env_bool("MLSORT_DEBUG", False):
+        log.debug("mlsort.select algo=%s n=%d path=%s", algo, n, thr_path)
+    return algo
+
+
+def sort(
+    arr: Sequence[Any],
+    thresholds_path: str | None = None,
+    *,
+    key: Any = None,
+    reverse: bool = False,
+) -> List[Any]:
+    # Always safe fallback path
+    try:
+        algo = select_algorithm(arr, thresholds_path, key=key, reverse=reverse)
+    except Exception as e:  # strict safety: fallback
+        if get_env_bool("MLSORT_DEBUG", False):
+            log.debug("mlsort.select failed: %s; falling back to timsort", e)
+        algo = ALG_TIMSORT
+
+    # Execute with correct key/reverse handling
+    if algo == ALG_TIMSORT:
+        a = list(arr)
+        a.sort(key=key, reverse=reverse)
+        return a
+
+    # For non-Timsort backends, key is unsupported (would have forced Timsort above)
+    if algo == ALG_NP_QUICK:
+        res = sort_np(arr, kind="quicksort").tolist()
+        return res[::-1] if reverse else res
+    if algo == ALG_NP_MERGE:
+        res = sort_np(arr, kind="mergesort").tolist()
+        return res[::-1] if reverse else res
+    if algo == ALG_COUNTING:
+        try:
+            res = sort_counting(arr)
+            return res[::-1] if reverse else res
+        except Exception:
+            res = sort_np(arr, kind="quicksort").tolist()
+            return res[::-1] if reverse else res
+    if algo == ALG_RADIX:
+        try:
+            res = sort_radix_lsd(arr)
+            return res[::-1] if reverse else res
+        except Exception:
+            res = sort_np(arr, kind="quicksort").tolist()
+            return res[::-1] if reverse else res
+
+    # Last resort: builtin
+    a = list(arr)
+    a.sort(key=key, reverse=reverse)
+    return a
+
+
+def profile_decisions(samples: int = 100, max_n: int = 200_000, thresholds_path: str | None = None) -> Dict[str, Any]:
+    import time
+    from .algorithms import time_algorithm
+    thr_path = thresholds_path or os.path.join(get_artifacts_dir(), "thresholds.json")
+    th = _ensure_thresholds(thr_path)
+    arrays = gen_cases(samples, max_n, seed=get_seed()+99)
+    rows = []
+    for arr in arrays:
+        t0 = time.perf_counter()
+        algo = decide(arr, th)
+        t1 = time.perf_counter()
+        t_sort = time_algorithm(arr, algo, repeats=1)
+        rows.append({"n": len(arr), "algo": algo, "decision_ms": (t1-t0)*1000.0, "sort_s": t_sort})
+    return {"count": len(rows), "rows": rows[:50]}

mlsort/baseline.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Dict
+
+from .algorithms import ALG_COUNTING, ALG_NP_MERGE, ALG_NP_QUICK, ALG_RADIX, ALG_TIMSORT
+
+
+def heuristic_baseline(props: Dict[str, float]) -> str:
+    n = props["n"]
+    dtype = int(props["dtype_code"])  # 0 float, 1 int
+    sortedness = props["est_sortedness"]
+    dup_ratio = props["est_dup_ratio"]
+    rng = props["est_range"]
+    entropy = props["est_entropy"]
+    run_len = props["est_run_len"]
+
+    # If almost sorted or long runs, Timsort shines
+    if sortedness >= 0.9 or run_len >= 32:
+        return ALG_TIMSORT
+
+    if dtype == 1:
+        # Counting sort when range relatively small and many duplicates
+        if rng > 0 and rng <= max(1024.0, 8.0 * n) and dup_ratio >= 0.3 and entropy <= 0.7:
+            return ALG_COUNTING
+        # Radix for wide range ints with moderate entropy
+        if n >= 512 and entropy <= 0.9:
+            return ALG_RADIX
+
+    # For general cases prefer NumPy quicksort for speed, merge for stability/some patterns
+    if n >= 2000:
+        return ALG_NP_QUICK
+    else:
+        return ALG_NP_MERGE

mlsort/benchmark.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+import os
+import statistics
+import time
+from typing import Dict, List
+
+import numpy as np
+
+from .algorithms import (
+    ALG_NP_MERGE,
+    ALG_NP_QUICK,
+    ALG_TIMSORT,
+    time_algorithm,
+)
+from .decision import decide
+from .installer import load_thresholds, train_thresholds, save_thresholds
+from .data import (
+    gen_sorted, gen_reverse, gen_nearly_sorted, gen_uniform, gen_small_range, gen_zipf, gen_normal,
+)
+
+
+Naive = [ALG_TIMSORT, ALG_NP_QUICK, ALG_NP_MERGE]
+
+
+def ensure_thresholds(path: str, samples: int, max_n: int, seed: int) -> str:
+    if os.path.exists(path):
+        return path
+    th = train_thresholds(num_samples=samples, max_n=max_n, seed=seed, max_depth=3)
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    save_thresholds(path, th)
+    return path
+
+
+def _random_case(rng: np.random.Generator, max_n: int):
+    n = int(rng.integers(128, max_n + 1))
+    gens = [
+        lambda n: gen_sorted(n, "int"),
+        lambda n: gen_reverse(n, "int"),
+        lambda n: gen_nearly_sorted(n, dtype="int"),
+        lambda n: gen_uniform(n, "int", 0, 10_000),
+        lambda n: gen_uniform(n, "float"),
+        lambda n: gen_small_range(n, 128),
+        lambda n: gen_zipf(n, a=2.0, dtype="int", max_val=50_000),
+        lambda n: gen_normal(n, dtype="float"),
+    ]
+    g = gens[int(rng.integers(0, len(gens)))]
+    arr = g(n)
+    return arr
+
+
+def run_benchmark(num_samples: int, max_n: int, seed: int, thresholds_path: str) -> Dict:
+    ensure_thresholds(thresholds_path, samples=max(600, num_samples // 2), max_n=max_n, seed=seed)
+    th = load_thresholds(thresholds_path)
+
+    rng = np.random.default_rng(seed + 101)
+
+    times_decision: List[float] = []
+    times_naive: Dict[str, List[float]] = {k: [] for k in Naive}
+    per_case: List[Dict] = []
+
+    for _ in range(num_samples):
+        arr = _random_case(rng, max_n)
+
+        t0 = time.perf_counter()
+        algo = decide(arr, th)
+        t1 = time.perf_counter()
+        t_sort = time_algorithm(arr, algo, repeats=1)
+        t_decision_total = (t1 - t0) + t_sort
+        times_decision.append(t_decision_total)
+
+        for k in Naive:
+            t = time_algorithm(arr, k, repeats=1)
+            times_naive[k].append(t)
+
+        per_case.append({
+            "n": int(len(arr)),
+            "decision_algo": algo,
+            "decision_total_time": t_decision_total,
+            **{f"time_{k}": times_naive[k][-1] for k in Naive},
+        })
+
+    def stats(vals: List[float]):
+        vals_sorted = sorted(vals)
+        p50 = vals_sorted[len(vals_sorted)//2]
+        p90 = vals_sorted[int(len(vals_sorted)*0.9)-1]
+        return {
+            "mean": float(statistics.fmean(vals)),
+            "median": float(p50),
+            "p90": float(p90),
+        }
+
+    agg = {"decision": stats(times_decision)}
+    for k in Naive:
+        agg[k] = stats(times_naive[k])
+
+    mean_naive = {k: agg[k]["mean"] for k in Naive}
+    best_naive_key = min(mean_naive.items(), key=lambda kv: kv[1])[0]
+    best_naive_mean = mean_naive[best_naive_key]
+    speedup_vs_best = best_naive_mean / agg["decision"]["mean"] if agg["decision"]["mean"] > 0 else 1.0
+
+    win_rates = {}
+    for k in Naive:
+        wins = sum(1 for i in range(num_samples) if times_decision[i] <= times_naive[k][i])
+        win_rates[k] = wins / num_samples
+
+    return {
+        "samples": num_samples,
+        "max_n": max_n,
+        "seed": seed,
+        "thresholds": thresholds_path,
+        "aggregate": agg,
+        "best_naive": {"key": best_naive_key, "mean_time": best_naive_mean},
+        "speedup_vs_best_naive": speedup_vs_best,
+        "win_rates": win_rates,
+        "cases_head": per_case[:50],
+    }

mlsort/cli_bench_compare.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+from mlsort.benchmark import run_benchmark
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Benchmark decision policy vs naive baselines")
+    parser.add_argument("--samples", type=int, default=600)
+    parser.add_argument("--max-n", type=int, default=20000)
+    parser.add_argument("--seed", type=int, default=123)
+    parser.add_argument("--thresholds", type=str, default=os.path.join(os.path.expanduser("~"), ".cache", "mlsort", "thresholds.json"))
+    parser.add_argument("--out-json", type=str, default="bench_compare.json")
+    parser.add_argument("--out-md", type=str, default="report.md")
+    args = parser.parse_args()
+
+    results = run_benchmark(args.samples, args.max_n, args.seed, args.thresholds)
+
+    with open(args.out_json, "w") as f:
+        json.dump(results, f, indent=2)
+
+    md = []
+    md.append("# mlsort: Decision Policy vs. Naive Single-Choice\n\n")
+    md.append(f"- Samples: {results['samples']}  \n- Max n: {results['max_n']}  \n- Seed: {results['seed']}  \n- Thresholds: {results['thresholds']}\n\n")
+    md.append("## Mean/Median/P90 (seconds)\n")
+    md.append(f"- Decision mean: {results['aggregate']['decision']['mean']:.6f}\n")
+    for k, v in results['aggregate'].items():
+        if k == 'decision':
+            continue
+        md.append(f"- {k} mean: {v['mean']:.6f}\n")
+    md.append(f"\nBest naive: {results['best_naive']['key']} at {results['best_naive']['mean_time']:.6f} s\n")
+    md.append(f"Speedup vs best naive: {results['speedup_vs_best_naive']:.3f}x\n")
+
+    with open(args.out_md, "w") as f:
+        f.write("".join(md))
+
+    print(f"Wrote {args.out_json} and {args.out_md}")  # noqa: T201
+
+
+if __name__ == "__main__":
+    main()

mlsort/cli_bench_install.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import argparse
+import os
+
+from mlsort.installer import train_thresholds, save_thresholds
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Benchmark and derive thresholds for mlsort")
+    parser.add_argument("--samples", type=int, default=1200)
+    parser.add_argument("--max-n", type=int, default=20000)
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--max-depth", type=int, default=3)
+    parser.add_argument("--out", type=str, default=os.path.join(os.path.expanduser("~"), ".cache", "mlsort", "thresholds.json"))
+    args = parser.parse_args()
+
+    os.makedirs(os.path.dirname(args.out), exist_ok=True)
+    th = train_thresholds(num_samples=args.samples, max_n=args.max_n, seed=args.seed, max_depth=args.max_depth)
+    save_thresholds(args.out, th)
+    print(f"Saved thresholds to {args.out}")  # noqa: T201
+
+
+if __name__ == "__main__":
+    main()

mlsort/cli_init.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import argparse
+import os
+
+from mlsort.config import get_artifacts_dir, get_seed
+from mlsort.installer import train_thresholds, save_thresholds, load_thresholds
+from mlsort.optimize import gen_cases, optimize_cutoffs
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Initialize mlsort artifacts; optional params have defaults")
+    parser.add_argument("--samples", type=int, default=1200, help="training samples")
+    parser.add_argument("--max-n", type=int, default=200000, help="max array size in benchmarking")
+    parser.add_argument("--seed", type=int, default=None, help="random seed; default from MLSORT_SEED or 42")
+    parser.add_argument("--artifacts", type=str, default=None, help="artifacts dir; default MLSORT_ARTIFACTS_DIR or OS cache")
+    args = parser.parse_args()
+
+    seed = args.seed if args.seed is not None else get_seed()
+    artifacts = args.artifacts or get_artifacts_dir()
+    thr_path = os.path.join(artifacts, "thresholds.json")
+    os.makedirs(artifacts, exist_ok=True)
+
+    th = train_thresholds(num_samples=args.samples, max_n=args.max_n, seed=seed, max_depth=3)
+    save_thresholds(thr_path, th)
+
+    arrays = gen_cases(num_samples=min(300, args.samples), max_n=args.max_n, seed=seed + 17)
+    res = optimize_cutoffs(load_thresholds(thr_path), arrays)
+    th_best = load_thresholds(thr_path)
+    th_best.cutoff_n = int(res["best"]["cutoff_n"])  # type: ignore[attr-defined]
+    th_best.activation_n = int(res["best"]["activation_n"])  # type: ignore[attr-defined]
+    save_thresholds(thr_path, th_best)
+
+    print({"artifacts": artifacts, "thresholds": thr_path, "best": res["best"]})  # noqa: T201
+
+
+if __name__ == "__main__":
+    main()

mlsort/cli_optimize_cutoffs.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import argparse
+import os
+
+from mlsort.config import get_artifacts_dir, get_seed
+from mlsort.installer import load_thresholds, save_thresholds
+from mlsort.optimize import gen_cases, optimize_cutoffs
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Optimize cutoff and activation thresholds")
+    parser.add_argument("--samples", type=int, default=350)
+    parser.add_argument("--max-n", type=int, default=100000)
+    parser.add_argument("--seed", type=int, default=None)
+    parser.add_argument("--thresholds", type=str, default=None)
+    args = parser.parse_args()
+
+    seed = args.seed if args.seed is not None else get_seed()
+    thr_path = args.thresholds or os.path.join(get_artifacts_dir(), "thresholds.json")
+    th = load_thresholds(thr_path)
+
+    arrays = gen_cases(args.samples, args.max_n, seed=seed + 10)
+    res = optimize_cutoffs(th, arrays)
+
+    th.cutoff_n = int(res["best"]["cutoff_n"])  # type: ignore[attr-defined]
+    th.activation_n = int(res["best"]["activation_n"])  # type: ignore[attr-defined]
+    save_thresholds(thr_path, th)
+
+    print({"best": res["best"], "thresholds": thr_path})  # noqa: T201
+
+
+if __name__ == "__main__":
+    main()

mlsort/config.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+
+def get_cache_root() -> str:
+    # macOS: ~/Library/Caches
+    # Linux: XDG_CACHE_HOME or ~/.cache
+    # Windows: LOCALAPPDATA
+    if sys.platform == "darwin":
+        return os.path.expanduser("~/Library/Caches")
+    if os.name == "nt":
+        return os.environ.get("LOCALAPPDATA", os.path.expanduser("~\\AppData\\Local"))
+    return os.environ.get("XDG_CACHE_HOME", os.path.expanduser("~/.cache"))
+
+
+def get_artifacts_dir() -> str:
+    return os.environ.get("MLSORT_ARTIFACTS_DIR", os.path.join(get_cache_root(), "mlsort"))
+
+
+def get_env_bool(name: str, default: bool = False) -> bool:
+    v = os.environ.get(name)
+    if v is None:
+        return default
+    return v.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def get_seed(default: int = 42) -> int:
+    try:
+        return int(os.environ.get("MLSORT_SEED", str(default)))
+    except Exception:
+        return default
+