VALIDATION_GUIDE.md

# Pre-Submission Validation Guide

## Before You Submit

Run the official pre-validation script to ensure your submission passes all checks.

## Prerequisites

Install required tools:

```bash
# Docker (if not already installed)
# https://docs.docker.com/get-docker/

# openenv-core
pip install openenv-core

# curl (usually pre-installed)
```

## Step 1: Deploy to HF Spaces

Before running validation, your Space must be live at a URL like:

```
https://{username}-email-triage.hf.space
```

### Deploy Steps:

```bash
cd d:/Projects/meta-hackathon

# Initialize git
git init
git add .
git commit -m "Initial Email Triage OpenEnv"

# Push to HF Space
git push https://huggingface.co/spaces/{USERNAME}/email-triage main
```

Wait 5-10 minutes for Docker build to complete.

## Step 2: Test Manually (Quick Check)

Before running full validation, do a quick manual test:

```bash
# Test /health endpoint
curl https://{username}-email-triage.hf.space/health

# Should return: {"status":"ok"}

# Test /reset endpoint
curl -X POST https://{username}-email-triage.hf.space/reset

# Should return observation JSON
```

## Step 3: Run Official Validator

Once your Space is live:

```bash
# Option A: Run validator directly
chmod +x validate-submission.sh
./validate-submission.sh https://{username}-email-triage.hf.space d:/Projects/meta-hackathon

# Option B: Download and run
curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/main/scripts/validate-submission.sh | \
  bash -s -- https://{username}-email-triage.hf.space d:/Projects/meta-hackathon
```

Replace:

- `{username}` with your HuggingFace username
- `<owner>/<repo>` with the official hackathon repo

## What the Validator Checks

### Check 1: HF Space Live

- Pings `https://{url}/reset` endpoint
- Expects HTTP 200 response
- Verifies Space is running

### Check 2: Docker Build

- Runs `docker build` on your Dockerfile
- Timeout: 600 seconds (10 minutes)
- Ensures containerization works locally

### Check 3: openenv validate

- Runs official `openenv validate` command
- Checks openenv.yaml format
- Validates specification compliance

## Expected Validator Output

```
========================================
  OpenEnv Submission Validator
========================================
[HH:MM:SS] Repo:     d:/Projects/meta-hackathon
[HH:MM:SS] Ping URL: https://username-email-triage.hf.space

[HH:MM:SS] Step 1/3: Pinging HF Space ...
[HH:MM:SS] PASSED -- HF Space is live and responds to /reset

[HH:MM:SS] Step 2/3: Running docker build ...
[HH:MM:SS] Found Dockerfile in d:/Projects/meta-hackathon
[HH:MM:SS] PASSED -- Docker build succeeded

[HH:MM:SS] Step 3/3: Running openenv validate ...
[HH:MM:SS] PASSED -- openenv validate passed

========================================
  All 3/3 checks passed!
  Your submission is ready to submit.
========================================
```

## Troubleshooting

### "HF Space not reachable"

- Wait 5-10 minutes for deployment to complete
- Check Space URL is correct
- Verify Space is public (not private)
- Test in browser: `https://{url}/health`

### "Docker build failed"

- Check Dockerfile syntax
- Verify all dependencies in requirements.txt
- Check file paths in Dockerfile
- Test locally: `docker build d:/Projects/meta-hackathon`

### "openenv validate failed"

- Check openenv.yaml format (valid YAML)
- Verify all required fields are present
- Check for syntax errors
- Run: `openenv validate d:/Projects/meta-hackathon`

## Your Project Status

File checklist for validator:

- [x] `Dockerfile` - ✓ Present and valid
- [x] `openenv.yaml` - ✓ Complete specification
- [x] `requirements.txt` - ✓ All dependencies listed
- [x] `inference.py` - ✓ Mandatory format compliant
- [x] `environment/` - ✓ Full implementation
- [x] `app.py` - ✓ Flask API ready
- [x] All endpoints working

## Quick Validation Checklist

Before submitting, verify:

```
[  ] HF Space URL is live and accessible
[  ] /health endpoint returns 200
[  ] /reset endpoint returns observation JSON
[  ] /step endpoint accepts POST with JSON action
[  ] Docker builds successfully locally
[  ] openenv validate passes
[  ] inference.py uses correct stdout format
[  ] All environment variables documented
[  ] README.md is complete
[  ] Score range is [0.0, 1.0]
```

## After Validation Passes

Once all 3 checks pass:

1. ✓ Your submission is ready
2. ✓ Submit your Space URL to the hackathon
3. ✓ Include any required metadata/links
4. ✓ Done!

## Support

If validator fails:

1. Check the error message
2. Review the "Troubleshooting" section above
3. Fix the issue in your code
4. Re-run validator
5. Repeat until all checks pass

## File Locations

For this project:

- **Dockerfile**: `d:/Projects/meta-hackathon/Dockerfile`
- **openenv.yaml**: `d:/Projects/meta-hackathon/openenv.yaml`
- **requirements.txt**: `d:/Projects/meta-hackathon/requirements.txt`
- **Validation runs from**: `d:/Projects/meta-hackathon`

All present and ready! ✓