# Development and deployment

## Local run

Python 3.13 is used by the hosted Space and CI.

```bash
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:

```bash
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.