Use prompts in code

Retrieve and compile a versioned Judgment prompt with the Python SDK.

Retrieve a prompt at runtime when its text should be managed and promoted in Judgment instead of copied into application source. This guide uses the public Python prompt API to fetch a tagged version, compile its variables, and expose the exact commit used.

Prerequisites

Python with judgeval installed
JUDGMENT_API_KEY and JUDGMENT_ORG_ID configured as described in Authentication
The exact project name used when the prompt was created
A committed support-system-prompt version tagged production

Retrieve and compile the prompt

Create the project-scoped client

from judgeval import Judgeval


client = Judgeval(project_name="my-project")

The API key identifies the user, the organization ID selects the organization, and project_name selects the project that owns the prompt.

Retrieve the promoted version

prompt = client.prompts.get(
    name="support-system-prompt",
    tag="production",
)

if prompt is None:
    raise RuntimeError("The production prompt was not found")

A tag keeps the application on a reviewed version while allowing promotion without an application release.

Compile the variables

compiled = prompt.compile(
    tone="concise",
    product="Acme Search",
)

print(f"Using prompt commit {prompt.commit_id}")
print(compiled)

Pass compiled to the model client your application already uses. The prompt object also exposes its name, tags, creation time, parent commit ID, and stored template.

For the template from Create a prompt, the second line prints:

You are a concise support assistant for Acme Search.
Answer the customer's question using only the supplied context.

Pin or inspect another version

Only one selector can be used at a time:

# Follow every newly committed version.
latest = client.prompts.get(name="support-system-prompt")

# Reproduce one immutable version.
pinned = client.prompts.get(
    name="support-system-prompt",
    commit_id="<commit-id>",
)

# Inspect the complete history, newest first.
versions = client.prompts.list(name="support-system-prompt")
for version in versions or []:
    print(version.commit_id, version.tags)

Use latest retrieval for active development, a tag for controlled promotion, and a commit ID when reproducibility matters. Do not pass both tag and commit_id to the same lookup.

See the PromptFactory SDK reference for creation, tagging, untagging, retrieval, and listing signatures.

Troubleshooting

If retrieval returns None, verify the project name, prompt name, and tag in the platform. A removed tag no longer resolves to a version.
If .compile() raises ValueError, supply every variable shown in the prompt’s Variables section using the same name.
If code receives an unexpected version, print prompt.commit_id and compare it with the commit card carrying the requested tag.

Next step

Record prompt.commit_id with application telemetry so a production trace can be tied back to the exact prompt version that generated it.

Verify the code path

Run the script and confirm that it prints a commit ID followed by the compiled text with no {{tone}} or {{product}} placeholders. In Judgment, open the prompt and verify that the same commit ID carries the production tag.