Prompts

Version and share task criteria without coupling them to individual rows.

A prompt explains the semantic decision or transformation. Use a registered Prompt when several tasks should share one evolving instruction. Use a raw prompt string when the instruction belongs only to that task.

from scratchpad.api import Prompt, SemCluster

same_event = Prompt(
    id="same-news-event",
    text=(
        "Group headlines only when they report the same developing event. "
        "Do not merge broad themes, industries, or recurring seasons."
    ),
)

SemCluster(
    name="group-events",
    prompt=same_event,
    input_spaces=("headlines",),
    output_space="events",
    primary_key="headline",
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
)

Parameterized prompts

Use parameters when the criterion is structurally the same across tasks. The template remains one prompt identity; only the rendered value changes at execution.

Prompt(
    id="normalize-attribute",
    text="Normalize values for the {attribute_name} attribute.",
    params={"attribute_name": "material"},
)

Write an effective task prompt

• State the decision boundary before examples.
• Include positive and negative examples near difficult boundaries.
• Say what information must be preserved.
• Keep deterministic conditions out of the semantic criterion; use a predicate instead.
• Describe output fields for transformations.

Prompt suggestions belong to the prompt identity. When many tasks share one prompt, their reviewed counterexamples contribute to one suggestion rather than generating a separate rewrite for every task.

Inspect the exact revision

The version prompt list resolves every task to the revision it uses. Read that revision to inspect its authored text, every pipeline-version-task declaration bound to it, and the subset that has actually executed.

for binding in workspace.prompts("news-events", "v2"):
    revision = workspace.prompt(
        "news-events",
        binding["prompt_id"],
        binding["version"],
    )
    print(revision["text"])
    print(revision["bindings"])
    print(revision["usages"])

bindings is complete as soon as a version is registered and is the field to use for prompt-to-task navigation. usages lists tasks that have executed with the prompt: a bound task appears there only after it has run. Keeping the two fields separate means an unexecuted task is never mistaken for missing configuration, and a declaration is never mistaken for evidence that work ran.

Only user-authored task prompts appear here. Provider request wrappers and other managed instructions are not part of the workspace API.