README.md

---
title: PlannerLLM
emoji: 🧠
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
short_description: OpenAI-compatible planner model API via llama.cpp
---

# PlannerLLM

OpenAI-compatible API for `bldeaw/m1_planner_q4_k_m` using llama.cpp on Hugging Face Spaces.

---

# Features

- Docker Space ready
- Persistent model storage
- Secure secret handling
- Runtime config via environment variables
- Auto model download on first start
- OpenAI-compatible endpoints

---

# Required Hugging Face Setup

## 1. Create Docker Space

Create a new Hugging Face Space:

- SDK: Docker

---

## 2. Optional: Add Persistent Storage

Settings → Storage

Recommended — prevents re-downloading the model on every restart.

Mounted path:

```text
/data
```

---

## 3. Add Variables / Secrets

Settings → Variables and Secrets

### Variables

```text
MODEL_REPO_ID=bldeaw/m1_planner_q4_k_m
MODEL_FILE=m1_planner_q4_k_m.gguf
MODEL_REVISION=main
CTX_SIZE=2048
THREADS=2
N_GPU_LAYERS=0
MODEL_DIR=/data/models
PORT=7860
```

### Secret (only if private repo)

```text
HF_TOKEN=hf_xxxxx
```

### Optional checksum

```text
MODEL_SHA256=xxxxxxxx
```

---

# Repository Files

```text
Dockerfile
start.sh
.dockerignore
README.md
```

---

# Deploy

```bash
git clone https://huggingface.co/spaces/bldeaw/planner-llm
cp Dockerfile start.sh .dockerignore README.md planner-llm/
cd planner-llm
git add .
git commit -m "production deploy"
git push origin main
```

---

# API Usage

## Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://bldeaw-planner-llm.hf.space/v1",
    api_key="dummy"
)

resp = client.chat.completions.create(
    model="local-model",
    messages=[
        {"role": "user", "content": "Hello"}
    ]
)

print(resp.choices[0].message.content)
```

---

## curl

```bash
curl https://bldeaw-planner-llm.hf.space/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'
```

---

# Endpoints

| Endpoint             | Method |
| -------------------- | ------ |
| /v1/chat/completions | POST   |
| /v1/completions      | POST   |
| /v1/models           | GET    |
| /                    | GET    |

---

# Troubleshooting

## 503 Service Unavailable

Usually:

- Space building
- Model downloading (~986 MB, takes a few minutes)
- Crash during startup

Check the Logs tab.

## checksum mismatch

Wrong file or corrupted download. Delete the cached file and restart.

## Slow startup

Large model downloading on first run. Add persistent storage so it only downloads once.

---

# Security

- Store tokens only in Secrets
- Use a private model repo + HF_TOKEN if needed
- Never commit `.env`
- Never commit `.gguf` into the Space repo