Skip to content

StatLine v4.0.0rc1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@amillolive amillolive released this 30 Aug 22:15
· 31 commits to next since this release
v4.0.0rc1
7f0d6c1

Changelog

[4.0.0rc1] - 2026-08-30

Release Summary

StatLine 4.0.0rc1 is a major architectural rebase of StatLine 3.0.0. It reorganizes the runtime into explicit core, gateway, and app layers, introduces portable StatPacks, replaces the SLAPI v3 HTTP surface with a consolidated v4 API, adds dataset-aware adapter expressions, and formalizes independent release metadata for the core, gateway, and application layers.

The high-level local Python API and most CLI workflows remain recognizable, but this release intentionally removes compatibility shims for the old package/module layout and direct SLAPI v3 endpoints. Applications importing internal v3 modules or calling v3 HTTP routes will require migration.

Added

  • Added package version 4.0.0rc1.

  • Added generation/layer release metadata through:

    • statline/RELEASE
    • statline._release.ReleaseInfo
    • statline._release.RELEASE
    • independent core, gateway, and app release counters.

  • Added generation 4 release values:

    • generation: 4
    • core release: 1
    • gateway release: 1
    • app release: 1

  • Added ARCHITECTURE.md documenting the StatLine rebase architecture and module-ownership rules.

  • Added explicit runtime layers:

    • statline.core for adapters, datasets, scoring, StatPacks, types, and shared tools.
    • statline.gateway for HTTP, authentication, adapter discovery, and persistence.
    • statline.app for CLI, server runner, TUI, and developer tooling.

  • Added python -m statline support through statline.__main__.

  • Added a populated statline.sdk as a stable SDK surface exposing:

    • adapter discovery/loading,
    • dataset discovery/loading,
    • row/batch mapping,
    • row/batch scoring,
    • score(),
    • run_statpack().

  • Added the StatPack package format for portable scoring packages.

  • Added StatPack lifecycle APIs for:

    • manifesting an adapter YAML or source directory,
    • packaging edited sources,
    • rendering runtime adapter YAML,
    • safe unpacking,
    • inspection without executing the runner,
    • execution,
    • report generation.

  • Added the statline statpack CLI group with:

    • manifest
    • pack
    • render
    • unpack
    • inspect
    • register
    • unregister

  • Added top-level statline run <pack.statpack> support for running trusted StatPacks.

  • Added StatPack runner output support for:

    • terminal tables,
    • JSON,
    • JSONL,
    • CSV,
    • Rich HTML/SVG/ANSI report output.

  • Added StatPack dataset embedding when metadata.dataset references a bundled dataset.

  • Added split StatPack schema sections such as:

    • dimensions
    • sniff
    • filters
    • buckets
    • metrics
    • efficiency
    • weights
    • penalties
    • score_profiles

  • Added a bundled unpacked eba_players StatPack source under statline/public/statpacks/.

  • Added .statpack file-type metadata with:

    • Windows current-user registration/unregistration support,
    • Linux MIME/desktop-entry generation,
    • macOS document/UTI manifest generation.

  • Added safe StatPack extraction checks that reject:

    • path traversal,
    • non-canonical archive paths,
    • symlink entries,
    • packages missing required metadata/runner/schema content.

  • Added secret isolation for StatPack subprocesses. API keys and secret-like environment variables are removed by default unless explicitly allowed with --inherit-secrets.

  • Added dataset aggregate functions to the adapter expression language:

    • dataset_max("HEADER")
    • dataset_min("HEADER")
    • dataset_mean("HEADER")
    • dataset_median("HEADER")
    • dataset_sum("HEADER")
    • dataset_count("HEADER")

  • Added case-insensitive dataset aggregate lookup across arbitrary raw input headers.

  • Added shared batch-level dataset context so aggregate values are computed once and reused while mapping every row.

  • Added one-row aggregate behavior so single-row scoring treats the submitted row as a one-row dataset.

  • Added adapter/dataset matching helpers for:

    • resolving dataset paths,
    • resolving an adapter's declared dataset,
    • finding an adapter for a dataset,
    • resolving combined scoring targets.

  • Added a process-wide adapter registry with:

    • compiled adapter caching,
    • parsed-spec caching,
    • source-path caching,
    • atomic refresh,
    • cache diagnostics,
    • normalized alias/stem/ID resolution,
    • collision detection.

  • Added canonical dotted adapter identifiers and separator normalization.

  • Added separate adapter schema directories:

    • schemas/current/
    • schemas/deprecated/

  • Added current v4 adapters:

    • eba.players
    • eba.teams
    • e302.players

  • Added bundled datasets:

    • EBA_Elevate302/e302.s1.players.csv
    • EBA_Elevate302/eba_players_gp3_plus.csv
    • EBA_Elevate302/statline-players(1).csv

  • Added SLAPI/Gateway v4 endpoints for:

    • API index and health,
    • consolidated adapter discovery and metadata,
    • adapter sniffing,
    • paginated packaged dataset access,
    • unified row/batch/dataset scoring,
    • raw and already-mapped input,
    • optional mapped-row output.

  • Added a single /v4/score request model that can score exactly one of:

    • row
    • rows
    • dataset

  • Added input_kind=raw|mapped, caps_mode=batch|row, include_mapped, and dataset scoring limits to the v4 score API.

  • Added v4 authentication, moderation, and administration routes under:

    • /v4/auth
    • /v4/moderation
    • /v4/admin

  • Added structural architecture tests enforcing the new package layout and module-ownership conventions.

  • Added dataset aggregate tests.

  • Added end-to-end StatPack lifecycle tests.

  • Expanded public API tests for current/deprecated adapter registration and v4 scoring behavior.

