# Sybil Address Prediction Example

This example demonstrates how to use the Competition Agent to solve the [Sybil Addresses Prediction competition](https://cryptopond.xyz/modelFactory/detail/2). It shows a complete end-to-end pipeline from data processing to submission.

**Note**: As LLMs (e.g., GPT-4o) are not deterministic, the results may vary from run to run. It might even generate wrong code which cannot be executed. A bug fixing agent is included but it is not guaranteed to fix all bugs. If any error occurs, please rerun the notebook/script. If you encounter any issues, please report them as [GitHub Issues](https://github.com/Pond-International/pond-agent/issues).


## Directory Structure

### Provided in Repository
```
sybil_address/
├── main.py              # Main script to run the competition agent
└── main.ipynb          # Step-by-step tutorial notebook
```

### Required User Setup
```
sybil_address/
└── .env                # OpenAI API configuration (create this file)
```

### Generated by Agent
```
.
├── overview.md         # Competition description (downloaded)
├── data_dictionary.xlsx # Dataset documentation (downloaded)
├── dataset/           # Competition datasets (downloaded)
├── output/            # Generated outputs
│   └── run_YYYYMMDD_HHMMSS/ # Timestamped run results
└── logs/             # Execution logs
```

## Getting Started

1. Set up your OpenAI API key in `.env`:
```env
OPENAI_API_KEY=your-api-key-here
```

2. Get the competition data:

   **Option 1: Automatic Download (Recommended)**
   - Simply provide the competition URL when creating the Competition Agent
   - The agent will automatically download:
     - Competition overview (`overview.md`)
     - Data dictionary (`data_dictionary.xlsx`)
     - Dataset files in the `dataset/` directory

   Example:
   ```python
   agent = CompetitionAgent(
       working_dir=".",
       competition_url="https://cryptopond.xyz/modelFactory/detail/2"
   )
   ```

   **Option 2: Manual Download**
   - Visit the [competition page](https://cryptopond.xyz/modelFactory/detail/2)
   - Copy text from Overview tab to `./overview.md`
   - Download data dictionary to `./data_dictionary.xlsx`
   - Download and unzip dataset files into `./dataset/`

   **Note**: If all required files (`overview.md`, `data_dictionary.xlsx`, and `dataset/`) already exist in your working directory, the agent will skip downloading even if `competition_url` is provided.

3. Run the example:

   **Option 1: Using Jupyter Notebook (Recommended for Learning)**
   - Open `main.ipynb` in Jupyter
   - Follow the step-by-step tutorial with detailed explanations
   - Execute cells one by one to understand each stage of the pipeline
   - Great for learning and experimenting with the agent

   **Option 2: Using Python Script (Recommended for Production)**
   - Run the script directly:
     ```bash
     python main.py
     ```
   - Executes the complete pipeline in one go
   - Ideal for production use or when you're familiar with the process
   - All outputs and logs will be generated automatically

## What to Expect

The agent will execute the following pipeline:
1. Download or verify competition data
2. Process and analyze the data
3. Engineer features
4. Build and train the model
5. Generate submission file

Check the `output/` directory for generated artifacts and the `logs/` directory for detailed execution logs.