Prompts

1
import { Opik, PromptType } from "opik";
2
3
const client = new Opik();
4
5
const prompt = await client.createPrompt({
6
  name: "greeting-prompt",
7
  prompt: "Hello {{name}}, your score is {{score}}",
8
  type: PromptType.MUSTACHE,
9
  metadata: { version: "1.0" },
10
  tags: ["greetings"],
11
  projectName: "my-project",
12
});
13
14
console.log(`Created prompt with version: ${prompt.version}`);

1
// Get latest version
2
const prompt = await client.getPrompt({ name: "greeting-prompt" });
3
4
if (prompt) {
5
  console.log(`Template: ${prompt.prompt}`);
6
  console.log(`Version: ${prompt.version}`);
7
}
8
9
// Get specific version by its sequential version identifier ("v<N>")
10
const oldVersion = await client.getPrompt({
11
  name: "greeting-prompt",
12
  version: "v1",
13
});

1
const prompt = await client.getPrompt({ name: "greeting-prompt" });
2
3
// Format with variables
4
const text = prompt.format({ name: "Alice", score: 95 });
5
// Returns: "Hello Alice, your score is 95"
6
7
// Format also works on PromptVersion objects
8
const versions = await prompt.getVersions();
9
const previousVersion = versions[1];
10
const oldText = previousVersion.format({ name: "Alice", score: 95 });

1
// Mustache syntax (default)
2
await client.createPrompt({
3
  name: "mustache-prompt",
4
  prompt: "Hello {{name}}, your score is {{score}}",
5
  type: PromptType.MUSTACHE,
6
  projectName: "my-project",
7
});
8
9
// Jinja2 syntax for advanced templating
10
await client.createPrompt({
11
  name: "jinja2-prompt",
12
  prompt: "Hello {{ name }}! {% if premium %}Premium user{% endif %}",
13
  type: PromptType.JINJA2,
14
  projectName: "my-project",
15
});

1
// First call - creates new prompt with version 1
2
const prompt1 = await client.createPrompt({
3
  name: "greeting-prompt",
4
  prompt: "Hello {{name}}, your score is {{score}}",
5
  type: PromptType.MUSTACHE,
6
  metadata: { version: "1.0" },
7
  tags: ["greetings"],
8
  projectName: "my-project",
9
});
10
11
// Same template, metadata, and type - returns existing version
12
const prompt2 = await client.createPrompt({
13
  name: "greeting-prompt",
14
  prompt: "Hello {{name}}, your score is {{score}}", // Same
15
  metadata: { version: "1.0" }, // Same
16
  type: PromptType.MUSTACHE, // Same
17
  tags: ["updated-tags"], // Different tags don't trigger new version
18
  projectName: "my-project",
19
});
20
console.log(prompt2.version === prompt1.version); // true
21
22
// Changed template - creates new version 2
23
const prompt3 = await client.createPrompt({
24
  name: "greeting-prompt",
25
  prompt: "Hi {{name}}, score: {{score}}", // Different template
26
  changeDescription: "Simplified greeting message",
27
  projectName: "my-project",
28
});
29
30
// Changed metadata - creates new version 3
31
const prompt4 = await client.createPrompt({
32
  name: "greeting-prompt",
33
  prompt: "Hi {{name}}, score: {{score}}", // Same as version 2
34
  metadata: { version: "2.0" }, // Different metadata triggers new version
35
  changeDescription: "Updated metadata",
36
  projectName: "my-project",
37
});

1
const prompt = await client.getPrompt({ name: "greeting-prompt" });
2
3
// Update name, description, or tags
4
await prompt.updateProperties({
5
  name: "welcome-prompt",
6
  description: "Updated greeting template",
7
  tags: ["welcome", "production", "v2"],
8
});
9
10
console.log(`Updated prompt name: ${prompt.name}`);

1
// Search all prompts (no filter)
2
const allPrompts = await client.searchPrompts();
3
4
// Search by exact name
5
const prompts = await client.searchPrompts('name = "greeting-prompt"');
6
7
// Search by name pattern
8
const chatPrompts = await client.searchPrompts('name contains "chat"');
9
10
// Search by tags
11
const prodPrompts = await client.searchPrompts('tags contains "production"');
12
13
// Search by creator
14
const myPrompts = await client.searchPrompts(
15
  'created_by = "alice@company.com"',
16
);
17
18
// Filter by prompt type
19
const chatPrompts = await client.searchPrompts('template_structure = "chat"');
20
const textPrompts = await client.searchPrompts('template_structure = "text"');
21
22
// Combine filters
23
const prodChatPrompts = await client.searchPrompts(
24
  'template_structure = "chat" AND tags contains "production"',
25
);