Changed

  • Changed package metadata from 3.0.0 to 4.0.0rc1.

  • Changed statline.__version__ from a hard-coded package constant to importlib.metadata.version("statline"), with 0+unknown as the source-tree fallback when distribution metadata is unavailable.

  • Reworked the package architecture around the new core, gateway, and app layer boundaries.

  • Changed statline/cli.py into a small command-line façade, with the main CLI implementation moved to statline/app/cli/main.py.

  • Changed the slapi console entry point from statline.slapi.__main__:main to statline.app.runner.main:main.

  • Moved the FastAPI application into statline.gateway.http.

  • Moved the server runner into statline.app.runner.

  • Moved the TUI into statline.app.tui.

  • Moved logging/path helpers into statline.core.tools.

  • Moved timing types into statline.core.types.

  • Split flat scoring modules into:

    • statline.core.scoring.map
    • statline.core.scoring.normalize
    • statline.core.scoring.score
    • statline.core.scoring.weights

  • Split dataset functionality into:

    • statline.core.datasets.load
    • statline.core.datasets.resolve

  • Reworked adapter types into statline.core.types.adapters.

  • Reworked adapter loading into dedicated load, path, validation, matching, compilation, and registry modules.

  • Changed current adapter identity metadata toward the required metadata block containing:

    • id
    • title
    • version
    • author
    • optional aliases,
    • optional dataset reference,
    • optional metadata.

  • Changed current adapter IDs to lowercase dotted identifiers such as eba.players and eba.teams.

  • Changed adapter name lookup so dots, underscores, hyphens, whitespace, and slashes normalize to a common lookup representation.

  • Kept legacy top-level adapter metadata readable for deprecated adapters by converting it into the new metadata structure during loading.

  • Moved demo, example, and valorant adapters into schemas/deprecated/ while keeping them discoverable.

  • Reworked eba_players into the canonical eba.players v4 adapter.

  • Added a second e302.players identity targeting the EBA/Elevate302 player data.

  • Expanded the EBA player adapter from 15 direct metrics and 18 efficiency metrics to 23 direct metrics and 20 efficiency metrics.

  • Added EBA player scoreability/reliability metrics including:

    • real_gp
    • real_gp1
    • no_real
    • rel_gp
    • stat_total
    • stat_active
    • scoreable
    • no_score
    • gp_share

  • Added EBA player scoring_gravity and gp buckets.

  • Changed EBA player relative-GP calculation to use the submitted dataset's maximum GP through dataset_max("GP").

  • Added schema-driven EBA player filters for:

    • league,
    • team,
    • conference,
    • position,
    • minimum GP.

  • Revised EBA player clamps, scoreability behavior, efficiency calculations, bucket weights, and scoring signals.

  • Reworked eba_teams into canonical eba.teams version 4.0.0.

  • Changed EBA team bucket names from the old offense/defense shorthand to explicit offense and defense buckets.

  • Added an EBA team form bucket.

  • Changed team streak scoring to participate directly in recent-form weighting.

  • Revised EBA team PRI, standings, and predictive weight distributions to account for the form bucket.

  • Changed packaged dataset storage from statline/data/stats/ to statline/core/datasets/.

  • Expanded the packaged dataset registry from six CSV files in 3.0.0 to nine CSV files in 4.0.0rc1.

  • Changed dataset discovery to use a canonical packaged root with safe path resolution and ambiguity detection.

  • Changed map_batch() so all rows share one precomputed dataset aggregate context.

  • Changed batch raw scoring so raw filters execute before aggregate context/mapping and mapped metric filters execute after mapping but before score-context calculation.

  • Changed public custom-adapter resolution to require map_raw; the older map_raw_to_metrics fallback is no longer accepted by statline.public.

  • Reworked the SLAPI HTTP API from many specialized v3 scoring routes into the consolidated v4 resource model.

  • Replaced separate v3 adapter metadata endpoints with one /v4/adapters/{adapter} document containing inputs, metrics, buckets, filters, dimensions, weights, penalties, and score profiles.

  • Replaced the separate v3 map/calc/PRI/score HTTP operations with /v4/score.

  • Changed moderation routes from /v3/mod/... to /v4/moderation/....

  • Changed API-key HTTP naming toward api-key / api-keys / api-key-requests.

  • Added an internal CLI request-translation layer so existing CLI workflows can target the consolidated v4 remote API without retaining v3 server routes.

  • Changed dataset API responses to include structured dataset summaries and paginated row responses.

  • Changed health output to include the active adapter count.

  • Changed build configuration to package datasets from statline/core/datasets/**/*.csv.

  • Added statline/RELEASE to wheel and source-distribution contents.

  • Added ARCHITECTURE.md and typing stubs to source distributions.

  • Removed the development upper bound on pytest>=8.1.

  • Changed the development twine requirement to >=7.0,<8.0.

