SUBMISSION_CHECKLIST.md

CiteGuardian Submission Checklist

✅ Docker Build Creation

• Dockerfile exists in repo root
• Builds successfully: docker build -t openenv-citeguardian .
• Base image: ghcr.io/meta-pytorch/openenv-base:latest
• Exposes port 8000
• Health check configured
• CMD runs FastAPI server

Test: docker build -t openenv-citeguardian .

---

✅ inference.py Execution

• Emits [START] before any operations
• Emits [STEP] for each action
• Emits [END] always (even on failure)
• Handles ENV_URL (direct server connection)
• Handles LOCAL_IMAGE_NAME (Docker image fallback)
• Catches all exceptions and prints traceback
• Never exits without printing [END]

Test: ENV_URL=http://localhost:8000 uv run python inference.py

---

✅ Output Parsing

• [START] format: [START] task=<task> env=<env> model=<model>
• [STEP] format: [STEP] step=<n> action=<json> reward=<0.00> done=<true|false> error=<msg|null>
• [END] format: [END] success=<true|false> steps=<n> score=<0.000> rewards=<r1,r2,...>
• Rewards formatted to 2 decimal places
• Score formatted to 3 decimal places
• done and success are lowercase booleans
• No newlines within a single log line

Verify: Check inference.py log functions match exact format

---

✅ Task Validation

• Environment implements 3 task levels (A, B, C)
• Task A: Structural error (missing Results section)
• Task B: Citation orphans (2 errors)
• Task C: Logical inconsistency (100 vs 85 subjects)
• Rewards are cumulative and clamped to [0, 1]
• Perfect run (100% recall, 0 false positives) = 1.0
• reset() randomly selects a task
• observation.task_level returns 'A', 'B', or 'C'

Test: Run environment locally and verify all 3 tasks work

---

✅ LLM Criteria Check

• System prompt includes all 5 tools
• System prompt has task-specific strategies
• Agent uses GO_TO to navigate sections
• Agent uses SCAN_CITATIONS to find markers
• Agent uses COMPARE_VALUES for numeric checks
• Agent uses FLAG_ERROR with correct error_type
• Agent uses SUBMIT to end audit
• LLM responses are parsed as JSON
• Fallback action on parse failure (SUBMIT)

Test: Run full inference loop and verify agent completes audit

---

🔧 Pre-Submission Commands

# 1. Build Docker image
docker build -t openenv-citeguardian .

# 2. Run prevalidation (local checks)
uv run python prevalidation.py https://zrypton-citeguardian.hf.space .

# 3. Test inference locally
ENV_URL=https://zrypton-citeguardian.hf.space uv run python inference.py

# 4. Validate with openenv CLI
uv run openenv validate

# 5. Push to HF Space
openenv push --repo-id zrypton/citeGuardian

---

📋 Required Files

• openenv.yaml - OpenEnv manifest
• pyproject.toml - Project metadata
• Dockerfile - Container definition
• models.py - Action & Observation models
• client.py - CiteguardianEnv client
• inference.py - LLM agent loop
• server/app.py - FastAPI application
• server/citeGuardian_environment.py - RL environment
• README.md - Documentation
• .gitignore - Excludes .env, pycache, etc.

---

🚨 Common Failure Points

Docker Build

• ❌ Missing dependencies in pyproject.toml
• ✅ All deps listed: openenv-core[core], openai, python-dotenv

inference.py

• ❌ Crashes before [START] is printed
• ✅ log_start() called immediately in main()
• ❌ Missing [END] on exception
• ✅ log_end() in finally block

Output Format

• ❌ Extra newlines in action JSON
• ✅ action.model_dump_json(exclude_none=True) on single line
• ❌ Wrong decimal precision
• ✅ reward:.2f, score:.3f

Environment

• ❌ Observation missing required fields
• ✅ All fields: current_view, metadata, audit_log, tool_result, message, task_level, reward, done
• ❌ Reward not in [0, 1]
• ✅ Clamped: min(max(score, 0.0), 1.0)

---

✅ Final Verification

Run this command to verify everything:

# Full validation pipeline
docker build -t openenv-citeguardian . && \
uv run openenv validate && \
ENV_URL=https://zrypton-citeguardian.hf.space uv run python inference.py

If all three succeed, you're ready to submit.