spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/studio/levelgen.py

@@ -0,0 +1,352 @@
+"""Deterministic level generators.
+
+Platformer levels are stitched from hand-designed chunks; top-down levels are bordered arenas whose
+obstacles never disconnect the floor. Generators only produce geometry and *slots*; the assembler
+decides what goes into each slot.
+"""
+
+from __future__ import annotations
+
+import random
+from collections import deque
+from dataclasses import dataclass, field
+
+Cell = tuple[int, int]
+
+PLATFORMER_HEIGHT = 14
+STAND_ROW = 11  # row the player / walkers stand on (ground top is row 12)
+
+
+@dataclass
+class Layout:
+    width: int
+    height: int
+    tiles: dict[Cell, str] = field(default_factory=dict)  # solid | oneway
+    player: Cell = (0, 0)
+    exit: Cell | None = None
+    door: Cell | None = None
+    ground_slots: list[Cell] = field(default_factory=list)  # walkers, turrets...
+    air_slots: list[Cell] = field(default_factory=list)  # pickups
+    hazard_slots: list[Cell] = field(default_factory=list)  # spikes
+    portal_slots: list[Cell] = field(default_factory=list)  # spawners (top-down)
+    free_cells: list[Cell] = field(default_factory=list)  # walkable, unoccupied (top-down)
+    chunks: list[str] = field(default_factory=list)  # platformer chunk names, in order
+
+    def is_free(self, c: Cell) -> bool:
+        return c not in self.tiles
+
+
+# --- platformer chunks ------------------------------------------------------------------------
+# Rows are absolute rows 4..13 (the top 4 rows are always empty). Markers:
+#   '#' solid  '=' one-way  'g' ground enemy slot  'c' pickup slot  'h' hazard slot  '.' empty
+
+
+@dataclass(frozen=True)
+class Chunk:
+    name: str
+    rows: tuple[str, ...]
+    needs_up: int  # tiles of jump height required
+    pit: bool = False
+    min_difficulty: int = 1
+    needs_across: int = 0  # tiles of horizontal jump distance required
+
+
+CHUNKS: tuple[Chunk, ...] = (
+    Chunk("flat", (
+        "..........",
+        "..........",
+        "..........",
+        "..........",
+        "..........",
+        "...c..c...",
+        "..........",
+        "..g....g..",
+        "##########",
+        "##########"), 0),
+    Chunk("low_platforms", (
+        "............",
+        "............",
+        "............",
+        "............",
+        "....cc......",
+        "............",
+        "...====.....",
+        ".g.......g..",
+        "############",
+        "############"), 2),
+    Chunk("stairs", (
+        "..............",
+        "..............",
+        "..........cc..",
+        "..............",
+        ".........====.",
+        "..............",
+        "..====........",
+        "g......g......",
+        "##############",
+        "##############"), 2),
+    Chunk("block_step", (
+        "............",
+        "............",
+        "............",
+        "............",
+        "....c.......",
+        "............",
+        "....###.....",
+        ".g..###...g.",
+        "############",
+        "############"), 2),
+    Chunk("tower", (
+        "............",
+        "............",
+        "............",
+        ".....ccc....",
+        "............",
+        ".....###....",
+        ".....###....",
+        ".g...###..g.",
+        "############",
+        "############"), 3, min_difficulty=2),
+    Chunk("high_platform", (
+        "............",
+        "............",
+        "....cccc....",
+        "............",
+        "...======...",
+        "............",
+        "............",
+        "..g......g..",
+        "############",
+        "############"), 4, min_difficulty=2),
+    Chunk("spike_run", (
+        "............",
+        "............",
+        "............",
+        "............",
+        "............",
+        "....c..c....",
+        "............",
+        "..hh....hh..",
+        "############",
+        "############"), 2),
+    Chunk("low_ceiling", (
+        "............",
+        "............",
+        "............",
+        "............",
+        "..########..",
+        "............",
+        "...c.c.c....",
+        "..g.....g...",
+        "############",
+        "############"), 0),
+    Chunk("gap", (
+        "..........",
+        "..........",
+        "..........",
+        "..........",
+        "..........",
+        "....cc....",
+        "..........",
+        "..g.......",
+        "####..####",
+        "####..####"), 0, pit=True, needs_across=3),
+    Chunk("bridge_gap", (
+        "..............",
+        "..............",
+        "..............",
+        "..............",
+        "......cc......",
+        "..............",
+        ".....====.....",
+        "..g........g..",
+        "####......####",
+        "####......####"), 2, pit=True, min_difficulty=2, needs_across=3),
+)
+
+START = (
+    "......",
+    "......",
+    "......",
+    "......",
+    "......",
+    "......",
+    "......",
+    "..P...",
+    "######",
+    "######",
+)
+
+LENGTH_CHUNKS = {"short": 4, "medium": 7, "long": 11}
+
+
+def _fits(c: Chunk, jump_up: int, jump_across: int, pits: bool) -> bool:
+    return c.needs_up <= jump_up and c.needs_across <= jump_across and (pits or not c.pit)
+
+
+def usable_chunks(jump_up: int, jump_across: int, pits: bool, difficulty: int) -> list[Chunk]:
+    return [c for c in CHUNKS if _fits(c, jump_up, jump_across, pits) and c.min_difficulty <= difficulty]
+
+
+CHUNK_BY_NAME = {c.name: c for c in CHUNKS}
+
+
+def plan_chunks(seed: int, length: str, jump_up: int, jump_across: int, pits: bool, difficulty: int) -> list[str]:
+    rng = random.Random(f"chunks:{seed}")
+    pool = usable_chunks(jump_up, jump_across, pits, difficulty)
+    picks: list[Chunk] = []
+    for _ in range(LENGTH_CHUNKS[length]):
+        options = [c for c in pool if not picks or c.name != picks[-1].name] or pool
+        # Harder levels lean toward chunks that need more skill.
+        weights = [1.0 + (c.needs_up + (2 if c.pit else 0)) * (difficulty - 1) * 0.25 for c in options]
+        picks.append(rng.choices(options, weights)[0])
+    return [c.name for c in picks]
+
+
+def chunks_fit(names: list[str], length: str, jump_up: int, jump_across: int, pits: bool) -> bool:
+    """Whether a previously planned chunk sequence still works for changed player abilities."""
+    if len(names) != LENGTH_CHUNKS[length] or any(n not in CHUNK_BY_NAME for n in names):
+        return False
+    return all(_fits(CHUNK_BY_NAME[n], jump_up, jump_across, pits) for n in names)
+
+
+def platformer(seed: int, length: str, jump_up: int, jump_across: int, pits: bool, difficulty: int, door: bool,
+               chunks: list[str] | None = None) -> Layout:
+    names = chunks if chunks is not None else plan_chunks(seed, length, jump_up, jump_across, pits, difficulty)
+    picks = [CHUNK_BY_NAME[n] for n in names]
+
+    lay = Layout(0, PLATFORMER_HEIGHT)
+    x0 = _stamp(lay, START, 0)
+    for chunk in picks:
+        x0 = _stamp(lay, chunk.rows, x0)
+    x0 = _end_chunk(lay, x0, door)
+    lay.width = x0
+    lay.chunks = list(names)
+    return lay
+
+
+def floor_below(lay: Layout, c: Cell) -> int | None:
+    """Height in tiles of cell `c` above the floor the player would stand on beneath it."""
+    x, y = c
+    for yy in range(y + 1, lay.height):
+        if (x, yy) in lay.tiles:
+            return yy - 1 - y
+    return None
+
+
+def _stamp(lay: Layout, rows: tuple[str, ...], x0: int) -> int:
+    top = PLATFORMER_HEIGHT - len(rows)
+    for dy, row in enumerate(rows):
+        y = top + dy
+        for dx, ch in enumerate(row):
+            c = (x0 + dx, y)
+            if ch == "#":
+                lay.tiles[c] = "solid"
+            elif ch == "=":
+                lay.tiles[c] = "oneway"
+            elif ch == "g":
+                lay.ground_slots.append(c)
+            elif ch == "c":
+                lay.air_slots.append(c)
+            elif ch == "h":
+                lay.hazard_slots.append(c)
+            elif ch == "P":
+                lay.player = c
+    return x0 + len(rows[0])
+
+
+def _end_chunk(lay: Layout, x0: int, door: bool) -> int:
+    width = 9
+    for x in range(x0, x0 + width):
+        lay.tiles[(x, 12)] = lay.tiles[(x, 13)] = "solid"
+    if door:
+        # A wall from the ceiling down to the door, so the exit can only be reached through it.
+        for y in range(0, 8):
+            lay.tiles[(x0 + 2, y)] = "solid"
+        lay.door = (x0 + 2, STAND_ROW)
+    lay.exit = (x0 + 6, STAND_ROW)
+    return x0 + width
+
+
+def extra_ground_cells(lay: Layout, min_x: int) -> list[Cell]:
+    """Standing cells on solid ground that no slot uses (for overflow enemies / pickups)."""
+    used = set(lay.ground_slots) | set(lay.air_slots) | set(lay.hazard_slots)
+    blocked = {lay.player, lay.exit, lay.door}
+    out = []
+    for x in range(min_x, lay.width):
+        c = (x, STAND_ROW)
+        if lay.tiles.get((x, STAND_ROW + 1)) == "solid" and lay.is_free(c) and c not in used and c not in blocked \
+                and lay.is_free((x, STAND_ROW - 1)):
+            out.append(c)
+    if lay.door:
+        out = [c for c in out if c[0] < lay.door[0] - 1]
+    return out
+
+
+# --- top-down arena ---------------------------------------------------------------------------
+
+ARENA_SIZE = {"short": (28, 18), "medium": (36, 24), "long": (46, 30)}
+OBSTACLES = ((2, 2), (4, 1), (1, 4), (3, 3), (2, 1), (1, 2))
+
+
+def arena(seed: int, length: str, difficulty: int) -> Layout:
+    w, h = ARENA_SIZE[length]
+    lay = Layout(w, h)
+    for x in range(w):
+        lay.tiles[(x, 0)] = lay.tiles[(x, h - 1)] = "solid"
+    for y in range(h):
+        lay.tiles[(0, y)] = lay.tiles[(w - 1, y)] = "solid"
+    lay.player = (w // 2, h // 2)
+
+    rng = random.Random(f"arena:{seed}")
+    target = (w * h) // (34 - difficulty * 2)
+    placed = attempts = 0
+    while placed * 4 < target and attempts < 400:
+        attempts += 1
+        ow, oh = rng.choice(OBSTACLES)
+        x, y = rng.randint(2, w - 3 - ow), rng.randint(2, h - 3 - oh)
+        cells = [(x + i, y + j) for i in range(ow) for j in range(oh)]
+        if any(abs(cx - lay.player[0]) <= 3 and abs(cy - lay.player[1]) <= 3 for cx, cy in cells):
+            continue
+        if any(c in lay.tiles for c in cells):
+            continue
+        for c in cells:
+            lay.tiles[c] = "solid"
+        if not _connected(lay):
+            for c in cells:
+                del lay.tiles[c]
+            continue
+        placed += 1
+
+    dist = _distances(lay, lay.player)
+    lay.free_cells = sorted(c for c in dist if c != lay.player)
+    lay.exit = max(dist, key=lambda c: (dist[c], c))
+    corners = [(2, 2), (w - 3, h - 3), (w - 3, 2), (2, h - 3)]
+    lay.portal_slots = [_nearest_free(lay, dist, c) for c in corners]
+    return lay
+
+
+def _neighbors(c: Cell):
+    x, y = c
+    return ((x + 1, y), (x - 1, y), (x, y + 1), (x, y - 1))
+
+
+def _distances(lay: Layout, start: Cell) -> dict[Cell, int]:
+    dist = {start: 0}
+    q = deque([start])
+    while q:
+        c = q.popleft()
+        for n in _neighbors(c):
+            if n not in dist and lay.is_free(n) and 0 <= n[0] < lay.width and 0 <= n[1] < lay.height:
+                dist[n] = dist[c] + 1
+                q.append(n)
+    return dist
+
+
+def _connected(lay: Layout) -> bool:
+    free = sum(1 for x in range(lay.width) for y in range(lay.height) if lay.is_free((x, y)))
+    return len(_distances(lay, lay.player)) == free
+
+
+def _nearest_free(lay: Layout, dist: dict[Cell, int], c: Cell) -> Cell:
+    return min(dist, key=lambda d: (abs(d[0] - c[0]) + abs(d[1] - c[1]), d))

spawnpoint/studio/llm.py

@@ -0,0 +1,145 @@
+"""Minimal OpenAI-compatible chat client with structured (JSON-schema) output.
+
+Works with vLLM, OpenAI, and any server implementing /v1/chat/completions with
+`response_format: {"type": "json_schema"}`. No third-party dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+DEFAULT_BASE_URL = "http://localhost:8000/v1"
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+@dataclass
+class Usage:
+    calls: int = 0
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    seconds: float = 0.0
+
+    def add(self, other: "Usage") -> None:
+        self.calls += other.calls
+        self.prompt_tokens += other.prompt_tokens
+        self.completion_tokens += other.completion_tokens
+        self.seconds += other.seconds
+
+    def __str__(self) -> str:
+        return (f"{self.calls} call(s), {self.prompt_tokens} prompt + {self.completion_tokens} completion tokens, "
+                f"{self.seconds:.1f}s")
+
+
+class ChatModel(Protocol):
+    name: str
+    usage: Usage
+
+    def chat_json(self, messages: list[dict], schema: dict, schema_name: str, *,
+                  temperature: float = 0.3, max_tokens: int = 1500) -> dict: ...
+
+
+@dataclass
+class OpenAICompatible:
+    base_url: str = field(default_factory=lambda: os.environ.get("SPAWNPOINT_LLM_BASE_URL", DEFAULT_BASE_URL))
+    model: str | None = field(default_factory=lambda: os.environ.get("SPAWNPOINT_LLM_MODEL"))
+    api_key: str | None = field(default_factory=lambda: os.environ.get("SPAWNPOINT_LLM_API_KEY"))
+    timeout: float = 180.0
+    usage: Usage = field(default_factory=Usage)
+
+    @property
+    def name(self) -> str:
+        return self.model or "?"
+
+    def _request(self, path: str, payload: dict | None = None) -> dict:
+        url = self.base_url.rstrip("/") + path
+        data = json.dumps(payload).encode() if payload is not None else None
+        req = urllib.request.Request(url, data=data, method="POST" if data else "GET")
+        req.add_header("Content-Type", "application/json")
+        if self.api_key:
+            req.add_header("Authorization", f"Bearer {self.api_key}")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            body = e.read().decode(errors="replace")[:500]
+            raise LLMError(f"LLM server returned {e.code} for {path}: {body}") from e
+        except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+            raise LLMError(
+                f"cannot reach the LLM at {self.base_url} ({e}). Start it (e.g. `docker start spawnpoint-llm`) "
+                "or set SPAWNPOINT_LLM_BASE_URL.") from e
+
+    def resolve_model(self) -> str:
+        if not self.model:
+            models = self._request("/models").get("data", [])
+            if not models:
+                raise LLMError(f"the LLM server at {self.base_url} lists no models")
+            # A fine-tuned adapter (vLLM lists it with a `parent`) beats the base model it sits on.
+            adapters = [m for m in models if m.get("parent")]
+            self.model = (adapters or models)[0]["id"]
+        return self.model
+
+    def chat_json(self, messages: list[dict], schema: dict, schema_name: str, *,
+                  temperature: float = 0.3, max_tokens: int = 1500) -> dict:
+        payload: dict[str, Any] = {
+            "model": self.resolve_model(),
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            "response_format": {"type": "json_schema",
+                                "json_schema": {"name": schema_name, "schema": schema, "strict": True}},
+        }
+        t0 = time.perf_counter()
+        resp = self._request("/chat/completions", payload)
+        elapsed = time.perf_counter() - t0
+        u = resp.get("usage") or {}
+        self.usage.add(Usage(1, u.get("prompt_tokens", 0), u.get("completion_tokens", 0), elapsed))
+        try:
+            content = resp["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as e:
+            raise LLMError(f"unexpected LLM response: {str(resp)[:300]}") from e
+        return parse_json(content)
+
+
+def parse_json(content: str) -> dict:
+    """Parse model output; tolerate code fences or text around a JSON object."""
+    text = (content or "").strip()
+    if text.startswith("```"):
+        text = text.strip("`")
+        text = text[text.find("{"):]
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        start, end = text.find("{"), text.rfind("}")
+        if start >= 0 and end > start:
+            try:
+                return json.loads(text[start:end + 1])
+            except json.JSONDecodeError:
+                pass
+    raise LLMError(f"LLM did not return valid JSON: {text[:300]}")
+
+
+@dataclass
+class ScriptedModel:
+    """Test double: returns canned responses in order and records the prompts it saw."""
+
+    responses: list[dict]
+    name: str = "scripted"
+    usage: Usage = field(default_factory=Usage)
+    seen: list[list[dict]] = field(default_factory=list)
+
+    def chat_json(self, messages: list[dict], schema: dict, schema_name: str, *,
+                  temperature: float = 0.3, max_tokens: int = 1500) -> dict:
+        self.seen.append(messages)
+        self.usage.add(Usage(1, 0, 0, 0.0))
+        if not self.responses:
+            raise LLMError("scripted model ran out of responses")
+        return self.responses.pop(0)