Fixed / Improved

  • Improved batch mapping so adapter expressions can reliably reference statistics from the entire submitted dataset.
  • Improved filtering order so adapter-declared metric filters are evaluated on mapped metric values before scoring context is derived.
  • Improved dimension and legacy filter lookup with case-insensitive raw-field matching.
  • Improved games-played fallback lookup across case variants of games_played, gp, and games.
  • Improved EBA handling of empty/unscoreable player rows.
  • Rows marked unscoreable now receive zero raw scoring contribution rather than participating normally in profile scoring.
  • Unscoreable rows are assigned zero percentile values.
  • Improved numeric coercion and error handling to catch explicit numeric conversion failures rather than broad exceptions in scoring paths.
  • Improved adapter expression compilation through a restricted AST-based expression evaluator with caching.
  • Improved adapter registry refresh so the new registry is installed atomically only after every discovered adapter has parsed and compiled successfully.
  • Improved unknown-adapter errors with a list of available canonical adapters.
  • Improved adapter alias/path resolution and collision detection.
  • Improved dataset resolution with explicit ambiguity errors rather than silently selecting one of multiple matches.
  • Improved packaged-dataset confinement for gateway dataset access.
  • Improved StatPack extraction security with canonical-path, traversal, and symlink validation.
  • Improved StatPack execution isolation by removing secret-like environment variables from child runner processes by default.
  • Improved StatPack portability by embedding referenced datasets and using portable relative dataset paths.
  • Improved machine-readable StatPack output with JSON, JSONL, and CSV modes.
  • Improved score display/export with split-profile and wide-table layouts plus Rich report export.
  • Expanded the test suite from the six tests shipped in 3.0.0 to 21 tests covering architecture, public APIs, dataset aggregates, and StatPacks.

