mlsort 0.1.0__py3-none-any.whl

mlsort-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+mlsort/__init__.py,sha256=49ZFRUBmCcD_YpHDLtAvb6CjCOAUoDqczL0c5pTWhPs,1121
+mlsort/algorithms.py,sha256=MgOOe9SHy9D_af7siDS4jWtuLK6alhIv8sPusqCx9qI,4475
+mlsort/api.py,sha256=T1T_ND-ybfld0FTHyjAihhNgPTcjcWgXnv50bnVnoKw,6026
+mlsort/baseline.py,sha256=2nZrEY7P5QAQ8RPOxqNz47rR_WZMyd3iONOSR38u_-Y,1104
+mlsort/benchmark.py,sha256=Ez_-HOnbvzfZD0323Nv_8vGj3xhENflztD-7IOEAalo,3713
+mlsort/cli_bench_compare.py,sha256=HH1C8H8IpWWdORT81_1gsO_je7emLW9NEIpqPedDbgw,1771
+mlsort/cli_bench_install.py,sha256=g28V9TZ_b5rJIEbV9LAkXZWYZaUMYQK10npGGxTZ5jI,936
+mlsort/cli_init.py,sha256=kDcnne1lLTRg5IEZVBOYiV8kkzb_5JHmTybZEvvPpKw,1721
+mlsort/cli_optimize_cutoffs.py,sha256=6De71xb93z6JScfMIduKkDe9DZ7xaG2Pg085JQe6HB0,1216
+mlsort/config.py,sha256=3Qzumm41uCvseH9LbRaDe06ffFOsJ3k3f20pM_bdjg8,966
+mlsort/data.py,sha256=HHtffrqOE15jLRxN6sc__mXBKsptT-USLxsZhq09SIc,3246
+mlsort/decision.py,sha256=YB3epa2L7Wa1faFmbyTSNjdGj0NigO2mro7K_k5IklA,1527
+mlsort/features.py,sha256=MJOwPnC4z8VDwiA9PXBgjwSr5r9djup7ZieGzSmwMbg,5303
+mlsort/installer.py,sha256=M7Dj2lMEecNblWY4YoMBME3fjqNf8L2BolNbvLcYUxE,4904
+mlsort/model.py,sha256=OY6b_04unIIbjrjmQ4LKrG52TmB7FvUBbflcBNg2-d0,2378
+mlsort/optimize.py,sha256=7Yi6tmiJcnj_6NtDfViuxzY1nVR3zoq-sbOj0v7yEis,2945
+mlsort-0.1.0.dist-info/licenses/LICENSE,sha256=yzOA5llIyAHw7tVsir3l5NgRm1_pkvXy2r4bUFcZY0g,1076
+mlsort-0.1.0.dist-info/METADATA,sha256=m4fy4EuvfqrB-enbeFxXrEQZb0nhbErdEaqAooD05DU,5794
+mlsort-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mlsort-0.1.0.dist-info/entry_points.txt,sha256=HKRZnDWd50NuGw9uFEhAUZE6OOEKl74MT3J3yHL-1Is,218
+mlsort-0.1.0.dist-info/top_level.txt,sha256=0tl8OhYGP3bgyXuS76DsDreFASPKloMccz5pGfteKp0,7
+mlsort-0.1.0.dist-info/RECORD,,

mlsort-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mlsort-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+mlsort-bench-compare = mlsort.cli_bench_compare:main
+mlsort-bench-install = mlsort.cli_bench_install:main
+mlsort-init = mlsort.cli_init:main
+mlsort-optimize-cutoffs = mlsort.cli_optimize_cutoffs:main

mlsort-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+mlsort