README.md

---
title: ZamAI mT5 Pashto Demo
emoji: 🤖
colorFrom: green
colorTo: red
sdk: gradio
sdk_version: 5.43.1
app_file: app.py
pinned: false
---

## ZamAI mT5 Pashto Instruction-Following Demo

This Space showcases the **[tasal9/ZamAI-mT5-Pashto](https://huggingface.co/tasal9/ZamAI-mT5-Pashto)** model, a fine-tuned version of `google/mt5-base` for instruction-following in the Pashto language.

### How to Use

1. **Enter an Instruction:** Provide a command or task in the "Instruction" textbox.
2. **(Optional) Provide Input:** If the instruction requires additional context, add it to the "Input" textbox.
3. **Adjust Settings:** You can modify generation parameters like `max_length`, `num_beams`, `temperature`, and `top_p` using the sliders.
4. **Generate:** Click the "Generate" button to see the model's response.

### About the Model

This model was fine-tuned on the `tasal9/ZamAI-Pashto-High-Qualituly-Dataset`. It is designed to understand and execute a wide variety of instructions in Pashto.

### Modes (Runtime Behavior)

The UI exposes a `Mode` dropdown:

- `off` – Real model generation (loads weights, may take time first run)
- `echo` – Returns the prompt exactly (fast, for UI testing)
- `useless` – Returns a fixed placeholder response (for latency / wiring checks)

You can also preset a default via environment: `ECHO_MODE=echo` or `ECHO_MODE=useless` before launching. The UI selection overrides the env per request.

### Running Locally

```bash
python app.py
```

Environment variables (optional):

| Variable | Purpose | Example |
|----------|---------|---------|
| `MODEL_ID` | Override model repo | `tasal9/ZamAI-mT5-Pashto` |
| `GRADIO_PORT` | Change port | `9000` |
| `GRADIO_HOST` | Bind address | `0.0.0.0` |
| `ECHO_MODE` | Default mode (`off\|echo\|useless`) | `echo` |
| `HF_HOME` | Hugging Face cache root | `/data/hf-cache` |
| `OFFLINE` | If set to `1/true`, sets `HF_HUB_OFFLINE=1` | `1` |
| `DEFAULT_MAX_NEW_TOKENS` | Slider default tokens | `128` |

Example:

```bash
HF_HOME=/data/hf-cache OFFLINE=1 ECHO_MODE=echo python app.py
```

### Caching & Offline Usage

1. Pick a persistent cache directory (fast disk/SSD recommended).
2. Set `HF_HOME` to that path on every run.
3. Launch once in real mode (`off`) so weights download.
4. Set `OFFLINE=1` (or directly `HF_HUB_OFFLINE=1`) for subsequent offline usage.

Linux example:

```bash
export HF_HOME=/data/hf-cache
python app.py  # first run downloads
export OFFLINE=1
python app.py  # offline reuse
```

Windows PowerShell example:

```powershell
$env:HF_HOME = 'D:\hf-cache'
python app.py   # first run
$env:OFFLINE = '1'
python app.py   # offline
```

### Health Endpoint

A lightweight HTTP health check server listens on `HEALTH_PORT` (default `8080`).


```bash
curl http://localhost:8080/health  # returns 'ok'
```

### Development Tips

- Use `echo` mode to iterate on UI changes without loading the full model.
- `useless` mode provides a constant response for benchmarking layout latency.
- Logs show cache configuration: `HF_HOME`, `TRANSFORMERS_CACHE`, and offline status.
- GPU is auto-detected (CUDA) and displayed in the header if available.

### Common Issues

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| Slow first generation | Model weights not cached | Ensure persistent `HF_HOME` |
| Network calls while offline | Missing `OFFLINE=1` | Export `OFFLINE=1` (sets `HF_HUB_OFFLINE`) |
| IndentationError on Space | Space not rebuilt | Trigger rebuild / push a new commit |
| Echo mode still loads model | Open runs before switching | Set `ECHO_MODE=echo` before launch |

### Trigger Rebuild (Hugging Face Space)

If a rebuild doesn’t trigger automatically, make a no-op commit:
 
```bash
date > .rebuild
git add .rebuild
git commit -m "chore: trigger rebuild"
git push origin main
```

### License / Usage

Refer to the model card of `tasal9/ZamAI-mT5-Pashto` for any licensing or usage constraints. This demo adds only interface logic and does not modify model licensing terms.