---
title: GameMaster Design Copilot
emoji: "🎲"
colorFrom: green
colorTo: gray
sdk: docker
app_port: 7860
license: apache-2.0
---

# GameMaster Design Copilot

CPU-first Hugging Face Space for a GameMaster game design assistant. It provides:

- A Gradio UI at `/ui`
- A plugin-friendly JSON endpoint at `/api/chat`
- A local RAG ingestion pipeline driven by `sources.yaml`
- A Legal Scraper tab for curated open game-design resources
- A pluggable LLM layer with a CPU-safe fallback and optional local GGUF model support

The project intentionally ships with no scraped corpus. Add only sources you own, public-domain sources, permissively licensed sources, or sources where you have explicit permission.

## API

`POST /api/chat`

```json
{
  "message": "Design a risk-reward stamina mechanic for a tactical RPG.",
  "project_context": "Low fantasy, party tactics, 45 minute sessions.",
  "mode": "balance",
  "retrieval_k": 4
}
```

Response:

```json
{
  "answer": "...",
  "citations": [],
  "retrieved_chunks": [],
  "warnings": []
}
```

Valid modes are `brainstorm`, `critique`, `balance`, `level_design`, and `gm_session`.

## Source Registry

Edit `sources.yaml` with approved sources only. Each source must include provenance and permission metadata:

```yaml
sources:
  - id: my_design_notes
    title: My Design Notes
    path: docs/my-design-notes.md
    license: owned
    permission: owned
    attribution: Vivek
    tags: [mechanics, balance]
```

For URL sources, enable crawling explicitly:

```yaml
sources:
  - id: public_domain_example
    title: Public Domain Design Essay
    url: https://example.org/design-essay.html
    license: public domain
    permission: public_domain
    attribution: Example Author
    tags: [level_design]
    crawl:
      enabled: true
      respect_robots: true
      user_agent: GameMasterCopilot/0.1
```

Do not add paid books, unclear web pages, proprietary rules, or broad website crawls without permission.

## Build The Index

For local development and quick tests:

```bash
python -m gamemaster_copilot.ingest --embedding-backend hash
```

For production semantic retrieval:

```bash
python -m gamemaster_copilot.ingest --embedding-backend sentence-transformers
```

Index files are written to `data/index/`.

## Legal Scraper Tab

The UI includes a `Legal Scraper` tab that can scrape a curated allowlist and rebuild the RAG index. It does not crawl arbitrary sites.

Current catalog:

- Game Design Concepts course, `CC BY 3.0 US`
- Wikipedia game design topics, `CC BY-SA 4.0 / GFDL`
- MIT OCW CMS.608 Game Design, `CC BY-NC-SA`
- Fate Core SRD, `CC BY 3.0 Unported`
- Blades in the Dark SRD, `CC BY 3.0 Unported`
- D&D Beyond SRD, `CC BY 4.0`

Legal guardrails:

- Only allowlisted catalog sources are scraped.
- `robots.txt` is checked before web page fetches.
- Binary assets, PDFs, images, scripts, and stylesheets are skipped.
- Every chunk stores source URL, license, attribution, and tags.
- Noncommercial/share-alike sources are flagged in the catalog metadata.

On Hugging Face free CPU, index builds can be slow. Start with a low `Max documents per source`, then raise it when the Space has enough time to complete ingestion. Runtime-built indexes are container-local unless you configure persistent storage or commit generated `data/index/` artifacts.

## Local Run

```bash
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 7860
```

Open `http://localhost:7860/ui`.

## Optional Local LLM

The app defaults to a deterministic template provider so the Space starts cheaply before model files are cached. Local GGUF inference also requires `llama-cpp-python`; install `requirements-local-llm.txt` or add that package back into the Space requirements before enabling it.

To enable the configured local GGUF model:

```bash
export GMC_ENABLE_LOCAL_LLM=true
export GMC_LLM_PROVIDER=llama_cpp
export GMC_LLM_MODEL_REPO=mistralai/Ministral-3-3B-Instruct-2512-GGUF
export GMC_LLM_MODEL_FILE=Ministral-3-3B-Instruct-2512-Q4_K_M.gguf
```

If Hugging Face persistent storage or a bucket is available, set cache variables so model downloads survive restarts:

```bash
export HF_HOME=/data/.huggingface
export HF_HUB_CACHE=/data/.cache/huggingface/hub
```

Storage improves cold starts, not CPU inference speed.

## Development Tests

```bash
pip install -r requirements-dev.txt
pytest
```