Formula-Traceable AI: How the ADE Decision Engine Makes Tetris AI Explainable

When AI plays Tetris, it makes thousands of piece-placement decisions per minute. Most implementations output only an action—no explanation, no reasoning trace, no audit trail. ADE (Aether Decision Engine) aims to change that: every decision flows through a formula-traceable pipeline—option_scoring → softmax → argmax → margin → rules—leaving an auditable record at every step.

The Problem: Opaque AI Decisions

A standard Tetris AI typically does this: enumerate all legal placements, score each one, and return the highest score directly. The output is just a single line like "place the piece in column 7, rotate 3 times"—no reasoning, no confidence, no audit trail.

ADE wraps this process in a decision framework that makes the previously implicit reasoning explicit as structured records. Each decision produces an ADEDecision dataclass containing: piece type, rotation, column, confidence, margin (the gap between top-1 and top-2 scores), softmax probabilities, formula chain, fired rules, full audit trace, decision ID, and latency.

In other words, any placement can be traced back through the complete formula chain to determine why the AI chose that position.

Architecture: A Five-Stage Formula Chain

ADE's decision pipeline is divided into five stages, each stage's output feeding into the next.

1. Option Scoring

Each legal placement is scored using Tetris heuristics, with features including max_height, holes, aggregate_height, wellness, combined with the number of lines cleared. These scores are the raw input for all subsequent computations.

2. Softmax Normalization

Raw scores are converted to probabilities via temperature-scaled softmax. Temperature controls the exploration-exploitation tradeoff: lower temperature means more certainty, higher temperature means more exploration. Self-testing used a temperature of 0.5.

How the temperature parameter works: The softmax function converts a set of real-valued scores into a probability distribution using the formula P(i) = exp(s_i / T) / Σ_j exp(s_j / T), where T is the temperature. As T→0, the distribution degenerates into a one-hot form, with the maximum term's probability approaching 1 and the decision becoming fully deterministic; as T increases, the probabilities of each option tend toward uniformity, increasing exploration. ADE uses T=0.5, which amounts to a gentle sharpening of the raw heuristic scores—preserving the relative ranking of scores while leaving meaningful gradient space for confidence estimation. Notably, softmax here is not a decorative step: its output probability distribution is a required input for downstream margin calculation and rule evaluation. In the extreme case where the O-piece has only a single legal placement, softmax degenerates into a degenerate distribution (all probability assigned to the sole option), and margin is naturally 1.0—this is not the engine being "overconfident" but a mathematical necessity. Understanding this helps correctly interpret ADE's confidence metrics.

3. Argmax Selection

The option with the highest weight is selected from the normalized probabilities—this is the final decision action.

4. Margin Calculation

Confidence is measured by the probability gap between top-1 and top-2. margin=1.0 means the best option is overwhelmingly ahead; margin≈0 means multiple options have similar scores—a "hard decision." This metric is ADE's core signal for assessing its own uncertainty.

5. Rule Evaluation

Rules fire based on margin thresholds and board state, including: margin gating (flagging uncertainty when below threshold), safety (rejecting placements that create holes or exceed height limits), and stability (preferring placements that form flat surfaces).

Margin gating and quantifying uncertainty: Margin is the gap between top-1 and top-2 in the softmax probability distribution, ranging over [0, 1]. When margin approaches 1, the top option's probability is far higher than the runner-up, and the decision is nearly unambiguous; when margin approaches 0, top-1 and top-2 probabilities are comparable, and the decision is in a "dilemma." ADE sets margin < 0.3 as the uncertainty flag threshold and margin < 0.1 triggers VPU parallel exploration. The significance of this tiered design is that the system no longer treats all decisions uniformly but dynamically allocates computational resources based on its own degree of confidence. In measured data, O-piece margin=1.0 (single-placement degenerate distribution) contrasts sharply with J-piece margin being extremely low (multiple options with close scores), showing that margin genuinely captures differences in decision difficulty rather than simple fluctuation in absolute score values.

Measured Benchmark Results

