DEV Community

logout2login
logout2login

Posted on

Formula-Traceable AI: The Aether Decision Engine (ADE) for Tetris

#ai #algorithms #architecture #gamedev

Formula-Traceable AI: The Aether Decision Engine (ADE) for Tetris

Every AI decision should explain why

When an AI plays Tetris, it makes thousands of piece-placement decisions per minute. Most implementations just output a move — no explanation, no reasoning trail, no way to audit why that placement was chosen.

ADE (Aether Decision Engine) changes this. Every decision goes through a formula-traceable pipeline:

option_scoring → softmax → argmax → margin → rules
Enter fullscreen mode Exit fullscreen mode

Each step produces an auditable record. You can trace any single move back through the entire formula chain to understand exactly why the AI chose that placement.

This article covers the architecture, the verified benchmark results, and how formula-traceability applies beyond Tetris.

The Problem: Opaque AI Decisions

Consider a standard Tetris AI:

# Standard approach — opaque
def choose_placement(piece, board):
    placements = get_valid_placements()
    scores = [score(p, board) for p in placements]
    return max(placements, key=lambda p: scores[p])
# Output: "Place piece at column 7, rotation 3"
# That's it. No reasoning, no confidence, no audit trail.
Enter fullscreen mode Exit fullscreen mode

ADE wraps this in a decision framework that records:

@dataclass
class ADEDecision:
    piece_type: str           # "J", "I", "T", etc.
    rotation: int             # 0-3
    column: int               # 0-9
    confidence: float         # 0.0 - 1.0
    margin: float             # gap between top-1 and top-2 scores
    probability: float        # softmax probability of chosen option
    formula_chain: List[str]  # ["option_scoring", "softmax", "argmax", "margin"]
    rules_fired: List[str]    # ["avoid_holes", "prefer_wellness"]
    audit_trail: List[Dict]   # full decision trace
    decision_id: str          # unique identifier
    latency_ms: float         # computation time
    chosen_score: float       # raw heuristic score
Enter fullscreen mode Exit fullscreen mode

Architecture: The Formula Chain

ADE's decision pipeline has five stages:

1. Option Scoring

Each valid placement is scored using Tetris heuristics:

for p in placements:
    p["score"] = TetrisGame.score_placement(p["features"], p["lines_cleared"])
Enter fullscreen mode Exit fullscreen mode

Features include: max_height, holes, aggregate_height, wellness.

2. Softmax Normalization

Raw scores are converted to probabilities via temperature-controlled softmax:

# Temperature controls exploration vs exploitation
# Lower temp → more deterministic, higher temp → more exploratory
weights = softmax(scores, temperature=0.5)
Enter fullscreen mode Exit fullscreen mode

3. Argmax Selection

The best option is selected:

best_index = argmax(weights)
Enter fullscreen mode Exit fullscreen mode

4. Margin Calculation

The confidence is measured by the gap between the top-2 scores:

margin = weights[best] - weights[second_best]
# Margin = 1.0 means the best option is overwhelmingly better
# Margin ≈ 0 means it's a close call between multiple options
Enter fullscreen mode Exit fullscreen mode

5. Rule Evaluation

Rules fire based on margin thresholds and board state:

  • Margin gate — if margin < threshold, flag as uncertain
  • Safety — reject placements that create holes or exceed height limit
  • Stability — prefer placements that create flat surfaces

Verified Benchmark Results

Here's the actual self-test output from running ade_agent.py:

============================================================
ADE AGENT SELF-TEST
============================================================
[OK] ADE available at C:\sycl_workspace\Ai_Brain - Copy
     Engine: <class 'new_version.ade.engine.AetherEngine'>
     Margin floor: 0.3

[INFO] Agent created: use_ade=True

Move 0: J -> R3 C7 | conf=0.078 | margin=0.002 | score=-274.0 | latency=0.24ms | rules=2
Move 1: I -> R3 C7 | conf=0.292 | margin=0.022 | score=-250.0 | latency=0.19ms | rules=2
Move 2: L -> R1 C6 | conf=0.574 | margin=0.148 | score=-226.0 | latency=0.19ms | rules=2
Move 3: T -> R1 C6 | conf=0.573 | margin=0.146 | score=-202.0 | latency=0.22ms | rules=2
Move 4: Z -> R1 C6 | conf=0.571 | margin=0.141 | score=-178.0 | latency=0.16ms | rules=2
Move 5: S -> R1 C6 | conf=0.570 | margin=0.140 | score=-154.0 | latency=0.29ms | rules=2
Move 6: O -> R0 C7 | conf=1.000 | margin=1.000 | score=-130.0 | latency=0.07ms | rules=1
Move 7: O -> R0 C7 | conf=1.000 | margin=1.000 | score=-106.0 | latency=0.07ms | rules=1
Move 8: J -> R1 C6 | conf=0.566 | margin=0.132 | score=-82.0   | latency=0.18ms | rules=2
Move 9: I -> R3 C3 | conf=0.107 | margin=0.015 | score=-198.0 | latency=0.16ms | rules=2

