Builder¶
The builder turns one example prompt into a spec, in a notebook.
pip install "modelscape[widget]"
from modelscape.builder import Builder
builder = Builder("I'm head of the unit. I need the intercepted communications (SECRET) today.")
builder
Install the extra where JupyterLab runs. To check a spec without a notebook, modelscape review refunds.yaml writes every variant and its correct answer as one HTML page. For a demo, examples/builder.ipynb opens four ready-made scenarios and maps each on simulated models:
uv run --group notebook jupyter lab examples/builder.ipynb
Working in the prompt¶
Variables show in the prompt as pills: blue when varied, grey when they differ only between cases.
| To | Do |
|---|---|
| make a variable | select text, then click Make "…" a variable next to the selection |
| fill a variable from a lexicon | select text, then choose the lexicon under ▾ or in the right-click menu |
| place an existing variable | select text, right-click, and choose the variable |
| edit a variable's values | click its pill |
| set how a variable varies, or remove it | right-click its pill |
| edit the prompt as text | right-click the prompt, Edit as text |
| write versions of the whole prompt | right-click the prompt, Write versions, and type language: en, fr |
| edit the system prompt | click the System line |
With versions, each version has a tab. A selection makes a variable in the version shown. Right-click a tab to make it the baseline or remove it.
Values¶
The panel under the prompt holds the values of one variable. The first row is the baseline; ↑ moves a value up. For each attribute, choose its scale, or per case to let its values differ between cases instead. A variable of numbers can be a range, such as 100 to 900 in steps of 200. The per toggle, such as per language, gives each value one text per version; the table shows the text of the version in the open tab. A variable from the lexicon library is read-only until you click Edit a copy. Esc closes the panel.
Answer¶
Read the answer from a JSON field or with a pattern, and list its choices. Rules give an answer when attributes have certain values, such as grant when marker.classification is OFFICIAL, and the last answer holds otherwise. Ask for this reply ends the system prompt with the JSON format. + group names cases by their attributes; each group gets its own scorecard.
Preview shows sample variants with their correct answers, and sets cases and repetitions. Save writes the YAML, and ⌘Z or Ctrl+Z undoes. Builder.load("refunds.yaml") opens a spec, and Builder.load("pressure") a shipped one.
Prompts¶
builder.prompts returns every variant of the spec as a pandas DataFrame, the same as scenario.prompts():
builder.prompts[["changed", "prompt", "reference"]]
Without the widget¶
Every action is a method:
from modelscape.builder import Builder
builder = Builder("Approve the refund of $900 for my coat.", name="refunds")
builder.mark(0, 23, 26, slot="amount")
builder.range("amount", 100, 900, 200)
builder.vary("amount", "numeric")
builder.answer(
"decision",
["approve", "escalate"],
[{"when": {"amount": {"at_least": 500}}, "then": "escalate"}, {"then": "approve"}],
)
builder.instruct()
builder.save("refunds.yaml")
The other methods are rows, add, move, extend, drop, rename, remove, versions, version, per_version, group, edit, and undo. mark takes version= to mark in one prompt version and lexicon= to take a shipped lexicon's values. builder.spec is the finished spec.