Agent.md

# Agent.md

This file documents tricks, ongoing deployment best practices, and the API exposure specification for the Odoo deployment on Hugging Face Spaces.

---

## 1. Deployment Configuration

### Target Space
- **Profile:** `Leon4gr45`  
- **Space:** `odoo`  
- **Full Identifier:** `Leon4gr45/odoo`  
- **Frontend Port:** `7860` (mandatory for all Hugging Face Spaces)

### Deployment Method
- **Docker SDK:** Configured with Python 3.12-slim executing FastAPI via Uvicorn. This provides full flexibility and extreme performance on basic CPU resources.

### HF Token
- Configured using environment variable `HF_TOKEN` at execution/deployment time.
- Never hardcode the token. Always read it from the environment.
- All monitoring and log‑streaming commands rely on `HF_TOKEN`.

### Required Files
- `Dockerfile` (standard python config, exposing port 7860)
- `README.md` (metadata with `sdk: docker` and `app_port: 7860`)
- `.hfignore` (crucial to ignore all non-essential repository directories to keep build time under 10 seconds and avoid large files upload)
- `app.py` (FastAPI lightweight backend)
- `Agent.md` (this file)

---

## 2. API Exposure and Documentation

### Mandatory Endpoints
Every deployment **must** expose:

- **`/health`**  
  - Returns HTTP 200 when the app is ready.  
  - Returns `{"status": "pass"}`.
  - Required for Hugging Face to transition the Space from *starting* → *running*.

- **`/api-docs`**  
  - Documents **all** available API endpoints.  
  - Reachable at: `https://Leon4gr45-odoo.hf.space/api-docs`

### Functional Endpoints

### `/api/version`
- **Method:** GET
- **Purpose:** Returns application and Odoo version details.
- **Request Example:**
  `GET https://Leon4gr45-odoo.hf.space/api/version`
- **Response Example:**
  ```json
  {
    "version": "19.0",
    "sdk": "docker"
  }
  ```

### `/api/modules`
- **Method:** GET
- **Purpose:** Lists available Odoo modules.
- **Request Example:**
  `GET https://Leon4gr45-odoo.hf.space/api/modules`
- **Response Example:**
  ```json
  ["base", "web", "crm", "website", "ecommerce", "inventory", "project"]
  ```

### `/api/sysinfo`
- **Method:** GET
- **Purpose:** Returns platform execution environment details.
- **Request Example:**
  `GET https://Leon4gr45-odoo.hf.space/api/sysinfo`
- **Response Example:**
  ```json
  {
    "system": "Linux",
    "release": "...",
    "version": "...",
    "machine": "x86_64",
    "python_version": "3.12.x"
  }
  ```

### `/api/ping`
- **Method:** GET
- **Purpose:** Simple ping-pong endpoint to verify responsiveness.
- **Request Example:**
  `GET https://Leon4gr45-odoo.hf.space/api/ping`
- **Response Example:**
  ```json
  {
    "ping": "pong"
  }
  ```

All endpoints listed above are documented in `/api-docs`.

---

## 3. Deployment Workflow

Precondition: Verify space is clean or contains only required metadata files before pushing.

### Standard Deployment Command
After any code change, run:

```bash
hf upload Leon4gr45/odoo --repo-type=space
```

### Scan build and run logs
- To stream build logs (SSE):
  ```bash
  curl -N -H "Authorization: Bearer $HF_TOKEN" "https://huggingface.co/api/spaces/Leon4gr45/odoo/logs/build"
  ```
- To stream run logs (SSE):
  ```bash
  curl -N -H "Authorization: Bearer $HF_TOKEN" "https://huggingface.co/api/spaces/Leon4gr45/odoo/logs/run"
  ```
- Continuously monitor for up to 300 seconds to ensure the Space starts successfully.