mlsort 0.1.0__tar.gz

mlsort-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Siddharth Chaudhary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlsort-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: mlsort
+Version: 0.1.0
+Summary: ML-guided sorting backend selector with install-time benchmarking
+Author: Siddharth Chaudhary
+License: MIT License
+        
+        Copyright (c) 2025 Siddharth Chaudhary
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/sidcoding/mlsort
+Project-URL: Repository, https://github.com/sidcoding/mlsort
+Project-URL: Issues, https://github.com/sidcoding/mlsort/issues
+Keywords: sorting,machine-learning,numpy,performance,benchmark,timsort,radix,counting-sort,decision-tree
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Benchmark
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.10
+Requires-Dist: joblib>=1.3
+Dynamic: license-file
+
+# mlsort
+
+ML-guided sorting backend selector. Chooses between Python Timsort, NumPy sorts, and integer-only counting/radix based on cheap, sampled properties of your data. Defaults are safe; selection only activates for large arrays.
+
+## Install
+
+```bash
+pip install mlsort
+```
+
+Optionally initialize thresholds and optimized cutoffs (recommended once per machine/user):
+
+```bash
+mlsort-init  # all params optional; see below
+```
+
+## Quick usage
+
+Top-level API:
+
+```python
+from mlsort import sort, select_algorithm
+
+data = [3, 1, 2, 5, 4]
+algo = select_algorithm(data)   # e.g., 'timsort' or a NumPy backend
+out = sort(data)                # returns a new sorted list
+
+# Options compatible with Python sort()
+out_desc = sort(data, reverse=True)
+out_by_len = sort(["aa", "b", "cccc"], key=len)  # forces builtin Timsort
+```
+
+Behavior summary:
+- Mixed/object/string inputs default to builtin Timsort for safety and compatibility.
+- Passing a key function forces builtin Timsort (NumPy/counting/radix do not support key).
+- reverse=True is supported for all backends; for non-Timsort, results are reversed after sorting.
+- For small arrays, Timsort is used; for medium arrays, NumPy quicksort; the ML decision runs only for very large arrays.
+
+## CLI: initialize thresholds (optional)
+
+```bash
+mlsort-init \
+	--samples 1200 \         # training samples (default 1200)
+	--max-n 200000 \         # max array size to consider (default 200000)
+	--seed 42 \              # default from MLSORT_SEED or 42
+	--artifacts /path/to/cache  # default MLSORT_ARTIFACTS_DIR or OS cache
+```
+
+This writes `thresholds.json` under the artifacts directory and optimizes two size thresholds:
+- cutoff_n: below this, always use Timsort.
+- activation_n: only run ML decision at/above this size; between cutoff and activation use a fast default (NumPy quicksort).
+
+## Configuration
+
+Use environment variables to control behavior:
+
+- MLSORT_ARTIFACTS_DIR: directory for cached artifacts (default: OS cache, e.g., `~/Library/Caches/mlsort` on macOS).
+- MLSORT_ENABLE_INSTALL_BENCH=1: allow benchmarking during lazy first-use initialization.
+- MLSORT_INIT_ON_IMPORT=1: opt-in to run a short init automatically on first import if artifacts are missing.
+- MLSORT_SEED=...: deterministic random seed for benchmarking.
+- MLSORT_DEBUG=1: debug logs showing the selected algorithm and paths.
+
+## Supported algorithms
+
+- Python Timsort (`list.sort`)
+- NumPy quicksort and mergesort
+- Counting sort (integers only; guarded by range to avoid large memory)
+- Radix LSD sort (integers only)
+
+## Safety and limits
+
+- Always-safe fallback: if selection fails or types are unsupported, we use builtin Timsort.
+- Type handling: strings/bytes/mixed objects use Timsort. Numeric-only arrays may use NumPy or integer algorithms.
+- Resource bounds: counting/radix only used when safe; decision is skipped for small/medium arrays to avoid overhead.
+
+## Python versions
+
+Tested on Python 3.9–3.11 in CI.
+
+## Troubleshooting
+
+- Selection slower than a single baseline: ensure you ran `mlsort-init` and that your data sizes reach the activation threshold. For mostly small arrays, Timsort/NumPy will be chosen automatically.
+- Custom cache location: set `MLSORT_ARTIFACTS_DIR` before running `mlsort-init` or your program.
+- Need full control: call `select_algorithm(...)` to see what would be chosen, then run your preferred sort.
+

