Managed prompts

A managed prompt stores model instructions, message templates, variables, metadata, and immutable versions in Nirmos. Applications reference a stable prompt ID or slug instead of embedding prompt text in source code.

This separation lets prompt owners:

• improve instructions without application redeployment
• review and activate a specific production version
• share one prompt across services
• track prompt metadata and version history
• roll forward by activating a new version
• keep application code focused on runtime data

Prompt structure

A retrieved Prompt contains logical prompt data and one resolved version:

type Prompt = {
  id: string;
  name: string;
  slug: string;
  description?: string;
  status: string;
  version: PromptVersion;
  content: PromptContent;
  variables: PromptVariable[];
  metadata: Record<string, JsonValue>;
  tags: string[];
  folder?: string;
  requestMetadata: RequestMetadata;
};

Content can be one text template:

{
  type: "text",
  role: "system",
  text: "Reply to {{customerName}} using a {{tone}} tone."
}

Or a chat template:

{
  type: "chat",
  messages: [
    { role: "system", content: "You are the support assistant for {{company}}." },
    { role: "developer", content: "Use policy version {{policyVersion}}." }
  ]
}

Production flow

1. Create a logical prompt and initial version.
2. Test the version against representative inputs.
3. Activate the approved version.
4. Applications retrieve the active version by prompt ID or slug.
5. Create a new immutable version for later changes.
6. Activate it when ready; applications pick it up after their configured cache TTL.

For AI requests, pass a prompt reference directly:

await nirmos.gateway.chat.create({
  model: "openai/gpt-4.1-mini",
  prompt: {
    id: "support-reply",
    variables: { customerName: "Mira", tone: "warm" },
  },
  messages: [{ role: "user", content: ticket.body }],
});

The prompt reference defaults to the active version. Pin an explicit version when reproducibility is more important than automatic updates.