adaptive_gamification 0.1.0

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

adaptive_gamification

A Flutter package that provides a deployment-oriented runtime library for deterministic execution of exported adaptive policy decisions inside Flutter-based applications.

The package is designed to consume a policy that is:

• trained offline in Python
• exported as a structured JSON lookup artifact
• executed at runtime inside Flutter through deterministic policy lookup

This package is the Flutter deployment and execution side of a larger end-to-end adaptive system:

• Python handles offline RL training, evaluation, and policy export.
• Flutter loads the exported policy and applies runtime adaptive decisions inside the host application.

---

Overview

The package is designed for runtime policy execution, not for model training inside Flutter.

At runtime, the host application supplies learner telemetry such as:

• current difficulty context
• recent accuracy
• response time
• correct-answer streak

The library maps these runtime signals into the deployment-facing state used by the exported policy:

• engagement
• motivation
• flow
• performance

It then performs deterministic policy lookup using the exported JSON artifact generated by the Python reinforcement learning pipeline.

---

Core Design Philosophy

This package follows a strict separation between:

• offline policy learning in Python
• deterministic runtime execution in Flutter

This design keeps the Flutter side:

• lightweight
• reproducible
• fast at runtime
• easy to inspect and debug
• independent from online retraining requirements

Rather than embedding PPO training inside the mobile application, the learned policy is exported as a structured JSON lookup artifact and executed directly inside Flutter.

---

What this package is

This package is:

• a reusable Flutter package
• a deployment-oriented runtime library
• a deterministic policy lookup engine
• a bridge between exported RL policy artifacts and host-application logic
• suitable for fully offline mobile execution

---

What this package is not

This package is not:

• an RL training implementation
• an online-learning mobile retraining system
• a mandatory backend service
• a replacement for the Python research/training pipeline
• a claim of online policy optimization inside Flutter

Backend delivery is optional. A policy can be loaded:

• from app assets using initFromAsset(...)
• or from a raw JSON string using initFromString(...)

---

Main Features

• deterministic policy execution from exported JSON
• deployment-facing state mapping from app telemetry
• exact policy-table lookup with deterministic fallback
• compatibility with policies trained externally in Python
• small and application-facing Flutter API
• support for structured exported policy metadata
• support for direct JSON-string initialization in addition to asset loading

Public API surface:

• AdaptiveEngine.initFromAsset(...)
• AdaptiveEngine.initFromString(...)
• AdaptiveEngine.decide(...)

---

Exported Policy Format

The package is designed to consume the structured policy export generated by the Python pipeline.

Preferred JSON format

{
  "metadata": {
    "format_version": "2.1",
    "policy_type": "deterministic_lookup_table",
    "export_mode": "deterministic_policy_lookup_export",
    "state_order": ["eng", "mot", "flow", "perf"],
    "state_key_format": "eng=<v>|mot=<v>|flow=<v>|perf=<v>",
    "state_decimals": 2,
    "export_resolution": 0.25,
    "state_dim": 4,
    "num_exported_states": 625,
    "num_actions": 6,
    "action_selection": "deterministic_argmax"
  },
  "policy": {
    "eng=0.25|mot=0.50|flow=0.75|perf=1.00": {
      "state_key": "eng=0.25|mot=0.50|flow=0.75|perf=1.00",
      "state": {
        "eng": 0.25,
        "mot": 0.50,
        "flow": 0.75,
        "perf": 1.00
      },
      "action": 3,
      "action_label": "hard_task",
      "decision": {
        "next_difficulty": "hard",
        "reason": "High performance and flow support progression.",
        "support_strategy": "challenge_escalation"
      },
      "probs": [0.01, 0.03, 0.10, 0.78, 0.04, 0.04],
      "value": 0.82
    }
  }
}

Policy key format

The runtime lookup key must match the Python export format exactly:

• eng=0.25|mot=0.50|flow=0.75|perf=1.00

Backward compatibility

The package may optionally support older list-based policy exports, but the structured metadata + policy object format is the preferred integration target.

---

Deployment State Representation

The exported policy operates on the deployment-facing state:

• eng -> engagement
• mot -> motivation
• flow -> flow
• perf -> performance

Each value is normalized to:

• 0.0 to 1.0

The Flutter side does not reproduce the full hidden training environment used in Python. Instead, it builds a runtime approximation of the observable deployment state from application telemetry.

---

Runtime Telemetry Input

The package currently expects a minimal UserState containing:

• currentDifficultyIndex
• accuracy
• responseTime
• correctStreak

These values are mapped into the deployment-facing state by StateMapper.

---

State Mapping Logic

The package includes a StateMapper that converts UserState into:

• engagement
• motivation
• flow
• performance

The mapping is designed to be:

• lightweight
• deterministic
• deployment-friendly
• compatible with the exported policy grid

In the current design:

• performance is derived primarily from accuracy
• engagement blends responsiveness, accuracy, and persistence signals
• motivation reflects streak and sustained performance tendencies
• flow approximates challenge-skill balance using current difficulty context and performance

After feature construction, the state is discretized to match the policy export grid before lookup.

Implemented in:

• lib/src/utils/state_mapper.dart

---

Decision Execution

The runtime execution flow is:

