spriteforge 0.1.1__py3-none-any.whl

spriteforge/app/static/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>SpriteForge Studio</title>
+    <script type="module" crossorigin src="/assets/index-aBfzgLQl.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-L2s1wlcp.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

spriteforge/app/static/press-start-2p-LICENSE.txt

@@ -0,0 +1,93 @@
+Copyright 2012 The Press Start 2P Project Authors (cody@zone38.net), with Reserved Font Name "Press Start 2P"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

spriteforge/app/studio.py

@@ -0,0 +1,278 @@
+"""The studio's API: projects (runs started from a first message), the agents of a run, each
+agent's thread and chat messages. Gates, artifacts, events and play stay in server.py."""
+
+import asyncio
+import json
+import os
+import re
+from functools import cache
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+from pydantic import BaseModel, Field
+
+from spriteforge.agents.workflow import WORKFLOW as AGENT_WORKFLOW
+from spriteforge.config import Config
+from spriteforge.core.cost import BudgetExceeded
+from spriteforge.core.gates import Gates
+from spriteforge.core.security import redact
+from spriteforge.core.state import Store
+from spriteforge.core.usage import usage_report
+from spriteforge.stages.chat_changes import file_change, for_gate
+from spriteforge.stages.references import MAX_BYTES, ReferenceError, add_reference, references
+from spriteforge.stages.rewind import LATE, request_stop, round_info
+from spriteforge.stages.workflow import WORKFLOW as INTAKE
+
+from .agents_view import AGENTS, actor, summarize, thread
+from .chat import Intent, answer_question, classify
+from .workers import FINAL, Workers
+
+# Runs with human gates are projects; the rest are tools (memory audits, evals, CLI builds).
+PROJECT_WORKFLOWS = {INTAKE, AGENT_WORKFLOW}
+# Project card picture, best first: the build's poster, its title screen, the art sheet.
+THUMBNAILS = [r"game/v(\d+)/poster\.png", r"game/v(\d+)/menus/title\.png", r"game/v(\d+)/art\.png",
+              r"concept/v(\d+)\.png", r"preview/v(\d+)/gameplay-4x\.png"]  # fmt: skip
+
+
+class NewProject(BaseModel):
+    text: str = Field(min_length=1, max_length=10000)
+    mock: bool = False
+
+
+class Stop(BaseModel):
+    change: int  # the chat change (its chat.user event id) the Go back card is about
+    later: bool = False  # Queue for later: apply it at the next gate instead
+
+
+class ChatMessage(BaseModel):
+    text: str = Field(min_length=1, max_length=4000)
+    attachments: list[str] = Field(default_factory=list)  # reference ids (phase 4)
+    intent: Intent | None = None  # None: classified; the user can override a wrong guess
+
+
+@cache
+def chromium_installed() -> bool:
+    """Playwright's Chromium plays and checks every build; checked once per process."""
+    from playwright.sync_api import sync_playwright
+
+    try:
+        with sync_playwright() as p:
+            return os.path.exists(p.chromium.executable_path)
+    except Exception:  # noqa: BLE001 -- any failure here means "not usable"
+        return False
+
+
+def project(store: Store, run, busy: bool) -> dict:
+    with store.connect() as db:
+        created = db.execute(
+            "SELECT timestamp FROM events WHERE run_id=? ORDER BY id LIMIT 1", (run.id,)
+        ).fetchone()
+        images = db.execute(
+            "SELECT id,name FROM artifacts WHERE run_id=? AND mime LIKE 'image/%'", (run.id,)
+        ).fetchall()
+        designs = db.execute(
+            "SELECT name,data FROM artifacts WHERE run_id=? AND name GLOB 'game/design/v*.json'",
+            (run.id,),
+        ).fetchall()
+    thumbnail = None
+    for pattern in THUMBNAILS:
+        found = [(int(m[1]), r["id"]) for r in images if (m := re.fullmatch(pattern, r["name"]))]
+        if found:
+            thumbnail = max(found)[1]
+            break
+    title = None
+    versions = [(int(m[1]), r["data"]) for r in designs
+                if (m := re.fullmatch(r"game/design/v(\d+)\.json", r["name"]))]  # fmt: skip
+    if versions:
+        title = json.loads(max(versions)[1]).get("title")
+    goal = " ".join(str(run.config.get("goal") or "").split())
+    gate = Gates(store).pending(run.id)
+    return {
+        "id": run.id,
+        "title": title or (goal[:80] + "…" if len(goal) > 80 else goal) or "Untitled game",
+        "idea": goal,
+        "status": run.status,
+        "workflow": run.config.get("workflow"),
+        "mock": bool(run.config.get("mock")),
+        "created": created[0] if created else None,
+        "cost": round(usage_report(store, run.id).known_estimated_cost, 4),
+        "thumbnail": thumbnail,
+        "gate": {"id": gate.id, "title": gate.title, "stage": gate.stage} if gate else None,
+        "busy": busy,
+    }
+
+
+def agent_cap(run) -> float | None:
+    """Each agent's allowance since the human's last action (None: the run's caps are per run)."""
+    budget = run.config.get("budget") or {}
+    return budget.get("max_agent_cost", 10) if budget.get("per_request") else None
+
+
+def studio_router(store: Store, workers: Workers, cfg: Config) -> APIRouter:
+    api = APIRouter(prefix="/api")
+
+    def require_run(id):
+        try:
+            return store.get_run(id)
+        except KeyError:
+            raise HTTPException(404, "Run not found") from None
+
+    def require_agent(name):
+        if name not in AGENTS:
+            raise HTTPException(404, "Unknown agent")
+        return name
+
+    @api.get("/setup")
+    async def setup():
+        """The first-run check: what live mode needs, in plain words."""
+        return {
+            "meta_api_key": bool(os.environ.get("META_API_KEY")),
+            "chromium": await asyncio.to_thread(chromium_installed),
+        }
+
+    @api.get("/projects")
+    def projects():
+        runs = [r for r in store.runs() if r.config.get("workflow") in PROJECT_WORKFLOWS]
+        return {"projects": [project(store, r, workers.busy(r.id)) for r in runs]}
+
+    @api.post("/projects", status_code=201)
+    async def create(body: NewProject):
+        from spriteforge.stages.workflow import start_run
+
+        if not body.mock and not os.environ.get("META_API_KEY"):
+            raise HTTPException(
+                409, "No META_API_KEY is set, so Muse cannot be called. Add your key to .env "
+                "and restart, or try offline (mock)."
+            )  # fmt: skip
+        run = await asyncio.to_thread(start_run, store, cfg, mock=body.mock, goal=body.text)
+        store.append_event(run.id, "Human", "chat.user", {"to": "Director", "text": body.text,
+                                                          "intent": "idea"})  # fmt: skip
+        workers.start(run.id)
+        return project(store, store.get_run(run.id), workers.busy(run.id))
+
+    @api.get("/runs/{id}/project")
+    def one(id: str):
+        return project(store, require_run(id), workers.busy(id))
+
+    @api.post("/runs/{id}/resume")
+    async def resume(id: str):  # async: the worker task needs the server's event loop
+        """Carry on a run whose worker is not running (the studio restarted mid-step, or the
+        run failed): the step functions continue from the durable checkpoint."""
+        run = require_run(id)
+        if run.status == "failed" and run.config.get("workflow") == INTAKE:
+            store.retry_failed(id)
+        elif run.status == "budget_exhausted":  # Continue: a fresh allowance (cost policy)
+            store.continue_run(id)
+        elif run.status in FINAL:
+            raise HTTPException(409, f"This project is {run.status.replace('_', ' ')}")
+        return {"started": workers.start(id)}
+
+    @api.get("/runs/{id}/agents")
+    def agents(id: str):
+        run = require_run(id)
+        # A finished run's worker may still be returning from its last step: not busy.
+        busy = workers.busy(id) and run.status not in FINAL
+        gate = Gates(store).pending(id)
+        from .server import latest_play
+
+        with store.connect() as db:
+            last = db.execute("SELECT MAX(id) FROM events WHERE run_id=?", (id,)).fetchone()[0]
+        return {
+            "agents": [a.model_dump() for a in summarize(store, id, busy)],
+            "last_event": last or 0,  # the event stream continues from here
+            "play": latest_play(store, id),
+            "status": run.status,
+            "busy": busy,
+            "gate": gate.model_dump(mode="json") if gate else None,
+            "queued": for_gate(store, id),  # chat changes the open gate's Request changes applies
+            "agent_cap": agent_cap(run),
+            "error": workers.errors.get(id),
+        }
+
+    @api.get("/runs/{id}/agents/{agent:path}/thread")
+    def agent_thread(id: str, agent: str, after: int = 0):
+        require_run(id)
+        return {"items": thread(store, id, require_agent(agent), after)}
+
+    @api.post("/runs/{id}/agents/{agent:path}/messages", status_code=201)
+    async def message(id: str, agent: str, body: ChatMessage):
+        require_run(id)
+        require_agent(agent)
+        intent = body.intent or classify(body.text)
+        cursor = max((e.id for e in store.events(id)), default=0)
+        user = {"to": agent, "text": body.text, "intent": intent}
+        if intent == "change":
+            # Filed under the agent's Revision slot; the gated pipeline applies it (chat_changes).
+            fields, reply = await asyncio.to_thread(file_change, store, id, agent, body.text)
+            store.append_event(id, "Human", "chat.user", {**user, **fields})
+            answer = {"text": reply, "intent": "change"}
+            info = round_info(store, id) if fields.get("slot") and workers.busy(id) else None
+            if info:
+                answer = await asyncio.to_thread(go_back_offer, id, agent, fields["slot"], info)
+            store.append_event(id, agent, "chat.agent", answer)
+        else:
+            store.append_event(id, "Human", "chat.user", user)
+            try:
+                reply = {"text": await asyncio.to_thread(answer_question, store, id, agent,
+                                                         body.text)}  # fmt: skip
+            except BudgetExceeded as exc:
+                reply = {"text": f"I can't answer now: {exc}.", "error": True}
+            except Exception as exc:  # noqa: BLE001 -- the reason is shown, scrubbed
+                reply = {"text": "I couldn't answer: " + redact(str(exc))[:300], "error": True}
+            store.append_event(id, agent, "chat.agent", {**reply, "intent": "question"})
+        return {"items": thread(store, id, agent, cursor)}
+
+    def go_back_offer(id: str, agent: str, slot: str, info: dict) -> dict:
+        """A change asked while a round of work runs: the agent's reply, with the Go back card
+        when the change concerns work this round already did (or is doing)."""
+        events = store.events(id, info["start"])
+        change = max(e.id for e in events if e.type == "chat.user")
+        build = f"build v{info['build']}" if info["build"] else "this round"
+        if slot in LATE and not any(actor(e) == agent for e in events):
+            return {"text": f"Noted: I'll use it when I get to it in {build}. Nothing stops.",
+                    "intent": "change"}  # fmt: skip
+        working = next((a.name for a in summarize(store, id, True) if a.status == "working"),
+                       "Director")  # fmt: skip
+        return {
+            "text": f"This stops the {working} ({build}, ${info['cost']:.2f} so far) and goes "
+                    f"back to the {agent}, so no more is spent on work this change replaces.",
+            "intent": "change",
+            "rewind": {"change": change, "round": info["round"], "working": working,
+                       "build": info["build"], "cost": info["cost"]},
+        }  # fmt: skip
+
+    @api.get("/runs/{id}/references")
+    def list_references(id: str):
+        require_run(id)
+        return {"references": references(store, id)}
+
+    @api.post("/runs/{id}/references", status_code=201)
+    async def upload_reference(id: str, file: UploadFile = File(...), agent: str = Form(...),
+                               rights: bool = Form(False)):  # fmt: skip
+        """A reference image for one agent (the Director: every agent), stored locked once the
+        human confirms they may use it (stages/references.py)."""
+        require_run(id)
+        require_agent(agent)
+        data = await file.read(MAX_BYTES + 1)
+        try:
+            ref = await asyncio.to_thread(add_reference, store, id, agent, file.filename or "",
+                                          data, rights)  # fmt: skip
+        except ReferenceError as exc:
+            raise HTTPException(400, str(exc)) from None
+        return ref
+
+    @api.post("/runs/{id}/stop")
+    def stop(id: str, body: Stop):
+        """The Go back card's answer: stop the round now (the worker rewinds it with every
+        queued change) or keep the change queued for the next gate."""
+        require_run(id)
+        if body.later:
+            store.append_event(id, "Human", "rewind.declined", {"change": body.change})
+            return {"stopping": False}
+        info = round_info(store, id)
+        if info is None or not workers.busy(id):
+            raise HTTPException(409, "That work already finished: your change waits for the "
+                                "review that is open now")  # fmt: skip
+        request_stop(store, id, [body.change])
+        return {"stopping": True, "round": info["round"]}
+
+    return api

