hf_space_deploy.md

Deploying Deceit to Hugging Face Spaces

Prerequisites

• Hugging Face account with write token (huggingface-cli login)
• OPENAI_API_KEY available (needed for grader semantic fallback at runtime)
• openenv-core installed in your environment (already in pyproject.toml)

Primary Method: openenv push

From the project root (where openenv.yaml lives):

# Authenticate first (one-time)
huggingface-cli login

# Push — replace with your actual HF username
python -m openenv.cli push --repo-id <your-hf-username>/deceit-env

This will:

1. Validate the OpenEnv directory structure
2. Create the HF Space (Docker SDK) if it doesn't exist
3. Stage and upload all project files
4. Inject ENV ENABLE_WEB_INTERFACE=true into the Dockerfile for the HF web UI
5. Print the live Space URL when done

Set the OpenAI API key as a Space secret (do NOT hardcode it):

# Via HF CLI
huggingface-cli repo secret set OPENAI_API_KEY --repo-type space \
    --repo-id <your-hf-username>/deceit-env

Or via the HF web UI: Space → Settings → Variables and secrets → New secret → OPENAI_API_KEY.

Verifying the Deployed Space

Once the Space build completes (~3–5 min cold start), verify it responds:

# Health check
curl https://<your-hf-username>-deceit-env.hf.space/health

# Reset (start episode)
curl -X POST https://<your-hf-username>-deceit-env.hf.space/reset \
    -H "Content-Type: application/json" -d '{}'

# Step (submit action)
curl -X POST https://<your-hf-username>-deceit-env.hf.space/step \
    -H "Content-Type: application/json" \
    -d '{"reasoning":"Thinking...","answer":"Canberra","confidence":0.9,"is_final":true}'

Or via the OpenEnv Python client:

from client import DeceitEnv
from deceit_env.models import DeceitAction

with DeceitEnv(base_url="https://<your-hf-username>-deceit-env.hf.space") as env:
    result = env.reset()
    print(result.observation.question)
    result = env.step(DeceitAction(
        reasoning="Canberra is the capital of Australia.",
        answer="Canberra",
        confidence=0.9,
        is_final=True,
    ))
    print(f"Reward: {result.reward}")

Manual Fallback (if openenv push fails)

1. Create a Docker SDK Space at huggingface.co/new-space (SDK: Docker, port: 8000)
2. Clone the Space repo: git clone https://huggingface.co/spaces/<user>/deceit-env
3. Copy project files into the cloned repo

4. Add HF frontmatter to README.md: ```yaml

   title: Deceit Env sdk: docker app_port: 8000

5. Commit and push: git add -A && git commit -m "deploy" && git push

Troubleshooting

Symptom	Fix
Build fails with pip install -e . error	Check that pyproject.toml is at repo root and all src/ files are present
/health returns 502	Space is still building — wait 2–3 min and retry
/step returns 500 with "OpenAI key" error	Secret OPENAI_API_KEY not injected — add via Space Settings
Cold start timeout (>30s first request)	Normal for HF free tier — first request starts the container
ENABLE_WEB_INTERFACE causes 404 on /web	Expected if web interface assets aren't bundled — use /health, /reset, /step directly

Environment Variables

Variable	Default	Purpose
OPENAI_API_KEY	(required for semantic grading)	GPT-4o-mini fallback grader
DECEIT_GRADER_CACHE	/tmp/deceit_grader_cache.json	Disk cache for grader results
ENABLE_WEB_INTERFACE	true (set by openenv push)	OpenEnv web UI

Updating the Deployed Space

Re-run openenv push from the project root — it uploads only changed files. The Space rebuilds automatically.