Thor Automated Program Builder (TAPB) v3.2.2.2

TAPB is a Windows desktop application that uses an OpenAI model to generate small Python or HTML/JavaScript projects from a plain-English project specification. It can validate the generated files, ask the model to repair detected problems, and then run additional improvement rounds against the current project.

Important: TAPB sends your project specification and project code to the selected OpenAI model. API usage may incur charges on your OpenAI account.

What TAPB Does

A normal build follows this workflow:

1. You describe the project in Project Specification.
2. TAPB asks the selected model to return a set of complete project files.
3. TAPB writes those files into a new timestamped project folder.
4. The validator checks the generated project.
5. When validation finds problems, TAPB sends the issues and current files back to the model.
6. The model returns full-file replacements intended to fix the problems.
7. TAPB writes the repaired files and validates again.
8. The process stops when validation passes or the maximum iteration count is reached.

Generated projects are stored in:

thor_projects_v3\

That folder is created inside the directory from which TAPB is launched. Each build receives its own timestamped subfolder, so earlier builds are preserved.

Requirements

• Windows 10 or Windows 11
• Python 3.10 or newer recommended
• An OpenAI API key
• The OpenAI Python package

Install the required package from PowerShell or Command Prompt:

python -m pip install openai

Starting TAPB

One-command Windows install and launch

Paste this into PowerShell from any folder:

