FORGE Studio

Appearance

Dev Tool: forge-session ​

scripts/forge-session.mjs is a command-line tool for testing and interactively troubleshooting FORGE backend modules without launching the full Electron app.

It speaks the same FORGE_RESP: protocol as FORGE Studio, so your module behaves identically in both contexts.

Usage ​

bash
node scripts/forge-session.mjs --python [path]  [--test | --repl] [--module <path>]
node scripts/forge-session.mjs --julia  [path]  [--test | --repl] [--module <path>]
node scripts/forge-session.mjs --matlab [path]  [--test | --repl] [--module <path>]

If the executable path is omitted, the tool looks for python3, julia, or matlab on PATH (or PYTHON/JULIA/MATLAB environment variables).

Test Mode (default) ​

Runs the minimal_module example (or a custom --module) automatically, reports pass/fail, and exits:

bash
# Python (using project venv)
node scripts/forge-session.mjs --python .venv/bin/python3

# Julia
node scripts/forge-session.mjs --julia /Applications/Julia-1.11.app/Contents/Resources/julia/bin/julia

# Custom module
node scripts/forge-session.mjs --python .venv/bin/python3 \
  --module resources/python/examples/iterative_recon_module.py

Example output:

[forge-session] Backend : python
[forge-session] Session ready.

→ {"type":"ping"}
[pong] Session alive.

[forge-session] Running module: .../minimal_module.py

→ {"type":"run",...}
  [info] minimal_module: starting
  [info] minimal_module: done, wrote result.npy
[ok] output_paths: ["/tmp/forge-session-123/result.npy"]

─────────────────────────────────────────
✓ PASS  (7ms)
  Outputs: /tmp/forge-session-123/result.npy
─────────────────────────────────────────

REPL Mode ​

Drops into an interactive prompt after the session is ready. Use this to run modules, inspect responses, and debug your code:

bash
node scripts/forge-session.mjs --python .venv/bin/python3 --repl
─────────────────────────────────────────────────────────────────
 FORGE Session REPL
 Commands: ping | run <module_path> [config_path] | addpath <path> | quit
 Or type raw JSON: {"type":"ping"}
─────────────────────────────────────────────────────────────────

python> ping
→ {"type":"ping"}
[pong] Session alive.

python> run resources/python/examples/minimal_module.py
[forge-session] Wrote temp config: /tmp/forge-session-456/_step_config_test-step.json
→ {"type":"run","job_id":"repl-job","module_path":"...","config_path":"..."}
  [info] minimal_module: starting
  [info] minimal_module: done, wrote result.npy
[ok] output_paths: ["/tmp/forge-session-456/result.npy"]

python> run my_module.py /tmp/my_config.json
→ {"type":"run",...}
...

python> quit

REPL Commands ​

CommandDescription
pingCheck session is alive
run <module_path> [config_path]Run a module. If no config path is given, a minimal config is generated automatically in a temp directory.
addpath <dir>Add a directory to the interpreter's module search path
quit / exitShut down the session
{ ... }Send raw JSON command directly

Config Auto-Generation ​

When you run a module without providing a config path, the tool creates a minimal config:

json
{
  "job_id": "repl-job",
  "step_id": "test-step",
  "stage_index": 0,
  "input_paths": [],
  "output_dir": "/tmp/forge-session-<timestamp>",
  "input_format": "ismrmrd",
  "params": {}
}

To test with real parameters, write a config JSON manually and pass its path:

python> run my_module.py /path/to/my_config.json

Providing a Real Config ​

Create a JSON file with the fields your module expects:

json
{
  "job_id": "dev-test",
  "step_id": "espirit_calib",
  "stage_index": 0,
  "input_paths": ["/data/meas_MID00107.dat"],
  "output_dir": "/tmp/dev-output",
  "input_format": "twix",
  "channels": 32,
  "params": {
    "calibration_size": 24,
    "use_gpu": true
  }
}

Then in the REPL:

python> run resources/python/examples/espirit_calib.py /tmp/dev_config.json

Integrating from an Existing Session ​

If you already have a Python/Julia/MATLAB session open (e.g. in an IDE), you can call your module's run() function directly and mock the config path:

Python:

python
import sys
sys.path.insert(0, '/path/to/forge-studio/resources/python')
from my_module import run

# Point to a hand-written config file:
output_paths = run('/tmp/dev_config.json')

Julia:

julia
push!(LOAD_PATH, "/path/to/forge-studio/resources/julia")
using ForgeStudio

include("my_module.jl")
output_paths = run("/tmp/dev_config.json")

MATLAB:

matlab
addpath('/path/to/forge-studio/resources/matlab')
output_paths = my_module('/tmp/dev_config.json')

All forge_* functions degrade gracefully outside a session (printing to stderr), so you get readable output without any FORGE Studio infrastructure.

FORGE Studio