1
const prompt = await client.getPrompt({ name: "greeting-prompt" });
2
3
// Delete prompt and all its versions
4
await prompt.delete();
5
6
// Or delete multiple prompts by ID
7
await client.deletePrompts([prompt.id, anotherPrompt.id]);

1
const prompt = await client.getPrompt({ name: "greeting-prompt" });
2
const versions = await prompt.getVersions();
3
const latest = versions[0];
4
5
// Version properties
6
console.log(`ID: ${latest.id}`);
7
console.log(`Version: ${latest.version}`);
8
console.log(`Template: ${latest.prompt}`);
9
console.log(`Created: ${latest.createdAt}`);
10
console.log(`Creator: ${latest.createdBy}`);
11
console.log(`Type: ${latest.type}`);
12
console.log(`Change: ${latest.changeDescription}`);
13
14
// Formatted version info
15
console.log(latest.getVersionInfo());
16
// Output: [abc123de] 2024-01-15 by user@example.com - Initial version
17
18
// Human-readable age
19
console.log(latest.getVersionAge());
20
// Output: "2 days ago"

1
const prompt = await client.getPrompt({ name: "greeting-prompt" });
2
3
// Get all versions
4
const versions = await prompt.getVersions();
5
6
console.log(`Total versions: ${versions.length}`);
7
8
versions.forEach((version) => {
9
  console.log(version.getVersionInfo());
10
  // Output: [abc123de] 2024-01-15 by user@example.com - Initial version
11
});

1
// Option 1: Fetch a specific version straight from the client
2
const oldVersion = await client.getPrompt({
3
  name: "greeting-prompt",
4
  version: "v1",
5
});
6
7
if (oldVersion) {
8
  const text = oldVersion.format({ name: "Bob", score: 88 });
9
  console.log(`Version ${oldVersion.version} output: ${text}`);
10
}
11
12
// Option 2: From an existing prompt instance, pin to a specific version
13
const prompt = await client.getPrompt({ name: "greeting-prompt" });
14
const v1 = await prompt.getVersion("v1");
15
16
if (v1) {
17
  console.log(v1.format({ name: "Alice", score: 95 }));
18
}
19
20
// Option 3: Iterate version history and use format() directly on PromptVersion objects
21
const versions = await prompt.getVersions();
22
const previousVersion = versions[1];
23
24
// PromptVersion also has a format() method
25
const formattedText = previousVersion.format({ name: "Charlie", score: 92 });
26
console.log(formattedText);

1
const versions = await prompt.getVersions();
2
3
if (versions.length >= 2) {
4
  const current = versions[0]; // e.g. "v3"
5
  const previous = versions[1]; // e.g. "v2"
6
7
  // Compare versions (logs diff and returns it). Diff labels show the
8
  // sequential version identifiers (e.g. "[v3]" / "[v2]").
9
  const diff = current.compareTo(previous);
10
  console.log(diff);
11
  /* Output:
12
   * - Other version [v2]
13
   * + Current version [v3]
14
   * @@ -1,2 +1,2 @@
15
   * - Hello {{name}}, welcome!
16
   * + Hello {{name}}, your score is {{score}}
17
   */
18
}

1
const prompt = await client.getPrompt({ name: "greeting-prompt" });
2
const versions = await prompt.getVersions();
3
4
// Pick the version you want to restore — for example, the previous one
5
const [, previousVersion] = versions;
6
7
if (previousVersion) {
8
  // Restore creates a new version with the old content
9
  const restoredPrompt = await prompt.useVersion(previousVersion);
10
11
  console.log(`Restored to version: ${restoredPrompt.version}`);
12
  console.log(`Template: ${restoredPrompt.prompt}`);
13
}

1
import { Opik, track } from "opik";
2
3
const client = new Opik();
4
5
@track
6
async function generateGreeting(userName: string, userScore: number) {
7
  // Get the prompt
8
  const prompt = await client.getPrompt({ name: "greeting-prompt" });
9
10
  // Format it
11
  const message = prompt.format({
12
    name: userName,
13
    score: userScore,
14
  });
15
16
  // Use with your LLM
17
  const response = await llmClient.complete(message);
18
19
  return response;
20
}

1
// prompts/greeting.ts
2
export const GREETING_TEMPLATE = "Hello {{name}}, your score is {{score}}";
3
4
// In your application
5
import { GREETING_TEMPLATE } from "./prompts/greeting";
6
7
const prompt = await client.createPrompt({
8
  name: "greeting",
9
  prompt: GREETING_TEMPLATE,
10
  metadata: { version: "1.0" },
11
  projectName: "my-project",
12
});

