| # Agent Deployment Guide & Best Practices for Hugging Face Space |
|
|
| This codebase is configured for deployment on **Hugging Face Spaces**. |
|
|
| ## 1. Deployment Configuration |
|
|
| ### Target Space |
| - **Profile:** `Leon4gr45` |
| - **Space:** `Velo` |
| - **Full Identifier:** `Leon4gr45/Velo` |
| - **Frontend Port:** `7860` (mandatory for Hugging Face Spaces) |
|
|
| ### Deployment Method |
| - **Docker SDK** — The application is built using a multi-stage Dockerfile (`Dockerfile`), building Vite static assets and serving them via Node.js / Express (`server.js`) on port 7860. |
|
|
| ### HF Token |
| - Always read the token from environment variable `HF_TOKEN`. |
| - Never hardcode secret tokens in tracked files. |
|
|
| ### Required Files |
| - `Dockerfile`: Multi-stage build for web application assets and Express runner. |
| - `server.js`: Web server serving static assets and API routes. |
| - `README.md`: Includes Hugging Face Space YAML frontmatter: |
| ```yaml |
| --- |
| title: Velo |
| sdk: docker |
| app_port: 7860 |
| --- |
| ``` |
| - `.hfignore`: Excludes `node_modules`, `.git`, build output artifacts, and logs from uploads. |
| - `Agent.md`: This deployment documentation. |
|
|
| --- |
|
|
| ## 2. API Exposure and Documentation |
|
|
| ### Mandatory Endpoints |
|
|
| - **`/health`** |
| - Method: `GET` |
| - Purpose: Liveness & readiness check for Hugging Face Spaces. |
| - Returns: `{ "status": "ok", "service": "Velo" }` with HTTP 200. |
|
|
| - **`/api-docs`** |
| - Method: `GET` |
| - Purpose: Documents all available API endpoints. |
| - Reachable at: `https://Leon4gr45-Velo.hf.space/api-docs` |
|
|
| ### Functional Endpoints |
|
|
| - **`/predict`** |
| - Method: `POST` |
| - Purpose: Story continuation and text prediction. |
| - Request Example: |
| ```json |
| { |
| "prompt": "The old clock struck midnight as Elena entered the library...", |
| "maxLength": 100 |
| } |
| ``` |
| - Response Example: |
| ```json |
| { |
| "continuation": "A faint blue light gleamed from behind the bookshelf...", |
| "status": "success" |
| } |
| ``` |
| |
| - **`/generate`** |
| - Method: `POST` |
| - Purpose: Generate narrative outlines and creative writing structures. |
| - Request Example: |
| ```json |
| { |
| "genre": "Sci-Fi", |
| "topic": "First contact with an ancient artifact" |
| } |
| ``` |
| - Response Example: |
| ```json |
| { |
| "genre": "Sci-Fi", |
| "topic": "First contact with an ancient artifact", |
| "outline": "Chapter 1: Discovery in the Kuiper Belt...", |
| "status": "success" |
| } |
| ``` |
| |
| ### OpenAI-Compatible Endpoints with Custom URL |
|
|
| - **`/v1/models`** |
| - Method: `GET` |
| - Purpose: List available models. |
|
|
| - **`/v1/chat/completions`** |
| - Method: `POST` |
| - Purpose: Chat completion interface matching the OpenAI API format. |
| - Custom URL Support: Accepts `custom_url` or `base_url` parameter in body or `X-Custom-Url` header to forward requests to custom upstream OpenAI-compatible endpoints. |
| - Request Example: |
| ```json |
| { |
| "model": "velo-default", |
| "messages": [ |
| { "role": "user", "content": "Write a short scene." } |
| ], |
| "custom_url": "https://api.openai.com/v1" |
| } |
| ``` |
| |
| --- |
|
|
| ## 3. Deployment Workflow & Tricks |
|
|
| 1. **Clean Hugging Face Repo (Precondition):** |
| ```python |
| from huggingface_hub import HfApi |
| api = HfApi(token=token) |
| # Reset space repo if file limit exceeded |
| ``` |
|
|
| 2. **Upload Codebase:** |
| ```bash |
| hf upload Leon4gr45/Velo . --repo-type=space --exclude "node_modules/*" --exclude "dist/*" --exclude ".git/*" |
| ``` |
|
|
| 3. **Stream Build and Run Logs:** |
| - Build logs (SSE): |
| ```bash |
| curl -N -H "Authorization: Bearer <TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/Velo/logs/build" |
| ``` |
| - Run logs (SSE): |
| ```bash |
| curl -N -H "Authorization: Bearer <TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/Velo/logs/run" |
| ``` |
| |
| 4. **Verify Health & OpenAI Endpoints:** |
| - Query `https://Leon4gr45-Velo.hf.space/health` and `https://Leon4gr45-Velo.hf.space/v1/chat/completions`. |
|
|
