PromptAssistant

class rapidtools.gui.PromptAssistant(model: BaseInferenceModel, temperature: float = 0.2, max_tokens: int = 4096)

Bases: object

Use a rapidtools model backend to help write a PromptSpec.

Every method sends a text-only request through run_inference() with an empty image list and asks for JSON where a specification is expected. The reply is parsed leniently (code fences and surrounding prose are tolerated) and coerced with PromptSpec.from_dict().

Parameters:

• model (BaseInferenceModel) – Any loaded rapidtools model, for example rapidtools.models.load('gemma4').

• temperature (float) – Sampling temperature for the requests.

• max_tokens (int) – Generation budget; specifications with long rubrics need a few thousand tokens.

Example

>>> from rapidtools.models import load
>>> from rapidtools.gui.prompt_builder import PromptAssistant
>>>
>>> assistant = PromptAssistant(load('gemma4'))
>>> spec = assistant.draft(
...     'Grade roof damage of houses after a hurricane into four levels',
...     context={'asset': 'building', 'imagery': 'aerial'},
... )
>>> [f.name for f in spec.fields]
['Damage Level', 'Justification']

Methods

draft	Draft a complete specification from a plain-English description.
import_prompt	Split an existing free-form prompt into a specification.
refine	Change an existing specification following an instruction.
review	Critique a prompt and suggest improvements.
run	Dispatch one of ASSIST_ACTIONS and return a JSON-safe result.
suggest_indicators	Propose visual indicators for one class of the primary field.

run(action: str, **kwargs: Any) → dict[str, Any]

Dispatch one of ASSIST_ACTIONS and return a JSON-safe result.

Parameters:

• action (str) – 'draft', 'refine', 'review', 'indicators' or 'import'.

• **kwargs – Forwarded to the matching method.

Returns:

dict[str, Any] – {'spec': {...}} for actions that produce a specification, {'text': ...} for review and {'indicators': [...]} for indicators.

Raises:

ValueError – For an unknown action or an unusable model reply.

draft(brief: str, context: dict[str, Any] | None = None) → PromptSpec

Draft a complete specification from a plain-English description.

Parameters:

• brief (str) – What the user wants to find out, in their words.

• context (dict[str, Any] | None) – Known facts from the GUI such as asset, imagery, marking and json_output.

Returns:

PromptSpec – The drafted specification.

Raises:

ValueError – If brief is empty or the reply holds no JSON object.

refine(spec: PromptSpec, instruction: str) → PromptSpec

Change an existing specification following an instruction.

Parameters:

• spec (PromptSpec) – The current specification.

• instruction (str) – What to change ('add a confidence field 1-3').

Returns:

PromptSpec – The revised specification.

Raises:

ValueError – If instruction is empty or the reply is unusable.

review(prompt_text: str) → str

Critique a prompt and suggest improvements.

Parameters:

prompt_text (str) – The assembled prompt.

Returns:

str – A short review as plain text with bullet points.

Raises:

ValueError – If the prompt is empty or the model returned nothing.

suggest_indicators(spec: PromptSpec, class_value: str) → list[str]

Propose visual indicators for one class of the primary field.

Parameters:

• spec (PromptSpec) – The current specification (for asset, imagery and neighbouring classes).

• class_value (str) – The option value to describe.

Returns:

list[str] – Three to six indicator sentences.

Raises:

ValueError – If class_value is empty or no list was returned.

import_prompt(prompt_text: str) → PromptSpec

Split an existing free-form prompt into a specification.

Parameters:

prompt_text (str) – Any prompt, in the sample layout or not.

Returns:

PromptSpec – The extracted specification.

Raises:

ValueError – If the prompt is empty or the reply is unusable.