StatLine

StatLine is an adapter-driven player scoring and analytics toolkit for turning raw stat rows into weighted, explainable ratings.

It can run completely locally for simple scoring workflows, or against SLAPI, the optional StatLine API layer for authenticated remote scoring, adapter inspection, and multi-client deployments.

Release target: v4.0.0rc3 Python: 3.10 through 3.14 License: AGPL-3.0-or-later, with separate trademark restrictions for the StatLine name and branding.

What StatLine does

StatLine takes raw rows such as CSV box-score data, maps those rows through an adapter, scores the mapped metrics, then returns profile scores such as PRI and adapter-defined variants.

At a high level, StatLine provides:

• Adapter-based scoring for different games, leagues, datasets, or stat schemas.
• Local scoring through the Python package and statline CLI.
• Remote/API scoring through SLAPI when installed with the remote stack.
• Weighted score profiles, including PRI-style outputs and adapter-defined variants.
• Batch scoring, row scoring, mapping-only commands, and already-mapped calculation commands.
• Adapter inspection tools for inputs, metrics, dimensions, filters, weights, and sniffing.
• Typed public Python API for bots, dashboards, notebooks, and application code.

v4.0.0rc3 highlights

• Compiled adapters now execute against a trusted numeric context, avoiding repeated numeric coercion in expression hot paths.
• Dataset aggregate expressions declare their required operations at compile time, so batches only prepare the headers and aggregates an adapter actually uses.
• Scoring can opt into selected profiles with profiles=[...]; existing callers still receive every adapter-defined profile by default.
• Output-aware scoring skips disabled bucket, component, weight, and context payload construction instead of allocating data only to discard it later.
• CLI score output uses the lean scoring path when --details is not requested while preserving the existing displayed/exported fields.
• statline os launches a persistent Textual REPL/shell/TUI client with pooled SLAPI connections and reusable in-process state.
• SLAPI scoring is kept off the async event loop and the server runner can use multiple worker processes through SLAPI_WORKERS.
• Deprecated adapter schemas are no longer discoverable through CLI/API lists or sniffing; an explicit local YAML path is required to use one.

Install

StatLine v4.0.0rc3 has five intended install variants.

For a source checkout:

python -m venv .venv

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -e ".[devpack]"

Quick start: local CLI

Local mode avoids all network probing and uses the installed StatLine core directly.

statline --mode local adapter list
statline --mode local adapter inputs eba.players
statline --mode local adapter weights eba.players

Score a bundled EBA CSV from a source checkout:

statline --mode local score \
  --adapter eba.players \
  EBA_Elevate302/eba_s1_players.csv \
  --fmt table \
  --profile all \
  --percentile \
  --limit 10

Write JSON instead:

statline --mode local score \
  --adapter eba.players \
  EBA_Elevate302/eba_s1_players.csv \
  --fmt json \
  --pretty \
  --out results.json

On Windows PowerShell, either enter the command on one line or use PowerShell's backtick continuation character instead of \.

Quick start: Python API

from statline import list_adapters, load_dataset, score

print(list_adapters())

rows = load_dataset("EBA_Elevate302/eba_s1_players", limit=10)

results = score(
    "eba.players",
    rows,
    mode="batch",
    weights="pri",
)

for row in results[:3]:
    print(row["pri"], row["pri_raw"], row.get("scores", {}))

For one row:

from statline import score_row

player = {
    "PLAYER": "Example Player",
    "GP": 12,
    "PPG": 24.5,
    "RPG": 5.0,
    "APG": 6.2,
    "SPG": 1.5,
    "BPG": 0.7,
    "TPG": 2.1,
    "FGMPG": 9.2,
    "FGAPG": 18.4,
    "WIN": 9,
    "LOSS": 3,
}

result = score_row("eba.players", player, weights="pri")

print(result["pri"])

CLI overview

The main command is:

statline --help

Useful global options:

Primary user commands:

Scoring concepts

Adapter

