# Agent Q3 — Compiler Space Standards
**Space:** `MADdegens/agent-q3-compiler` (HF Spaces — Gradio)
**Owner:** Nick McLeod (MADdegen)
**Last updated:** 2026-05-27

---

## What this Space is

The Agent Q3 routing compiler — a Gradio UI that provides dispatch, routing configuration, and testing for Agent Q3 requests. It is a companion service to the main orchestrator Space and runs independently as a Gradio app.

**This Space is not the orchestrator.** It does not run FastAPI or serve `/v1/` endpoints directly. It routes requests TO the orchestrator at `https://maddegens-agent-q3.hf.space`.

---

## Entry point

`app.py` — Gradio application. This is the only file the Space executes. All UI, routing logic, and model dispatch lives here.

---

## Model name requirement — strictly enforced

Every model reference in this Space **must** use `nicholasjmcleod/` Ollama Cloud namespace. The old `maddegens/*` names are invalid and will fail at runtime.

| Wrong (will fail) | Correct |
|-------------------|---------|
| `maddegens/kimi-linear-48b-instruct` | `nicholasjmcleod/kimi-linear:q6_k` |
| `maddegens/harmonic-hermes-9b` | `nicholasjmcleod/harmonic-hermes:q6_k` |
| `maddegens/qwen3-48b-savant-commander` | `nicholasjmcleod/qwen3-coder-53b:q6_k` |
| `maddegens/list-3-ultra-coder-brain` | `nicholasjmcleod/qwen3-coder-53b:q6_k` |
| `maddegens/kimi-vl-a3b` | `nicholasjmcleod/kimi-linear:q6_k` |
| `maddegens/llama4-maverick-iq4nl` | `nicholasjmcleod/kimi-distilled:iq4_xs` |

**This fix is pending** — `app.py` currently contains stale `maddegens/*` references. Do not deploy until corrected.

---

## Deployment procedure

```bash
# After verifying model names are correct in app.py:
hf upload MADdegens/agent-q3-compiler app.py app.py --repo-type space
```

Gradio Spaces rebuild automatically on any file upload. Allow 60–90 seconds for the build to complete.

---

## Post-deployment verification

1. Open `https://huggingface.co/spaces/MADdegens/agent-q3-compiler`
2. Check the Space logs tab — look for `Running on public URL`
3. Send a test request from the UI to confirm routing to the orchestrator returns a response

---

## What must NOT be in this Space

- Orchestrator Python files (`main.py`, `router.py`, etc.)
- Skill `.md` files — those live in the skills-registry bucket
- `.env` files or hardcoded API keys — use HF Space secrets
- MAD Gambit content of any kind

---

## HF Space secrets (set via HF UI)

| Secret | Purpose |
|--------|---------|
| `AGENT_Q3_URL` | Orchestrator base URL (`https://maddegens-agent-q3.hf.space`) |
| `HF_TOKEN` | HF API access if needed |

---

## Change log

| Date | Action | Files | By |
|------|--------|-------|----|
| 2026-05-27 | Initial bucket backup uploaded (120 files) | All compiler source | Claude Code / MADdegen |
| 2026-05-27 | Added UPLOAD_STANDARDS.md to Space | `UPLOAD_STANDARDS.md` | Claude Code / MADdegen |
| Pending | Fix app.py model names: maddegens/* → nicholasjmcleod/* | `app.py` | Pending |