Intelligent Hint System (Oracle)

The Intelligent Hint System, also referred to as the Oracle, is a core component of the Debug Arena platform designed to provide logical guidance to participants during debugging challenges. Instead of providing direct code fixes, the system delivers strategic hints that help teams identify syntactical or logical flaws while maintaining the competitive integrity of the event.

To ensure fairness, the system operates on a "penalty-for-knowledge" basis. Every hint requested by a team results in a predefined score penalty applied to that specific level's final calculation. This mechanism forces teams to balance the speed of progress against the preservation of their total score.

Sources: README.md:38-42, templates/arena.html:120-122

Architecture and Data Flow

The Hint System is implemented through a decoupled architecture involving a frontend UI component, a backend API endpoint, and a centralized level management configuration.

Frontend Interaction

The participant interacts with the system through a modal-based interface. When the "Get Hint" button is clicked, a custom modal appears to warn the user about the score penalty. Upon confirmation, a POST request is dispatched to the backend.

Backend Processing

The Flask backend validates the session and retrieves the specific hint associated with the current level. It simultaneously updates the user's session state to flag that a hint was consumed, which is later used by the scoring engine.

The following sequence diagram illustrates the request-response flow for acquiring a hint:

Hint Data Structure and Configuration

Hints are statically defined within the LEVELS dictionary. Each level entry contains the specific text of the hint and the associated penalty points.

Level Configuration Schema

Implementation Example

# levels/level_manager.py
LEVELS = {
    1: {
        "title": "The Missing Link",
        "hint": "Python requires balanced parentheses. Count the '(' and ')' in your print statement.",
        "penalty": 15,
        # ... other fields
    }
}

Sources: levels/level_manager.py:4-16, routes/arena_routes.py:98-100

Scoring and Penalty Integration

The hint system directly impacts the scoring logic located in the submission processing route. The final score for a level is calculated by taking the base points, subtracting a time-based penalty, and then applying the Oracle's penalty if a hint was used.

Scoring Logic Flow

1. Base Calculation: Start with 100 points.
2. Time Penalty: Subtract 1 point for every 10 seconds elapsed.
3. Hint Check: Check the session for hint_used_level_<id>.
4. Final Deduction: Subtract level.penalty from the current subtotal.
5. Hard Minimum: Ensure the score does not fall below 30 points.

API Endpoint Details

The system relies on a single secure endpoint to manage hint delivery.

POST /get_hint/<int:level_id>

This endpoint handles the retrieval and state-tracking of hint usage.

• Authentication: Requires a valid team_id in the session.
• Request Parameters: level_id (URL Path).
• Session Impact: Sets a dynamic key hint_used_level_<level_id> to True.
• Response:

  {
    "success": true,
    "hint": "Logical guidance text here",
    "penalty": 15
  }
  

Sources: routes/arena_routes.py:84-101, routes/submit_routes.py:56-58

Conclusion

The Intelligent Hint System (Oracle) serves as a critical balancing tool within the Debug Arena. By providing structured logical guidance through a penalty-weighted mechanism, it ensures that teams can overcome technical blocks without trivializing the difficulty of the levels. The integration between frontend modals, session tracking, and the backend scoring engine maintains a consistent and competitive user experience.

Sources: README.md:38-42, templates/arena.html:43-56