An adapter is a YAML contract that explains how to turn raw fields into StatLine metrics. It defines:

• metadata such as key, version, aliases, and title,
• raw-to-metric mappings,
• derived efficiency metrics,
• buckets,
• weight profiles,
• penalties,
• score profiles,
• optional dimensions and filters,
• optional sniffing rules for adapter detection.

Metric

A metric is a numeric signal used by the scoring engine. Metrics can be direct fields, constants, or safe expressions over previous values.

Bucket

A bucket groups metrics for weighting. A PRI profile does not usually weight every metric one by one; it weights the buckets.

Weight profile

A weight profile defines how strongly each bucket contributes. The default profile is usually pri, but adapters can expose more.

Score profile

A score profile controls how the normalized raw score becomes a published score. StatLine supports affine profiles and windowed profiles.

PRI and pri_raw

pri_raw is the normalized raw score. pri is the adapter/profile-rendered score.

Some adapters also expose additional profile scores such as pri_af, pri_ar, or pri_ap.

Dataset-relative expressions

Adapters can reference aggregate values from the current input dataset when mapping rows.

Available dataset aggregate functions include:

dataset_max("FIELD")
dataset_min("FIELD")
dataset_mean("FIELD")
dataset_median("FIELD")
dataset_sum("FIELD")
dataset_count("FIELD")

Field lookup is case-insensitive.

This allows adapters to define scoring behavior relative to the current dataset rather than relying exclusively on fixed constants. For example:

rel_gp:
  expr: min(1.0, real_gp / max(1.0, dataset_max("GP") * 0.65))

In batch workflows, dataset aggregates are calculated once for the input dataset and shared while mapping its rows.

Input formats

The CLI reads CSV, YAML, JSON-like YAML, and stdin CSV for commands that accept file input.

CSV example:

name,ppg,apg,orpg,drpg,spg,bpg,tov,fgm,fga,win,loss
Example Player,24.5,6.2,1.0,4.0,1.5,0.7,2.1,9.2,18.4,12,8

YAML example:

- name: Example Player
  ppg: 24.5
  apg: 6.2
  orpg: 1.0
  drpg: 4.0
  spg: 1.5
  bpg: 0.7
  tov: 2.1
  fgm: 9.2
  fga: 18.4
  win: 12
  loss: 8

Remote/API mode

Install the remote variant:

pip install "statline[remote]"

Start SLAPI locally:

statline --mode local serve --host 127.0.0.1 --port 8000

Or use the slapi console entry point:

SLAPI_HOST=127.0.0.1 SLAPI_PORT=8000 slapi

Then point clients at it:

export SLAPI_URL="http://127.0.0.1:8000"
statline --mode remote sys status

On Windows PowerShell:

$env:SLAPI_URL = "http://127.0.0.1:8000"
statline --mode remote sys status

SLAPI supports protected authentication flows. Normal remote use requires both device enrollment and an API key. Administrative and moderation commands require the corresponding scopes.

Common auth flow:

statline auth device-init
statline auth enroll --token reg_... --user your-handle --email you@example.com
statline auth apikey-request --owner your-name
statline auth apikey-claim --request-id REQUEST_ID
statline auth whoami

The exact approval steps depend on the SLAPI administrator.

Development

Install the development pack:

python -m pip install -e ".[devpack]"

Run checks:

pytest
ruff check statline tests
mypy statline
pyright

Build release artifacts:

python -m build
twine check dist/*

Legal

StatLine source code is licensed under the GNU Affero General Public License v3 or later. The StatLine name, marks, and logos are not granted by the source license.

See:

• LICENSE
• TRADEMARK_POLICY.md
• CLA.md
• legal/tos.md
• legal/privacypolicy.md
• legal/aup.md

Repository

• Homepage: https://statline.dev
• Repository: https://github.com/amillolive/StatLine
• Issues: https://github.com/amillolive/StatLine/issues
• API Documentation: https://api.statline.dev/redoc
• Interactive API Documentation: https://api.statline.dev/docs