| Name | mlsort JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | ML-guided sorting backend selector with install-time benchmarking |
| upload_time | 2025-09-10 17:16:19 |
| maintainer | None |
| docs_url | None |
| author | Siddharth Chaudhary |
| requires_python | >=3.9 |
| 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.
|
| keywords |
sorting
machine-learning
numpy
performance
benchmark
timsort
radix
counting-sort
decision-tree
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "mlsort",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "sorting, machine-learning, numpy, performance, benchmark, timsort, radix, counting-sort, decision-tree",
"author": "Siddharth Chaudhary",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/18/50/18b62163bcb79f130deff89407f36fd84b910a3da8845cb1adf27a312f31/mlsort-0.1.0.tar.gz",
"platform": null,
"description": "# mlsort\n\nML-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.\n\n## Install\n\n```bash\npip install mlsort\n```\n\nOptionally initialize thresholds and optimized cutoffs (recommended once per machine/user):\n\n```bash\nmlsort-init # all params optional; see below\n```\n\n## Quick usage\n\nTop-level API:\n\n```python\nfrom mlsort import sort, select_algorithm\n\ndata = [3, 1, 2, 5, 4]\nalgo = select_algorithm(data) # e.g., 'timsort' or a NumPy backend\nout = sort(data) # returns a new sorted list\n\n# Options compatible with Python sort()\nout_desc = sort(data, reverse=True)\nout_by_len = sort([\"aa\", \"b\", \"cccc\"], key=len) # forces builtin Timsort\n```\n\nBehavior summary:\n- Mixed/object/string inputs default to builtin Timsort for safety and compatibility.\n- Passing a key function forces builtin Timsort (NumPy/counting/radix do not support key).\n- reverse=True is supported for all backends; for non-Timsort, results are reversed after sorting.\n- For small arrays, Timsort is used; for medium arrays, NumPy quicksort; the ML decision runs only for very large arrays.\n\n## CLI: initialize thresholds (optional)\n\n```bash\nmlsort-init \\\n\t--samples 1200 \\ # training samples (default 1200)\n\t--max-n 200000 \\ # max array size to consider (default 200000)\n\t--seed 42 \\ # default from MLSORT_SEED or 42\n\t--artifacts /path/to/cache # default MLSORT_ARTIFACTS_DIR or OS cache\n```\n\nThis writes `thresholds.json` under the artifacts directory and optimizes two size thresholds:\n- cutoff_n: below this, always use Timsort.\n- activation_n: only run ML decision at/above this size; between cutoff and activation use a fast default (NumPy quicksort).\n\n## Configuration\n\nUse environment variables to control behavior:\n\n- MLSORT_ARTIFACTS_DIR: directory for cached artifacts (default: OS cache, e.g., `~/Library/Caches/mlsort` on macOS).\n- MLSORT_ENABLE_INSTALL_BENCH=1: allow benchmarking during lazy first-use initialization.\n- MLSORT_INIT_ON_IMPORT=1: opt-in to run a short init automatically on first import if artifacts are missing.\n- MLSORT_SEED=...: deterministic random seed for benchmarking.\n- MLSORT_DEBUG=1: debug logs showing the selected algorithm and paths.\n\n## Supported algorithms\n\n- Python Timsort (`list.sort`)\n- NumPy quicksort and mergesort\n- Counting sort (integers only; guarded by range to avoid large memory)\n- Radix LSD sort (integers only)\n\n## Safety and limits\n\n- Always-safe fallback: if selection fails or types are unsupported, we use builtin Timsort.\n- Type handling: strings/bytes/mixed objects use Timsort. Numeric-only arrays may use NumPy or integer algorithms.\n- Resource bounds: counting/radix only used when safe; decision is skipped for small/medium arrays to avoid overhead.\n\n## Python versions\n\nTested on Python 3.9\u20133.11 in CI.\n\n## Troubleshooting\n\n- 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.\n- Custom cache location: set `MLSORT_ARTIFACTS_DIR` before running `mlsort-init` or your program.\n- Need full control: call `select_algorithm(...)` to see what would be chosen, then run your preferred sort.\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Siddharth Chaudhary\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "ML-guided sorting backend selector with install-time benchmarking",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/sidcoding/mlsort",
"Issues": "https://github.com/sidcoding/mlsort/issues",
"Repository": "https://github.com/sidcoding/mlsort"
},
"split_keywords": [
"sorting",
" machine-learning",
" numpy",
" performance",
" benchmark",
" timsort",
" radix",
" counting-sort",
" decision-tree"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "33cda45e42006c130d857ce11b82f829f5fec4b47de0a3abdcd2173fd5bb7c36",
"md5": "75eac26c0897afc9fb3e050d8ca63f9d",
"sha256": "a2052a2c851ee262bb4ff04af254e49c4102c1868855476abd548705dac898d2"
},
"downloads": -1,
"filename": "mlsort-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "75eac26c0897afc9fb3e050d8ca63f9d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 23096,
"upload_time": "2025-09-10T17:16:17",
"upload_time_iso_8601": "2025-09-10T17:16:17.925392Z",
"url": "https://files.pythonhosted.org/packages/33/cd/a45e42006c130d857ce11b82f829f5fec4b47de0a3abdcd2173fd5bb7c36/mlsort-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "185018b62163bcb79f130deff89407f36fd84b910a3da8845cb1adf27a312f31",
"md5": "3c7401debdc3861d88e8d8403ed8b59d",
"sha256": "21b7e76e083a1ad8ad43083fdd3faf05c6d4771a45b607190b0425d75f154400"
},
"downloads": -1,
"filename": "mlsort-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "3c7401debdc3861d88e8d8403ed8b59d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19239,
"upload_time": "2025-09-10T17:16:19",
"upload_time_iso_8601": "2025-09-10T17:16:19.432046Z",
"url": "https://files.pythonhosted.org/packages/18/50/18b62163bcb79f130deff89407f36fd84b910a3da8845cb1adf27a312f31/mlsort-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 17:16:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sidcoding",
"github_project": "mlsort",
"github_not_found": true,
"lcname": "mlsort"
}