1
const prompt = await client.createPrompt({
2
  name: "summary-prompt",
3
  prompt: updatedTemplate,
4
  changeDescription: "Added support for multi-language summaries",
5
  metadata: { sprint: "Q1-2024" },
6
  projectName: "my-project",
7
});

1
const prompt = await client.createPrompt({
2
  name: "production-greeting",
3
  prompt: template,
4
  tags: ["production", "customer-facing", "v2"],
5
  projectName: "my-project",
6
});
7
8
// Later, search by tags
9
const prodPrompts = await client.searchPrompts('tags contains "production"');

1
import { Opik, PromptType } from "opik";
2
3
const client = new Opik();
4
5
// Define chat messages with variables
6
const messages = [
7
  {
8
    role: "system",
9
    content: "You are a helpful assistant specializing in {{domain}}.",
10
  },
11
  {
12
    role: "user",
13
    content: "Explain {{topic}} in simple terms.",
14
  },
15
];
16
17
// Create a chat prompt
18
const chatPrompt = await client.createChatPrompt({
19
  name: "educational-assistant",
20
  messages: messages,
21
  type: PromptType.MUSTACHE,
22
  metadata: { category: "education" },
23
  tags: ["education", "assistant"],
24
  projectName: "my-project",
25
});
26
27
console.log(`Created chat prompt with version: ${chatPrompt.version}`);

1
const chatPrompt = await client.getChatPrompt({
2
  name: "educational-assistant",
3
});
4
5
if (chatPrompt) {
6
  // Format the messages with variables
7
  const formattedMessages = chatPrompt.format({
8
    domain: "physics",
9
    topic: "quantum entanglement",
10
  });
11
12
  console.log(formattedMessages);
13
  // Output:
14
  // [
15
  //   { role: "system", content: "You are a helpful assistant specializing in physics." },
16
  //   { role: "user", content: "Explain quantum entanglement in simple terms." }
17
  // ]
18
}

1
const messages = [
2
  {
3
    role: "system",
4
    content: "You are a customer support agent for {{company}}.",
5
  },
6
  {
7
    role: "user",
8
    content: "I have an issue with {{product}}.",
9
  },
10
  {
11
    role: "assistant",
12
    content: "I'd be happy to help with your {{product}}. Can you describe the issue?",
13
  },
14
  {
15
    role: "user",
16
    content: "{{issue_description}}",
17
  },
18
];
19
20
const chatPrompt = await client.createChatPrompt({
21
  name: "customer-support-flow",
22
  messages: messages,
23
  projectName: "my-project",
24
});
25
26
// Format with specific values
27
const formatted = chatPrompt.format({
28
  company: "Acme Corp",
29
  product: "Widget Pro",
30
  issue_description: "It won't turn on",
31
});

1
// Chat prompt with image content
2
const messages = [
3
  {
4
    role: "system",
5
    content: "You analyze images and provide detailed descriptions.",
6
  },
7
  {
8
    role: "user",
9
    content: [
10
      { type: "text", text: "What's in this image of {{subject}}?" },
11
      {
12
        type: "image_url",
13
        image_url: {
14
          url: "{{image_url}}",
15
          detail: "high",
16
        },
17
      },
18
    ],
19
  },
20
];
21
22
const chatPrompt = await client.createChatPrompt({
23
  name: "image-analyzer",
24
  messages: messages,
25
  projectName: "my-project",
26
});
27
28
// Format with variables
29
const formatted = chatPrompt.format(
30
  {
31
    subject: "a sunset",
32
    image_url: "https://example.com/sunset.jpg",
33
  },
34
  { vision: true }, // Supported modalities
35
);

1
// Chat prompt with video content
2
const messages = [
3
  {
4
    role: "system",
5
    content: "You analyze videos and provide insights.",
6
  },
7
  {
8
    role: "user",
9
    content: [
10
      { type: "text", text: "Analyze this video: {{description}}" },
11
      {
12
        type: "video_url",
13
        video_url: {
14
          url: "{{video_url}}",
15
          mime_type: "video/mp4",
16
        },
17
      },
18
    ],
19
  },
20
];
21
22
const chatPrompt = await client.createChatPrompt({
23
  name: "video-analyzer",
24
  messages: messages,
25
  projectName: "my-project",
26
});
27
28
// Format with variables
29
const formatted = chatPrompt.format(
30
  {
31
    description: "traffic analysis",
32
    video_url: "https://example.com/traffic.mp4",
33
  },
34
  { vision: true, video: true },
35
);

