Update README.md

README.md

@@ -7,4 +7,158 @@ sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Getting Started with the Jobs API
+
+The Jobs API allows users to execute scripts remotely. The key concept is simple: you write a script, host it in a dedicated space, and then any user can execute it as a job with their arguments. Let's walk through the setup step by step.
+
+## Creating a Space
+
+To begin, you'll need to create a space to host your script. Follow these steps:
+
+1. Visit [Hugging Face Spaces](https://huggingface.co/spaces).
+2. Click on `New Space`.
+3. Name your space (e.g., `run-hello-world`).
+4. Select `Docker` as the space type.
+5. Choose the `Blank` template.
+6. For hardware, select `CPU basic • 2vCPU • 16GB FREE` (note: this does not limit the resources used when running jobs).
+7. Set visibility to `Public`.
+
+Once created, your space will contain two default files: `README.md` and `.gitattributes`. To make it functional for running jobs, you need to add two more files: `Dockerfile` and `run_job.py`.
+
+### Setting Up the Environment
+
+The `Dockerfile` defines the environment in which your script will run. Below is the simplest version to get started:
+
+```dockerfile
+# Use a lightweight Python image as the base
+FROM python:3.11-slim
+
+# Set the working directory inside the container
+WORKDIR /app
+
+# Copy all files to the container
+COPY . /app
+```
+
+### Writing the Job Script
+
+The second required file is `run_job.py`, which contains the script you want to execute. To start, create a simple script that prints a message:
+
+```python
+print("Hello, world!")
+```
+
+At this stage, your space will display a `Runtime error`. This is expected since no application has been defined yet. However, this is not an issue as we don’t need one for job execution. You can add an application later if you want to provide a user-friendly interface for managing jobs.
+
+## Running a Job
+
+### Step 1: Create an API Token
+
+Before launching a job, you need to create a dedicated token for job execution. This token identifies the user requesting the job, ensures access permissions, and handles billing if necessary.
+
+1. Go to [Hugging Face Tokens](https://huggingface.co/settings/tokens).
+2. Click on `Create new token`.
+3. Give it a name of your choice.
+4. Select the permission `Start and manage Jobs on your behalf`.
+5. Click `Create token`.
+6. Copy the token and store it securely. Do not share it with anyone.
+
+### Step 2: Execute a Job
+
+Open a terminal and run the following command:
+
+```bash
+curl -L 'https://huggingface.co/api/jobs/<username>' \
+     -H 'Content-Type: application/json' \
+     -H 'Authorization: Bearer <token>' \
+     -d '{
+         "spaceId": "<space-id>",
+         "command": ["python", "<script-name>.py"],
+         "arguments": ["--arg1", "value1", "--arg2", "value2"],
+         "environment": {"ENV_VAR1": "value1", "ENV_VAR2": "value2"},
+         "flavor": "<flavor>"
+     }'
+```
+
+Let's break down the command:
+
+- `-L 'https://huggingface.co/api/jobs/<username>'`: API endpoint to launch a job. Replace `<username>` with your Hugging Face username.
+- `-H 'Authorization: Bearer <token>'`: The token you created earlier, used for authentication and permission verification.
+- `-d '{...}'`: The body of the request, containing job parameters:
+  - `spaceId`: The identifier of your space (e.g., `qgallouedec/run-hello-world`).
+  - `command`: The command to execute. Here, we run a Python script: `["python", "run_job.py"]`.
+  - `arguments`: Optional arguments for the script. If none are needed, use an empty array: `[]`.
+  - `environment`: Environment variables for the job. If none are needed, use `{}`.
+  - `flavor`: The type of machine to run the job on. Available options include `cpu-basic`, `cpu-upgrade`, `t4-small`, `t4-medium`, `a10g-small`, `a10g-large`, `a10g-largex2`, `a10glargex4`, `a100-large`, `h100`, `h100x8`, `l4x4`, `l4x1`, `l40sx1`, `l40sx4`, `l40sx8`.
+
+In my example, the command would look like this:
+
+```bash
+curl -L 'https://huggingface.co/api/jobs/qgallouedec' \
+     -H 'Content-Type: application/json' \
+     -H 'Authorization: Bearer hf_MyTokenIsSecret' \
+     -d '{
+        "spaceId": "qgallouedec/run-hello-world",
+        "command": ["python", "run_job.py"],
+        "arguments": [],
+        "environment": {},
+        "flavor": "cpu-basic" 
+}'
+```
+
+In the above example, the namespace of the space (`qgallouedec`) matches the username of the person who launch the job. However, this is usually not always the case, as users can launch jobs from spaces created by others.
+
+### Step 3: Interpreting the Response
+
+Once the job is launched, you'll receive a response like this:
+
+```json
+{
+    "metadata": {
+        "job_id": "-FZNr5FTonBJJ8F2ENXnDQ5SY",
+        "owner": {"id": "631ce4b244503b72277fc89f", "name": "qgallouedec"}
+    },
+    "spec": {
+        "input": {"spaceId": "qgallouedec/run-hello-world"},
+        "timeout": null,
+        "env": {},
+        "command": ["python", "run_job.py"],
+        "args": [],
+        "flavor": "cpu-basic",
+        "owner": {"id": "631ce4b244503b72277fc89f", "name": "qgallouedec"}
+    },
+    "status": {
+        "stage": "RUNNING",
+        "error": null,
+        "message": null,
+        "abuse": {"flagged": false, "reason": "", "detector": "", "at": "2025-03-17T00:22:06.432Z"}
+    }
+}
+```
+
+The most important field here is `job_id` (`-FZNr5FTonBJJ8F2ENXnDQ5SY`), which allows you to track the job's progress and access logs to verify execution.
+
+## Monitoring Job Progress
+
+To monitor the job's progress, you can use the following command:
+
+```bash
+curl -L 'https://huggingface.co/api/jobs/<username>/<job_id>/logs-stream' \
+     -H 'Authorization: Bearer <token>'
+```
+
+In my case, the command would look like this:
+
+```bash
+curl -L 'https://huggingface.co/api/jobs/qgallouedec/-FZNr5FTonBJJ8F2ENXnDQ5SY/logs-stream' \
+     -H 'Authorization: Bearer hf_MyTokenIsSecret'
+```
+
+And you'll receive a stream of logs like this:
+
+```txt
+data: {"data":"===== Job started at 2025-03-17 00:22:06 =====","timestamp":"2025-03-17T00:22:06Z"}
+
+data: {"data":"Hello, world!","timestamp":"2025-03-17T00:22:08.836Z"}
+```
+