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:

# 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:

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:

# 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:

# 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:

• Dockerfile - ✓ Present and valid
• openenv.yaml - ✓ Complete specification
• requirements.txt - ✓ All dependencies listed
• inference.py - ✓ Mandatory format compliant
• environment/ - ✓ Full implementation
• app.py - ✓ Flask API ready
• 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! ✓