Prompt Data Model

The Prompt Object

A XeroML prompt is a combination of the instructions you send to the LLM and optional configuration (model parameters, metadata). The core attributes are:

Attribute	Description
name	Unique identifier within the project
type	text or chat — cannot be changed after creation
prompt	The prompt content (string for text, message array for chat)
version	Immutable integer, auto-incremented on each save
labels	Array of string labels pointing to this version
config	Optional model config (temperature, max_tokens, model name)
metadata	Arbitrary key-value data

Prompt Types

Text Prompts

A text prompt is a single string. Use this for:

• System messages passed directly to the model
• Templates for user-facing prompts
• Simple completion tasks

You are a financial analyst specializing in {{sector}} markets.
Analyze the following data and provide a {{length}} summary:

{{data}}

Chat Prompts

A chat prompt is an array of messages with role fields (system, user, assistant). Use this for:

• Conversation setups with example exchanges
• Multi-role templates
• Few-shot prompting patterns

[
  {"role": "system", "content": "You are a helpful assistant for {{company}}."},
  {"role": "user",   "content": "How do I reset my password?"},
  {"role": "assistant", "content": "I can help you reset your password. First, click 'Forgot Password' on the login page."},
  {"role": "user",   "content": "{{user_message}}"}
]

The type field is immutable — once a prompt is created as text or chat, it cannot be converted.

Dynamic Content

Variables

Variables are placeholders using double-brace syntax: {{variable_name}}. At runtime, call .compile(variable=value) to substitute them.

Variables can appear anywhere in the prompt text, including inside message content for chat prompts.

Prompt References

Include another prompt inside your prompt to avoid duplicating shared instructions. References are resolved at fetch time, so changes to the referenced prompt propagate automatically.

{{>shared-instructions}}

Now, given the above context, answer the following question:
{{user_question}}

Message Placeholders

For chat prompts, insert a block of messages (e.g., conversation history) at a specific position using a placeholder:

[
  {"role": "system", "content": "You are a helpful assistant."},
  {"type": "placeholder", "variable": "{{history}}"},
  {"role": "user", "content": "{{current_message}}"}
]

At runtime, pass the history array as the history variable to .compile().

Versioning

Every save creates a new version — an immutable snapshot of the prompt content and config. Versions are numbered sequentially starting at 1.

Versions are permanent. You cannot delete a version (to ensure traceability of which version produced which traces). You can archive them to hide from the UI.

Labels

Labels are mutable pointers to specific versions. Your application code fetches a prompt by label name, not by version number. This is what enables zero-downtime prompt deployments.

Built-in labels:

• production — the version your application should use in production
• latest — automatically updated to the most recent version on every save

Custom labels:

• staging, experiment-a, shadow, anything you define

Deployment workflow:

1. Create a new version (edit the prompt and save)
2. Test in the Playground
3. Update the production label to point to the new version
4. All running instances pick up the new version on their next cache refresh

To roll back: point production back to the previous version number.

Caching

The XeroML SDK caches prompts client-side after the first fetch. The default TTL is 300 seconds (5 minutes). During this window, the SDK serves the cached version without hitting the network.

See Caching for configuration and tradeoffs.