Upload DEPLOY.md with huggingface_hub

DEPLOY.md

@@ -0,0 +1,89 @@
+# 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.