HF_SPACES_DEPLOY.md

Hugging Face Spaces Deployment Checklist

Local Preflight

Run these from the repo root:

pip install -r requirements.txt
python -m pytest
python app.py

Open:

http://127.0.0.1:7860

Test a small repo first:

https://github.com/pallets/itsdangerous

Create The Space

1. Go to Hugging Face Spaces.
2. Create a new Space.
3. Choose SDK: Gradio.
4. Choose hardware: CPU basic for the mock MVP.
5. Use the AMD hackathon organization if the event requires it.

Required Files

These must be at the repo root:

app.py
requirements.txt
README.md

The README includes the Space metadata:

sdk: gradio
sdk_version: 6.14.0
app_file: app.py

Environment Variables

For the public mock demo:

LLM_PROVIDER=mock

For a later AMD/vLLM deployment:

LLM_PROVIDER=vllm
LLM_BASE_URL=http://YOUR_VLLM_ENDPOINT/v1
LLM_API_KEY=not-needed-if-your-endpoint-does-not-require-one
LLM_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct

First Hosted Smoke Test

In the deployed Space, test:

https://github.com/pallets/itsdangerous

Then test:

https://github.com/psf/requests

Expected behavior:

• Crawler maps files.
• Chunker creates chunks.
• Security, Performance, Quality, and Docs agents run.
• Synthesizer returns a report.
• Report shows a prioritized subset while preserving total finding counts.

If The Space Fails

Check the Space logs first. Common issues:

• Dependency install failure: verify requirements.txt.
• App import failure: verify root app.py.
• GitHub clone failure: verify Space has outbound internet access.
• Large repo timeout: test pallets/itsdangerous before larger repos.