$dir="$HOME\TAPB"; if(Test-Path "$dir\.git"){git -C $dir pull}else{git clone https://github.com/lightningfastcomputing/TAPB.git $dir}; Set-Location $dir; if(!(Test-Path ".\.venv\Scripts\python.exe")){py -m venv .venv}; & ".\.venv\Scripts\python.exe" -m pip install --upgrade pip; & ".\.venv\Scripts\python.exe" -m pip install openai; Start-Process -FilePath ".\.venv\Scripts\pythonw.exe" -ArgumentList ".\tapbv3_2_2_2.py" -WorkingDirectory $dir

Git and Python must already be installed. After TAPB opens, click Load API Key... and select a text file containing the OpenAI API key on its first non-empty line.

Or Manual Download Repo

Then Run:

START.bat

Or launch it directly:

python tapbv3_2_2_2.py

Adding an OpenAI API Key

TAPB supports two API-key methods.

Method 1: Load the key from a text file

1. Create a plain-text file, such as:

   openai_key.txt
   

2. Put the API key on the first non-empty line:

   sk-your-api-key-here
   

3. Start TAPB.

4. Click Load API Key....

5. Select the text file.

6. The status near the model field should change to:

   [API key: loaded]
   

TAPB reads only the first non-empty line and places it into the OPENAI_API_KEY environment variable for the current TAPB process.

Do not place the key file inside a public GitHub repository. Keep it elsewhere on your computer. The included .gitignore also excludes .env files, but it cannot protect an arbitrary .txt file containing a key.

Method 2: Set an environment variable

In PowerShell, for the current window only:

$env:OPENAI_API_KEY = "sk-your-api-key-here"
python tapbv3_2_2_2.py

When TAPB detects the variable at startup, it displays:

[API key: ENV]

Main Controls

Target type

Controls what kind of project TAPB asks the model to create.

• python — generates one or more Python files.
• html_js — generates a browser project, normally including index.html and JavaScript files.

Max iterations

The maximum number of validation attempts during the initial build.

For example, with a value of 5, TAPB can validate the project up to five times. After a failed validation, it asks the model for repairs before the next attempt. TAPB stops early when validation passes.

Higher values may improve the chance of repairing a project, but they also use more API calls and tokens.

Model

The OpenAI model name used for generation, repair, and improvement requests.

The default is:

gpt-4.1-mini

The default can also be changed with the TAPB_MODEL environment variable.

Project Specification

This is the main build prompt. Describe the program, expected behavior, controls, interface, and required files as clearly as possible.

Example:

Create a single-player HTML5 canvas platformer. The player moves with A and D,
jumps with Space, lands on platforms, and reaches a goal flag. Include index.html,
game.js, and styles.css. Keep all assets procedural and require no external files.

Build Project

Starts a new build in a background thread. TAPB creates a new project folder, generates the files, validates them, and performs repair iterations when necessary.

Open Projects Folder

Opens the thor_projects_v3 output directory in Windows File Explorer.

Validation Modes

Validation modes mainly affect HTML/JavaScript projects. Python projects use the Python validator regardless of the selected mode.

All HTML/JavaScript modes perform these general checks:

• index.html exists
• a <canvas> element exists
• at least one <script> tag exists
• at least one JavaScript file exists
• requestAnimationFrame is present
• an update() or loop() function is present
• parentheses and braces appear balanced

Platformer

The strict default for side-view platform games.

In addition to the general checks, TAPB looks for:

• player-related logic
• platform or ground-related logic

Choose this for games with jumping, falling, floors, and platforms.

Sandbox

Uses only the general canvas and animation checks. It does not require a player, platforms, movement keys, jumping, or ground logic.

Choose this for:

• physics demonstrations
• visual simulations
• particle systems
• drawing tools
• cellular automata
• experimental canvas scenes

Topdown

Designed for overhead movement games.

TAPB additionally checks for:

• WASD or arrow-key movement logic
• absence of obvious jump or vertical-gravity logic

Choose this for maze games, overhead shooters, RPG-style movement, and similar projects.

Custom

Uses the least opinionated HTML/JavaScript validation. It keeps the general file, canvas, animation, and basic syntax checks but does not apply platformer, sandbox-specific, or top-down gameplay rules.

Choose this when the project does not fit the provided game categories but still uses an animated HTML canvas.

Python Validation

For Python targets, TAPB:

1. Finds generated .py files.
2. Uses main.py as the entry point when present; otherwise it uses the first Python file returned.
3. Runs py_compile to check syntax.
4. Launches the entry point for a short runtime test.
5. Treats a five-second timeout as a likely long-running GUI, game, or service rather than an automatic failure.

The Python validator does not install missing dependencies. A generated project can therefore pass syntax validation but still need packages installed manually.

Build and Repair Iterations

During the initial build, TAPB works in three phases.

Phase 1: Initial generation

The model receives the project specification and target type and returns complete files. TAPB writes them to the new project folder.

Phase 2: Validation

The local validator checks the generated files. Problems are displayed in the Log panel.

Phase 3: Repair

When validation fails and iterations remain, TAPB sends the following back to the model:

• the original project specification
• the target type
• the current project files
• the validator's issue list

The model returns full updated file contents. TAPB replaces the affected files and validates again.

This is an automated repair loop, not a guarantee that the generated program is correct. Always inspect and test generated code before relying on it.

Improve / Evolve Current Project

After a build finishes, TAPB keeps the current project in memory. The lower section of the application can then modify that same project.

Rounds

Controls how many improvement passes are requested. Each round sends the current files and the improvement prompt to the model, receives full-file patches, and writes those changes into the existing project folder.

Improvement Prompt

Describe the changes you want applied.

Example:

Add a title screen, pause support, three lives, a score counter, and clearer code comments.
Do not remove the current controls or level behavior.

Enhance Current Project

Runs the requested improvement rounds against the most recently built project.

Important behavior:

• You must build a project during the current TAPB session first.
• Improvements modify the existing generated project folder rather than creating a new timestamped copy.
• The improvement system expects full-file rewrites from the model.
• Improvement rounds do not run the same complete validation-and-repair loop used by Build Project.
• Make a backup or Git commit before large improvement runs when preserving the previous state matters.

Physics Audio Injection

The Auto-inject Physics Audio checkbox enables TAPB's optional JavaScript sound-support behavior.

During initial generation and repair:

1. TAPB checks whether the generated project contains:

   physicsEvents.js
   

2. When that file exists, TAPB looks for:

   game.js
   

3. It inserts a built-in SoundManager and several embedded audio placeholders at the top of game.js.

4. A marker prevents the same block from being inserted twice.

When physicsEvents.js does not exist, project-level sound injection is skipped.

During Enhance Current Project, the iterator may also add TAPB sound support to JavaScript files it rewrites. Leave the checkbox disabled when the generated project should manage audio entirely on its own.

Reading the Log

The log records:

• build settings
• project output location
• generated file count
• validation results
• detected issues
• repair requests
• improvement rounds
• sound-injection activity
• errors and Python tracebacks

When a project fails, the log is the first place to look.

Recommended Workflow

1. Start with a detailed project specification.
2. Use platformer, sandbox, topdown, or custom according to the intended HTML/JavaScript structure.
3. Keep the initial maximum iterations modest, such as 3 to 5.
4. Build and test the generated project manually.
5. Use focused improvement prompts rather than asking for many unrelated changes at once.
6. Commit working versions to Git before running major evolution passes.
7. Never publish API keys, private prompts, or sensitive generated data.

Project Files

START.bat                  Starts the TAPB GUI
tapbv3_2_2_2.py            Main GUI and build coordinator
llm_client.py              OpenAI requests and model response handling
validator.py               Python and HTML/JavaScript validation
iterator.py                Improvement/evolution rounds
sound_auto_injector.py     Conditional physics-audio injection
sound_injector.py          JavaScript sound-support injection helper
utils.py                   Output paths, naming, and JSON extraction
TAPB.spec                  PyInstaller build specification
.gitignore                 Excludes local/generated files from Git

Packaging with PyInstaller

The repository includes TAPB.spec for creating a packaged Windows build.

Install PyInstaller:

python -m pip install pyinstaller

Build from the repository root:

pyinstaller TAPB.spec

PyInstaller normally creates:

build\
dist\

Those directories are generated output and should not be committed to the main source repository. A packaged build can instead be attached to a GitHub Release.

Security Notes

• Keep API keys outside the repository.
• Review all model-generated code before running it.
• Generated programs may contain errors or unsafe behavior.
• TAPB executes generated Python entry points during validation, so only use specifications and models you trust, and inspect unfamiliar output when security matters.
• Do not use TAPB to process private source code unless you accept that the content is sent to the configured model provider.

Version

Thor Automated Program Builder v3.2.2.2 — Evolution Mode