algal/sparky/solveit-tools

SolveIt Dialog Tools

Manipulate SolveIt dialogs (similar to Jupyter notebooks) via CLI. A dialog contains messages (cells) of type code, note (markdown), prompt (AI prompt/response), or raw.

Every command takes a dialog URL as its first argument and returns JSON to stdout.

Invocation

uv run {baseDir}/solveit_tools.py <command> [args...]

Commands

read_dialog — Read all messages

uv run {baseDir}/solveit_tools.py read_dialog "<url>"

Returns:

{
  "url": "...",
  "name": "my-project/experiment",
  "mode": "learning",
  "messages": [
    {"id": "_ea386899", "type": "note",   "index": 0, "content": "# Title"},
    {"id": "_f70704ce", "type": "code",   "index": 1, "content": "1+1", "output": "2"},
    {"id": "_b3796dd8", "type": "prompt", "index": 2, "content": "explain this", "output": "Sure..."}
  ]
}

Use id values to reference messages in other commands. The output field is omitted when empty.

add_message — Add a new message

# Append a code cell at the end (default)
uv run {baseDir}/solveit_tools.py add_message "<url>" "print('hello')"
 
# Add a note before a specific message
uv run {baseDir}/solveit_tools.py add_message "<url>" "# Section 2" --type note --placement before --ref-id "_f70704ce"
 
# Add a prompt after a specific message
uv run {baseDir}/solveit_tools.py add_message "<url>" "explain the error above" --type prompt --placement after --ref-id "_f70704ce"

Returns the new message: {"id": "_abc123", "type": "code", "content": "print('hello')"}.

exec_message — Execute a single message

uv run {baseDir}/solveit_tools.py exec_message "<url>" "_f70704ce"
uv run {baseDir}/solveit_tools.py exec_message "<url>" "_f70704ce" --timeout 120

Executes the message and waits for the result (default timeout: 60s). Returns the message with its output:

{"id": "_f70704ce", "type": "code", "content": "1+1", "output": "2"}

update_message — Change content or type

uv run {baseDir}/solveit_tools.py update_message "<url>" "_f70704ce" --content "2+2"
uv run {baseDir}/solveit_tools.py update_message "<url>" "_f70704ce" --type note

Provide --content, --type, or both. Returns the updated message.

delete_message — Remove a message

uv run {baseDir}/solveit_tools.py delete_message "<url>" "_ea386899"

Returns {"id": "_ea386899", "deleted": true}.

run_dialog — Execute the entire dialog

uv run {baseDir}/solveit_tools.py run_dialog "<url>"
uv run {baseDir}/solveit_tools.py run_dialog "<url>" --timeout 300

Runs all cells front-to-back using SolveIt's intelligent defaults: code cells are executed, prompt cells and cells with existing output are skipped. Default timeout: 120s.

Returns a summary:

{"executed": 3, "skipped": 5, "errors": 0}

Use read_dialog afterward to inspect the full results.

Typical workflow

1. Read the dialog to understand its current state
2. Add or update messages as needed
3. Execute individual messages with exec_message, or run everything with run_dialog
4. Read again to inspect outputs

Message types

Rules

• Always quote the URL in shell commands — it contains special characters (?, &, %).
• Message IDs look like _ea386899 (underscore + 8 hex chars). Always use the exact ID from read_dialog.
• After run_dialog, check results with read_dialog — the summary only shows counts.
• Errors from the tool are JSON on stderr: {"error": "..."}.