minions-prompts

What is minions-prompts?

minions-prompts is a structured prompt engineering system that gives every prompt a full version history, a test suite, and measurable quality scores. Think of it as Git for your AI prompts.

Built on the Minions SDK, it treats prompts as first-class versioned objects with typed variables, follows relation chains, and reproducible A/B comparisons.

Why version prompts?

Prompts degrade silently. A change that improves one use case breaks another. Without version control, there is no way to roll back, compare, or systematically test prompt variations.

minions-prompts makes prompt regressions visible and reversible.

Key features

• Full version history — every change is tracked via follows relations
• Variable interpolation — {{variable}}, {{#if condition}}, {{#each items}}
• Test-driven development — create test cases before changing prompts
• A/B comparison — run two versions against the same tests and compare scores
• Agent self-improvement — agents can version their own system prompts
• Multi-language — identical TypeScript and Python SDKs
• Export anywhere — LangChain, LlamaIndex, raw string, or JSON

Quick example

Choose between the unified MinionsPrompts client for seamless access or the modular functions for absolute control.

TypeScript

Unified Client

import { MinionsPrompts, InMemoryStorage } from 'minions-prompts';

const minions = new MinionsPrompts({ storage: new InMemoryStorage() });

// 1. Create a prompt template
const template = await minions.create(
  { title: 'Summarizer', fields: { content: 'Summarize {{topic}} for {{audience}}.' } },
  'promptTemplate'
);

// 2. Render it
const rendered = minions.render(template.fields.content, {
  topic: 'quantum computing',
  audience: 'high school students',
});

// 3. Bump a version
const v2 = await minions.create(
  { title: 'Summarizer v2', fields: {
    content: 'Write a engaging summary of {{topic}} for {{audience}}.',
    versionNumber: 2,
  }},
  'promptVersion'
);
await minions.link(v2.id, template.id, 'follows');

// 4. Show diff
const diff = minions.diff(template, v2);
console.log(minions.formatDiff(diff, true));

// 5. Get version chain
const versions = await minions.getVersionChain(template.id);

OR Modular Imports

import { createMinion, generateId, now } from 'minions-sdk';
import {
  promptTemplateType, promptVersionType,
  PromptChain, PromptRenderer, PromptDiff,
  InMemoryStorage,
} from 'minions-prompts';

const storage = new InMemoryStorage();

// 1. Create a prompt template
const { minion: template } = createMinion(
  { title: 'Summarizer', fields: { content: 'Summarize {{topic}} for {{audience}}.' } },
  promptTemplateType,
);
await storage.saveMinion(template);

// 2. Render it
const renderer = new PromptRenderer();
const rendered = renderer.render(template.fields.content, {
  topic: 'quantum computing',
  audience: 'high school students',
});

// 3. Bump a version
const { minion: v2 } = createMinion(
  { title: 'Summarizer v2', fields: {
    content: 'Write a clear, engaging summary of {{topic}} suitable for {{audience}}. Focus on practical implications.',
    changelog: 'More specific instructions',
    versionNumber: 2,
  }},
  promptVersionType,
);
await storage.saveMinion(v2);
await storage.saveRelation({ id: generateId(), sourceId: v2.id, targetId: template.id, type: 'follows', createdAt: now() });

// 4. Show diff
const differ = new PromptDiff();
const diff = differ.diff(template, v2);
console.log(differ.format(diff, true));

// 5. Get version chain
const chain = new PromptChain(storage);
const versions = await chain.getVersionChain(template.id);
console.log(`${versions.length} versions in chain`);

Python

Unified Client

from minions_prompts import MinionsPrompts, InMemoryStorage

minions = MinionsPrompts(storage=InMemoryStorage())

# 1. Create a prompt template
template = minions.create(
    {"title": "Summarizer", "fields": {"content": "Summarize {{topic}} for {{audience}}."}},
    "promptTemplate"
)

# 2. Render it
rendered = minions.render(
    template.fields["content"],
    {"topic": "quantum computing", "audience": "high school students"}
)

# 3. Bump a version
v2 = minions.create(
    {"title": "Summarizer v2", "fields": {
        "content": "Write an engaging summary of {{topic}} for {{audience}}.",
        "versionNumber": 2,
    }},
    "promptVersion"
)
minions.link(v2.id, template.id, "follows")

# 4. Show version chain
versions = minions.get_version_chain(template.id)

OR Modular Imports

from minions import create_minion, generate_id, now, Relation
from minions_prompts import (
    prompt_template_type, prompt_version_type,
    PromptChain, PromptRenderer, PromptDiff,
    InMemoryStorage,
)

storage = InMemoryStorage()

# 1. Create a prompt template
template, _ = create_minion(
    {"title": "Summarizer", "fields": {"content": "Summarize {{topic}} for {{audience}}."}},
    prompt_template_type,
)
storage.save_minion(template)

# 2. Render it
renderer = PromptRenderer()
rendered = renderer.render(
    template.fields["content"],
    {"topic": "quantum computing", "audience": "high school students"},
)

# 3. Show version chain
chain = PromptChain(storage)
versions = chain.get_version_chain(template.id)
print(f"{len(versions)} version(s) in chain")