DEPLOY.md

# Deploying PASITA

Step-by-step guide to run the Space on your PC or on Hugging Face Spaces.

## Option A: on your PC (CPU or local GPU)

1. Clone the Space:
   ```
   git clone https://huggingface.co/spaces/OpceanAI/PASITA pasita-space
   cd pasita-space
   ```

2. Create a virtual environment and install dependencies:
   ```
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   pip install "gradio>=6.26" spaces torch
   ```
   On a CPU-only machine, the lighter CPU torch wheel works:
   `pip install torch --index-url https://download.pytorch.org/whl/cpu`

3. (Optional) If the model is private or you want to avoid download limits:
   ```
   hf auth login
   ```

4. Start the app:
   ```
   python app.py
   ```
   Open http://127.0.0.1:7860. Without a local GPU the model runs on CPU (bf16, slower).
   The `spaces` package is a no-op outside ZeroGPU: no code changes are needed.

5. Try the local API (same surface as the Space):
   ```
   curl http://127.0.0.1:7860/v1/health
   curl -X POST http://127.0.0.1:7860/v1/convert -H "Content-Type: application/json" \
     -d '{"text": "Shopping list: keyboard 49.90 EUR; free shipping over 50 EUR."}'
   ```

## Option B: on Hugging Face Spaces (ZeroGPU)

1. Create the Space (ZeroGPU hardware, free for up to 2 Spaces per account):
   ```
   hf repos create OpceanAI/PASITA --type space --sdk gradio --flavor zero-a10g --public
   ```

2. Upload the files:
   ```
   hf upload OpceanAI/PASITA . --repo-type space
   ```

3. The build installs `requirements.txt` and starts `app.py` automatically.
   Check the status:
   ```
   hf spaces info OpceanAI/PASITA --expand runtime
   hf spaces logs OpceanAI/PASITA --tail 100
   ```

4. To change the hardware later:
   ```
   hf spaces settings OpceanAI/PASITA --hardware zero-a10g
   ```

## Using the API from outside

Base URL on the Space: `https://opceanai-pasita.hf.space` (local: `http://127.0.0.1:7860`).

- OpenAI SDK compatible (`/v1/chat/completions`, streaming included):

  ```python
  from openai import OpenAI

  client = OpenAI(base_url="https://opceanai-pasita.hf.space/v1", api_key="not-needed")
  resp = client.chat.completions.create(
      model="pasita-v1",
      messages=[{"role": "user", "content": "<your plain text>"}],
  )
  print(resp.choices[0].message.content)
  ```

- Native REST: `POST /v1/convert` with `{"text", "candidates" 1-3, "structured_fallback"}`.
- Interactive docs: `GET /docs` (Swagger UI, schema at `/openapi.json`).
- Gradio API and MCP server: `?view=api` and `https://opceanai-pasita.hf.space/gradio_api/mcp/`.

Quota notes: on ZeroGPU every visitor consumes their own daily quota (the `x-ip-token` JWT
from the HF proxy travels through the request headers). Unauthenticated requests get less
quota; quota errors answer with HTTP 429.