Spaces:
Running
Running
| title: Assembler | |
| emoji: 📚 | |
| colorFrom: blue | |
| colorTo: blue | |
| sdk: gradio | |
| sdk_version: 5.18.0 | |
| app_file: app.py | |
| pinned: false | |
| Here’s the Assembler Space API documentation rewritten in a Markdown code block, suitable for pasting into a Markdown file or passing to another LLM while preserving formatting. | |
| markdown | |
| # Assembler Space API Documentation | |
| ## Overview | |
| The **Assembler Space** is a Hugging Face Space that acts as a factory for creating new Hugging Face Spaces dynamically. It exposes a Flask-based API that accepts JSON input containing code, files, parameters, and configuration details. Upon receiving a valid request, it creates a new Space repository on Hugging Face, populates it with the provided files, and triggers its deployment. The API supports multiple Space types (e.g., `gradio`, `static`, `docker`, `streamlit`) and multi-file submissions, making it versatile for generating a wide range of applications. | |
| The Assembler Space itself runs as a Docker-based Space on Hugging Face, accessible via a public URL once deployed. | |
| ## Base URL | |
| The API is hosted at: | |
| https://<your-username>-assembler.hf.space/create-space | |
| Replace `<your-username>` with the Hugging Face username hosting the Assembler Space. The exact URL will be provided once the Space is deployed. | |
| ## Endpoint | |
| ### `POST /create-space` | |
| Creates a new Hugging Face Space based on the provided JSON payload. | |
| #### Request Format | |
| - **Method**: `POST` | |
| - **Content-Type**: `application/json` | |
| - **Body**: A JSON object with the following fields: | |
| | Field | Type | Required | Description | | |
| |--------------|----------|----------|-----------------------------------------------------------------------------| | |
| | `space_type` | String | No | The type of Space to create. Options: `gradio`, `static`, `docker`, `streamlit`. Defaults to `gradio` if omitted. | | |
| | `files` | Object | Yes | A dictionary where keys are filenames (e.g., `app.py`, `index.html`) and values are file contents as strings. | | |
| | `parameters` | Object | No | A dictionary of key-value pairs to be injected into Python files as `PARAMS` or used by the generated Space’s code. | | |
| #### Request Constraints | |
| - At least one file must be provided in `files`. | |
| - Filenames in `files` should include extensions (e.g., `.py`, `.html`, `.css`, `.txt`) to ensure correct handling. | |
| - `space_type` must match one of the supported values, or the request will fail. | |
| - File contents should be valid for the intended `space_type` (e.g., Python code for `gradio` or `docker`, HTML for `static`). | |
| #### Response Format | |
| - **Content-Type**: `application/json` | |
| - **Status Codes**: | |
| - `200 OK`: Space creation succeeded. | |
| - `400 Bad Request`: Invalid JSON or missing/invalid fields. | |
| - `500 Internal Server Error`: Unexpected error during Space creation. | |
| - **Body**: A JSON object with the following fields: | |
| | Field | Type | Description | | |
| |-----------|--------|-----------------------------------------------------------------------------| | |
| | `message` | String | A brief status message (e.g., `"New Space created"`). | | |
| | `url` | String | The URL of the newly created Space (e.g., `https://huggingface.co/spaces/<username>/<space-name>`). | | |
| | `note` | String | Additional information (e.g., deployment time warning). | | |
| | `error` | String | (Only in error responses) Description of what went wrong. | | |
| #### Example Requests and Responses | |
| ##### Example 1: Static Space | |
| **Request:** | |
| ```json | |
| { | |
| "space_type": "static", | |
| "files": { | |
| "index.html": "<html><body><h1>Hello World</h1><p>Message: {{params['message']}}</p></body></html>", | |
| "style.css": "h1 { color: green; }" | |
| }, | |
| "parameters": { | |
| "message": "Static Space Test" | |
| } | |
| } | |
| Response (200 OK): | |
| { | |
| "message": "New Space created", | |
| "url": "https://huggingface.co/spaces/your-username/GeneratedSpace-abc123", | |
| "note": "It may take a few minutes to build and deploy." | |
| } | |
| Notes: | |
| Static Spaces don’t automatically process parameters. The new Space’s code must handle them (e.g., via JavaScript or server-side templating if added). | |
| Example 2: Docker Space with Flask | |
| Request: | |
| json | |
| { | |
| "space_type": "docker", | |
| "files": { | |
| "app.py": "from flask import Flask\napp = Flask(__name__)\[email protected]('/')\ndef home():\n return f'Hello, {PARAMS['name']}'\nif __name__ == '__main__':\n app.run(host='0.0.0.0', port=7860)", | |
| "requirements.txt": "flask", | |
| "Dockerfile": "FROM python:3.10-slim\nWORKDIR /app\nCOPY . .\nRUN pip install -r requirements.txt\nEXPOSE 7860\nCMD [\"python\", \"app.py\"]" | |
| }, | |
| "parameters": { | |
| "name": "Docker User" | |
| } | |
| } | |
| Response (200 OK): | |
| json | |
| { | |
| "message": "New Space created", | |
| "url": "https://huggingface.co/spaces/your-username/GeneratedSpace-xyz789", | |
| "note": "It may take a few minutes to build and deploy." | |
| } | |
| Notes: | |
| The parameters are injected into app.py as PARAMS. The port is set to 7860 to match Hugging Face’s default. | |
| Example 3: Gradio Space | |
| Request: | |
| json | |
| { | |
| "space_type": "gradio", | |
| "files": { | |
| "app.py": "import gradio as gr\ndef greet():\n return f'Hi, {PARAMS['user']}'\ninterface = gr.Interface(fn=greet, inputs=None, outputs='text')\ninterface.launch()" | |
| }, | |
| "parameters": { | |
| "user": "Gradio Fan" | |
| } | |
| } | |
| Response (200 OK): | |
| json | |
| { | |
| "message": "New Space created", | |
| "url": "https://huggingface.co/spaces/your-username/GeneratedSpace-def456", | |
| "note": "It may take a few minutes to build and deploy." | |
| } | |
| Example 4: Invalid Request | |
| Request: | |
| json | |
| { | |
| "space_type": "invalid", | |
| "files": {} | |
| } | |
| Response (400 Bad Request): | |
| json | |
| { | |
| "error": "Invalid space_type. Must be one of ['gradio', 'static', 'docker', 'streamlit']" | |
| } | |
| Usage Example (Python) | |
| Here’s how to call the API using Python’s requests library: | |
| python | |
| import requests | |
| url = "https://your-username-assembler.hf.space/create-space" | |
| payload = { | |
| "space_type": "static", | |
| "files": { | |
| "index.html": "<html><body><h1>Test Page</h1></body></html>" | |
| }, | |
| "parameters": { | |
| "key": "value" | |
| } | |
| } | |
| headers = {"Content-Type": "application/json"} | |
| response = requests.post(url, json=payload) | |
| if response.status_code == 200: | |
| print("Success:", response.json()) | |
| else: | |
| print("Error:", response.status_code, response.json()) | |
| Additional Details | |
| Supported Space Types | |
| gradio: For interactive Python apps using the Gradio framework. Requires an app.py with Gradio code. | |
| static: For static websites. Requires at least an index.html file; supports additional files like style.css. | |
| docker: For custom apps (e.g., Flask, FastAPI). Requires a Dockerfile or uses a default one if omitted. | |
| streamlit: For Streamlit apps. Requires an app.py with Streamlit code. | |
| File Handling | |
| Python Files (.py): The parameters object is injected as a global PARAMS variable at the top of the file. | |
| Other Files: Contents are uploaded as-is; no automatic parameter injection (e.g., HTML files need custom logic to use parameters). | |
| Requirements: If requirements.txt isn’t provided, a default is generated based on space_type (e.g., gradio for Gradio, flask for Docker). | |
| Deployment Notes | |
| Build Time: New Spaces take 1-5 minutes to build and deploy on Hugging Face. The API returns immediately with a URL, but the Space won’t be live until the build completes. | |
| Port for Docker: Hugging Face expects Docker Spaces to listen on port 7860. Ensure your Dockerfile and app code align with this (see Example 2). | |
| Security Considerations | |
| The Assembler doesn’t execute the provided code; it only creates a new Space. However, ensure the generated Space’s code is safe if deploying publicly. | |
| Avoid sending sensitive data in parameters unless the new Space is private (not implemented here but can be adjusted). | |
| Limitations | |
| Rate Limits: Hugging Face may restrict frequent Space creation. Check their API documentation for quotas. | |
| File Size: Large files may fail to upload; keep contents reasonable (e.g., <1MB per file). | |
| Error Handling: Basic validation is included, but complex syntax checking isn’t performed. | |
| --- | |
| This Markdown code block preserves the structure and formatting, making it easy to share or render in a Markdown viewer. You can copy this directly into a `.md` file or pass it to another LLM for further processing. Let me know if you need any adjustments! |