1
// Chat prompt with multiple images and text
2
const messages = [
3
  {
4
    role: "user",
5
    content: [
6
      { type: "text", text: "Compare these two images:" },
7
      {
8
        type: "image_url",
9
        image_url: { url: "{{image1_url}}" },
10
      },
11
      { type: "text", text: "and" },
12
      {
13
        type: "image_url",
14
        image_url: { url: "{{image2_url}}" },
15
      },
16
      { type: "text", text: "What are the main differences?" },
17
    ],
18
  },
19
];
20
21
const chatPrompt = await client.createChatPrompt({
22
  name: "image-comparison",
23
  messages: messages,
24
  projectName: "my-project",
25
});
26
27
const formatted = chatPrompt.format(
28
  {
29
    image1_url: "https://example.com/before.jpg",
30
    image2_url: "https://example.com/after.jpg",
31
  },
32
  { vision: true },
33
);

1
// Get latest version
2
const chatPrompt = await client.getChatPrompt({
3
  name: "educational-assistant",
4
});
5
6
if (chatPrompt) {
7
  console.log(`Messages: ${JSON.stringify(chatPrompt.messages)}`);
8
  console.log(`Version: ${chatPrompt.version}`);
9
}
10
11
// Get specific version by its sequential version identifier ("v<N>")
12
const oldVersion = await client.getChatPrompt({
13
  name: "educational-assistant",
14
  version: "v1",
15
});

1
// Search for only chat prompts
2
const chatPrompts = await client.searchPrompts(
3
  'template_structure = "chat" AND name contains "assistant"',
4
);
5
6
for (const prompt of chatPrompts) {
7
  console.log(`Chat prompt: ${prompt.name}`);
8
}
9
10
// Search for text prompts only
11
const textPrompts = await client.searchPrompts('template_structure = "text"');

1
import { PromptType } from "opik";
2
3
const messages = [
4
  {
5
    role: "user",
6
    content: "Hello {{name}}, you live in {{city}}.",
7
  },
8
];
9
10
const chatPrompt = await client.createChatPrompt({
11
  name: "mustache-example",
12
  messages: messages,
13
  type: PromptType.MUSTACHE, // Default
14
  projectName: "my-project",
15
});
16
17
const formatted = chatPrompt.format({
18
  name: "Alice",
19
  city: "Paris",
20
});
21
// Result: [{ role: "user", content: "Hello Alice, you live in Paris." }]

1
import { PromptType } from "opik";
2
3
const messages = [
4
  {
5
    role: "user",
6
    content: `
7
      {% if is_premium %}
8
      Hello {{ name }}, welcome to our premium service!
9
      {% else %}
10
      Hello {{ name }}, welcome!
11
      {% endif %}
12
    `,
13
  },
14
];
15
16
const chatPrompt = await client.createChatPrompt({
17
  name: "jinja-example",
18
  messages: messages,
19
  type: PromptType.JINJA2,
20
  projectName: "my-project",
21
});
22
23
// With premium user
24
const formatted1 = chatPrompt.format({
25
  name: "Alice",
26
  is_premium: true,
27
});
28
// Result includes: "Hello Alice, welcome to our premium service!"
29
30
// With regular user
31
const formatted2 = chatPrompt.format({
32
  name: "Bob",
33
  is_premium: false,
34
});
35
// Result includes: "Hello Bob, welcome!"

1
// Create initial version
2
const messagesV1 = [
3
  { role: "system", content: "You are helpful." },
4
  { role: "user", content: "Hi!" },
5
];
6
7
const chatPrompt = await client.createChatPrompt({
8
  name: "greeting-prompt",
9
  messages: messagesV1,
10
  projectName: "my-project",
11
});
12
13
console.log(`Created ${chatPrompt.version}`);
14
15
// Update with new messages - creates new version
16
const messagesV2 = [
17
  { role: "system", content: "You are a helpful assistant." },
18
  { role: "user", content: "Hello {{name}}!" },
19
];
20
21
const chatPromptV2 = await client.createChatPrompt({
22
  name: "greeting-prompt",
23
  messages: messagesV2,
24
  changeDescription: "Added personalization with name variable",
25
  projectName: "my-project",
26
});
27
28
console.log(`Created ${chatPromptV2.version}`);
29
30
// Get version history
31
const versions = await chatPrompt.getVersions();
32
console.log(`Total versions: ${versions.length}`);

