DEPLOY.md

# Deploy Polis — GitHub + Hugging Face

Everything is built and tested. Follow these copy-paste steps. You'll need:
- a GitHub account
- a Hugging Face account (free) — https://huggingface.co/join

---

## 1. Push to GitHub

The repo already has a clean commit history. From inside the `polis/` folder:

```bash
# create the GitHub repo first at https://github.com/new  (name it "polis", empty, no README)
git remote add origin https://github.com/<YOUR_USERNAME>/polis.git
git branch -M main
git push -u origin main
```

> Replace `<YOUR_USERNAME>`. If prompted for a password, use a
> **Personal Access Token** (GitHub → Settings → Developer settings → Tokens).

---

## 2. Deploy to Hugging Face Spaces (Docker)

### a) Create the Space
1. Go to https://huggingface.co/new-space
2. **Owner**: you · **Space name**: `polis`
3. **SDK**: choose **Docker** → **Blank**
4. **Hardware**: CPU basic (free) is enough
5. Create Space.

### b) Push the code to the Space
A Space is just a git repo. From inside `polis/`:

```bash
git remote add space https://huggingface.co/spaces/<YOUR_HF_USERNAME>/polis
git push space main
```

> When prompted, username = your HF username, password = a **HF access token**
> with *write* scope (https://huggingface.co/settings/tokens).

The `README.md` header (`sdk: docker`, `app_port: 7860`) tells Spaces how to
build and run the Dockerfile automatically. First build takes ~2–3 minutes.

### c) (Optional) Turn on the live LLM engine
By default the Space runs in **mock mode** ($0) and replays the pre-recorded demo.
To make agents think with real OpenAI calls:

1. In your Space → **Settings** → **Variables and secrets** → **New secret**
2. Name: `OPENAI_API_KEY`  ·  Value: your key
3. (optional) add `POLIS_BUDGET_USD` = `1.00` to cap spend
4. **Restart** the Space.

The header dot turns green and reads **LIVE ENGINE · OpenAI**.

---

## 3. Finishing touches
- Put the **Space URL** and **GitHub URL** into the two placeholders near the top
  of `README.md`, then commit and push again.
- In `static/app.js`, the "Read the architecture" button opens GitHub — swap the
  placeholder URL for your repo (search for `github.com` in that file).
- Pin the repo on your GitHub profile and add the Space link to your resume/LinkedIn.

That's it — one link shows recruiters a deployed, interactive, agentic AI system.
```