1. Load the exported JSON policy.
2. Parse metadata and build a lookup index.
3. Convert UserState into deployment-facing state.
4. Discretize the state to the policy grid.
5. Build the policy key.
6. Retrieve the matching policy entry.
7. Return the adaptive decision.
8. If no exact key is found, apply a deterministic fallback rule.

The fallback is deterministic and intended only as a safe runtime backup when no exact policy entry is found.

---

Public API

AdaptiveEngine

Main entry point for the package.

Methods:

• Future<void> initFromAsset({ required String policyAssetPath, AssetBundle? bundle, double grid = StateMapper.defaultGrid })
  • loads the policy from a Flutter asset
• void initFromString(String jsonString, { double grid = StateMapper.defaultGrid })
  • loads the policy from a raw JSON string
• AdaptiveDecision decide(UserState state)
  • returns the next adaptive difficulty decision
• void reset()
  • clears the current runtime engine state

The engine also exposes useful metadata after initialization, such as:

• parsed export metadata
• policy size
• current grid
• whether the policy used the structured export format

UserState

Represents runtime learner telemetry.

Fields:

• currentDifficultyIndex
• accuracy
• responseTime
• correctStreak

AdaptiveDecision

Represents the final adaptive decision returned by the library.

Core field:

• nextDifficulty

Additional metadata may include:

• reason
• supportStrategy
• sourceActionName
• decisionType
• lookupKey
• foundExactMatch

---

Installation

A) Local path dependency

In your app's pubspec.yaml:

dependencies:
  adaptive_gamification:
    path: ../adaptive_gamification

B) Git dependency

dependencies:
  adaptive_gamification:
    git:
      url: https://github.com/AmerNakhal/adaptive-gamification-library.git
      path: adaptive_gamification

C) pub.dev

dependencies:
  adaptive_gamification: ^0.1.0

---

Add the Policy JSON to Your App

This package does not bundle a policy by default.

Policies are generated by the Python training/export pipeline and must be supplied by the host application.

Example app pubspec.yaml:

flutter:
  assets:
    - assets/data/adaptive_policy.json

---

Quick Start

import 'package:adaptive_gamification/adaptive_gamification.dart';

final engine = AdaptiveEngine();

Future<void> main() async {
  await engine.initFromAsset(
    policyAssetPath: 'assets/data/adaptive_policy.json',
  );

  final state = UserState(
    currentDifficultyIndex: 2,
    accuracy: 0.70,
    responseTime: 1.20,
    correctStreak: 3,
  );

  final decision = engine.decide(state);

  print('Next difficulty: ${decision.nextDifficulty}');
  print('Reason: ${decision.reason}');
  print('Exact match: ${decision.foundExactMatch}');
}

---

Internal Components

PolicyLoader

Responsible for:

• loading policy JSON
• parsing metadata
• parsing policy entries
• building a fast lookup index

Implemented in:

• lib/src/core/policy_loader.dart

StateMapper

Responsible for:

• converting app telemetry into deployment-facing state
• discretizing values to the export grid
• building Python-compatible lookup keys

Implemented in:

• lib/src/utils/state_mapper.dart

DecisionEngine

Responsible for:

• generating the lookup key
• retrieving the indexed policy entry
• extracting the final adaptive decision
• applying deterministic fallback when necessary

Implemented in:

• lib/src/core/decision_engine.dart

AdaptiveEngine

Provides the high-level runtime API for application use.

Implemented in:

• lib/src/engine/adaptive_engine.dart

---

Library Structure

adaptive_gamification/
├── lib/
│   ├── adaptive_gamification.dart
│   └── src/
│       ├── core/
│       │   ├── decision_engine.dart
│       │   └── policy_loader.dart
│       ├── engine/
│       │   └── adaptive_engine.dart
│       ├── models/
│       │   ├── adaptive_decision.dart
│       │   └── user_state.dart
│       └── utils/
│           ├── difficulty_mapper.dart
│           └── state_mapper.dart
├── example/
├── README.md
└── pubspec.yaml

---

Example App

A runnable example app is included under example/.

cd example
flutter pub get
flutter run

---

Testing

Run package tests with:

flutter test

---

Integration with the Python Pipeline

This package is designed to work directly with the Python reinforcement learning pipeline that:

• trains the policy offline
• evaluates the policy against baselines
• exports a deterministic JSON policy table
• optionally exports a checkpoint or TorchScript artifact

In the full system:

• Python is the training and export side
• Flutter is the deployment and execution side

The primary integration artifact is:

• adaptive_policy.json

---

Current Scope

This package currently supports:

• deterministic execution of exported adaptive policies
• offline policy loading from assets or raw JSON
• runtime deployment-state mapping
• adaptive difficulty decision retrieval
• deterministic fallback behavior when exact lookup fails

The package should be understood as a deployment-oriented runtime library, not as a claim of online RL training or real-time policy optimization inside Flutter.

---

Research Context

This library is part of a broader adaptive educational system that investigates how reinforcement learning can support:

• sequential adaptive intervention selection
• learner-state-aware decision making
• deployment-friendly policy execution
• reusable cross-platform adaptive learning applications

Its contribution lies in making externally trained adaptive policies usable inside a practical Flutter deployment layer.

---

License

See LICENSE.