adaptive_gamification 0.1.2

A deployment-oriented Flutter runtime library for deterministic execution of exported adaptive policy decisions.

Changelog

All notable changes to adaptive_gamification will be documented in this file.

The format is based on Keep a Changelog (https://keepachangelog.com/en/1.1.0/), and this project follows Semantic Versioning (https://semver.org/).

Unreleased

Added

• None.

Changed

• None.

Deprecated

• None.

Removed

• None.

Fixed

• None.

Security

• None.

0.1.2 - 2026-04-21

Patch release focused on final packaging cleanup, changelog/version alignment, and publish-readiness improvements after the 0.1.1 release.

Added

• None.

Changed

• Updated package release metadata and changelog references to align with version 0.1.2.
• Finalized release documentation consistency for the publishable 0.1.2 patch release.

Deprecated

• None.

Removed

• None.

Fixed

• Fixed final release bookkeeping inconsistencies between package versioning and changelog history.
• Fixed residual publish-readiness issues identified after the 0.1.1 patch release.

Security

• None.

0.1.1 - 2026-04-21

Patch release focused on publish-readiness fixes and final package cleanup after the 0.1.0 runtime-library update.

Added

• None.

Changed

• Replaced AdaptiveDecision.fromMap(...) factory constructor with a static fromMap(...) method for safer package compatibility during pub.dev evaluation.
• Finalized package metadata, examples, and documentation for the publishable 0.1.1 patch release.

Deprecated

• None.

Removed

• None.

Fixed

• Fixed pub.dev/package-evaluation issues related to the AdaptiveDecision deserialization helper.
• Fixed final publish-readiness inconsistencies after the 0.1.0 package maturation update.

Security

• None.

0.1.0 - 2026-04-21

Package maturation release focused on deployment-oriented runtime execution, stronger public API clarity, improved structured policy handling, and cleaner example/demo integration.

Added

• AdaptiveEngine.reset() and AdaptiveEngine.grid for clearer runtime lifecycle control and inspection.
• Richer AdaptiveDecision support with:
  • decisionType
  • fromMap(...)
  • toJson()
• Improved UserState helpers with:
  • isValid
  • toJson()
• Stronger policy-loading support through PolicyLoader.clear() and rawEntryCount.
• Better state-mapping utilities through StateMapper.toRlStateMap(...) and grid validation.
• More robust difficulty utilities through an expanded DifficultyMapper.
• Improved example application visibility for:
  • engine initialization status
  • grid value
  • export metadata
  • decision type
  • exact-match vs fallback behavior

Changed

• Reframed the package more precisely as a deployment-oriented runtime library for deterministic execution of exported adaptive policy decisions.
• Updated package metadata and documentation to align with version 0.1.0.
• Improved DecisionEngine to preserve stronger runtime traceability through clearer fallback reasoning and lookup-key propagation.
• Improved PolicyLoader normalization and legacy-format handling.
• Improved StateMapper readability and validation while keeping deployment-facing state generation deterministic.
• Improved model serialization and copy patterns across runtime-facing data objects.
• Updated README examples to use adaptive_policy.json rather than older seed-specific filenames.
• Cleaned and strengthened package/example structure so the library is exposed more clearly as a reusable Flutter runtime artifact.

Fixed

• Fixed inconsistencies between older seed-specific example references and the updated exported policy naming used by the current workflow.
• Fixed package/example mismatches in documentation and initialization examples.
• Fixed runtime integration issues uncovered while aligning the Flutter package with the finalized structured Python export pipeline.
• Fixed package quality issues so the package remains compatible with:
  • flutter analyze
  • flutter test
  • dart pub publish --dry-run

Security

• None.

0.0.2 - 2026-03-29

Major update of the Flutter deployment library to align with the finalized Python reinforcement learning pipeline and structured policy export format.

Added

• Support for the structured exported policy format with:
  • top-level metadata
  • top-level policy
• Export metadata exposure through AdaptiveEngine, including:
  • parsed policy metadata
  • structured-format detection
  • policy size
• Richer AdaptiveDecision model with optional runtime metadata:
  • supportStrategy
  • sourceActionName
  • lookupKey
  • foundExactMatch
• Improved example application that demonstrates:
  • policy metadata display
  • runtime session state
  • latest adaptive decision details
  • exact-match vs fallback visibility

Changed

• Updated PolicyLoader to support the finalized Python export structure and Python-compatible policy keys.
• Updated StateMapper to use the deployment-facing state representation:
  • engagement
  • motivation
  • flow
  • performance
• Updated runtime key generation to the finalized format:
  • eng=0.25|mot=0.50|flow=0.75|perf=1.00
• Improved DecisionEngine to read full policy entries rather than decision-only values.
• Improved fallback logic to use deployment-facing state signals instead of relying only on accuracy.
• Updated AdaptiveEngine to pass export metadata such as stateDecimals into runtime lookup logic.
• Improved UserState handling with safer normalization and parsing.
• Improved package documentation and README to reflect the finalized deployment-oriented architecture.
• Improved test coverage to validate the structured export format and richer adaptive decision outputs.

Fixed

• Fixed incompatibility with the older list-based policy assumption.
• Fixed mismatch between Flutter policy lookup format and finalized Python export key format.
• Fixed outdated example and README content that no longer matched the final Python pipeline.
• Fixed analyzer issues and package-quality issues so the package passes:
  • flutter analyze
  • flutter test
  • flutter pub publish --dry-run

Security

• None.

0.0.1 - 2026-03-23

Initial public release of the package.

Added

• Core API
  • AdaptiveEngine with:
    • initFromAsset({ required String policyAssetPath, AssetBundle? bundle })
    • initFromString(String jsonString)
  • AdaptiveEngine.decide(UserState) returning an AdaptiveDecision.
• Models
  • UserState (difficulty index, accuracy, response time, correct streak).
  • AdaptiveDecision (next difficulty label and a human-readable reason).
• Policy loading & indexing
  • PolicyLoader to load and index an RL policy exported as JSON.
  • Deterministic lookup by a discretized RL-state key (fixed 2 decimals).
• RL state mapping utilities
  • StateMapper.toRlState() mapping app telemetry → RL state (eng, mot, flow, perf).
  • Grid discretization aligned with a 0.25 state resolution.
  • Stable key formatting to prevent lookup mismatches.
• Fallback behavior
  • Deterministic fallback decision logic when the exact policy entry is missing.