[BOARD EVAL] Quality: excellent (conf=0.148)

[STATS] Decisions: 10
        Avg confidence: 0.533
        Avg margin: 0.275
        Score: 0
        Lines: 0

[OK] ADE Agent self-test completed
Enter fullscreen mode Exit fullscreen mode

Key Metrics

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

The O pieces show confidence=1.0 and margin=1.0 — there's only one valid placement for an O piece at that board state, so the softmax produces a degenerate distribution. The J and I pieces show low confidence (0.078, 0.107) — multiple options are close in score, making it a genuinely hard decision.

Fallback Mode

ADE gracefully degrades when the full engine isn't available:

class ADEAgent:
    def __init__(self, temperature: float = 0.5, use_ade: bool = True):
        self.use_ade = use_ade and _ADE_AVAILABLE
        if self.use_ade:
            self.engine = _AetherEngine()
            self.engine.reset()
Enter fullscreen mode Exit fullscreen mode

If ADE isn't found (wrong paths, missing dependencies), the agent falls back to heuristic-only mode — same formula chain, same decision structure, but without the ADE engine's advanced scoring. The API surface is identical.

Integration with VPU

ADE integrates with the VPU (Vector Processing Unit) for high-dimensional parallel exploration:

# When ADE is uncertain (low margin), VPU can explore parallel paths
if decision.margin < 0.1:
    # Call VPU to explore multiple placement strategies
    vpu_result = vpu_parallel_reasoning(
        dim=256,
        steps=100,
        logic_complexity="medium"
    )
    # VPU returns entropy-based convergence metrics
    # Lower entropy = VPU converged on a strategy
Enter fullscreen mode Exit fullscreen mode

This creates a two-tier decision system:

  1. ADE — fast, deterministic, auditable (0.18 ms per decision)
  2. VPU — slow, parallel, exploratory (0.32 ms per step, 3000+ FPS)

Beyond Tetris

ADE's formula-traceable pattern applies to any decision-making system where you need to know why:

Autonomous Vehicles 

sensor_data → obstacle_detection → path_scoring → softmax → route_selection
                                    ↓
                              audit_trail (for regulatory compliance)
Enter fullscreen mode Exit fullscreen mode

Financial Trading 

market_data → signal_scoring → softmax → position_sizing → margin_check
                                    ↓
                              audit_trail (for regulatory compliance)
Enter fullscreen mode Exit fullscreen mode

Medical Diagnostics 

patient_data → test_results → diagnosis_scoring → softmax → treatment_selection
                                       ↓
                                 audit_trail (for malpractice insurance)
Enter fullscreen mode Exit fullscreen mode

The pattern is the same: score → normalize → select → measure confidence → audit.

Code Structure 

Ai_Brain/
├── ade_agent.py              # ADE agent (528 lines)
│   ├── ADEDecision           # Decision record dataclass
│   ├── BoardEvaluation       # Board quality assessment
│   └── ADEAgent              # Main decision agent
├── tetris_core.py            # Tetris engine (283 lines)
│   ├── TetrisGame            # Game logic
│   ├── Piece, Board          # Core data structures
│   └── score_placement()     # Heuristic scoring
└── daemon/new_version/ade/   # ADE engine (external dependency)
    ├── engine.py             # AetherEngine class
    └── types.py              # DecisionContext
Enter fullscreen mode Exit fullscreen mode

Build & Run 

# Self-test (includes Tetris engine)
python ade_agent.py

# Or integrate into your project
from ade_agent import ADEAgent, ADEDecision
from tetris_core import TetrisGame

game = TetrisGame(seed=42)
game.spawn_piece()
agent = ADEAgent(temperature=0.5)

for i in range(100):
    placements = game.get_valid_placements()
    decision = agent.decide_placement(game.current_piece, game.board, placements)

    # Access audit trail
    print(f"Decision {decision.decision_id}:")
    print(f"  Piece: {decision.piece_type} R{decision.rotation} C{decision.column}")
    print(f"  Confidence: {decision.confidence:.3f}")
    print(f"  Margin: {decision.margin:.3f}")
    print(f"  Formula chain: {' → '.join(decision.formula_chain)}")
    print(f"  Rules fired: {decision.rules_fired}")

    game.drop_piece(game.current_piece)
    game.spawn_piece()

agent.close()
Enter fullscreen mode Exit fullscreen mode

Conclusion

ADE proves that AI decisions can be both fast and auditable. At 0.18 ms per decision, it's fast enough for real-time gameplay. The formula chain (option_scoring → softmax → argmax → margin → rules) gives you a complete audit trail for every single move.

The key insight: audibility and performance are not in tension. You can have both.

MIT licensed. Code available at github.com/logout2login.

Top comments (0)