---
title: HackBuddyAI
emoji: 🧑‍🤝‍🧑
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
license: apache-2.0
short_description: Instantly match hackathon participants into ideal teams!
---

# 🤖 AI-Powered HackBuddyAI

This project is a web application that helps hackathon organizers automatically form balanced teams from a list of participants. It uses a `TinyCodeAgent` to analyze participant skills and goals, creating optimal teams based on criteria defined by the organizer.

The application features a two-tab interface:
1.  **Participant Registration**: A form for participants to submit their profile, including skills, background, and what they want to achieve during the hackathon.
2.  **Organizer Dashboard**: A view for the organizer to see all registered participants, define matching criteria, and run the AI-powered team formation process.

## Tech Stack
-   **Backend**: Python
-   **AI Agent Framework**: `TinyCodeAgent`
-   **Web UI**: Gradio
-   **Data Handling**: Pandas
-   **Database**: SQLite

---

## Setup and Installation

### 1. Prerequisites
-   Python 3.8+
-   An OpenAI API key

### 2. Installation
1.  **Clone the repository** (if applicable) or ensure you have the project files in a directory.

2.  **Navigate to the project directory**:
    ```bash
    cd path/to/project
    ```

3.  **Create a virtual environment** (recommended):
    ```bash
    python -m venv venv
    source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
    ```

4.  **Install dependencies**:
    The project relies on the `tinyagent` library. Assuming it is available in your environment, install the other required packages:
    ```bash
    pip install -r hackathon_organizer/requirements.txt
    ```

### 3. Configure Environment Variables
You must set your OpenAI API key as an environment variable. The application will not run without it.

-   **On macOS/Linux**:
    ```bash
    export OPENAI_API_KEY="your_api_key_here"
    ```
-   **On Windows (Command Prompt)**:
    ```bash
    set OPENAI_API_KEY="your_api_key_here"
    ```

---

## 🚀 Running the Application

Once the setup is complete, you can launch the Gradio web application using one of the following methods:

### Method 1: Using the main script (recommended)

```bash
python main.py
```

This script handles all the necessary path configurations and launches the application.

### Method 2: Running app.py directly

```bash
cd hackathon_organizer
python app.py
```

Either method will start a local web server, and you can access the application at the URL provided in the console (usually `http://127.0.0.1:7860`).

The application will create a `hackathon_participants.db` file in the working directory to store the participant data.

---

## 🧪 Running Tests

The project includes unit tests for the database and the agent setup logic. The tests are located in the `tests/` directory.

To run the tests:

```bash
# From the project root directory
cd hackathon_organizer
python -m unittest discover tests
```

The tests are designed to run without needing an active internet connection or a valid API key. They use mocks to simulate agent behavior and an in-memory database for testing database operations.