spriteforge/app/workers.py

@@ -0,0 +1,73 @@
+"""One background worker per active run: it steps the run's workflow until the next gate (or
+the end), so several projects can be in progress at once in one studio process."""
+
+import asyncio
+from contextlib import suppress
+
+from spriteforge.agents.workflow import WORKFLOW
+from spriteforge.agents.workflow import workflow_step as agent_step
+from spriteforge.core.cost import BudgetExceeded, Cancelled
+from spriteforge.core.demo import demo_step
+from spriteforge.core.security import redact
+from spriteforge.core.state import Store
+from spriteforge.stages.rewind import rewind
+from spriteforge.stages.workflow import WORKFLOW as INTAKE
+from spriteforge.stages.workflow import workflow_step as intake_step
+
+# budget_exhausted is not final: the run waits for Continue (cost policy).
+FINAL = {"completed", "aborted", "failed"}
+
+
+def step_for(store: Store, run_id: str):
+    workflow = store.get_run(run_id).config.get("workflow")
+    return intake_step if workflow == INTAKE else agent_step if workflow == WORKFLOW else demo_step
+
+
+class Workers:
+    def __init__(self, store: Store, interval: float = 1.0):
+        self.store, self.interval = store, interval
+        self.tasks: dict[str, asyncio.Task] = {}
+        self.errors: dict[str, str] = {}  # run id -> scrubbed message of the failure
+
+    def busy(self, run_id: str) -> bool:
+        task = self.tasks.get(run_id)
+        return task is not None and not task.done()
+
+    def start(self, run_id: str) -> bool:
+        """Step this run in the background; False when its worker is already running.
+        Needs a running event loop (call from a route or the app lifespan)."""
+        if self.busy(run_id):
+            return False
+        self.errors.pop(run_id, None)
+        self.tasks[run_id] = asyncio.create_task(self._work(run_id))
+        return True
+
+    async def _work(self, run_id: str):
+        while True:
+            try:
+                if self.store.get_run(run_id).status in FINAL:
+                    break
+                more = await asyncio.to_thread(step_for(self.store, run_id), self.store, run_id)
+                if not more:
+                    break
+            except Cancelled:
+                # Go back: the stopped round is superseded and starts again with the changes.
+                await asyncio.to_thread(rewind, self.store, run_id)
+                continue
+            except BudgetExceeded as exc:
+                await asyncio.to_thread(self.store.pause_for_budget, run_id,
+                                        f"{redact(str(exc))}: press Continue for a fresh allowance")  # fmt: skip
+                break
+            except Exception as exc:  # noqa: BLE001 -- persist any worker failure at task boundary
+                # No traceback/HTTP headers: errors are scrubbed at this boundary.
+                self.errors[run_id] = redact(str(exc))
+                await asyncio.to_thread(self.store.fail, run_id, str(exc))
+                break
+            await asyncio.sleep(self.interval)
+
+    async def close(self):
+        for task in self.tasks.values():
+            task.cancel()
+        for task in self.tasks.values():
+            with suppress(asyncio.CancelledError):
+                await task