README.md

metadata

title: HF Backend
emoji: ⚡
colorFrom: purple
colorTo: indigo
sdk: docker
app_port: 7860

HF Backend

FastAPI host running on a Hugging Face Docker Space. It mounts backend routers from separate project repositories under specific URL prefixes.

How it works

The host application does not define business logic. Each subproject lives in its own repository, exposes a router in <package>/router.py, and is installed as a Python package.

The host imports each router dynamically from registry.py and mounts it under a prefix. If an individual router fails to import, the host logs the error, records the failure, and keeps running for the other services.

/project-1/* -> HEARTFLOW_OS backend router
/project-2/* -> Semantic Comment Analyzer backend router
/health      -> Host health status

Adding a project

Adding a new service takes two steps:

1. Add the prefix and router path to registry.py:

PROJECT_REGISTRY = {
    "/project-1": "heartflow_backend.router:router",
    "/project-2": "semantic_backend.router:router",
    "/project-3": "new_project.router:router",
}

2. Add the pinned Git tag to requirements.txt:

git+https://github.com/<user>/<repo>.git@v1.0#subdirectory=backend

Pushing to main syncs the change to Hugging Face and rebuilds the Space container.

Configuration

Set these in the Space settings under Variables and secrets:

Variable	Required	Default	Notes
CORS_ALLOWED_ORIGINS	No	None	Comma-separated allowed origins. Wildcards (*) are ignored.
DISABLE_PROJECTS	No	None	Comma-separated prefixes to skip loading (e.g. project-2).
MAX_BODY_SIZE_BYTES	No	10485760 (10 MB)	Max request body size before returning 413.
REQUEST_TIMEOUT_SECONDS	No	60.0	Request timeout before returning 504.
GITHUB_TOKEN	Only for private repos	None	GitHub token passed as a build secret to clone private dependencies.

GitHub repository secrets (used by GitHub Actions):

Secret	Notes
HF_BACKEND_SPACE	Hugging Face write token used to push code and trigger Space restart.
HF_SPACE_URL	Optional. Health URL for the keep-alive workflow.

Endpoints

GET /health

Returns the status of the host and each registered project.

{
  "status": "healthy",
  "loaded": {
    "/project-1": "heartflow_backend.router:router",
    "/project-2": "semantic_backend.router:router"
  },
  "failed": {}
}

If any service fails to load, status changes to "degraded" or "unhealthy" and the error is listed under "failed".

Interactive documentation (/docs, /redoc, /openapi.json) is disabled.

Release workflow

1. Test changes in the project repository using its dev.py.
2. Tag the release (git tag v1.0, git push origin v1.0).
3. Update the tag in this repo's requirements.txt.
4. Push to main. The GitHub Actions workflow pushes to Hugging Face and restarts the Space.