StatLine v4.0.0rc1

[amillolive]

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/

---

This discussion was created from the release StatLine v4.0.0rc1.