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
});
12
13
console.log(`Created prompt with commit: ${prompt.commit}`);

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(`Commit: ${prompt.commit}`);
7
}
8
9
// Get specific version
10
const oldVersion = await client.getPrompt({
11
  name: "greeting-prompt",
12
  commit: "abc123de",
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
});
7
8
// Jinja2 syntax for advanced templating
9
await client.createPrompt({
10
  name: "jinja2-prompt",
11
  prompt: "Hello {{ name }}! {% if premium %}Premium user{% endif %}",
12
  type: PromptType.JINJA2,
13
});

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
});
9
10
// Same template, metadata, and type - returns existing version
11
const prompt2 = await client.createPrompt({
12
  name: "greeting-prompt",
13
  prompt: "Hello {{name}}, your score is {{score}}", // Same
14
  metadata: { version: "1.0" }, // Same
15
  type: PromptType.MUSTACHE, // Same
16
  tags: ["updated-tags"], // Different tags don't trigger new version
17
});
18
console.log(prompt2.commit === prompt1.commit); // true
19
20
// Changed template - creates new version 2
21
const prompt3 = await client.createPrompt({
22
  name: "greeting-prompt",
23
  prompt: "Hi {{name}}, score: {{score}}", // Different template
24
  changeDescription: "Simplified greeting message",
25
});
26
27
// Changed metadata - creates new version 3
28
const prompt4 = await client.createPrompt({
29
  name: "greeting-prompt",
30
  prompt: "Hi {{name}}, score: {{score}}", // Same as version 2
31
  metadata: { version: "2.0" }, // Different metadata triggers new version
32
  changeDescription: "Updated metadata",
33
});

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(`Commit: ${latest.commit}`);
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
const prompt = await client.getPrompt({ name: "greeting-prompt" });
2
3
// Option 1: Get version as Prompt instance (recommended for formatting)
4
const oldVersion = await prompt.getVersion("abc123de");
5
6
if (oldVersion) {
7
  const text = oldVersion.format({ name: "Bob", score: 88 });
8
  console.log(`Old version output: ${text}`);
9
}
10
11
// Option 2: Use format directly on PromptVersion objects
12
const versions = await prompt.getVersions();
13
const secondVersion = versions[1];
14
15
// PromptVersion also has format() method
16
const formattedText = secondVersion.format({ name: "Charlie", score: 92 });
17
console.log(`Version ${secondVersion.commit}: ${formattedText}`);

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

1
const prompt = await client.getPrompt({ name: "greeting-prompt" });
2
const versions = await prompt.getVersions();
3
4
// Find specific version to restore
5
const targetVersion = versions.find((v) => v.commit === "abc123de");
6
7
if (targetVersion) {
8
  // Restore creates a new version with the old content
9
  const restoredPrompt = await prompt.useVersion(targetVersion);
10
11
  console.log(`Restored to commit: ${restoredPrompt.commit}`);
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
});

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
});

1
const prompt = await client.createPrompt({
2
  name: "production-greeting",
3
  prompt: template,
4
  tags: ["production", "customer-facing", "v2"],
5
});
6
7
// Later, search by tags
8
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
});
25
26
console.log(`Created chat prompt with commit: ${chatPrompt.commit}`);

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
});
24
25
// Format with specific values
26
const formatted = chatPrompt.format({
27
  company: "Acme Corp",
28
  product: "Widget Pro",
29
  issue_description: "It won't turn on",
30
});

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
});
26
27
// Format with variables
28
const formatted = chatPrompt.format(
29
  {
30
    subject: "a sunset",
31
    image_url: "https://example.com/sunset.jpg",
32
  },
33
  { vision: true }, // Supported modalities
34
);

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
});
26
27
// Format with variables
28
const formatted = chatPrompt.format(
29
  {
30
    description: "traffic analysis",
31
    video_url: "https://example.com/traffic.mp4",
32
  },
33
  { vision: true, video: true },
34
);

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
});
25
26
const formatted = chatPrompt.format(
27
  {
28
    image1_url: "https://example.com/before.jpg",
29
    image2_url: "https://example.com/after.jpg",
30
  },
31
  { vision: true },
32
);

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(`Commit: ${chatPrompt.commit}`);
9
}
10
11
// Get specific version
12
const oldVersion = await client.getChatPrompt({
13
  name: "educational-assistant",
14
  commit: "abc123de",
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
});
15
16
const formatted = chatPrompt.format({
17
  name: "Alice",
18
  city: "Paris",
19
});
20
// 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
});
21
22
// With premium user
23
const formatted1 = chatPrompt.format({
24
  name: "Alice",
25
  is_premium: true,
26
});
27
// Result includes: "Hello Alice, welcome to our premium service!"
28
29
// With regular user
30
const formatted2 = chatPrompt.format({
31
  name: "Bob",
32
  is_premium: false,
33
});
34
// 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
});
11
12
console.log(`Version 1 commit: ${chatPrompt.commit}`);
13
14
// Update with new messages - creates new version
15
const messagesV2 = [
16
  { role: "system", content: "You are a helpful assistant." },
17
  { role: "user", content: "Hello {{name}}!" },
18
];
19
20
const chatPromptV2 = await client.createChatPrompt({
21
  name: "greeting-prompt",
22
  messages: messagesV2,
23
  changeDescription: "Added personalization with name variable",
24
});
25
26
console.log(`Version 2 commit: ${chatPromptV2.commit}`);
27
28
// Get version history
29
const versions = await chatPrompt.getVersions();
30
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 specific version
9
const oldVersion = await chatPrompt.getVersion("abc123de");
10
11
// Compare versions
12
if (versions.length >= 2) {
13
  const current = versions[0];
14
  const previous = versions[1];
15
  const diff = current.compareTo(previous);
16
  console.log(diff);
17
}
18
19
// Restore previous version
20
const targetVersion = versions.find((v) => v.commit === "abc123de");
21
if (targetVersion) {
22
  const restoredPrompt = await chatPrompt.useVersion(targetVersion);
23
  console.log(`Restored to commit: ${restoredPrompt.commit}`);
24
}

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
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
);