Updating and versioning prompts

Nirmos separates logical prompt metadata from immutable prompt versions.

Use prompts.update for name, slug, description, organization, tags, folder, metadata, and lifecycle status.
Use prompts.versions.create for content or variable changes.
Use prompts.versions.activate to move production traffic to an approved version.

Update prompt metadata

const prompt = await nirmos.prompts.update("support-reply", {
  description: "Customer support response policy for production.",
  tags: ["support", "production", "reviewed"],
  folder: "customer-experience",
  metadata: {
    owner: "support-platform",
    reviewCadenceDays: 30,
  },
});

Metadata updates do not rewrite an immutable content version.

Create a version

const version = await nirmos.prompts.versions.create("support-reply", {
  content: {
    type: "chat",
    messages: [
      {
        role: "system",
        content: "Help {{customerName}} using policy {{policyVersion}}.",
      },
      {
        role: "developer",
        content: "Be concise. Never invent order status.",
      },
    ],
  },
  variables: [
    { name: "customerName", type: "string", required: true },
    { name: "policyVersion", type: "string", required: true },
  ],
  commitMessage: "Require explicit support policy version",
});

Create versions as drafts, test them, then activate the approved release.

List version history

let cursor: string | undefined;

do {
  const page = await nirmos.prompts.versions.list("support-reply", {
    limit: 20,
    cursor,
  });

  for (const version of page.data) {
    console.log(version.number, version.status, version.commitMessage);
  }

  cursor = page.nextCursor;
} while (cursor);

Retrieve one version

const version = await nirmos.prompts.versions.retrieve("support-reply", 8);

Activate a version

const active = await nirmos.prompts.versions.activate("support-reply", 8);

console.log(active.active); // true

Prompt mutations clear the client's in-memory prompt cache. Other running application instances observe the new active version after their local cache TTL expires, after a reload retrieval, or after explicit cache invalidation.

Roll forward

Prompt versions are immutable. If version 8 behaves poorly, activate a previously approved version or create version 9 with the correction. Do not mutate version 8 in place.