docs/DEPLOYMENT.md

Development and deployment

Local run

Python 3.13 is used by the hosted Space and CI.

git clone https://github.com/Wuhpondiscord/bbcollect.git
cd bbcollect
python -m venv .venv

Activate .venv (.venv\Scripts\Activate.ps1 in PowerShell; source .venv/bin/activate on macOS/Linux), then:

pip install -r requirements.txt
python -m unittest discover -s tests -v
python app.py

Gradio: http://localhost:7860 · REST: http://localhost:7860/api/v1 · Docs: http://localhost:7860/api/docs.

app.py mounts Gradio at / on the FastAPI application after registering REST routes, then starts Uvicorn. Keep the REST route registration before the root mount. No platform tokens or runtime secrets are needed. Set PORT to change port 7860.

Hugging Face Space

The README.md front matter configures the Gradio Space with Python 3.13, Gradio 6.31.0, and app_file: app.py. Keep the Space public for anonymous access. Use CPU Basic unless your own load requires more resources; the app does not run a model.

GitHub Actions tests every push and pull request. Successful pushes to main and manual workflow dispatches upload application files to the existing wuhp/bbconnectapi Space. scripts/deploy.py explicitly selects app modules, docs, and examples; it never uploads secrets, .git, virtual environments, or tests, and does not mirror-delete unrelated Space files.

The GitHub Actions repository secret HF_TOKEN needs write access to the destination Space. This secret is only for publishing. API callers do not need it, and the running application does not read it. For a fork, change repo_id in scripts/deploy.py, add your own deployment secret, and update the public URLs in docs/examples.

Public hosting behavior

• REST and Gradio are deliberately unauthenticated. Browser CORS allows public GET/POST calls without credentials.
• A per-process capacity gate permits two concurrent REST collection requests; busy callers get 429 with Retry-After: 5. Health/source descriptions stay lightweight.
• Source cache is process-local: 900 seconds for successes, 60 for failures. Multiple processes have independent caches/capacity gates. Use one Uvicorn process on the free Space.
• Free Spaces can sleep/restart. Long live scope requests may exceed a client's default timeout; start with small pages and allow a larger timeout. Summary discovery plus selected batch details is usually faster.
• There is no persistent storage, scheduled refresh, force-refresh bypass, service-level agreement, or API-key subscription mechanism.

Release checklist

1. Run the test suite and verify generated OpenAPI schemas.
2. Keep the five-input Gradio /collect contract and six-input /collect_options contract intact.
3. Test /api/v1/health, /api/docs, a summary page, a detail document, normalized assets, and a mixed batch.
4. Confirm the Gradio UI and its event API still work after mounting.
5. Check ok, partial, and source states rather than treating missing rules as an empty policy.
6. Update the changelog, API reference, and examples for intentional behavior changes. Make breaking REST changes under a new versioned path.