Removed

  • Removed the statline.slapi package namespace.

  • Removed the old flat statline.services namespace.

  • Removed the old flat statline.utils namespace.

  • Removed the old top-level statline.tui namespace; TUI functionality now lives under statline.app.tui.

  • Removed the old statline.data package layout.

  • Removed the old top-level statline.datasets module.

  • Removed the old flat core modules:

    • statline.core.calculator
    • statline.core.normalization
    • statline.core.scoring
    • statline.core.weights

  • Removed the old statline/core/adapters/defs/ adapter location.

  • Removed the old statline/core/adapters/loader.py and types.py layout.

  • Removed direct server exposure of the SLAPI v3 scoring and adapter-metadata API.

  • Removed separate server endpoints for:

    • /v3/map/row
    • /v3/map/batch
    • /v3/calc/pri
    • /v3/calc/pri/batch
    • /v3/pri/row
    • /v3/pri/batch
    • /v3/score/row
    • /v3/score/batch
    • the individual /v3/adapter/{adapter}/... metadata resources.

  • Removed compatibility shims for the old package namespaces as part of the rebase.

  • Removed the public-API fallback for custom adapters exposing only map_raw_to_metrics.

  • Removed the build expectation for statline/slapi/storage/migrations/*.sql.

Breaking Changes

  • Internal imports changed substantially. Code importing statline.slapi, statline.services, statline.utils, statline.tui, statline.datasets, or the old flat core scoring modules must migrate to the new core, gateway, or app paths.
  • There are intentionally no package-level compatibility shims for the removed v3 namespaces.
  • SLAPI clients must migrate from /v3/... to /v4/.... The v4 server does not retain the old scoring/metadata route surface.
  • Remote scoring request and response shapes changed. /v4/score wraps results with adapter/source/count metadata and supports row, rows, or dataset input rather than exposing separate score/map/calc routes.
  • Adapter metadata endpoints changed. Clients should use /v4/adapters/{adapter} rather than the old individual weights, metrics, inputs, dimensions, filters, traits, and spec endpoints.
  • Moderation/auth URL paths changed, including /v4/moderation and the new hyphenated API-key resource names.
  • Canonical adapter IDs changed. eba_players and eba_teams now report canonical IDs eba.players and eba.teams. Legacy stems/aliases remain resolvable by the adapter registry, but code comparing returned adapter names literally may need updates.
  • Current adapter schemas require the v4 metadata model. New adapters should use metadata.id, metadata.title, metadata.version, and metadata.author.
  • Dataset package paths changed from statline/data/stats/... to statline/core/datasets/....
  • Custom compiled-adapter-like objects passed to the public API must expose map_raw. map_raw_to_metrics alone is no longer sufficient.
  • Batch mapping semantics changed for adapters using dataset aggregate functions because mapped values can now depend on the complete filtered batch.
  • EBA player scores may differ materially from 3.0.0 because of new scoreability rules, dataset-relative GP scaling, scoring-gravity weighting, revised clamps, and revised adapter formulas.
  • EBA team scores may differ because of revised weights and the new recent-form bucket.
  • Direct version handling changed. statline.__version__ now comes from installed distribution metadata rather than a hard-coded source constant.

Known RC1 Issues

  • The uploaded 4.0.0rc1 source tree currently runs 20 passing tests and 1 failing test out of 21.
  • The failing test is test_manifest_render_unpack_and_run_round_trip, where StatPack-rendered adapter headers use the StatLine package version while the test expects the adapter's metadata.version.
  • In a bare extracted source tree without installed package metadata, that rendered version currently falls back to 0+unknown.
  • Some documentation in the rc1 source distribution still refers to v3.0.1 despite the package metadata being 4.0.0rc1.
  • Some README/HOWTO dataset examples still contain stale statline/core/datasets/data/stats/... paths; the actual packaged dataset root is statline/core/datasets/....
  • Generated EBA player adapter header comments still contain stale # Version: 3.0.1 text even though their adapter metadata reports version 4.0.0.

Find it on PyPI: https://pypi.org/project/statline/

Assets 3
Loading
0 Join discussion