---
title: Maze AI Competition
emoji: 🕹️
colorFrom: gray
colorTo: gray
sdk: gradio
pinned: false
license: mit
short_description: Enterprise AI benchmark for complex maze-solving.
sdk_version: 6.6.0
---

# 🧠 Maze AI Competition Suite

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Gradio](https://img.shields.io/badge/UI-Gradio-blue.svg)](https://gradio.app/)
[![Docker](https://img.shields.io/badge/Deployment-Docker-blue.svg)](https://www.docker.com/)

> **An Enterprise-Grade Benchmarking Platform for Algorithmic & AI Solvers**

The **Maze AI Competition Suite** is a robust, modular framework designed to rigorously test and compare maze-solving algorithms. From classical graph traversal methods (A*, BFS, DFS) to cutting-edge Reinforcement Learning agents, this platform provides standardized metrics, reproducible environments, and detailed visualization.

---

## 🏗️ Architecture

The system is built on a modular "Hexagonal" architecture to ensure separation of concerns and extensibility.

```mermaid
graph TD
    A[User Interface (Gradio)] --> B(Maze Controller)
    B --> C{Core Engine}
    C --> D[Maze Generator]
    C --> E[Solver Interface]
    E --> F[Classical Solvers]
    E --> G[AI Agents]
    C --> H[Metrics & Analytics]
```

### Key Components
-   **Core Engine**: Handles state management, validation, and standardized maze representation.
-   **Generator Module**: Implements diverse maze generation algorithms (Recursive Backtracker, Prim's, Wilson's) to create varied difficulty levels.
-   **Solver Interface**: An abstract base class that enforces a consistent API for all solvers, ensuring fair comparison.
-   **Metrics System**: Tracks execution time (ms), nodes expanded, path length, and memory consumption.

---

## 🚀 Features

-   **Interactive Dashboard**: Real-time visualization of maze generation and solving processes.
-   **Multi-Algorithm benchmark**: Compare multiple algorithms side-by-side on the same seed.
-   **Performance Profiling**: Detailed breakdowns of time vs. space complexity.
-   **Extensible Design**: new solvers can be added with just a few lines of code by inheriting from `BaseSolver`.

---

## 🛠️ Installation

### Local Development

1.  **Clone the repository**:
    ```bash
    git clone https://huggingface.co/spaces/NorthernTribe-Research/maze-ai.competition
    cd maze-ai.competition
    ```

2.  **Create a virtual environment**:
    ```bash
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```

3.  **Install dependencies**:
    ```bash
    pip install -r requirements.txt
    ```

4.  **Run the application**:
    ```bash
    python app.py
    ```

### Docker Deployment

```bash
docker build -t maze-ai-benchmark .
docker run -p 7860:7860 maze-ai-benchmark
```

---

## 🧩 Usage

### The "Playground" Mode
For visual debugging and demonstration. Select a generation algorithm, set the grid size, and choose a solver to watch it navigate the maze in real-time.

### The "Benchmark" Mode
For serious evaluation. Define a test suite (e.g., "Run A* and BFS on 50 100x100 mazes") and receive a statistical report on their relative performance.

---

## 🤝 Contributing

We welcome contributions! Please follow the `CONTRIBUTING.md` guidelines.
-   **New Solvers**: Add files to `maze_ai/solvers/` and inherit from `BaseSolver`.
-   **New Generators**: Add files to `maze_ai/core/generators/`.

---

**Developed by NorthernTribe Research**