Leon4gr45/builder

1# Hugging Face Space Deployment Guidelines & Best Practices2 3## 1. Deployment Configuration4 5### Target Space6- **Profile:** `Leon4gr45`7- **Space:** `builder`8- **Full Identifier:** `Leon4gr45/builder`9- **Frontend Port:** `7860` (mandatory for all Hugging Face Spaces)10 11### Deployment Method12We use the **Docker SDK** for flexibility, utilizing a standard `Dockerfile` configured to run Next.js standalone on port `7860`.13 14### HF Token15- The environment variable **`HF_TOKEN` will always be provided at execution time**.16- Never hardcode the token. Always read it from the environment.17- All monitoring and log-streaming commands rely on `$HF_TOKEN`.18 19### Required Files20- `Dockerfile` (binds the app to port `7860`)21- `README.md` (includes Hugging Face YAML frontmatter)22- `.hfignore` (excludes unnecessary files to prevent repository limit issues)23- `Agent.md` (this file, detailing current practices)24 25---26 27## 2. API Exposure and Documentation28 29### Mandatory Endpoints30The following endpoints must be accessible publicly without any redirection/authentication block (configured in Next.js middleware):31 32- **`/health`**33  - **Method:** GET34  - **Purpose:** Health check returning HTTP 200 once Next.js server is ready. Necessary for Hugging Face to transition the Space status to *running*.35  - **Request Example:** None (GET request)36  - **Response Example:**37    ```json38    {39      "ok": true,40      "name": "osw-studio",41      "version": "1.84.0",42      "mode": "browser",43      "timestamp": "2026-07-16T12:00:00.000Z"44    }45    ```46 47- **`/api-docs`**48  - **Method:** GET49  - **Purpose:** Serve documentation of all available API endpoints. Reachable at `https://Leon4gr45-builder.hf.space/api-docs`50  - **Request Example:** None (GET request)51  - **Response Example:**52    ```json53    {54      "name": "OSW Studio API Documentation",55      "version": "1.84.0",56      "description": "API endpoints documentation...",57      "endpoints": [...]58    }59    ```60 61### Functional Endpoints62 63- **`/api/models`**64  - **Method:** GET65  - **Purpose:** List available AI models across supported providers.66  - **Request Example:** GET `/api/models`67  - **Response Example:** `{"models": [...]}`68 69- **`/api/validate-key`**70  - **Method:** POST71  - **Purpose:** Validate provider API key.72  - **Request Example:** `{"provider": "openrouter", "apiKey": "sk-..."}`73  - **Response Example:** `{"valid": true}`74 75- **`/api/generate`**76  - **Method:** POST77  - **Purpose:** Generate web code or site response via AI model.78  - **Request Example:** `{"prompt": "Create landing page", "provider": "openrouter", "model": "..."}`79  - **Response Example:** `{"result": "..."}`80 81- **`/api/generate-image`**82  - **Method:** POST83  - **Purpose:** Generate image assets using AI image generation service.84  - **Request Example:** `{"prompt": "Logo design"}`85  - **Response Example:** `{"url": "..."}`86 87- **`/api/web/search`**88  - **Method:** POST89  - **Purpose:** Perform web search for context retrieval.90  - **Request Example:** `{"query": "Next.js 15 features"}`91  - **Response Example:** `{"results": [...]}`92 93- **`/api/web/fetch`**94  - **Method:** POST95  - **Purpose:** Fetch web content from external URL.96  - **Request Example:** `{"url": "https://example.com"}`97  - **Response Example:** `{"content": "..."}`98 99---100 101## 3. Deployment Workflow & Troubleshooting102 103### Standard Deployment Command104Check that space is empty or clean, then run:105 106```bash107hf upload Leon4gr45/builder . --repo-type=space --token=$HF_TOKEN108```109 110### Log Monitoring111Scan build and run logs using curl with Bearer token:112 113```bash114# Build logs115curl -N -H "Authorization: Bearer $HF_TOKEN" "https://huggingface.co/api/spaces/Leon4gr45/builder/logs/build"116 117# Run logs (once build succeeds)118curl -N -H "Authorization: Bearer $HF_TOKEN" "https://huggingface.co/api/spaces/Leon4gr45/builder/logs/run"119```120 121Monitor for 300 seconds to verify deployment success. If any logs indicate failure, fix issues in codebase, redeploy, and monitor in a cycle.122 123### Exclusions & Size Limits124- Set up `.hfignore` to ignore large local directories such as `node_modules/*`, `.next/*`, `.git/*`.125 126### Middleware Matcher Exclusion127- Next.js matcher in `middleware.ts` must explicitly allow `/health` and `/api-docs` so Hugging Face load balancers can reach them without running into authentication loops or redirects.128