mlsort-0.1.0/README.md

@@ -0,0 +1,85 @@
+# mlsort
+
+ML-guided sorting backend selector. Chooses between Python Timsort, NumPy sorts, and integer-only counting/radix based on cheap, sampled properties of your data. Defaults are safe; selection only activates for large arrays.
+
+## Install
+
+```bash
+pip install mlsort
+```
+
+Optionally initialize thresholds and optimized cutoffs (recommended once per machine/user):
+
+```bash
+mlsort-init  # all params optional; see below
+```
+
+## Quick usage
+
+Top-level API:
+
+```python
+from mlsort import sort, select_algorithm
+
+data = [3, 1, 2, 5, 4]
+algo = select_algorithm(data)   # e.g., 'timsort' or a NumPy backend
+out = sort(data)                # returns a new sorted list
+
+# Options compatible with Python sort()
+out_desc = sort(data, reverse=True)
+out_by_len = sort(["aa", "b", "cccc"], key=len)  # forces builtin Timsort
+```
+
+Behavior summary:
+- Mixed/object/string inputs default to builtin Timsort for safety and compatibility.
+- Passing a key function forces builtin Timsort (NumPy/counting/radix do not support key).
+- reverse=True is supported for all backends; for non-Timsort, results are reversed after sorting.
+- For small arrays, Timsort is used; for medium arrays, NumPy quicksort; the ML decision runs only for very large arrays.
+
+## CLI: initialize thresholds (optional)
+
+```bash
+mlsort-init \
+	--samples 1200 \         # training samples (default 1200)
+	--max-n 200000 \         # max array size to consider (default 200000)
+	--seed 42 \              # default from MLSORT_SEED or 42
+	--artifacts /path/to/cache  # default MLSORT_ARTIFACTS_DIR or OS cache
+```
+
+This writes `thresholds.json` under the artifacts directory and optimizes two size thresholds:
+- cutoff_n: below this, always use Timsort.
+- activation_n: only run ML decision at/above this size; between cutoff and activation use a fast default (NumPy quicksort).
+
+## Configuration
+
+Use environment variables to control behavior:
+
+- MLSORT_ARTIFACTS_DIR: directory for cached artifacts (default: OS cache, e.g., `~/Library/Caches/mlsort` on macOS).
+- MLSORT_ENABLE_INSTALL_BENCH=1: allow benchmarking during lazy first-use initialization.
+- MLSORT_INIT_ON_IMPORT=1: opt-in to run a short init automatically on first import if artifacts are missing.
+- MLSORT_SEED=...: deterministic random seed for benchmarking.
+- MLSORT_DEBUG=1: debug logs showing the selected algorithm and paths.
+
+## Supported algorithms
+
+- Python Timsort (`list.sort`)
+- NumPy quicksort and mergesort
+- Counting sort (integers only; guarded by range to avoid large memory)
+- Radix LSD sort (integers only)
+
+## Safety and limits
+
+- Always-safe fallback: if selection fails or types are unsupported, we use builtin Timsort.
+- Type handling: strings/bytes/mixed objects use Timsort. Numeric-only arrays may use NumPy or integer algorithms.
+- Resource bounds: counting/radix only used when safe; decision is skipped for small/medium arrays to avoid overhead.
+
+## Python versions
+
+Tested on Python 3.9–3.11 in CI.
+
+## Troubleshooting
+
+- Selection slower than a single baseline: ensure you ran `mlsort-init` and that your data sizes reach the activation threshold. For mostly small arrays, Timsort/NumPy will be chosen automatically.
+- Custom cache location: set `MLSORT_ARTIFACTS_DIR` before running `mlsort-init` or your program.
+- Need full control: call `select_algorithm(...)` to see what would be chosen, then run your preferred sort.
+

mlsort-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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