tools.generate_background module

GENERATE_BACKGROUND – Generate + save backgrounds for VN scenes.

Wraps the existing Gemini image generation to also save output to /home/star/large_files/assets/backgrounds/ so it can be served by nginx and referenced in scene scripts.

@fire @skull THE CANVAS PAINTS ITSELF.

async tools.generate_background.run(prompt, name=None, aspect_ratio='16:9', ctx=None)[source]

Generate a VN scene background, persist it, and post it to the channel.

Entry point for the generate_background tool. It borrows the image pipeline from tools.generate_image – reusing _resolve_api_key and _call_gemini_native – after wrapping the caller’s prompt in a background-specific instruction (no characters, wide establishing shot) so the result is usable as a compose_scene backdrop. The returned bytes are normalised to PNG off the event loop via the nested _convert_to_png and asyncio.to_thread, then the function has three side effects: it writes the PNG to BACKGROUNDS_DIR on disk (creating the directory if needed) so nginx can serve it under /backgrounds/, uploads the same bytes to the current channel through ctx.adapter.send_file, and appends a record to ctx.sent_files. The deterministic filename embeds a SHA-256 hash of the image (plus a sanitised name when given). Any failure is caught and returned as a JSON error object.

Dispatched by tool_loader.py, which imports this module and resolves run via getattr(module, "run") to register it under TOOL_NAME (“generate_background”).

Parameters:

  • prompt (str) – Text description of the background; mood, lighting, style, and perspective all help.

  • name (str | None) – Optional short label for the file (prefixed with bg_). When omitted the filename is derived purely from the image hash.

  • aspect_ratio (str) – Output aspect ratio passed through to Gemini (default "16:9").

  • ctx (ToolContext | None) – The current ToolContext; its adapter is required to send the file and its channel_id / sent_files are used for the upload. When ctx or ctx.adapter is missing the call returns an error immediately.

Return type:

str

Returns:

A pretty-printed JSON string with success: True plus filename, path, scene_ref (the bg: reference for scene scripts), save_path, and a usage message on success; otherwise a JSON object with success: False and an error describing the failure.