mpara-learning-engine

Tap pattern learning engine for grid-based prediction games.

Analyzes user tap patterns on a price-prediction grid and generates learned strategies for automated play.

---

Overview

This engine powers the Training Mode in MegaPARA. It records where and when users tap on a grid overlay of a live price chart, then learns their play style to enable auto-play.

What it does:

1. Records tap data (grid position, multiplier, win/loss result)
2. Analyzes patterns (preferred positions, timing, strategy type)
3. Selects optimal positions for auto-play based on learned weights

Install

pip install -e .

Or just copy mpara_learning_engine/engine.py into your project - it has zero external dependencies.

Quick Start

from mpara_learning_engine import PatternEngine, TapRecord

# Record some taps
taps = [
    TapRecord(grid_row=0, grid_col=2, price_at_tap=2100.0, multiplier=1.2, result="win"),
    TapRecord(grid_row=1, grid_col=3, price_at_tap=2101.5, multiplier=1.5, result="loss"),
    TapRecord(grid_row=0, grid_col=2, price_at_tap=2099.0, multiplier=1.2, result="win"),
]

# Analyze
engine = PatternEngine()
pattern = engine.analyze(taps)

print(pattern.strategy)           # "balanced"
print(pattern.win_rate)           # 66.7
print(pattern.preferred_positions)  # [PositionStat(position='0,2', win_rate=100.0, count=2), ...]

# Auto-play: select next position
row, col = engine.select_position(pattern)

How It Works

Pattern Analysis

The engine computes the following from tap history:

Field	Description
strategy	aggressive / balanced / conservative based on avg winning multiplier
win_rate	Overall win percentage (0-100)
preferred_positions	Top positions ranked by win rate and frequency
row_weights	Normalized preference per row (price band)
col_weights	Normalized preference per column (timing)

Strategy Classification

Strategy	Condition	Description
aggressive	avg_win_multiplier >= 1.4x	Prefers high-risk, high-reward positions
conservative	avg_win_multiplier <= 1.1x	Prefers safe, low-multiplier positions
balanced	between 1.1x and 1.4x	Mix of safe and risky bets

Thresholds are configurable:

engine = PatternEngine(
    aggressive_threshold=2.0,
    conservative_threshold=0.8,
    max_preferred_positions=5,
)

Auto-Play Selection

select_position() uses weighted random selection from preferred_positions, where weight = win_rate * count. Positions with higher win rates and more data points are selected more frequently.

API Reference

TapRecord

@dataclass
class TapRecord:
    grid_row: int          # Row offset from price center
    grid_col: int          # Column index (0 = nearest future)
    price_at_tap: float    # Reference price at tap time
    multiplier: float      # Payout multiplier for this cell
    result: "win" | "loss" # Outcome
    timestamp: int | None  # Unix ms (optional)

LearnedPattern

@dataclass
class LearnedPattern:
    strategy: "aggressive" | "balanced" | "conservative"
    win_rate: float                        # 0-100
    avg_multiplier: float
    avg_win_multiplier: float
    preferred_positions: list[PositionStat]
    row_weights: dict[str, float]          # "row_idx" -> 0-100
    col_weights: dict[str, float]          # "col_idx" -> 0-100
    total_taps: int
    total_wins: int

PatternEngine

class PatternEngine:
    def analyze(self, tap_history: list[TapRecord]) -> LearnedPattern | None
    def select_position(self, pattern: LearnedPattern) -> tuple[int, int] | None

Testing

pip install pytest
pytest

Contributing

See CONTRIBUTING.md for guidelines.

Areas where contributions are welcome:

• New strategy classifiers - ML-based, time-series aware, etc.
• Better position selection - Explore/exploit balance, multi-armed bandit
• Streak detection - Identify hot/cold streaks in tap history
• Temporal analysis - Weight recent taps more heavily
• Visualization - Heatmaps, charts for pattern analysis results

License

MIT - See LICENSE

---

mpara-learning-engine (Japanese)

グリッドベース予測ゲーム用のタップパターン学習エンジン。

ライブ価格チャート上のグリッドでユーザーのタップパターンを分析し、自動プレイのための学習済み戦略を生成します。

概要

このエンジンは MegaPARA のトレーニングモードで使用されています。ユーザーがグリッド上でタップした位置とタイミングを記録し、プレイスタイルを学習して自動プレイを実現します。

機能:

1. 記録 - タップデータ（グリッド位置、倍率、勝敗）
2. 分析 - パターン（好みのポジション、タイミング、戦略タイプ）
3. 選択 - 学習した重みに基づく自動プレイ用ポジション選択

インストール

pip install -e .

または mpara_learning_engine/engine.py をプロジェクトにコピーするだけでOK。外部依存なし。

コントリビューション歓迎

• 新しい戦略分類器（ML、時系列分析）
• より良いポジション選択（探索/活用バランス）
• ストリーク検出（連勝/連敗パターン）
• 時間的分析（最近のタップに重み付け）
• 可視化（ヒートマップ、チャート）

詳細は CONTRIBUTING.md を参照してください。