Metadata-Version: 2.5
Name: strathmark
Version: 3.0.0rc12
Summary: Offline woodchopping handicap engine with trusted V2 and an auditable V3 adaptive-ensemble release candidate
Project-URL: Homepage, https://github.com/SquirmyWormy275/STRATHMARK
Project-URL: Source, https://github.com/SquirmyWormy275/STRATHMARK
Project-URL: Issues, https://github.com/SquirmyWormy275/STRATHMARK/issues
Project-URL: Documentation, https://github.com/SquirmyWormy275/STRATHMARK/tree/main/docs/wiki
Project-URL: Changelog, https://github.com/SquirmyWormy275/STRATHMARK/blob/main/CHANGELOG.md
Author-email: Alex Kaper <alex.j.kaper@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: audit,axemen,ensemble,handicap,sports,woodchopping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.28
Requires-Dist: ulid-py>=1.1
Provides-Extra: api
Requires-Dist: cryptography<51,>=50.0.2; extra == 'api'
Requires-Dist: fastapi>=0.142.2; extra == 'api'
Requires-Dist: httpx2>=2.12.0; extra == 'api'
Requires-Dist: httpx<1,>=0.27; extra == 'api'
Requires-Dist: starlette>=1.3.1; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'api'
Provides-Extra: db
Requires-Dist: supabase>=2.0; extra == 'db'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: cryptography<51,>=50.0.2; extra == 'dev'
Requires-Dist: hatchling>=1.27; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: jsonschema>=4.18; extra == 'dev'
Requires-Dist: openpyxl>=3.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff==0.16.5; extra == 'dev'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
Provides-Extra: llm
Requires-Dist: google-generativeai>=0.8; extra == 'llm'
Requires-Dist: ollama>=0.3; extra == 'llm'
Provides-Extra: ml
Requires-Dist: catboost>=1.2; extra == 'ml'
Requires-Dist: lightgbm>=4.0; extra == 'ml'
Requires-Dist: scikit-learn>=1.3; extra == 'ml'
Requires-Dist: xgboost>=2.0; extra == 'ml'
Provides-Extra: security
Requires-Dist: cryptography<51,>=50.0.2; extra == 'security'
Provides-Extra: v3-candidate
Requires-Dist: catboost==1.2.10; extra == 'v3-candidate'
Requires-Dist: cryptography==50.0.2; extra == 'v3-candidate'
Provides-Extra: workspace
Requires-Dist: flask-wtf<2,>=1.2.2; extra == 'workspace'
Requires-Dist: flask<4,>=3.1.3; extra == 'workspace'
Description-Content-Type: text/markdown

# STRATHMARK

STRATHMARK predicts raw woodchopping times and calculates handicap start marks.
[Managed event operations](docs/MANAGED_EVENTS.md) add a supplied-data standalone
CLI and optional shared workspace over one persistent event. The initial profile
uses real V2 numerics for synthetic SB/UH rehearsals; official activation is
disabled. Calculation-only access and existing V3 profiles remain independent.
[STRATHEX](https://github.com/SquirmyWormy275/STRATHEX) is the application judges use
to set up events, review marks and enter results. Use STRATHMARK directly when you
need the Python library or an API for another application.

## Which version should I use?

| Version or tool | What you can use it for |
| --- | --- |
| **V2** | The established prediction engine. Runs locally on Linux and Windows. |
| **V3 Linux competition runtime** | Formula and trained ML predictions, reviewed and issued fields, results, recovery and learning between rounds. Requires a configured local installation. |
| **V3 Windows V7 service** | Development and rehearsal. Windows production qualification is incomplete. |
| **Accuracy Preview** | Compare a frozen calibration candidate with the baseline. It does not change competition predictions. |

The reviewed pair for new Linux profiles is **STRATHMARK 3.0.0rc12 + STRATHEX 7.4.4**.
Retained rc7/7.4.2 competitions keep their original exact installation, model,
signing authority and saved data. Installing the new pair does not migrate or
activate a profile. Judges choose V2 or V3 when creating each event or tournament;
its events and rounds keep that choice. See
[engine selection](docs/wiki/Competition-Engine-Selection.md).

## Run a competition

Start with [STRATHEX's quick start](https://github.com/SquirmyWormy275/STRATHEX/wiki/Quick-Start).
For Linux V3, follow the [competition setup guide](docs/V3_LINUX_COMPETITION.md).
It covers the separate Python 3.13 environment, trained model, signing key, backup
location and judge workflow. Private models and competition data are supplied by
the operator; they are not included in the public package.

The Linux runtime uses Formula and ML. Its LLM council is unavailable, so judges
must explicitly review affected fields. The Windows V7 service has different
installation and qualification requirements.

## Install the V2 library

Use Python 3.10–3.13; Python 3.13 is recommended. In your virtual environment:

```bash
python -m pip install "strathmark==3.0.0rc12"
python -c "import strathmark; print(strathmark.__version__)"
```

The maintained 3.0.0rc12 package retains the V2 `2.0.0` calculation contract.
New STRATHEX 7.4.4 installations pin its exact reviewed security source. The older
2.0.0/2.0.1 artifacts remain available for retained installations but do not contain
these transport and storage fixes. Install upgrades in a separate environment.
Follow the [Python example](docs/wiki/Quick-Start.md) to calculate a small synthetic
field, or [Installation](docs/wiki/Installation.md) for API setup.

New package versions publish to PyPI automatically after successful main CI. See
the [package release policy](docs/PACKAGE_RELEASE.md) for versioning and recovery.

The maintained **3.0.0rc12** candidate adds request and archive limits, private
storage, trusted receipt timestamps and independent pins for custom V2 models.
See [security and upgrade notes](docs/SECURITY_HARDENING.md). Operational V3 event
authority also requires an independently provisioned monotonic witness; see
[authority trust and migration](docs/AUTHORITY_TRUST.md). Keep saved Linux V3
competitions on their original exact runtime; install upgrades separately for new
competitions. The older 2.0.x library releases do not contain these transport fixes.

## Try the source-build demo

From this repository, on Linux:

```bash
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
strathmark demo
```

Or on Windows PowerShell, with Python 3.13 installed:

```powershell
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
strathmark demo
```

The demo calculates a synthetic V2 field and opens no competition database. It is
included in the current source build; it is not a command in the older V2 PyPI release.

## Understand the marks

A smaller mark starts earlier. A faster expected competitor gets a larger mark and
waits longer. Marks are calculated for the complete field, so a heat's displayed
marks cannot simply be copied into a final with different competitors.

[How handicaps work](docs/wiki/Handicap-Mark-Math.md) explains cutting time, start
counts, rebasing and the role of officials with worked examples.

## Accuracy Preview

The [separate preview program](tools/accuracy-preview/README.md) is implemented.
Its frozen candidate reduced average error from **23.12 to 22.47 seconds** on
278 previously examined historical results. That 2.81% improvement misses the 5%
qualification target and has no independent future validation. The changes are
available in the preview; they are **not enabled in competition predictions**.

## More help

- [Wiki](https://github.com/SquirmyWormy275/STRATHMARK/wiki): installation, examples and explanations.
- [V2](docs/PREDICTION_ENGINE_V2.md) and [V3](docs/PREDICTION_ENGINE_V3.md): detailed engine specifications.
- [Onboarding](ONBOARDING.md): contributor instructions and test isolation.
- [Deployment](docs/DEPLOYMENT.md): service qualification and recovery requirements.
- [Changelog](CHANGELOG.md): release history.

[Apache 2.0 license](LICENSE).
