Agent.md

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:

    {
      "prompt": "The old clock struck midnight as Elena entered the library...",
      "maxLength": 100
    }
    

  • Response Example:

    {
      "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:

    {
      "genre": "Sci-Fi",
      "topic": "First contact with an ancient artifact"
    }
    

  • Response Example:

    {
      "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:

    {
      "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):

   from huggingface_hub import HfApi
   api = HfApi(token=token)
   # Reset space repo if file limit exceeded
   

2. Upload Codebase:

   hf upload Leon4gr45/Velo . --repo-type=space --exclude "node_modules/*" --exclude "dist/*" --exclude ".git/*"
   

3. Stream Build and Run Logs:

   • Build logs (SSE):

     curl -N -H "Authorization: Bearer <TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/Velo/logs/build"
     

   • Run logs (SSE):

     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.