1
const chatPrompt = await client.getChatPrompt({
2
  name: "greeting-prompt",
3
});
4
5
// Get all versions
6
const versions = await chatPrompt.getVersions();
7
8
// Get a specific version by its sequential identifier ("v<N>")
9
const oldVersion = await client.getChatPrompt({
10
  name: "greeting-prompt",
11
  version: "v1",
12
});
13
14
// Compare versions
15
if (versions.length >= 2) {
16
  const current = versions[0];
17
  const previous = versions[1];
18
  const diff = current.compareTo(previous);
19
  console.log(diff);
20
}
21
22
// Restore the previous version
23
const [, previousVersion] = versions;
24
if (previousVersion) {
25
  const restoredPrompt = await chatPrompt.useVersion(previousVersion);
26
  console.log(`Restored to version: ${restoredPrompt.version}`);
27
}

1
const chatPrompt = await client.getChatPrompt({
2
  name: "greeting-prompt",
3
});
4
5
// Update name, description, or tags
6
await chatPrompt.updateProperties({
7
  name: "welcome-prompt",
8
  description: "Updated greeting template",
9
  tags: ["welcome", "production", "v2"],
10
});
11
12
console.log(`Updated prompt name: ${chatPrompt.name}`);

1
// Replace all tags on multiple versions (default behavior)
2
await client.updatePromptVersionTags(["version-id-1", "version-id-2"], {
3
  tags: ["production", "v2"],
4
});
5
6
// Merge new tags with existing tags
7
await client.updatePromptVersionTags(["version-id-1"], {
8
  tags: ["hotfix"],
9
  mergeTags: true,
10
});
11
12
// Clear all tags
13
await client.updatePromptVersionTags(["version-id-1"], {
14
  tags: [],
15
});

1
interface ChatMessage {
2
  role: "system" | "user" | "assistant";
3
  content: string | ContentPart[];
4
}
5
6
interface ContentPart {
7
  type: "text" | "image_url" | "video_url";
8
  text?: string; // For text type
9
  image_url?: { url: string; detail?: string }; // For image_url type
10
  video_url?: { url: string; mime_type?: string }; // For video_url type
11
}

1
// Get all versions
2
const versions = await prompt.getVersions();
3
4
// Search by template or change description content
5
const searched = await prompt.getVersions({ search: "customer" });
6
7
// Filter by tag
8
const prodVersions = await prompt.getVersions({
9
  filters: JSON.stringify([
10
    { field: "tags", operator: "contains", value: "production" },
11
  ]),
12
});
13
14
// Filter by multiple tags (AND logic)
15
const stable = await prompt.getVersions({
16
  filters: JSON.stringify([
17
    { field: "tags", operator: "contains", value: "production" },
18
    { field: "tags", operator: "contains", value: "stable" },
19
  ]),
20
});
21
22
// Filter by template content
23
const customerVersions = await prompt.getVersions({
24
  filters: JSON.stringify([
25
    { field: "template", operator: "contains", value: "customer" },
26
  ]),
27
});
28
29
// Filter by date
30
const recentVersions = await prompt.getVersions({
31
  filters: JSON.stringify([
32
    { field: "created_at", operator: ">=", value: "2024-01-01T00:00:00Z" },
33
  ]),
34
});
35
36
// Sort by creation date (oldest first)
37
const oldest = await prompt.getVersions({
38
  sorting: JSON.stringify([{ field: "created_at", direction: "ASC" }]),
39
});
40
41
// Sort alphabetically by template content
42
const alphabetical = await prompt.getVersions({
43
  sorting: JSON.stringify([{ field: "template", direction: "ASC" }]),
44
});
45
46
// Combine search, filter, and sort
47
const results = await prompt.getVersions({
48
  search: "customer",
49
  filters: JSON.stringify([
50
    { field: "tags", operator: "contains", value: "production" },
51
  ]),
52
  sorting: JSON.stringify([{ field: "created_at", direction: "DESC" }]),
53
});

1
// Preferred: fetch by sequential version identifier
2
const v3 = await prompt.getVersion("v3");
3
4
// Deprecated: fetch by commit hash
5
const byCommit = await prompt.getVersion("abc123de");

1
interface SupportedModalities {
2
  vision?: boolean; // Support for image content (default: true)
3
  video?: boolean; // Support for video content (default: true)
4
}

1
const formatted = chatPrompt.format(
2
  { name: "Alice", topic: "AI" },
3
  { vision: true, video: false },
4
);

1
// Preferred: fetch by sequential version identifier
2
const v3 = await chatPrompt.getVersion("v3");
3
4
// Deprecated: fetch by commit hash
5
const byCommit = await chatPrompt.getVersion("abc123de");