ADE's self-test output shows actual records from 10 consecutive decisions. Key metrics are as follows:

Metric	Value
Average latency	0.18 ms/decision
Latency range	0.07–0.29 ms
Average confidence	0.533
Average margin	0.275
Rules fired	1–2 per decision
Margin lower bound	0.3

The data itself reveals several interesting phenomena. The O-piece had confidence=1.0 and margin=1.0 in two decisions—not because the engine was "confident," but because in that board state the O-piece had only one legal placement, and softmax degenerated into a degenerate distribution. J- and I-pieces showed low confidence (0.078, 0.107), indicating multiple options with similar scores—a genuinely difficult judgment.

This ability to distinguish is precisely the value of explainability: the system doesn't just give an answer but also annotates its own degree of confidence in that answer.

Degraded Mode and VPU Coordination

ADE is designed with fault tolerance in mind. When the full engine is unavailable (path errors or missing dependencies), the agent degrades to pure heuristic mode—same formula chain, same decision structure, just lacking ADE engine's advanced scoring, with a completely identical API interface.

When uncertainty is high (margin < 0.1), ADE can invoke the VPU (Vector Processing Unit) for high-dimensional parallel exploration. This forms a two-layer decision system: ADE handles fast, deterministic, auditable decisions (0.18 ms/decision), while VPU handles slow, parallel, exploratory reasoning (0.32 ms/step, 3000+ FPS). VPU returns entropy-based convergence metrics, where lower entropy indicates greater convergence toward a particular strategy.

VPU's entropy convergence metric: VPU (Vector Processing Unit) here refers to a vectorized parallel computing unit capable of simultaneously evaluating large numbers of candidate strategies in high-dimensional space. When ADE invokes VPU, the "entropy" returned is Shannon entropy in the information-theoretic sense, H = -Σ p_i log p_i, measuring the degree of uncertainty in the strategy distribution. Lower entropy means VPU is converging toward a particular strategy cluster during high-dimensional exploration; higher entropy means the strategy space remains dispersed. ADE's regular mode (softmax + argmax) is essentially single-step greedy selection, while VPU mode is more like a parallel "sweep" of the strategy space, using entropy as a convergence signal to decide whether to adopt its suggestions. The division of labor between the two layers is: ADE handles over 90% of routine decisions (0.18 ms each), invoking VPU's parallel compute power only when margin is extremely low (0.32 ms/step), achieving a dynamic balance between performance and exploration depth.

Beyond Tetris: A General Pattern for Auditable Decisions

ADE's formula-traceable pattern applies to any decision system that needs to know "why." The original article gives three application directions:

• Autonomous driving: sensor data → obstacle detection → path scoring → softmax → route selection, with audit trails for regulatory compliance
• Financial trading: market data → signal scoring → softmax → position sizing → margin checks, with audit trails also serving regulatory compliance
• Medical diagnosis: patient data → test results → diagnostic scoring → softmax → treatment selection, with audit trails for malpractice insurance

All three scenarios share the same pattern: scoring → normalization → selection → confidence measurement → audit. This abstraction makes ADE not just a game AI trick but a transferable decision architecture.

Code Structure and How to Run

The project structure is clear: ade_agent.py (528 lines) contains ADEDecision, BoardEvaluation, and ADEAgent; tetris_core.py (283 lines) contains game logic and heuristic scoring; daemon/new_version/ade/ is the external ADE engine dependency, providing the AetherEngine class and DecisionContext type.

Running the self-test just requires python ade_agent.py. When integrating into a project, create TetrisGame(seed=42) and ADEAgent(temperature=0.5), call agent.decide_placement() in a loop, and access fields like decision.formula_chain and decision.rules_fired for complete audit information. The project is MIT-licensed, with code hosted at github.com/logout2login.

Key Takeaways

ADE proves with measured data that auditability and performance are not contradictory. An average latency of 0.18 ms is sufficient for real-time gaming, and the five-stage formula chain provides a complete audit trail for every placement. For any AI decision system that needs to explain "why," this "scoring → normalization → selection → confidence → audit" pattern is worth referencing.