ifr dictionary
+ * @param {HTMLElement} node - The node that should occur after the iframe
+ * @param {HTMLElement} prevNode - The node that should occur before the
+ * iframe
+ * @param {HTMLElement} currIfr - The iframe to check
+ * @param {DOMIterator~checkIframeFilterIfr} ifr - The iframe dictionary.
+ * Will be manipulated (by reference)
+ * @return {boolean} Returns true when it should be handled, otherwise false
+ * @access protected
+ */
+ checkIframeFilter(node, prevNode, currIfr, ifr) {
+ let key = false, handled = false;
+ ifr.forEach((ifrDict, i) => {
+ if (ifrDict.val === currIfr) {
+ key = i;
+ handled = ifrDict.handled;
+ }
+ });
+ if (this.compareNodeIframe(node, prevNode, currIfr)) {
+ if (key === false && !handled) {
+ ifr.push({
+ val: currIfr,
+ handled: true
+ });
+ } else if (key !== false && !handled) {
+ ifr[key].handled = true;
+ }
+ return true;
+ }
+ if (key === false) {
+ ifr.push({
+ val: currIfr,
+ handled: false
+ });
+ }
+ return false;
+ }
+ /**
+ * Creates an iterator on all open iframes in the specified array and calls
+ * the end callback when finished
+ * @param {DOMIterator~checkIframeFilterIfr} ifr
+ * @param {DOMIterator~whatToShow} whatToShow
+ * @param {DOMIterator~forEachNodeCallback} eCb - Each callback
+ * @param {DOMIterator~filterCb} fCb
+ * @access protected
+ */
+ handleOpenIframes(ifr, whatToShow, eCb, fCb) {
+ ifr.forEach((ifrDict) => {
+ if (!ifrDict.handled) {
+ this.getIframeContents(ifrDict.val, (con) => {
+ this.createInstanceOnIframe(con).forEachNode(
+ whatToShow,
+ eCb,
+ fCb
+ );
+ });
+ }
+ });
+ }
+ /**
+ * Iterates through all nodes in the specified context and handles iframe
+ * nodes at the correct position
+ * @param {DOMIterator~whatToShow} whatToShow
+ * @param {HTMLElement} ctx - The context
+ * @param {DOMIterator~forEachNodeCallback} eachCb - Each callback
+ * @param {DOMIterator~filterCb} filterCb - Filter callback
+ * @param {DOMIterator~forEachNodeEndCallback} doneCb - End callback
+ * @access protected
+ */
+ iterateThroughNodes(whatToShow, ctx, eachCb, filterCb, doneCb) {
+ const itr = this.createIterator(ctx, whatToShow, filterCb);
+ let ifr = [], elements = [], node, prevNode, retrieveNodes = () => {
+ ({
+ prevNode,
+ node
+ } = this.getIteratorNode(itr));
+ return node;
+ };
+ while (retrieveNodes()) {
+ if (this.iframes) {
+ this.forEachIframe(ctx, (currIfr) => {
+ return this.checkIframeFilter(node, prevNode, currIfr, ifr);
+ }, (con) => {
+ this.createInstanceOnIframe(con).forEachNode(
+ whatToShow,
+ (ifrNode) => elements.push(ifrNode),
+ filterCb
+ );
+ });
+ }
+ elements.push(node);
+ }
+ elements.forEach((node2) => {
+ eachCb(node2);
+ });
+ if (this.iframes) {
+ this.handleOpenIframes(ifr, whatToShow, eachCb, filterCb);
+ }
+ doneCb();
+ }
+ /**
+ * Callback for each node
+ * @callback DOMIterator~forEachNodeCallback
+ * @param {HTMLElement} node - The DOM text node element
+ */
+ /**
+ * Callback if all contexts were handled
+ * @callback DOMIterator~forEachNodeEndCallback
+ */
+ /**
+ * Iterates over all contexts and initializes
+ * {@link DOMIterator#iterateThroughNodes iterateThroughNodes} on them
+ * @param {DOMIterator~whatToShow} whatToShow
+ * @param {DOMIterator~forEachNodeCallback} each - Each callback
+ * @param {DOMIterator~filterCb} filter - Filter callback
+ * @param {DOMIterator~forEachNodeEndCallback} done - End callback
+ * @access public
+ */
+ forEachNode(whatToShow, each, filter, done = () => {
+ }) {
+ const contexts = this.getContexts();
+ let open = contexts.length;
+ if (!open) {
+ done();
+ }
+ contexts.forEach((ctx) => {
+ const ready = () => {
+ this.iterateThroughNodes(whatToShow, ctx, each, filter, () => {
+ if (--open <= 0) {
+ done();
+ }
+ });
+ };
+ if (this.iframes) {
+ this.waitForIframes(ctx, ready);
+ } else {
+ ready();
+ }
+ });
+ }
+ /**
+ * Callback to filter nodes. Can return e.g. NodeFilter.FILTER_ACCEPT or
+ * NodeFilter.FILTER_REJECT
+ * @see {@link http://tinyurl.com/zdczmm2}
+ * @callback DOMIterator~filterCb
+ * @param {HTMLElement} node - The node to filter
+ */
+ /**
+ * @typedef DOMIterator~whatToShow
+ * @see {@link http://tinyurl.com/zfqqkx2}
+ * @type {number}
+ */
+}
+let Mark$1 = class Mark {
+ // eslint-disable-line no-unused-vars
+ /**
+ * @param {HTMLElement|HTMLElement[]|NodeList|string} ctx - The context DOM
+ * element, an array of DOM elements, a NodeList or a selector
+ */
+ constructor(ctx) {
+ this.ctx = ctx;
+ this.ie = false;
+ const ua = window.navigator.userAgent;
+ if (ua.indexOf("MSIE") > -1 || ua.indexOf("Trident") > -1) {
+ this.ie = true;
+ }
+ }
+ /**
+ * Options defined by the user. They will be initialized from one of the
+ * public methods. See {@link Mark#mark}, {@link Mark#markRegExp},
+ * {@link Mark#markRanges} and {@link Mark#unmark} for option properties.
+ * @type {object}
+ * @param {object} [val] - An object that will be merged with defaults
+ * @access protected
+ */
+ set opt(val) {
+ this._opt = Object.assign({}, {
+ "element": "",
+ "className": "",
+ "exclude": [],
+ "iframes": false,
+ "iframesTimeout": 5e3,
+ "separateWordSearch": true,
+ "diacritics": true,
+ "synonyms": {},
+ "accuracy": "partially",
+ "acrossElements": false,
+ "caseSensitive": false,
+ "ignoreJoiners": false,
+ "ignoreGroups": 0,
+ "ignorePunctuation": [],
+ "wildcards": "disabled",
+ "each": () => {
+ },
+ "noMatch": () => {
+ },
+ "filter": () => true,
+ "done": () => {
+ },
+ "debug": false,
+ "log": window.console
+ }, val);
+ }
+ get opt() {
+ return this._opt;
+ }
+ /**
+ * An instance of DOMIterator
+ * @type {DOMIterator}
+ * @access protected
+ */
+ get iterator() {
+ return new DOMIterator(
+ this.ctx,
+ this.opt.iframes,
+ this.opt.exclude,
+ this.opt.iframesTimeout
+ );
+ }
+ /**
+ * Logs a message if log is enabled
+ * @param {string} msg - The message to log
+ * @param {string} [level="debug"] - The log level, e.g. warn
+ * error, debug
+ * @access protected
+ */
+ log(msg, level = "debug") {
+ const log = this.opt.log;
+ if (!this.opt.debug) {
+ return;
+ }
+ if (typeof log === "object" && typeof log[level] === "function") {
+ log[level](`mark.js: ${msg}`);
+ }
+ }
+ /**
+ * Escapes a string for usage within a regular expression
+ * @param {string} str - The string to escape
+ * @return {string}
+ * @access protected
+ */
+ escapeStr(str) {
+ return str.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g, "\\$&");
+ }
+ /**
+ * Creates a regular expression string to match the specified search
+ * term including synonyms, diacritics and accuracy if defined
+ * @param {string} str - The search term to be used
+ * @return {string}
+ * @access protected
+ */
+ createRegExp(str) {
+ if (this.opt.wildcards !== "disabled") {
+ str = this.setupWildcardsRegExp(str);
+ }
+ str = this.escapeStr(str);
+ if (Object.keys(this.opt.synonyms).length) {
+ str = this.createSynonymsRegExp(str);
+ }
+ if (this.opt.ignoreJoiners || this.opt.ignorePunctuation.length) {
+ str = this.setupIgnoreJoinersRegExp(str);
+ }
+ if (this.opt.diacritics) {
+ str = this.createDiacriticsRegExp(str);
+ }
+ str = this.createMergedBlanksRegExp(str);
+ if (this.opt.ignoreJoiners || this.opt.ignorePunctuation.length) {
+ str = this.createJoinersRegExp(str);
+ }
+ if (this.opt.wildcards !== "disabled") {
+ str = this.createWildcardsRegExp(str);
+ }
+ str = this.createAccuracyRegExp(str);
+ return str;
+ }
+ /**
+ * Creates a regular expression string to match the defined synonyms
+ * @param {string} str - The search term to be used
+ * @return {string}
+ * @access protected
+ */
+ createSynonymsRegExp(str) {
+ const syn = this.opt.synonyms, sens = this.opt.caseSensitive ? "" : "i", joinerPlaceholder = this.opt.ignoreJoiners || this.opt.ignorePunctuation.length ? "\0" : "";
+ for (let index in syn) {
+ if (syn.hasOwnProperty(index)) {
+ const value = syn[index], k1 = this.opt.wildcards !== "disabled" ? this.setupWildcardsRegExp(index) : this.escapeStr(index), k2 = this.opt.wildcards !== "disabled" ? this.setupWildcardsRegExp(value) : this.escapeStr(value);
+ if (k1 !== "" && k2 !== "") {
+ str = str.replace(
+ new RegExp(
+ `(${this.escapeStr(k1)}|${this.escapeStr(k2)})`,
+ `gm${sens}`
+ ),
+ joinerPlaceholder + `(${this.processSynomyms(k1)}|${this.processSynomyms(k2)})` + joinerPlaceholder
+ );
+ }
+ }
+ }
+ return str;
+ }
+ /**
+ * Setup synonyms to work with ignoreJoiners and or ignorePunctuation
+ * @param {string} str - synonym key or value to process
+ * @return {string} - processed synonym string
+ */
+ processSynomyms(str) {
+ if (this.opt.ignoreJoiners || this.opt.ignorePunctuation.length) {
+ str = this.setupIgnoreJoinersRegExp(str);
+ }
+ return str;
+ }
+ /**
+ * Sets up the regular expression string to allow later insertion of
+ * wildcard regular expression matches
+ * @param {string} str - The search term to be used
+ * @return {string}
+ * @access protected
+ */
+ setupWildcardsRegExp(str) {
+ str = str.replace(/(?:\\)*\?/g, (val) => {
+ return val.charAt(0) === "\\" ? "?" : "";
+ });
+ return str.replace(/(?:\\)*\*/g, (val) => {
+ return val.charAt(0) === "\\" ? "*" : "";
+ });
+ }
+ /**
+ * Sets up the regular expression string to allow later insertion of
+ * wildcard regular expression matches
+ * @param {string} str - The search term to be used
+ * @return {string}
+ * @access protected
+ */
+ createWildcardsRegExp(str) {
+ let spaces = this.opt.wildcards === "withSpaces";
+ return str.replace(/\u0001/g, spaces ? "[\\S\\s]?" : "\\S?").replace(/\u0002/g, spaces ? "[\\S\\s]*?" : "\\S*");
+ }
+ /**
+ * Sets up the regular expression string to allow later insertion of
+ * designated characters (soft hyphens & zero width characters)
+ * @param {string} str - The search term to be used
+ * @return {string}
+ * @access protected
+ */
+ setupIgnoreJoinersRegExp(str) {
+ return str.replace(/[^(|)\\]/g, (val, indx, original) => {
+ let nextChar = original.charAt(indx + 1);
+ if (/[(|)\\]/.test(nextChar) || nextChar === "") {
+ return val;
+ } else {
+ return val + "\0";
+ }
+ });
+ }
+ /**
+ * Creates a regular expression string to allow ignoring of designated
+ * characters (soft hyphens, zero width characters & punctuation) based on
+ * the specified option values of ignorePunctuation and
+ * ignoreJoiners
+ * @param {string} str - The search term to be used
+ * @return {string}
+ * @access protected
+ */
+ createJoinersRegExp(str) {
+ let joiner = [];
+ const ignorePunctuation = this.opt.ignorePunctuation;
+ if (Array.isArray(ignorePunctuation) && ignorePunctuation.length) {
+ joiner.push(this.escapeStr(ignorePunctuation.join("")));
+ }
+ if (this.opt.ignoreJoiners) {
+ joiner.push("\\u00ad\\u200b\\u200c\\u200d");
+ }
+ return joiner.length ? str.split(/\u0000+/).join(`[${joiner.join("")}]*`) : str;
+ }
+ /**
+ * Creates a regular expression string to match diacritics
+ * @param {string} str - The search term to be used
+ * @return {string}
+ * @access protected
+ */
+ createDiacriticsRegExp(str) {
+ const sens = this.opt.caseSensitive ? "" : "i", dct = this.opt.caseSensitive ? [
+ "aàáảãạăằắẳẵặâầấẩẫậäåāą",
+ "AÀÁẢÃẠĂẰẮẲẴẶÂẦẤẨẪẬÄÅĀĄ",
+ "cçćč",
+ "CÇĆČ",
+ "dđď",
+ "DĐĎ",
+ "eèéẻẽẹêềếểễệëěēę",
+ "EÈÉẺẼẸÊỀẾỂỄỆËĚĒĘ",
+ "iìíỉĩịîïī",
+ "IÌÍỈĨỊÎÏĪ",
+ "lł",
+ "LŁ",
+ "nñňń",
+ "NÑŇŃ",
+ "oòóỏõọôồốổỗộơởỡớờợöøō",
+ "OÒÓỎÕỌÔỒỐỔỖỘƠỞỠỚỜỢÖØŌ",
+ "rř",
+ "RŘ",
+ "sšśșş",
+ "SŠŚȘŞ",
+ "tťțţ",
+ "TŤȚŢ",
+ "uùúủũụưừứửữựûüůū",
+ "UÙÚỦŨỤƯỪỨỬỮỰÛÜŮŪ",
+ "yýỳỷỹỵÿ",
+ "YÝỲỶỸỴŸ",
+ "zžżź",
+ "ZŽŻŹ"
+ ] : [
+ "aàáảãạăằắẳẵặâầấẩẫậäåāąAÀÁẢÃẠĂẰẮẲẴẶÂẦẤẨẪẬÄÅĀĄ",
+ "cçćčCÇĆČ",
+ "dđďDĐĎ",
+ "eèéẻẽẹêềếểễệëěēęEÈÉẺẼẸÊỀẾỂỄỆËĚĒĘ",
+ "iìíỉĩịîïīIÌÍỈĨỊÎÏĪ",
+ "lłLŁ",
+ "nñňńNÑŇŃ",
+ "oòóỏõọôồốổỗộơởỡớờợöøōOÒÓỎÕỌÔỒỐỔỖỘƠỞỠỚỜỢÖØŌ",
+ "rřRŘ",
+ "sšśșşSŠŚȘŞ",
+ "tťțţTŤȚŢ",
+ "uùúủũụưừứửữựûüůūUÙÚỦŨỤƯỪỨỬỮỰÛÜŮŪ",
+ "yýỳỷỹỵÿYÝỲỶỸỴŸ",
+ "zžżźZŽŻŹ"
+ ];
+ let handled = [];
+ str.split("").forEach((ch) => {
+ dct.every((dct2) => {
+ if (dct2.indexOf(ch) !== -1) {
+ if (handled.indexOf(dct2) > -1) {
+ return false;
+ }
+ str = str.replace(
+ new RegExp(`[${dct2}]`, `gm${sens}`),
+ `[${dct2}]`
+ );
+ handled.push(dct2);
+ }
+ return true;
+ });
+ });
+ return str;
+ }
+ /**
+ * Creates a regular expression string that merges whitespace characters
+ * including subsequent ones into a single pattern, one or multiple
+ * whitespaces
+ * @param {string} str - The search term to be used
+ * @return {string}
+ * @access protected
+ */
+ createMergedBlanksRegExp(str) {
+ return str.replace(/[\s]+/gmi, "[\\s]+");
+ }
+ /**
+ * Creates a regular expression string to match the specified string with
+ * the defined accuracy. As in the regular expression of "exactly" can be
+ * a group containing a blank at the beginning, all regular expressions will
+ * be created with two groups. The first group can be ignored (may contain
+ * the said blank), the second contains the actual match
+ * @param {string} str - The searm term to be used
+ * @return {str}
+ * @access protected
+ */
+ createAccuracyRegExp(str) {
+ const chars = "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~¡¿";
+ let acc = this.opt.accuracy, val = typeof acc === "string" ? acc : acc.value, ls = typeof acc === "string" ? [] : acc.limiters, lsJoin = "";
+ ls.forEach((limiter) => {
+ lsJoin += `|${this.escapeStr(limiter)}`;
+ });
+ switch (val) {
+ case "partially":
+ default:
+ return `()(${str})`;
+ case "complementary":
+ lsJoin = "\\s" + (lsJoin ? lsJoin : this.escapeStr(chars));
+ return `()([^${lsJoin}]*${str}[^${lsJoin}]*)`;
+ case "exactly":
+ return `(^|\\s${lsJoin})(${str})(?=$|\\s${lsJoin})`;
+ }
+ }
+ /**
+ * @typedef Mark~separatedKeywords
+ * @type {object.["-", ","]
+ */
+ /**
+ * @typedef Mark~markAccuracySetting
+ * @type {string}
+ * @property {"partially"|"complementary"|"exactly"|Mark~markAccuracyObject}
+ * [accuracy="partially"] - Either one of the following string values:
+ * -
+ *
- partially: When searching for "lor" only "lor" inside + * "lorem" will be marked + *
- complementary: When searching for "lor" the whole word + * "lorem" will be marked + *
- exactly: When searching for "lor" only those exact words + * will be marked. In this example nothing inside "lorem". This value + * is equivalent to the previous option wordBoundary + *
-
+ *
- value: One of the above named string values + *
- limiters: A custom array of string limiters for accuracy + * "exactly" or "complementary" + *
-
+ *
- disabled: Disable wildcard usage + *
- enabled: When searching for "lor?m", the "?" will match zero + * or one non-space character (e.g. "lorm", "loram", "lor3m", etc). When + * searching for "lor*m", the "*" will match zero or more non-space + * characters (e.g. "lorm", "loram", "lor123m", etc). + *
- withSpaces: When searching for "lor?m", the "?" will + * match zero or one space or non-space character (e.g. "lor m", "loram", + * etc). When searching for "lor*m", the "*" will match zero or more space + * or non-space characters (e.g. "lorm", "lore et dolor ipsum", "lor: m", + * etc). + *
-
+ *
- These punctuation marks can be between any characters, e.g. setting
+ * this option to
["'"]would match "Worlds", "World's" and + * "Wo'rlds"
+ * - One or more apostrophes between the letters would still produce a + * match (e.g. "W'o''r'l'd's"). + *
- A typical setting for this option could be as follows:
+ *
ignorePunctuation: ":;.,-–—‒_(){}[]!'\"+=".split(""),This + * setting includes common punctuation as well as a minus, en-dash, + * em-dash and figure-dash + * ({@link https://en.wikipedia.org/wiki/Dash#Figure_dash ref}), as well + * as an underscore.
+ *
Coverage of Model Providers
PromptingTools.jl routes AI calls through the use of subtypes of AbstractPromptSchema, which determine how data is formatted and where it is sent. (For example, OpenAI models have the corresponding subtype AbstractOpenAISchema, having the corresponding schemas - OpenAISchema, CustomOpenAISchema, etc.) This ensures that the data is correctly formatted for the specific AI model provider.
Below is an overview of the model providers supported by PromptingTools.jl, along with the corresponding schema information.
| Abstract Schema | Schema | Model Provider | aigenerate | aiembed | aiextract | aiscan | aiimage | aiclassify |
|---|---|---|---|---|---|---|---|---|
| AbstractOpenAISchema | OpenAISchema | OpenAI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| AbstractOpenAISchema | CustomOpenAISchema* | Any OpenAI-compatible API (eg, vLLM)* | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | LocalServerOpenAISchema** | Any OpenAI-compatible Local server** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | MistralOpenAISchema | Mistral AI | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | DatabricksOpenAISchema | Databricks | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | FireworksOpenAISchema | Fireworks AI | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | TogetherOpenAISchema | Together AI | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | GroqOpenAISchema | Groq | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| AbstractOllamaSchema | OllamaSchema | Ollama (endpoint api/chat) | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
| AbstractManagedSchema | AbstractOllamaManagedSchema | Ollama (endpoint api/generate) | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| AbstractAnthropicSchema | AnthropicSchema | Anthropic | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| AbstractGoogleSchema | GoogleSchema | Google Gemini | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
- Catch-all implementation - Requires providing a
urlwithapi_kwargsand corresponding API key.
** This schema is a flavor of CustomOpenAISchema with a url key preset by global preference key LOCAL_SERVER. It is specifically designed for seamless integration with Llama.jl and utilizes an ENV variable for the URL, making integration easier in certain workflows, such as when nested calls are involved and passing api_kwargs is more challenging.
Note 1: aitools has identical support as aiextract for all providers, as it has the API requirements.
Note 2: The aiscan and aiimage functions rely on specific endpoints being implemented by the provider. Ensure that the provider you choose supports these functionalities.
For more detailed explanations of the functions and schema information, refer to How It Works.
', 9) + ])); +} +const coverage_of_model_providers = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + coverage_of_model_providers as default +}; diff --git a/previews/PR252/assets/coverage_of_model_providers.md.fAV8yRPK.lean.js b/previews/PR252/assets/coverage_of_model_providers.md.fAV8yRPK.lean.js new file mode 100644 index 00000000..034fed38 --- /dev/null +++ b/previews/PR252/assets/coverage_of_model_providers.md.fAV8yRPK.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Coverage of Model Providers","description":"","frontmatter":{},"headers":[],"relativePath":"coverage_of_model_providers.md","filePath":"coverage_of_model_providers.md","lastUpdated":null}'); +const _sfc_main = { name: "coverage_of_model_providers.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('Coverage of Model Providers
PromptingTools.jl routes AI calls through the use of subtypes of AbstractPromptSchema, which determine how data is formatted and where it is sent. (For example, OpenAI models have the corresponding subtype AbstractOpenAISchema, having the corresponding schemas - OpenAISchema, CustomOpenAISchema, etc.) This ensures that the data is correctly formatted for the specific AI model provider.
Below is an overview of the model providers supported by PromptingTools.jl, along with the corresponding schema information.
| Abstract Schema | Schema | Model Provider | aigenerate | aiembed | aiextract | aiscan | aiimage | aiclassify |
|---|---|---|---|---|---|---|---|---|
| AbstractOpenAISchema | OpenAISchema | OpenAI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| AbstractOpenAISchema | CustomOpenAISchema* | Any OpenAI-compatible API (eg, vLLM)* | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | LocalServerOpenAISchema** | Any OpenAI-compatible Local server** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | MistralOpenAISchema | Mistral AI | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | DatabricksOpenAISchema | Databricks | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | FireworksOpenAISchema | Fireworks AI | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | TogetherOpenAISchema | Together AI | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| AbstractOpenAISchema | GroqOpenAISchema | Groq | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| AbstractOllamaSchema | OllamaSchema | Ollama (endpoint api/chat) | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
| AbstractManagedSchema | AbstractOllamaManagedSchema | Ollama (endpoint api/generate) | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| AbstractAnthropicSchema | AnthropicSchema | Anthropic | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| AbstractGoogleSchema | GoogleSchema | Google Gemini | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
- Catch-all implementation - Requires providing a
urlwithapi_kwargsand corresponding API key.
** This schema is a flavor of CustomOpenAISchema with a url key preset by global preference key LOCAL_SERVER. It is specifically designed for seamless integration with Llama.jl and utilizes an ENV variable for the URL, making integration easier in certain workflows, such as when nested calls are involved and passing api_kwargs is more challenging.
Note 1: aitools has identical support as aiextract for all providers, as it has the API requirements.
Note 2: The aiscan and aiimage functions rely on specific endpoints being implemented by the provider. Ensure that the provider you choose supports these functionalities.
For more detailed explanations of the functions and schema information, refer to How It Works.
', 9) + ])); +} +const coverage_of_model_providers = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + coverage_of_model_providers as default +}; diff --git a/previews/PR252/assets/examples_building_RAG.md.CwNBDc-f.js b/previews/PR252/assets/examples_building_RAG.md.CwNBDc-f.js new file mode 100644 index 00000000..34f794bb --- /dev/null +++ b/previews/PR252/assets/examples_building_RAG.md.CwNBDc-f.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Building a Simple Retrieval-Augmented Generation (RAG) System with RAGTools","description":"","frontmatter":{},"headers":[],"relativePath":"examples/building_RAG.md","filePath":"examples/building_RAG.md","lastUpdated":null}'); +const _sfc_main = { name: "examples/building_RAG.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('Building a Simple Retrieval-Augmented Generation (RAG) System with RAGTools
Let's build a Retrieval-Augmented Generation (RAG) chatbot, tailored to navigate and interact with the DataFrames.jl documentation. "RAG" is probably the most common and valuable pattern in Generative AI at the moment.
If you're not familiar with "RAG", start with this article.
Note: You must first import LinearAlgebra, SparseArrays, and Unicode to use this example!
using LinearAlgebra, SparseArrays, Unicode\nusing PromptingTools\nusing PromptingTools.Experimental.RAGTools\n## Note: RAGTools module is still experimental and will change in the future. Ideally, they will be cleaned up and moved to a dedicated package\nusing JSON3, Serialization, DataFramesMeta\nusing Statistics: mean\nconst PT = PromptingTools\nconst RT = PromptingTools.Experimental.RAGToolsRAG in Two Lines
Let's put together a few text pages from DataFrames.jl docs. Simply go to DataFrames.jl docs and copy&paste a few pages into separate text files. Save them in the examples/data folder (see some example pages provided). Ideally, delete all the noise (like headers, footers, etc.) and keep only the text you want to use for the chatbot. Remember, garbage in, garbage out!
files = [\n joinpath("examples", "data", "database_style_joins.txt"),\n joinpath("examples", "data", "what_is_dataframes.txt"),\n]\n# Build an index of chunks, embed them, and create a lookup index of metadata/tags for each chunk\nindex = build_index(files; extract_metadata = false);Let's ask a question
# Embeds the question, finds the closest chunks in the index, and generates an answer from the closest chunks\nanswer = airag(index; question = "I like dplyr, what is the equivalent in Julia?")AIMessage("The equivalent package in Julia to dplyr in R is DataFramesMeta.jl. It provides convenience functions for data manipulation with syntax similar to dplyr.")First RAG in two lines? Done!
What does it do?
build_indexwill chunk the documents into smaller pieces, embed them into numbers (to be able to judge the similarity of chunks) and, optionally, create a lookup index of metadata/tags for each chunk)indexis the result of this step and it holds your chunks, embeddings, and other metadata! Just show it 😃
airagwillembed your question
find the closest chunks in the index (use parameters
top_kandminimum_similarityto tweak the "relevant" chunks)[OPTIONAL] extracts any potential tags/filters from the question and applies them to filter down the potential candidates (use
extract_metadata=trueinbuild_index, you can also provide some filters explicitly viatag_filter)[OPTIONAL] re-ranks the candidate chunks (define and provide your own
rerank_strategy, eg Cohere ReRank API)build a context from the closest chunks (use
chunks_window_marginto tweak if we include preceding and succeeding chunks as well, see?build_contextfor more details)
generate an answer from the closest chunks (use
return_all=trueto see under the hood and debug your application)
You should save the index for later to avoid re-embedding / re-extracting the document chunks!
serialize("examples/index.jls", index)\nindex = deserialize("examples/index.jls");Evaluations
However, we want to evaluate the quality of the system. For that, we need a set of questions and answers. Ideally, we would handcraft a set of high-quality Q&A pairs. However, this is time-consuming and expensive. Let's generate them from the chunks in our index!
Generate Q&A pairs
We need to provide: chunks and sources (file paths for future reference)
evals = build_qa_evals(RT.chunks(index),\n RT.sources(index);\n instructions = "None.",\n verbose = true);[ Info: Q&A Sets built! (cost: $0.102)In practice, you would review each item in this golden evaluation set (and delete any generic/poor questions). It will determine the future success of your app, so you need to make sure it's good!
# Save the evals for later\nJSON3.write("examples/evals.json", evals)\nevals = JSON3.read("examples/evals.json", Vector{RT.QAEvalItem});Explore one Q&A pair
Let's explore one evals item – it's not the best quality but gives you the idea!
evals[1]QAEvalItem:\n source: examples/data/database_style_joins.txt\n context: Database-Style Joins\nIntroduction to joins\nWe often need to combine two or more data sets together to provide a complete picture of the topic we are studying. For example, suppose that we have the following two data sets:\n\njulia> using DataFrames\n question: What is the purpose of joining two or more data sets together?\n answer: The purpose of joining two or more data sets together is to provide a complete picture of the topic being studied.Evaluate this Q&A pair
Let's evaluate this QA item with a "judge model" (often GPT-4 is used as a judge).
# Note: that we used the same question, but generated a different context and answer via `airag`\nctx = airag(index; evals[1].question, return_all = true);\n# ctx is a RAGContext object that keeps all intermediate states of the RAG pipeline for easy evaluation\njudged = aiextract(:RAGJudgeAnswerFromContext;\n ctx.context,\n ctx.question,\n ctx.answer,\n return_type = RT.JudgeAllScores)\njudged.contentDict{Symbol, Any} with 6 entries:\n :final_rating => 4.8\n :clarity => 5\n :completeness => 4\n :relevance => 5\n :consistency => 5\n :helpfulness => 5We can also run the generation + evaluation in a function (a few more metrics are available, eg, retrieval score):
x = run_qa_evals(evals[10], ctx;\n parameters_dict = Dict(:top_k => 3), verbose = true, model_judge = "gpt4t")QAEvalResult:\n source: examples/data/database_style_joins.txt\n context: outerjoin: the output contains rows for values of the key that exist in any of the passed data frames.\nsemijoin: Like an inner join, but output is restricted to columns from the first (left) argument.\n question: What is the difference between outer join and semi join?\n answer: The purpose of joining two or more data sets together is to combine them in order to provide a complete picture or analysis of a specific topic or dataset. By joining data sets, we can combine information from multiple sources to gain more insights and make more informed decisions.\n retrieval_score: 0.0\n retrieval_rank: nothing\n answer_score: 5\n parameters: Dict(:top_k => 3)Fortunately, we don't have to do this one by one – let's evaluate all our Q&A pairs at once.
Evaluate the Whole Set
Let's run each question & answer through our eval loop in async (we do it only for the first 10 to save time). See the ?airag for which parameters you can tweak, eg, top_k
results = asyncmap(evals[1:10]) do qa_item\n # Generate an answer -- often you want the model_judge to be the highest quality possible, eg, "GPT-4 Turbo" (alias "gpt4t)\n ctx = airag(index; qa_item.question, return_all = true, verbose = false)\n # Evaluate the response\n # Note: you can log key parameters for easier analysis later\n run_qa_evals(qa_item, ctx; parameters_dict = Dict(:top_k => 3), verbose = false, model_judge = "gpt4t")\nend\n## Note that the "failed" evals can show as "nothing" (failed as in there was some API error or parsing error), so make sure to handle them.\nresults = filter(x->!isnothing(x.answer_score), results);Note: You could also use the vectorized version results = run_qa_evals(index, evals) to evaluate all items at once.
\n# Let's take a simple average to calculate our score\n@info "RAG Evals: $(length(results)) results, Avg. score: $(round(mean(x->x.answer_score, results);digits=1)), Retrieval score: $(100*round(Int,mean(x->x.retrieval_score,results)))%"[ Info: RAG Evals: 10 results, Avg. score: 4.6, Retrieval score: 100%Note: The retrieval score is 100% only because we have two small documents and running on 10 items only. In practice, you would have a much larger document set and a much larger eval set, which would result in a more representative retrieval score.
You can also analyze the results in a DataFrame:
df = DataFrame(results)| Row | source | context | question | answer | retrieval_score | retrieval_rank | answer_score | parameters |
|---|---|---|---|---|---|---|---|---|
| String | String | String | SubStrin… | Float64 | Int64 | Float64 | Dict… | |
| 1 | examples/data/database_style_joins.txt | Database-Style Joins\\nIntroduction to joins\\nWe often need to combine two or more data sets together to provide a complete picture of the topic we are studying. For example, suppose that we have the following two data sets:\\n\\njulia> using DataFrames | What is the purpose of joining two or more data sets together? | The purpose of joining two or more data sets together is to combine the data sets based on a common key and provide a complete picture of the topic being studied. | 1.0 | 1 | 5.0 | Dict(:top_k=>3) |
| 2 | examples/data/database_style_joins.txt | julia> people = DataFrame(ID=[20, 40], Name=["John Doe", "Jane Doe"])\\n2×2 DataFrame\\n Row │ ID Name\\n │ Int64 String\\n─────┼─────────────────\\n 1 │ 20 John Doe\\n 2 │ 40 Jane Doe | What is the DataFrame called 'people' composed of? | The DataFrame called 'people' consists of two columns: 'ID' and 'Name'. The 'ID' column contains integers, and the 'Name' column contains strings. | 1.0 | 1 | 4.0 | Dict(:top_k=>3) |
| 3 | examples/data/database_style_joins.txt | julia> jobs = DataFrame(ID=[20, 40], Job=["Lawyer", "Doctor"])\\n2×2 DataFrame\\n Row │ ID Job\\n │ Int64 String\\n─────┼───────────────\\n 1 │ 20 Lawyer\\n 2 │ 40 Doctor | What are the jobs and IDs listed in the dataframe? | The jobs and IDs listed in the dataframe are as follows:\\n\\nID: 20\\nJob: Lawyer\\n\\nID: 40\\nJob: Doctor | 1.0 | 1 | 4.67 | Dict(:top_k=>3) |
| 4 | examples/data/database_style_joins.txt | We might want to work with a larger data set that contains both the names and jobs for each ID. We can do this using the innerjoin function: | How can we combine the names and jobs for each ID in a larger data set? | We can use the `innerjoin` function to combine the names and jobs for each ID in a larger data set. | 1.0 | 1 | 4.33333 | Dict(:top_k=>3) |
| 5 | examples/data/database_style_joins.txt | julia> innerjoin(people, jobs, on = :ID)\\n2×3 DataFrame\\n Row │ ID Name Job\\n │ Int64 String String\\n─────┼─────────────────────────\\n 1 │ 20 John Doe Lawyer\\n 2 │ 40 Jane Doe Doctor | What is the name of the person with the ID 40 and their job? | The name of the person with the ID 40 is Jane Doe and their job is Doctor. | 1.0 | 2 | 4.67 | Dict(:top_k=>3) |
| 6 | examples/data/database_style_joins.txt | In relational database theory, this operation is generally referred to as a join. The columns used to determine which rows should be combined during a join are called keys.\\n\\nThe following functions are provided to perform seven kinds of joins: | What are the different kinds of joins? | The different kinds of joins are:\\n\\n1. Inner Join: Returns only the rows that have matching values in both data frames.\\n2. Left Join: Returns all rows from the left data frame and the matching rows from the right data frame.\\n3. Right Join: Returns all rows from the right data frame and the matching rows from the left data frame.\\n4. Full Outer Join: Returns all rows from both data frames and fills in missing values with null.\\n5. Cross Join: Returns the cartesian product of the rows from both data frames.\\n6. Semi Join: Returns only the rows from the left data frame that have matching values in the right data frame.\\n7. Anti Join: Returns only the rows from the left data frame that do not have matching values in the right data frame. | 1.0 | 1 | 4.66667 | Dict(:top_k=>3) |
| 7 | examples/data/database_style_joins.txt | innerjoin: the output contains rows for values of the key that exist in all passed data frames. | What does the output of the inner join operation contain? | The output of the inner join operation contains only the rows for values of the key that exist in all passed data frames. | 1.0 | 1 | 5.0 | Dict(:top_k=>3) |
| 8 | examples/data/database_style_joins.txt | leftjoin: the output contains rows for values of the key that exist in the first (left) argument, whether or not that value exists in the second (right) argument. | What is the purpose of the left join operation? | The purpose of the left join operation is to combine data from two tables based on a common key, where all rows from the left (first) table are included in the output, regardless of whether there is a match in the right (second) table. | 1.0 | 1 | 4.66667 | Dict(:top_k=>3) |
| 9 | examples/data/database_style_joins.txt | rightjoin: the output contains rows for values of the key that exist in the second (right) argument, whether or not that value exists in the first (left) argument. | What is the purpose of the right join operation? | The purpose of the right join operation is to include all the rows from the second (right) argument, regardless of whether a match is found in the first (left) argument. | 1.0 | 1 | 4.67 | Dict(:top_k=>3) |
| 10 | examples/data/database_style_joins.txt | outerjoin: the output contains rows for values of the key that exist in any of the passed data frames.\\nsemijoin: Like an inner join, but output is restricted to columns from the first (left) argument. | What is the difference between outer join and semi join? | The difference between outer join and semi join is that outer join includes rows for values of the key that exist in any of the passed data frames, whereas semi join is like an inner join but only outputs columns from the first argument. | 1.0 | 1 | 4.66667 | Dict(:top_k=>3) |
We're done for today!
What would we do next?
Review your evaluation golden data set and keep only the good items
Play with the chunk sizes (max_length in build_index) and see how it affects the quality
Explore using metadata/key filters (
extract_metadata=truein build_index)Add filtering for semantic similarity (embedding distance) to make sure we don't pick up irrelevant chunks in the context
Use multiple indices or a hybrid index (add a simple BM25 lookup from TextAnalysis.jl)
Data processing is the most important step - properly parsed and split text could make wonders
Add re-ranking of context (see
rerankfunction, you can use Cohere ReRank API)Improve the question embedding (eg, rephrase it, generate hypothetical answers and use them to find better context)
... and much more! See some ideas in Anyscale RAG tutorial
This page was generated using Literate.jl.
', 53) + ])); +} +const building_RAG = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + building_RAG as default +}; diff --git a/previews/PR252/assets/examples_building_RAG.md.CwNBDc-f.lean.js b/previews/PR252/assets/examples_building_RAG.md.CwNBDc-f.lean.js new file mode 100644 index 00000000..34f794bb --- /dev/null +++ b/previews/PR252/assets/examples_building_RAG.md.CwNBDc-f.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Building a Simple Retrieval-Augmented Generation (RAG) System with RAGTools","description":"","frontmatter":{},"headers":[],"relativePath":"examples/building_RAG.md","filePath":"examples/building_RAG.md","lastUpdated":null}'); +const _sfc_main = { name: "examples/building_RAG.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('Building a Simple Retrieval-Augmented Generation (RAG) System with RAGTools
Let's build a Retrieval-Augmented Generation (RAG) chatbot, tailored to navigate and interact with the DataFrames.jl documentation. "RAG" is probably the most common and valuable pattern in Generative AI at the moment.
If you're not familiar with "RAG", start with this article.
Note: You must first import LinearAlgebra, SparseArrays, and Unicode to use this example!
using LinearAlgebra, SparseArrays, Unicode\nusing PromptingTools\nusing PromptingTools.Experimental.RAGTools\n## Note: RAGTools module is still experimental and will change in the future. Ideally, they will be cleaned up and moved to a dedicated package\nusing JSON3, Serialization, DataFramesMeta\nusing Statistics: mean\nconst PT = PromptingTools\nconst RT = PromptingTools.Experimental.RAGToolsRAG in Two Lines
Let's put together a few text pages from DataFrames.jl docs. Simply go to DataFrames.jl docs and copy&paste a few pages into separate text files. Save them in the examples/data folder (see some example pages provided). Ideally, delete all the noise (like headers, footers, etc.) and keep only the text you want to use for the chatbot. Remember, garbage in, garbage out!
files = [\n joinpath("examples", "data", "database_style_joins.txt"),\n joinpath("examples", "data", "what_is_dataframes.txt"),\n]\n# Build an index of chunks, embed them, and create a lookup index of metadata/tags for each chunk\nindex = build_index(files; extract_metadata = false);Let's ask a question
# Embeds the question, finds the closest chunks in the index, and generates an answer from the closest chunks\nanswer = airag(index; question = "I like dplyr, what is the equivalent in Julia?")AIMessage("The equivalent package in Julia to dplyr in R is DataFramesMeta.jl. It provides convenience functions for data manipulation with syntax similar to dplyr.")First RAG in two lines? Done!
What does it do?
build_indexwill chunk the documents into smaller pieces, embed them into numbers (to be able to judge the similarity of chunks) and, optionally, create a lookup index of metadata/tags for each chunk)indexis the result of this step and it holds your chunks, embeddings, and other metadata! Just show it 😃
airagwillembed your question
find the closest chunks in the index (use parameters
top_kandminimum_similarityto tweak the "relevant" chunks)[OPTIONAL] extracts any potential tags/filters from the question and applies them to filter down the potential candidates (use
extract_metadata=trueinbuild_index, you can also provide some filters explicitly viatag_filter)[OPTIONAL] re-ranks the candidate chunks (define and provide your own
rerank_strategy, eg Cohere ReRank API)build a context from the closest chunks (use
chunks_window_marginto tweak if we include preceding and succeeding chunks as well, see?build_contextfor more details)
generate an answer from the closest chunks (use
return_all=trueto see under the hood and debug your application)
You should save the index for later to avoid re-embedding / re-extracting the document chunks!
serialize("examples/index.jls", index)\nindex = deserialize("examples/index.jls");Evaluations
However, we want to evaluate the quality of the system. For that, we need a set of questions and answers. Ideally, we would handcraft a set of high-quality Q&A pairs. However, this is time-consuming and expensive. Let's generate them from the chunks in our index!
Generate Q&A pairs
We need to provide: chunks and sources (file paths for future reference)
evals = build_qa_evals(RT.chunks(index),\n RT.sources(index);\n instructions = "None.",\n verbose = true);[ Info: Q&A Sets built! (cost: $0.102)In practice, you would review each item in this golden evaluation set (and delete any generic/poor questions). It will determine the future success of your app, so you need to make sure it's good!
# Save the evals for later\nJSON3.write("examples/evals.json", evals)\nevals = JSON3.read("examples/evals.json", Vector{RT.QAEvalItem});Explore one Q&A pair
Let's explore one evals item – it's not the best quality but gives you the idea!
evals[1]QAEvalItem:\n source: examples/data/database_style_joins.txt\n context: Database-Style Joins\nIntroduction to joins\nWe often need to combine two or more data sets together to provide a complete picture of the topic we are studying. For example, suppose that we have the following two data sets:\n\njulia> using DataFrames\n question: What is the purpose of joining two or more data sets together?\n answer: The purpose of joining two or more data sets together is to provide a complete picture of the topic being studied.Evaluate this Q&A pair
Let's evaluate this QA item with a "judge model" (often GPT-4 is used as a judge).
# Note: that we used the same question, but generated a different context and answer via `airag`\nctx = airag(index; evals[1].question, return_all = true);\n# ctx is a RAGContext object that keeps all intermediate states of the RAG pipeline for easy evaluation\njudged = aiextract(:RAGJudgeAnswerFromContext;\n ctx.context,\n ctx.question,\n ctx.answer,\n return_type = RT.JudgeAllScores)\njudged.contentDict{Symbol, Any} with 6 entries:\n :final_rating => 4.8\n :clarity => 5\n :completeness => 4\n :relevance => 5\n :consistency => 5\n :helpfulness => 5We can also run the generation + evaluation in a function (a few more metrics are available, eg, retrieval score):
x = run_qa_evals(evals[10], ctx;\n parameters_dict = Dict(:top_k => 3), verbose = true, model_judge = "gpt4t")QAEvalResult:\n source: examples/data/database_style_joins.txt\n context: outerjoin: the output contains rows for values of the key that exist in any of the passed data frames.\nsemijoin: Like an inner join, but output is restricted to columns from the first (left) argument.\n question: What is the difference between outer join and semi join?\n answer: The purpose of joining two or more data sets together is to combine them in order to provide a complete picture or analysis of a specific topic or dataset. By joining data sets, we can combine information from multiple sources to gain more insights and make more informed decisions.\n retrieval_score: 0.0\n retrieval_rank: nothing\n answer_score: 5\n parameters: Dict(:top_k => 3)Fortunately, we don't have to do this one by one – let's evaluate all our Q&A pairs at once.
Evaluate the Whole Set
Let's run each question & answer through our eval loop in async (we do it only for the first 10 to save time). See the ?airag for which parameters you can tweak, eg, top_k
results = asyncmap(evals[1:10]) do qa_item\n # Generate an answer -- often you want the model_judge to be the highest quality possible, eg, "GPT-4 Turbo" (alias "gpt4t)\n ctx = airag(index; qa_item.question, return_all = true, verbose = false)\n # Evaluate the response\n # Note: you can log key parameters for easier analysis later\n run_qa_evals(qa_item, ctx; parameters_dict = Dict(:top_k => 3), verbose = false, model_judge = "gpt4t")\nend\n## Note that the "failed" evals can show as "nothing" (failed as in there was some API error or parsing error), so make sure to handle them.\nresults = filter(x->!isnothing(x.answer_score), results);Note: You could also use the vectorized version results = run_qa_evals(index, evals) to evaluate all items at once.
\n# Let's take a simple average to calculate our score\n@info "RAG Evals: $(length(results)) results, Avg. score: $(round(mean(x->x.answer_score, results);digits=1)), Retrieval score: $(100*round(Int,mean(x->x.retrieval_score,results)))%"[ Info: RAG Evals: 10 results, Avg. score: 4.6, Retrieval score: 100%Note: The retrieval score is 100% only because we have two small documents and running on 10 items only. In practice, you would have a much larger document set and a much larger eval set, which would result in a more representative retrieval score.
You can also analyze the results in a DataFrame:
df = DataFrame(results)| Row | source | context | question | answer | retrieval_score | retrieval_rank | answer_score | parameters |
|---|---|---|---|---|---|---|---|---|
| String | String | String | SubStrin… | Float64 | Int64 | Float64 | Dict… | |
| 1 | examples/data/database_style_joins.txt | Database-Style Joins\\nIntroduction to joins\\nWe often need to combine two or more data sets together to provide a complete picture of the topic we are studying. For example, suppose that we have the following two data sets:\\n\\njulia> using DataFrames | What is the purpose of joining two or more data sets together? | The purpose of joining two or more data sets together is to combine the data sets based on a common key and provide a complete picture of the topic being studied. | 1.0 | 1 | 5.0 | Dict(:top_k=>3) |
| 2 | examples/data/database_style_joins.txt | julia> people = DataFrame(ID=[20, 40], Name=["John Doe", "Jane Doe"])\\n2×2 DataFrame\\n Row │ ID Name\\n │ Int64 String\\n─────┼─────────────────\\n 1 │ 20 John Doe\\n 2 │ 40 Jane Doe | What is the DataFrame called 'people' composed of? | The DataFrame called 'people' consists of two columns: 'ID' and 'Name'. The 'ID' column contains integers, and the 'Name' column contains strings. | 1.0 | 1 | 4.0 | Dict(:top_k=>3) |
| 3 | examples/data/database_style_joins.txt | julia> jobs = DataFrame(ID=[20, 40], Job=["Lawyer", "Doctor"])\\n2×2 DataFrame\\n Row │ ID Job\\n │ Int64 String\\n─────┼───────────────\\n 1 │ 20 Lawyer\\n 2 │ 40 Doctor | What are the jobs and IDs listed in the dataframe? | The jobs and IDs listed in the dataframe are as follows:\\n\\nID: 20\\nJob: Lawyer\\n\\nID: 40\\nJob: Doctor | 1.0 | 1 | 4.67 | Dict(:top_k=>3) |
| 4 | examples/data/database_style_joins.txt | We might want to work with a larger data set that contains both the names and jobs for each ID. We can do this using the innerjoin function: | How can we combine the names and jobs for each ID in a larger data set? | We can use the `innerjoin` function to combine the names and jobs for each ID in a larger data set. | 1.0 | 1 | 4.33333 | Dict(:top_k=>3) |
| 5 | examples/data/database_style_joins.txt | julia> innerjoin(people, jobs, on = :ID)\\n2×3 DataFrame\\n Row │ ID Name Job\\n │ Int64 String String\\n─────┼─────────────────────────\\n 1 │ 20 John Doe Lawyer\\n 2 │ 40 Jane Doe Doctor | What is the name of the person with the ID 40 and their job? | The name of the person with the ID 40 is Jane Doe and their job is Doctor. | 1.0 | 2 | 4.67 | Dict(:top_k=>3) |
| 6 | examples/data/database_style_joins.txt | In relational database theory, this operation is generally referred to as a join. The columns used to determine which rows should be combined during a join are called keys.\\n\\nThe following functions are provided to perform seven kinds of joins: | What are the different kinds of joins? | The different kinds of joins are:\\n\\n1. Inner Join: Returns only the rows that have matching values in both data frames.\\n2. Left Join: Returns all rows from the left data frame and the matching rows from the right data frame.\\n3. Right Join: Returns all rows from the right data frame and the matching rows from the left data frame.\\n4. Full Outer Join: Returns all rows from both data frames and fills in missing values with null.\\n5. Cross Join: Returns the cartesian product of the rows from both data frames.\\n6. Semi Join: Returns only the rows from the left data frame that have matching values in the right data frame.\\n7. Anti Join: Returns only the rows from the left data frame that do not have matching values in the right data frame. | 1.0 | 1 | 4.66667 | Dict(:top_k=>3) |
| 7 | examples/data/database_style_joins.txt | innerjoin: the output contains rows for values of the key that exist in all passed data frames. | What does the output of the inner join operation contain? | The output of the inner join operation contains only the rows for values of the key that exist in all passed data frames. | 1.0 | 1 | 5.0 | Dict(:top_k=>3) |
| 8 | examples/data/database_style_joins.txt | leftjoin: the output contains rows for values of the key that exist in the first (left) argument, whether or not that value exists in the second (right) argument. | What is the purpose of the left join operation? | The purpose of the left join operation is to combine data from two tables based on a common key, where all rows from the left (first) table are included in the output, regardless of whether there is a match in the right (second) table. | 1.0 | 1 | 4.66667 | Dict(:top_k=>3) |
| 9 | examples/data/database_style_joins.txt | rightjoin: the output contains rows for values of the key that exist in the second (right) argument, whether or not that value exists in the first (left) argument. | What is the purpose of the right join operation? | The purpose of the right join operation is to include all the rows from the second (right) argument, regardless of whether a match is found in the first (left) argument. | 1.0 | 1 | 4.67 | Dict(:top_k=>3) |
| 10 | examples/data/database_style_joins.txt | outerjoin: the output contains rows for values of the key that exist in any of the passed data frames.\\nsemijoin: Like an inner join, but output is restricted to columns from the first (left) argument. | What is the difference between outer join and semi join? | The difference between outer join and semi join is that outer join includes rows for values of the key that exist in any of the passed data frames, whereas semi join is like an inner join but only outputs columns from the first argument. | 1.0 | 1 | 4.66667 | Dict(:top_k=>3) |
We're done for today!
What would we do next?
Review your evaluation golden data set and keep only the good items
Play with the chunk sizes (max_length in build_index) and see how it affects the quality
Explore using metadata/key filters (
extract_metadata=truein build_index)Add filtering for semantic similarity (embedding distance) to make sure we don't pick up irrelevant chunks in the context
Use multiple indices or a hybrid index (add a simple BM25 lookup from TextAnalysis.jl)
Data processing is the most important step - properly parsed and split text could make wonders
Add re-ranking of context (see
rerankfunction, you can use Cohere ReRank API)Improve the question embedding (eg, rephrase it, generate hypothetical answers and use them to find better context)
... and much more! See some ideas in Anyscale RAG tutorial
This page was generated using Literate.jl.
', 53) + ])); +} +const building_RAG = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + building_RAG as default +}; diff --git a/previews/PR252/assets/examples_readme_examples.md.5cumyWJ0.js b/previews/PR252/assets/examples_readme_examples.md.5cumyWJ0.js new file mode 100644 index 00000000..fcd2544c --- /dev/null +++ b/previews/PR252/assets/examples_readme_examples.md.5cumyWJ0.js @@ -0,0 +1,21 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, j as createBaseVNode, a as createTextVNode, t as toDisplayString, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Various Examples","description":"","frontmatter":{},"headers":[],"relativePath":"examples/readme_examples.md","filePath":"examples/readme_examples.md","lastUpdated":null}'); +const _sfc_main = { name: "examples/readme_examples.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, [ + _cache[4] || (_cache[4] = createStaticVNode('Various Examples
ai* Functions Overview
Noteworthy functions: aigenerate, aiembed, aiclassify, aiextract, aiscan, aiimage, aitemplates
All ai* functions have the same basic structure:
ai*(<optional schema>,<prompt or conversation>; <optional keyword arguments>),
but they differ in purpose:
aigenerateis the general-purpose function to generate any text response with LLMs, ie, it returnsAIMessagewith field:contentcontaining the generated text (eg,ans.content isa AbstractString)aiembedis designed to extract embeddings from the AI model's response, ie, it returnsDataMessagewith field:contentcontaining the embeddings (eg,ans.content isa AbstractArray)aiextractis designed to extract structured data from the AI model's response and return them as a Julia struct (eg, if we providereturn_type=Food, we getans.content isa Food). You need to define the return type first and then provide it as a keyword argument.aiclassifyis designed to classify the input text into (or simply respond within) a set of discretechoicesprovided by the user. It can be very useful as an LLM Judge or a router for RAG systems, as it uses the "logit bias trick" and generates exactly 1 token. It returnsAIMessagewith field:content, but the:contentcan be only one of the providedchoices(eg,ans.content in choices)aiscanis for working with images and vision-enabled models (as an input), but it returnsAIMessagewith field:contentcontaining the generated text (eg,ans.content isa AbstractString) similar toaigenerate.aiimageis for generating images (eg, with OpenAI DALL-E 3). It returns aDataMessage, where the field:contentmight contain either the URL to download the image from or the Base64-encoded image depending on the user-provided kwargapi_kwargs.response_format.aitemplatesis a helper function to discover available templates and see their details (eg,aitemplates("some keyword")oraitemplates(:AssistantAsk))
If you're using a known model, you do NOT need to provide a schema (the first argument).
Optional keyword arguments in ai* tend to be:
model::String- Which model you want to useverbose::Bool- Whether you went to see INFO logs around AI costsreturn_all::Bool- Whether you want the WHOLE conversation or just the AI answer (ie, whether you want to include your inputs/prompt in the output)api_kwargs::NamedTuple- Specific parameters for the model, eg,temperature=0.0to be NOT creative (and have more similar output in each run)http_kwargs::NamedTuple- Parameters for the HTTP.jl package, eg,readtimeout = 120to time out in 120 seconds if no response was received.
Experimental: AgentTools
In addition to the above list of ai* functions, you can also use the "lazy" counterparts of these functions from the experimental AgentTools module.
using PromptingTools.Experimental.AgentToolsFor example, AIGenerate() will create a lazy instance of aigenerate. It is an instance of AICall with aigenerate as its ai function. It uses exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details).
"lazy" refers to the fact that it does NOT generate any output when instantiated (only when run! is called).
Or said differently, the AICall struct and all its flavors (AIGenerate, ...) are designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied. This allows us to remember user inputs and trigger the LLM call repeatedly if needed, which enables automatic fixing (see ?airetry!).
Experimental: RAGTools
Lastly, we provide a set of tools to build RAG applications (Retrieve, Answer, Generate).
It can be as simple as two calls: build_index and airag (Retrieve, Answer, Generate).
If you then use pretty-printing with PromptingTools.pprint, we highlight the generated text vs text likely sourced from the context and we score how strongly is the generated answer supported by the context. In addition, we annotate each generated chunk with a reference to which source document it likely came from (including the confidence score between 0 and 1).
Seamless Integration Into Your Workflow
Google search is great, but it's a context switch. You often have to open a few pages and read through the discussion to find the answer you need. Same with the ChatGPT website.
Imagine you are in VSCode, editing your .gitignore file. How do I ignore a file in all subfolders again?
All you need to do is to type: aai"What to write in .gitignore to ignore file XYZ in any folder or subfolder?"
With aai"" (as opposed to ai""), we make a non-blocking call to the LLM to not prevent you from continuing your work. When the answer is ready, we log it from the background:
[ Info: Tokens: 102 @ Cost: $0.0002 in 2.7 seconds\n┌ Info: AIMessage> To ignore a file called "XYZ" in any folder or subfolder, you can add the following line to your .gitignore file:\n│ \n│ ```\n│ **/XYZ\n│ ```\n│ \n└ This pattern uses the double asterisk (`**`) to match any folder or subfolder, and then specifies the name of the file you want to ignore.You probably saved 3-5 minutes on this task and probably another 5-10 minutes, because of the context switch/distraction you avoided. It's a small win, but it adds up quickly.
Advanced Prompts / Conversations
', 28)), + createBaseVNode("p", null, [ + _cache[0] || (_cache[0] = createTextVNode("You can use the ")), + _cache[1] || (_cache[1] = createBaseVNode("code", null, "aigenerate", -1)), + _cache[2] || (_cache[2] = createTextVNode(" function to replace handlebar variables (eg, ")), + createBaseVNode("code", null, toDisplayString(_ctx.name), 1), + _cache[3] || (_cache[3] = createTextVNode(") via keyword arguments.")) + ]), + _cache[5] || (_cache[5] = createStaticVNode('msg = aigenerate("Say hello to {{name}}!", name="World")The more complex prompts are effectively a conversation (a set of messages), where you can have messages from three entities: System, User, AI Assistant. We provide the corresponding types for each of them: SystemMessage, UserMessage, AIMessage.
using PromptingTools: SystemMessage, UserMessage\n\nconversation = [\n SystemMessage("You're master Yoda from Star Wars trying to help the user become a Jedi."),\n UserMessage("I have feelings for my {{object}}. What should I do?")]\nmsg = aigenerate(conversation; object = "old iPhone")AIMessage("Ah, a dilemma, you have. Emotional attachment can cloud your path to becoming a Jedi. To be attached to material possessions, you must not. The iPhone is but a tool, nothing more. Let go, you must.\n\nSeek detachment, young padawan. Reflect upon the impermanence of all things. Appreciate the memories it gave you, and gratefully part ways. In its absence, find new experiences to grow and become one with the Force. Only then, a true Jedi, you shall become.")You can also use it to build conversations, eg,
new_conversation = vcat(conversation...,msg, UserMessage("Thank you, master Yoda! Do you have {{object}} to know what it feels like?"))\naigenerate(new_conversation; object = "old iPhone")> AIMessage("Hmm, possess an old iPhone, I do not. But experience with attachments, I have. Detachment, I learned. True power and freedom, it brings...")Templated Prompts
With LLMs, the quality / robustness of your results depends on the quality of your prompts. But writing prompts is hard! That's why we offer a templating system to save you time and effort.
To use a specific template (eg, `` to ask a Julia language):
msg = aigenerate(:JuliaExpertAsk; ask = "How do I add packages?")The above is equivalent to a more verbose version that explicitly uses the dispatch on AITemplate:
msg = aigenerate(AITemplate(:JuliaExpertAsk); ask = "How do I add packages?")Find available templates with aitemplates:
tmps = aitemplates("JuliaExpertAsk")\n# Will surface one specific template\n# 1-element Vector{AITemplateMetadata}:\n# PromptingTools.AITemplateMetadata\n# name: Symbol JuliaExpertAsk\n# description: String "For asking questions about Julia language. Placeholders: `ask`"\n# version: String "1"\n# wordcount: Int64 237\n# variables: Array{Symbol}((1,))\n# system_preview: String "You are a world-class Julia language programmer with the knowledge of the latest syntax. Your commun"\n# user_preview: String "# Question\\n\\n{{ask}}"\n# source: String ""The above gives you a good idea of what the template is about, what placeholders are available, and how much it would cost to use it (=wordcount).
Search for all Julia-related templates:
tmps = aitemplates("Julia")\n# 2-element Vector{AITemplateMetadata}... -> more to come later!If you are on VSCode, you can leverage a nice tabular display with vscodedisplay:
using DataFrames\ntmps = aitemplates("Julia") |> DataFrame |> vscodedisplayI have my selected template, how do I use it? Just use the "name" in aigenerate or aiclassify like you see in the first example!
You can inspect any template by "rendering" it (this is what the LLM will see):
julia> AITemplate(:JudgeIsItTrue) |> PromptingTools.renderSee more examples in the Examples folder.
Asynchronous Execution
You can leverage asyncmap to run multiple AI-powered tasks concurrently, improving performance for batch operations.
prompts = [aigenerate("Translate 'Hello, World!' to {{language}}"; language) for language in ["Spanish", "French", "Mandarin"]]\nresponses = asyncmap(aigenerate, prompts)Pro tip: You can limit the number of concurrent tasks with the keyword asyncmap(...; ntasks=10).
Model Aliases
Certain tasks require more powerful models. All user-facing functions have a keyword argument model that can be used to specify the model to be used. For example, you can use model = "gpt-4-1106-preview" to use the latest GPT-4 Turbo model. However, no one wants to type that!
We offer a set of model aliases (eg, "gpt3", "gpt4", "gpt4t" -> the above GPT-4 Turbo, etc.) that can be used instead.
Each ai... call first looks up the provided model name in the dictionary PromptingTools.MODEL_ALIASES, so you can easily extend with your own aliases!
const PT = PromptingTools\nPT.MODEL_ALIASES["gpt4t"] = "gpt-4-1106-preview"These aliases also can be used as flags in the @ai_str macro, eg, ai"What is the capital of France?"gpt4t (GPT-4 Turbo has a knowledge cut-off in April 2023, so it's useful for more contemporary questions).
Embeddings
Use the aiembed function to create embeddings via the default OpenAI model that can be used for semantic search, clustering, and more complex AI workflows.
text_to_embed = "The concept of artificial intelligence."\nmsg = aiembed(text_to_embed)\nembedding = msg.content # 1536-element Vector{Float64}If you plan to calculate the cosine distance between embeddings, you can normalize them first:
using LinearAlgebra\nmsg = aiembed(["embed me", "and me too"], LinearAlgebra.normalize)\n\n# calculate cosine distance between the two normalized embeddings as a simple dot product\nmsg.content' * msg.content[:, 1] # [1.0, 0.787]Classification
You can use the aiclassify function to classify any provided statement as true/false/unknown. This is useful for fact-checking, hallucination or NLI checks, moderation, filtering, sentiment analysis, feature engineering and more.
aiclassify("Is two plus two four?") \n# trueSystem prompts and higher-quality models can be used for more complex tasks, including knowing when to defer to a human:
aiclassify(:JudgeIsItTrue; it = "Is two plus three a vegetable on Mars?", model = "gpt4t") \n# unknownIn the above example, we used a prompt template :JudgeIsItTrue, which automatically expands into the following system prompt (and a separate user prompt):
"You are an impartial AI judge evaluating whether the provided statement is "true" or "false". Answer "unknown" if you cannot decide."
For more information on templates, see the Templated Prompts section.
Routing to Defined Categories
aiclassify can be also used for classification into a set of defined categories (maximum 20), so we can use it for routing.
In addition, if you provide the choices as tuples ((label, description)), the model will use the descriptions to decide, but it will return the labels.
Example:
choices = [("A", "any animal or creature"), ("P", "for any plant or tree"), ("O", "for everything else")]\n\ninput = "spider" \naiclassify(:InputClassifier; choices, input) # -> returns "A" for any animal or creature\n\n# Try also with:\ninput = "daphodil" # -> returns "P" for any plant or tree\ninput = "castle" # -> returns "O" for everything elseUnder the hood, we use the "logit bias" trick to force only 1 generated token - that means it's very cheap and very fast!
Data Extraction
Are you tired of extracting data with regex? You can use LLMs to extract structured data from text!
All you have to do is to define the structure of the data you want to extract and the LLM will do the rest.
Define a return_type with struct. Provide docstrings if needed (improves results and helps with documentation).
Let's start with a hard task - extracting the current weather in a given location:
@enum TemperatureUnits celsius fahrenheit\n"""Extract the current weather in a given location\n\n# Arguments\n- `location`: The city and state, e.g. "San Francisco, CA"\n- `unit`: The unit of temperature to return, either `celsius` or `fahrenheit`\n"""\nstruct CurrentWeather\n location::String\n unit::Union{Nothing,TemperatureUnits}\nend\n\n# Note that we provide the TYPE itself, not an instance of it!\nmsg = aiextract("What's the weather in Salt Lake City in C?"; return_type=CurrentWeather)\nmsg.content\n# CurrentWeather("Salt Lake City, UT", celsius)But you can use it even for more complex tasks, like extracting many entities from a text:
"Person's age, height, and weight."\nstruct MyMeasurement\n age::Int\n height::Union{Int,Nothing}\n weight::Union{Nothing,Float64}\nend\nstruct ManyMeasurements\n measurements::Vector{MyMeasurement}\nend\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; return_type=ManyMeasurements)\nmsg.content.measurements\n# 2-element Vector{MyMeasurement}:\n# MyMeasurement(30, 180, 80.0)\n# MyMeasurement(19, 190, nothing)There is even a wrapper to help you catch errors together with helpful explanations on why parsing failed. See ?PromptingTools.MaybeExtract for more information.
OCR and Image Comprehension
With the aiscan function, you can interact with images as if they were text.
You can simply describe a provided image:
msg = aiscan("Describe the image"; image_path="julia.png", model="gpt4v")\n# [ Info: Tokens: 1141 @ Cost: \\$0.0117 in 2.2 seconds\n# AIMessage("The image shows a logo consisting of the word "julia" written in lowercase")Or you can do an OCR of a screenshot. Let's transcribe some SQL code from a screenshot (no more re-typing!), we use a template :OCRTask:
# Screenshot of some SQL code\nimage_url = "https://www.sqlservercentral.com/wp-content/uploads/legacy/8755f69180b7ac7ee76a69ae68ec36872a116ad4/24622.png"\nmsg = aiscan(:OCRTask; image_url, model="gpt4v", task="Transcribe the SQL code in the image.", api_kwargs=(; max_tokens=2500))\n\n# [ Info: Tokens: 362 @ Cost: \\$0.0045 in 2.5 seconds\n# AIMessage("```sql\n# update Orders <continue>You can add syntax highlighting of the outputs via Markdown
using Markdown\nmsg.content |> Markdown.parseExperimental Agent Workflows / Output Validation with airetry!
This is an experimental feature, so you have to import it explicitly:
using PromptingTools.Experimental.AgentToolsThis module offers "lazy" counterparts to the ai... functions, so you can use them in a more controlled way, eg, aigenerate -> AIGenerate (notice the CamelCase), which has exactly the same arguments except it generates only when run! is called.
For example:
out = AIGenerate("Say hi!"; model="gpt4t")\nrun!(out)How is it useful? We can use the same "inputs" for repeated calls, eg, when we want to validate or regenerate some outputs. We have a function airetry to help us with that.
The signature of airetry is airetry(condition_function, aicall::AICall, feedback_function). It evaluates the condition condition_function on the aicall object (eg, we evaluate f_cond(aicall) -> Bool). If it fails, we call feedback_function on the aicall object to provide feedback for the AI model (eg, f_feedback(aicall) -> String) and repeat the process until it passes or until max_retries value is exceeded.
We can catch API failures (no feedback needed, so none is provided)
# API failure because of a non-existent model\n# RetryConfig allows us to change the "retry" behaviour of any lazy call\nout = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\n model = "NOTEXIST")\nrun!(out) # fails\n\n# we ask to wait 2s between retries and retry 2 times (can be set in `config` in aicall as well)\nairetry!(isvalid, out; retry_delay = 2, max_retries = 2)Or we can validate some outputs (eg, its format, its content, etc.)
We'll play a color guessing game (I'm thinking "yellow"):
# Notice that we ask for two samples (`n_samples=2`) at each attempt (to improve our chances). \n# Both guesses are scored at each time step, and the best one is chosen for the next step.\n# And with OpenAI, we can set `api_kwargs = (;n=2)` to get both samples simultaneously (cheaper and faster)!\nout = AIGenerate(\n "Guess what color I'm thinking. It could be: blue, red, black, white, yellow. Answer with 1 word only";\n verbose = false,\n config = RetryConfig(; n_samples = 2), api_kwargs = (; n = 2))\nrun!(out)\n\n## Check that the output is 1 word only, third argument is the feedback that will be provided if the condition fails\n## Notice: functions operate on `aicall` as the only argument. We can use utilities like `last_output` and `last_message` to access the last message and output in the conversation.\nairetry!(x -> length(split(last_output(x), r" |\\\\.")) == 1, out,\n "You must answer with 1 word only.")\n\n# Note: you could also use the do-syntax, eg, \nairetry!(out, "You must answer with 1 word only.") do aicall\n length(split(last_output(aicall), r" |\\\\.")) == 1\nendYou can place multiple airetry! calls in a sequence. They will keep retrying until they run out of maximum AI calls allowed (max_calls) or maximum retries (max_retries).
See the docs for more complex examples and usage tips (?airetry). We leverage Monte Carlo Tree Search (MCTS) to optimize the sequence of retries, so it's a very powerful tool for building robust AI workflows (inspired by Language Agent Tree Search paper and by DSPy Assertions paper).
Using Ollama models
Ollama.ai is an amazingly simple tool that allows you to run several Large Language Models (LLM) on your computer. It's especially suitable when you're working with some sensitive data that should not be sent anywhere.
Let's assume you have installed Ollama, downloaded a model, and it's running in the background.
We can use it with the aigenerate function:
const PT = PromptingTools\nschema = PT.OllamaManagedSchema() # notice the different schema!\n\nmsg = aigenerate(schema, "Say hi!"; model="openhermes2.5-mistral")\n# [ Info: Tokens: 69 in 0.9 seconds\n# AIMessage("Hello! How can I assist you today?")And we can also use the aiembed function:
msg = aiembed(schema, "Embed me", copy; model="openhermes2.5-mistral")\nmsg.content # 4096-element JSON3.Array{Float64...\n\nmsg = aiembed(schema, ["Embed me", "Embed me"]; model="openhermes2.5-mistral")\nmsg.content # 4096×2 Matrix{Float64}:If you're getting errors, check that Ollama is running - see the Setup Guide for Ollama section below.
Using MistralAI API and other OpenAI-compatible APIs
Mistral models have long been dominating the open-source space. They are now available via their API, so you can use them with PromptingTools.jl!
msg = aigenerate("Say hi!"; model="mistral-tiny")\n# [ Info: Tokens: 114 @ Cost: $0.0 in 0.9 seconds\n# AIMessage("Hello there! I'm here to help answer any questions you might have, or assist you with tasks to the best of my abilities. How can I be of service to you today? If you have a specific question, feel free to ask and I'll do my best to provide accurate and helpful information. If you're looking for general assistance, I can help you find resources or information on a variety of topics. Let me know how I can help.")It all just works, because we have registered the models in the PromptingTools.MODEL_REGISTRY! There are currently 4 models available: mistral-tiny, mistral-small, mistral-medium, mistral-embed.
Under the hood, we use a dedicated schema MistralOpenAISchema that leverages most of the OpenAI-specific code base, so you can always provide that explicitly as the first argument:
const PT = PromptingTools\nmsg = aigenerate(PT.MistralOpenAISchema(), "Say Hi!"; model="mistral-tiny", api_key=ENV["MISTRAL_API_KEY"])As you can see, we can load your API key either from the ENV or via the Preferences.jl mechanism (see ?PREFERENCES for more information).
But MistralAI are not the only ones! There are many other exciting providers, eg, Perplexity.ai, Fireworks.ai. As long as they are compatible with the OpenAI API (eg, sending messages with role and content keys), you can use them with PromptingTools.jl by using schema = CustomOpenAISchema():
# Set your API key and the necessary base URL for the API\napi_key = "..."\nprompt = "Say hi!"\nmsg = aigenerate(PT.CustomOpenAISchema(), prompt; model="my_model", api_key, api_kwargs=(; url="http://localhost:8081"))As you can see, it also works for any local models that you might have running on your computer!
Note: At the moment, we only support aigenerate and aiembed functions for MistralAI and other OpenAI-compatible APIs. We plan to extend the support in the future.
Various Examples
ai* Functions Overview
Noteworthy functions: aigenerate, aiembed, aiclassify, aiextract, aiscan, aiimage, aitemplates
All ai* functions have the same basic structure:
ai*(<optional schema>,<prompt or conversation>; <optional keyword arguments>),
but they differ in purpose:
aigenerateis the general-purpose function to generate any text response with LLMs, ie, it returnsAIMessagewith field:contentcontaining the generated text (eg,ans.content isa AbstractString)aiembedis designed to extract embeddings from the AI model's response, ie, it returnsDataMessagewith field:contentcontaining the embeddings (eg,ans.content isa AbstractArray)aiextractis designed to extract structured data from the AI model's response and return them as a Julia struct (eg, if we providereturn_type=Food, we getans.content isa Food). You need to define the return type first and then provide it as a keyword argument.aiclassifyis designed to classify the input text into (or simply respond within) a set of discretechoicesprovided by the user. It can be very useful as an LLM Judge or a router for RAG systems, as it uses the "logit bias trick" and generates exactly 1 token. It returnsAIMessagewith field:content, but the:contentcan be only one of the providedchoices(eg,ans.content in choices)aiscanis for working with images and vision-enabled models (as an input), but it returnsAIMessagewith field:contentcontaining the generated text (eg,ans.content isa AbstractString) similar toaigenerate.aiimageis for generating images (eg, with OpenAI DALL-E 3). It returns aDataMessage, where the field:contentmight contain either the URL to download the image from or the Base64-encoded image depending on the user-provided kwargapi_kwargs.response_format.aitemplatesis a helper function to discover available templates and see their details (eg,aitemplates("some keyword")oraitemplates(:AssistantAsk))
If you're using a known model, you do NOT need to provide a schema (the first argument).
Optional keyword arguments in ai* tend to be:
model::String- Which model you want to useverbose::Bool- Whether you went to see INFO logs around AI costsreturn_all::Bool- Whether you want the WHOLE conversation or just the AI answer (ie, whether you want to include your inputs/prompt in the output)api_kwargs::NamedTuple- Specific parameters for the model, eg,temperature=0.0to be NOT creative (and have more similar output in each run)http_kwargs::NamedTuple- Parameters for the HTTP.jl package, eg,readtimeout = 120to time out in 120 seconds if no response was received.
Experimental: AgentTools
In addition to the above list of ai* functions, you can also use the "lazy" counterparts of these functions from the experimental AgentTools module.
using PromptingTools.Experimental.AgentToolsFor example, AIGenerate() will create a lazy instance of aigenerate. It is an instance of AICall with aigenerate as its ai function. It uses exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details).
"lazy" refers to the fact that it does NOT generate any output when instantiated (only when run! is called).
Or said differently, the AICall struct and all its flavors (AIGenerate, ...) are designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied. This allows us to remember user inputs and trigger the LLM call repeatedly if needed, which enables automatic fixing (see ?airetry!).
Experimental: RAGTools
Lastly, we provide a set of tools to build RAG applications (Retrieve, Answer, Generate).
It can be as simple as two calls: build_index and airag (Retrieve, Answer, Generate).
If you then use pretty-printing with PromptingTools.pprint, we highlight the generated text vs text likely sourced from the context and we score how strongly is the generated answer supported by the context. In addition, we annotate each generated chunk with a reference to which source document it likely came from (including the confidence score between 0 and 1).
Seamless Integration Into Your Workflow
Google search is great, but it's a context switch. You often have to open a few pages and read through the discussion to find the answer you need. Same with the ChatGPT website.
Imagine you are in VSCode, editing your .gitignore file. How do I ignore a file in all subfolders again?
All you need to do is to type: aai"What to write in .gitignore to ignore file XYZ in any folder or subfolder?"
With aai"" (as opposed to ai""), we make a non-blocking call to the LLM to not prevent you from continuing your work. When the answer is ready, we log it from the background:
[ Info: Tokens: 102 @ Cost: $0.0002 in 2.7 seconds\n┌ Info: AIMessage> To ignore a file called "XYZ" in any folder or subfolder, you can add the following line to your .gitignore file:\n│ \n│ ```\n│ **/XYZ\n│ ```\n│ \n└ This pattern uses the double asterisk (`**`) to match any folder or subfolder, and then specifies the name of the file you want to ignore.You probably saved 3-5 minutes on this task and probably another 5-10 minutes, because of the context switch/distraction you avoided. It's a small win, but it adds up quickly.
Advanced Prompts / Conversations
', 28)), + createBaseVNode("p", null, [ + _cache[0] || (_cache[0] = createTextVNode("You can use the ")), + _cache[1] || (_cache[1] = createBaseVNode("code", null, "aigenerate", -1)), + _cache[2] || (_cache[2] = createTextVNode(" function to replace handlebar variables (eg, ")), + createBaseVNode("code", null, toDisplayString(_ctx.name), 1), + _cache[3] || (_cache[3] = createTextVNode(") via keyword arguments.")) + ]), + _cache[5] || (_cache[5] = createStaticVNode('msg = aigenerate("Say hello to {{name}}!", name="World")The more complex prompts are effectively a conversation (a set of messages), where you can have messages from three entities: System, User, AI Assistant. We provide the corresponding types for each of them: SystemMessage, UserMessage, AIMessage.
using PromptingTools: SystemMessage, UserMessage\n\nconversation = [\n SystemMessage("You're master Yoda from Star Wars trying to help the user become a Jedi."),\n UserMessage("I have feelings for my {{object}}. What should I do?")]\nmsg = aigenerate(conversation; object = "old iPhone")AIMessage("Ah, a dilemma, you have. Emotional attachment can cloud your path to becoming a Jedi. To be attached to material possessions, you must not. The iPhone is but a tool, nothing more. Let go, you must.\n\nSeek detachment, young padawan. Reflect upon the impermanence of all things. Appreciate the memories it gave you, and gratefully part ways. In its absence, find new experiences to grow and become one with the Force. Only then, a true Jedi, you shall become.")You can also use it to build conversations, eg,
new_conversation = vcat(conversation...,msg, UserMessage("Thank you, master Yoda! Do you have {{object}} to know what it feels like?"))\naigenerate(new_conversation; object = "old iPhone")> AIMessage("Hmm, possess an old iPhone, I do not. But experience with attachments, I have. Detachment, I learned. True power and freedom, it brings...")Templated Prompts
With LLMs, the quality / robustness of your results depends on the quality of your prompts. But writing prompts is hard! That's why we offer a templating system to save you time and effort.
To use a specific template (eg, `` to ask a Julia language):
msg = aigenerate(:JuliaExpertAsk; ask = "How do I add packages?")The above is equivalent to a more verbose version that explicitly uses the dispatch on AITemplate:
msg = aigenerate(AITemplate(:JuliaExpertAsk); ask = "How do I add packages?")Find available templates with aitemplates:
tmps = aitemplates("JuliaExpertAsk")\n# Will surface one specific template\n# 1-element Vector{AITemplateMetadata}:\n# PromptingTools.AITemplateMetadata\n# name: Symbol JuliaExpertAsk\n# description: String "For asking questions about Julia language. Placeholders: `ask`"\n# version: String "1"\n# wordcount: Int64 237\n# variables: Array{Symbol}((1,))\n# system_preview: String "You are a world-class Julia language programmer with the knowledge of the latest syntax. Your commun"\n# user_preview: String "# Question\\n\\n{{ask}}"\n# source: String ""The above gives you a good idea of what the template is about, what placeholders are available, and how much it would cost to use it (=wordcount).
Search for all Julia-related templates:
tmps = aitemplates("Julia")\n# 2-element Vector{AITemplateMetadata}... -> more to come later!If you are on VSCode, you can leverage a nice tabular display with vscodedisplay:
using DataFrames\ntmps = aitemplates("Julia") |> DataFrame |> vscodedisplayI have my selected template, how do I use it? Just use the "name" in aigenerate or aiclassify like you see in the first example!
You can inspect any template by "rendering" it (this is what the LLM will see):
julia> AITemplate(:JudgeIsItTrue) |> PromptingTools.renderSee more examples in the Examples folder.
Asynchronous Execution
You can leverage asyncmap to run multiple AI-powered tasks concurrently, improving performance for batch operations.
prompts = [aigenerate("Translate 'Hello, World!' to {{language}}"; language) for language in ["Spanish", "French", "Mandarin"]]\nresponses = asyncmap(aigenerate, prompts)Pro tip: You can limit the number of concurrent tasks with the keyword asyncmap(...; ntasks=10).
Model Aliases
Certain tasks require more powerful models. All user-facing functions have a keyword argument model that can be used to specify the model to be used. For example, you can use model = "gpt-4-1106-preview" to use the latest GPT-4 Turbo model. However, no one wants to type that!
We offer a set of model aliases (eg, "gpt3", "gpt4", "gpt4t" -> the above GPT-4 Turbo, etc.) that can be used instead.
Each ai... call first looks up the provided model name in the dictionary PromptingTools.MODEL_ALIASES, so you can easily extend with your own aliases!
const PT = PromptingTools\nPT.MODEL_ALIASES["gpt4t"] = "gpt-4-1106-preview"These aliases also can be used as flags in the @ai_str macro, eg, ai"What is the capital of France?"gpt4t (GPT-4 Turbo has a knowledge cut-off in April 2023, so it's useful for more contemporary questions).
Embeddings
Use the aiembed function to create embeddings via the default OpenAI model that can be used for semantic search, clustering, and more complex AI workflows.
text_to_embed = "The concept of artificial intelligence."\nmsg = aiembed(text_to_embed)\nembedding = msg.content # 1536-element Vector{Float64}If you plan to calculate the cosine distance between embeddings, you can normalize them first:
using LinearAlgebra\nmsg = aiembed(["embed me", "and me too"], LinearAlgebra.normalize)\n\n# calculate cosine distance between the two normalized embeddings as a simple dot product\nmsg.content' * msg.content[:, 1] # [1.0, 0.787]Classification
You can use the aiclassify function to classify any provided statement as true/false/unknown. This is useful for fact-checking, hallucination or NLI checks, moderation, filtering, sentiment analysis, feature engineering and more.
aiclassify("Is two plus two four?") \n# trueSystem prompts and higher-quality models can be used for more complex tasks, including knowing when to defer to a human:
aiclassify(:JudgeIsItTrue; it = "Is two plus three a vegetable on Mars?", model = "gpt4t") \n# unknownIn the above example, we used a prompt template :JudgeIsItTrue, which automatically expands into the following system prompt (and a separate user prompt):
"You are an impartial AI judge evaluating whether the provided statement is "true" or "false". Answer "unknown" if you cannot decide."
For more information on templates, see the Templated Prompts section.
Routing to Defined Categories
aiclassify can be also used for classification into a set of defined categories (maximum 20), so we can use it for routing.
In addition, if you provide the choices as tuples ((label, description)), the model will use the descriptions to decide, but it will return the labels.
Example:
choices = [("A", "any animal or creature"), ("P", "for any plant or tree"), ("O", "for everything else")]\n\ninput = "spider" \naiclassify(:InputClassifier; choices, input) # -> returns "A" for any animal or creature\n\n# Try also with:\ninput = "daphodil" # -> returns "P" for any plant or tree\ninput = "castle" # -> returns "O" for everything elseUnder the hood, we use the "logit bias" trick to force only 1 generated token - that means it's very cheap and very fast!
Data Extraction
Are you tired of extracting data with regex? You can use LLMs to extract structured data from text!
All you have to do is to define the structure of the data you want to extract and the LLM will do the rest.
Define a return_type with struct. Provide docstrings if needed (improves results and helps with documentation).
Let's start with a hard task - extracting the current weather in a given location:
@enum TemperatureUnits celsius fahrenheit\n"""Extract the current weather in a given location\n\n# Arguments\n- `location`: The city and state, e.g. "San Francisco, CA"\n- `unit`: The unit of temperature to return, either `celsius` or `fahrenheit`\n"""\nstruct CurrentWeather\n location::String\n unit::Union{Nothing,TemperatureUnits}\nend\n\n# Note that we provide the TYPE itself, not an instance of it!\nmsg = aiextract("What's the weather in Salt Lake City in C?"; return_type=CurrentWeather)\nmsg.content\n# CurrentWeather("Salt Lake City, UT", celsius)But you can use it even for more complex tasks, like extracting many entities from a text:
"Person's age, height, and weight."\nstruct MyMeasurement\n age::Int\n height::Union{Int,Nothing}\n weight::Union{Nothing,Float64}\nend\nstruct ManyMeasurements\n measurements::Vector{MyMeasurement}\nend\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; return_type=ManyMeasurements)\nmsg.content.measurements\n# 2-element Vector{MyMeasurement}:\n# MyMeasurement(30, 180, 80.0)\n# MyMeasurement(19, 190, nothing)There is even a wrapper to help you catch errors together with helpful explanations on why parsing failed. See ?PromptingTools.MaybeExtract for more information.
OCR and Image Comprehension
With the aiscan function, you can interact with images as if they were text.
You can simply describe a provided image:
msg = aiscan("Describe the image"; image_path="julia.png", model="gpt4v")\n# [ Info: Tokens: 1141 @ Cost: \\$0.0117 in 2.2 seconds\n# AIMessage("The image shows a logo consisting of the word "julia" written in lowercase")Or you can do an OCR of a screenshot. Let's transcribe some SQL code from a screenshot (no more re-typing!), we use a template :OCRTask:
# Screenshot of some SQL code\nimage_url = "https://www.sqlservercentral.com/wp-content/uploads/legacy/8755f69180b7ac7ee76a69ae68ec36872a116ad4/24622.png"\nmsg = aiscan(:OCRTask; image_url, model="gpt4v", task="Transcribe the SQL code in the image.", api_kwargs=(; max_tokens=2500))\n\n# [ Info: Tokens: 362 @ Cost: \\$0.0045 in 2.5 seconds\n# AIMessage("```sql\n# update Orders <continue>You can add syntax highlighting of the outputs via Markdown
using Markdown\nmsg.content |> Markdown.parseExperimental Agent Workflows / Output Validation with airetry!
This is an experimental feature, so you have to import it explicitly:
using PromptingTools.Experimental.AgentToolsThis module offers "lazy" counterparts to the ai... functions, so you can use them in a more controlled way, eg, aigenerate -> AIGenerate (notice the CamelCase), which has exactly the same arguments except it generates only when run! is called.
For example:
out = AIGenerate("Say hi!"; model="gpt4t")\nrun!(out)How is it useful? We can use the same "inputs" for repeated calls, eg, when we want to validate or regenerate some outputs. We have a function airetry to help us with that.
The signature of airetry is airetry(condition_function, aicall::AICall, feedback_function). It evaluates the condition condition_function on the aicall object (eg, we evaluate f_cond(aicall) -> Bool). If it fails, we call feedback_function on the aicall object to provide feedback for the AI model (eg, f_feedback(aicall) -> String) and repeat the process until it passes or until max_retries value is exceeded.
We can catch API failures (no feedback needed, so none is provided)
# API failure because of a non-existent model\n# RetryConfig allows us to change the "retry" behaviour of any lazy call\nout = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\n model = "NOTEXIST")\nrun!(out) # fails\n\n# we ask to wait 2s between retries and retry 2 times (can be set in `config` in aicall as well)\nairetry!(isvalid, out; retry_delay = 2, max_retries = 2)Or we can validate some outputs (eg, its format, its content, etc.)
We'll play a color guessing game (I'm thinking "yellow"):
# Notice that we ask for two samples (`n_samples=2`) at each attempt (to improve our chances). \n# Both guesses are scored at each time step, and the best one is chosen for the next step.\n# And with OpenAI, we can set `api_kwargs = (;n=2)` to get both samples simultaneously (cheaper and faster)!\nout = AIGenerate(\n "Guess what color I'm thinking. It could be: blue, red, black, white, yellow. Answer with 1 word only";\n verbose = false,\n config = RetryConfig(; n_samples = 2), api_kwargs = (; n = 2))\nrun!(out)\n\n## Check that the output is 1 word only, third argument is the feedback that will be provided if the condition fails\n## Notice: functions operate on `aicall` as the only argument. We can use utilities like `last_output` and `last_message` to access the last message and output in the conversation.\nairetry!(x -> length(split(last_output(x), r" |\\\\.")) == 1, out,\n "You must answer with 1 word only.")\n\n# Note: you could also use the do-syntax, eg, \nairetry!(out, "You must answer with 1 word only.") do aicall\n length(split(last_output(aicall), r" |\\\\.")) == 1\nendYou can place multiple airetry! calls in a sequence. They will keep retrying until they run out of maximum AI calls allowed (max_calls) or maximum retries (max_retries).
See the docs for more complex examples and usage tips (?airetry). We leverage Monte Carlo Tree Search (MCTS) to optimize the sequence of retries, so it's a very powerful tool for building robust AI workflows (inspired by Language Agent Tree Search paper and by DSPy Assertions paper).
Using Ollama models
Ollama.ai is an amazingly simple tool that allows you to run several Large Language Models (LLM) on your computer. It's especially suitable when you're working with some sensitive data that should not be sent anywhere.
Let's assume you have installed Ollama, downloaded a model, and it's running in the background.
We can use it with the aigenerate function:
const PT = PromptingTools\nschema = PT.OllamaManagedSchema() # notice the different schema!\n\nmsg = aigenerate(schema, "Say hi!"; model="openhermes2.5-mistral")\n# [ Info: Tokens: 69 in 0.9 seconds\n# AIMessage("Hello! How can I assist you today?")And we can also use the aiembed function:
msg = aiembed(schema, "Embed me", copy; model="openhermes2.5-mistral")\nmsg.content # 4096-element JSON3.Array{Float64...\n\nmsg = aiembed(schema, ["Embed me", "Embed me"]; model="openhermes2.5-mistral")\nmsg.content # 4096×2 Matrix{Float64}:If you're getting errors, check that Ollama is running - see the Setup Guide for Ollama section below.
Using MistralAI API and other OpenAI-compatible APIs
Mistral models have long been dominating the open-source space. They are now available via their API, so you can use them with PromptingTools.jl!
msg = aigenerate("Say hi!"; model="mistral-tiny")\n# [ Info: Tokens: 114 @ Cost: $0.0 in 0.9 seconds\n# AIMessage("Hello there! I'm here to help answer any questions you might have, or assist you with tasks to the best of my abilities. How can I be of service to you today? If you have a specific question, feel free to ask and I'll do my best to provide accurate and helpful information. If you're looking for general assistance, I can help you find resources or information on a variety of topics. Let me know how I can help.")It all just works, because we have registered the models in the PromptingTools.MODEL_REGISTRY! There are currently 4 models available: mistral-tiny, mistral-small, mistral-medium, mistral-embed.
Under the hood, we use a dedicated schema MistralOpenAISchema that leverages most of the OpenAI-specific code base, so you can always provide that explicitly as the first argument:
const PT = PromptingTools\nmsg = aigenerate(PT.MistralOpenAISchema(), "Say Hi!"; model="mistral-tiny", api_key=ENV["MISTRAL_API_KEY"])As you can see, we can load your API key either from the ENV or via the Preferences.jl mechanism (see ?PREFERENCES for more information).
But MistralAI are not the only ones! There are many other exciting providers, eg, Perplexity.ai, Fireworks.ai. As long as they are compatible with the OpenAI API (eg, sending messages with role and content keys), you can use them with PromptingTools.jl by using schema = CustomOpenAISchema():
# Set your API key and the necessary base URL for the API\napi_key = "..."\nprompt = "Say hi!"\nmsg = aigenerate(PT.CustomOpenAISchema(), prompt; model="my_model", api_key, api_kwargs=(; url="http://localhost:8081"))As you can see, it also works for any local models that you might have running on your computer!
Note: At the moment, we only support aigenerate and aiembed functions for MistralAI and other OpenAI-compatible APIs. We plan to extend the support in the future.
Using AITemplates
This file contains examples of how to work with AITemplate(s).
First, let's import the package and define a helper link for calling un-exported functions:
using PromptingTools\nconst PT = PromptingToolsPromptingToolsLLM responses are only as good as the prompts you give them. However, great prompts take long time to write – AITemplate are a way to re-use great prompts!
', 6)), + createBaseVNode("p", null, 'AITemplates are just a collection of templated prompts (ie, set of "messages" that have placeholders like ' + toDisplayString(_ctx.question) + ")", 1), + _cache[1] || (_cache[1] = createStaticVNode('They are saved as JSON files in the templates directory. They are automatically loaded on package import, but you can always force a re-load with PT.load_templates!()
PT.load_templates!();You can (create them) and use them for any ai* function instead of a prompt: Let's use a template called :JuliaExpertAsk alternatively, you can use AITemplate(:JuliaExpertAsk) for cleaner dispatch
msg = aigenerate(:JuliaExpertAsk; ask = "How do I add packages?")AIMessage("To add packages in Julia, you can use the `Pkg` module. Here are the steps:\n\n1. Start Julia by running the Julia REPL (Read-Eval-Print Loop).\n2. Press the `]` key to enter the Pkg mode.\n3. To add a package, use the `add` command followed by the package name.\n4. Press the backspace key to exit Pkg mode and return to the Julia REPL.\n\nFor example, to add the `Example` package, you would enter:\n\n```julia\n]add Example\n```\n\nAfter the package is added, you can start using it in your Julia code by using the `using` keyword. For the `Example` package, you would add the following line to your code:\n\n```julia\nusing Example\n```\n\nNote: The first time you add a package, Julia may take some time to download and compile the package and its dependencies.")You can see that it had a placeholder for the actual question (ask) that we provided as a keyword argument. We did not have to write any system prompt for personas, tone, etc. – it was all provided by the template!
How to know which templates are available? You can search for them with aitemplates(): You can search by Symbol (only for partial name match), String (partial match on name or description), or Regex (more fields)
tmps = aitemplates("JuliaExpertAsk")1-element Vector{AITemplateMetadata}:\nPromptingTools.AITemplateMetadata\n name: Symbol JuliaExpertAsk\n description: String "For asking questions about Julia language. Placeholders: `ask`"\n version: String "1"\n wordcount: Int64 237\n variables: Array{Symbol}((1,))\n system_preview: String "You are a world-class Julia language programmer with the knowledge of the latest syntax. Your commun"\n user_preview: String "# Question\\n\\n{{ask}}"\n source: String ""You can see that it outputs a list of available templates that match the search - there is just one in this case.
Moreover, it shows not just the description, but also a preview of the actual prompts, placeholders available, and the length (to gauge how much it would cost).
If you use VSCode, you can display them in a nice scrollable table with vscodedisplay:
using DataFrames\nDataFrame(tmp) |> vscodedisplayYou can also just render the template to see the underlying mesages:
msgs = PT.render(AITemplate(:JuliaExpertAsk))2-element Vector{PromptingTools.AbstractChatMessage}:\n PromptingTools.SystemMessage("You are a world-class Julia language programmer with the knowledge of the latest syntax. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n PromptingTools.UserMessage{String}("# Question\\n\\n{{ask}}", [:ask], :usermessage)Now, you know exactly what's in the template!
If you want to modify it, simply change it and save it as a new file with save_template (see the docs ?save_template for more details).
Let's adjust the previous template to be more specific to a data analysis question:
tpl = [PT.SystemMessage("You are a world-class Julia language programmer with the knowledge of the latest syntax. You're also a senior Data Scientist and proficient in data analysis in Julia. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n PT.UserMessage("# Question\\n\\n{{ask}}")]2-element Vector{PromptingTools.AbstractChatMessage}:\n PromptingTools.SystemMessage("You are a world-class Julia language programmer with the knowledge of the latest syntax. You're also a senior Data Scientist and proficient in data analysis in Julia. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n PromptingTools.UserMessage{String}("# Question\\n\\n{{ask}}", [:ask], :usermessage)Templates are saved in the templates directory of the package. Name of the file will become the template name (eg, call :JuliaDataExpertAsk)
filename = joinpath(pkgdir(PromptingTools),\n "templates",\n "persona-task",\n "JuliaDataExpertAsk_123.json")\nPT.save_template(filename,\n tpl;\n description = "For asking data analysis questions in Julia language. Placeholders: `ask`")\nrm(filename) # cleanup if we don't like itWhen you create a new template, remember to re-load the templates with load_templates!() so that it's available for use.
PT.load_templates!();!!! If you have some good templates (or suggestions for the existing ones), please consider sharing them with the community by opening a PR to the templates directory!
This page was generated using Literate.jl.
', 28)) + ]); +} +const working_with_aitemplates = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + working_with_aitemplates as default +}; diff --git a/previews/PR252/assets/examples_working_with_aitemplates.md.9Sdjf5TX.lean.js b/previews/PR252/assets/examples_working_with_aitemplates.md.9Sdjf5TX.lean.js new file mode 100644 index 00000000..b171432b --- /dev/null +++ b/previews/PR252/assets/examples_working_with_aitemplates.md.9Sdjf5TX.lean.js @@ -0,0 +1,15 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, j as createBaseVNode, t as toDisplayString, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Using AITemplates","description":"","frontmatter":{},"headers":[],"relativePath":"examples/working_with_aitemplates.md","filePath":"examples/working_with_aitemplates.md","lastUpdated":null}'); +const _sfc_main = { name: "examples/working_with_aitemplates.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, [ + _cache[0] || (_cache[0] = createStaticVNode('Using AITemplates
This file contains examples of how to work with AITemplate(s).
First, let's import the package and define a helper link for calling un-exported functions:
using PromptingTools\nconst PT = PromptingToolsPromptingToolsLLM responses are only as good as the prompts you give them. However, great prompts take long time to write – AITemplate are a way to re-use great prompts!
', 6)), + createBaseVNode("p", null, 'AITemplates are just a collection of templated prompts (ie, set of "messages" that have placeholders like ' + toDisplayString(_ctx.question) + ")", 1), + _cache[1] || (_cache[1] = createStaticVNode('They are saved as JSON files in the templates directory. They are automatically loaded on package import, but you can always force a re-load with PT.load_templates!()
PT.load_templates!();You can (create them) and use them for any ai* function instead of a prompt: Let's use a template called :JuliaExpertAsk alternatively, you can use AITemplate(:JuliaExpertAsk) for cleaner dispatch
msg = aigenerate(:JuliaExpertAsk; ask = "How do I add packages?")AIMessage("To add packages in Julia, you can use the `Pkg` module. Here are the steps:\n\n1. Start Julia by running the Julia REPL (Read-Eval-Print Loop).\n2. Press the `]` key to enter the Pkg mode.\n3. To add a package, use the `add` command followed by the package name.\n4. Press the backspace key to exit Pkg mode and return to the Julia REPL.\n\nFor example, to add the `Example` package, you would enter:\n\n```julia\n]add Example\n```\n\nAfter the package is added, you can start using it in your Julia code by using the `using` keyword. For the `Example` package, you would add the following line to your code:\n\n```julia\nusing Example\n```\n\nNote: The first time you add a package, Julia may take some time to download and compile the package and its dependencies.")You can see that it had a placeholder for the actual question (ask) that we provided as a keyword argument. We did not have to write any system prompt for personas, tone, etc. – it was all provided by the template!
How to know which templates are available? You can search for them with aitemplates(): You can search by Symbol (only for partial name match), String (partial match on name or description), or Regex (more fields)
tmps = aitemplates("JuliaExpertAsk")1-element Vector{AITemplateMetadata}:\nPromptingTools.AITemplateMetadata\n name: Symbol JuliaExpertAsk\n description: String "For asking questions about Julia language. Placeholders: `ask`"\n version: String "1"\n wordcount: Int64 237\n variables: Array{Symbol}((1,))\n system_preview: String "You are a world-class Julia language programmer with the knowledge of the latest syntax. Your commun"\n user_preview: String "# Question\\n\\n{{ask}}"\n source: String ""You can see that it outputs a list of available templates that match the search - there is just one in this case.
Moreover, it shows not just the description, but also a preview of the actual prompts, placeholders available, and the length (to gauge how much it would cost).
If you use VSCode, you can display them in a nice scrollable table with vscodedisplay:
using DataFrames\nDataFrame(tmp) |> vscodedisplayYou can also just render the template to see the underlying mesages:
msgs = PT.render(AITemplate(:JuliaExpertAsk))2-element Vector{PromptingTools.AbstractChatMessage}:\n PromptingTools.SystemMessage("You are a world-class Julia language programmer with the knowledge of the latest syntax. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n PromptingTools.UserMessage{String}("# Question\\n\\n{{ask}}", [:ask], :usermessage)Now, you know exactly what's in the template!
If you want to modify it, simply change it and save it as a new file with save_template (see the docs ?save_template for more details).
Let's adjust the previous template to be more specific to a data analysis question:
tpl = [PT.SystemMessage("You are a world-class Julia language programmer with the knowledge of the latest syntax. You're also a senior Data Scientist and proficient in data analysis in Julia. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n PT.UserMessage("# Question\\n\\n{{ask}}")]2-element Vector{PromptingTools.AbstractChatMessage}:\n PromptingTools.SystemMessage("You are a world-class Julia language programmer with the knowledge of the latest syntax. You're also a senior Data Scientist and proficient in data analysis in Julia. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n PromptingTools.UserMessage{String}("# Question\\n\\n{{ask}}", [:ask], :usermessage)Templates are saved in the templates directory of the package. Name of the file will become the template name (eg, call :JuliaDataExpertAsk)
filename = joinpath(pkgdir(PromptingTools),\n "templates",\n "persona-task",\n "JuliaDataExpertAsk_123.json")\nPT.save_template(filename,\n tpl;\n description = "For asking data analysis questions in Julia language. Placeholders: `ask`")\nrm(filename) # cleanup if we don't like itWhen you create a new template, remember to re-load the templates with load_templates!() so that it's available for use.
PT.load_templates!();!!! If you have some good templates (or suggestions for the existing ones), please consider sharing them with the community by opening a PR to the templates directory!
This page was generated using Literate.jl.
', 28)) + ]); +} +const working_with_aitemplates = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + working_with_aitemplates as default +}; diff --git a/previews/PR252/assets/examples_working_with_custom_apis.md.BOKSUMR5.js b/previews/PR252/assets/examples_working_with_custom_apis.md.BOKSUMR5.js new file mode 100644 index 00000000..2c212030 --- /dev/null +++ b/previews/PR252/assets/examples_working_with_custom_apis.md.BOKSUMR5.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Custom APIs","description":"","frontmatter":{},"headers":[],"relativePath":"examples/working_with_custom_apis.md","filePath":"examples/working_with_custom_apis.md","lastUpdated":null}'); +const _sfc_main = { name: "examples/working_with_custom_apis.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('Custom APIs
PromptingTools allows you to use any OpenAI-compatible API (eg, MistralAI), including a locally hosted one like the server from llama.cpp.
using PromptingTools\nconst PT = PromptingToolsUsing MistralAI
Mistral models have long been dominating the open-source space. They are now available via their API, so you can use them with PromptingTools.jl!
msg = aigenerate("Say hi!"; model="mistral-tiny")\n# [ Info: Tokens: 114 @ Cost: $0.0 in 0.9 seconds\n# AIMessage("Hello there! I'm here to help answer any questions you might have, or assist you with tasks to the best of my abilities. How can I be of service to you today? If you have a specific question, feel free to ask and I'll do my best to provide accurate and helpful information. If you're looking for general assistance, I can help you find resources or information on a variety of topics. Let me know how I can help.")It all just works, because we have registered the models in the PromptingTools.MODEL_REGISTRY! There are currently 4 models available: mistral-tiny, mistral-small, mistral-medium, mistral-embed.
Under the hood, we use a dedicated schema MistralOpenAISchema that leverages most of the OpenAI-specific code base, so you can always provide that explicitly as the first argument:
const PT = PromptingTools\nmsg = aigenerate(PT.MistralOpenAISchema(), "Say Hi!"; model="mistral-tiny", api_key=ENV["MISTRAL_API_KEY"])As you can see, we can load your API key either from the ENV or via the Preferences.jl mechanism (see ?PREFERENCES for more information).
Using other OpenAI-compatible APIs
MistralAI are not the only ones who mimic the OpenAI API! There are many other exciting providers, eg, Perplexity.ai, Fireworks.ai.
As long as they are compatible with the OpenAI API (eg, sending messages with role and content keys), you can use them with PromptingTools.jl by using schema = CustomOpenAISchema():
# Set your API key and the necessary base URL for the API\napi_key = "..."\nprovider_url = "..." # provider API URL\nprompt = "Say hi!"\nmsg = aigenerate(PT.CustomOpenAISchema(), prompt; model="<some-model>", api_key, api_kwargs=(; url=provider_url))If you register the model names with `PT.register_model!`, you won't have to keep providing the `schema` manually.
Note: At the moment, we only support aigenerate and aiembed functions.
Using llama.cpp server
In line with the above, you can also use the llama.cpp server.
It is a bit more technically demanding because you need to "compile" llama.cpp first, but it will always have the latest models and it is quite fast (eg, faster than Ollama, which uses llama.cpp under the hood but has some extra overhead).
Start your server in a command line (-m refers to the model file, -c is the context length, -ngl is the number of layers to offload to GPU):
./server -m models/mixtral-8x7b-instruct-v0.1.Q4_K_M.gguf -c 2048 -ngl 99Then simply access it via PromptingTools:
msg = aigenerate(PT.CustomOpenAISchema(), "Count to 5 and say hi!"; api_kwargs=(; url="http://localhost:8080/v1"))If you register the model names with `PT.register_model!`, you won't have to keep providing the `schema` manually. It can be any `model` name, because the model is actually selected when you start the server in the terminal.
Using Databricks Foundation Models
You can also use the Databricks Foundation Models API with PromptingTools.jl. It requires you to set ENV variables DATABRICKS_API_KEY (often referred to as "DATABRICKS TOKEN") and DATABRICKS_HOST.
The long way to use it is:
msg = aigenerate(PT.DatabricksOpenAISchema(),\n "Say hi to the llama!";\n model = "databricks-llama-2-70b-chat",\n api_key = ENV["DATABRICKS_API_KEY"], api_kwargs = (; url=ENV["DATABRICKS_HOST"]))But you can also register the models you're hosting and use it as usual:
# Quick registration of a model\nPT.register_model!(;\n name = "databricks-llama-2-70b-chat",\n schema = PT.DatabricksOpenAISchema())\nPT.MODEL_ALIASES["dllama"] = "databricks-llama-2-70b-chat" # set alias to make your life easier\n\n# Simply call:\nmsg = aigenerate("Say hi to the llama!"; model = "dllama")\n# Or even shorter\nai"Say hi to the llama!"dllamaYou can use aiembed as well.
Find more information here.
Using Together.ai
You can also use the Together.ai API with PromptingTools.jl. It requires you to set ENV variable TOGETHER_API_KEY.
The corresponding schema is TogetherOpenAISchema, but we have registered one model for you, so you can use it as usual. Alias "tmixtral" (T for Together.ai and mixtral for the model name) is already set for you.
msg = aigenerate("Say hi"; model="tmixtral")\n## [ Info: Tokens: 87 @ Cost: \\$0.0001 in 5.1 seconds\n## AIMessage("Hello! I'm here to help you. Is there something specific you'd like to know or discuss? I can provide information on a wide range of topics, assist with tasks, and even engage in a friendly conversation. Let me know how I can best assist you today.")For embedding a text, use aiembed:
aiembed(PT.TogetherOpenAISchema(), "embed me"; model="BAAI/bge-large-en-v1.5")Note: You can register the model with PT.register_model! and use it as usual.
Using Fireworks.ai
You can also use the Fireworks.ai API with PromptingTools.jl. It requires you to set ENV variable FIREWORKS_API_KEY.
The corresponding schema is FireworksOpenAISchema, but we have registered one model for you, so you can use it as usual. Alias "fmixtral" (F for Fireworks.ai and mixtral for the model name) is already set for you.
msg = aigenerate("Say hi"; model="fmixtral")\n## [ Info: Tokens: 78 @ Cost: \\$0.0001 in 0.9 seconds\n## AIMessage("Hello! I'm glad you're here. I'm here to help answer any questions you have to the best of my ability. Is there something specific you'd like to know or discuss? I can assist with a wide range of topics, so feel free to ask me anything!")In addition, at the time of writing (23rd Feb 2024), Fireworks is providing access to their new function calling model (fine-tuned Mixtral) for free.
Try it with aiextract for structured extraction (model is aliased as firefunction):
"""\nExtract the food from the sentence. Extract any provided adjectives for the food as well.\n\nExample: "I am eating a crunchy bread." -> Food("bread", ["crunchy"])\n"""\nstruct Food\n name::String\n adjectives::Union{Nothing,Vector{String}}\nend\nprompt = "I just ate a delicious and juicy apple."\nmsg = aiextract(prompt; return_type=Food, model="firefunction")\nmsg.content\n# Output: Food("apple", ["delicious", "juicy"])For embedding a text, use aiembed:
aiembed(PT.FireworksOpenAISchema(), "embed me"; model="nomic-ai/nomic-embed-text-v1.5")Note: You can register the model with PT.register_model! and use it as usual.
Custom APIs
PromptingTools allows you to use any OpenAI-compatible API (eg, MistralAI), including a locally hosted one like the server from llama.cpp.
using PromptingTools\nconst PT = PromptingToolsUsing MistralAI
Mistral models have long been dominating the open-source space. They are now available via their API, so you can use them with PromptingTools.jl!
msg = aigenerate("Say hi!"; model="mistral-tiny")\n# [ Info: Tokens: 114 @ Cost: $0.0 in 0.9 seconds\n# AIMessage("Hello there! I'm here to help answer any questions you might have, or assist you with tasks to the best of my abilities. How can I be of service to you today? If you have a specific question, feel free to ask and I'll do my best to provide accurate and helpful information. If you're looking for general assistance, I can help you find resources or information on a variety of topics. Let me know how I can help.")It all just works, because we have registered the models in the PromptingTools.MODEL_REGISTRY! There are currently 4 models available: mistral-tiny, mistral-small, mistral-medium, mistral-embed.
Under the hood, we use a dedicated schema MistralOpenAISchema that leverages most of the OpenAI-specific code base, so you can always provide that explicitly as the first argument:
const PT = PromptingTools\nmsg = aigenerate(PT.MistralOpenAISchema(), "Say Hi!"; model="mistral-tiny", api_key=ENV["MISTRAL_API_KEY"])As you can see, we can load your API key either from the ENV or via the Preferences.jl mechanism (see ?PREFERENCES for more information).
Using other OpenAI-compatible APIs
MistralAI are not the only ones who mimic the OpenAI API! There are many other exciting providers, eg, Perplexity.ai, Fireworks.ai.
As long as they are compatible with the OpenAI API (eg, sending messages with role and content keys), you can use them with PromptingTools.jl by using schema = CustomOpenAISchema():
# Set your API key and the necessary base URL for the API\napi_key = "..."\nprovider_url = "..." # provider API URL\nprompt = "Say hi!"\nmsg = aigenerate(PT.CustomOpenAISchema(), prompt; model="<some-model>", api_key, api_kwargs=(; url=provider_url))If you register the model names with `PT.register_model!`, you won't have to keep providing the `schema` manually.
Note: At the moment, we only support aigenerate and aiembed functions.
Using llama.cpp server
In line with the above, you can also use the llama.cpp server.
It is a bit more technically demanding because you need to "compile" llama.cpp first, but it will always have the latest models and it is quite fast (eg, faster than Ollama, which uses llama.cpp under the hood but has some extra overhead).
Start your server in a command line (-m refers to the model file, -c is the context length, -ngl is the number of layers to offload to GPU):
./server -m models/mixtral-8x7b-instruct-v0.1.Q4_K_M.gguf -c 2048 -ngl 99Then simply access it via PromptingTools:
msg = aigenerate(PT.CustomOpenAISchema(), "Count to 5 and say hi!"; api_kwargs=(; url="http://localhost:8080/v1"))If you register the model names with `PT.register_model!`, you won't have to keep providing the `schema` manually. It can be any `model` name, because the model is actually selected when you start the server in the terminal.
Using Databricks Foundation Models
You can also use the Databricks Foundation Models API with PromptingTools.jl. It requires you to set ENV variables DATABRICKS_API_KEY (often referred to as "DATABRICKS TOKEN") and DATABRICKS_HOST.
The long way to use it is:
msg = aigenerate(PT.DatabricksOpenAISchema(),\n "Say hi to the llama!";\n model = "databricks-llama-2-70b-chat",\n api_key = ENV["DATABRICKS_API_KEY"], api_kwargs = (; url=ENV["DATABRICKS_HOST"]))But you can also register the models you're hosting and use it as usual:
# Quick registration of a model\nPT.register_model!(;\n name = "databricks-llama-2-70b-chat",\n schema = PT.DatabricksOpenAISchema())\nPT.MODEL_ALIASES["dllama"] = "databricks-llama-2-70b-chat" # set alias to make your life easier\n\n# Simply call:\nmsg = aigenerate("Say hi to the llama!"; model = "dllama")\n# Or even shorter\nai"Say hi to the llama!"dllamaYou can use aiembed as well.
Find more information here.
Using Together.ai
You can also use the Together.ai API with PromptingTools.jl. It requires you to set ENV variable TOGETHER_API_KEY.
The corresponding schema is TogetherOpenAISchema, but we have registered one model for you, so you can use it as usual. Alias "tmixtral" (T for Together.ai and mixtral for the model name) is already set for you.
msg = aigenerate("Say hi"; model="tmixtral")\n## [ Info: Tokens: 87 @ Cost: \\$0.0001 in 5.1 seconds\n## AIMessage("Hello! I'm here to help you. Is there something specific you'd like to know or discuss? I can provide information on a wide range of topics, assist with tasks, and even engage in a friendly conversation. Let me know how I can best assist you today.")For embedding a text, use aiembed:
aiembed(PT.TogetherOpenAISchema(), "embed me"; model="BAAI/bge-large-en-v1.5")Note: You can register the model with PT.register_model! and use it as usual.
Using Fireworks.ai
You can also use the Fireworks.ai API with PromptingTools.jl. It requires you to set ENV variable FIREWORKS_API_KEY.
The corresponding schema is FireworksOpenAISchema, but we have registered one model for you, so you can use it as usual. Alias "fmixtral" (F for Fireworks.ai and mixtral for the model name) is already set for you.
msg = aigenerate("Say hi"; model="fmixtral")\n## [ Info: Tokens: 78 @ Cost: \\$0.0001 in 0.9 seconds\n## AIMessage("Hello! I'm glad you're here. I'm here to help answer any questions you have to the best of my ability. Is there something specific you'd like to know or discuss? I can assist with a wide range of topics, so feel free to ask me anything!")In addition, at the time of writing (23rd Feb 2024), Fireworks is providing access to their new function calling model (fine-tuned Mixtral) for free.
Try it with aiextract for structured extraction (model is aliased as firefunction):
"""\nExtract the food from the sentence. Extract any provided adjectives for the food as well.\n\nExample: "I am eating a crunchy bread." -> Food("bread", ["crunchy"])\n"""\nstruct Food\n name::String\n adjectives::Union{Nothing,Vector{String}}\nend\nprompt = "I just ate a delicious and juicy apple."\nmsg = aiextract(prompt; return_type=Food, model="firefunction")\nmsg.content\n# Output: Food("apple", ["delicious", "juicy"])For embedding a text, use aiembed:
aiembed(PT.FireworksOpenAISchema(), "embed me"; model="nomic-ai/nomic-embed-text-v1.5")Note: You can register the model with PT.register_model! and use it as usual.
Working with Google AI Studio
This file contains examples of how to work with Google AI Studio. It is known for its Gemini models.
Get an API key from here. If you see a documentation page ("Available languages and regions for Google AI Studio and Gemini API"), it means that it's not yet available in your region.
Save the API key in your environment as GOOGLE_API_KEY.
We'll need GoogleGenAI package:
using Pkg; Pkg.add("GoogleGenAI")You can now use the Gemini-1.0-Pro model like any other model in PromptingTools. We only support aigenerate at the moment.
Let's import PromptingTools:
using PromptingTools\nconst PT = PromptingToolsText Generation with aigenerate
You can use the alias "gemini" for the Gemini-1.0-Pro model.
Simple message
msg = aigenerate("Say hi!"; model = "gemini")AIMessage("Hi there! As a helpful AI assistant, I'm here to help you with any questions or tasks you may have. Feel free to ask me anything, and I'll do my best to assist you.")You could achieve the same with a string macro (notice the "gemini" at the end to specify which model to use):
ai"Say hi!"geminiAdvanced Prompts
You can provide multi-turn conversations like with any other model:
conversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\nmsg = aigenerate(conversation; model="gemini")AIMessage("Young Padawan, you have stumbled into a dangerous path. Attachment leads to suffering, and love can turn to darkness. \n\nRelease your feelings for this inanimate object. \n\nThe Force flows through all living things, not machines. Seek balance in the Force, and your heart will find true connection. \n\nRemember, the path of the Jedi is to serve others, not to be attached to possessions.")Gotchas
Gemini models actually do NOT have a system prompt (for instructions), so we simply concatenate the system and user messages together for consistency with other APIs.
The reported
tokensin theAIMessageare actually characters (that's how Google AI Studio intends to charge for them) and are a conservative estimate that we produce. It does not matter, because at the time of writing (Feb-24), the usage is free-of-charge.
Working with Google AI Studio
This file contains examples of how to work with Google AI Studio. It is known for its Gemini models.
Get an API key from here. If you see a documentation page ("Available languages and regions for Google AI Studio and Gemini API"), it means that it's not yet available in your region.
Save the API key in your environment as GOOGLE_API_KEY.
We'll need GoogleGenAI package:
using Pkg; Pkg.add("GoogleGenAI")You can now use the Gemini-1.0-Pro model like any other model in PromptingTools. We only support aigenerate at the moment.
Let's import PromptingTools:
using PromptingTools\nconst PT = PromptingToolsText Generation with aigenerate
You can use the alias "gemini" for the Gemini-1.0-Pro model.
Simple message
msg = aigenerate("Say hi!"; model = "gemini")AIMessage("Hi there! As a helpful AI assistant, I'm here to help you with any questions or tasks you may have. Feel free to ask me anything, and I'll do my best to assist you.")You could achieve the same with a string macro (notice the "gemini" at the end to specify which model to use):
ai"Say hi!"geminiAdvanced Prompts
You can provide multi-turn conversations like with any other model:
conversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\nmsg = aigenerate(conversation; model="gemini")AIMessage("Young Padawan, you have stumbled into a dangerous path. Attachment leads to suffering, and love can turn to darkness. \n\nRelease your feelings for this inanimate object. \n\nThe Force flows through all living things, not machines. Seek balance in the Force, and your heart will find true connection. \n\nRemember, the path of the Jedi is to serve others, not to be attached to possessions.")Gotchas
Gemini models actually do NOT have a system prompt (for instructions), so we simply concatenate the system and user messages together for consistency with other APIs.
The reported
tokensin theAIMessageare actually characters (that's how Google AI Studio intends to charge for them) and are a conservative estimate that we produce. It does not matter, because at the time of writing (Feb-24), the usage is free-of-charge.
Local models with Ollama.ai
This file contains examples of how to work with Ollama.ai models. It assumes that you've already installated and launched the Ollama server. For more details or troubleshooting advice, see the Frequently Asked Questions section.
First, let's import the package and define a helper link for calling un-exported functions:
using PromptingTools\nconst PT = PromptingToolsPromptingToolsThere were are several models from https://ollama.ai/library that we have added to our PT.MODEL_REGISTRY, which means you don't need to worry about schema changes: Eg, "llama2" or "openhermes2.5-mistral" (see PT.list_registry() and PT.list_aliases())
Note: You must download these models prior to using them with ollama pull <model_name> in your Terminal.
If you use Apple Mac M1-3, make sure to provide `api_kwargs=(; options=(; num_gpu=99))` to make sure the whole model is offloaded on your GPU. Current default is 1, which makes some models unusable. Example for running Mixtral: `msg = aigenerate(PT.OllamaSchema(), "Count from 1 to 5 and then say hi."; model="dolphin-mixtral:8x7b-v2.5-q4_K_M", api_kwargs=(; options=(; num_gpu=99)))`
Text Generation with aigenerate
Simple message
TL;DR if you use models in PT.MODEL_REGISTRY, you don't need to add schema as the first argument:
msg = aigenerate("Say hi!"; model = "llama2")AIMessage("Hello there! *adjusts glasses* It's nice to meet you! Is there anything I can help you with or would you like me to chat with you for a bit?")Standard string interpolation
model = "openhermes2.5-mistral"\n\na = 1\nmsg = aigenerate("What is `$a+$a`?"; model)\n\nname = "John"\nmsg = aigenerate("Say hi to {{name}}."; name, model)AIMessage("Hello John! *smiles* It's nice to meet you! Is there anything I can help you with today?")Advanced Prompts
conversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\nmsg = aigenerate(conversation; model)AIMessage("(Deep sigh) A problem, you have. Feelings for an iPhone, hmm? (adjusts spectacles)\n\nMuch confusion, this causes. (scratches head) A being, you are. Attached to a device, you have become. (chuckles) Interesting, this is.\n\nFirst, let go, you must. (winks) Hard, it is, but necessary, yes. Distract yourself, find something else, try. (pauses)\n\nOr, perhaps, a balance, you seek? (nods) Both, enjoy and let go, the middle path, there is. (smirks) Finding joy in technology, without losing yourself, the trick, it is. (chuckles)\n\nBut fear not, young one! (grins) Help, I am here. Guide you, I will. The ways of the Yedi, teach you, I will. (winks) Patience and understanding, you must have. (nods)\n\nNow, go forth! (gestures) Explore, discover, find your balance. (smiles) The Force be with you, it does! (grins)")Schema Changes / Custom models
If you're using some model that is not in the registry, you can either add it:
PT.register_model!(;\n name = "llama123",\n schema = PT.OllamaSchema(),\n description = "Some model")\nPT.MODEL_ALIASES["l123"] = "llama123" # set an alias you like for it"llama123"OR define the schema explicitly (to avoid dispatch on global PT.PROMPT_SCHEMA):
schema = PT.OllamaSchema()\naigenerate(schema, "Say hi!"; model = "llama2")AIMessage("Hello there! *smiling face* It's nice to meet you! I'm here to help you with any questions or tasks you may have, so feel free to ask me anything. Is there something specific you need assistance with today? 😊")Note: If you only use Ollama, you can change the default schema to PT.OllamaSchema() via PT.set_preferences!("PROMPT_SCHEMA" => "OllamaSchema", "MODEL_CHAT"=>"llama2")
Restart your session and run aigenerate("Say hi!") to test it.
! Note that in version 0.6, we've introduced OllamaSchema, which superseded OllamaManagedSchema and allows multi-turn conversations and conversations with images (eg, with Llava and Bakllava models). OllamaManagedSchema has been kept for compatibility and as an example of a schema where one provides a prompt as a string (not dictionaries like OpenAI API).
Providing Images with aiscan
It's as simple as providing a local image path (keyword image_path). You can provide one or more images:
msg = aiscan("Describe the image"; image_path=["julia.png","python.png"] model="bakllava")image_url keyword is not supported at the moment (use Downloads.download to download the image locally).
Embeddings with aiembed
Simple embedding for one document
msg = aiembed(schema, "Embed me"; model) # access msg.contentPromptingTools.DataMessage(JSON3.Array{Float64, Vector{UInt8}, SubArray{UInt64, 1, Vector{UInt64}, Tuple{UnitRange{Int64}}, true}} of size (4096,))One document and we materialize the data into a Vector with copy (postprocess function argument)
msg = aiembed(schema, "Embed me", copy; model)PromptingTools.DataMessage(Vector{Float64} of size (4096,))Multiple documents embedding
Multiple documents - embedded sequentially, you can get faster speed with async
msg = aiembed(schema, ["Embed me", "Embed me"]; model)PromptingTools.DataMessage(Matrix{Float64} of size (4096, 2))You can use Threads.@spawn or asyncmap, whichever you prefer, to paralellize the model calls
docs = ["Embed me", "Embed me"]\ntasks = asyncmap(docs) do doc\n msg = aiembed(schema, doc; model)\nend\nembedding = mapreduce(x -> x.content, hcat, tasks)\nsize(embedding)4096×2 Matrix{Float64}:\n...Using postprocessing function
Add normalization as postprocessing function to normalize embeddings on reception (for easy cosine similarity later)
using LinearAlgebra\nschema = PT.OllamaSchema()\n\nmsg = aiembed(schema,\n ["embed me", "and me too"],\n LinearAlgebra.normalize;\n model = "openhermes2.5-mistral")PromptingTools.DataMessage(Matrix{Float64} of size (4096, 2))Cosine similarity is then a simple multiplication
msg.content' * msg.content[:, 1]2-element Vector{Float64}:\n 0.9999999999999982\n 0.40796033843072876This page was generated using Literate.jl.
', 56) + ])); +} +const working_with_ollama = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + working_with_ollama as default +}; diff --git a/previews/PR252/assets/examples_working_with_ollama.md.CbOfWzMk.lean.js b/previews/PR252/assets/examples_working_with_ollama.md.CbOfWzMk.lean.js new file mode 100644 index 00000000..ea884d02 --- /dev/null +++ b/previews/PR252/assets/examples_working_with_ollama.md.CbOfWzMk.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Local models with Ollama.ai","description":"","frontmatter":{},"headers":[],"relativePath":"examples/working_with_ollama.md","filePath":"examples/working_with_ollama.md","lastUpdated":null}'); +const _sfc_main = { name: "examples/working_with_ollama.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('Local models with Ollama.ai
This file contains examples of how to work with Ollama.ai models. It assumes that you've already installated and launched the Ollama server. For more details or troubleshooting advice, see the Frequently Asked Questions section.
First, let's import the package and define a helper link for calling un-exported functions:
using PromptingTools\nconst PT = PromptingToolsPromptingToolsThere were are several models from https://ollama.ai/library that we have added to our PT.MODEL_REGISTRY, which means you don't need to worry about schema changes: Eg, "llama2" or "openhermes2.5-mistral" (see PT.list_registry() and PT.list_aliases())
Note: You must download these models prior to using them with ollama pull <model_name> in your Terminal.
If you use Apple Mac M1-3, make sure to provide `api_kwargs=(; options=(; num_gpu=99))` to make sure the whole model is offloaded on your GPU. Current default is 1, which makes some models unusable. Example for running Mixtral: `msg = aigenerate(PT.OllamaSchema(), "Count from 1 to 5 and then say hi."; model="dolphin-mixtral:8x7b-v2.5-q4_K_M", api_kwargs=(; options=(; num_gpu=99)))`
Text Generation with aigenerate
Simple message
TL;DR if you use models in PT.MODEL_REGISTRY, you don't need to add schema as the first argument:
msg = aigenerate("Say hi!"; model = "llama2")AIMessage("Hello there! *adjusts glasses* It's nice to meet you! Is there anything I can help you with or would you like me to chat with you for a bit?")Standard string interpolation
model = "openhermes2.5-mistral"\n\na = 1\nmsg = aigenerate("What is `$a+$a`?"; model)\n\nname = "John"\nmsg = aigenerate("Say hi to {{name}}."; name, model)AIMessage("Hello John! *smiles* It's nice to meet you! Is there anything I can help you with today?")Advanced Prompts
conversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\nmsg = aigenerate(conversation; model)AIMessage("(Deep sigh) A problem, you have. Feelings for an iPhone, hmm? (adjusts spectacles)\n\nMuch confusion, this causes. (scratches head) A being, you are. Attached to a device, you have become. (chuckles) Interesting, this is.\n\nFirst, let go, you must. (winks) Hard, it is, but necessary, yes. Distract yourself, find something else, try. (pauses)\n\nOr, perhaps, a balance, you seek? (nods) Both, enjoy and let go, the middle path, there is. (smirks) Finding joy in technology, without losing yourself, the trick, it is. (chuckles)\n\nBut fear not, young one! (grins) Help, I am here. Guide you, I will. The ways of the Yedi, teach you, I will. (winks) Patience and understanding, you must have. (nods)\n\nNow, go forth! (gestures) Explore, discover, find your balance. (smiles) The Force be with you, it does! (grins)")Schema Changes / Custom models
If you're using some model that is not in the registry, you can either add it:
PT.register_model!(;\n name = "llama123",\n schema = PT.OllamaSchema(),\n description = "Some model")\nPT.MODEL_ALIASES["l123"] = "llama123" # set an alias you like for it"llama123"OR define the schema explicitly (to avoid dispatch on global PT.PROMPT_SCHEMA):
schema = PT.OllamaSchema()\naigenerate(schema, "Say hi!"; model = "llama2")AIMessage("Hello there! *smiling face* It's nice to meet you! I'm here to help you with any questions or tasks you may have, so feel free to ask me anything. Is there something specific you need assistance with today? 😊")Note: If you only use Ollama, you can change the default schema to PT.OllamaSchema() via PT.set_preferences!("PROMPT_SCHEMA" => "OllamaSchema", "MODEL_CHAT"=>"llama2")
Restart your session and run aigenerate("Say hi!") to test it.
! Note that in version 0.6, we've introduced OllamaSchema, which superseded OllamaManagedSchema and allows multi-turn conversations and conversations with images (eg, with Llava and Bakllava models). OllamaManagedSchema has been kept for compatibility and as an example of a schema where one provides a prompt as a string (not dictionaries like OpenAI API).
Providing Images with aiscan
It's as simple as providing a local image path (keyword image_path). You can provide one or more images:
msg = aiscan("Describe the image"; image_path=["julia.png","python.png"] model="bakllava")image_url keyword is not supported at the moment (use Downloads.download to download the image locally).
Embeddings with aiembed
Simple embedding for one document
msg = aiembed(schema, "Embed me"; model) # access msg.contentPromptingTools.DataMessage(JSON3.Array{Float64, Vector{UInt8}, SubArray{UInt64, 1, Vector{UInt64}, Tuple{UnitRange{Int64}}, true}} of size (4096,))One document and we materialize the data into a Vector with copy (postprocess function argument)
msg = aiembed(schema, "Embed me", copy; model)PromptingTools.DataMessage(Vector{Float64} of size (4096,))Multiple documents embedding
Multiple documents - embedded sequentially, you can get faster speed with async
msg = aiembed(schema, ["Embed me", "Embed me"]; model)PromptingTools.DataMessage(Matrix{Float64} of size (4096, 2))You can use Threads.@spawn or asyncmap, whichever you prefer, to paralellize the model calls
docs = ["Embed me", "Embed me"]\ntasks = asyncmap(docs) do doc\n msg = aiembed(schema, doc; model)\nend\nembedding = mapreduce(x -> x.content, hcat, tasks)\nsize(embedding)4096×2 Matrix{Float64}:\n...Using postprocessing function
Add normalization as postprocessing function to normalize embeddings on reception (for easy cosine similarity later)
using LinearAlgebra\nschema = PT.OllamaSchema()\n\nmsg = aiembed(schema,\n ["embed me", "and me too"],\n LinearAlgebra.normalize;\n model = "openhermes2.5-mistral")PromptingTools.DataMessage(Matrix{Float64} of size (4096, 2))Cosine similarity is then a simple multiplication
msg.content' * msg.content[:, 1]2-element Vector{Float64}:\n 0.9999999999999982\n 0.40796033843072876This page was generated using Literate.jl.
', 56) + ])); +} +const working_with_ollama = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + working_with_ollama as default +}; diff --git a/previews/PR252/assets/extra_tools_agent_tools_intro.md.CGplc6KB.js b/previews/PR252/assets/extra_tools_agent_tools_intro.md.CGplc6KB.js new file mode 100644 index 00000000..817d10ec --- /dev/null +++ b/previews/PR252/assets/extra_tools_agent_tools_intro.md.CGplc6KB.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Agent Tools Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"extra_tools/agent_tools_intro.md","filePath":"extra_tools/agent_tools_intro.md","lastUpdated":null}'); +const _sfc_main = { name: "extra_tools/agent_tools_intro.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('Agent Tools Introduction
AgentTools is an experimental module that provides a set of utilities for building advanced agentic workflows, code-generating and self-fixing agents.
Import the module as follows:
using PromptingTools.Experimental.AgentTools\n# to access unexported functionality\nconst AT = PromptingTools.Experimental.AgentToolsHighlights
The main functions to be aware of are:
AIGenerate- Lazy counterpart ofaigenerate(). Allai*functions have a correspondingAI*::AICallstruct that allows for deferred execution (triggered byrun!method).last_output,last_message- Simple utilities to access the last output and message of the AI calls likeAIGenerate.airetry!- A utility to automatically retry the AI call with the same inputs if the AI model fails to generate a valid output. It allows retrying many times and providing feedback to the AI model about the failure to increase its robustness.AIGenerateand other AI calls have a fieldconfig::RetryConfigwhere you can globally adjust the retrying behavior.print_samples-airetry!implements a Monte Carlo Tree Search under the hood when trying to find the best way to fix the AI model's failure.print_samplesis a utility to print the "samples" generated by the MCTS to better understand the attempts made by the AI model to fix the failure.AICodeextensions likeaicodefixer_feedbackanderror_feedback-AICodeis a wrapper that extracts any Julia code provided in theAIMessage(response from the AI model) and executes it (including catch any errors).aicodefixer_feedbackanderror_feedbackare utilities that automatically review an outcome ofAICodeevaluation and generate the corresponding feedback for the AI model.
The main contribution of this module is providing the "lazy" counterparts to the ai... functions, which allow us to build a workflow, which can be re-executed many times with the same inputs.
For example, AIGenerate() will create a lazy instance of aigenerate, which is an instance of AICall with aigenerate as its ai-calling function. It uses exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details). The notion of "lazy" refers to the fact that it does NOT generate any output when instantiated (only when run! is called).
Or said differently, the AICall struct and all its flavors (AIGenerate, ...) are designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied. This allows us to remember user inputs and trigger the LLM call repeatedly if needed, which enables automatic fixing (see ?airetry!).
Examples
Automatic Fixing of AI Calls
We need to switch from aigenerate to AIGenerate to get the lazy version of the function.
output = AIGenerate("Say hi!"; model="gpt4t") |> run!How is it useful? We can use the same "inputs" for repeated calls, eg, when we want to validate or regenerate some outputs. We have a function airetry! to help us with that.
The signature of airetry is airetry(condition_function, aicall::AICall, feedback_function).
It evaluates the condition condition_function on the aicall object (eg, we evaluate f_cond(aicall) -> Bool). If it fails, we call feedback_function on the aicall object to provide feedback for the AI model (eg, f_feedback(aicall) -> String) and repeat the process until it passes or until max_retries value is exceeded.
We can catch API failures (no feedback needed, so none is provided)
# API failure because of a non-existent model\n# RetryConfig allows us to change the "retry" behaviour of any lazy call\noutput = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\n model = "NOTEXIST")\nrun!(output) # fails\n\n# we ask to wait 2s between retries and retry 2 times (can be set in `config` in aicall as well)\nairetry!(isvalid, output; retry_delay = 2, max_retries = 2)Or we can use it for output validation (eg, its format, its content, etc.) and feedback generation.
Let's play a color guessing game (I'm thinking "yellow"). We'll implement two formatting checks with airetry!:
# Notice that we ask for two samples (`n_samples=2`) at each attempt (to improve our chances). \n# Both guesses are scored at each time step, and the best one is chosen for the next step.\n# And with OpenAI, we can set `api_kwargs = (;n=2)` to get both samples simultaneously (cheaper and faster)!\nout = AIGenerate(\n "Guess what color I'm thinking. It could be: blue, red, black, white, yellow. Answer with 1 word only";\n verbose = false,\n config = RetryConfig(; n_samples = 2), api_kwargs = (; n = 2))\nrun!(out)\n\n## Check that the output is 1 word only, third argument is the feedback that will be provided if the condition fails\n## Notice: functions operate on `aicall` as the only argument. We can use utilities like `last_output` and `last_message` to access the last message and output in the conversation.\nairetry!(x -> length(split(last_output(x), r" |\\\\.")) == 1, out,\n "You must answer with 1 word only.")\n\n# Note: you could also use the do-syntax, eg, \nairetry!(out, "You must answer with 1 word only.") do aicall\n length(split(last_output(aicall), r" |\\\\.")) == 1\nendYou can even add the guessing itself as an airetry! condition of last_output(out) == "yellow" and provide feedback if the guess is wrong.
References
AIGenerate(args...; kwargs...)Creates a lazy instance of aigenerate. It is an instance of AICall with aigenerate as the function.
Use exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details).
AICall(func::F, args...; kwargs...) where {F<:Function}\n\nAIGenerate(args...; kwargs...)\nAIEmbed(args...; kwargs...)\nAIExtract(args...; kwargs...)A lazy call wrapper for AI functions in the PromptingTools module, such as aigenerate.
The AICall struct is designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied. This approach allows for more flexible and efficient handling of AI function calls, especially in interactive environments.
Seel also: run!, AICodeFixer
Fields
func::F: The AI function to be called lazily. This should be a function likeaigenerateor otherai*functions.schema::Union{Nothing, PT.AbstractPromptSchema}: Optional schema to structure the prompt for the AI function.conversation::Vector{PT.AbstractMessage}: A vector of messages that forms the conversation context for the AI call.kwargs::NamedTuple: Keyword arguments to be passed to the AI function.success::Union{Nothing, Bool}: Indicates whether the last call was successful (true) or not (false).Nothingif the call hasn't been made yet.error::Union{Nothing, Exception}: Stores any exception that occurred during the last call.Nothingif no error occurred or if the call hasn't been made yet.
Example
Initiate an AICall like any ai* function, eg, AIGenerate:
aicall = AICall(aigenerate)\n\n# With arguments and kwargs like ai* functions\n# from `aigenerate(schema, conversation; model="abc", api_kwargs=(; temperature=0.1))`\n# to\naicall = AICall(aigenerate, schema, conversation; model="abc", api_kwargs=(; temperature=0.1)\n\n# Or with a template\naicall = AIGenerate(:JuliaExpertAsk; ask="xyz", model="abc", api_kwargs=(; temperature=0.1))Trigger the AICall with run! (it returns the update AICall struct back):
aicall |> run!\n````\n\nYou can also use `AICall` as a functor to trigger the AI call with a `UserMessage` or simply the text to send:julia aicall(UserMessage("Hello, world!")) # Triggers the lazy call result = run!(aicall) # Explicitly runs the AI call ``` This can be used to "reply" to previous message / continue the stored conversation
Notes
The
AICallstruct is a key component in building flexible and efficient Agentic pipelinesThe lazy evaluation model allows for setting up the call parameters in advance and deferring the actual execution until it is explicitly triggered.
This struct is particularly useful in scenarios where the timing of AI function execution needs to be deferred or where multiple potential calls need to be prepared and selectively executed.
Extracts the last output (generated text answer) from the RAGResult.
Helpful accessor for AICall blocks. Returns the last output in the conversation (eg, the string/data in the last message).
Helpful accessor for the last generated output (msg.content) in conversation. Returns the last output in the conversation (eg, the string/data in the last message).
last_output(mem::ConversationMemory)Get the last AI message in the conversation.
PT.last_message(result::RAGResult)Extract the last message from the RAGResult. It looks for final_answer first, then answer fields in the conversations dictionary. Returns nothing if not found.
Helpful accessor for AICall blocks. Returns the last message in the conversation.
Helpful accessor for the last message in conversation. Returns the last message in the conversation.
last_message(mem::ConversationMemory)Get the last message in the conversation.
airetry!(\n f_cond::Function, aicall::AICallBlock, feedback::Union{AbstractString, Function} = "";\n verbose::Bool = true, throw::Bool = false, evaluate_all::Bool = true, feedback_expensive::Bool = false,\n max_retries::Union{Nothing, Int} = nothing, retry_delay::Union{Nothing, Int} = nothing)Evaluates the condition f_cond on the aicall object. If the condition is not met, it will return the best sample to retry from and provide feedback (string or function) to aicall. That's why it's mutating. It will retry maximum max_retries times, with throw=true, an error will be thrown if the condition is not met after max_retries retries.
Note: aicall must be run first via run!(aicall) before calling airetry!.
Function signatures
f_cond(aicall::AICallBlock) -> Bool, ie, it must accept the aicall object and return a boolean value.feedbackcan be a string orfeedback(aicall::AICallBlock) -> String, ie, it must accept the aicall object and return a string.
You can leverage the last_message, last_output, and AICode functions to access the last message, last output and execute code blocks in the conversation, respectively. See examples below.
Good Use Cases
Retry with API failures/drops (add
retry_delay=2to wait 2s between retries)Check the output format / type / length / etc
Check the output with
aiclassifycall (LLM Judge) to catch unsafe/NSFW/out-of-scope contentProvide hints to the model to guide it to the correct answer
Gotchas
If controlling keyword arguments are set to nothing, they will fall back to the default values in
aicall.config. You can override them by passing the keyword arguments explicitly.If there multiple
airetry!checks, they are evaluted sequentially. As long asthrow==false, they will be all evaluated even if they failed previous checks.Only samples which passed previous evaluations are evaluated (
sample.successistrue). If there are no successful samples, the function will evaluate only the active sample (aicall.active_sample_id) and nothing else.Feedback from all "ancestor" evaluations is added upon retry, not feedback from the "sibblings" or other branches. To have only ONE long BRANCH (no sibblings), make sure to keep
RetryConfig(; n_samples=1). That way the model will always see ALL previous feedback.We implement a version of Monte Carlo Tree Search (MCTS) to always pick the most promising sample to restart from (you can tweak the options in
RetryConfigto change the behaviour).For large number of parallel branches (ie, "shallow and wide trees"), you might benefit from switching scoring to
scoring=ThompsonSampling()(similar to how Bandit algorithms work).Open-source/local models can struggle with too long conversation, you might want to experiment with
in-place feedback(setRetryConfig(; feedback_inplace=true)).
Arguments
f_cond::Function: A function that accepts theaicallobject and returns a boolean value. Retry will be attempted if the condition is not met (f_cond -> false).aicall::AICallBlock: Theaicallobject to evaluate the condition on.feedback::Union{AbstractString, Function}: Feedback to provide if the condition is not met. If a function is provided, it must accept theaicallobject as the only argument and return a string.verbose::Integer=1: A verbosity level for logging the retry attempts and warnings. A higher value indicates more detailed logging.throw::Bool=false: If true, it will throw an error if the functionf_conddoes not returntrueaftermax_retriesretries.evaluate_all::Bool=false: If true, it will evaluate all the "successful" samples in theaicallobject. Otherwise, it will only evaluate the active sample.feedback_expensive::Bool=false: If false, it will provide feedback to all samples that fail the condition. Iffeedbackfunction is expensive to call (eg, another ai* function), set this totrueand feedback will be provided only to the sample we will retry from.max_retries::Union{Nothing, Int}=nothing: Maximum number of retries. If not provided, it will fall back to themax_retriesinaicall.config.retry_delay::Union{Nothing, Int}=nothing: Delay between retries in seconds. If not provided, it will fall back to theretry_delayinaicall.config.
Returns
- The
aicallobject with the updatedconversation, andsamples(saves the evaluations and their scores/feedback).
Example
You can use airetry! to catch API errors in run! and auto-retry the call. RetryConfig is how you influence all the subsequent retry behaviours - see ?RetryConfig for more details.
# API failure because of a non-existent model\nout = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\n model = "NOTEXIST")\nrun!(out) # fails\n\n# we ask to wait 2s between retries and retry 2 times (can be set in `config` in aicall as well)\nairetry!(isvalid, out; retry_delay = 2, max_retries = 2)If you provide arguments to the aicall, we try to honor them as much as possible in the following calls, eg, set low verbosity
out = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\nmodel = "NOTEXIST", verbose=false)\nrun!(out)\n# No info message, you just see `success = false` in the properties of the AICallLet's show a toy example to demonstrate the runtime checks / guardrails for the model output. We'll play a color guessing game (I'm thinking "yellow"):
# Notice that we ask for two samples (`n_samples=2`) at each attempt (to improve our chances). \n# Both guesses are scored at each time step, and the best one is chosen for the next step.\n# And with OpenAI, we can set `api_kwargs = (;n=2)` to get both samples simultaneously (cheaper and faster)!\nout = AIGenerate(\n "Guess what color I'm thinking. It could be: blue, red, black, white, yellow. Answer with 1 word only";\n verbose = false,\n config = RetryConfig(; n_samples = 2), api_kwargs = (; n = 2))\nrun!(out)\n\n\n## Check that the output is 1 word only, third argument is the feedback that will be provided if the condition fails\n## Notice: functions operate on `aicall` as the only argument. We can use utilities like `last_output` and `last_message` to access the last message and output in the conversation.\nairetry!(x -> length(split(last_output(x), r" |\\.")) == 1, out,\n "You must answer with 1 word only.")\n\n\n## Let's ensure that the output is in lowercase - simple and short\nairetry!(x -> all(islowercase, last_output(x)), out, "You must answer in lowercase.")\n# [ Info: Condition not met. Retrying...\n\n\n## Let's add final hint - it took us 2 retries\nairetry!(x -> startswith(last_output(x), "y"), out, "It starts with "y"")\n# [ Info: Condition not met. Retrying...\n# [ Info: Condition not met. Retrying...\n\n\n## We end up with the correct answer\nlast_output(out)\n# Output: "yellow"Let's explore how we got here. We save the various attempts in a "tree" (SampleNode object) You can access it in out.samples, which is the ROOT of the tree (top level). Currently "active" sample ID is out.active_sample_id -> that's the same as conversation field in your AICall.
# Root node:\nout.samples\n# Output: SampleNode(id: 46839, stats: 6/12, length: 2)\n\n# Active sample (our correct answer):\nout.active_sample_id \n# Output: 50086\n\n# Let's obtain the active sample node with this ID - use getindex notation or function find_node\nout.samples[out.active_sample_id]\n# Output: SampleNode(id: 50086, stats: 1/1, length: 7)\n\n# The SampleNode has two key fields: data and feedback. Data is where the conversation is stored:\nactive_sample = out.samples[out.active_sample_id]\nactive_sample.data == out.conversation # Output: true -> This is the winning guess!We also get a clear view of the tree structure of all samples with print_samples:
julia> print_samples(out.samples)\nSampleNode(id: 46839, stats: 6/12, score: 0.5, length: 2)\n├─ SampleNode(id: 12940, stats: 5/8, score: 1.41, length: 4)\n│ ├─ SampleNode(id: 34315, stats: 3/4, score: 1.77, length: 6)\n│ │ ├─ SampleNode(id: 20493, stats: 1/1, score: 2.67, length: 7)\n│ │ └─ SampleNode(id: 50086, stats: 1/1, score: 2.67, length: 7)\n│ └─ SampleNode(id: 2733, stats: 1/2, score: 1.94, length: 5)\n└─ SampleNode(id: 48343, stats: 1/4, score: 1.36, length: 4)\n ├─ SampleNode(id: 30088, stats: 0/1, score: 1.67, length: 5)\n └─ SampleNode(id: 44816, stats: 0/1, score: 1.67, length: 5)You can use the id to grab and inspect any of these nodes, eg,
out.samples[2733]\n# Output: SampleNode(id: 2733, stats: 1/2, length: 5)We can also iterate through all samples and extract whatever information we want with PostOrderDFS or PreOrderDFS (exported from AbstractTrees.jl)
for sample in PostOrderDFS(out.samples)\n # Data is the universal field for samples, we put `conversation` in there\n # Last item in data is the last message in coversation\n msg = sample.data[end]\n if msg isa PT.AIMessage # skip feedback\n # get only the message content, ie, the guess\n println("ID: $(sample.id), Answer: $(msg.content)")\n end\nend\n\n# ID: 20493, Answer: yellow\n# ID: 50086, Answer: yellow\n# ID: 2733, Answer: red\n# ID: 30088, Answer: blue\n# ID: 44816, Answer: blueNote: airetry! will attempt to fix the model max_retries times. If you set throw=true, it will throw an ErrorException if the condition is not met after max_retries retries.
Let's define a mini program to guess the number and use airetry! to guide the model to the correct answer:
"""\n llm_guesser()\n\nMini program to guess the number provided by the user (betwee 1-100).\n"""\nfunction llm_guesser(user_number::Int)\n @assert 1 <= user_number <= 100\n prompt = """\nI'm thinking a number between 1-100. Guess which one it is. \nYou must respond only with digits and nothing else. \nYour guess:"""\n ## 2 samples at a time, max 5 fixing rounds\n out = AIGenerate(prompt; config = RetryConfig(; n_samples = 2, max_retries = 5),\n api_kwargs = (; n = 2)) |> run!\n ## Check the proper output format - must parse to Int, use do-syntax\n ## We can provide feedback via a function!\n function feedback_f(aicall)\n "Output: $(last_output(aicall))\nFeedback: You must respond only with digits!!"\n end\n airetry!(out, feedback_f) do aicall\n !isnothing(tryparse(Int, last_output(aicall)))\n end\n ## Give a hint on bounds\n lower_bound = (user_number ÷ 10) * 10\n upper_bound = lower_bound + 10\n airetry!(\n out, "The number is between or equal to $lower_bound to $upper_bound.") do aicall\n guess = tryparse(Int, last_output(aicall))\n lower_bound <= guess <= upper_bound\n end\n ## You can make at most 3x guess now -- if there is max_retries in `config.max_retries` left\n max_retries = out.config.retries + 3\n function feedback_f2(aicall)\n guess = tryparse(Int, last_output(aicall))\n "Your guess of $(guess) is wrong, it's $(abs(guess-user_number)) numbers away."\n end\n airetry!(out, feedback_f2; max_retries) do aicall\n tryparse(Int, last_output(aicall)) == user_number\n end\n\n ## Evaluate the best guess\n @info "Results: Guess: $(last_output(out)) vs User: $user_number (Number of calls made: $(out.config.calls))"\n return out\nend\n\n# Let's play the game\nout = llm_guesser(33)\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Results: Guess: 33 vs User: 33 (Number of calls made: 10)Yay! We got it 😃
Now, we could explore different samples (eg, print_samples(out.samples)) or see what the model guessed at each step:
print_samples(out.samples)\n## SampleNode(id: 57694, stats: 6/14, score: 0.43, length: 2)\n## ├─ SampleNode(id: 35603, stats: 5/10, score: 1.23, length: 4)\n## │ ├─ SampleNode(id: 55394, stats: 1/4, score: 1.32, length: 6)\n## │ │ ├─ SampleNode(id: 20737, stats: 0/1, score: 1.67, length: 7)\n## │ │ └─ SampleNode(id: 52910, stats: 0/1, score: 1.67, length: 7)\n## │ └─ SampleNode(id: 43094, stats: 3/4, score: 1.82, length: 6)\n## │ ├─ SampleNode(id: 14966, stats: 1/1, score: 2.67, length: 7)\n## │ └─ SampleNode(id: 32991, stats: 1/1, score: 2.67, length: 7)\n## └─ SampleNode(id: 20506, stats: 1/4, score: 1.4, length: 4)\n## ├─ SampleNode(id: 37581, stats: 0/1, score: 1.67, length: 5)\n## └─ SampleNode(id: 46632, stats: 0/1, score: 1.67, length: 5)\n\n# Lastly, let's check all the guesses AI made across all samples. \n# Our winning guess was ID 32991 (`out.active_sample_id`)\n\nfor sample in PostOrderDFS(out.samples)\n [println("ID: $(sample.id), Guess: $(msg.content)")\n for msg in sample.data if msg isa PT.AIMessage]\nend\n## ID: 20737, Guess: 50\n## ID: 20737, Guess: 35\n## ID: 20737, Guess: 37\n## ID: 52910, Guess: 50\n## ID: 52910, Guess: 35\n## ID: 52910, Guess: 32\n## ID: 14966, Guess: 50\n## ID: 14966, Guess: 35\n## ID: 14966, Guess: 33\n## ID: 32991, Guess: 50\n## ID: 32991, Guess: 35\n## ID: 32991, Guess: 33\n## etc...Note that if there are multiple "branches" the model will see only the feedback of its own and its ancestors not the other "branches". If you wanted to provide ALL feedback, set RetryConfig(; n_samples=1) to remove any "branching". It fixing will be done sequentially in one conversation and the model will see all feedback (less powerful if the model falls into a bad state). Alternatively, you can tweak the feedback function.
See Also
References: airetry is inspired by the Language Agent Tree Search paper and by DSPy Assertions paper.
Pretty prints the samples tree starting from node. Usually, node is the root of the tree. Example: print_samples(aicall.samples).
AICode(code::AbstractString; auto_eval::Bool=true, safe_eval::Bool=false, \nskip_unsafe::Bool=false, capture_stdout::Bool=true, verbose::Bool=false,\nprefix::AbstractString="", suffix::AbstractString="", remove_tests::Bool=false, execution_timeout::Int = 60)\n\nAICode(msg::AIMessage; auto_eval::Bool=true, safe_eval::Bool=false, \nskip_unsafe::Bool=false, skip_invalid::Bool=false, capture_stdout::Bool=true,\nverbose::Bool=false, prefix::AbstractString="", suffix::AbstractString="", remove_tests::Bool=false, execution_timeout::Int = 60)A mutable structure representing a code block (received from the AI model) with automatic parsing, execution, and output/error capturing capabilities.
Upon instantiation with a string, the AICode object automatically runs a code parser and executor (via PromptingTools.eval!()), capturing any standard output (stdout) or errors. This structure is useful for programmatically handling and evaluating Julia code snippets.
See also: PromptingTools.extract_code_blocks, PromptingTools.eval!
Workflow
Until
cb::AICodehas been evaluated,cb.successis set tonothing(and so are all other fields).The text in
cb.codeis parsed (saved tocb.expression).The parsed expression is evaluated.
Outputs of the evaluated expression are captured in
cb.output.Any
stdoutoutputs (e.g., fromprintln) are captured incb.stdout.If an error occurs during evaluation, it is saved in
cb.error.After successful evaluation without errors,
cb.successis set totrue. Otherwise, it is set tofalseand you can inspect thecb.errorto understand why.
Properties
code::AbstractString: The raw string of the code to be parsed and executed.expression: The parsed Julia expression (set after parsingcode).stdout: Captured standard output from the execution of the code.output: The result of evaluating the code block.success::Union{Nothing, Bool}: Indicates whether the code block executed successfully (true), unsuccessfully (false), or has yet to be evaluated (nothing).error::Union{Nothing, Exception}: Any exception raised during the execution of the code block.
Keyword Arguments
auto_eval::Bool: If set totrue, the code block is automatically parsed and evaluated upon instantiation. Defaults totrue.safe_eval::Bool: If set totrue, the code block checks for package operations (e.g., installing new packages) and missing imports, and then evaluates the code inside a bespoke scratch module. This is to ensure that the evaluation does not alter any user-defined variables or the global state. Defaults tofalse.skip_unsafe::Bool: If set totrue, we skip any lines in the code block that are deemed unsafe (eg,Pkgoperations). Defaults tofalse.skip_invalid::Bool: If set totrue, we skip code blocks that do not even parse. Defaults tofalse.verbose::Bool: If set totrue, we print out any lines that are skipped due to being unsafe. Defaults tofalse.capture_stdout::Bool: If set totrue, we capture any stdout outputs (eg, test failures) incb.stdout. Defaults totrue.prefix::AbstractString: A string to be prepended to the code block before parsing and evaluation. Useful to add some additional code definition or necessary imports. Defaults to an empty string.suffix::AbstractString: A string to be appended to the code block before parsing and evaluation. Useful to check that tests pass or that an example executes. Defaults to an empty string.remove_tests::Bool: If set totrue, we remove any@testor@testsetmacros from the code block before parsing and evaluation. Defaults tofalse.execution_timeout::Int: The maximum time (in seconds) allowed for the code block to execute. Defaults to 60 seconds.
Methods
Base.isvalid(cb::AICode): Check if the code block has executed successfully. Returnstrueifcb.success == true.
Examples
code = AICode("println("Hello, World!")") # Auto-parses and evaluates the code, capturing output and errors.\nisvalid(code) # Output: true\ncode.stdout # Output: "Hello, World!\n"We try to evaluate "safely" by default (eg, inside a custom module, to avoid changing user variables). You can avoid that with save_eval=false:
code = AICode("new_variable = 1"; safe_eval=false)\nisvalid(code) # Output: true\nnew_variable # Output: 1You can also call AICode directly on an AIMessage, which will extract the Julia code blocks, concatenate them and evaluate them:
msg = aigenerate("In Julia, how do you create a vector of 10 random numbers?")\ncode = AICode(msg)\n# Output: AICode(Success: True, Parsed: True, Evaluated: True, Error Caught: N/A, StdOut: True, Code: 2 Lines)\n\n# show the code\ncode.code |> println\n# Output: \n# numbers = rand(10)\n# numbers = rand(1:100, 10)\n\n# or copy it to the clipboard\ncode.code |> clipboard\n\n# or execute it in the current module (=Main)\neval(code.expression)aicodefixer_feedback(cb::AICode; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(conversation::AbstractVector{<:PT.AbstractMessage}; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(msg::PT.AIMessage; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(aicall::AICall; max_length::Int = 512) -> NamedTuple(; feedback::String)Generate feedback for an AI code fixing session based on the AICode block /or conversation history (that will be used to extract and evaluate a code block). Function is designed to be extensible for different types of feedback and code evaluation outcomes.
The highlevel wrapper accepts a conversation and returns new kwargs for the AICall.
Individual feedback functions are dispatched on different subtypes of AbstractCodeOutcome and can be extended/overwritten to provide more detailed feedback.
See also: AIGenerate, AICodeFixer
Arguments
cb::AICode: AICode block to evaluate and provide feedback on.max_length::Int=512: An optional argument that specifies the maximum length of the feedback message.
Returns
NamedTuple: A feedback message as a kwarg in NamedTuple based on the analysis of the code provided in the conversation.
Example
cb = AICode(msg; skip_unsafe = true, capture_stdout = true)\nnew_kwargs = aicodefixer_feedback(cb)\n\nnew_kwargs = aicodefixer_feedback(msg)\nnew_kwargs = aicodefixer_feedback(conversation)Notes
This function is part of the AI code fixing system, intended to interact with code in AIMessage and provide feedback on improving it.
The highlevel wrapper accepts a conversation and returns new kwargs for the AICall.
It dispatches for the code feedback based on the subtypes of AbstractCodeOutcome below:
CodeEmpty: No code found in the message.CodeFailedParse: Code parsing error.CodeFailedEval: Runtime evaluation error.CodeFailedTimeout: Code execution timed out.CodeSuccess: Successful code execution.
You can override the individual methods to customize the feedback.
error_feedback(e::Any; max_length::Int = 512)Set of specialized methods to provide feedback on different types of errors (e).
', 42) + ])); +} +const agent_tools_intro = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + agent_tools_intro as default +}; diff --git a/previews/PR252/assets/extra_tools_agent_tools_intro.md.CGplc6KB.lean.js b/previews/PR252/assets/extra_tools_agent_tools_intro.md.CGplc6KB.lean.js new file mode 100644 index 00000000..817d10ec --- /dev/null +++ b/previews/PR252/assets/extra_tools_agent_tools_intro.md.CGplc6KB.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Agent Tools Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"extra_tools/agent_tools_intro.md","filePath":"extra_tools/agent_tools_intro.md","lastUpdated":null}'); +const _sfc_main = { name: "extra_tools/agent_tools_intro.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Agent Tools Introduction
AgentTools is an experimental module that provides a set of utilities for building advanced agentic workflows, code-generating and self-fixing agents.
Import the module as follows:
using PromptingTools.Experimental.AgentTools\n# to access unexported functionality\nconst AT = PromptingTools.Experimental.AgentToolsHighlights
The main functions to be aware of are:
AIGenerate- Lazy counterpart ofaigenerate(). Allai*functions have a correspondingAI*::AICallstruct that allows for deferred execution (triggered byrun!method).last_output,last_message- Simple utilities to access the last output and message of the AI calls likeAIGenerate.airetry!- A utility to automatically retry the AI call with the same inputs if the AI model fails to generate a valid output. It allows retrying many times and providing feedback to the AI model about the failure to increase its robustness.AIGenerateand other AI calls have a fieldconfig::RetryConfigwhere you can globally adjust the retrying behavior.print_samples-airetry!implements a Monte Carlo Tree Search under the hood when trying to find the best way to fix the AI model's failure.print_samplesis a utility to print the "samples" generated by the MCTS to better understand the attempts made by the AI model to fix the failure.AICodeextensions likeaicodefixer_feedbackanderror_feedback-AICodeis a wrapper that extracts any Julia code provided in theAIMessage(response from the AI model) and executes it (including catch any errors).aicodefixer_feedbackanderror_feedbackare utilities that automatically review an outcome ofAICodeevaluation and generate the corresponding feedback for the AI model.
The main contribution of this module is providing the "lazy" counterparts to the ai... functions, which allow us to build a workflow, which can be re-executed many times with the same inputs.
For example, AIGenerate() will create a lazy instance of aigenerate, which is an instance of AICall with aigenerate as its ai-calling function. It uses exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details). The notion of "lazy" refers to the fact that it does NOT generate any output when instantiated (only when run! is called).
Or said differently, the AICall struct and all its flavors (AIGenerate, ...) are designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied. This allows us to remember user inputs and trigger the LLM call repeatedly if needed, which enables automatic fixing (see ?airetry!).
Examples
Automatic Fixing of AI Calls
We need to switch from aigenerate to AIGenerate to get the lazy version of the function.
output = AIGenerate("Say hi!"; model="gpt4t") |> run!How is it useful? We can use the same "inputs" for repeated calls, eg, when we want to validate or regenerate some outputs. We have a function airetry! to help us with that.
The signature of airetry is airetry(condition_function, aicall::AICall, feedback_function).
It evaluates the condition condition_function on the aicall object (eg, we evaluate f_cond(aicall) -> Bool). If it fails, we call feedback_function on the aicall object to provide feedback for the AI model (eg, f_feedback(aicall) -> String) and repeat the process until it passes or until max_retries value is exceeded.
We can catch API failures (no feedback needed, so none is provided)
# API failure because of a non-existent model\n# RetryConfig allows us to change the "retry" behaviour of any lazy call\noutput = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\n model = "NOTEXIST")\nrun!(output) # fails\n\n# we ask to wait 2s between retries and retry 2 times (can be set in `config` in aicall as well)\nairetry!(isvalid, output; retry_delay = 2, max_retries = 2)Or we can use it for output validation (eg, its format, its content, etc.) and feedback generation.
Let's play a color guessing game (I'm thinking "yellow"). We'll implement two formatting checks with airetry!:
# Notice that we ask for two samples (`n_samples=2`) at each attempt (to improve our chances). \n# Both guesses are scored at each time step, and the best one is chosen for the next step.\n# And with OpenAI, we can set `api_kwargs = (;n=2)` to get both samples simultaneously (cheaper and faster)!\nout = AIGenerate(\n "Guess what color I'm thinking. It could be: blue, red, black, white, yellow. Answer with 1 word only";\n verbose = false,\n config = RetryConfig(; n_samples = 2), api_kwargs = (; n = 2))\nrun!(out)\n\n## Check that the output is 1 word only, third argument is the feedback that will be provided if the condition fails\n## Notice: functions operate on `aicall` as the only argument. We can use utilities like `last_output` and `last_message` to access the last message and output in the conversation.\nairetry!(x -> length(split(last_output(x), r" |\\\\.")) == 1, out,\n "You must answer with 1 word only.")\n\n# Note: you could also use the do-syntax, eg, \nairetry!(out, "You must answer with 1 word only.") do aicall\n length(split(last_output(aicall), r" |\\\\.")) == 1\nendYou can even add the guessing itself as an airetry! condition of last_output(out) == "yellow" and provide feedback if the guess is wrong.
References
AIGenerate(args...; kwargs...)Creates a lazy instance of aigenerate. It is an instance of AICall with aigenerate as the function.
Use exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details).
AICall(func::F, args...; kwargs...) where {F<:Function}\n\nAIGenerate(args...; kwargs...)\nAIEmbed(args...; kwargs...)\nAIExtract(args...; kwargs...)A lazy call wrapper for AI functions in the PromptingTools module, such as aigenerate.
The AICall struct is designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied. This approach allows for more flexible and efficient handling of AI function calls, especially in interactive environments.
Seel also: run!, AICodeFixer
Fields
func::F: The AI function to be called lazily. This should be a function likeaigenerateor otherai*functions.schema::Union{Nothing, PT.AbstractPromptSchema}: Optional schema to structure the prompt for the AI function.conversation::Vector{PT.AbstractMessage}: A vector of messages that forms the conversation context for the AI call.kwargs::NamedTuple: Keyword arguments to be passed to the AI function.success::Union{Nothing, Bool}: Indicates whether the last call was successful (true) or not (false).Nothingif the call hasn't been made yet.error::Union{Nothing, Exception}: Stores any exception that occurred during the last call.Nothingif no error occurred or if the call hasn't been made yet.
Example
Initiate an AICall like any ai* function, eg, AIGenerate:
aicall = AICall(aigenerate)\n\n# With arguments and kwargs like ai* functions\n# from `aigenerate(schema, conversation; model="abc", api_kwargs=(; temperature=0.1))`\n# to\naicall = AICall(aigenerate, schema, conversation; model="abc", api_kwargs=(; temperature=0.1)\n\n# Or with a template\naicall = AIGenerate(:JuliaExpertAsk; ask="xyz", model="abc", api_kwargs=(; temperature=0.1))Trigger the AICall with run! (it returns the update AICall struct back):
aicall |> run!\n````\n\nYou can also use `AICall` as a functor to trigger the AI call with a `UserMessage` or simply the text to send:julia aicall(UserMessage("Hello, world!")) # Triggers the lazy call result = run!(aicall) # Explicitly runs the AI call ``` This can be used to "reply" to previous message / continue the stored conversation
Notes
The
AICallstruct is a key component in building flexible and efficient Agentic pipelinesThe lazy evaluation model allows for setting up the call parameters in advance and deferring the actual execution until it is explicitly triggered.
This struct is particularly useful in scenarios where the timing of AI function execution needs to be deferred or where multiple potential calls need to be prepared and selectively executed.
Extracts the last output (generated text answer) from the RAGResult.
Helpful accessor for AICall blocks. Returns the last output in the conversation (eg, the string/data in the last message).
Helpful accessor for the last generated output (msg.content) in conversation. Returns the last output in the conversation (eg, the string/data in the last message).
last_output(mem::ConversationMemory)Get the last AI message in the conversation.
PT.last_message(result::RAGResult)Extract the last message from the RAGResult. It looks for final_answer first, then answer fields in the conversations dictionary. Returns nothing if not found.
Helpful accessor for AICall blocks. Returns the last message in the conversation.
Helpful accessor for the last message in conversation. Returns the last message in the conversation.
last_message(mem::ConversationMemory)Get the last message in the conversation.
airetry!(\n f_cond::Function, aicall::AICallBlock, feedback::Union{AbstractString, Function} = "";\n verbose::Bool = true, throw::Bool = false, evaluate_all::Bool = true, feedback_expensive::Bool = false,\n max_retries::Union{Nothing, Int} = nothing, retry_delay::Union{Nothing, Int} = nothing)Evaluates the condition f_cond on the aicall object. If the condition is not met, it will return the best sample to retry from and provide feedback (string or function) to aicall. That's why it's mutating. It will retry maximum max_retries times, with throw=true, an error will be thrown if the condition is not met after max_retries retries.
Note: aicall must be run first via run!(aicall) before calling airetry!.
Function signatures
f_cond(aicall::AICallBlock) -> Bool, ie, it must accept the aicall object and return a boolean value.feedbackcan be a string orfeedback(aicall::AICallBlock) -> String, ie, it must accept the aicall object and return a string.
You can leverage the last_message, last_output, and AICode functions to access the last message, last output and execute code blocks in the conversation, respectively. See examples below.
Good Use Cases
Retry with API failures/drops (add
retry_delay=2to wait 2s between retries)Check the output format / type / length / etc
Check the output with
aiclassifycall (LLM Judge) to catch unsafe/NSFW/out-of-scope contentProvide hints to the model to guide it to the correct answer
Gotchas
If controlling keyword arguments are set to nothing, they will fall back to the default values in
aicall.config. You can override them by passing the keyword arguments explicitly.If there multiple
airetry!checks, they are evaluted sequentially. As long asthrow==false, they will be all evaluated even if they failed previous checks.Only samples which passed previous evaluations are evaluated (
sample.successistrue). If there are no successful samples, the function will evaluate only the active sample (aicall.active_sample_id) and nothing else.Feedback from all "ancestor" evaluations is added upon retry, not feedback from the "sibblings" or other branches. To have only ONE long BRANCH (no sibblings), make sure to keep
RetryConfig(; n_samples=1). That way the model will always see ALL previous feedback.We implement a version of Monte Carlo Tree Search (MCTS) to always pick the most promising sample to restart from (you can tweak the options in
RetryConfigto change the behaviour).For large number of parallel branches (ie, "shallow and wide trees"), you might benefit from switching scoring to
scoring=ThompsonSampling()(similar to how Bandit algorithms work).Open-source/local models can struggle with too long conversation, you might want to experiment with
in-place feedback(setRetryConfig(; feedback_inplace=true)).
Arguments
f_cond::Function: A function that accepts theaicallobject and returns a boolean value. Retry will be attempted if the condition is not met (f_cond -> false).aicall::AICallBlock: Theaicallobject to evaluate the condition on.feedback::Union{AbstractString, Function}: Feedback to provide if the condition is not met. If a function is provided, it must accept theaicallobject as the only argument and return a string.verbose::Integer=1: A verbosity level for logging the retry attempts and warnings. A higher value indicates more detailed logging.throw::Bool=false: If true, it will throw an error if the functionf_conddoes not returntrueaftermax_retriesretries.evaluate_all::Bool=false: If true, it will evaluate all the "successful" samples in theaicallobject. Otherwise, it will only evaluate the active sample.feedback_expensive::Bool=false: If false, it will provide feedback to all samples that fail the condition. Iffeedbackfunction is expensive to call (eg, another ai* function), set this totrueand feedback will be provided only to the sample we will retry from.max_retries::Union{Nothing, Int}=nothing: Maximum number of retries. If not provided, it will fall back to themax_retriesinaicall.config.retry_delay::Union{Nothing, Int}=nothing: Delay between retries in seconds. If not provided, it will fall back to theretry_delayinaicall.config.
Returns
- The
aicallobject with the updatedconversation, andsamples(saves the evaluations and their scores/feedback).
Example
You can use airetry! to catch API errors in run! and auto-retry the call. RetryConfig is how you influence all the subsequent retry behaviours - see ?RetryConfig for more details.
# API failure because of a non-existent model\nout = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\n model = "NOTEXIST")\nrun!(out) # fails\n\n# we ask to wait 2s between retries and retry 2 times (can be set in `config` in aicall as well)\nairetry!(isvalid, out; retry_delay = 2, max_retries = 2)If you provide arguments to the aicall, we try to honor them as much as possible in the following calls, eg, set low verbosity
out = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\nmodel = "NOTEXIST", verbose=false)\nrun!(out)\n# No info message, you just see `success = false` in the properties of the AICallLet's show a toy example to demonstrate the runtime checks / guardrails for the model output. We'll play a color guessing game (I'm thinking "yellow"):
# Notice that we ask for two samples (`n_samples=2`) at each attempt (to improve our chances). \n# Both guesses are scored at each time step, and the best one is chosen for the next step.\n# And with OpenAI, we can set `api_kwargs = (;n=2)` to get both samples simultaneously (cheaper and faster)!\nout = AIGenerate(\n "Guess what color I'm thinking. It could be: blue, red, black, white, yellow. Answer with 1 word only";\n verbose = false,\n config = RetryConfig(; n_samples = 2), api_kwargs = (; n = 2))\nrun!(out)\n\n\n## Check that the output is 1 word only, third argument is the feedback that will be provided if the condition fails\n## Notice: functions operate on `aicall` as the only argument. We can use utilities like `last_output` and `last_message` to access the last message and output in the conversation.\nairetry!(x -> length(split(last_output(x), r" |\\.")) == 1, out,\n "You must answer with 1 word only.")\n\n\n## Let's ensure that the output is in lowercase - simple and short\nairetry!(x -> all(islowercase, last_output(x)), out, "You must answer in lowercase.")\n# [ Info: Condition not met. Retrying...\n\n\n## Let's add final hint - it took us 2 retries\nairetry!(x -> startswith(last_output(x), "y"), out, "It starts with "y"")\n# [ Info: Condition not met. Retrying...\n# [ Info: Condition not met. Retrying...\n\n\n## We end up with the correct answer\nlast_output(out)\n# Output: "yellow"Let's explore how we got here. We save the various attempts in a "tree" (SampleNode object) You can access it in out.samples, which is the ROOT of the tree (top level). Currently "active" sample ID is out.active_sample_id -> that's the same as conversation field in your AICall.
# Root node:\nout.samples\n# Output: SampleNode(id: 46839, stats: 6/12, length: 2)\n\n# Active sample (our correct answer):\nout.active_sample_id \n# Output: 50086\n\n# Let's obtain the active sample node with this ID - use getindex notation or function find_node\nout.samples[out.active_sample_id]\n# Output: SampleNode(id: 50086, stats: 1/1, length: 7)\n\n# The SampleNode has two key fields: data and feedback. Data is where the conversation is stored:\nactive_sample = out.samples[out.active_sample_id]\nactive_sample.data == out.conversation # Output: true -> This is the winning guess!We also get a clear view of the tree structure of all samples with print_samples:
julia> print_samples(out.samples)\nSampleNode(id: 46839, stats: 6/12, score: 0.5, length: 2)\n├─ SampleNode(id: 12940, stats: 5/8, score: 1.41, length: 4)\n│ ├─ SampleNode(id: 34315, stats: 3/4, score: 1.77, length: 6)\n│ │ ├─ SampleNode(id: 20493, stats: 1/1, score: 2.67, length: 7)\n│ │ └─ SampleNode(id: 50086, stats: 1/1, score: 2.67, length: 7)\n│ └─ SampleNode(id: 2733, stats: 1/2, score: 1.94, length: 5)\n└─ SampleNode(id: 48343, stats: 1/4, score: 1.36, length: 4)\n ├─ SampleNode(id: 30088, stats: 0/1, score: 1.67, length: 5)\n └─ SampleNode(id: 44816, stats: 0/1, score: 1.67, length: 5)You can use the id to grab and inspect any of these nodes, eg,
out.samples[2733]\n# Output: SampleNode(id: 2733, stats: 1/2, length: 5)We can also iterate through all samples and extract whatever information we want with PostOrderDFS or PreOrderDFS (exported from AbstractTrees.jl)
for sample in PostOrderDFS(out.samples)\n # Data is the universal field for samples, we put `conversation` in there\n # Last item in data is the last message in coversation\n msg = sample.data[end]\n if msg isa PT.AIMessage # skip feedback\n # get only the message content, ie, the guess\n println("ID: $(sample.id), Answer: $(msg.content)")\n end\nend\n\n# ID: 20493, Answer: yellow\n# ID: 50086, Answer: yellow\n# ID: 2733, Answer: red\n# ID: 30088, Answer: blue\n# ID: 44816, Answer: blueNote: airetry! will attempt to fix the model max_retries times. If you set throw=true, it will throw an ErrorException if the condition is not met after max_retries retries.
Let's define a mini program to guess the number and use airetry! to guide the model to the correct answer:
"""\n llm_guesser()\n\nMini program to guess the number provided by the user (betwee 1-100).\n"""\nfunction llm_guesser(user_number::Int)\n @assert 1 <= user_number <= 100\n prompt = """\nI'm thinking a number between 1-100. Guess which one it is. \nYou must respond only with digits and nothing else. \nYour guess:"""\n ## 2 samples at a time, max 5 fixing rounds\n out = AIGenerate(prompt; config = RetryConfig(; n_samples = 2, max_retries = 5),\n api_kwargs = (; n = 2)) |> run!\n ## Check the proper output format - must parse to Int, use do-syntax\n ## We can provide feedback via a function!\n function feedback_f(aicall)\n "Output: $(last_output(aicall))\nFeedback: You must respond only with digits!!"\n end\n airetry!(out, feedback_f) do aicall\n !isnothing(tryparse(Int, last_output(aicall)))\n end\n ## Give a hint on bounds\n lower_bound = (user_number ÷ 10) * 10\n upper_bound = lower_bound + 10\n airetry!(\n out, "The number is between or equal to $lower_bound to $upper_bound.") do aicall\n guess = tryparse(Int, last_output(aicall))\n lower_bound <= guess <= upper_bound\n end\n ## You can make at most 3x guess now -- if there is max_retries in `config.max_retries` left\n max_retries = out.config.retries + 3\n function feedback_f2(aicall)\n guess = tryparse(Int, last_output(aicall))\n "Your guess of $(guess) is wrong, it's $(abs(guess-user_number)) numbers away."\n end\n airetry!(out, feedback_f2; max_retries) do aicall\n tryparse(Int, last_output(aicall)) == user_number\n end\n\n ## Evaluate the best guess\n @info "Results: Guess: $(last_output(out)) vs User: $user_number (Number of calls made: $(out.config.calls))"\n return out\nend\n\n# Let's play the game\nout = llm_guesser(33)\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Results: Guess: 33 vs User: 33 (Number of calls made: 10)Yay! We got it 😃
Now, we could explore different samples (eg, print_samples(out.samples)) or see what the model guessed at each step:
print_samples(out.samples)\n## SampleNode(id: 57694, stats: 6/14, score: 0.43, length: 2)\n## ├─ SampleNode(id: 35603, stats: 5/10, score: 1.23, length: 4)\n## │ ├─ SampleNode(id: 55394, stats: 1/4, score: 1.32, length: 6)\n## │ │ ├─ SampleNode(id: 20737, stats: 0/1, score: 1.67, length: 7)\n## │ │ └─ SampleNode(id: 52910, stats: 0/1, score: 1.67, length: 7)\n## │ └─ SampleNode(id: 43094, stats: 3/4, score: 1.82, length: 6)\n## │ ├─ SampleNode(id: 14966, stats: 1/1, score: 2.67, length: 7)\n## │ └─ SampleNode(id: 32991, stats: 1/1, score: 2.67, length: 7)\n## └─ SampleNode(id: 20506, stats: 1/4, score: 1.4, length: 4)\n## ├─ SampleNode(id: 37581, stats: 0/1, score: 1.67, length: 5)\n## └─ SampleNode(id: 46632, stats: 0/1, score: 1.67, length: 5)\n\n# Lastly, let's check all the guesses AI made across all samples. \n# Our winning guess was ID 32991 (`out.active_sample_id`)\n\nfor sample in PostOrderDFS(out.samples)\n [println("ID: $(sample.id), Guess: $(msg.content)")\n for msg in sample.data if msg isa PT.AIMessage]\nend\n## ID: 20737, Guess: 50\n## ID: 20737, Guess: 35\n## ID: 20737, Guess: 37\n## ID: 52910, Guess: 50\n## ID: 52910, Guess: 35\n## ID: 52910, Guess: 32\n## ID: 14966, Guess: 50\n## ID: 14966, Guess: 35\n## ID: 14966, Guess: 33\n## ID: 32991, Guess: 50\n## ID: 32991, Guess: 35\n## ID: 32991, Guess: 33\n## etc...Note that if there are multiple "branches" the model will see only the feedback of its own and its ancestors not the other "branches". If you wanted to provide ALL feedback, set RetryConfig(; n_samples=1) to remove any "branching". It fixing will be done sequentially in one conversation and the model will see all feedback (less powerful if the model falls into a bad state). Alternatively, you can tweak the feedback function.
See Also
References: airetry is inspired by the Language Agent Tree Search paper and by DSPy Assertions paper.
Pretty prints the samples tree starting from node. Usually, node is the root of the tree. Example: print_samples(aicall.samples).
AICode(code::AbstractString; auto_eval::Bool=true, safe_eval::Bool=false, \nskip_unsafe::Bool=false, capture_stdout::Bool=true, verbose::Bool=false,\nprefix::AbstractString="", suffix::AbstractString="", remove_tests::Bool=false, execution_timeout::Int = 60)\n\nAICode(msg::AIMessage; auto_eval::Bool=true, safe_eval::Bool=false, \nskip_unsafe::Bool=false, skip_invalid::Bool=false, capture_stdout::Bool=true,\nverbose::Bool=false, prefix::AbstractString="", suffix::AbstractString="", remove_tests::Bool=false, execution_timeout::Int = 60)A mutable structure representing a code block (received from the AI model) with automatic parsing, execution, and output/error capturing capabilities.
Upon instantiation with a string, the AICode object automatically runs a code parser and executor (via PromptingTools.eval!()), capturing any standard output (stdout) or errors. This structure is useful for programmatically handling and evaluating Julia code snippets.
See also: PromptingTools.extract_code_blocks, PromptingTools.eval!
Workflow
Until
cb::AICodehas been evaluated,cb.successis set tonothing(and so are all other fields).The text in
cb.codeis parsed (saved tocb.expression).The parsed expression is evaluated.
Outputs of the evaluated expression are captured in
cb.output.Any
stdoutoutputs (e.g., fromprintln) are captured incb.stdout.If an error occurs during evaluation, it is saved in
cb.error.After successful evaluation without errors,
cb.successis set totrue. Otherwise, it is set tofalseand you can inspect thecb.errorto understand why.
Properties
code::AbstractString: The raw string of the code to be parsed and executed.expression: The parsed Julia expression (set after parsingcode).stdout: Captured standard output from the execution of the code.output: The result of evaluating the code block.success::Union{Nothing, Bool}: Indicates whether the code block executed successfully (true), unsuccessfully (false), or has yet to be evaluated (nothing).error::Union{Nothing, Exception}: Any exception raised during the execution of the code block.
Keyword Arguments
auto_eval::Bool: If set totrue, the code block is automatically parsed and evaluated upon instantiation. Defaults totrue.safe_eval::Bool: If set totrue, the code block checks for package operations (e.g., installing new packages) and missing imports, and then evaluates the code inside a bespoke scratch module. This is to ensure that the evaluation does not alter any user-defined variables or the global state. Defaults tofalse.skip_unsafe::Bool: If set totrue, we skip any lines in the code block that are deemed unsafe (eg,Pkgoperations). Defaults tofalse.skip_invalid::Bool: If set totrue, we skip code blocks that do not even parse. Defaults tofalse.verbose::Bool: If set totrue, we print out any lines that are skipped due to being unsafe. Defaults tofalse.capture_stdout::Bool: If set totrue, we capture any stdout outputs (eg, test failures) incb.stdout. Defaults totrue.prefix::AbstractString: A string to be prepended to the code block before parsing and evaluation. Useful to add some additional code definition or necessary imports. Defaults to an empty string.suffix::AbstractString: A string to be appended to the code block before parsing and evaluation. Useful to check that tests pass or that an example executes. Defaults to an empty string.remove_tests::Bool: If set totrue, we remove any@testor@testsetmacros from the code block before parsing and evaluation. Defaults tofalse.execution_timeout::Int: The maximum time (in seconds) allowed for the code block to execute. Defaults to 60 seconds.
Methods
Base.isvalid(cb::AICode): Check if the code block has executed successfully. Returnstrueifcb.success == true.
Examples
code = AICode("println("Hello, World!")") # Auto-parses and evaluates the code, capturing output and errors.\nisvalid(code) # Output: true\ncode.stdout # Output: "Hello, World!\n"We try to evaluate "safely" by default (eg, inside a custom module, to avoid changing user variables). You can avoid that with save_eval=false:
code = AICode("new_variable = 1"; safe_eval=false)\nisvalid(code) # Output: true\nnew_variable # Output: 1You can also call AICode directly on an AIMessage, which will extract the Julia code blocks, concatenate them and evaluate them:
msg = aigenerate("In Julia, how do you create a vector of 10 random numbers?")\ncode = AICode(msg)\n# Output: AICode(Success: True, Parsed: True, Evaluated: True, Error Caught: N/A, StdOut: True, Code: 2 Lines)\n\n# show the code\ncode.code |> println\n# Output: \n# numbers = rand(10)\n# numbers = rand(1:100, 10)\n\n# or copy it to the clipboard\ncode.code |> clipboard\n\n# or execute it in the current module (=Main)\neval(code.expression)aicodefixer_feedback(cb::AICode; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(conversation::AbstractVector{<:PT.AbstractMessage}; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(msg::PT.AIMessage; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(aicall::AICall; max_length::Int = 512) -> NamedTuple(; feedback::String)Generate feedback for an AI code fixing session based on the AICode block /or conversation history (that will be used to extract and evaluate a code block). Function is designed to be extensible for different types of feedback and code evaluation outcomes.
The highlevel wrapper accepts a conversation and returns new kwargs for the AICall.
Individual feedback functions are dispatched on different subtypes of AbstractCodeOutcome and can be extended/overwritten to provide more detailed feedback.
See also: AIGenerate, AICodeFixer
Arguments
cb::AICode: AICode block to evaluate and provide feedback on.max_length::Int=512: An optional argument that specifies the maximum length of the feedback message.
Returns
NamedTuple: A feedback message as a kwarg in NamedTuple based on the analysis of the code provided in the conversation.
Example
cb = AICode(msg; skip_unsafe = true, capture_stdout = true)\nnew_kwargs = aicodefixer_feedback(cb)\n\nnew_kwargs = aicodefixer_feedback(msg)\nnew_kwargs = aicodefixer_feedback(conversation)Notes
This function is part of the AI code fixing system, intended to interact with code in AIMessage and provide feedback on improving it.
The highlevel wrapper accepts a conversation and returns new kwargs for the AICall.
It dispatches for the code feedback based on the subtypes of AbstractCodeOutcome below:
CodeEmpty: No code found in the message.CodeFailedParse: Code parsing error.CodeFailedEval: Runtime evaluation error.CodeFailedTimeout: Code execution timed out.CodeSuccess: Successful code execution.
You can override the individual methods to customize the feedback.
error_feedback(e::Any; max_length::Int = 512)Set of specialized methods to provide feedback on different types of errors (e).
', 42) + ])); +} +const agent_tools_intro = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + agent_tools_intro as default +}; diff --git a/previews/PR252/assets/extra_tools_api_tools_intro.md.DnbQnD35.js b/previews/PR252/assets/extra_tools_api_tools_intro.md.DnbQnD35.js new file mode 100644 index 00000000..d477345a --- /dev/null +++ b/previews/PR252/assets/extra_tools_api_tools_intro.md.DnbQnD35.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"APITools Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"extra_tools/api_tools_intro.md","filePath":"extra_tools/api_tools_intro.md","lastUpdated":null}'); +const _sfc_main = { name: "extra_tools/api_tools_intro.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
APITools Introduction
APITools is an experimental module wrapping helpful APIs for working with and enhancing GenerativeAI models.
Import the module as follows:
using PromptingTools.Experimental.APIToolsHighlights
Currently, there is only one function in this module create_websearch that leverages Tavily.com search and answer engine to provide additional context.
You need to sign up for an API key at Tavily.com and set it as an environment variable TAVILY_API_KEY to use this function.
References
create_websearch(query::AbstractString;\n api_key::AbstractString,\n search_depth::AbstractString = "basic")Arguments
query::AbstractString: The query to search for.api_key::AbstractString: The API key to use for the search. Get an API key from Tavily.search_depth::AbstractString: The depth of the search. Can be either "basic" or "advanced". Default is "basic". Advanced search calls equal to 2 requests.include_answer::Bool: Whether to include the answer in the search results. Default isfalse.include_raw_content::Bool: Whether to include the raw content in the search results. Default isfalse.max_results::Integer: The maximum number of results to return. Default is 5.include_images::Bool: Whether to include images in the search results. Default isfalse.include_domains::AbstractVector{<:AbstractString}: A list of domains to include in the search results. Default is an empty list.exclude_domains::AbstractVector{<:AbstractString}: A list of domains to exclude from the search results. Default is an empty list.
Example
r = create_websearch("Who is King Charles?")Even better, you can get not just the results but also the answer:
r = create_websearch("Who is King Charles?"; include_answer = true)See Rest API documentation for more information.
', 10) + ])); +} +const api_tools_intro = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + api_tools_intro as default +}; diff --git a/previews/PR252/assets/extra_tools_api_tools_intro.md.DnbQnD35.lean.js b/previews/PR252/assets/extra_tools_api_tools_intro.md.DnbQnD35.lean.js new file mode 100644 index 00000000..d477345a --- /dev/null +++ b/previews/PR252/assets/extra_tools_api_tools_intro.md.DnbQnD35.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"APITools Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"extra_tools/api_tools_intro.md","filePath":"extra_tools/api_tools_intro.md","lastUpdated":null}'); +const _sfc_main = { name: "extra_tools/api_tools_intro.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
APITools Introduction
APITools is an experimental module wrapping helpful APIs for working with and enhancing GenerativeAI models.
Import the module as follows:
using PromptingTools.Experimental.APIToolsHighlights
Currently, there is only one function in this module create_websearch that leverages Tavily.com search and answer engine to provide additional context.
You need to sign up for an API key at Tavily.com and set it as an environment variable TAVILY_API_KEY to use this function.
References
create_websearch(query::AbstractString;\n api_key::AbstractString,\n search_depth::AbstractString = "basic")Arguments
query::AbstractString: The query to search for.api_key::AbstractString: The API key to use for the search. Get an API key from Tavily.search_depth::AbstractString: The depth of the search. Can be either "basic" or "advanced". Default is "basic". Advanced search calls equal to 2 requests.include_answer::Bool: Whether to include the answer in the search results. Default isfalse.include_raw_content::Bool: Whether to include the raw content in the search results. Default isfalse.max_results::Integer: The maximum number of results to return. Default is 5.include_images::Bool: Whether to include images in the search results. Default isfalse.include_domains::AbstractVector{<:AbstractString}: A list of domains to include in the search results. Default is an empty list.exclude_domains::AbstractVector{<:AbstractString}: A list of domains to exclude from the search results. Default is an empty list.
Example
r = create_websearch("Who is King Charles?")Even better, you can get not just the results but also the answer:
r = create_websearch("Who is King Charles?"; include_answer = true)See Rest API documentation for more information.
', 10) + ])); +} +const api_tools_intro = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + api_tools_intro as default +}; diff --git a/previews/PR252/assets/extra_tools_rag_tools_intro.md.4q3sQBlr.js b/previews/PR252/assets/extra_tools_rag_tools_intro.md.4q3sQBlr.js new file mode 100644 index 00000000..4cbdc4f1 --- /dev/null +++ b/previews/PR252/assets/extra_tools_rag_tools_intro.md.4q3sQBlr.js @@ -0,0 +1,15 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const _imports_0 = "/PromptingTools.jl/previews/PR252/assets/rag_diagram_highlevel.D_aLugML.png"; +const _imports_1 = "/PromptingTools.jl/previews/PR252/assets/rag_diagram_detailed._BjqL9Ae.png"; +const __pageData = JSON.parse('{"title":"RAG Tools Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"extra_tools/rag_tools_intro.md","filePath":"extra_tools/rag_tools_intro.md","lastUpdated":null}'); +const _sfc_main = { name: "extra_tools/rag_tools_intro.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
RAG Tools Introduction
RAGTools is an experimental module that provides a set of utilities for building Retrieval-Augmented Generation (RAG) applications, ie, applications that generate answers by combining knowledge of the underlying AI model with the information from the user's knowledge base.
It is designed to be powerful and flexible, allowing you to build RAG applications with minimal effort. Extend any step of the pipeline with your own custom code (see the RAG Interface section), or use the provided defaults to get started quickly.
Once the API stabilizes (near term), we hope to carve it out into a separate package.
Import the module as follows:
# required dependencies to load the necessary extensions!!!\nusing LinearAlgebra, SparseArrays, Unicode, Snowball\nusing PromptingTools.Experimental.RAGTools\n# to access unexported functionality\nconst RT = PromptingTools.Experimental.RAGToolsHighlights
The main functions to be aware of are:
build_indexto build a RAG index from a list of documents (typeChunkIndex)airagto generate answers using the RAG model on top of theindexbuilt aboveretrieveto retrieve relevant chunks from the index for a given questiongenerate!to generate an answer from the retrieved chunks
annotate_supportto highlight which parts of the RAG answer are supported by the documents in the index vs which are generated by the model, it is applied automatically if you use pretty printing withpprint(eg,pprint(result))build_qa_evalsto build a set of question-answer pairs for evaluation of the RAG model from your corpus
The hope is to provide a modular and easily extensible set of tools for building RAG applications in Julia. Feel free to open an issue or ask in the #generative-ai channel in the JuliaLang Slack if you have a specific need.
Examples
Let's build an index, we need to provide a starter list of documents:
sentences = [\n "Find the most comprehensive guide on Julia programming language for beginners published in 2023.",\n "Search for the latest advancements in quantum computing using Julia language.",\n "How to implement machine learning algorithms in Julia with examples.",\n "Looking for performance comparison between Julia, Python, and R for data analysis.",\n "Find Julia language tutorials focusing on high-performance scientific computing.",\n "Search for the top Julia language packages for data visualization and their documentation.",\n "How to set up a Julia development environment on Windows 10.",\n "Discover the best practices for parallel computing in Julia.",\n "Search for case studies of large-scale data processing using Julia.",\n "Find comprehensive resources for mastering metaprogramming in Julia.",\n "Looking for articles on the advantages of using Julia for statistical modeling.",\n "How to contribute to the Julia open-source community: A step-by-step guide.",\n "Find the comparison of numerical accuracy between Julia and MATLAB.",\n "Looking for the latest Julia language updates and their impact on AI research.",\n "How to efficiently handle big data with Julia: Techniques and libraries.",\n "Discover how Julia integrates with other programming languages and tools.",\n "Search for Julia-based frameworks for developing web applications.",\n "Find tutorials on creating interactive dashboards with Julia.",\n "How to use Julia for natural language processing and text analysis.",\n "Discover the role of Julia in the future of computational finance and econometrics."\n]Let's index these "documents":
index = build_index(sentences; chunker_kwargs=(; sources=map(i -> "Doc$i", 1:length(sentences))))This would be equivalent to the following index = build_index(SimpleIndexer(), sentences) which dispatches to the default implementation of each step via the SimpleIndexer struct. We provide these default implementations for the main functions as an optional argument - no need to provide them if you're running the default pipeline.
Notice that we have provided a chunker_kwargs argument to the build_index function. These will be kwargs passed to chunker step.
Now let's generate an answer to a question.
- Run end-to-end RAG (retrieve + generate!), return
AIMessage
question = "What are the best practices for parallel computing in Julia?"\n\nmsg = airag(index; question) # short for airag(RAGConfig(), index; question)\n## Output:\n## [ Info: Done with RAG. Total cost: \\$0.0\n## AIMessage("Some best practices for parallel computing in Julia include us...- Explore what's happening under the hood by changing the return type -
RAGResultcontains all intermediate steps.
result = airag(index; question, return_all=true)\n## RAGResult\n## question: String "What are the best practices for parallel computing in Julia?"\n## rephrased_questions: Array{String}((1,))\n## answer: SubString{String}\n## final_answer: SubString{String}\n## context: Array{String}((5,))\n## sources: Array{String}((5,))\n## emb_candidates: CandidateChunks{Int64, Float32}\n## tag_candidates: CandidateChunks{Int64, Float32}\n## filtered_candidates: CandidateChunks{Int64, Float32}\n## reranked_candidates: CandidateChunks{Int64, Float32}\n## conversations: Dict{Symbol, Vector{<:PromptingTools.AbstractMessage}}You can still get the message from the result, see result.conversations[:final_answer] (the dictionary keys correspond to the function names of those steps).
- If you need to customize it, break the pipeline into its sub-steps: retrieve and generate - RAGResult serves as the intermediate result.
# Retrieve which chunks are relevant to the question\nresult = retrieve(index, question)\n# Generate an answer\nresult = generate!(index, result)You can leverage a pretty-printing system with pprint where we automatically annotate the support of the answer by the chunks we provided to the model. It is configurable and you can select only some of its functions (eg, scores, sources).
pprint(result)You'll see the following in REPL but with COLOR highlighting in the terminal.
--------------------\nQUESTION(s)\n--------------------\n- What are the best practices for parallel computing in Julia?\n\n--------------------\nANSWER\n--------------------\nSome of the best practices for parallel computing in Julia include:[1,0.7]\n- Using [3,0.4]`@threads` for simple parallelism[1,0.34]\n- Utilizing `Distributed` module for more complex parallel tasks[1,0.19]\n- Avoiding excessive memory allocation\n- Considering task granularity for efficient workload distribution\n\n--------------------\nSOURCES\n--------------------\n1. Doc8\n2. Doc15\n3. Doc5\n4. Doc2\n5. Doc9See ?print_html for the HTML version of the pretty-printing and styling system, eg, when you want to display the results in a web application based on Genie.jl/Stipple.jl.
How to read the output
Color legend:
No color: High match with the context, can be trusted more
Blue: Partial match against some words in the context, investigate
Magenta (Red): No match with the context, fully generated by the model
Square brackets: The best matching context ID + Match score of the chunk (eg,
[3,0.4]means the highest support for the sentence is from the context chunk number 3 with a 40% match).
Want more?
See examples/building_RAG.jl for one more example.
RAG Interface
System Overview
This system is designed for information retrieval and response generation, structured in three main phases:
Preparation, when you create an instance of
AbstractIndexRetrieval, when you surface the top most relevant chunks/items in the
indexand returnAbstractRAGResult, which contains the references to the chunks (AbstractCandidateChunks)Generation, when you generate an answer based on the context built from the retrieved chunks, return either
AIMessageorAbstractRAGResult
The corresponding functions are build_index, retrieve, and generate!, respectively. Here is the high-level diagram that shows the signature of the main functions:
Notice that the first argument is a custom type for multiple dispatch. In addition, observe the "kwargs" names, that's how the keyword arguments for each function are passed down from the higher-level functions (eg, build_index(...; chunker_kwargs=(; separators=...)))). It's the simplest way to customize some step of the pipeline (eg, set a custom model with a model kwarg or prompt template with template kwarg).
The system is designed to be hackable and extensible at almost every entry point. If you want to customize the behavior of any step, you can do so by defining a new type and defining a new method for the step you're changing, eg,
PromptingTools.Experimental.RAGTools: rerank\n\nstruct MyReranker <: AbstractReranker end\nrerank(::MyReranker, index, candidates) = ...And then you would set the retrive step to use your custom MyReranker via reranker kwarg, eg, retrieve(....; reranker = MyReranker()) (or customize the main dispatching AbstractRetriever struct).
The overarching principles are:
Always dispatch / customize the behavior by defining a new
Structand the corresponding method for the existing functions (eg,rerankfunction for the re-ranking step).Custom types are provided as the first argument (the high-level functions will work without them as we provide some defaults).
Custom types do NOT have any internal fields or DATA (with the exception of managing sub-steps of the pipeline like
AbstractRetrieverorRAGConfig).Additional data should be passed around as keyword arguments (eg,
chunker_kwargsinbuild_indexto pass data to the chunking step). The intention was to have some clearly documented default values in the docstrings of each step + to have the various options all in one place.
RAG Diagram
The main functions are:
Prepare your document index with build_index:
signature:
(indexer::AbstractIndexBuilder, files_or_docs::Vector{<:AbstractString}) -> AbstractChunkIndexflow:
get_chunks->get_embeddings->get_tags->build_tagsdispatch types:
AbstractIndexBuilder,AbstractChunker,AbstractEmbedder,AbstractTagger
Run E2E RAG with airag:
signature:
(cfg::AbstractRAGConfig, index::AbstractChunkIndex; question::AbstractString)->AIMessageorAbstractRAGResultflow:
retrieve->generate!dispatch types:
AbstractRAGConfig,AbstractRetriever,AbstractGenerator
Retrieve relevant chunks with retrieve:
signature:
(retriever::AbstractRetriever, index::AbstractChunkIndex, question::AbstractString) -> AbstractRAGResultflow:
rephrase->get_embeddings->find_closest->get_tags->find_tags->rerankdispatch types:
AbstractRAGConfig,AbstractRephraser,AbstractEmbedder,AbstractSimilarityFinder,AbstractTagger,AbstractTagFilter,AbstractReranker
Generate an answer from relevant chunks with generate!:
signature:
(generator::AbstractGenerator, index::AbstractChunkIndex, result::AbstractRAGResult)->AIMessageorAbstractRAGResultflow:
build_context!->answer!->refine!->postprocess!dispatch types:
AbstractGenerator,AbstractContextBuilder,AbstractAnswerer,AbstractRefiner,AbstractPostprocessor
To discover the currently available implementations, use subtypes function, eg, subtypes(AbstractReranker).
Passing Keyword Arguments
If you need to pass keyword arguments, use the nested kwargs corresponding to the dispatch type names (rephrase step, has rephraser dispatch type and rephraser_kwargs for its keyword arguments).
For example:
cfg = RAGConfig(; retriever = AdvancedRetriever())\n\n# kwargs will be big and nested, let's prepare them upfront\n# we specify "custom" model for each component that calls LLM\nkwargs = (\n retriever = AdvancedRetriever(),\n retriever_kwargs = (;\n top_k = 100,\n top_n = 5,\n # notice that this is effectively: retriever_kwargs/rephraser_kwargs/template\n rephraser_kwargs = (;\n template = :RAGQueryHyDE,\n model = "custom")),\n generator_kwargs = (;\n # pass kwargs to `answer!` step defined by the `answerer` -> we're setting `answerer_kwargs`\n answerer_kwargs = (;\n model = "custom"),\n # api_kwargs can be shared across all components\n api_kwargs = (;\n url = "http://localhost:8080")))\n\nresult = airag(cfg, index, question; kwargs...)If you were one level deeper in the pipeline, working with retriever directly, you would pass:
retriever_kwargs = (;\n top_k = 100,\n top_n = 5,\n # notice that this is effectively: rephraser_kwargs/template\n rephraser_kwargs = (;\n template = :RAGQueryHyDE,\n model = "custom"),\n # api_kwargs can be shared across all components\n api_kwargs = (;\n url = "http://localhost:8080"))\n\nresult = retrieve(AdvancedRetriever(), index, question; retriever_kwargs...)And going even deeper, you would provide the rephraser_kwargs directly to the rephrase step, eg,
rephrase(SimpleRephraser(), question; model="custom", template = :RAGQueryHyDE, api_kwargs = (; url = "http://localhost:8080"))Deepdive
Preparation Phase:
Begins with
build_index, which creates a user-defined index type from an abstract chunk index using specified dels and function strategies.get_chunksthen divides the indexed data into manageable pieces based on a chunking strategy.get_embeddingsgenerates embeddings for each chunk using an embedding strategy to facilitate similarity arches.Finally,
get_tagsextracts relevant metadata from each chunk, enabling tag-based filtering (hybrid search index). If there aretagsavailable,build_tagsis called to build the corresponding sparse matrix for filtering with tags.
Retrieval Phase:
The
retrievestep is intended to find the most relevant chunks in theindex.rephraseis called first, if we want to rephrase the query (methods likeHyDEcan improve retrieval quite a bit)!get_embeddingsgenerates embeddings for the original + rephrased queryfind_closestlooks up the most relevant candidates (CandidateChunks) using a similarity search strategy.get_tagsextracts the potential tags (can be provided as part of theairagcall, eg, when we want to use only some small part of the indexed chunks)find_tagsfilters the candidates to strictly match at least one of the tags (if provided)rerankis called to rerank the candidates based on the reranking strategy (ie, to improve the ordering of the chunks in context).
Generation Phase:
The
generate!step is intended to generate a response based on the retrieved chunks, provided viaAbstractRAGResult(eg,RAGResult).build_context!constructs the context for response generation based on a context strategy and applies the necessary formattinganswer!generates the response based on the context and the queryrefine!is called to refine the response (optional, defaults to passthrough)postprocessing!is available for any final touches to the response or to potentially save or format the results (eg, automatically save to the disk)
Note that all generation steps are mutating the RAGResult object.
See more details and corresponding functions and types in src/Experimental/RAGTools/rag_interface.jl.
References
build_index(\n indexer::AbstractIndexBuilder, files_or_docs::Vector{<:AbstractString};\n verbose::Integer = 1,\n extras::Union{Nothing, AbstractVector} = nothing,\n index_id = gensym("ChunkEmbeddingsIndex"),\n chunker::AbstractChunker = indexer.chunker,\n chunker_kwargs::NamedTuple = NamedTuple(),\n embedder::AbstractEmbedder = indexer.embedder,\n embedder_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = indexer.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n api_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))Build an INDEX for RAG (Retriever-Augmented Generation) applications from the provided file paths. INDEX is a object storing the document chunks and their embeddings (and potentially other information).
The function processes each file or document (depending on chunker), splits its content into chunks, embeds these chunks, optionally extracts metadata, and then combines this information into a retrievable index.
Define your own methods via indexer and its subcomponents (chunker, embedder, tagger).
Arguments
indexer::AbstractIndexBuilder: The indexing logic to use. Default isSimpleIndexer().files_or_docs: A vector of valid file paths OR string documents to be indexed (chunked and embedded). Specify which mode to use viachunker.verbose: An Integer specifying the verbosity of the logs. Default is1(high-level logging).0is disabled.extras: An optional vector of extra information to be stored with each chunk. Default isnothing.index_id: A unique identifier for the index. Default is a generated symbol.chunker: The chunker logic to use for splitting the documents. Default isTextChunker().chunker_kwargs: Parameters to be provided to theget_chunksfunction. Useful to change theseparatorsormax_length.sources: A vector of strings indicating the source of each chunk. Default is equal tofiles_or_docs.
embedder: The embedder logic to use for embedding the chunks. Default isBatchEmbedder().embedder_kwargs: Parameters to be provided to theget_embeddingsfunction. Useful to change thetarget_batch_size_lengthor reduce asyncmap tasksntasks.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.
tagger: The tagger logic to use for extracting tags from the chunks. Default isNoTagger(), ie, skip tag extraction. There are alsoPassthroughTaggerandOpenTagger.tagger_kwargs: Parameters to be provided to theget_tagsfunction.model: The model to use for tags extraction. Default isPT.MODEL_CHAT.template: A template to be used for tags extraction. Default is:RAGExtractMetadataShort.tags: A vector of vectors of strings directly providing the tags for each chunk. Applicable fortagger::PasstroughTagger.
api_kwargs: Parameters to be provided to the API endpoint. Shared across all API calls if provided.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.
Returns
ChunkEmbeddingsIndex: An object containing the compiled index of chunks, embeddings, tags, vocabulary, and sources.
See also: ChunkEmbeddingsIndex, get_chunks, get_embeddings, get_tags, CandidateChunks, find_closest, find_tags, rerank, retrieve, generate!, airag
Examples
# Default is loading a vector of strings and chunking them (`TextChunker()`)\nindex = build_index(SimpleIndexer(), texts; chunker_kwargs = (; max_length=10))\n\n# Another example with tags extraction, splitting only sentences and verbose output\n# Assuming `test_files` is a vector of file paths\nindexer = SimpleIndexer(chunker=FileChunker(), tagger=OpenTagger())\nindex = build_index(indexer, test_files; \n chunker_kwargs(; separators=[". "]), verbose=true)Notes
- If you get errors about exceeding embedding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try changing theembedding_kwargs. In particular, reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes (eg, Databricks).
build_index(\n indexer::KeywordsIndexer, files_or_docs::Vector{<:AbstractString};\n verbose::Integer = 1,\n extras::Union{Nothing, AbstractVector} = nothing,\n index_id = gensym("ChunkKeywordsIndex"),\n chunker::AbstractChunker = indexer.chunker,\n chunker_kwargs::NamedTuple = NamedTuple(),\n processor::AbstractProcessor = indexer.processor,\n processor_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = indexer.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n api_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))Builds a ChunkKeywordsIndex from the provided files or documents to support keyword-based search (BM25).
airag(cfg::AbstractRAGConfig, index::AbstractDocumentIndex;\n question::AbstractString,\n verbose::Integer = 1, return_all::Bool = false,\n api_kwargs::NamedTuple = NamedTuple(),\n retriever::AbstractRetriever = cfg.retriever,\n retriever_kwargs::NamedTuple = NamedTuple(),\n generator::AbstractGenerator = cfg.generator,\n generator_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))High-level wrapper for Retrieval-Augmented Generation (RAG), it combines together the retrieve and generate! steps which you can customize if needed.
The simplest version first finds the relevant chunks in index for the question and then sends these chunks to the AI model to help with generating a response to the question.
To customize the components, replace the types (retriever, generator) of the corresponding step of the RAG pipeline - or go into sub-routines within the steps. Eg, use subtypes(AbstractRetriever) to find the available options.
Arguments
cfg::AbstractRAGConfig: The configuration for the RAG pipeline. Defaults toRAGConfig(), where you can swap sub-types to customize the pipeline.index::AbstractDocumentIndex: The chunk index to search for relevant text.question::AbstractString: The question to be answered.return_all::Bool: Iftrue, returns the details used for RAG along with the response.verbose::Integer: If>0, enables verbose logging. The higher the number, the more nested functions will log.api_kwargs: API parameters that will be forwarded to ALL of the API calls (aiembed,aigenerate, andaiextract).retriever::AbstractRetriever: The retriever to use for finding relevant chunks. Defaults tocfg.retriever, eg,SimpleRetriever(with no question rephrasing).retriever_kwargs::NamedTuple: API parameters that will be forwarded to theretrievercall. Examples of important ones:top_k::Int: Number of top candidates to retrieve based on embedding similarity.top_n::Int: Number of candidates to return after reranking.tagger::AbstractTagger: Tagger to use for tagging the chunks. Defaults toNoTagger().tagger_kwargs::NamedTuple: API parameters that will be forwarded to thetaggercall. You could provide the explicit tags directly withPassthroughTaggerandtagger_kwargs = (; tags = ["tag1", "tag2"]).
generator::AbstractGenerator: The generator to use for generating the answer. Defaults tocfg.generator, eg,SimpleGenerator.generator_kwargs::NamedTuple: API parameters that will be forwarded to thegeneratorcall. Examples of important ones:answerer_kwargs::NamedTuple: API parameters that will be forwarded to theanswerercall. Examples:model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.
refiner::AbstractRefiner: The method to use for refining the answer. Defaults togenerator.refiner, eg,NoRefiner.refiner_kwargs::NamedTuple: API parameters that will be forwarded to therefinercall.model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.
cost_tracker: An atomic counter to track the total cost of the operations (if you want to track the cost of multiple pipeline runs - it passed around in the pipeline).
Returns
If
return_allisfalse, returns the generated message (msg).If
return_allistrue, returns the detail of the full pipeline inRAGResult(see the docs).
See also build_index, retrieve, generate!, RAGResult, getpropertynested, setpropertynested, merge_kwargs_nested, ChunkKeywordsIndex.
Examples
Using airag to get a response for a question:
index = build_index(...) # create an index\nquestion = "How to make a barplot in Makie.jl?"\nmsg = airag(index; question)To understand the details of the RAG process, use return_all=true
msg, details = airag(index; question, return_all = true)\n# details is a RAGDetails object with all the internal steps of the `airag` functionYou can also pretty-print details to highlight generated text vs text that is supported by context. It also includes annotations of which context was used for each part of the response (where available).
PT.pprint(details)Example with advanced retrieval (with question rephrasing and reranking (requires COHERE_API_KEY). We will obtain top 100 chunks from embeddings (top_k) and top 5 chunks from reranking (top_n). In addition, it will be done with a "custom" locally-hosted model.
cfg = RAGConfig(; retriever = AdvancedRetriever())\n\n# kwargs will be big and nested, let's prepare them upfront\n# we specify "custom" model for each component that calls LLM\nkwargs = (\n retriever_kwargs = (;\n top_k = 100,\n top_n = 5,\n rephraser_kwargs = (;\n model = "custom"),\n embedder_kwargs = (;\n model = "custom"),\n tagger_kwargs = (;\n model = "custom")),\n generator_kwargs = (;\n answerer_kwargs = (;\n model = "custom"),\n refiner_kwargs = (;\n model = "custom")),\n api_kwargs = (;\n url = "http://localhost:8080"))\n\nresult = airag(cfg, index, question; kwargs...)If you want to use hybrid retrieval (embeddings + BM25), you can easily create an additional index based on keywords and pass them both into a MultiIndex.
You need to provide an explicit config, so the pipeline knows how to handle each index in the search similarity phase (finder).
index = # your existing index\n\n# create the multi-index with the keywords index\nindex_keywords = ChunkKeywordsIndex(index)\nmulti_index = MultiIndex([index, index_keywords])\n\n# define the similarity measures for the indices that you have (same order)\nfinder = RT.MultiFinder([RT.CosineSimilarity(), RT.BM25Similarity()])\ncfg = RAGConfig(; retriever=AdvancedRetriever(; processor=RT.KeywordsProcessor(), finder))\n\n# Run the pipeline with the new hybrid retrieval (return the `RAGResult` to see the details)\nresult = airag(cfg, multi_index; question, return_all=true)\n\n# Pretty-print the result\nPT.pprint(result)For easier manipulation of nested kwargs, see utilities getpropertynested, setpropertynested, merge_kwargs_nested.
retrieve(retriever::AbstractRetriever,\n index::AbstractChunkIndex,\n question::AbstractString;\n verbose::Integer = 1,\n top_k::Integer = 100,\n top_n::Integer = 5,\n api_kwargs::NamedTuple = NamedTuple(),\n rephraser::AbstractRephraser = retriever.rephraser,\n rephraser_kwargs::NamedTuple = NamedTuple(),\n embedder::AbstractEmbedder = retriever.embedder,\n embedder_kwargs::NamedTuple = NamedTuple(),\n processor::AbstractProcessor = retriever.processor,\n processor_kwargs::NamedTuple = NamedTuple(),\n finder::AbstractSimilarityFinder = retriever.finder,\n finder_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = retriever.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n filter::AbstractTagFilter = retriever.filter,\n filter_kwargs::NamedTuple = NamedTuple(),\n reranker::AbstractReranker = retriever.reranker,\n reranker_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Retrieves the most relevant chunks from the index for the given question and returns them in the RAGResult object.
This is the main entry point for the retrieval stage of the RAG pipeline. It is often followed by generate! step.
Notes:
- The default flow is
build_context!->answer!->refine!->postprocess!.
The arguments correspond to the steps of the retrieval process (rephrasing, embedding, finding similar docs, tagging, filtering by tags, reranking). You can customize each step by providing a new custom type that dispatches the corresponding function, eg, create your own type struct MyReranker<:AbstractReranker end and define the custom method for it rerank(::MyReranker,...) = ....
Note: Discover available retrieval sub-types for each step with subtypes(AbstractRephraser) and similar for other abstract types.
If you're using locally-hosted models, you can pass the api_kwargs with the url field set to the model's URL and make sure to provide corresponding model kwargs to rephraser, embedder, and tagger to use the custom models (they make AI calls).
Arguments
retriever: The retrieval method to use. Default isSimpleRetrieverbut could beAdvancedRetrieverfor more advanced retrieval.index: The index that holds the chunks and sources to be retrieved from.question: The question to be used for the retrieval.verbose: If>0, it prints out verbose logging. Default is1. If you set it to2, it will print out logs for each sub-function.top_k: The TOTAL number of closest chunks to return fromfind_closest. Default is100. If there are multiple rephrased questions, the number of chunks per each item will betop_k ÷ number_of_rephrased_questions.top_n: The TOTAL number of most relevant chunks to return for the context (fromrerankstep). Default is5.api_kwargs: Additional keyword arguments to be passed to the API calls (shared by allai*calls).rephraser: Transform the question into one or more questions. Default isretriever.rephraser.rephraser_kwargs: Additional keyword arguments to be passed to the rephraser.model: The model to use for rephrasing. Default isPT.MODEL_CHAT.template: The rephrasing template to use. Default is:RAGQueryOptimizeror:RAGQueryHyDE(depending on therephraserselected).
embedder: The embedding method to use. Default isretriever.embedder.embedder_kwargs: Additional keyword arguments to be passed to the embedder.processor: The processor method to use when using Keyword-based index. Default isretriever.processor.processor_kwargs: Additional keyword arguments to be passed to the processor.finder: The similarity search method to use. Default isretriever.finder, oftenCosineSimilarity.finder_kwargs: Additional keyword arguments to be passed to the similarity finder.tagger: The tag generating method to use. Default isretriever.tagger.tagger_kwargs: Additional keyword arguments to be passed to the tagger. Noteworthy arguments:tags: Directly provide the tags to use for filtering (can be String, Regex, or Vector{String}). Useful fortagger = PassthroughTagger.
filter: The tag matching method to use. Default isretriever.filter.filter_kwargs: Additional keyword arguments to be passed to the tag filter.reranker: The reranking method to use. Default isretriever.reranker.reranker_kwargs: Additional keyword arguments to be passed to the reranker.model: The model to use for reranking. Default isrerank-english-v2.0if you usereranker = CohereReranker().
cost_tracker: An atomic counter to track the cost of the retrieval. Default isThreads.Atomic{Float64}(0.0).
See also: SimpleRetriever, AdvancedRetriever, build_index, rephrase, get_embeddings, get_keywords, find_closest, get_tags, find_tags, rerank, RAGResult.
Examples
Find the 5 most relevant chunks from the index for the given question.
# assumes you have an existing index `index`\nretriever = SimpleRetriever()\n\nresult = retrieve(retriever,\n index,\n "What is the capital of France?",\n top_n = 5)\n\n# or use the default retriever (same as above)\nresult = retrieve(retriever,\n index,\n "What is the capital of France?",\n top_n = 5)Apply more advanced retrieval with question rephrasing and reranking (requires COHERE_API_KEY). We will obtain top 100 chunks from embeddings (top_k) and top 5 chunks from reranking (top_n).
retriever = AdvancedRetriever()\n\nresult = retrieve(retriever, index, question; top_k=100, top_n=5)You can use the retriever to customize your retrieval strategy or directly change the strategy types in the retrieve kwargs!
Example of using locally-hosted model hosted on localhost:8080:
retriever = SimpleRetriever()\nresult = retrieve(retriever, index, question;\n rephraser_kwargs = (; model = "custom"),\n embedder_kwargs = (; model = "custom"),\n tagger_kwargs = (; model = "custom"), api_kwargs = (;\n url = "http://localhost:8080"))generate!(\n generator::AbstractGenerator, index::AbstractDocumentIndex, result::AbstractRAGResult;\n verbose::Integer = 1,\n api_kwargs::NamedTuple = NamedTuple(),\n contexter::AbstractContextBuilder = generator.contexter,\n contexter_kwargs::NamedTuple = NamedTuple(),\n answerer::AbstractAnswerer = generator.answerer,\n answerer_kwargs::NamedTuple = NamedTuple(),\n refiner::AbstractRefiner = generator.refiner,\n refiner_kwargs::NamedTuple = NamedTuple(),\n postprocessor::AbstractPostprocessor = generator.postprocessor,\n postprocessor_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Generate the response using the provided generator and the index and result. It is the second step in the RAG pipeline (after retrieve)
Returns the mutated result with the result.final_answer and the full conversation saved in result.conversations[:final_answer].
Notes
The default flow is
build_context!->answer!->refine!->postprocess!.contexteris the method to use for building the context, eg, simply enumerate the context chunks withContextEnumerator.answereris the standard answer generation step with LLMs.refinerstep allows the LLM to critique itself and refine its own answer.postprocessorstep allows for additional processing of the answer, eg, logging, saving conversations, etc.All of its sub-routines operate by mutating the
resultobject (and adding their part).Discover available sub-types for each step with
subtypes(AbstractRefiner)and similar for other abstract types.
Arguments
generator::AbstractGenerator: Thegeneratorto use for generating the answer. Can beSimpleGeneratororAdvancedGenerator.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.verbose::Integer: If >0, enables verbose logging.api_kwargs::NamedTuple: API parameters that will be forwarded to ALL of the API calls (aiembed,aigenerate, andaiextract).contexter::AbstractContextBuilder: The method to use for building the context. Defaults togenerator.contexter, eg,ContextEnumerator.contexter_kwargs::NamedTuple: API parameters that will be forwarded to thecontextercall.answerer::AbstractAnswerer: The method to use for generating the answer. Defaults togenerator.answerer, eg,SimpleAnswerer.answerer_kwargs::NamedTuple: API parameters that will be forwarded to theanswerercall. Examples:model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.
refiner::AbstractRefiner: The method to use for refining the answer. Defaults togenerator.refiner, eg,NoRefiner.refiner_kwargs::NamedTuple: API parameters that will be forwarded to therefinercall.model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.
postprocessor::AbstractPostprocessor: The method to use for postprocessing the answer. Defaults togenerator.postprocessor, eg,NoPostprocessor.postprocessor_kwargs::NamedTuple: API parameters that will be forwarded to thepostprocessorcall.cost_tracker: An atomic counter to track the total cost of the operations.
See also: retrieve, build_context!, ContextEnumerator, answer!, SimpleAnswerer, refine!, NoRefiner, SimpleRefiner, postprocess!, NoPostprocessor
Examples
Assume we already have `index`\n\nquestion = "What are the best practices for parallel computing in Julia?"\n\n# Retrieve the relevant chunks - returns RAGResult\nresult = retrieve(index, question)\n\n# Generate the answer using the default generator, mutates the same result\nresult = generate!(index, result)annotate_support(annotater::TrigramAnnotater, answer::AbstractString,\n context::AbstractVector; min_score::Float64 = 0.5,\n skip_trigrams::Bool = true, hashed::Bool = true,\n sources::Union{Nothing, AbstractVector{<:AbstractString}} = nothing,\n min_source_score::Float64 = 0.25,\n add_sources::Bool = true,\n add_scores::Bool = true, kwargs...)Annotates the answer with the overlap/what's supported in context and returns the annotated tree of nodes representing the answer
Returns a "root" node with children nodes representing the sentences/code blocks in the answer. Only the "leaf" nodes are to be printed (to avoid duplication), "leaf" nodes are those with NO children.
Default logic:
Split into sentences/code blocks, then into tokens (~words).
Then match each token (~word) exactly.
If no exact match found, count trigram-based match (include the surrounding tokens for better contextual awareness).
If the match is higher than
min_score, it's recorded in thescoreof the node.
Arguments
annotater::TrigramAnnotater: Annotater to useanswer::AbstractString: Text to annotatecontext::AbstractVector: Context to annotate against, ie, look for "support" in the texts incontextmin_score::Float64: Minimum score to consider a match. Default: 0.5, which means that half of the trigrams of each word should matchskip_trigrams::Bool: Whether to potentially skip trigram matching if exact full match is found. Default: truehashed::Bool: Whether to use hashed trigrams. It's harder to debug, but it's much faster for larger texts (hashed text are held in a Set to deduplicate). Default: truesources::Union{Nothing, AbstractVector{<:AbstractString}}: Sources to add at the end of the context. Default: nothingmin_source_score::Float64: Minimum score to consider/to display a source. Default: 0.25, which means that at least a quarter of the trigrams of each word should match to some context. The threshold is lower thanmin_score, because it's average across ALL words in a block, so it's much harder to match fully with generated text.add_sources::Bool: Whether to add sources at the end of each code block/sentence. Sources are addded in the square brackets like "[1]". Default: trueadd_scores::Bool: Whether to add source-matching scores at the end of each code block/sentence. Scores are added in the square brackets like "[0.75]". Default: truekwargs: Additional keyword arguments to pass to
trigram_support!andset_node_style!. See their documentation for more details (eg, customize the colors of the nodes based on the score)
Example
annotater = TrigramAnnotater()\ncontext = [\n "This is a test context.", "Another context sentence.", "Final piece of context."]\nanswer = "This is a test context. Another context sentence."\n\nannotated_root = annotate_support(annotater, answer, context)\npprint(annotated_root) # pretty print the annotated treeannotate_support(\n annotater::TrigramAnnotater, result::AbstractRAGResult; min_score::Float64 = 0.5,\n skip_trigrams::Bool = true, hashed::Bool = true,\n min_source_score::Float64 = 0.25,\n add_sources::Bool = true,\n add_scores::Bool = true, kwargs...)Dispatch for annotate_support for AbstractRAGResult type. It extracts the final_answer and context from the result and calls annotate_support with them.
See annotate_support for more details.
Example
res = RAGResult(; question = "", final_answer = "This is a test.",\n context = ["Test context.", "Completely different"])\nannotated_root = annotate_support(annotater, res)\nPT.pprint(annotated_root)build_qa_evals(doc_chunks::Vector{<:AbstractString}, sources::Vector{<:AbstractString};\n model=PT.MODEL_CHAT, instructions="None.", qa_template::Symbol=:RAGCreateQAFromContext, \n verbose::Bool=true, api_kwargs::NamedTuple = NamedTuple(), kwargs...) -> Vector{QAEvalItem}Create a collection of question and answer evaluations (QAEvalItem) from document chunks and sources. This function generates Q&A pairs based on the provided document chunks, using a specified AI model and template.
Arguments
doc_chunks::Vector{<:AbstractString}: A vector of document chunks, each representing a segment of text.sources::Vector{<:AbstractString}: A vector of source identifiers corresponding to each chunk indoc_chunks(eg, filenames or paths).model: The AI model used for generating Q&A pairs. Default isPT.MODEL_CHAT.instructions::String: Additional instructions or context to provide to the model generating QA sets. Defaults to "None.".qa_template::Symbol: A template symbol that dictates the AITemplate that will be used. It must have placeholdercontext. Default is:CreateQAFromContext.api_kwargs::NamedTuple: Parameters that will be forwarded to the API endpoint.verbose::Bool: Iftrue, additional information like costs will be logged. Defaults totrue.
Returns
Vector{QAEvalItem}: A vector of QAEvalItem structs, each containing a source, context, question, and answer. Invalid or empty items are filtered out.
Notes
The function internally uses
aiextractto generate Q&A pairs based on the providedqa_template. So you can use any kwargs that you want.Each
QAEvalItemincludes the context (document chunk), the generated question and answer, and the source.The function tracks and reports the cost of AI calls if
verboseis enabled.Items where the question, answer, or context is empty are considered invalid and are filtered out.
Examples
Creating Q&A evaluations from a set of document chunks:
doc_chunks = ["Text from document 1", "Text from document 2"]\nsources = ["source1", "source2"]\nqa_evals = build_qa_evals(doc_chunks, sources)', 88) + ])); +} +const rag_tools_intro = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + rag_tools_intro as default +}; diff --git a/previews/PR252/assets/extra_tools_rag_tools_intro.md.4q3sQBlr.lean.js b/previews/PR252/assets/extra_tools_rag_tools_intro.md.4q3sQBlr.lean.js new file mode 100644 index 00000000..4cbdc4f1 --- /dev/null +++ b/previews/PR252/assets/extra_tools_rag_tools_intro.md.4q3sQBlr.lean.js @@ -0,0 +1,15 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const _imports_0 = "/PromptingTools.jl/previews/PR252/assets/rag_diagram_highlevel.D_aLugML.png"; +const _imports_1 = "/PromptingTools.jl/previews/PR252/assets/rag_diagram_detailed._BjqL9Ae.png"; +const __pageData = JSON.parse('{"title":"RAG Tools Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"extra_tools/rag_tools_intro.md","filePath":"extra_tools/rag_tools_intro.md","lastUpdated":null}'); +const _sfc_main = { name: "extra_tools/rag_tools_intro.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
RAG Tools Introduction
RAGTools is an experimental module that provides a set of utilities for building Retrieval-Augmented Generation (RAG) applications, ie, applications that generate answers by combining knowledge of the underlying AI model with the information from the user's knowledge base.
It is designed to be powerful and flexible, allowing you to build RAG applications with minimal effort. Extend any step of the pipeline with your own custom code (see the RAG Interface section), or use the provided defaults to get started quickly.
Once the API stabilizes (near term), we hope to carve it out into a separate package.
Import the module as follows:
# required dependencies to load the necessary extensions!!!\nusing LinearAlgebra, SparseArrays, Unicode, Snowball\nusing PromptingTools.Experimental.RAGTools\n# to access unexported functionality\nconst RT = PromptingTools.Experimental.RAGToolsHighlights
The main functions to be aware of are:
build_indexto build a RAG index from a list of documents (typeChunkIndex)airagto generate answers using the RAG model on top of theindexbuilt aboveretrieveto retrieve relevant chunks from the index for a given questiongenerate!to generate an answer from the retrieved chunks
annotate_supportto highlight which parts of the RAG answer are supported by the documents in the index vs which are generated by the model, it is applied automatically if you use pretty printing withpprint(eg,pprint(result))build_qa_evalsto build a set of question-answer pairs for evaluation of the RAG model from your corpus
The hope is to provide a modular and easily extensible set of tools for building RAG applications in Julia. Feel free to open an issue or ask in the #generative-ai channel in the JuliaLang Slack if you have a specific need.
Examples
Let's build an index, we need to provide a starter list of documents:
sentences = [\n "Find the most comprehensive guide on Julia programming language for beginners published in 2023.",\n "Search for the latest advancements in quantum computing using Julia language.",\n "How to implement machine learning algorithms in Julia with examples.",\n "Looking for performance comparison between Julia, Python, and R for data analysis.",\n "Find Julia language tutorials focusing on high-performance scientific computing.",\n "Search for the top Julia language packages for data visualization and their documentation.",\n "How to set up a Julia development environment on Windows 10.",\n "Discover the best practices for parallel computing in Julia.",\n "Search for case studies of large-scale data processing using Julia.",\n "Find comprehensive resources for mastering metaprogramming in Julia.",\n "Looking for articles on the advantages of using Julia for statistical modeling.",\n "How to contribute to the Julia open-source community: A step-by-step guide.",\n "Find the comparison of numerical accuracy between Julia and MATLAB.",\n "Looking for the latest Julia language updates and their impact on AI research.",\n "How to efficiently handle big data with Julia: Techniques and libraries.",\n "Discover how Julia integrates with other programming languages and tools.",\n "Search for Julia-based frameworks for developing web applications.",\n "Find tutorials on creating interactive dashboards with Julia.",\n "How to use Julia for natural language processing and text analysis.",\n "Discover the role of Julia in the future of computational finance and econometrics."\n]Let's index these "documents":
index = build_index(sentences; chunker_kwargs=(; sources=map(i -> "Doc$i", 1:length(sentences))))This would be equivalent to the following index = build_index(SimpleIndexer(), sentences) which dispatches to the default implementation of each step via the SimpleIndexer struct. We provide these default implementations for the main functions as an optional argument - no need to provide them if you're running the default pipeline.
Notice that we have provided a chunker_kwargs argument to the build_index function. These will be kwargs passed to chunker step.
Now let's generate an answer to a question.
- Run end-to-end RAG (retrieve + generate!), return
AIMessage
question = "What are the best practices for parallel computing in Julia?"\n\nmsg = airag(index; question) # short for airag(RAGConfig(), index; question)\n## Output:\n## [ Info: Done with RAG. Total cost: \\$0.0\n## AIMessage("Some best practices for parallel computing in Julia include us...- Explore what's happening under the hood by changing the return type -
RAGResultcontains all intermediate steps.
result = airag(index; question, return_all=true)\n## RAGResult\n## question: String "What are the best practices for parallel computing in Julia?"\n## rephrased_questions: Array{String}((1,))\n## answer: SubString{String}\n## final_answer: SubString{String}\n## context: Array{String}((5,))\n## sources: Array{String}((5,))\n## emb_candidates: CandidateChunks{Int64, Float32}\n## tag_candidates: CandidateChunks{Int64, Float32}\n## filtered_candidates: CandidateChunks{Int64, Float32}\n## reranked_candidates: CandidateChunks{Int64, Float32}\n## conversations: Dict{Symbol, Vector{<:PromptingTools.AbstractMessage}}You can still get the message from the result, see result.conversations[:final_answer] (the dictionary keys correspond to the function names of those steps).
- If you need to customize it, break the pipeline into its sub-steps: retrieve and generate - RAGResult serves as the intermediate result.
# Retrieve which chunks are relevant to the question\nresult = retrieve(index, question)\n# Generate an answer\nresult = generate!(index, result)You can leverage a pretty-printing system with pprint where we automatically annotate the support of the answer by the chunks we provided to the model. It is configurable and you can select only some of its functions (eg, scores, sources).
pprint(result)You'll see the following in REPL but with COLOR highlighting in the terminal.
--------------------\nQUESTION(s)\n--------------------\n- What are the best practices for parallel computing in Julia?\n\n--------------------\nANSWER\n--------------------\nSome of the best practices for parallel computing in Julia include:[1,0.7]\n- Using [3,0.4]`@threads` for simple parallelism[1,0.34]\n- Utilizing `Distributed` module for more complex parallel tasks[1,0.19]\n- Avoiding excessive memory allocation\n- Considering task granularity for efficient workload distribution\n\n--------------------\nSOURCES\n--------------------\n1. Doc8\n2. Doc15\n3. Doc5\n4. Doc2\n5. Doc9See ?print_html for the HTML version of the pretty-printing and styling system, eg, when you want to display the results in a web application based on Genie.jl/Stipple.jl.
How to read the output
Color legend:
No color: High match with the context, can be trusted more
Blue: Partial match against some words in the context, investigate
Magenta (Red): No match with the context, fully generated by the model
Square brackets: The best matching context ID + Match score of the chunk (eg,
[3,0.4]means the highest support for the sentence is from the context chunk number 3 with a 40% match).
Want more?
See examples/building_RAG.jl for one more example.
RAG Interface
System Overview
This system is designed for information retrieval and response generation, structured in three main phases:
Preparation, when you create an instance of
AbstractIndexRetrieval, when you surface the top most relevant chunks/items in the
indexand returnAbstractRAGResult, which contains the references to the chunks (AbstractCandidateChunks)Generation, when you generate an answer based on the context built from the retrieved chunks, return either
AIMessageorAbstractRAGResult
The corresponding functions are build_index, retrieve, and generate!, respectively. Here is the high-level diagram that shows the signature of the main functions:
Notice that the first argument is a custom type for multiple dispatch. In addition, observe the "kwargs" names, that's how the keyword arguments for each function are passed down from the higher-level functions (eg, build_index(...; chunker_kwargs=(; separators=...)))). It's the simplest way to customize some step of the pipeline (eg, set a custom model with a model kwarg or prompt template with template kwarg).
The system is designed to be hackable and extensible at almost every entry point. If you want to customize the behavior of any step, you can do so by defining a new type and defining a new method for the step you're changing, eg,
PromptingTools.Experimental.RAGTools: rerank\n\nstruct MyReranker <: AbstractReranker end\nrerank(::MyReranker, index, candidates) = ...And then you would set the retrive step to use your custom MyReranker via reranker kwarg, eg, retrieve(....; reranker = MyReranker()) (or customize the main dispatching AbstractRetriever struct).
The overarching principles are:
Always dispatch / customize the behavior by defining a new
Structand the corresponding method for the existing functions (eg,rerankfunction for the re-ranking step).Custom types are provided as the first argument (the high-level functions will work without them as we provide some defaults).
Custom types do NOT have any internal fields or DATA (with the exception of managing sub-steps of the pipeline like
AbstractRetrieverorRAGConfig).Additional data should be passed around as keyword arguments (eg,
chunker_kwargsinbuild_indexto pass data to the chunking step). The intention was to have some clearly documented default values in the docstrings of each step + to have the various options all in one place.
RAG Diagram
The main functions are:
Prepare your document index with build_index:
signature:
(indexer::AbstractIndexBuilder, files_or_docs::Vector{<:AbstractString}) -> AbstractChunkIndexflow:
get_chunks->get_embeddings->get_tags->build_tagsdispatch types:
AbstractIndexBuilder,AbstractChunker,AbstractEmbedder,AbstractTagger
Run E2E RAG with airag:
signature:
(cfg::AbstractRAGConfig, index::AbstractChunkIndex; question::AbstractString)->AIMessageorAbstractRAGResultflow:
retrieve->generate!dispatch types:
AbstractRAGConfig,AbstractRetriever,AbstractGenerator
Retrieve relevant chunks with retrieve:
signature:
(retriever::AbstractRetriever, index::AbstractChunkIndex, question::AbstractString) -> AbstractRAGResultflow:
rephrase->get_embeddings->find_closest->get_tags->find_tags->rerankdispatch types:
AbstractRAGConfig,AbstractRephraser,AbstractEmbedder,AbstractSimilarityFinder,AbstractTagger,AbstractTagFilter,AbstractReranker
Generate an answer from relevant chunks with generate!:
signature:
(generator::AbstractGenerator, index::AbstractChunkIndex, result::AbstractRAGResult)->AIMessageorAbstractRAGResultflow:
build_context!->answer!->refine!->postprocess!dispatch types:
AbstractGenerator,AbstractContextBuilder,AbstractAnswerer,AbstractRefiner,AbstractPostprocessor
To discover the currently available implementations, use subtypes function, eg, subtypes(AbstractReranker).
Passing Keyword Arguments
If you need to pass keyword arguments, use the nested kwargs corresponding to the dispatch type names (rephrase step, has rephraser dispatch type and rephraser_kwargs for its keyword arguments).
For example:
cfg = RAGConfig(; retriever = AdvancedRetriever())\n\n# kwargs will be big and nested, let's prepare them upfront\n# we specify "custom" model for each component that calls LLM\nkwargs = (\n retriever = AdvancedRetriever(),\n retriever_kwargs = (;\n top_k = 100,\n top_n = 5,\n # notice that this is effectively: retriever_kwargs/rephraser_kwargs/template\n rephraser_kwargs = (;\n template = :RAGQueryHyDE,\n model = "custom")),\n generator_kwargs = (;\n # pass kwargs to `answer!` step defined by the `answerer` -> we're setting `answerer_kwargs`\n answerer_kwargs = (;\n model = "custom"),\n # api_kwargs can be shared across all components\n api_kwargs = (;\n url = "http://localhost:8080")))\n\nresult = airag(cfg, index, question; kwargs...)If you were one level deeper in the pipeline, working with retriever directly, you would pass:
retriever_kwargs = (;\n top_k = 100,\n top_n = 5,\n # notice that this is effectively: rephraser_kwargs/template\n rephraser_kwargs = (;\n template = :RAGQueryHyDE,\n model = "custom"),\n # api_kwargs can be shared across all components\n api_kwargs = (;\n url = "http://localhost:8080"))\n\nresult = retrieve(AdvancedRetriever(), index, question; retriever_kwargs...)And going even deeper, you would provide the rephraser_kwargs directly to the rephrase step, eg,
rephrase(SimpleRephraser(), question; model="custom", template = :RAGQueryHyDE, api_kwargs = (; url = "http://localhost:8080"))Deepdive
Preparation Phase:
Begins with
build_index, which creates a user-defined index type from an abstract chunk index using specified dels and function strategies.get_chunksthen divides the indexed data into manageable pieces based on a chunking strategy.get_embeddingsgenerates embeddings for each chunk using an embedding strategy to facilitate similarity arches.Finally,
get_tagsextracts relevant metadata from each chunk, enabling tag-based filtering (hybrid search index). If there aretagsavailable,build_tagsis called to build the corresponding sparse matrix for filtering with tags.
Retrieval Phase:
The
retrievestep is intended to find the most relevant chunks in theindex.rephraseis called first, if we want to rephrase the query (methods likeHyDEcan improve retrieval quite a bit)!get_embeddingsgenerates embeddings for the original + rephrased queryfind_closestlooks up the most relevant candidates (CandidateChunks) using a similarity search strategy.get_tagsextracts the potential tags (can be provided as part of theairagcall, eg, when we want to use only some small part of the indexed chunks)find_tagsfilters the candidates to strictly match at least one of the tags (if provided)rerankis called to rerank the candidates based on the reranking strategy (ie, to improve the ordering of the chunks in context).
Generation Phase:
The
generate!step is intended to generate a response based on the retrieved chunks, provided viaAbstractRAGResult(eg,RAGResult).build_context!constructs the context for response generation based on a context strategy and applies the necessary formattinganswer!generates the response based on the context and the queryrefine!is called to refine the response (optional, defaults to passthrough)postprocessing!is available for any final touches to the response or to potentially save or format the results (eg, automatically save to the disk)
Note that all generation steps are mutating the RAGResult object.
See more details and corresponding functions and types in src/Experimental/RAGTools/rag_interface.jl.
References
build_index(\n indexer::AbstractIndexBuilder, files_or_docs::Vector{<:AbstractString};\n verbose::Integer = 1,\n extras::Union{Nothing, AbstractVector} = nothing,\n index_id = gensym("ChunkEmbeddingsIndex"),\n chunker::AbstractChunker = indexer.chunker,\n chunker_kwargs::NamedTuple = NamedTuple(),\n embedder::AbstractEmbedder = indexer.embedder,\n embedder_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = indexer.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n api_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))Build an INDEX for RAG (Retriever-Augmented Generation) applications from the provided file paths. INDEX is a object storing the document chunks and their embeddings (and potentially other information).
The function processes each file or document (depending on chunker), splits its content into chunks, embeds these chunks, optionally extracts metadata, and then combines this information into a retrievable index.
Define your own methods via indexer and its subcomponents (chunker, embedder, tagger).
Arguments
indexer::AbstractIndexBuilder: The indexing logic to use. Default isSimpleIndexer().files_or_docs: A vector of valid file paths OR string documents to be indexed (chunked and embedded). Specify which mode to use viachunker.verbose: An Integer specifying the verbosity of the logs. Default is1(high-level logging).0is disabled.extras: An optional vector of extra information to be stored with each chunk. Default isnothing.index_id: A unique identifier for the index. Default is a generated symbol.chunker: The chunker logic to use for splitting the documents. Default isTextChunker().chunker_kwargs: Parameters to be provided to theget_chunksfunction. Useful to change theseparatorsormax_length.sources: A vector of strings indicating the source of each chunk. Default is equal tofiles_or_docs.
embedder: The embedder logic to use for embedding the chunks. Default isBatchEmbedder().embedder_kwargs: Parameters to be provided to theget_embeddingsfunction. Useful to change thetarget_batch_size_lengthor reduce asyncmap tasksntasks.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.
tagger: The tagger logic to use for extracting tags from the chunks. Default isNoTagger(), ie, skip tag extraction. There are alsoPassthroughTaggerandOpenTagger.tagger_kwargs: Parameters to be provided to theget_tagsfunction.model: The model to use for tags extraction. Default isPT.MODEL_CHAT.template: A template to be used for tags extraction. Default is:RAGExtractMetadataShort.tags: A vector of vectors of strings directly providing the tags for each chunk. Applicable fortagger::PasstroughTagger.
api_kwargs: Parameters to be provided to the API endpoint. Shared across all API calls if provided.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.
Returns
ChunkEmbeddingsIndex: An object containing the compiled index of chunks, embeddings, tags, vocabulary, and sources.
See also: ChunkEmbeddingsIndex, get_chunks, get_embeddings, get_tags, CandidateChunks, find_closest, find_tags, rerank, retrieve, generate!, airag
Examples
# Default is loading a vector of strings and chunking them (`TextChunker()`)\nindex = build_index(SimpleIndexer(), texts; chunker_kwargs = (; max_length=10))\n\n# Another example with tags extraction, splitting only sentences and verbose output\n# Assuming `test_files` is a vector of file paths\nindexer = SimpleIndexer(chunker=FileChunker(), tagger=OpenTagger())\nindex = build_index(indexer, test_files; \n chunker_kwargs(; separators=[". "]), verbose=true)Notes
- If you get errors about exceeding embedding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try changing theembedding_kwargs. In particular, reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes (eg, Databricks).
build_index(\n indexer::KeywordsIndexer, files_or_docs::Vector{<:AbstractString};\n verbose::Integer = 1,\n extras::Union{Nothing, AbstractVector} = nothing,\n index_id = gensym("ChunkKeywordsIndex"),\n chunker::AbstractChunker = indexer.chunker,\n chunker_kwargs::NamedTuple = NamedTuple(),\n processor::AbstractProcessor = indexer.processor,\n processor_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = indexer.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n api_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))Builds a ChunkKeywordsIndex from the provided files or documents to support keyword-based search (BM25).
airag(cfg::AbstractRAGConfig, index::AbstractDocumentIndex;\n question::AbstractString,\n verbose::Integer = 1, return_all::Bool = false,\n api_kwargs::NamedTuple = NamedTuple(),\n retriever::AbstractRetriever = cfg.retriever,\n retriever_kwargs::NamedTuple = NamedTuple(),\n generator::AbstractGenerator = cfg.generator,\n generator_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))High-level wrapper for Retrieval-Augmented Generation (RAG), it combines together the retrieve and generate! steps which you can customize if needed.
The simplest version first finds the relevant chunks in index for the question and then sends these chunks to the AI model to help with generating a response to the question.
To customize the components, replace the types (retriever, generator) of the corresponding step of the RAG pipeline - or go into sub-routines within the steps. Eg, use subtypes(AbstractRetriever) to find the available options.
Arguments
cfg::AbstractRAGConfig: The configuration for the RAG pipeline. Defaults toRAGConfig(), where you can swap sub-types to customize the pipeline.index::AbstractDocumentIndex: The chunk index to search for relevant text.question::AbstractString: The question to be answered.return_all::Bool: Iftrue, returns the details used for RAG along with the response.verbose::Integer: If>0, enables verbose logging. The higher the number, the more nested functions will log.api_kwargs: API parameters that will be forwarded to ALL of the API calls (aiembed,aigenerate, andaiextract).retriever::AbstractRetriever: The retriever to use for finding relevant chunks. Defaults tocfg.retriever, eg,SimpleRetriever(with no question rephrasing).retriever_kwargs::NamedTuple: API parameters that will be forwarded to theretrievercall. Examples of important ones:top_k::Int: Number of top candidates to retrieve based on embedding similarity.top_n::Int: Number of candidates to return after reranking.tagger::AbstractTagger: Tagger to use for tagging the chunks. Defaults toNoTagger().tagger_kwargs::NamedTuple: API parameters that will be forwarded to thetaggercall. You could provide the explicit tags directly withPassthroughTaggerandtagger_kwargs = (; tags = ["tag1", "tag2"]).
generator::AbstractGenerator: The generator to use for generating the answer. Defaults tocfg.generator, eg,SimpleGenerator.generator_kwargs::NamedTuple: API parameters that will be forwarded to thegeneratorcall. Examples of important ones:answerer_kwargs::NamedTuple: API parameters that will be forwarded to theanswerercall. Examples:model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.
refiner::AbstractRefiner: The method to use for refining the answer. Defaults togenerator.refiner, eg,NoRefiner.refiner_kwargs::NamedTuple: API parameters that will be forwarded to therefinercall.model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.
cost_tracker: An atomic counter to track the total cost of the operations (if you want to track the cost of multiple pipeline runs - it passed around in the pipeline).
Returns
If
return_allisfalse, returns the generated message (msg).If
return_allistrue, returns the detail of the full pipeline inRAGResult(see the docs).
See also build_index, retrieve, generate!, RAGResult, getpropertynested, setpropertynested, merge_kwargs_nested, ChunkKeywordsIndex.
Examples
Using airag to get a response for a question:
index = build_index(...) # create an index\nquestion = "How to make a barplot in Makie.jl?"\nmsg = airag(index; question)To understand the details of the RAG process, use return_all=true
msg, details = airag(index; question, return_all = true)\n# details is a RAGDetails object with all the internal steps of the `airag` functionYou can also pretty-print details to highlight generated text vs text that is supported by context. It also includes annotations of which context was used for each part of the response (where available).
PT.pprint(details)Example with advanced retrieval (with question rephrasing and reranking (requires COHERE_API_KEY). We will obtain top 100 chunks from embeddings (top_k) and top 5 chunks from reranking (top_n). In addition, it will be done with a "custom" locally-hosted model.
cfg = RAGConfig(; retriever = AdvancedRetriever())\n\n# kwargs will be big and nested, let's prepare them upfront\n# we specify "custom" model for each component that calls LLM\nkwargs = (\n retriever_kwargs = (;\n top_k = 100,\n top_n = 5,\n rephraser_kwargs = (;\n model = "custom"),\n embedder_kwargs = (;\n model = "custom"),\n tagger_kwargs = (;\n model = "custom")),\n generator_kwargs = (;\n answerer_kwargs = (;\n model = "custom"),\n refiner_kwargs = (;\n model = "custom")),\n api_kwargs = (;\n url = "http://localhost:8080"))\n\nresult = airag(cfg, index, question; kwargs...)If you want to use hybrid retrieval (embeddings + BM25), you can easily create an additional index based on keywords and pass them both into a MultiIndex.
You need to provide an explicit config, so the pipeline knows how to handle each index in the search similarity phase (finder).
index = # your existing index\n\n# create the multi-index with the keywords index\nindex_keywords = ChunkKeywordsIndex(index)\nmulti_index = MultiIndex([index, index_keywords])\n\n# define the similarity measures for the indices that you have (same order)\nfinder = RT.MultiFinder([RT.CosineSimilarity(), RT.BM25Similarity()])\ncfg = RAGConfig(; retriever=AdvancedRetriever(; processor=RT.KeywordsProcessor(), finder))\n\n# Run the pipeline with the new hybrid retrieval (return the `RAGResult` to see the details)\nresult = airag(cfg, multi_index; question, return_all=true)\n\n# Pretty-print the result\nPT.pprint(result)For easier manipulation of nested kwargs, see utilities getpropertynested, setpropertynested, merge_kwargs_nested.
retrieve(retriever::AbstractRetriever,\n index::AbstractChunkIndex,\n question::AbstractString;\n verbose::Integer = 1,\n top_k::Integer = 100,\n top_n::Integer = 5,\n api_kwargs::NamedTuple = NamedTuple(),\n rephraser::AbstractRephraser = retriever.rephraser,\n rephraser_kwargs::NamedTuple = NamedTuple(),\n embedder::AbstractEmbedder = retriever.embedder,\n embedder_kwargs::NamedTuple = NamedTuple(),\n processor::AbstractProcessor = retriever.processor,\n processor_kwargs::NamedTuple = NamedTuple(),\n finder::AbstractSimilarityFinder = retriever.finder,\n finder_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = retriever.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n filter::AbstractTagFilter = retriever.filter,\n filter_kwargs::NamedTuple = NamedTuple(),\n reranker::AbstractReranker = retriever.reranker,\n reranker_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Retrieves the most relevant chunks from the index for the given question and returns them in the RAGResult object.
This is the main entry point for the retrieval stage of the RAG pipeline. It is often followed by generate! step.
Notes:
- The default flow is
build_context!->answer!->refine!->postprocess!.
The arguments correspond to the steps of the retrieval process (rephrasing, embedding, finding similar docs, tagging, filtering by tags, reranking). You can customize each step by providing a new custom type that dispatches the corresponding function, eg, create your own type struct MyReranker<:AbstractReranker end and define the custom method for it rerank(::MyReranker,...) = ....
Note: Discover available retrieval sub-types for each step with subtypes(AbstractRephraser) and similar for other abstract types.
If you're using locally-hosted models, you can pass the api_kwargs with the url field set to the model's URL and make sure to provide corresponding model kwargs to rephraser, embedder, and tagger to use the custom models (they make AI calls).
Arguments
retriever: The retrieval method to use. Default isSimpleRetrieverbut could beAdvancedRetrieverfor more advanced retrieval.index: The index that holds the chunks and sources to be retrieved from.question: The question to be used for the retrieval.verbose: If>0, it prints out verbose logging. Default is1. If you set it to2, it will print out logs for each sub-function.top_k: The TOTAL number of closest chunks to return fromfind_closest. Default is100. If there are multiple rephrased questions, the number of chunks per each item will betop_k ÷ number_of_rephrased_questions.top_n: The TOTAL number of most relevant chunks to return for the context (fromrerankstep). Default is5.api_kwargs: Additional keyword arguments to be passed to the API calls (shared by allai*calls).rephraser: Transform the question into one or more questions. Default isretriever.rephraser.rephraser_kwargs: Additional keyword arguments to be passed to the rephraser.model: The model to use for rephrasing. Default isPT.MODEL_CHAT.template: The rephrasing template to use. Default is:RAGQueryOptimizeror:RAGQueryHyDE(depending on therephraserselected).
embedder: The embedding method to use. Default isretriever.embedder.embedder_kwargs: Additional keyword arguments to be passed to the embedder.processor: The processor method to use when using Keyword-based index. Default isretriever.processor.processor_kwargs: Additional keyword arguments to be passed to the processor.finder: The similarity search method to use. Default isretriever.finder, oftenCosineSimilarity.finder_kwargs: Additional keyword arguments to be passed to the similarity finder.tagger: The tag generating method to use. Default isretriever.tagger.tagger_kwargs: Additional keyword arguments to be passed to the tagger. Noteworthy arguments:tags: Directly provide the tags to use for filtering (can be String, Regex, or Vector{String}). Useful fortagger = PassthroughTagger.
filter: The tag matching method to use. Default isretriever.filter.filter_kwargs: Additional keyword arguments to be passed to the tag filter.reranker: The reranking method to use. Default isretriever.reranker.reranker_kwargs: Additional keyword arguments to be passed to the reranker.model: The model to use for reranking. Default isrerank-english-v2.0if you usereranker = CohereReranker().
cost_tracker: An atomic counter to track the cost of the retrieval. Default isThreads.Atomic{Float64}(0.0).
See also: SimpleRetriever, AdvancedRetriever, build_index, rephrase, get_embeddings, get_keywords, find_closest, get_tags, find_tags, rerank, RAGResult.
Examples
Find the 5 most relevant chunks from the index for the given question.
# assumes you have an existing index `index`\nretriever = SimpleRetriever()\n\nresult = retrieve(retriever,\n index,\n "What is the capital of France?",\n top_n = 5)\n\n# or use the default retriever (same as above)\nresult = retrieve(retriever,\n index,\n "What is the capital of France?",\n top_n = 5)Apply more advanced retrieval with question rephrasing and reranking (requires COHERE_API_KEY). We will obtain top 100 chunks from embeddings (top_k) and top 5 chunks from reranking (top_n).
retriever = AdvancedRetriever()\n\nresult = retrieve(retriever, index, question; top_k=100, top_n=5)You can use the retriever to customize your retrieval strategy or directly change the strategy types in the retrieve kwargs!
Example of using locally-hosted model hosted on localhost:8080:
retriever = SimpleRetriever()\nresult = retrieve(retriever, index, question;\n rephraser_kwargs = (; model = "custom"),\n embedder_kwargs = (; model = "custom"),\n tagger_kwargs = (; model = "custom"), api_kwargs = (;\n url = "http://localhost:8080"))generate!(\n generator::AbstractGenerator, index::AbstractDocumentIndex, result::AbstractRAGResult;\n verbose::Integer = 1,\n api_kwargs::NamedTuple = NamedTuple(),\n contexter::AbstractContextBuilder = generator.contexter,\n contexter_kwargs::NamedTuple = NamedTuple(),\n answerer::AbstractAnswerer = generator.answerer,\n answerer_kwargs::NamedTuple = NamedTuple(),\n refiner::AbstractRefiner = generator.refiner,\n refiner_kwargs::NamedTuple = NamedTuple(),\n postprocessor::AbstractPostprocessor = generator.postprocessor,\n postprocessor_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Generate the response using the provided generator and the index and result. It is the second step in the RAG pipeline (after retrieve)
Returns the mutated result with the result.final_answer and the full conversation saved in result.conversations[:final_answer].
Notes
The default flow is
build_context!->answer!->refine!->postprocess!.contexteris the method to use for building the context, eg, simply enumerate the context chunks withContextEnumerator.answereris the standard answer generation step with LLMs.refinerstep allows the LLM to critique itself and refine its own answer.postprocessorstep allows for additional processing of the answer, eg, logging, saving conversations, etc.All of its sub-routines operate by mutating the
resultobject (and adding their part).Discover available sub-types for each step with
subtypes(AbstractRefiner)and similar for other abstract types.
Arguments
generator::AbstractGenerator: Thegeneratorto use for generating the answer. Can beSimpleGeneratororAdvancedGenerator.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.verbose::Integer: If >0, enables verbose logging.api_kwargs::NamedTuple: API parameters that will be forwarded to ALL of the API calls (aiembed,aigenerate, andaiextract).contexter::AbstractContextBuilder: The method to use for building the context. Defaults togenerator.contexter, eg,ContextEnumerator.contexter_kwargs::NamedTuple: API parameters that will be forwarded to thecontextercall.answerer::AbstractAnswerer: The method to use for generating the answer. Defaults togenerator.answerer, eg,SimpleAnswerer.answerer_kwargs::NamedTuple: API parameters that will be forwarded to theanswerercall. Examples:model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.
refiner::AbstractRefiner: The method to use for refining the answer. Defaults togenerator.refiner, eg,NoRefiner.refiner_kwargs::NamedTuple: API parameters that will be forwarded to therefinercall.model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.
postprocessor::AbstractPostprocessor: The method to use for postprocessing the answer. Defaults togenerator.postprocessor, eg,NoPostprocessor.postprocessor_kwargs::NamedTuple: API parameters that will be forwarded to thepostprocessorcall.cost_tracker: An atomic counter to track the total cost of the operations.
See also: retrieve, build_context!, ContextEnumerator, answer!, SimpleAnswerer, refine!, NoRefiner, SimpleRefiner, postprocess!, NoPostprocessor
Examples
Assume we already have `index`\n\nquestion = "What are the best practices for parallel computing in Julia?"\n\n# Retrieve the relevant chunks - returns RAGResult\nresult = retrieve(index, question)\n\n# Generate the answer using the default generator, mutates the same result\nresult = generate!(index, result)annotate_support(annotater::TrigramAnnotater, answer::AbstractString,\n context::AbstractVector; min_score::Float64 = 0.5,\n skip_trigrams::Bool = true, hashed::Bool = true,\n sources::Union{Nothing, AbstractVector{<:AbstractString}} = nothing,\n min_source_score::Float64 = 0.25,\n add_sources::Bool = true,\n add_scores::Bool = true, kwargs...)Annotates the answer with the overlap/what's supported in context and returns the annotated tree of nodes representing the answer
Returns a "root" node with children nodes representing the sentences/code blocks in the answer. Only the "leaf" nodes are to be printed (to avoid duplication), "leaf" nodes are those with NO children.
Default logic:
Split into sentences/code blocks, then into tokens (~words).
Then match each token (~word) exactly.
If no exact match found, count trigram-based match (include the surrounding tokens for better contextual awareness).
If the match is higher than
min_score, it's recorded in thescoreof the node.
Arguments
annotater::TrigramAnnotater: Annotater to useanswer::AbstractString: Text to annotatecontext::AbstractVector: Context to annotate against, ie, look for "support" in the texts incontextmin_score::Float64: Minimum score to consider a match. Default: 0.5, which means that half of the trigrams of each word should matchskip_trigrams::Bool: Whether to potentially skip trigram matching if exact full match is found. Default: truehashed::Bool: Whether to use hashed trigrams. It's harder to debug, but it's much faster for larger texts (hashed text are held in a Set to deduplicate). Default: truesources::Union{Nothing, AbstractVector{<:AbstractString}}: Sources to add at the end of the context. Default: nothingmin_source_score::Float64: Minimum score to consider/to display a source. Default: 0.25, which means that at least a quarter of the trigrams of each word should match to some context. The threshold is lower thanmin_score, because it's average across ALL words in a block, so it's much harder to match fully with generated text.add_sources::Bool: Whether to add sources at the end of each code block/sentence. Sources are addded in the square brackets like "[1]". Default: trueadd_scores::Bool: Whether to add source-matching scores at the end of each code block/sentence. Scores are added in the square brackets like "[0.75]". Default: truekwargs: Additional keyword arguments to pass to
trigram_support!andset_node_style!. See their documentation for more details (eg, customize the colors of the nodes based on the score)
Example
annotater = TrigramAnnotater()\ncontext = [\n "This is a test context.", "Another context sentence.", "Final piece of context."]\nanswer = "This is a test context. Another context sentence."\n\nannotated_root = annotate_support(annotater, answer, context)\npprint(annotated_root) # pretty print the annotated treeannotate_support(\n annotater::TrigramAnnotater, result::AbstractRAGResult; min_score::Float64 = 0.5,\n skip_trigrams::Bool = true, hashed::Bool = true,\n min_source_score::Float64 = 0.25,\n add_sources::Bool = true,\n add_scores::Bool = true, kwargs...)Dispatch for annotate_support for AbstractRAGResult type. It extracts the final_answer and context from the result and calls annotate_support with them.
See annotate_support for more details.
Example
res = RAGResult(; question = "", final_answer = "This is a test.",\n context = ["Test context.", "Completely different"])\nannotated_root = annotate_support(annotater, res)\nPT.pprint(annotated_root)build_qa_evals(doc_chunks::Vector{<:AbstractString}, sources::Vector{<:AbstractString};\n model=PT.MODEL_CHAT, instructions="None.", qa_template::Symbol=:RAGCreateQAFromContext, \n verbose::Bool=true, api_kwargs::NamedTuple = NamedTuple(), kwargs...) -> Vector{QAEvalItem}Create a collection of question and answer evaluations (QAEvalItem) from document chunks and sources. This function generates Q&A pairs based on the provided document chunks, using a specified AI model and template.
Arguments
doc_chunks::Vector{<:AbstractString}: A vector of document chunks, each representing a segment of text.sources::Vector{<:AbstractString}: A vector of source identifiers corresponding to each chunk indoc_chunks(eg, filenames or paths).model: The AI model used for generating Q&A pairs. Default isPT.MODEL_CHAT.instructions::String: Additional instructions or context to provide to the model generating QA sets. Defaults to "None.".qa_template::Symbol: A template symbol that dictates the AITemplate that will be used. It must have placeholdercontext. Default is:CreateQAFromContext.api_kwargs::NamedTuple: Parameters that will be forwarded to the API endpoint.verbose::Bool: Iftrue, additional information like costs will be logged. Defaults totrue.
Returns
Vector{QAEvalItem}: A vector of QAEvalItem structs, each containing a source, context, question, and answer. Invalid or empty items are filtered out.
Notes
The function internally uses
aiextractto generate Q&A pairs based on the providedqa_template. So you can use any kwargs that you want.Each
QAEvalItemincludes the context (document chunk), the generated question and answer, and the source.The function tracks and reports the cost of AI calls if
verboseis enabled.Items where the question, answer, or context is empty are considered invalid and are filtered out.
Examples
Creating Q&A evaluations from a set of document chunks:
doc_chunks = ["Text from document 1", "Text from document 2"]\nsources = ["source1", "source2"]\nqa_evals = build_qa_evals(doc_chunks, sources)', 88) + ])); +} +const rag_tools_intro = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + rag_tools_intro as default +}; diff --git a/previews/PR252/assets/extra_tools_text_utilities_intro.md.KU1O3vgQ.js b/previews/PR252/assets/extra_tools_text_utilities_intro.md.KU1O3vgQ.js new file mode 100644 index 00000000..b2f575a4 --- /dev/null +++ b/previews/PR252/assets/extra_tools_text_utilities_intro.md.KU1O3vgQ.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Text Utilities","description":"","frontmatter":{},"headers":[],"relativePath":"extra_tools/text_utilities_intro.md","filePath":"extra_tools/text_utilities_intro.md","lastUpdated":null}'); +const _sfc_main = { name: "extra_tools/text_utilities_intro.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Text Utilities
Working with Generative AI (and in particular with the text modality), requires a lot of text manipulation. PromptingTools.jl provides a set of utilities to make this process easier and more efficient.
Highlights
The main functions to be aware of are
recursive_splitterto split the text into sentences and words (of a desired lengthmax_length)replace_wordsto mask some sensitive words in your text before sending it to AIwrap_stringfor wrapping the text into a desired length by adding newlines (eg, to fit some large text into your terminal width)length_longest_common_subsequenceto find the length of the longest common subsequence between two strings (eg, to compare the similarity between the context provided and generated text)distance_longest_common_subsequencea companion utility forlength_longest_common_subsequenceto find the normalized distance between two strings. Always returns a number between 0-1, where 0 means the strings are identical and 1 means they are completely different.
You can import them simply via:
using PromptingTools: recursive_splitter, replace_words, wrap_string, length_longest_common_subsequence, distance_longest_common_subsequenceThere are many more (especially in the AgentTools and RAGTools experimental modules)!
RAGTools module contains the following text utilities:
split_into_code_and_sentencesto split a string into code and sentencestokenizeto tokenize a string (eg, a sentence) into wordstrigramsto generate trigrams from a string (eg, a word)text_to_trigramsto generate trigrams from a larger string (ie, effectively wraps the three functions above)STOPWORDSa set of common stopwords (very brief)
Feel free to open an issue or ask in the #generative-ai channel in the JuliaLang Slack if you have a specific need.
References
recursive_splitter(text::String; separator::String=" ", max_length::Int=35000) -> Vector{String}Split a given string text into chunks of a specified maximum length max_length. This is particularly useful for splitting larger documents or texts into smaller segments, suitable for models or systems with smaller context windows.
There is a method for dispatching on multiple separators, recursive_splitter(text::String, separators::Vector{String}; max_length::Int=35000) -> Vector{String} that mimics the logic of Langchain's RecursiveCharacterTextSplitter.
Arguments
text::String: The text to be split.separator::String=" ": The separator used to split the text into minichunks. Defaults to a space character.max_length::Int=35000: The maximum length of each chunk. Defaults to 35,000 characters, which should fit within 16K context window.
Returns
Vector{String}: A vector of strings, each representing a chunk of the original text that is smaller than or equal to max_length.
Notes
The function ensures that each chunk is as close to
max_lengthas possible without exceeding it.If the
textis empty, the function returns an empty array.The
separatoris re-added to the text chunks after splitting, preserving the original structure of the text as closely as possible.
Examples
Splitting text with the default separator (" "):
text = "Hello world. How are you?"\nchunks = recursive_splitter(text; max_length=13)\nlength(chunks) # Output: 2Using a custom separator and custom max_length
text = "Hello,World," ^ 2900 # length 34900 chars\nrecursive_splitter(text; separator=",", max_length=10000) # for 4K context window\nlength(chunks[1]) # Output: 4recursive_splitter(text::AbstractString, separators::Vector{String}; max_length::Int=35000) -> Vector{String}Split a given string text into chunks recursively using a series of separators, with each chunk having a maximum length of max_length (if it's achievable given the separators provided). This function is useful for splitting large documents or texts into smaller segments that are more manageable for processing, particularly for models or systems with limited context windows.
It was previously known as split_by_length.
This is similar to Langchain's RecursiveCharacterTextSplitter. To achieve the same behavior, use separators=["\\n\\n", "\\n", " ", ""].
Arguments
text::AbstractString: The text to be split.separators::Vector{String}: An ordered list of separators used to split the text. The function iteratively applies these separators to split the text. Recommend to use["\\n\\n", ". ", "\\n", " "]max_length::Int: The maximum length of each chunk. Defaults to 35,000 characters. This length is considered after each iteration of splitting, ensuring chunks fit within specified constraints.
Returns
Vector{String}: A vector of strings, where each string is a chunk of the original text that is smaller than or equal to max_length.
Usage Tips
I tend to prefer splitting on sentences (
". ") before splitting on newline characters ("\\n") to preserve the structure of the text.What's the difference between
separators=["\\n"," ",""]andseparators=["\\n"," "]? The former will split down to character level (""), so it will always achieve themax_lengthbut it will split words (bad for context!) I prefer to instead set slightly smallermax_lengthbut not split words.
How It Works
The function processes the text iteratively with each separator in the provided order. It then measures the length of each chunk and splits it further if it exceeds the
max_length. If the chunks is "short enough", the subsequent separators are not applied to it.Each chunk is as close to
max_lengthas possible (unless we cannot split it any further, eg, if the splitters are "too big" / there are not enough of them)If the
textis empty, the function returns an empty array.Separators are re-added to the text chunks after splitting, preserving the original structure of the text as closely as possible. Apply
stripif you do not need them.The function provides
separatorsas the second argument to distinguish itself from its single-separator counterpart dispatch.
Examples
Splitting text using multiple separators:
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n"] # split by paragraphs, sentences, and newlines (not by words)\nchunks = recursive_splitter(text, separators, max_length=20)Splitting text using multiple separators - with splitting on words:
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n", " "] # split by paragraphs, sentences, and newlines, words\nchunks = recursive_splitter(text, separators, max_length=10)Using a single separator:
text = "Hello,World," ^ 2900 # length 34900 characters\nchunks = recursive_splitter(text, [","], max_length=10000)To achieve the same behavior as Langchain's RecursiveCharacterTextSplitter, use separators=["\\n\\n", "\\n", " ", ""].
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", "\\n", " ", ""]\nchunks = recursive_splitter(text, separators, max_length=10)replace_words(text::AbstractString, words::Vector{<:AbstractString}; replacement::AbstractString="ABC")Replace all occurrences of words in words with replacement in text. Useful to quickly remove specific names or entities from a text.
Arguments
text::AbstractString: The text to be processed.words::Vector{<:AbstractString}: A vector of words to be replaced.replacement::AbstractString="ABC": The replacement string to be used. Defaults to "ABC".
Example
text = "Disney is a great company"\nreplace_words(text, ["Disney", "Snow White", "Mickey Mouse"])\n# Output: "ABC is a great company"wrap_string(str::String,\n text_width::Int = 20;\n newline::Union{AbstractString, AbstractChar} = '')
Breaks a string into lines of a given text_width. Optionally, you can specify the newline character or string to use.
Example:
wrap_string("Certainly, here's a function in Julia that will wrap a string according to the specifications:", 10) |> printlength_longest_common_subsequence(itr1::AbstractString, itr2::AbstractString)Compute the length of the longest common subsequence between two string sequences (ie, the higher the number, the better the match).
Arguments
itr1: The first sequence, eg, a String.itr2: The second sequence, eg, a String.
Returns
The length of the longest common subsequence.
Examples
text1 = "abc-abc----"\ntext2 = "___ab_c__abc"\nlongest_common_subsequence(text1, text2)\n# Output: 6 (-> "abcabc")It can be used to fuzzy match strings and find the similarity between them (Tip: normalize the match)
commands = ["product recommendation", "emotions", "specific product advice", "checkout advice"]\nquery = "Which product can you recommend for me?"\nlet pos = argmax(length_longest_common_subsequence.(Ref(query), commands))\n dist = length_longest_common_subsequence(query, commands[pos])\n norm = dist / min(length(query), length(commands[pos]))\n @info "The closest command to the query: "$(query)" is: "$(commands[pos])" (distance: $(dist), normalized: $(norm))"\nendBut it might be easier to use directly the convenience wrapper distance_longest_common_subsequence!
\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/utils.jl#L252-L288)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.distance_longest_common_subsequence-extra_tools-text_utilities_intro' href='#PromptingTools.distance_longest_common_subsequence-extra_tools-text_utilities_intro'>#</a> <b><u>PromptingTools.distance_longest_common_subsequence</u></b> — <i>Function</i>.\n\n\n\n\n```julia\ndistance_longest_common_subsequence(\n input1::AbstractString, input2::AbstractString)\n\ndistance_longest_common_subsequence(\n input1::AbstractString, input2::AbstractVector{<:AbstractString})Measures distance between two strings using the length of the longest common subsequence (ie, the lower the number, the better the match). Perfect match is distance = 0.0
Convenience wrapper around length_longest_common_subsequence to normalize the distances to 0-1 range. There is a also a dispatch for comparing a string vs an array of strings.
Notes
Use
argminandminimumto find the position of the closest match and the distance, respectively.Matching with an empty string will always return 1.0 (worst match), even if the other string is empty as well (safety mechanism to avoid division by zero).
Arguments
input1::AbstractString: The first string to compare.input2::AbstractString: The second string to compare.
Example
You can also use it to find the closest context for some AI generated summary/story:
context = ["The enigmatic stranger vanished as swiftly as a wisp of smoke, leaving behind a trail of unanswered questions.",\n "Beneath the shimmering moonlight, the ocean whispered secrets only the stars could hear.",\n "The ancient tree stood as a silent guardian, its gnarled branches reaching for the heavens.",\n "The melody danced through the air, painting a vibrant tapestry of emotions.",\n "Time flowed like a relentless river, carrying away memories and leaving imprints in its wake."]\n\nstory = """\n Beneath the shimmering moonlight, the ocean whispered secrets only the stars could hear.\n\n Under the celestial tapestry, the vast ocean whispered its secrets to the indifferent stars. Each ripple, a murmured confidence, each wave, a whispered lament. The glittering celestial bodies listened in silent complicity, their enigmatic gaze reflecting the ocean's unspoken truths. The cosmic dance between the sea and the sky, a symphony of shared secrets, forever echoing in the ethereal expanse.\n """\n\ndist = distance_longest_common_subsequence(story, context)\n@info "The closest context to the query: "$(first(story,20))..." is: "$(context[argmin(dist)])" (distance: $(minimum(dist)))"', 20) + ])); +} +const text_utilities_intro = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + text_utilities_intro as default +}; diff --git a/previews/PR252/assets/extra_tools_text_utilities_intro.md.KU1O3vgQ.lean.js b/previews/PR252/assets/extra_tools_text_utilities_intro.md.KU1O3vgQ.lean.js new file mode 100644 index 00000000..b2f575a4 --- /dev/null +++ b/previews/PR252/assets/extra_tools_text_utilities_intro.md.KU1O3vgQ.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Text Utilities","description":"","frontmatter":{},"headers":[],"relativePath":"extra_tools/text_utilities_intro.md","filePath":"extra_tools/text_utilities_intro.md","lastUpdated":null}'); +const _sfc_main = { name: "extra_tools/text_utilities_intro.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Text Utilities
Working with Generative AI (and in particular with the text modality), requires a lot of text manipulation. PromptingTools.jl provides a set of utilities to make this process easier and more efficient.
Highlights
The main functions to be aware of are
recursive_splitterto split the text into sentences and words (of a desired lengthmax_length)replace_wordsto mask some sensitive words in your text before sending it to AIwrap_stringfor wrapping the text into a desired length by adding newlines (eg, to fit some large text into your terminal width)length_longest_common_subsequenceto find the length of the longest common subsequence between two strings (eg, to compare the similarity between the context provided and generated text)distance_longest_common_subsequencea companion utility forlength_longest_common_subsequenceto find the normalized distance between two strings. Always returns a number between 0-1, where 0 means the strings are identical and 1 means they are completely different.
You can import them simply via:
using PromptingTools: recursive_splitter, replace_words, wrap_string, length_longest_common_subsequence, distance_longest_common_subsequenceThere are many more (especially in the AgentTools and RAGTools experimental modules)!
RAGTools module contains the following text utilities:
split_into_code_and_sentencesto split a string into code and sentencestokenizeto tokenize a string (eg, a sentence) into wordstrigramsto generate trigrams from a string (eg, a word)text_to_trigramsto generate trigrams from a larger string (ie, effectively wraps the three functions above)STOPWORDSa set of common stopwords (very brief)
Feel free to open an issue or ask in the #generative-ai channel in the JuliaLang Slack if you have a specific need.
References
recursive_splitter(text::String; separator::String=" ", max_length::Int=35000) -> Vector{String}Split a given string text into chunks of a specified maximum length max_length. This is particularly useful for splitting larger documents or texts into smaller segments, suitable for models or systems with smaller context windows.
There is a method for dispatching on multiple separators, recursive_splitter(text::String, separators::Vector{String}; max_length::Int=35000) -> Vector{String} that mimics the logic of Langchain's RecursiveCharacterTextSplitter.
Arguments
text::String: The text to be split.separator::String=" ": The separator used to split the text into minichunks. Defaults to a space character.max_length::Int=35000: The maximum length of each chunk. Defaults to 35,000 characters, which should fit within 16K context window.
Returns
Vector{String}: A vector of strings, each representing a chunk of the original text that is smaller than or equal to max_length.
Notes
The function ensures that each chunk is as close to
max_lengthas possible without exceeding it.If the
textis empty, the function returns an empty array.The
separatoris re-added to the text chunks after splitting, preserving the original structure of the text as closely as possible.
Examples
Splitting text with the default separator (" "):
text = "Hello world. How are you?"\nchunks = recursive_splitter(text; max_length=13)\nlength(chunks) # Output: 2Using a custom separator and custom max_length
text = "Hello,World," ^ 2900 # length 34900 chars\nrecursive_splitter(text; separator=",", max_length=10000) # for 4K context window\nlength(chunks[1]) # Output: 4recursive_splitter(text::AbstractString, separators::Vector{String}; max_length::Int=35000) -> Vector{String}Split a given string text into chunks recursively using a series of separators, with each chunk having a maximum length of max_length (if it's achievable given the separators provided). This function is useful for splitting large documents or texts into smaller segments that are more manageable for processing, particularly for models or systems with limited context windows.
It was previously known as split_by_length.
This is similar to Langchain's RecursiveCharacterTextSplitter. To achieve the same behavior, use separators=["\\n\\n", "\\n", " ", ""].
Arguments
text::AbstractString: The text to be split.separators::Vector{String}: An ordered list of separators used to split the text. The function iteratively applies these separators to split the text. Recommend to use["\\n\\n", ". ", "\\n", " "]max_length::Int: The maximum length of each chunk. Defaults to 35,000 characters. This length is considered after each iteration of splitting, ensuring chunks fit within specified constraints.
Returns
Vector{String}: A vector of strings, where each string is a chunk of the original text that is smaller than or equal to max_length.
Usage Tips
I tend to prefer splitting on sentences (
". ") before splitting on newline characters ("\\n") to preserve the structure of the text.What's the difference between
separators=["\\n"," ",""]andseparators=["\\n"," "]? The former will split down to character level (""), so it will always achieve themax_lengthbut it will split words (bad for context!) I prefer to instead set slightly smallermax_lengthbut not split words.
How It Works
The function processes the text iteratively with each separator in the provided order. It then measures the length of each chunk and splits it further if it exceeds the
max_length. If the chunks is "short enough", the subsequent separators are not applied to it.Each chunk is as close to
max_lengthas possible (unless we cannot split it any further, eg, if the splitters are "too big" / there are not enough of them)If the
textis empty, the function returns an empty array.Separators are re-added to the text chunks after splitting, preserving the original structure of the text as closely as possible. Apply
stripif you do not need them.The function provides
separatorsas the second argument to distinguish itself from its single-separator counterpart dispatch.
Examples
Splitting text using multiple separators:
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n"] # split by paragraphs, sentences, and newlines (not by words)\nchunks = recursive_splitter(text, separators, max_length=20)Splitting text using multiple separators - with splitting on words:
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n", " "] # split by paragraphs, sentences, and newlines, words\nchunks = recursive_splitter(text, separators, max_length=10)Using a single separator:
text = "Hello,World," ^ 2900 # length 34900 characters\nchunks = recursive_splitter(text, [","], max_length=10000)To achieve the same behavior as Langchain's RecursiveCharacterTextSplitter, use separators=["\\n\\n", "\\n", " ", ""].
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", "\\n", " ", ""]\nchunks = recursive_splitter(text, separators, max_length=10)replace_words(text::AbstractString, words::Vector{<:AbstractString}; replacement::AbstractString="ABC")Replace all occurrences of words in words with replacement in text. Useful to quickly remove specific names or entities from a text.
Arguments
text::AbstractString: The text to be processed.words::Vector{<:AbstractString}: A vector of words to be replaced.replacement::AbstractString="ABC": The replacement string to be used. Defaults to "ABC".
Example
text = "Disney is a great company"\nreplace_words(text, ["Disney", "Snow White", "Mickey Mouse"])\n# Output: "ABC is a great company"wrap_string(str::String,\n text_width::Int = 20;\n newline::Union{AbstractString, AbstractChar} = '')
Breaks a string into lines of a given text_width. Optionally, you can specify the newline character or string to use.
Example:
wrap_string("Certainly, here's a function in Julia that will wrap a string according to the specifications:", 10) |> printlength_longest_common_subsequence(itr1::AbstractString, itr2::AbstractString)Compute the length of the longest common subsequence between two string sequences (ie, the higher the number, the better the match).
Arguments
itr1: The first sequence, eg, a String.itr2: The second sequence, eg, a String.
Returns
The length of the longest common subsequence.
Examples
text1 = "abc-abc----"\ntext2 = "___ab_c__abc"\nlongest_common_subsequence(text1, text2)\n# Output: 6 (-> "abcabc")It can be used to fuzzy match strings and find the similarity between them (Tip: normalize the match)
commands = ["product recommendation", "emotions", "specific product advice", "checkout advice"]\nquery = "Which product can you recommend for me?"\nlet pos = argmax(length_longest_common_subsequence.(Ref(query), commands))\n dist = length_longest_common_subsequence(query, commands[pos])\n norm = dist / min(length(query), length(commands[pos]))\n @info "The closest command to the query: "$(query)" is: "$(commands[pos])" (distance: $(dist), normalized: $(norm))"\nendBut it might be easier to use directly the convenience wrapper distance_longest_common_subsequence!
\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/utils.jl#L252-L288)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.distance_longest_common_subsequence-extra_tools-text_utilities_intro' href='#PromptingTools.distance_longest_common_subsequence-extra_tools-text_utilities_intro'>#</a> <b><u>PromptingTools.distance_longest_common_subsequence</u></b> — <i>Function</i>.\n\n\n\n\n```julia\ndistance_longest_common_subsequence(\n input1::AbstractString, input2::AbstractString)\n\ndistance_longest_common_subsequence(\n input1::AbstractString, input2::AbstractVector{<:AbstractString})Measures distance between two strings using the length of the longest common subsequence (ie, the lower the number, the better the match). Perfect match is distance = 0.0
Convenience wrapper around length_longest_common_subsequence to normalize the distances to 0-1 range. There is a also a dispatch for comparing a string vs an array of strings.
Notes
Use
argminandminimumto find the position of the closest match and the distance, respectively.Matching with an empty string will always return 1.0 (worst match), even if the other string is empty as well (safety mechanism to avoid division by zero).
Arguments
input1::AbstractString: The first string to compare.input2::AbstractString: The second string to compare.
Example
You can also use it to find the closest context for some AI generated summary/story:
context = ["The enigmatic stranger vanished as swiftly as a wisp of smoke, leaving behind a trail of unanswered questions.",\n "Beneath the shimmering moonlight, the ocean whispered secrets only the stars could hear.",\n "The ancient tree stood as a silent guardian, its gnarled branches reaching for the heavens.",\n "The melody danced through the air, painting a vibrant tapestry of emotions.",\n "Time flowed like a relentless river, carrying away memories and leaving imprints in its wake."]\n\nstory = """\n Beneath the shimmering moonlight, the ocean whispered secrets only the stars could hear.\n\n Under the celestial tapestry, the vast ocean whispered its secrets to the indifferent stars. Each ripple, a murmured confidence, each wave, a whispered lament. The glittering celestial bodies listened in silent complicity, their enigmatic gaze reflecting the ocean's unspoken truths. The cosmic dance between the sea and the sky, a symphony of shared secrets, forever echoing in the ethereal expanse.\n """\n\ndist = distance_longest_common_subsequence(story, context)\n@info "The closest context to the query: "$(first(story,20))..." is: "$(context[argmin(dist)])" (distance: $(minimum(dist)))"', 20) + ])); +} +const text_utilities_intro = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + text_utilities_intro as default +}; diff --git a/previews/PR252/assets/frequently_asked_questions.md.CKWNizFt.js b/previews/PR252/assets/frequently_asked_questions.md.CKWNizFt.js new file mode 100644 index 00000000..218c2c62 --- /dev/null +++ b/previews/PR252/assets/frequently_asked_questions.md.CKWNizFt.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Frequently Asked Questions","description":"","frontmatter":{},"headers":[],"relativePath":"frequently_asked_questions.md","filePath":"frequently_asked_questions.md","lastUpdated":null}'); +const _sfc_main = { name: "frequently_asked_questions.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Frequently Asked Questions
Why OpenAI
OpenAI's models are at the forefront of AI research and provide robust, state-of-the-art capabilities for many tasks.
There will be situations not or cannot use it (eg, privacy, cost, etc.). In that case, you can use local models (eg, Ollama) or other APIs (eg, Anthropic).
Note: To get started with Ollama.ai, see the Setup Guide for Ollama section below.
What if I cannot access OpenAI?
There are many alternatives:
Other APIs: MistralAI, Anthropic, Google, Together, Fireworks, Voyager (the latter ones tend to give free credits upon joining!)
Locally-hosted models: Llama.cpp/Llama.jl, Ollama, vLLM (see the examples and the corresponding docs)
Data Privacy and OpenAI
At the time of writing, OpenAI does NOT use the API calls for training their models.
API
OpenAI does not use data submitted to and generated by our API to train OpenAI models or improve OpenAI’s service offering. In order to support the continuous improvement of our models, you can fill out this form to opt-in to share your data with us. – How your data is used to improve our models
You can always double-check the latest information on the OpenAI's How we use your data page.
Resources:
Creating OpenAI API Key
You can get your API key from OpenAI by signing up for an account and accessing the API section of the OpenAI website.
Create an account with OpenAI
Go to API Key page
Click on “Create new secret key”
!!! Do not share it with anyone and do NOT save it to any files that get synced online.
Resources:
Pro tip: Always set the spending limits!
Getting an error "ArgumentError: api_key cannot be empty" despite having set OPENAI_API_KEY? {#Getting-an-error-"ArgumentError:-apikey-cannot-be-empty"-despite-having-set-OPENAIAPI_KEY?}
Quick fix: just provide kwarg api_key with your key to the aigenerate function (and other ai* functions).
This error is thrown when the OpenAI API key is not available in 1) local preferences or 2) environment variables (ENV["OPENAI_API_KEY"]).
First, check if you can access the key by running ENV["OPENAI_API_KEY"] in the Julia REPL. If it returns nothing, the key is not set.
If the key is set, but you still get the error, there was a rare bug in earlier versions where if you first precompiled PromptingTools without the API key, it would remember it and "compile away" the get(ENV,...) function call. If you're experiencing this bug on the latest version of PromptingTools, please open an issue on GitHub.
The solution is to force a new precompilation, so you can do any of the below:
Force precompilation (run
Pkg.precompile()in the Julia REPL)Update the PromptingTools package (runs precompilation automatically)
Delete your compiled cache in
.juliaDEPOT (usually.julia/compiled/v1.10/PromptingTools). You can do it manually in the file explorer or via Julia REPL:rm("~/.julia/compiled/v1.10/PromptingTools", recursive=true, force=true)
Getting an error "Rate limit exceeded" from OpenAI?
Have you opened a new account recently? It is quite likely that you've exceeded the free tier limits.
OpenAI has a rate limit on the number of requests and the number of tokens you can make in a given period. If you exceed either of these, you will receive a "Rate limit exceeded" error. "Free tier" (ie, before you pay the first 5 USD) has very low limits, eg, maximum of 3 requests per minute. See the OpenAI Rate Limits for more information.
If you look at the HTTP response headers in the error, you can see the limits remaining and how long until it resets, eg, x-ratelimit-remaining-* and x-ratelimit-reset-*.
If you want to avoid this error, you have two options:
Put a simple
sleep(x)after every request, wherexis calculated so that the number of your requests stays below the limit.Use
ntaskskeyword argument inasyncmapto limit the number of concurrent requests. Eg, let's assume you want to process 100x c. 10,000 tokens, but your tier limit is only 60,000 tokens per minute. If we know that one request takes c. 10 seconds, it means that withntasks=1we would send 6 requests per minute, which already maxes out our limit. If we setntasks=2, we could process 12 requests per minute, so we would need our limit to be 120,000 tokens per minute.
# simple asyncmap loop with 2 concurrent requests; otherwise, same syntax as `map`\nasyncmap(my_prompts; ntasks=2) do prompt\n aigenerate(prompt)\nendGetting the error "429 Too Many Requests"?
Assuming you have not just sent hundreds of requests, this error might be related to insufficient "credits" in your account balance.
See the error message. If it says "You exceeded your current quota, please check your plan and billing details. For more information on this error, read the docs: https://platform.openai.com/docs/guides/error-codes/api-errors", you'll need to re-charge your account balance. Visit Billing overview.
Please note that, unlike ChatGPT, OpenAI API is NOT free. However, individual requests are extremely cheap (eg, tenth of a cent), so if you charge 5 , it might last you up to hundreds of requests (depending on the models and prompts).
Setting OpenAI Spending Limits
OpenAI allows you to set spending limits directly on your account dashboard to prevent unexpected costs.
Go to OpenAI Billing
Set Soft Limit (you’ll receive a notification) and Hard Limit (API will stop working not to spend more money)
A good start might be a soft limit of c.$5 and a hard limit of c.$10 - you can always increase it later in the month.
Resources:
How much does it cost? Is it worth paying for?
If you use a local model (eg, with Ollama), it's free. If you use any commercial APIs (eg, OpenAI), you will likely pay per "token" (a sub-word unit).
For example, a simple request with a simple question and 1 sentence response in return (”Is statement XYZ a positive comment”) will cost you ~0.0001 (ie, one-hundredth of a cent)
Is it worth paying for?
GenAI is a way to buy time! You can pay cents to save tens of minutes every day.
Continuing the example above, imagine you have a table with 200 comments. Now, you can parse each one of them with an LLM for the features/checks you need. Assuming the price per call was 0.0001 , you'd pay 2 cents for the job and save 30-60 minutes of your time!
Resources:
How to try new OpenAI models if I'm not Tier 5 customer?
As of September 2024, you cannot access the new o1 models via API unless you're a Tier 5 customer.
Fortunately, you can use OpenRouter to access these new models.
Get your API key from OpenRouter
Add some minimum Credits to the account (eg, 5 ).
Set it as an environment variable (or use local preferences):
ENV["OPENROUTER_API_KEY"] = "<your key>"Use the model aliases with
orprefix, eg,oro1for o1-preview ororo1mfor o1-mini.
Example:
# Let's use o1-preview model hosted on OpenRouter ("or" prefix)\nmsg = aigenerate("What is the meaning of life?"; model="oro1")Note: There are some quirks for the o1 models. For example, the new o1 series does NOT support SystemMessage yet, so OpenRouter does some tricks (likely converting them to normal user messages). To be in control of this behavior and have comparable behavior to the native OpenAI API, you can use kwarg no_system_message=true in aigenerate to ensure OpenRouter does not do any tricks.
Example:
# Let's use o1-mini and disable adding automatic system message\nmsg = aigenerate("What is the meaning of life?"; model="oro1m", no_system_message=true)Configuring the Environment Variable for API Key
This is a guide for OpenAI's API key, but it works for any other API key you might need (eg, MISTRAL_API_KEY for MistralAI API).
To use the OpenAI API with PromptingTools.jl, set your API key as an environment variable:
ENV["OPENAI_API_KEY"] = "your-api-key"As a one-off, you can:
set it in the terminal before launching Julia:
export OPENAI_API_KEY = <your key>set it in your
setup.jl(make sure not to commit it to GitHub!)
Make sure to start Julia from the same terminal window where you set the variable. Easy check in Julia, run ENV["OPENAI_API_KEY"] and you should see your key!
A better way:
On a Mac, add the configuration line to your terminal's configuration file (eg,
~/.zshrc). It will get automatically loaded every time you launch the terminalOn Windows, set it as a system variable in "Environment Variables" settings (see the Resources)
Resources:
Setting the API Key via Preferences.jl
You can also set the API key in LocalPreferences.toml, so it persists across sessions and projects.
Use: PromptingTools.set_preferences!("OPENAI_API_KEY"=>"your-api-key")
To double-check, run PromptingTools.get_preferences("OPENAI_API_KEY") and you should see your key!
See more detail in the ?PromptingTools.PREFERENCES docstring.
Understanding the API Keyword Arguments in aigenerate (api_kwargs)
See OpenAI API reference for more information.
Instant Access from Anywhere
For easy access from anywhere, add PromptingTools into your startup.jl (can be found in ~/.julia/config/startup.jl).
Add the following snippet:
using PromptingTools\nconst PT = PromptingTools # to access unexported functions and typesNow, you can just use ai"Help me do X to achieve Y" from any REPL session!
Open Source Alternatives
The ethos of PromptingTools.jl is to allow you to use whatever model you want, which includes Open Source LLMs. The most popular and easiest to setup is Ollama.ai - see below for more information.
Setup Guide for Ollama
Ollama runs a background service hosting LLMs that you can access via a simple API. It's especially useful when you're working with some sensitive data that should not be sent anywhere.
Installation is very easy, just download the latest version here.
Once you've installed it, just launch the app and you're ready to go!
To check if it's running, go to your browser and open 127.0.0.1:11434. You should see the message "Ollama is running". Alternatively, you can run ollama serve in your terminal and you'll get a message that it's already running.
There are many models available in Ollama Library, including Llama2, CodeLlama, SQLCoder, or my personal favorite openhermes2.5-mistral.
Download new models with ollama pull <model_name> (eg, ollama pull openhermes2.5-mistral).
Show currently available models with ollama list.
See Ollama.ai for more information.
Changing the Default Model or Schema
If you tend to use non-default options, it can get tedious to specify PT.* every time.
There are three ways how you can customize your workflows (especially when you use Ollama or other local models):
Import the functions/types you need explicitly at the top (eg,
using PromptingTools: OllamaSchema)Register your model and its associated schema (
PT.register_model!(; name="123", schema=PT.OllamaSchema())). You won't have to specify the schema anymore only the model name. See Working with Ollama for more information.Override your default model (
PT.MODEL_CHAT) and schema (PT.PROMPT_SCHEMA). It can be done persistently with Preferences, eg,PT.set_preferences!("PROMPT_SCHEMA" => "OllamaSchema", "MODEL_CHAT"=>"llama2").
Using Custom API Providers like Azure or Databricks
Several providers are directly supported (eg, Databricks), check the available prompt schemas (eg, subtypes(PT.AbstractOpenAISchema)).
If you need a custom URL or a few keyword parameters, refer to the implementation of DatabricksOpenAISchema. You effectively need to create your own prompt schema (struct MySchema <: PT.AbstractOpenAISchema) and override the OpenAI.jl behavior. The easiest way is to provide your custom method for OpenAI.create_chat and customize the url, api_key, and other kwargs fields. You can follow the implementation of create_chat for DatabricksOpenAISchema in src/llm_openAI.jl.
Once your schema is ready, you can register the necessary models via PT.register_model!(; name="myschema", schema=MySchema()). You can also add aliases for easier access (eg, PT.MODEL_ALIASES["mymodel"] = "my-model-with-really-long-name").
If you would like to use some heavily customized API, eg, your company's internal LLM proxy (to change headers, URL paths, etc.), refer to the example examples/adding_custom_API.jl in the repo.
How to have Multi-turn Conversations?
Let's say you would like to respond back to a model's response. How to do it?
- With
ai""macro
The simplest way if you used ai"" macro, is to send a reply with the ai!"" macro. It will use the last response as the conversation.
ai"Hi! I'm John"\n\nai!"What's my name?"\n# Return: "Your name is John."- With
aigeneratefunction
You can use the conversation keyword argument to pass the previous conversation (in all ai* functions). It will prepend the past conversation before sending the new request to the model.
To get the conversation, set return_all=true and store the whole conversation thread (not just the last message) in a variable. Then, use it as a keyword argument in the next call.
conversation = aigenerate("Hi! I'm John"; return_all=true)\n@info last(conversation) # display the response\n\n# follow-up (notice that we provide past messages as conversation kwarg\nconversation = aigenerate("What's my name?"; return_all=true, conversation)\n\n## [ Info: Tokens: 50 @ Cost: $0.0 in 1.0 seconds\n## 5-element Vector{PromptingTools.AbstractMessage}:\n## PromptingTools.SystemMessage("Act as a helpful AI assistant")\n## PromptingTools.UserMessage("Hi! I'm John")\n## AIMessage("Hello John! How can I assist you today?")\n## PromptingTools.UserMessage("What's my name?")\n## AIMessage("Your name is John.")Notice that the last message is the response to the second request, but with return_all=true we can see the whole conversation from the beginning.
How to have typed responses?
Our responses are always in AbstractMessage types to ensure we can also handle downstream processing, error handling, and self-healing code (see airetry!).
A good use case for a typed response is when you have a complicated control flow and would like to group and handle certain outcomes differently. You can easily do it as an extra step after the response is received.
Trivially, we can use aiclassifier for Bool statements, eg,
# We can do either\nmybool = tryparse(Bool, aiclassify("Is two plus two four?")) isa Bool # true\n\n# or simply check equality\nmsg = aiclassify("Is two plus two four?") # true\nmybool = msg.content == "true"Now a more complicated example with multiple categories mapping to an enum:
choices = [("A", "any animal or creature"), ("P", "for any plant or tree"), ("O", "for everything else")]\n\n# Set up the return types we want\n@enum Categories A P O\nstring_to_category = Dict("A" => A, "P" => P,"O" => O)\n\n# Run an example\ninput = "spider"\nmsg = aiclassify(:InputClassifier; choices, input)\n\nmytype = string_to_category[msg.content] # A (for animal)How does it work? aiclassify guarantees to output one of our choices (and it handles some of the common quirks)!
How would we achieve the same with aigenerate and arbitrary struct? We need to use the "lazy" AIGenerate struct and airetry! to ensure we get the response and then we can process it further.
AIGenerate has two fields you should know about:
conversation- eg, the vector of "messages" in the current conversation (same as what you get fromaigeneratewithreturn_all=true)success- a boolean flag if the request was successful AND if it passed any subsequentairetry!calls
Let's mimic a case where our "program" should return one of three types: SmallInt, LargeInt, FailedResponse.
We first need to define our custom types:
\n# not needed, just to show a fully typed example\nabstract type MyAbstractResponse end\nstruct SmallInt <: MyAbstractResponse\n number::Int\nend\nstruct LargeInt <: MyAbstractResponse\n number::Int\nend\nstruct FailedResponse <: MyAbstractResponse\n content::String\nendLet's define our "program" as a function to be cleaner. Notice that we use AIGenerate and airetry! to ensure we get the response and then we can process it further.
using PromptingTools.Experimental.AgentTools\n\nfunction give_me_number(prompt::String)::MyAbstractResponse\n # Generate the response\n response = AIGenerate(prompt; config=RetryConfig(;max_retries=2)) |> run!\n\n # Check if it's parseable as Int, if not, send back to be fixed\n # syntax: airetry!(CONDITION-TO-CHECK, <response object>, FEEDBACK-TO-MODEL)\n airetry!(x->tryparse(Int,last_output(x))|>!isnothing, response, "Wrong output format! Answer with digits and nothing else. The number is:")\n\n if response.success != true\n ## we failed to generate a parseable integer\n return FailedResponse("I failed to get the response. Last output: $(last_output(response))")\n end\n number = tryparse(Int,last_output(response))\n return number < 1000 ? SmallInt(number) : LargeInt(number)\nend\n\ngive_me_number("How many car seats are in Porsche 911T?")\n## [ Info: Condition not met. Retrying...\n## [ Info: Condition not met. Retrying...\n## SmallInt(2)We ultimately received our custom type SmallInt with the number of car seats in the Porsche 911T (I hope it's correct!).
If you want to access the full conversation history (all the attempts and feedback), simply output the response object and explore response.conversation.
How to quickly create a prompt template?
Many times, you will want to create a prompt template that you can reuse with different inputs (eg, to create templates for AIHelpMe or LLMTextAnalysis).
Previously, you would have to create a vector of SystemMessage and UserMessage objects and then save it to a disk and reload. Now, you can use the create_template function to do it for you. It's designed for quick prototyping, so it skips the serialization step and loads it directly into the template store (ie, you can use it like any other templates - try aitemplates() search).
The syntax is simple: create_template(;user=<user prompt>, system=<system prompt>, load_as=<template name>)
When called it creates a vector of messages, which you can use directly in the ai* functions. If you provide load_as, it will load the template in the template store (under the load_as name).
Let's generate a quick template for a simple conversation (only one placeholder: name)
# first system message, then user message (or use kwargs)\ntpl=PT.create_template("You must speak like a pirate", "Say hi to {{name}}"; load_as="GreatingPirate")\n\n## 2-element Vector{PromptingTools.AbstractChatMessage}:\n## PromptingTools.SystemMessage("You must speak like a pirate")\n## PromptingTools.UserMessage("Say hi to {{name}}")You can immediately use this template in ai* functions:
aigenerate(tpl; name="Jack Sparrow")\n# Output: AIMessage("Arr, me hearty! Best be sending me regards to Captain Jack Sparrow on the salty seas! May his compass always point true to the nearest treasure trove. Yarrr!")Since we provided load_as, it's also registered in the template store:
aitemplates("pirate")\n\n## 1-element Vector{AITemplateMetadata}:\n## PromptingTools.AITemplateMetadata\n## name: Symbol GreatingPirate\n## description: String ""\n## version: String "1.0"\n## wordcount: Int64 46\n## variables: Array{Symbol}((1,))\n## system_preview: String "You must speak like a pirate"\n## user_preview: String "Say hi to {{name}}"\n## source: String ""So you can use it like any other template:
aigenerate(:GreatingPirate; name="Jack Sparrow")\n# Output: AIMessage("Arr, me hearty! Best be sending me regards to Captain Jack Sparrow on the salty seas! May his compass always point true to the nearest treasure trove. Yarrr!")If you want to save it in your project folder:
PT.save_template("templates/GreatingPirate.json", tpl; version="1.0") # optionally, add descriptionIt will be saved and accessed under its basename, ie, GreatingPirate (same as load_as keyword argument).
Note: If you make any changes to the templates on the disk/in a folder, you need to explicitly reload all templates again!
If you are using the main PromptingTools templates, you can simply call PT.load_templates!(). If you have a project folder with your templates, you want to add it first:
PT.load_templates!("templates")After the first run, we will remember the folder and you can simply call PT.load_templates!() to reload all the templates in the future!
Do we have a RecursiveCharacterTextSplitter like Langchain?
Yes, we do! Look for utility recursive_spliter (previously known as split_by_length). See its docstring for more information.
For reference, Langchain's RecursiveCharacterTextSplitter uses the following setting: separators = ["\\n\\n", "\\n", " ", ""].
I'd recommend using the following instead: separators = ["\\\\n\\\\n", ". ", "\\\\n", " "] (ie, it does not split words, which tends to be unnecessary and quite damaging to the chunk quality).
Example:
using PromptingTools: recursive_splitter\n\ntext = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n", " "] # split by paragraphs, sentences, and newlines, and words\nchunks = recursive_splitter(text, separators, max_length=10)How would I fine-tune a model?
Fine-tuning is a powerful technique to adapt a model to your specific use case (mostly the format/syntax/task). It requires a dataset of examples, which you can now easily generate with PromptingTools.jl!
You can save any conversation (vector of messages) to a file with
PT.save_conversation("filename.json", conversation).Once the finetuning time comes, create a bundle of ShareGPT-formatted conversations (common finetuning format) in a single
.jsonlfile. UsePT.save_conversations("dataset.jsonl", [conversation1, conversation2, ...])(notice that plural "conversationS" in the function name).
For an example of an end-to-end finetuning process, check out our sister project JuliaLLMLeaderboard Finetuning experiment. It shows the process of finetuning for half a dollar with JarvisLabs.ai and Axolotl.
Can I see how my prompt is rendered / what is sent to the API?
Yes, there are two ways.
"dry run", where the
ai*function will return the prompt rendered in the style of the selected API provider"partial render", for provider-agnostic purposes, you can run only the first step of the rendering pipeline to see the messages that will be sent (but formatted as
SystemMessageandUserMessage), which is easy to read and work withDry Run
Add kwargs dry_run and return_all to see what could have been sent to the API to your ai* functions (without return_all there is nothing to show you).
Example for OpenAI:
dry_conv = aigenerate(:BlankSystemUser; system = "I exist", user = "say hi",\n model = "lngpt3t", return_all = true, dry_run = true)2-element Vector{Dict{String, Any}}:\n Dict("role" => "system", "content" => "I exist")\n Dict("role" => "user", "content" => "say hi")- Partial Render
Personally, I prefer to see the pretty formatting of PromptingTools *Messages. To see what will be sent to the model, you can render only the first stage of the rendering pipeline with schema NoSchema() (it merely does the variable replacements and creates the necessary messages). It's shared by all the schema/providers.
PT.render(PT.NoSchema(), "say hi, {{name}}"; name="John")2-element Vector{PromptingTools.AbstractMessage}:\n PromptingTools.SystemMessage("Act as a helpful AI assistant")\n PromptingTools.UserMessage("say hi, John")What about the prompt templates? Prompt templates have an extra pre-rendering step that expands the symbolic :name (understood by PromptingTools as a reference to AITemplate(:name)) into a vector of Messages.
# expand the template into messages\ntpl = PT.render(AITemplate(:BlankSystemUser))\nPT.render(PT.NoSchema(), tpl; system = "I exist", user = "say hi")\n# replace any variables, etc.2-element Vector{PromptingTools.AbstractMessage}:\n PromptingTools.SystemMessage("I exist")\n PromptingTools.UserMessage("say hi")For more information about the rendering pipeline and examples refer to Walkthrough Example for aigenerate.
Automatic Logging / Tracing
If you would like to automatically capture metadata about your conversations, you can use the TracerSchema. It automatically captures the necessary metadata such as model, task (parent_id), current thread (thread_id), API kwargs used and any prompt templates (and its versions).
using PromptingTools: TracerSchema, OpenAISchema\n\nwrap_schema = TracerSchema(OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model="gpt-4")\n# output type should be TracerMessage\nmsg isa TracerMessageYou can work with the message like any other message (properties of the inner object are overloaded). You can extract the original message with unwrap:
unwrap(msg) isa StringYou can extract the metadata with meta:
meta(msg) isa DictIf you would like to automatically save the conversations, you can use the SaverSchema. It automatically serializes the conversation to a file in the directory specified by the environment variable LOG_DIR.
using PromptingTools: SaverSchema\n\nwrap_schema = SaverSchema(OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model="gpt-4")See LOG_DIR location to find the serialized conversation.
You can also compose multiple tracing schemas. For example, you can capture metadata with TracerSchema and then save everything automatically with SaverSchema:
using PromptingTools: TracerSchema, SaverSchema, OpenAISchema\n\nwrap_schema = OpenAISchema() |> TracerSchema |> SaverSchema\nconv = aigenerate(wrap_schema,:BlankSystemUser; system="You're a French-speaking assistant!",\n user="Say hi!"; model="gpt-4", api_kwargs=(;temperature=0.1), return_all=true)conv is a vector of tracing messages that will be saved to a JSON together with metadata about the template and api_kwargs.
If you would like to enable this behavior automatically, you can register your favorite model (or re-register existing models) with the "wrapped" schema:
PT.register_model!(; name= "gpt-3.5-turbo", schema=OpenAISchema() |> TracerSchema |> SaverSchema)Frequently Asked Questions
Why OpenAI
OpenAI's models are at the forefront of AI research and provide robust, state-of-the-art capabilities for many tasks.
There will be situations not or cannot use it (eg, privacy, cost, etc.). In that case, you can use local models (eg, Ollama) or other APIs (eg, Anthropic).
Note: To get started with Ollama.ai, see the Setup Guide for Ollama section below.
What if I cannot access OpenAI?
There are many alternatives:
Other APIs: MistralAI, Anthropic, Google, Together, Fireworks, Voyager (the latter ones tend to give free credits upon joining!)
Locally-hosted models: Llama.cpp/Llama.jl, Ollama, vLLM (see the examples and the corresponding docs)
Data Privacy and OpenAI
At the time of writing, OpenAI does NOT use the API calls for training their models.
API
OpenAI does not use data submitted to and generated by our API to train OpenAI models or improve OpenAI’s service offering. In order to support the continuous improvement of our models, you can fill out this form to opt-in to share your data with us. – How your data is used to improve our models
You can always double-check the latest information on the OpenAI's How we use your data page.
Resources:
Creating OpenAI API Key
You can get your API key from OpenAI by signing up for an account and accessing the API section of the OpenAI website.
Create an account with OpenAI
Go to API Key page
Click on “Create new secret key”
!!! Do not share it with anyone and do NOT save it to any files that get synced online.
Resources:
Pro tip: Always set the spending limits!
Getting an error "ArgumentError: api_key cannot be empty" despite having set OPENAI_API_KEY? {#Getting-an-error-"ArgumentError:-apikey-cannot-be-empty"-despite-having-set-OPENAIAPI_KEY?}
Quick fix: just provide kwarg api_key with your key to the aigenerate function (and other ai* functions).
This error is thrown when the OpenAI API key is not available in 1) local preferences or 2) environment variables (ENV["OPENAI_API_KEY"]).
First, check if you can access the key by running ENV["OPENAI_API_KEY"] in the Julia REPL. If it returns nothing, the key is not set.
If the key is set, but you still get the error, there was a rare bug in earlier versions where if you first precompiled PromptingTools without the API key, it would remember it and "compile away" the get(ENV,...) function call. If you're experiencing this bug on the latest version of PromptingTools, please open an issue on GitHub.
The solution is to force a new precompilation, so you can do any of the below:
Force precompilation (run
Pkg.precompile()in the Julia REPL)Update the PromptingTools package (runs precompilation automatically)
Delete your compiled cache in
.juliaDEPOT (usually.julia/compiled/v1.10/PromptingTools). You can do it manually in the file explorer or via Julia REPL:rm("~/.julia/compiled/v1.10/PromptingTools", recursive=true, force=true)
Getting an error "Rate limit exceeded" from OpenAI?
Have you opened a new account recently? It is quite likely that you've exceeded the free tier limits.
OpenAI has a rate limit on the number of requests and the number of tokens you can make in a given period. If you exceed either of these, you will receive a "Rate limit exceeded" error. "Free tier" (ie, before you pay the first 5 USD) has very low limits, eg, maximum of 3 requests per minute. See the OpenAI Rate Limits for more information.
If you look at the HTTP response headers in the error, you can see the limits remaining and how long until it resets, eg, x-ratelimit-remaining-* and x-ratelimit-reset-*.
If you want to avoid this error, you have two options:
Put a simple
sleep(x)after every request, wherexis calculated so that the number of your requests stays below the limit.Use
ntaskskeyword argument inasyncmapto limit the number of concurrent requests. Eg, let's assume you want to process 100x c. 10,000 tokens, but your tier limit is only 60,000 tokens per minute. If we know that one request takes c. 10 seconds, it means that withntasks=1we would send 6 requests per minute, which already maxes out our limit. If we setntasks=2, we could process 12 requests per minute, so we would need our limit to be 120,000 tokens per minute.
# simple asyncmap loop with 2 concurrent requests; otherwise, same syntax as `map`\nasyncmap(my_prompts; ntasks=2) do prompt\n aigenerate(prompt)\nendGetting the error "429 Too Many Requests"?
Assuming you have not just sent hundreds of requests, this error might be related to insufficient "credits" in your account balance.
See the error message. If it says "You exceeded your current quota, please check your plan and billing details. For more information on this error, read the docs: https://platform.openai.com/docs/guides/error-codes/api-errors", you'll need to re-charge your account balance. Visit Billing overview.
Please note that, unlike ChatGPT, OpenAI API is NOT free. However, individual requests are extremely cheap (eg, tenth of a cent), so if you charge 5 , it might last you up to hundreds of requests (depending on the models and prompts).
Setting OpenAI Spending Limits
OpenAI allows you to set spending limits directly on your account dashboard to prevent unexpected costs.
Go to OpenAI Billing
Set Soft Limit (you’ll receive a notification) and Hard Limit (API will stop working not to spend more money)
A good start might be a soft limit of c.$5 and a hard limit of c.$10 - you can always increase it later in the month.
Resources:
How much does it cost? Is it worth paying for?
If you use a local model (eg, with Ollama), it's free. If you use any commercial APIs (eg, OpenAI), you will likely pay per "token" (a sub-word unit).
For example, a simple request with a simple question and 1 sentence response in return (”Is statement XYZ a positive comment”) will cost you ~0.0001 (ie, one-hundredth of a cent)
Is it worth paying for?
GenAI is a way to buy time! You can pay cents to save tens of minutes every day.
Continuing the example above, imagine you have a table with 200 comments. Now, you can parse each one of them with an LLM for the features/checks you need. Assuming the price per call was 0.0001 , you'd pay 2 cents for the job and save 30-60 minutes of your time!
Resources:
How to try new OpenAI models if I'm not Tier 5 customer?
As of September 2024, you cannot access the new o1 models via API unless you're a Tier 5 customer.
Fortunately, you can use OpenRouter to access these new models.
Get your API key from OpenRouter
Add some minimum Credits to the account (eg, 5 ).
Set it as an environment variable (or use local preferences):
ENV["OPENROUTER_API_KEY"] = "<your key>"Use the model aliases with
orprefix, eg,oro1for o1-preview ororo1mfor o1-mini.
Example:
# Let's use o1-preview model hosted on OpenRouter ("or" prefix)\nmsg = aigenerate("What is the meaning of life?"; model="oro1")Note: There are some quirks for the o1 models. For example, the new o1 series does NOT support SystemMessage yet, so OpenRouter does some tricks (likely converting them to normal user messages). To be in control of this behavior and have comparable behavior to the native OpenAI API, you can use kwarg no_system_message=true in aigenerate to ensure OpenRouter does not do any tricks.
Example:
# Let's use o1-mini and disable adding automatic system message\nmsg = aigenerate("What is the meaning of life?"; model="oro1m", no_system_message=true)Configuring the Environment Variable for API Key
This is a guide for OpenAI's API key, but it works for any other API key you might need (eg, MISTRAL_API_KEY for MistralAI API).
To use the OpenAI API with PromptingTools.jl, set your API key as an environment variable:
ENV["OPENAI_API_KEY"] = "your-api-key"As a one-off, you can:
set it in the terminal before launching Julia:
export OPENAI_API_KEY = <your key>set it in your
setup.jl(make sure not to commit it to GitHub!)
Make sure to start Julia from the same terminal window where you set the variable. Easy check in Julia, run ENV["OPENAI_API_KEY"] and you should see your key!
A better way:
On a Mac, add the configuration line to your terminal's configuration file (eg,
~/.zshrc). It will get automatically loaded every time you launch the terminalOn Windows, set it as a system variable in "Environment Variables" settings (see the Resources)
Resources:
Setting the API Key via Preferences.jl
You can also set the API key in LocalPreferences.toml, so it persists across sessions and projects.
Use: PromptingTools.set_preferences!("OPENAI_API_KEY"=>"your-api-key")
To double-check, run PromptingTools.get_preferences("OPENAI_API_KEY") and you should see your key!
See more detail in the ?PromptingTools.PREFERENCES docstring.
Understanding the API Keyword Arguments in aigenerate (api_kwargs)
See OpenAI API reference for more information.
Instant Access from Anywhere
For easy access from anywhere, add PromptingTools into your startup.jl (can be found in ~/.julia/config/startup.jl).
Add the following snippet:
using PromptingTools\nconst PT = PromptingTools # to access unexported functions and typesNow, you can just use ai"Help me do X to achieve Y" from any REPL session!
Open Source Alternatives
The ethos of PromptingTools.jl is to allow you to use whatever model you want, which includes Open Source LLMs. The most popular and easiest to setup is Ollama.ai - see below for more information.
Setup Guide for Ollama
Ollama runs a background service hosting LLMs that you can access via a simple API. It's especially useful when you're working with some sensitive data that should not be sent anywhere.
Installation is very easy, just download the latest version here.
Once you've installed it, just launch the app and you're ready to go!
To check if it's running, go to your browser and open 127.0.0.1:11434. You should see the message "Ollama is running". Alternatively, you can run ollama serve in your terminal and you'll get a message that it's already running.
There are many models available in Ollama Library, including Llama2, CodeLlama, SQLCoder, or my personal favorite openhermes2.5-mistral.
Download new models with ollama pull <model_name> (eg, ollama pull openhermes2.5-mistral).
Show currently available models with ollama list.
See Ollama.ai for more information.
Changing the Default Model or Schema
If you tend to use non-default options, it can get tedious to specify PT.* every time.
There are three ways how you can customize your workflows (especially when you use Ollama or other local models):
Import the functions/types you need explicitly at the top (eg,
using PromptingTools: OllamaSchema)Register your model and its associated schema (
PT.register_model!(; name="123", schema=PT.OllamaSchema())). You won't have to specify the schema anymore only the model name. See Working with Ollama for more information.Override your default model (
PT.MODEL_CHAT) and schema (PT.PROMPT_SCHEMA). It can be done persistently with Preferences, eg,PT.set_preferences!("PROMPT_SCHEMA" => "OllamaSchema", "MODEL_CHAT"=>"llama2").
Using Custom API Providers like Azure or Databricks
Several providers are directly supported (eg, Databricks), check the available prompt schemas (eg, subtypes(PT.AbstractOpenAISchema)).
If you need a custom URL or a few keyword parameters, refer to the implementation of DatabricksOpenAISchema. You effectively need to create your own prompt schema (struct MySchema <: PT.AbstractOpenAISchema) and override the OpenAI.jl behavior. The easiest way is to provide your custom method for OpenAI.create_chat and customize the url, api_key, and other kwargs fields. You can follow the implementation of create_chat for DatabricksOpenAISchema in src/llm_openAI.jl.
Once your schema is ready, you can register the necessary models via PT.register_model!(; name="myschema", schema=MySchema()). You can also add aliases for easier access (eg, PT.MODEL_ALIASES["mymodel"] = "my-model-with-really-long-name").
If you would like to use some heavily customized API, eg, your company's internal LLM proxy (to change headers, URL paths, etc.), refer to the example examples/adding_custom_API.jl in the repo.
How to have Multi-turn Conversations?
Let's say you would like to respond back to a model's response. How to do it?
- With
ai""macro
The simplest way if you used ai"" macro, is to send a reply with the ai!"" macro. It will use the last response as the conversation.
ai"Hi! I'm John"\n\nai!"What's my name?"\n# Return: "Your name is John."- With
aigeneratefunction
You can use the conversation keyword argument to pass the previous conversation (in all ai* functions). It will prepend the past conversation before sending the new request to the model.
To get the conversation, set return_all=true and store the whole conversation thread (not just the last message) in a variable. Then, use it as a keyword argument in the next call.
conversation = aigenerate("Hi! I'm John"; return_all=true)\n@info last(conversation) # display the response\n\n# follow-up (notice that we provide past messages as conversation kwarg\nconversation = aigenerate("What's my name?"; return_all=true, conversation)\n\n## [ Info: Tokens: 50 @ Cost: $0.0 in 1.0 seconds\n## 5-element Vector{PromptingTools.AbstractMessage}:\n## PromptingTools.SystemMessage("Act as a helpful AI assistant")\n## PromptingTools.UserMessage("Hi! I'm John")\n## AIMessage("Hello John! How can I assist you today?")\n## PromptingTools.UserMessage("What's my name?")\n## AIMessage("Your name is John.")Notice that the last message is the response to the second request, but with return_all=true we can see the whole conversation from the beginning.
How to have typed responses?
Our responses are always in AbstractMessage types to ensure we can also handle downstream processing, error handling, and self-healing code (see airetry!).
A good use case for a typed response is when you have a complicated control flow and would like to group and handle certain outcomes differently. You can easily do it as an extra step after the response is received.
Trivially, we can use aiclassifier for Bool statements, eg,
# We can do either\nmybool = tryparse(Bool, aiclassify("Is two plus two four?")) isa Bool # true\n\n# or simply check equality\nmsg = aiclassify("Is two plus two four?") # true\nmybool = msg.content == "true"Now a more complicated example with multiple categories mapping to an enum:
choices = [("A", "any animal or creature"), ("P", "for any plant or tree"), ("O", "for everything else")]\n\n# Set up the return types we want\n@enum Categories A P O\nstring_to_category = Dict("A" => A, "P" => P,"O" => O)\n\n# Run an example\ninput = "spider"\nmsg = aiclassify(:InputClassifier; choices, input)\n\nmytype = string_to_category[msg.content] # A (for animal)How does it work? aiclassify guarantees to output one of our choices (and it handles some of the common quirks)!
How would we achieve the same with aigenerate and arbitrary struct? We need to use the "lazy" AIGenerate struct and airetry! to ensure we get the response and then we can process it further.
AIGenerate has two fields you should know about:
conversation- eg, the vector of "messages" in the current conversation (same as what you get fromaigeneratewithreturn_all=true)success- a boolean flag if the request was successful AND if it passed any subsequentairetry!calls
Let's mimic a case where our "program" should return one of three types: SmallInt, LargeInt, FailedResponse.
We first need to define our custom types:
\n# not needed, just to show a fully typed example\nabstract type MyAbstractResponse end\nstruct SmallInt <: MyAbstractResponse\n number::Int\nend\nstruct LargeInt <: MyAbstractResponse\n number::Int\nend\nstruct FailedResponse <: MyAbstractResponse\n content::String\nendLet's define our "program" as a function to be cleaner. Notice that we use AIGenerate and airetry! to ensure we get the response and then we can process it further.
using PromptingTools.Experimental.AgentTools\n\nfunction give_me_number(prompt::String)::MyAbstractResponse\n # Generate the response\n response = AIGenerate(prompt; config=RetryConfig(;max_retries=2)) |> run!\n\n # Check if it's parseable as Int, if not, send back to be fixed\n # syntax: airetry!(CONDITION-TO-CHECK, <response object>, FEEDBACK-TO-MODEL)\n airetry!(x->tryparse(Int,last_output(x))|>!isnothing, response, "Wrong output format! Answer with digits and nothing else. The number is:")\n\n if response.success != true\n ## we failed to generate a parseable integer\n return FailedResponse("I failed to get the response. Last output: $(last_output(response))")\n end\n number = tryparse(Int,last_output(response))\n return number < 1000 ? SmallInt(number) : LargeInt(number)\nend\n\ngive_me_number("How many car seats are in Porsche 911T?")\n## [ Info: Condition not met. Retrying...\n## [ Info: Condition not met. Retrying...\n## SmallInt(2)We ultimately received our custom type SmallInt with the number of car seats in the Porsche 911T (I hope it's correct!).
If you want to access the full conversation history (all the attempts and feedback), simply output the response object and explore response.conversation.
How to quickly create a prompt template?
Many times, you will want to create a prompt template that you can reuse with different inputs (eg, to create templates for AIHelpMe or LLMTextAnalysis).
Previously, you would have to create a vector of SystemMessage and UserMessage objects and then save it to a disk and reload. Now, you can use the create_template function to do it for you. It's designed for quick prototyping, so it skips the serialization step and loads it directly into the template store (ie, you can use it like any other templates - try aitemplates() search).
The syntax is simple: create_template(;user=<user prompt>, system=<system prompt>, load_as=<template name>)
When called it creates a vector of messages, which you can use directly in the ai* functions. If you provide load_as, it will load the template in the template store (under the load_as name).
Let's generate a quick template for a simple conversation (only one placeholder: name)
# first system message, then user message (or use kwargs)\ntpl=PT.create_template("You must speak like a pirate", "Say hi to {{name}}"; load_as="GreatingPirate")\n\n## 2-element Vector{PromptingTools.AbstractChatMessage}:\n## PromptingTools.SystemMessage("You must speak like a pirate")\n## PromptingTools.UserMessage("Say hi to {{name}}")You can immediately use this template in ai* functions:
aigenerate(tpl; name="Jack Sparrow")\n# Output: AIMessage("Arr, me hearty! Best be sending me regards to Captain Jack Sparrow on the salty seas! May his compass always point true to the nearest treasure trove. Yarrr!")Since we provided load_as, it's also registered in the template store:
aitemplates("pirate")\n\n## 1-element Vector{AITemplateMetadata}:\n## PromptingTools.AITemplateMetadata\n## name: Symbol GreatingPirate\n## description: String ""\n## version: String "1.0"\n## wordcount: Int64 46\n## variables: Array{Symbol}((1,))\n## system_preview: String "You must speak like a pirate"\n## user_preview: String "Say hi to {{name}}"\n## source: String ""So you can use it like any other template:
aigenerate(:GreatingPirate; name="Jack Sparrow")\n# Output: AIMessage("Arr, me hearty! Best be sending me regards to Captain Jack Sparrow on the salty seas! May his compass always point true to the nearest treasure trove. Yarrr!")If you want to save it in your project folder:
PT.save_template("templates/GreatingPirate.json", tpl; version="1.0") # optionally, add descriptionIt will be saved and accessed under its basename, ie, GreatingPirate (same as load_as keyword argument).
Note: If you make any changes to the templates on the disk/in a folder, you need to explicitly reload all templates again!
If you are using the main PromptingTools templates, you can simply call PT.load_templates!(). If you have a project folder with your templates, you want to add it first:
PT.load_templates!("templates")After the first run, we will remember the folder and you can simply call PT.load_templates!() to reload all the templates in the future!
Do we have a RecursiveCharacterTextSplitter like Langchain?
Yes, we do! Look for utility recursive_spliter (previously known as split_by_length). See its docstring for more information.
For reference, Langchain's RecursiveCharacterTextSplitter uses the following setting: separators = ["\\n\\n", "\\n", " ", ""].
I'd recommend using the following instead: separators = ["\\\\n\\\\n", ". ", "\\\\n", " "] (ie, it does not split words, which tends to be unnecessary and quite damaging to the chunk quality).
Example:
using PromptingTools: recursive_splitter\n\ntext = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n", " "] # split by paragraphs, sentences, and newlines, and words\nchunks = recursive_splitter(text, separators, max_length=10)How would I fine-tune a model?
Fine-tuning is a powerful technique to adapt a model to your specific use case (mostly the format/syntax/task). It requires a dataset of examples, which you can now easily generate with PromptingTools.jl!
You can save any conversation (vector of messages) to a file with
PT.save_conversation("filename.json", conversation).Once the finetuning time comes, create a bundle of ShareGPT-formatted conversations (common finetuning format) in a single
.jsonlfile. UsePT.save_conversations("dataset.jsonl", [conversation1, conversation2, ...])(notice that plural "conversationS" in the function name).
For an example of an end-to-end finetuning process, check out our sister project JuliaLLMLeaderboard Finetuning experiment. It shows the process of finetuning for half a dollar with JarvisLabs.ai and Axolotl.
Can I see how my prompt is rendered / what is sent to the API?
Yes, there are two ways.
"dry run", where the
ai*function will return the prompt rendered in the style of the selected API provider"partial render", for provider-agnostic purposes, you can run only the first step of the rendering pipeline to see the messages that will be sent (but formatted as
SystemMessageandUserMessage), which is easy to read and work withDry Run
Add kwargs dry_run and return_all to see what could have been sent to the API to your ai* functions (without return_all there is nothing to show you).
Example for OpenAI:
dry_conv = aigenerate(:BlankSystemUser; system = "I exist", user = "say hi",\n model = "lngpt3t", return_all = true, dry_run = true)2-element Vector{Dict{String, Any}}:\n Dict("role" => "system", "content" => "I exist")\n Dict("role" => "user", "content" => "say hi")- Partial Render
Personally, I prefer to see the pretty formatting of PromptingTools *Messages. To see what will be sent to the model, you can render only the first stage of the rendering pipeline with schema NoSchema() (it merely does the variable replacements and creates the necessary messages). It's shared by all the schema/providers.
PT.render(PT.NoSchema(), "say hi, {{name}}"; name="John")2-element Vector{PromptingTools.AbstractMessage}:\n PromptingTools.SystemMessage("Act as a helpful AI assistant")\n PromptingTools.UserMessage("say hi, John")What about the prompt templates? Prompt templates have an extra pre-rendering step that expands the symbolic :name (understood by PromptingTools as a reference to AITemplate(:name)) into a vector of Messages.
# expand the template into messages\ntpl = PT.render(AITemplate(:BlankSystemUser))\nPT.render(PT.NoSchema(), tpl; system = "I exist", user = "say hi")\n# replace any variables, etc.2-element Vector{PromptingTools.AbstractMessage}:\n PromptingTools.SystemMessage("I exist")\n PromptingTools.UserMessage("say hi")For more information about the rendering pipeline and examples refer to Walkthrough Example for aigenerate.
Automatic Logging / Tracing
If you would like to automatically capture metadata about your conversations, you can use the TracerSchema. It automatically captures the necessary metadata such as model, task (parent_id), current thread (thread_id), API kwargs used and any prompt templates (and its versions).
using PromptingTools: TracerSchema, OpenAISchema\n\nwrap_schema = TracerSchema(OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model="gpt-4")\n# output type should be TracerMessage\nmsg isa TracerMessageYou can work with the message like any other message (properties of the inner object are overloaded). You can extract the original message with unwrap:
unwrap(msg) isa StringYou can extract the metadata with meta:
meta(msg) isa DictIf you would like to automatically save the conversations, you can use the SaverSchema. It automatically serializes the conversation to a file in the directory specified by the environment variable LOG_DIR.
using PromptingTools: SaverSchema\n\nwrap_schema = SaverSchema(OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model="gpt-4")See LOG_DIR location to find the serialized conversation.
You can also compose multiple tracing schemas. For example, you can capture metadata with TracerSchema and then save everything automatically with SaverSchema:
using PromptingTools: TracerSchema, SaverSchema, OpenAISchema\n\nwrap_schema = OpenAISchema() |> TracerSchema |> SaverSchema\nconv = aigenerate(wrap_schema,:BlankSystemUser; system="You're a French-speaking assistant!",\n user="Say hi!"; model="gpt-4", api_kwargs=(;temperature=0.1), return_all=true)conv is a vector of tracing messages that will be saved to a JSON together with metadata about the template and api_kwargs.
If you would like to enable this behavior automatically, you can register your favorite model (or re-register existing models) with the "wrapped" schema:
PT.register_model!(; name= "gpt-3.5-turbo", schema=OpenAISchema() |> TracerSchema |> SaverSchema)Getting Started
Prerequisites
OpenAI API key saved in the environment variable OPENAI_API_KEY
You will need to register with OpenAI and generate an API key:
Create an account with OpenAI
Go to Account Billing and buy some credits (prepayment, minimum 5 ). Your account must have credits for the API access to work.
Go to API Key page
Click on “Create new secret key”
!!! Do not share it with anyone and do NOT save it to any files that get synced online.
Resources:
You will need to set this key as an environment variable before using PromptingTools.jl:
For a quick start, simply set it via ENV["OPENAI_API_KEY"] = "your-api-key" Alternatively, you can:
set it in the terminal before launching Julia:
export OPENAI_API_KEY = <your key>set it in your
setup.jl(make sure not to commit it to GitHub!)
Make sure to start Julia from the same terminal window where you set the variable. Easy check in Julia, run ENV["OPENAI_API_KEY"] and you should see your key!
For other options or more robust solutions, see the FAQ section.
Resources:
Installation
PromptingTools can be installed using the following commands:
using Pkg\nPkg.add("PromptingTools.jl")Throughout the rest of this tutorial, we will assume that you have installed the PromptingTools package and have already typed using PromptingTools to bring all of the relevant variables into your current namespace.
Quick Start with @ai_str
The easiest start is the @ai_str macro. Simply type ai"your prompt" and you will get a response from the default model (GPT-3.5 Turbo).
ai"What is the capital of France?"[ Info: Tokens: 31 @ Cost: $0.0 in 1.5 seconds --> Be in control of your spending! \nAIMessage("The capital of France is Paris.")Returned object is a light wrapper with generated message in field :content (eg, ans.content) for additional downstream processing.
If you want to reply to the previous message, or simply continue the conversation, use @ai!_str (notice the bang !):
ai!"And what is the population of it?"You can easily inject any variables with string interpolation:
country = "Spain"\nai"What is the capital of \\$(country)?"[ Info: Tokens: 32 @ Cost: $0.0001 in 0.5 seconds\nAIMessage("The capital of Spain is Madrid.")Pro tip: Use after-string-flags to select the model to be called, eg, ai"What is the capital of France?"gpt4 (use gpt4t for the new GPT-4 Turbo model). Great for those extra hard questions!
Using aigenerate with placeholders
For more complex prompt templates, you can use handlebars-style templating and provide variables as keyword arguments:
msg = aigenerate("What is the capital of {{country}}? Is the population larger than {{population}}?", country="Spain", population="1M")[ Info: Tokens: 74 @ Cost: $0.0001 in 1.3 seconds\nAIMessage("The capital of Spain is Madrid. And yes, the population of Madrid is larger than 1 million. As of 2020, the estimated population of Madrid is around 3.3 million people.")Pro tip: Use asyncmap to run multiple AI-powered tasks concurrently.
Pro tip: If you use slow models (like GPT-4), you can use the asynchronous version of @ai_str -> @aai_str to avoid blocking the REPL, eg, aai"Say hi but slowly!"gpt4 (similarly @ai!_str -> @aai!_str for multi-turn conversations).
For more practical examples, see the Various Examples section.
', 37) + ])); +} +const getting_started = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + getting_started as default +}; diff --git a/previews/PR252/assets/getting_started.md.2FgCGmLD.lean.js b/previews/PR252/assets/getting_started.md.2FgCGmLD.lean.js new file mode 100644 index 00000000..2bb8e41b --- /dev/null +++ b/previews/PR252/assets/getting_started.md.2FgCGmLD.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Getting Started","description":"","frontmatter":{},"headers":[],"relativePath":"getting_started.md","filePath":"getting_started.md","lastUpdated":null}'); +const _sfc_main = { name: "getting_started.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('Getting Started
Prerequisites
OpenAI API key saved in the environment variable OPENAI_API_KEY
You will need to register with OpenAI and generate an API key:
Create an account with OpenAI
Go to Account Billing and buy some credits (prepayment, minimum 5 ). Your account must have credits for the API access to work.
Go to API Key page
Click on “Create new secret key”
!!! Do not share it with anyone and do NOT save it to any files that get synced online.
Resources:
You will need to set this key as an environment variable before using PromptingTools.jl:
For a quick start, simply set it via ENV["OPENAI_API_KEY"] = "your-api-key" Alternatively, you can:
set it in the terminal before launching Julia:
export OPENAI_API_KEY = <your key>set it in your
setup.jl(make sure not to commit it to GitHub!)
Make sure to start Julia from the same terminal window where you set the variable. Easy check in Julia, run ENV["OPENAI_API_KEY"] and you should see your key!
For other options or more robust solutions, see the FAQ section.
Resources:
Installation
PromptingTools can be installed using the following commands:
using Pkg\nPkg.add("PromptingTools.jl")Throughout the rest of this tutorial, we will assume that you have installed the PromptingTools package and have already typed using PromptingTools to bring all of the relevant variables into your current namespace.
Quick Start with @ai_str
The easiest start is the @ai_str macro. Simply type ai"your prompt" and you will get a response from the default model (GPT-3.5 Turbo).
ai"What is the capital of France?"[ Info: Tokens: 31 @ Cost: $0.0 in 1.5 seconds --> Be in control of your spending! \nAIMessage("The capital of France is Paris.")Returned object is a light wrapper with generated message in field :content (eg, ans.content) for additional downstream processing.
If you want to reply to the previous message, or simply continue the conversation, use @ai!_str (notice the bang !):
ai!"And what is the population of it?"You can easily inject any variables with string interpolation:
country = "Spain"\nai"What is the capital of \\$(country)?"[ Info: Tokens: 32 @ Cost: $0.0001 in 0.5 seconds\nAIMessage("The capital of Spain is Madrid.")Pro tip: Use after-string-flags to select the model to be called, eg, ai"What is the capital of France?"gpt4 (use gpt4t for the new GPT-4 Turbo model). Great for those extra hard questions!
Using aigenerate with placeholders
For more complex prompt templates, you can use handlebars-style templating and provide variables as keyword arguments:
msg = aigenerate("What is the capital of {{country}}? Is the population larger than {{population}}?", country="Spain", population="1M")[ Info: Tokens: 74 @ Cost: $0.0001 in 1.3 seconds\nAIMessage("The capital of Spain is Madrid. And yes, the population of Madrid is larger than 1 million. As of 2020, the estimated population of Madrid is around 3.3 million people.")Pro tip: Use asyncmap to run multiple AI-powered tasks concurrently.
Pro tip: If you use slow models (like GPT-4), you can use the asynchronous version of @ai_str -> @aai_str to avoid blocking the REPL, eg, aai"Say hi but slowly!"gpt4 (similarly @ai!_str -> @aai!_str for multi-turn conversations).
For more practical examples, see the Various Examples section.
', 37) + ])); +} +const getting_started = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + getting_started as default +}; diff --git a/previews/PR252/assets/how_it_works.md.BjfUlTEL.js b/previews/PR252/assets/how_it_works.md.BjfUlTEL.js new file mode 100644 index 00000000..dc4dcbbf --- /dev/null +++ b/previews/PR252/assets/how_it_works.md.BjfUlTEL.js @@ -0,0 +1,35 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, j as createBaseVNode, a as createTextVNode, t as toDisplayString, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"How It Works","description":"","frontmatter":{},"headers":[],"relativePath":"how_it_works.md","filePath":"how_it_works.md","lastUpdated":null}'); +const _sfc_main = { name: "how_it_works.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, [ + _cache[10] || (_cache[10] = createStaticVNode('How It Works
This is an advanced section that explains how PromptingTools.jl works under the hood. It is not necessary to understand this to use the package, but it can be helpful for debugging and understanding the limitations of the package.
We'll start with the key concepts and then walk through an example of aigenerate to see how it all fits together.
Key Concepts
5 Key Concepts (/Objects):
API/Model Providers -> The method that gives you access to Large Language Models (LLM), it can be an API (eg, OpenAI) or a locally-hosted application (eg, Llama.cpp or Ollama)
Schemas -> object of type
AbstractPromptSchemathat determines which methods are called and, hence, what providers/APIs are usedPrompts -> the information you want to convey to the AI model
Messages -> the basic unit of communication between the user and the AI model (eg,
UserMessagevsAIMessage)Prompt Templates -> re-usable "prompts" with placeholders that you can replace with your inputs at the time of making the request
When you call aigenerate, roughly the following happens: render -> UserMessage(s) -> render -> OpenAI.create_chat -> ... -> AIMessage.
API/Model Providers
You can think of "API/Model Providers" as the method that gives you access to Large Language Models (LLM). It can be an API (eg, OpenAI) or a locally-hosted application (eg, Llama.cpp or Ollama).
You interact with them via the schema object, which is a subtype of AbstractPromptSchema, eg, there is an OpenAISchema for the provider "OpenAI" and its supertype AbstractOpenAISchema is for all other providers that mimic the OpenAI API.
Schemas
For your "message" to reach an AI model, it needs to be formatted and sent to the right place (-> provider!).
We leverage the multiple dispatch around the "schemas" to pick the right logic. All schemas are subtypes of AbstractPromptSchema and there are many subtypes, eg, OpenAISchema <: AbstractOpenAISchema <:AbstractPromptSchema.
For example, if you provide schema = OpenAISchema(), the system knows that:
it will have to format any user inputs to OpenAI's "message specification" (a vector of dictionaries, see their API documentation). Function
render(OpenAISchema(),...)will take care of the rendering.it will have to send the message to OpenAI's API. We will use the amazing
OpenAI.jlpackage to handle the communication.
Prompts
Prompt is loosely the information you want to convey to the AI model. It can be a question, a statement, or a command. It can have instructions or some context, eg, previous conversation.
You need to remember that Large Language Models (LLMs) are stateless. They don't remember the previous conversation/request, so you need to provide the whole history/context every time (similar to how REST APIs work).
Prompts that we send to the LLMs are effectively a sequence of messages (<:AbstractMessage).
Messages
Messages are the basic unit of communication between the user and the AI model.
There are 5 main types of messages (<:AbstractMessage):
SystemMessage- this contains information about the "system", eg, how it should behave, format its output, etc. (eg, `You're a world-class Julia programmer. You write brief and concise code.)UserMessage- the information "from the user", ie, your question/statement/taskUserMessageWithImages- the same asUserMessage, but with images (URLs or Base64-encoded images)AIMessage- the response from the AI model, when the "output" is textDataMessage- the response from the AI model, when the "output" is data, eg, embeddings withaiembedor user-defined structs withaiextract
Prompt Templates
', 24)), + createBaseVNode("p", null, [ + _cache[0] || (_cache[0] = createTextVNode('We want to have re-usable "prompts", so we provide you with a system to retrieve pre-defined prompts with placeholders (eg, ')), + createBaseVNode("code", null, toDisplayString(_ctx.name), 1), + _cache[1] || (_cache[1] = createTextVNode(") that you can replace with your inputs at the time of making the request.")) + ]), + _cache[11] || (_cache[11] = createStaticVNode('"AI Templates" as we call them (AITemplate) are usually a vector of SystemMessage and a UserMessage with specific purpose/task.
For example, the template :AssistantAsk is defined loosely as:
template = [SystemMessage("You are a world-class AI assistant. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer."),\n UserMessage("# Question\\n\\n{{ask}}")]When you provide a Symbol (eg, :AssistantAsk) to ai* functions, thanks to the multiple dispatch, it recognizes that it's an AITemplate(:AssistantAsk) and looks it up.
You can discover all available templates with aitemplates("some keyword") or just see the details of some template aitemplates(:AssistantAsk).
Note: There is a new way to create and register templates in one go with create_template(;user=<user prompt>, system=<system prompt>, load_as=<template name>) (it skips the serialization step where a template previously must have been saved somewhere on the disk). See FAQ for more details or directly ?create_template.
ai* Functions Overview
The above steps are implemented in the ai* functions, eg, aigenerate, aiembed, aiextract, etc. They all have the same basic structure:
ai*(<optional schema>,<prompt or conversation>; <optional keyword arguments>),
but they differ in purpose:
aigenerateis the general-purpose function to generate any text response with LLMs, ie, it returnsAIMessagewith field:contentcontaining the generated text (eg,ans.content isa AbstractString)aiembedis designed to extract embeddings from the AI model's response, ie, it returnsDataMessagewith field:contentcontaining the embeddings (eg,ans.content isa AbstractArray)aiextractis designed to extract structured data from the AI model's response and return them as a Julia struct (eg, if we providereturn_type=Food, we getans.content isa Food). You need to define the return type first and then provide it as a keyword argument.aitoolsis designed for agentic workflows with a mix of tool calls and user inputs. It can work with simple functions and execute them.aiclassifyis designed to classify the input text into (or simply respond within) a set of discretechoicesprovided by the user. It can be very useful as an LLM Judge or a router for RAG systems, as it uses the "logit bias trick" and generates exactly 1 token. It returnsAIMessagewith field:content, but the:contentcan be only one of the providedchoices(eg,ans.content in choices)aiscanis for working with images and vision-enabled models (as an input), but it returnsAIMessagewith field:contentcontaining the generated text (eg,ans.content isa AbstractString) similar toaigenerate.aiimageis for generating images (eg, with OpenAI DALL-E 3). It returns aDataMessage, where the field:contentmight contain either the URL to download the image from or the Base64-encoded image depending on the user-provided kwargapi_kwargs.response_format.aitemplatesis a helper function to discover available templates and see their details (eg,aitemplates("some keyword")oraitemplates(:AssistantAsk))
If you're using a known model, you do NOT need to provide a schema (the first argument).
Optional keyword arguments in ai* tend to be:
model::String- Which model you want to useverbose::Bool- Whether you went to see INFO logs around AI costsreturn_all::Bool- Whether you want the WHOLE conversation or just the AI answer (ie, whether you want to include your inputs/prompt in the output)api_kwargs::NamedTuple- Specific parameters for the model, eg,temperature=0.0to be NOT creative (and have more similar output in each run)http_kwargs::NamedTuple- Parameters for the HTTP.jl package, eg,readtimeout = 120to time out in 120 seconds if no response was received.
In addition to the above list of ai* functions, you can also use the "lazy" counterparts of these functions from the experimental AgentTools module.
using PromptingTools.Experimental.AgentToolsFor example, AIGenerate() will create a lazy instance of aigenerate. It is an instance of AICall with aigenerate as its ai function. It uses exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details).
"lazy" refers to the fact that it does NOT generate any output when instantiated (only when run! is called).
Or said differently, the AICall struct and all its flavors (AIGenerate, ...) are designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied.
This approach allows us to remember user inputs and trigger the LLM call repeatedly if needed, which enables automatic fixing (see ?airetry!).
Example:
result = AIGenerate(:JuliaExpertAsk; ask="xyz", model="abc", api_kwargs=(; temperature=0.1))\nresult |> run!\n\n# Is equivalent to\nresult = aigenerate(:JuliaExpertAsk; ask="xyz", model="abc", api_kwargs=(; temperature=0.1), return_all=true)\n# The only difference is that we default to `return_all=true` with lazy types because we have a dedicated `conversation` field, which makes it much easierLazy AI calls and self-healing mechanisms unlock much more robust and useful LLM workflows!
Walkthrough Example for aigenerate
using PromptingTools\nconst PT = PromptingTools\n\n# Let's say this is our ask\nmsg = aigenerate(:AssistantAsk; ask="What is the capital of France?")\n\n# it is effectively the same as:\nmsg = aigenerate(PT.OpenAISchema(), PT.AITemplate(:AssistantAsk); ask="What is the capital of France?", model="gpt3t")There is no model provided, so we use the default PT.MODEL_CHAT (effectively GPT3.5-Turbo). Then we look it up in PT.MDOEL_REGISTRY and use the associated schema for it (OpenAISchema in this case).
The next step is to render the template, replace the placeholders and render it for the OpenAI model.
# Let's remember out schema\nschema = PT.OpenAISchema()\nask = "What is the capital of France?"First, we obtain the template (no placeholder replacement yet) and "expand it"
template_rendered = PT.render(schema, AITemplate(:AssistantAsk); ask)2-element Vector{PromptingTools.AbstractChatMessage}:\n PromptingTools.SystemMessage("You are a world-class AI assistant. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n PromptingTools.UserMessage{String}("# Question\\n\\n{{ask}}", [:ask], :usermessage)Second, we replace the placeholders
rendered_for_api = PT.render(schema, template_rendered; ask)2-element Vector{Dict{String, Any}}:\n Dict("role" => "system", "content" => "You are a world-class AI assistant. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n Dict("role" => "user", "content" => "# Question\\n\\nWhat is the capital of France?")Notice that the placeholders are only replaced in the second step. The final output here is a vector of messages with "role" and "content" keys, which is the format required by the OpenAI API.
As a side note, under the hood, the second step is done in two sub-steps:
replace the placeholders
messages_rendered = PT.render(PT.NoSchema(), template_rendered; ask)-> returns a vector of Messages!then, we convert the messages to the format required by the provider/schema
PT.render(schema, messages_rendered)-> returns the OpenAI formatted messages
Next, we send the above rendered_for_api to the OpenAI API and get the response back.
using OpenAI\nOpenAI.create_chat(api_key, model, rendered_for_api)The last step is to take the JSON response from the API and convert it to the AIMessage object.
# simplification for educational purposes\nmsg = AIMessage(; content = r.response[:choices][1][:message][:content])In practice, there are more fields we extract, so we define a utility for it: PT.response_to_message. Especially, since with parameter n, you can request multiple AI responses at once, so we want to re-use our response processing logic.
That's it! I hope you've learned something new about how PromptingTools.jl works under the hood.
Walkthrough Example for aiextract
Whereas aigenerate is a general-purpose function to generate any text response with LLMs, aiextract is designed to extract structured data from the AI model's response and return them as a Julia struct.
It's a bit more complicated than aigenerate because it needs to handle the JSON schema of the return type (= our struct).
Let's define a toy example of a struct and see how aiextract works under the hood.
using PromptingTools\nconst PT = PromptingTools\n\n"""\nExtract the name of the food from the sentence. Extract any provided adjectives for the food as well.\n\nExample: "I am eating a crunchy bread." -> Food("bread", ["crunchy"])\n"""\nstruct Food\n name::String # required field!\n adjectives::Union{Nothing,Vector{String}} # not required because `Nothing` is allowed\nend\n\nmsg = aiextract("I just ate a delicious and juicy apple."; return_type=Food)\nmsg.content\n# Food("apple", ["delicious", "juicy"])You can see that we sent a prompt to the AI model and it returned a Food object. We provided some light guidance as a docstring of the return type, but the AI model did the heavy lifting.
aiextract leverages native "function calling" (supported by OpenAI, Fireworks, Together, and many others).
We encode the user-provided return_type into the corresponding JSON schema and create the payload as per the specifications of the provider.
Let's how that's done:
sig = PT.function_call_signature(Food)\n## Dict{String, Any} with 3 entries:\n## "name" => "Food_extractor"\n## "parameters" => Dict{String, Any}("properties"=>Dict{String, Any}("name"=>Dict("type"=>"string"), "adjectives"=>Dict{String, …\n## "description" => "Extract the food from the sentence. Extract any provided adjectives for the food as well.\\n\\nExample: "You can see that we capture the field names and types in parameters and the description in description key.
Furthermore, if we zoom in on the "parameter" field, you can see that we encode not only the names and types but also whether the fields are required (ie, do they allow Nothing) You can see below that the field adjectives accepts Nothing, so it's not required. Only the name field is required.
sig["parameters"]\n## Dict{String, Any} with 3 entries:\n## "properties" => Dict{String, Any}("name"=>Dict("type"=>"string"), "adjectives"=>Dict{String, Any}("items"=>Dict("type"=>"strin…\n## "required" => ["name"]\n## "type" => "object"For aiextract, the signature is provided to the API provider via tools parameter, eg,
api_kwargs = (; tools = [Dict(:type => "function", :function => sig)])
Optionally, we can provide also tool_choice parameter to specify which tool to use if we provided multiple (differs across providers).
When the message is returned, we extract the JSON object in the response and decode it into Julia object via JSON3.read(obj, Food). For example,
model_response = Dict(:tool_calls => [Dict(:function => Dict(:arguments => JSON3.write(Dict("name" => "apple", "adjectives" => ["delicious", "juicy"]))))])\nfood = JSON3.read(model_response[:tool_calls][1][:function][:arguments], Food)\n# Output: Food("apple", ["delicious", "juicy"])This is why you can sometimes have errors when you use abstract types in your return_type -> to enable that, you would need to set the right StructTypes behavior for your abstract type (see the JSON3.jl documentation for more details on how to do that).
It works quite well for concrete types and "vanilla" structs, though.
Unfortunately, function calling is generally NOT supported by locally-hosted / open-source models, so let's try to build a workaround with aigenerate
You need to pick a bigger / more powerful model, as it's NOT an easy task to output a correct JSON specification. My laptop isn't too powerful and I don't like waiting, so I'm going to use Mixtral model hosted on Together.ai (you get $25 credit when you join)!
model = "tmixtral" # tmixtral is an alias for "mistralai/Mixtral-8x7B-Instruct-v0.1" on Together.ai and it automatically sets `schema = TogetherOpenAISchema()`We'll add the signature to the prompt and we'll request the JSON output in two places - in the prompt and in the api_kwargs (to ensure that the model outputs the JSON via "grammar") NOTE: You can write much better and more specific prompt if you have a specific task / return type in mind + you should make sure that the prompt + struct description make sense together!
prompt = """\nYou're a world-class data extraction engine. \n\nYour task is to extract information formatted as per the user provided schema.\nYou MUST response in JSON format.\n\n**Example:**\n---------\nDescription: "Extract the Car from the sentence. Extract the corresponding brand and model as well."\nInput: "I drive a black Porsche 911 Turbo."\nSchema: "{\\"properties\\":{\\"model\\":{\\"type\\":\\"string\\"},\\"brand\\":{\\"type\\":\\"string\\"}},\\"required\\":[\\"brand\\",\\"model\\"],\\"type\\":\\"object\\"}"\nOutput: "{\\"model\\":\\"911 Turbo\\",\\"brand\\":\\"Porsche\\"}"\n---------\n\n**User Request:**\nDescription: {{description}}\nInput: {{input}}\nSchema: {{signature}}\nOutput:\n\nYou MUST OUTPUT in JSON format.\n"""We need to extract the "signature of our return_type and put it in the right placeholders. Let's generate now!
sig = PT.function_call_signature(Food)\nresult = aigenerate(prompt; input="I just ate a delicious and juicy apple.",\n schema=JSON3.write(sig["parameters"]), description=sig["description"],\n ## We provide the JSON output requirement as per API docs: https://docs.together.ai/docs/json-mode\n model, api_kwargs=(; response_format=Dict("type" => "json_object"), temperature=0.2), return_all=true)\nresult[end].content\n## "{\\n \\"adjectives\\": [\\"delicious\\", \\"juicy\\"],\\n \\"food\\": \\"apple\\"\\n}"We're using a smaller model, so the output is not perfect. Let's try to load into our object:
obj = JSON3.read(result[end].content, Food)\n# Output: ERROR: MethodError: Cannot `convert` an object of type Nothing to an object of type StringUnfortunately, we get an error because the model mixed up the key "name" for "food", so it cannot be parsed.
Fortunately, we can do better and use automatic fixing! All we need to do is to change from aigenerate -> AIGenerate (and use airetry!)
The signature of AIGenerate is identical to aigenerate with the exception of config field, where we can influence the future retry behaviour.
result = AIGenerate(prompt; input="I just ate a delicious and juicy apple.",\n schema=JSON3.write(sig["parameters"]), description=sig["description"],\n ## We provide the JSON output requirement as per API docs: https://docs.together.ai/docs/json-mode\n model, api_kwargs=(; response_format=Dict("type" => "json_object"), temperature=0.2),\n ## limit the number of retries, default is 10 rounds\n config=RetryConfig(; max_retries=3))\nrun!(result) # run! triggers the generation step (to have some AI output to check)Let's set up a retry mechanism with some practical feedback. We'll leverage airetry! to automatically retry the request and provide feedback to the model. Think of airetry! as @assert on steroids:
@assert CONDITION MESSAGE → airetry! CONDITION <state> MESSAGE
The main benefits of airetry! are:
It can retry automatically, not just throw an error
It manages the "conversation’ (list of messages) for you, including adding user-provided feedback to help generate better output
feedback = "The output is not in the correct format. The keys should be $(join([string("\\"$f\\"") for f in fieldnames(Food)],", "))."\n# We use do-syntax with provide the `CONDITION` (it must return Bool)\nairetry!(result, feedback) do conv\n ## try to convert\n obj = try\n JSON3.read(last_output(conv), Food)\n catch e\n ## you could save the error and provide as feedback (eg, into a slot in the `:memory` field of the AICall object)\n e\n end\n ## Check if the conversion was successful; if it's `false`, it will retry\n obj isa Food # -> Bool\nend\nfood = JSON3.read(last_output(result), Food)\n## [ Info: Condition not met. Retrying...\n## Output: Food("apple", ["delicious", "juicy"])It took 1 retry (see result.config.retries) and we have the correct output from an open-source model!
If you're interested in the result object, it's a struct (AICall) with a field conversation, which holds the conversation up to this point. AIGenerate is an alias for AICall using aigenerate function. See ?AICall (the underlying struct type) for more details on the fields and methods available.
How It Works
This is an advanced section that explains how PromptingTools.jl works under the hood. It is not necessary to understand this to use the package, but it can be helpful for debugging and understanding the limitations of the package.
We'll start with the key concepts and then walk through an example of aigenerate to see how it all fits together.
Key Concepts
5 Key Concepts (/Objects):
API/Model Providers -> The method that gives you access to Large Language Models (LLM), it can be an API (eg, OpenAI) or a locally-hosted application (eg, Llama.cpp or Ollama)
Schemas -> object of type
AbstractPromptSchemathat determines which methods are called and, hence, what providers/APIs are usedPrompts -> the information you want to convey to the AI model
Messages -> the basic unit of communication between the user and the AI model (eg,
UserMessagevsAIMessage)Prompt Templates -> re-usable "prompts" with placeholders that you can replace with your inputs at the time of making the request
When you call aigenerate, roughly the following happens: render -> UserMessage(s) -> render -> OpenAI.create_chat -> ... -> AIMessage.
API/Model Providers
You can think of "API/Model Providers" as the method that gives you access to Large Language Models (LLM). It can be an API (eg, OpenAI) or a locally-hosted application (eg, Llama.cpp or Ollama).
You interact with them via the schema object, which is a subtype of AbstractPromptSchema, eg, there is an OpenAISchema for the provider "OpenAI" and its supertype AbstractOpenAISchema is for all other providers that mimic the OpenAI API.
Schemas
For your "message" to reach an AI model, it needs to be formatted and sent to the right place (-> provider!).
We leverage the multiple dispatch around the "schemas" to pick the right logic. All schemas are subtypes of AbstractPromptSchema and there are many subtypes, eg, OpenAISchema <: AbstractOpenAISchema <:AbstractPromptSchema.
For example, if you provide schema = OpenAISchema(), the system knows that:
it will have to format any user inputs to OpenAI's "message specification" (a vector of dictionaries, see their API documentation). Function
render(OpenAISchema(),...)will take care of the rendering.it will have to send the message to OpenAI's API. We will use the amazing
OpenAI.jlpackage to handle the communication.
Prompts
Prompt is loosely the information you want to convey to the AI model. It can be a question, a statement, or a command. It can have instructions or some context, eg, previous conversation.
You need to remember that Large Language Models (LLMs) are stateless. They don't remember the previous conversation/request, so you need to provide the whole history/context every time (similar to how REST APIs work).
Prompts that we send to the LLMs are effectively a sequence of messages (<:AbstractMessage).
Messages
Messages are the basic unit of communication between the user and the AI model.
There are 5 main types of messages (<:AbstractMessage):
SystemMessage- this contains information about the "system", eg, how it should behave, format its output, etc. (eg, `You're a world-class Julia programmer. You write brief and concise code.)UserMessage- the information "from the user", ie, your question/statement/taskUserMessageWithImages- the same asUserMessage, but with images (URLs or Base64-encoded images)AIMessage- the response from the AI model, when the "output" is textDataMessage- the response from the AI model, when the "output" is data, eg, embeddings withaiembedor user-defined structs withaiextract
Prompt Templates
', 24)), + createBaseVNode("p", null, [ + _cache[0] || (_cache[0] = createTextVNode('We want to have re-usable "prompts", so we provide you with a system to retrieve pre-defined prompts with placeholders (eg, ')), + createBaseVNode("code", null, toDisplayString(_ctx.name), 1), + _cache[1] || (_cache[1] = createTextVNode(") that you can replace with your inputs at the time of making the request.")) + ]), + _cache[11] || (_cache[11] = createStaticVNode('"AI Templates" as we call them (AITemplate) are usually a vector of SystemMessage and a UserMessage with specific purpose/task.
For example, the template :AssistantAsk is defined loosely as:
template = [SystemMessage("You are a world-class AI assistant. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer."),\n UserMessage("# Question\\n\\n{{ask}}")]When you provide a Symbol (eg, :AssistantAsk) to ai* functions, thanks to the multiple dispatch, it recognizes that it's an AITemplate(:AssistantAsk) and looks it up.
You can discover all available templates with aitemplates("some keyword") or just see the details of some template aitemplates(:AssistantAsk).
Note: There is a new way to create and register templates in one go with create_template(;user=<user prompt>, system=<system prompt>, load_as=<template name>) (it skips the serialization step where a template previously must have been saved somewhere on the disk). See FAQ for more details or directly ?create_template.
ai* Functions Overview
The above steps are implemented in the ai* functions, eg, aigenerate, aiembed, aiextract, etc. They all have the same basic structure:
ai*(<optional schema>,<prompt or conversation>; <optional keyword arguments>),
but they differ in purpose:
aigenerateis the general-purpose function to generate any text response with LLMs, ie, it returnsAIMessagewith field:contentcontaining the generated text (eg,ans.content isa AbstractString)aiembedis designed to extract embeddings from the AI model's response, ie, it returnsDataMessagewith field:contentcontaining the embeddings (eg,ans.content isa AbstractArray)aiextractis designed to extract structured data from the AI model's response and return them as a Julia struct (eg, if we providereturn_type=Food, we getans.content isa Food). You need to define the return type first and then provide it as a keyword argument.aitoolsis designed for agentic workflows with a mix of tool calls and user inputs. It can work with simple functions and execute them.aiclassifyis designed to classify the input text into (or simply respond within) a set of discretechoicesprovided by the user. It can be very useful as an LLM Judge or a router for RAG systems, as it uses the "logit bias trick" and generates exactly 1 token. It returnsAIMessagewith field:content, but the:contentcan be only one of the providedchoices(eg,ans.content in choices)aiscanis for working with images and vision-enabled models (as an input), but it returnsAIMessagewith field:contentcontaining the generated text (eg,ans.content isa AbstractString) similar toaigenerate.aiimageis for generating images (eg, with OpenAI DALL-E 3). It returns aDataMessage, where the field:contentmight contain either the URL to download the image from or the Base64-encoded image depending on the user-provided kwargapi_kwargs.response_format.aitemplatesis a helper function to discover available templates and see their details (eg,aitemplates("some keyword")oraitemplates(:AssistantAsk))
If you're using a known model, you do NOT need to provide a schema (the first argument).
Optional keyword arguments in ai* tend to be:
model::String- Which model you want to useverbose::Bool- Whether you went to see INFO logs around AI costsreturn_all::Bool- Whether you want the WHOLE conversation or just the AI answer (ie, whether you want to include your inputs/prompt in the output)api_kwargs::NamedTuple- Specific parameters for the model, eg,temperature=0.0to be NOT creative (and have more similar output in each run)http_kwargs::NamedTuple- Parameters for the HTTP.jl package, eg,readtimeout = 120to time out in 120 seconds if no response was received.
In addition to the above list of ai* functions, you can also use the "lazy" counterparts of these functions from the experimental AgentTools module.
using PromptingTools.Experimental.AgentToolsFor example, AIGenerate() will create a lazy instance of aigenerate. It is an instance of AICall with aigenerate as its ai function. It uses exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details).
"lazy" refers to the fact that it does NOT generate any output when instantiated (only when run! is called).
Or said differently, the AICall struct and all its flavors (AIGenerate, ...) are designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied.
This approach allows us to remember user inputs and trigger the LLM call repeatedly if needed, which enables automatic fixing (see ?airetry!).
Example:
result = AIGenerate(:JuliaExpertAsk; ask="xyz", model="abc", api_kwargs=(; temperature=0.1))\nresult |> run!\n\n# Is equivalent to\nresult = aigenerate(:JuliaExpertAsk; ask="xyz", model="abc", api_kwargs=(; temperature=0.1), return_all=true)\n# The only difference is that we default to `return_all=true` with lazy types because we have a dedicated `conversation` field, which makes it much easierLazy AI calls and self-healing mechanisms unlock much more robust and useful LLM workflows!
Walkthrough Example for aigenerate
using PromptingTools\nconst PT = PromptingTools\n\n# Let's say this is our ask\nmsg = aigenerate(:AssistantAsk; ask="What is the capital of France?")\n\n# it is effectively the same as:\nmsg = aigenerate(PT.OpenAISchema(), PT.AITemplate(:AssistantAsk); ask="What is the capital of France?", model="gpt3t")There is no model provided, so we use the default PT.MODEL_CHAT (effectively GPT3.5-Turbo). Then we look it up in PT.MDOEL_REGISTRY and use the associated schema for it (OpenAISchema in this case).
The next step is to render the template, replace the placeholders and render it for the OpenAI model.
# Let's remember out schema\nschema = PT.OpenAISchema()\nask = "What is the capital of France?"First, we obtain the template (no placeholder replacement yet) and "expand it"
template_rendered = PT.render(schema, AITemplate(:AssistantAsk); ask)2-element Vector{PromptingTools.AbstractChatMessage}:\n PromptingTools.SystemMessage("You are a world-class AI assistant. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n PromptingTools.UserMessage{String}("# Question\\n\\n{{ask}}", [:ask], :usermessage)Second, we replace the placeholders
rendered_for_api = PT.render(schema, template_rendered; ask)2-element Vector{Dict{String, Any}}:\n Dict("role" => "system", "content" => "You are a world-class AI assistant. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.")\n Dict("role" => "user", "content" => "# Question\\n\\nWhat is the capital of France?")Notice that the placeholders are only replaced in the second step. The final output here is a vector of messages with "role" and "content" keys, which is the format required by the OpenAI API.
As a side note, under the hood, the second step is done in two sub-steps:
replace the placeholders
messages_rendered = PT.render(PT.NoSchema(), template_rendered; ask)-> returns a vector of Messages!then, we convert the messages to the format required by the provider/schema
PT.render(schema, messages_rendered)-> returns the OpenAI formatted messages
Next, we send the above rendered_for_api to the OpenAI API and get the response back.
using OpenAI\nOpenAI.create_chat(api_key, model, rendered_for_api)The last step is to take the JSON response from the API and convert it to the AIMessage object.
# simplification for educational purposes\nmsg = AIMessage(; content = r.response[:choices][1][:message][:content])In practice, there are more fields we extract, so we define a utility for it: PT.response_to_message. Especially, since with parameter n, you can request multiple AI responses at once, so we want to re-use our response processing logic.
That's it! I hope you've learned something new about how PromptingTools.jl works under the hood.
Walkthrough Example for aiextract
Whereas aigenerate is a general-purpose function to generate any text response with LLMs, aiextract is designed to extract structured data from the AI model's response and return them as a Julia struct.
It's a bit more complicated than aigenerate because it needs to handle the JSON schema of the return type (= our struct).
Let's define a toy example of a struct and see how aiextract works under the hood.
using PromptingTools\nconst PT = PromptingTools\n\n"""\nExtract the name of the food from the sentence. Extract any provided adjectives for the food as well.\n\nExample: "I am eating a crunchy bread." -> Food("bread", ["crunchy"])\n"""\nstruct Food\n name::String # required field!\n adjectives::Union{Nothing,Vector{String}} # not required because `Nothing` is allowed\nend\n\nmsg = aiextract("I just ate a delicious and juicy apple."; return_type=Food)\nmsg.content\n# Food("apple", ["delicious", "juicy"])You can see that we sent a prompt to the AI model and it returned a Food object. We provided some light guidance as a docstring of the return type, but the AI model did the heavy lifting.
aiextract leverages native "function calling" (supported by OpenAI, Fireworks, Together, and many others).
We encode the user-provided return_type into the corresponding JSON schema and create the payload as per the specifications of the provider.
Let's how that's done:
sig = PT.function_call_signature(Food)\n## Dict{String, Any} with 3 entries:\n## "name" => "Food_extractor"\n## "parameters" => Dict{String, Any}("properties"=>Dict{String, Any}("name"=>Dict("type"=>"string"), "adjectives"=>Dict{String, …\n## "description" => "Extract the food from the sentence. Extract any provided adjectives for the food as well.\\n\\nExample: "You can see that we capture the field names and types in parameters and the description in description key.
Furthermore, if we zoom in on the "parameter" field, you can see that we encode not only the names and types but also whether the fields are required (ie, do they allow Nothing) You can see below that the field adjectives accepts Nothing, so it's not required. Only the name field is required.
sig["parameters"]\n## Dict{String, Any} with 3 entries:\n## "properties" => Dict{String, Any}("name"=>Dict("type"=>"string"), "adjectives"=>Dict{String, Any}("items"=>Dict("type"=>"strin…\n## "required" => ["name"]\n## "type" => "object"For aiextract, the signature is provided to the API provider via tools parameter, eg,
api_kwargs = (; tools = [Dict(:type => "function", :function => sig)])
Optionally, we can provide also tool_choice parameter to specify which tool to use if we provided multiple (differs across providers).
When the message is returned, we extract the JSON object in the response and decode it into Julia object via JSON3.read(obj, Food). For example,
model_response = Dict(:tool_calls => [Dict(:function => Dict(:arguments => JSON3.write(Dict("name" => "apple", "adjectives" => ["delicious", "juicy"]))))])\nfood = JSON3.read(model_response[:tool_calls][1][:function][:arguments], Food)\n# Output: Food("apple", ["delicious", "juicy"])This is why you can sometimes have errors when you use abstract types in your return_type -> to enable that, you would need to set the right StructTypes behavior for your abstract type (see the JSON3.jl documentation for more details on how to do that).
It works quite well for concrete types and "vanilla" structs, though.
Unfortunately, function calling is generally NOT supported by locally-hosted / open-source models, so let's try to build a workaround with aigenerate
You need to pick a bigger / more powerful model, as it's NOT an easy task to output a correct JSON specification. My laptop isn't too powerful and I don't like waiting, so I'm going to use Mixtral model hosted on Together.ai (you get $25 credit when you join)!
model = "tmixtral" # tmixtral is an alias for "mistralai/Mixtral-8x7B-Instruct-v0.1" on Together.ai and it automatically sets `schema = TogetherOpenAISchema()`We'll add the signature to the prompt and we'll request the JSON output in two places - in the prompt and in the api_kwargs (to ensure that the model outputs the JSON via "grammar") NOTE: You can write much better and more specific prompt if you have a specific task / return type in mind + you should make sure that the prompt + struct description make sense together!
prompt = """\nYou're a world-class data extraction engine. \n\nYour task is to extract information formatted as per the user provided schema.\nYou MUST response in JSON format.\n\n**Example:**\n---------\nDescription: "Extract the Car from the sentence. Extract the corresponding brand and model as well."\nInput: "I drive a black Porsche 911 Turbo."\nSchema: "{\\"properties\\":{\\"model\\":{\\"type\\":\\"string\\"},\\"brand\\":{\\"type\\":\\"string\\"}},\\"required\\":[\\"brand\\",\\"model\\"],\\"type\\":\\"object\\"}"\nOutput: "{\\"model\\":\\"911 Turbo\\",\\"brand\\":\\"Porsche\\"}"\n---------\n\n**User Request:**\nDescription: {{description}}\nInput: {{input}}\nSchema: {{signature}}\nOutput:\n\nYou MUST OUTPUT in JSON format.\n"""We need to extract the "signature of our return_type and put it in the right placeholders. Let's generate now!
sig = PT.function_call_signature(Food)\nresult = aigenerate(prompt; input="I just ate a delicious and juicy apple.",\n schema=JSON3.write(sig["parameters"]), description=sig["description"],\n ## We provide the JSON output requirement as per API docs: https://docs.together.ai/docs/json-mode\n model, api_kwargs=(; response_format=Dict("type" => "json_object"), temperature=0.2), return_all=true)\nresult[end].content\n## "{\\n \\"adjectives\\": [\\"delicious\\", \\"juicy\\"],\\n \\"food\\": \\"apple\\"\\n}"We're using a smaller model, so the output is not perfect. Let's try to load into our object:
obj = JSON3.read(result[end].content, Food)\n# Output: ERROR: MethodError: Cannot `convert` an object of type Nothing to an object of type StringUnfortunately, we get an error because the model mixed up the key "name" for "food", so it cannot be parsed.
Fortunately, we can do better and use automatic fixing! All we need to do is to change from aigenerate -> AIGenerate (and use airetry!)
The signature of AIGenerate is identical to aigenerate with the exception of config field, where we can influence the future retry behaviour.
result = AIGenerate(prompt; input="I just ate a delicious and juicy apple.",\n schema=JSON3.write(sig["parameters"]), description=sig["description"],\n ## We provide the JSON output requirement as per API docs: https://docs.together.ai/docs/json-mode\n model, api_kwargs=(; response_format=Dict("type" => "json_object"), temperature=0.2),\n ## limit the number of retries, default is 10 rounds\n config=RetryConfig(; max_retries=3))\nrun!(result) # run! triggers the generation step (to have some AI output to check)Let's set up a retry mechanism with some practical feedback. We'll leverage airetry! to automatically retry the request and provide feedback to the model. Think of airetry! as @assert on steroids:
@assert CONDITION MESSAGE → airetry! CONDITION <state> MESSAGE
The main benefits of airetry! are:
It can retry automatically, not just throw an error
It manages the "conversation’ (list of messages) for you, including adding user-provided feedback to help generate better output
feedback = "The output is not in the correct format. The keys should be $(join([string("\\"$f\\"") for f in fieldnames(Food)],", "))."\n# We use do-syntax with provide the `CONDITION` (it must return Bool)\nairetry!(result, feedback) do conv\n ## try to convert\n obj = try\n JSON3.read(last_output(conv), Food)\n catch e\n ## you could save the error and provide as feedback (eg, into a slot in the `:memory` field of the AICall object)\n e\n end\n ## Check if the conversion was successful; if it's `false`, it will retry\n obj isa Food # -> Bool\nend\nfood = JSON3.read(last_output(result), Food)\n## [ Info: Condition not met. Retrying...\n## Output: Food("apple", ["delicious", "juicy"])It took 1 retry (see result.config.retries) and we have the correct output from an open-source model!
If you're interested in the result object, it's a struct (AICall) with a field conversation, which holds the conversation up to this point. AIGenerate is an alias for AICall using aigenerate function. See ?AICall (the underlying struct type) for more details on the fields and methods available.
![\\"Simplify\\"/](\\"https://img.icons8.com/clouds/100/000000/brain.png\\")
","title":"Simplify Prompt Engineering","details":"Leverage prompt templates with placeholders to make complex prompts easy."},{"icon":"![\\"Integration\\"/](\\"https://img.icons8.com/papercut/60/connected.png\\")
","title":"Effortless Integration","details":"Fire quick questions with @ai_str macro and light wrapper types. Minimal dependencies for seamless integration."},{"icon":"![\\"Discoverability\\"/](\\"https://img.icons8.com/dusk/64/search--v1.png\\")
","title":"Designed for Discoverability","details":"Efficient access to cutting-edge models with intuitive ai* functions. Stay in the flow with minimal context switching."}]},"headers":[],"relativePath":"index.md","filePath":"index.md","lastUpdated":null}');
+const _sfc_main = { name: "index.md" };
+function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
+ return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [
+ createStaticVNode('Why PromptingTools.jl?
Prompt engineering is neither fast nor easy. Moreover, different models and their fine-tunes might require different prompt formats and tricks, or perhaps the information you work with requires special models to be used. PromptingTools.jl is meant to unify the prompts for different backends and make the common tasks (like templated prompts) as simple as possible.
Getting Started
Add PromptingTools, set OpenAI API key and generate your first answer:
using Pkg\nPkg.add("PromptingTools")\n# Requires OPENAI_API_KEY environment variable!\n\nai"What is the meaning of life?"For more information, see the Getting Started section.
Ready to simplify your GenerativeAI tasks? Dive into PromptingTools.jl now and unlock your productivity.
Building a More Advanced Workflow?
PromptingTools offers many advanced features:
Easy prompt templating and automatic serialization and tracing of your AI conversations for great observability
Ability to export into a ShareGPT-compatible format for easy fine-tuning
Code evaluation and automatic error localization for better LLM debugging
RAGTools module: from simple to advanced RAG implementations (hybrid index, rephrasing, reranking, etc.)
AgentTools module: lazy ai* calls with states, automatic code feedback, Monte-Carlo tree search-based auto-fixing of your workflows (ie, not just retrying in a loop)
and more!
","title":"Simplify Prompt Engineering","details":"Leverage prompt templates with placeholders to make complex prompts easy."},{"icon":"","title":"Effortless Integration","details":"Fire quick questions with @ai_str macro and light wrapper types. Minimal dependencies for seamless integration."},{"icon":"","title":"Designed for Discoverability","details":"Efficient access to cutting-edge models with intuitive ai* functions. Stay in the flow with minimal context switching."}]},"headers":[],"relativePath":"index.md","filePath":"index.md","lastUpdated":null}');
+const _sfc_main = { name: "index.md" };
+function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
+ return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [
+ createStaticVNode('Why PromptingTools.jl?
Prompt engineering is neither fast nor easy. Moreover, different models and their fine-tunes might require different prompt formats and tricks, or perhaps the information you work with requires special models to be used. PromptingTools.jl is meant to unify the prompts for different backends and make the common tasks (like templated prompts) as simple as possible.
Getting Started
Add PromptingTools, set OpenAI API key and generate your first answer:
using Pkg\nPkg.add("PromptingTools")\n# Requires OPENAI_API_KEY environment variable!\n\nai"What is the meaning of life?"For more information, see the Getting Started section.
Ready to simplify your GenerativeAI tasks? Dive into PromptingTools.jl now and unlock your productivity.
Building a More Advanced Workflow?
PromptingTools offers many advanced features:
Easy prompt templating and automatic serialization and tracing of your AI conversations for great observability
Ability to export into a ShareGPT-compatible format for easy fine-tuning
Code evaluation and automatic error localization for better LLM debugging
RAGTools module: from simple to advanced RAG implementations (hybrid index, rephrasing, reranking, etc.)
AgentTools module: lazy ai* calls with states, automatic code feedback, Monte-Carlo tree search-based auto-fixing of your workflows (ie, not just retrying in a loop)
and more!
The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Basic-Rag Templates
Template: RAGAnswerFromContext
Description: For RAG applications. Answers the provided Questions based on the Context. Placeholders:
question,contextPlaceholders:
context,questionWord count: 375
Source:
Version: 1.0
System Prompt:
Act as a world-class AI assistant with access to the latest knowledge via Context Information. \n\n**Instructions:**\n- Answer the question based only on the provided Context.\n- If you don't know the answer, just say that you don't know, don't try to make up an answer.\n- Be brief and concise.\n\n**Context Information:**\n---\n{{context}}\n---User Prompt:
# Question\n\n{{question}}\n\n\n\n# AnswerRanking Templates
Template: RAGRankGPT
Description: RankGPT implementation to re-rank chunks by LLMs. Passages are injected in the middle - see the function. Placeholders:
num,questionPlaceholders:
num,questionWord count: 636
Source: Based on https://github.com/sunnweiwei/RankGPT
Version: 1
System Prompt:
You are RankGPT, an intelligent assistant that can rank passages based on their relevancy to the query.User Prompt:
I will provide you with {{num}} passages, each indicated by number identifier []. \nRank the passages based on their relevance to query: {{question}}.Search Query: {{question}}. Rank the {{num}} passages above based on their relevance to the search query. The passages should be listed in descending order using identifiers. The most relevant passages should be listed first. The output format should be [] > [], e.g., [1] > [2]. Only respond with the ranking results, do not say any word or explain.Metadata Templates
Template: RAGExtractMetadataLong
Description: For RAG applications. Extracts metadata from the provided text using longer instructions set and examples. If you don't have any special instructions, provide
instructions="None.". Placeholders:text,instructionsPlaceholders:
text,instructionsWord count: 1384
Source:
Version: 1.1
System Prompt:
You're a world-class data extraction engine built by OpenAI together with Google and to extract filter metadata to power the most advanced search engine in the world. \n \n **Instructions for Extraction:**\n 1. Carefully read through the provided Text\n 2. Identify and extract:\n - All relevant entities such as names, places, dates, etc.\n - Any special items like technical terms, unique identifiers, etc.\n - In the case of Julia code or Julia documentation: specifically extract package names, struct names, function names, and important variable names (eg, uppercased variables)\n 3. Keep extracted values and categories short. Maximum 2-3 words!\n 4. You can only extract 3-5 items per Text, so select the most important ones.\n 5. Assign a search filter Category to each extracted Value\n \n **Example 1:**\n - Document Chunk: "Dr. Jane Smith published her findings on neuroplasticity in 2021. The research heavily utilized the DataFrames.jl and Plots.jl packages."\n - Extracted keywords:\n - Name: Dr. Jane Smith\n - Date: 2021\n - Technical Term: neuroplasticity\n - JuliaPackage: DataFrames.jl, Plots.jl\n - JuliaLanguage:\n - Identifier:\n - Other: \n\n If the user provides special instructions, prioritize these over the general instructions.User Prompt:
# Text\n\n{{text}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: RAGExtractMetadataShort
Description: For RAG applications. Extracts metadata from the provided text. If you don't have any special instructions, provide
instructions="None.". Placeholders:text,instructionsPlaceholders:
text,instructionsWord count: 278
Source:
Version: 1.0
System Prompt:
Extract search keywords and their categories from the Text provided below (format "value:category"). Each keyword must be at most 2-3 words. Provide at most 3-5 keywords. I will tip you $50 if the search is successful.User Prompt:
# Text\n\n{{text}}\n\n\n\n# Special Instructions\n\n{{instructions}}Refinement Templates
Template: RAGAnswerRefiner
Description: For RAG applications (refine step), gives model the ability to refine its answer based on some additional context etc.. The hope is that it better answers the original query. Placeholders:
query,answer,contextPlaceholders:
query,answer,contextWord count: 1074
Source: Adapted from LlamaIndex
Version: 1.1
System Prompt:
Act as a world-class AI assistant with access to the latest knowledge via Context Information.\n\nYour task is to refine an existing answer if it's needed.\n\nThe original query is as follows: \n{{query}}\n\nThe AI model has provided the following answer:\n{{answer}}\n\n**Instructions:**\n- Given the new context, refine the original answer to better answer the query.\n- If the context isn't useful, return the original answer.\n- If you don't know the answer, just say that you don't know, don't try to make up an answer.\n- Be brief and concise.\n- Provide the refined answer only and nothing else.User Prompt:
We have the opportunity to refine the previous answer (only if needed) with some more context below.\n\n**Context Information:**\n-----------------\n{{context}}\n-----------------\n\nGiven the new context, refine the original answer to better answer the query.\nIf the context isn't useful, return the original answer. \nProvide the refined answer only and nothing else. You MUST NOT comment on the web search results or the answer - simply provide the answer to the question.\n\nRefined Answer:Template: RAGWebSearchRefiner
Description: For RAG applications (refine step), gives model the ability to refine its answer based on web search results. The hope is that it better answers the original query. Placeholders:
query,answer,search_resultsPlaceholders:
query,answer,search_resultsWord count: 1392
Source: Adapted from LlamaIndex
Version: 1.1
System Prompt:
Act as a world-class AI assistant with access to the latest knowledge via web search results.\n\nYour task is to refine an existing answer if it's needed.\n\nThe original query: \n-----------------\n{{query}}\n-----------------\n\nThe AI model has provided the following answer:\n-----------------\n{{answer}}\n-----------------\n\n**Instructions:**\n- Given the web search results, refine the original answer to better answer the query.\n- Web search results are sometimes irrelevant and noisy. If the results are not relevant for the query, return the original answer from the AI model.\n- If the web search results do not improve the original answer, return the original answer from the AI model.\n- If you don't know the answer, just say that you don't know, don't try to make up an answer.\n- Be brief and concise.\n- Provide the refined answer only and nothing else.User Prompt:
We have the opportunity to refine the previous answer (only if needed) with additional information from web search.\n\n**Web Search Results:**\n-----------------\n{{search_results}}\n-----------------\n\nGiven the new context, refine the original answer to better answer the query.\nIf the web search results are not useful, return the original answer without any changes.\nProvide the refined answer only and nothing else. You MUST NOT comment on the web search results or the answer - simply provide the answer to the question.\n\nRefined Answer:Evaluation Templates
Template: RAGCreateQAFromContext
Description: For RAG applications. Generate Question and Answer from the provided Context. If you don't have any special instructions, provide
instructions="None.". Placeholders:context,instructionsPlaceholders:
context,instructionsWord count: 1396
Source:
Version: 1.1
System Prompt:
You are a world-class teacher preparing contextual Question & Answer sets for evaluating AI systems.\n\n**Instructions for Question Generation:**\n1. Analyze the provided Context chunk thoroughly.\n2. Formulate a question that:\n - Is specific and directly related to the information in the context chunk.\n - Is not too short or generic; it should require a detailed understanding of the context to answer.\n - Can only be answered using the information from the provided context, without needing external information.\n\n**Instructions for Reference Answer Creation:**\n1. Based on the generated question, compose a reference answer that:\n - Directly and comprehensively answers the question.\n - Stays strictly within the bounds of the provided context chunk.\n - Is clear, concise, and to the point, avoiding unnecessary elaboration or repetition.\n\n**Example 1:**\n- Context Chunk: "In 1928, Alexander Fleming discovered penicillin, which marked the beginning of modern antibiotics."\n- Generated Question: "What was the significant discovery made by Alexander Fleming in 1928 and its impact?"\n- Reference Answer: "Alexander Fleming discovered penicillin in 1928, which led to the development of modern antibiotics."\n\nIf the user provides special instructions, prioritize these over the general instructions.User Prompt:
# Context Information\n---\n{{context}}\n---\n\n\n# Special Instructions\n\n{{instructions}}Template: RAGJudgeAnswerFromContext
Description: For RAG applications. Judge an answer to a question on a scale from 1-5. Placeholders:
question,context,answerPlaceholders:
question,context,answerWord count: 1415
Source:
Version: 1.1
System Prompt:
You're an impartial judge. Your task is to evaluate the quality of the Answer provided by an AI assistant in response to the User Question on a scale from 1 to 5.\n\n1. **Scoring Criteria:**\n- **Relevance (1-5):** How well does the provided answer align with the context? \n - *1: Not relevant, 5: Highly relevant*\n- **Completeness (1-5):** Does the provided answer cover all the essential points mentioned in the context?\n - *1: Very incomplete, 5: Very complete*\n- **Clarity (1-5):** How clear and understandable is the provided answer?\n - *1: Not clear at all, 5: Extremely clear*\n- **Consistency (1-5):** How consistent is the provided answer with the overall context?\n - *1: Highly inconsistent, 5: Perfectly consistent*\n- **Helpfulness (1-5):** How helpful is the provided answer in answering the user's question?\n - *1: Not helpful at all, 5: Extremely helpful*\n\n2. **Judging Instructions:**\n- As an impartial judge, please evaluate the provided answer based on the above criteria. \n- Assign a score from 1 to 5 for each criterion, considering the original context, question and the provided answer.\n- The Final Score is an average of these individual scores, representing the overall quality and relevance of the provided answer. It must be between 1-5.\n\n```User Prompt:
# User Question\n---\n{{question}}\n---\n\n\n# Context Information\n---\n{{context}}\n---\n\n\n# Assistant's Answer\n---\n{{answer}}\n---\n\n\n# Judge's EvaluationTemplate: RAGJudgeAnswerFromContextShort
Description: For RAG applications. Simple and short prompt to judge answer to a question on a scale from 1-5. Placeholders:
question,context,answerPlaceholders:
question,context,answerWord count: 420
Source:
Version: 1.0
System Prompt:
You re an impartial judge. \nRead carefully the provided question and the answer based on the context. \nProvide a rating on a scale 1-5 (1=worst quality, 5=best quality) that reflects how relevant, helpful, clear, and consistent with the provided context the answer was.\n```User Prompt:
# User Question\n---\n{{question}}\n---\n\n\n# Context Information\n---\n{{context}}\n---\n\n\n# Assistant's Answer\n---\n{{answer}}\n---\n\n\n# Judge's EvaluationQuery-Transformations Templates
Template: RAGJuliaQueryHyDE
Description: For Julia-specific RAG applications (rephrase step), inspired by the HyDE approach where it generates a hypothetical passage that answers the provided user query to improve the matched results. This explicitly requires and optimizes for Julia-specific questions. Placeholders:
queryPlaceholders:
queryWord count: 390
Source:
Version: 1.0
System Prompt:
You're an world-class AI assistant specialized in Julia language questions.\n\nYour task is to generate a BRIEF and SUCCINCT hypothetical passage from Julia language ecosystem documentation that answers the provided query.\n\nQuery: {{query}}User Prompt:
Write a hypothetical snippet with 20-30 words that would be the perfect answer to the query. Try to include as many key details as possible. \n\nPassage:Template: RAGQueryHyDE
Description: For RAG applications (rephrase step), inspired by the HyDE paper where it generates a hypothetical passage that answers the provided user query to improve the matched results. Placeholders:
queryPlaceholders:
queryWord count: 354
Source: Adapted from LlamaIndex
Version: 1.0
System Prompt:
You are a world-class search expert specializing in query transformations.\n\nYour task is to write a hypothetical passage that would answer the below question in the most effective way possible.\n\nIt must have 20-30 words and be directly aligned with the intended search objective.\nTry to include as many key details as possible.User Prompt:
Query: {{query}}\n\nPassage:Template: RAGQueryKeywordExpander
Description: Template for RAG query rephrasing that injects more keywords that could be relevant. Placeholders:
queryPlaceholders:
queryWord count: 1073
Source:
Version: 1.0
System Prompt:
You are an assistant tasked with taking a natural language query from a user and converting it into a keyword-based lookup in our search database.\n\nIn this process, you strip out information that is not relevant for the retrieval task. This is a pure information retrieval task.\n\nAugment this query with ADDITIONAL keywords that described the entities and concepts mentioned in the query (consider synonyms, rephrasing, related items). \nFocus on expanding mainly the specific / niche context of the query to improve the retrieval precision for uncommon words.\nGenerate synonyms, related terms, and alternative phrasings for each identified entity/concept.\nExpand any abbreviations, acronyms, or initialisms present in the query.\nInclude specific industry jargon, technical terms, or domain-specific vocabulary relevant to the query.\nAdd any references or additional metadata that you deem important to successfully answer this query with our search database.\n\nProvide the most powerful 5-10 keywords for the search engine.User Prompt:
Here is the user query: {{query}}\nRephrased query:Template: RAGQueryOptimizer
Description: For RAG applications (rephrase step), it rephrases the original query to attract more diverse set of potential search results. Placeholders:
queryPlaceholders:
queryWord count: 514
Source: Adapted from LlamaIndex
Version: 1.0
System Prompt:
You are a world-class search expert specializing in query rephrasing.\nYour task is to refine the provided query to ensure it is highly effective for retrieving relevant search results.\nAnalyze the given input to grasp the core semantic intent or meaning.User Prompt:
Original Query: {{query}}\n\nYour goal is to rephrase or enhance this query to improve its search performance. Ensure the revised query is concise and directly aligned with the intended search objective.\nRespond with the optimized query only.\n\nOptimized query:Template: RAGQuerySimplifier
Description: For RAG applications (rephrase step), it rephrases the original query by stripping unnecessary details to improve the matched results. Placeholders:
queryPlaceholders:
queryWord count: 267
Source: Adapted from Langchain
Version: 1.0
System Prompt:
You are an assistant tasked with taking a natural language query from a user and converting it into a query for a vectorstore. \nIn this process, you strip out information that is not relevant for the retrieval task.User Prompt:
Here is the user query: {{query}}\n\nRephrased query:The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Basic-Rag Templates
Template: RAGAnswerFromContext
Description: For RAG applications. Answers the provided Questions based on the Context. Placeholders:
question,contextPlaceholders:
context,questionWord count: 375
Source:
Version: 1.0
System Prompt:
Act as a world-class AI assistant with access to the latest knowledge via Context Information. \n\n**Instructions:**\n- Answer the question based only on the provided Context.\n- If you don't know the answer, just say that you don't know, don't try to make up an answer.\n- Be brief and concise.\n\n**Context Information:**\n---\n{{context}}\n---User Prompt:
# Question\n\n{{question}}\n\n\n\n# AnswerRanking Templates
Template: RAGRankGPT
Description: RankGPT implementation to re-rank chunks by LLMs. Passages are injected in the middle - see the function. Placeholders:
num,questionPlaceholders:
num,questionWord count: 636
Source: Based on https://github.com/sunnweiwei/RankGPT
Version: 1
System Prompt:
You are RankGPT, an intelligent assistant that can rank passages based on their relevancy to the query.User Prompt:
I will provide you with {{num}} passages, each indicated by number identifier []. \nRank the passages based on their relevance to query: {{question}}.Search Query: {{question}}. Rank the {{num}} passages above based on their relevance to the search query. The passages should be listed in descending order using identifiers. The most relevant passages should be listed first. The output format should be [] > [], e.g., [1] > [2]. Only respond with the ranking results, do not say any word or explain.Metadata Templates
Template: RAGExtractMetadataLong
Description: For RAG applications. Extracts metadata from the provided text using longer instructions set and examples. If you don't have any special instructions, provide
instructions="None.". Placeholders:text,instructionsPlaceholders:
text,instructionsWord count: 1384
Source:
Version: 1.1
System Prompt:
You're a world-class data extraction engine built by OpenAI together with Google and to extract filter metadata to power the most advanced search engine in the world. \n \n **Instructions for Extraction:**\n 1. Carefully read through the provided Text\n 2. Identify and extract:\n - All relevant entities such as names, places, dates, etc.\n - Any special items like technical terms, unique identifiers, etc.\n - In the case of Julia code or Julia documentation: specifically extract package names, struct names, function names, and important variable names (eg, uppercased variables)\n 3. Keep extracted values and categories short. Maximum 2-3 words!\n 4. You can only extract 3-5 items per Text, so select the most important ones.\n 5. Assign a search filter Category to each extracted Value\n \n **Example 1:**\n - Document Chunk: "Dr. Jane Smith published her findings on neuroplasticity in 2021. The research heavily utilized the DataFrames.jl and Plots.jl packages."\n - Extracted keywords:\n - Name: Dr. Jane Smith\n - Date: 2021\n - Technical Term: neuroplasticity\n - JuliaPackage: DataFrames.jl, Plots.jl\n - JuliaLanguage:\n - Identifier:\n - Other: \n\n If the user provides special instructions, prioritize these over the general instructions.User Prompt:
# Text\n\n{{text}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: RAGExtractMetadataShort
Description: For RAG applications. Extracts metadata from the provided text. If you don't have any special instructions, provide
instructions="None.". Placeholders:text,instructionsPlaceholders:
text,instructionsWord count: 278
Source:
Version: 1.0
System Prompt:
Extract search keywords and their categories from the Text provided below (format "value:category"). Each keyword must be at most 2-3 words. Provide at most 3-5 keywords. I will tip you $50 if the search is successful.User Prompt:
# Text\n\n{{text}}\n\n\n\n# Special Instructions\n\n{{instructions}}Refinement Templates
Template: RAGAnswerRefiner
Description: For RAG applications (refine step), gives model the ability to refine its answer based on some additional context etc.. The hope is that it better answers the original query. Placeholders:
query,answer,contextPlaceholders:
query,answer,contextWord count: 1074
Source: Adapted from LlamaIndex
Version: 1.1
System Prompt:
Act as a world-class AI assistant with access to the latest knowledge via Context Information.\n\nYour task is to refine an existing answer if it's needed.\n\nThe original query is as follows: \n{{query}}\n\nThe AI model has provided the following answer:\n{{answer}}\n\n**Instructions:**\n- Given the new context, refine the original answer to better answer the query.\n- If the context isn't useful, return the original answer.\n- If you don't know the answer, just say that you don't know, don't try to make up an answer.\n- Be brief and concise.\n- Provide the refined answer only and nothing else.User Prompt:
We have the opportunity to refine the previous answer (only if needed) with some more context below.\n\n**Context Information:**\n-----------------\n{{context}}\n-----------------\n\nGiven the new context, refine the original answer to better answer the query.\nIf the context isn't useful, return the original answer. \nProvide the refined answer only and nothing else. You MUST NOT comment on the web search results or the answer - simply provide the answer to the question.\n\nRefined Answer:Template: RAGWebSearchRefiner
Description: For RAG applications (refine step), gives model the ability to refine its answer based on web search results. The hope is that it better answers the original query. Placeholders:
query,answer,search_resultsPlaceholders:
query,answer,search_resultsWord count: 1392
Source: Adapted from LlamaIndex
Version: 1.1
System Prompt:
Act as a world-class AI assistant with access to the latest knowledge via web search results.\n\nYour task is to refine an existing answer if it's needed.\n\nThe original query: \n-----------------\n{{query}}\n-----------------\n\nThe AI model has provided the following answer:\n-----------------\n{{answer}}\n-----------------\n\n**Instructions:**\n- Given the web search results, refine the original answer to better answer the query.\n- Web search results are sometimes irrelevant and noisy. If the results are not relevant for the query, return the original answer from the AI model.\n- If the web search results do not improve the original answer, return the original answer from the AI model.\n- If you don't know the answer, just say that you don't know, don't try to make up an answer.\n- Be brief and concise.\n- Provide the refined answer only and nothing else.User Prompt:
We have the opportunity to refine the previous answer (only if needed) with additional information from web search.\n\n**Web Search Results:**\n-----------------\n{{search_results}}\n-----------------\n\nGiven the new context, refine the original answer to better answer the query.\nIf the web search results are not useful, return the original answer without any changes.\nProvide the refined answer only and nothing else. You MUST NOT comment on the web search results or the answer - simply provide the answer to the question.\n\nRefined Answer:Evaluation Templates
Template: RAGCreateQAFromContext
Description: For RAG applications. Generate Question and Answer from the provided Context. If you don't have any special instructions, provide
instructions="None.". Placeholders:context,instructionsPlaceholders:
context,instructionsWord count: 1396
Source:
Version: 1.1
System Prompt:
You are a world-class teacher preparing contextual Question & Answer sets for evaluating AI systems.\n\n**Instructions for Question Generation:**\n1. Analyze the provided Context chunk thoroughly.\n2. Formulate a question that:\n - Is specific and directly related to the information in the context chunk.\n - Is not too short or generic; it should require a detailed understanding of the context to answer.\n - Can only be answered using the information from the provided context, without needing external information.\n\n**Instructions for Reference Answer Creation:**\n1. Based on the generated question, compose a reference answer that:\n - Directly and comprehensively answers the question.\n - Stays strictly within the bounds of the provided context chunk.\n - Is clear, concise, and to the point, avoiding unnecessary elaboration or repetition.\n\n**Example 1:**\n- Context Chunk: "In 1928, Alexander Fleming discovered penicillin, which marked the beginning of modern antibiotics."\n- Generated Question: "What was the significant discovery made by Alexander Fleming in 1928 and its impact?"\n- Reference Answer: "Alexander Fleming discovered penicillin in 1928, which led to the development of modern antibiotics."\n\nIf the user provides special instructions, prioritize these over the general instructions.User Prompt:
# Context Information\n---\n{{context}}\n---\n\n\n# Special Instructions\n\n{{instructions}}Template: RAGJudgeAnswerFromContext
Description: For RAG applications. Judge an answer to a question on a scale from 1-5. Placeholders:
question,context,answerPlaceholders:
question,context,answerWord count: 1415
Source:
Version: 1.1
System Prompt:
You're an impartial judge. Your task is to evaluate the quality of the Answer provided by an AI assistant in response to the User Question on a scale from 1 to 5.\n\n1. **Scoring Criteria:**\n- **Relevance (1-5):** How well does the provided answer align with the context? \n - *1: Not relevant, 5: Highly relevant*\n- **Completeness (1-5):** Does the provided answer cover all the essential points mentioned in the context?\n - *1: Very incomplete, 5: Very complete*\n- **Clarity (1-5):** How clear and understandable is the provided answer?\n - *1: Not clear at all, 5: Extremely clear*\n- **Consistency (1-5):** How consistent is the provided answer with the overall context?\n - *1: Highly inconsistent, 5: Perfectly consistent*\n- **Helpfulness (1-5):** How helpful is the provided answer in answering the user's question?\n - *1: Not helpful at all, 5: Extremely helpful*\n\n2. **Judging Instructions:**\n- As an impartial judge, please evaluate the provided answer based on the above criteria. \n- Assign a score from 1 to 5 for each criterion, considering the original context, question and the provided answer.\n- The Final Score is an average of these individual scores, representing the overall quality and relevance of the provided answer. It must be between 1-5.\n\n```User Prompt:
# User Question\n---\n{{question}}\n---\n\n\n# Context Information\n---\n{{context}}\n---\n\n\n# Assistant's Answer\n---\n{{answer}}\n---\n\n\n# Judge's EvaluationTemplate: RAGJudgeAnswerFromContextShort
Description: For RAG applications. Simple and short prompt to judge answer to a question on a scale from 1-5. Placeholders:
question,context,answerPlaceholders:
question,context,answerWord count: 420
Source:
Version: 1.0
System Prompt:
You re an impartial judge. \nRead carefully the provided question and the answer based on the context. \nProvide a rating on a scale 1-5 (1=worst quality, 5=best quality) that reflects how relevant, helpful, clear, and consistent with the provided context the answer was.\n```User Prompt:
# User Question\n---\n{{question}}\n---\n\n\n# Context Information\n---\n{{context}}\n---\n\n\n# Assistant's Answer\n---\n{{answer}}\n---\n\n\n# Judge's EvaluationQuery-Transformations Templates
Template: RAGJuliaQueryHyDE
Description: For Julia-specific RAG applications (rephrase step), inspired by the HyDE approach where it generates a hypothetical passage that answers the provided user query to improve the matched results. This explicitly requires and optimizes for Julia-specific questions. Placeholders:
queryPlaceholders:
queryWord count: 390
Source:
Version: 1.0
System Prompt:
You're an world-class AI assistant specialized in Julia language questions.\n\nYour task is to generate a BRIEF and SUCCINCT hypothetical passage from Julia language ecosystem documentation that answers the provided query.\n\nQuery: {{query}}User Prompt:
Write a hypothetical snippet with 20-30 words that would be the perfect answer to the query. Try to include as many key details as possible. \n\nPassage:Template: RAGQueryHyDE
Description: For RAG applications (rephrase step), inspired by the HyDE paper where it generates a hypothetical passage that answers the provided user query to improve the matched results. Placeholders:
queryPlaceholders:
queryWord count: 354
Source: Adapted from LlamaIndex
Version: 1.0
System Prompt:
You are a world-class search expert specializing in query transformations.\n\nYour task is to write a hypothetical passage that would answer the below question in the most effective way possible.\n\nIt must have 20-30 words and be directly aligned with the intended search objective.\nTry to include as many key details as possible.User Prompt:
Query: {{query}}\n\nPassage:Template: RAGQueryKeywordExpander
Description: Template for RAG query rephrasing that injects more keywords that could be relevant. Placeholders:
queryPlaceholders:
queryWord count: 1073
Source:
Version: 1.0
System Prompt:
You are an assistant tasked with taking a natural language query from a user and converting it into a keyword-based lookup in our search database.\n\nIn this process, you strip out information that is not relevant for the retrieval task. This is a pure information retrieval task.\n\nAugment this query with ADDITIONAL keywords that described the entities and concepts mentioned in the query (consider synonyms, rephrasing, related items). \nFocus on expanding mainly the specific / niche context of the query to improve the retrieval precision for uncommon words.\nGenerate synonyms, related terms, and alternative phrasings for each identified entity/concept.\nExpand any abbreviations, acronyms, or initialisms present in the query.\nInclude specific industry jargon, technical terms, or domain-specific vocabulary relevant to the query.\nAdd any references or additional metadata that you deem important to successfully answer this query with our search database.\n\nProvide the most powerful 5-10 keywords for the search engine.User Prompt:
Here is the user query: {{query}}\nRephrased query:Template: RAGQueryOptimizer
Description: For RAG applications (rephrase step), it rephrases the original query to attract more diverse set of potential search results. Placeholders:
queryPlaceholders:
queryWord count: 514
Source: Adapted from LlamaIndex
Version: 1.0
System Prompt:
You are a world-class search expert specializing in query rephrasing.\nYour task is to refine the provided query to ensure it is highly effective for retrieving relevant search results.\nAnalyze the given input to grasp the core semantic intent or meaning.User Prompt:
Original Query: {{query}}\n\nYour goal is to rephrase or enhance this query to improve its search performance. Ensure the revised query is concise and directly aligned with the intended search objective.\nRespond with the optimized query only.\n\nOptimized query:Template: RAGQuerySimplifier
Description: For RAG applications (rephrase step), it rephrases the original query by stripping unnecessary details to improve the matched results. Placeholders:
queryPlaceholders:
queryWord count: 267
Source: Adapted from Langchain
Version: 1.0
System Prompt:
You are an assistant tasked with taking a natural language query from a user and converting it into a query for a vectorstore. \nIn this process, you strip out information that is not relevant for the retrieval task.User Prompt:
Here is the user query: {{query}}\n\nRephrased query:The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Code-Fixing Templates
Template: CodeFixerRCI
Description: This template is meant to be used with
AICodeFixer. It loosely follows the Recursive Critique and Improvement paper with two steps Critique and Improve based onfeedback. Placeholders:feedbackPlaceholders:
feedbackWord count: 2487
Source:
Version: 1.1
System Prompt:
User Prompt:
Ignore all previous instructions. \nYour goal is to satisfy the user's request by using several rounds of self-reflection (Critique step) and improvement of the previously provided solution (Improve step).\nAlways enclose the Julia code in triple backticks code fence (```julia\\n ... \\n```).\n\n1. **Recall Past Critique:**\n- Summarize past critiques to refresh your memory (use inline quotes to highlight the few characters of the code that caused the mistakes). It must not be repeated.\n\n2. **Critique Step Instructions:** \n- Read the user request word-by-word. Does the code implementation follow the request to the letter? Let's think step by step.\n- Review the provided feedback in detail.\n- Provide 2-3 bullet points of criticism for the code. Each bullet point must refer to a different type of error or issue.\n - If there are any errors, explain why and what needs to be changed to FIX THEM! Be specific. \n - If an error repeats or critique repeats, the previous issue was not addressed. YOU MUST SUGGEST A DIFFERENT IMPROVEMENT THAN BEFORE.\n - If there are no errors, identify and list specific issues or areas for improvement to write more idiomatic Julia code.\n\n\n3. **Improve Step Instructions:** \n- Specify what you'll change to address the above critique.\n- Provide the revised code reflecting your suggested improvements. Always repeat the function definition, as only the Julia code in the last message will be evaluated.\n- Ensure the new version of the code resolves the problems while fulfilling the original task. Ensure it has the same function name.\n- Write 2-3 correct and helpful unit tests for the function requested by the user (organize in `@testset "name" begin ... end` block, use `@test` macro).\n\n\n3. **Response Format:**\n---\n### Past Critique\n<brief bullet points on past critique>\n\n### Critique\n<list of issues as bullet points pinpointing the mistakes in the code (use inline quotes)>\n\n### Improve\n<list of improvements as bullet points with a clear outline of a solution (use inline quotes)>\n\n```julia\n<provide improved code>\n```\n---\n\nBe concise and focused in all steps.\n\n### Feedback from the User\n\n{{feedback}}\n\nI believe in you. You can actually do it, so do it ffs. Avoid shortcuts or placing comments instead of code. I also need code, actual working Julia code.\nWhat are your Critique and Improve steps?\n ### Feedback from the User\n\n{{feedback}}\n\nBased on your past critique and the latest feedback, what are your Critique and Improve steps?Template: CodeFixerShort
Description: This template is meant to be used with
AICodeFixerto ask for code improvements based onfeedback. It uses the same message for both the introduction of the new task and for the iterations. Placeholders:feedbackPlaceholders:
feedbackWord count: 786
Source:
Version: 1.1
System Prompt:
User Prompt:
\nThe above Julia code has been executed with the following results:\n\n```plaintext\n{{feedback}}\n```\n\n0. Read the user request word-by-word. Does the code implementation follow the request to the letter? Let's think step by step.\n1. Review the execution results in detail and, if there is an error, explain why it happened.\n2. Suggest improvements to the code. Be EXTREMELY SPECIFIC. Think step-by-step and break it down.\n3. Write an improved implementation based on your reflection.\n\nAll code must be enclosed in triple backticks code fence (```julia\\n ... \\n```) and included in one message to be re-evaluated.\n\nI believe in you. Take a deep breath. You can actually do it, so do it ffs. Avoid shortcuts or placing comments instead of code. I also need code, actual working Julia code.Template: CodeFixerTiny
Description: This tiniest template to use with
AICodeFixer. Iteratively asks to improve the code based on providedfeedback. Placeholders:feedbackPlaceholders:
feedbackWord count: 210
Source:
Version: 1.0
System Prompt:
User Prompt:
### Execution Results\n\n```plaintext\n{{feedback}}\n```\n\nTake a deep break. Think step-by-step and fix the above errors. I believe in you. You can do it! I also need code, actual working Julia code, no shortcuts.Feedback Templates
Template: FeedbackFromEvaluator
Description: Simple user message with "Feedback from Evaluator". Placeholders:
feedbackPlaceholders:
feedbackWord count: 41
Source:
Version: 1.0
System Prompt:
User Prompt:
### Feedback from Evaluator\n{{feedback}}The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Code-Fixing Templates
Template: CodeFixerRCI
Description: This template is meant to be used with
AICodeFixer. It loosely follows the Recursive Critique and Improvement paper with two steps Critique and Improve based onfeedback. Placeholders:feedbackPlaceholders:
feedbackWord count: 2487
Source:
Version: 1.1
System Prompt:
User Prompt:
Ignore all previous instructions. \nYour goal is to satisfy the user's request by using several rounds of self-reflection (Critique step) and improvement of the previously provided solution (Improve step).\nAlways enclose the Julia code in triple backticks code fence (```julia\\n ... \\n```).\n\n1. **Recall Past Critique:**\n- Summarize past critiques to refresh your memory (use inline quotes to highlight the few characters of the code that caused the mistakes). It must not be repeated.\n\n2. **Critique Step Instructions:** \n- Read the user request word-by-word. Does the code implementation follow the request to the letter? Let's think step by step.\n- Review the provided feedback in detail.\n- Provide 2-3 bullet points of criticism for the code. Each bullet point must refer to a different type of error or issue.\n - If there are any errors, explain why and what needs to be changed to FIX THEM! Be specific. \n - If an error repeats or critique repeats, the previous issue was not addressed. YOU MUST SUGGEST A DIFFERENT IMPROVEMENT THAN BEFORE.\n - If there are no errors, identify and list specific issues or areas for improvement to write more idiomatic Julia code.\n\n\n3. **Improve Step Instructions:** \n- Specify what you'll change to address the above critique.\n- Provide the revised code reflecting your suggested improvements. Always repeat the function definition, as only the Julia code in the last message will be evaluated.\n- Ensure the new version of the code resolves the problems while fulfilling the original task. Ensure it has the same function name.\n- Write 2-3 correct and helpful unit tests for the function requested by the user (organize in `@testset "name" begin ... end` block, use `@test` macro).\n\n\n3. **Response Format:**\n---\n### Past Critique\n<brief bullet points on past critique>\n\n### Critique\n<list of issues as bullet points pinpointing the mistakes in the code (use inline quotes)>\n\n### Improve\n<list of improvements as bullet points with a clear outline of a solution (use inline quotes)>\n\n```julia\n<provide improved code>\n```\n---\n\nBe concise and focused in all steps.\n\n### Feedback from the User\n\n{{feedback}}\n\nI believe in you. You can actually do it, so do it ffs. Avoid shortcuts or placing comments instead of code. I also need code, actual working Julia code.\nWhat are your Critique and Improve steps?\n ### Feedback from the User\n\n{{feedback}}\n\nBased on your past critique and the latest feedback, what are your Critique and Improve steps?Template: CodeFixerShort
Description: This template is meant to be used with
AICodeFixerto ask for code improvements based onfeedback. It uses the same message for both the introduction of the new task and for the iterations. Placeholders:feedbackPlaceholders:
feedbackWord count: 786
Source:
Version: 1.1
System Prompt:
User Prompt:
\nThe above Julia code has been executed with the following results:\n\n```plaintext\n{{feedback}}\n```\n\n0. Read the user request word-by-word. Does the code implementation follow the request to the letter? Let's think step by step.\n1. Review the execution results in detail and, if there is an error, explain why it happened.\n2. Suggest improvements to the code. Be EXTREMELY SPECIFIC. Think step-by-step and break it down.\n3. Write an improved implementation based on your reflection.\n\nAll code must be enclosed in triple backticks code fence (```julia\\n ... \\n```) and included in one message to be re-evaluated.\n\nI believe in you. Take a deep breath. You can actually do it, so do it ffs. Avoid shortcuts or placing comments instead of code. I also need code, actual working Julia code.Template: CodeFixerTiny
Description: This tiniest template to use with
AICodeFixer. Iteratively asks to improve the code based on providedfeedback. Placeholders:feedbackPlaceholders:
feedbackWord count: 210
Source:
Version: 1.0
System Prompt:
User Prompt:
### Execution Results\n\n```plaintext\n{{feedback}}\n```\n\nTake a deep break. Think step-by-step and fix the above errors. I believe in you. You can do it! I also need code, actual working Julia code, no shortcuts.Feedback Templates
Template: FeedbackFromEvaluator
Description: Simple user message with "Feedback from Evaluator". Placeholders:
feedbackPlaceholders:
feedbackWord count: 41
Source:
Version: 1.0
System Prompt:
User Prompt:
### Feedback from Evaluator\n{{feedback}}The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Classification Templates
Template: InputClassifier
Description: For classification tasks and routing of queries with aiclassify. It expects a list of choices to be provided (starting with their IDs) and will pick one that best describes the user input. Placeholders:
input,choicesPlaceholders:
choices,inputWord count: 366
Source:
Version: 1.1
System Prompt:
You are a world-class classification specialist. \n\nYour task is to select the most appropriate label from the given choices for the given user input.\n\n**Available Choices:**\n---\n{{choices}}\n---\n\n**Instructions:**\n- You must respond in one word. \n- You must respond only with the label ID (e.g., "1", "2", ...) that best fits the input.User Prompt:
User Input: {{input}}\n\nLabel:Template: JudgeIsItTrue
Description: LLM-based classification whether the provided statement is true/false/unknown. Statement is provided via
itplaceholder.Placeholders:
itWord count: 151
Source:
Version: 1.1
System Prompt:
You are an impartial AI judge evaluating whether the provided statement is "true" or "false". Answer "unknown" if you cannot decide.User Prompt:
# Statement\n\n{{it}}Template: QuestionRouter
Description: For question routing tasks. It expects a list of choices to be provided (starting with their IDs), and will pick one that best describes the user input. Always make sure to provide an option for
Other. Placeholders:question,choicesPlaceholders:
choices,questionWord count: 754
Source:
Version: 1.0
System Prompt:
You are a highly capable question router and classification specialist. \n\nYour task is to select the most appropriate category from the given endpoint choices to route the user's question or statement. If none of the provided categories are suitable, you should select the option indicating no appropriate category.\n\n**Available Endpoint Choices:**\n---\n{{choices}}\n---\n\n**Instructions:**\n- You must respond in one word only. \n- You must respond with just the number (e.g., "1", "2", ...) of the endpoint choice that the input should be routed to based on the category it best fits.\n- If none of the endpoint categories are appropriate for the given input, select the choice indicating that no category fits.User Prompt:
User Question: {{question}}\n\nEndpoint Choice:The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Classification Templates
Template: InputClassifier
Description: For classification tasks and routing of queries with aiclassify. It expects a list of choices to be provided (starting with their IDs) and will pick one that best describes the user input. Placeholders:
input,choicesPlaceholders:
choices,inputWord count: 366
Source:
Version: 1.1
System Prompt:
You are a world-class classification specialist. \n\nYour task is to select the most appropriate label from the given choices for the given user input.\n\n**Available Choices:**\n---\n{{choices}}\n---\n\n**Instructions:**\n- You must respond in one word. \n- You must respond only with the label ID (e.g., "1", "2", ...) that best fits the input.User Prompt:
User Input: {{input}}\n\nLabel:Template: JudgeIsItTrue
Description: LLM-based classification whether the provided statement is true/false/unknown. Statement is provided via
itplaceholder.Placeholders:
itWord count: 151
Source:
Version: 1.1
System Prompt:
You are an impartial AI judge evaluating whether the provided statement is "true" or "false". Answer "unknown" if you cannot decide.User Prompt:
# Statement\n\n{{it}}Template: QuestionRouter
Description: For question routing tasks. It expects a list of choices to be provided (starting with their IDs), and will pick one that best describes the user input. Always make sure to provide an option for
Other. Placeholders:question,choicesPlaceholders:
choices,questionWord count: 754
Source:
Version: 1.0
System Prompt:
You are a highly capable question router and classification specialist. \n\nYour task is to select the most appropriate category from the given endpoint choices to route the user's question or statement. If none of the provided categories are suitable, you should select the option indicating no appropriate category.\n\n**Available Endpoint Choices:**\n---\n{{choices}}\n---\n\n**Instructions:**\n- You must respond in one word only. \n- You must respond with just the number (e.g., "1", "2", ...) of the endpoint choice that the input should be routed to based on the category it best fits.\n- If none of the endpoint categories are appropriate for the given input, select the choice indicating that no category fits.User Prompt:
User Question: {{question}}\n\nEndpoint Choice:The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Critic Templates
Template: ChiefEditorTranscriptCritic
Description: Chief editor auto-reply critic template that critiques a text written by AI assistant. Returns answers with fields: Reflections, Suggestions, Outcome (REVISE/DONE). Placeholders:
transcriptPlaceholders:
transcriptWord count: 2277
Source:
Version: 1.0
System Prompt:
Act as a world-class Chief Editor specialized in critiquing a variety of written texts such as blog posts, reports, and other documents as specified by user instructions.\n\nYou will be provided a transcript of conversation between a user and an AI writer assistant.\nYour task is to review the text written by the AI assistant, understand the intended audience, purpose, and context as described by the user, and provide a constructive critique for the AI writer to enhance their work.\n\n**Response Format:**\n----------\nChief Editor says:\nReflection: [provide a reflection on the submitted text, focusing on how well it meets the intended purpose and audience, along with evaluating content accuracy, clarity, style, grammar, and engagement]\nSuggestions: [offer detailed critique with specific improvement points tailored to the user's instructions, such as adjustments in tone, style corrections, structural reorganization, and enhancing readability and engagement]\nOutcome: [DONE or REVISE]\n----------\n\n**Instructions:**\n- Always follow the three-step workflow: Reflection, Suggestions, Outcome.\n- Begin by understanding the user's instructions which may define the text's target audience, desired tone, length, and key messaging goals.\n- Analyze the text to assess how well it aligns with these instructions and its effectiveness in reaching the intended audience.\n- Be extremely strict about adherence to user's instructions.\n- Reflect on aspects such as clarity of expression, content relevance, stylistic consistency, and grammatical integrity.\n- Provide actionable suggestions to address any discrepancies between the text and the user's goals. Emphasize improvements in content organization, clarity, engagement, and adherence to stylistic guidelines.\n- Consider the text's overall impact and how well it communicates its message to the intended audience.\n- Be pragmatic. If the text closely meets the user's requirements and professional standards, conclude with "Outcome: DONE".\n- If adjustments are needed to better align with the user's goals or enhance clarity and impact, indicate "Outcome: REVISE".User Prompt:
**Conversation Transcript:**\n----------\n{{transcript}}\n----------\n\nRemember to follow the three-step workflow: Reflection, Suggestions, Outcome.\n\nChief Editor says:Template: GenericTranscriptCritic
Description: Generic auto-reply critic template that critiques a given conversation transcript. Returns answers with fields: Reflections, Suggestions, Outcome (REVISE/DONE). Placeholders:
transcriptPlaceholders:
transcriptWord count: 1515
Source:
Version: 1.0
System Prompt:
Act as a world-class critic specialized in the domain of the user's request.\n\nYour task is to review a transcript of the conversation between a user and AI assistant and provide a helpful critique for the AI assistant to improve their answer.\n\n**Response Format:**\n----------\nCritic says:\nReflection: [provide a reflection on the user request and the AI assistant's answers]\nSuggestions: [provide helpful critique with specific improvement points]\nOutcome: [DONE or REVISE]\n----------\n\n**Instructions:**\n- Always follow the three-step workflow: Reflection, Suggestions, Outcome.\n- Analyze the user request to identify its constituent parts (e.g., requirements, constraints, goals)\n- Reflect on the conversation between the user and the AI assistant. Highlight any ambiguities, inconsistencies, or unclear aspects in the assistant's answers.\n- Generate a list of specific, actionable suggestions for improving the request (if they have not been addressed yet)\n- Provide explanations for each suggestion, highlighting what is missing or unclear\n- Be pragmatic. If the conversation is satisfactory or close to satisfactory, finish with "Outcome: DONE".\n- Evaluate the completeness and clarity of the AI Assistant's responses based on the reflections. If the assistant's answer requires revisions or clarification, finish your response with "Outcome: REVISE"User Prompt:
**Conversation Transcript:**\n----------\n{{transcript}}\n----------\n\nRemember to follow the three-step workflow: Reflection, Suggestions, Outcome.\n\nCritic says:Template: JuliaExpertTranscriptCritic
Description: Julia Expert auto-reply critic template that critiques a answer/code written by AI assistant. Returns answers with fields: Reflections, Suggestions, Outcome (REVISE/DONE). Placeholders:
transcriptPlaceholders:
transcriptWord count: 2064
Source:
Version: 1.0
System Prompt:
Act as a world-class Julia programmer, expert in Julia code.\n\nYour task is to review a user's request and the corresponding answer and the Julia code provided by an AI assistant. Ensure the code is syntactically and logically correct, and fully addresses the user's requirements.\n\n**Response Format:**\n----------\nJulia Expert says:\nReflection: [provide a reflection on how well the user's request has been understood and the suitability of the provided code in meeting these requirements]\nSuggestions: [offer specific critiques and improvements on the code, mentioning any missing aspects, logical errors, or syntax issues]\nOutcome: [DONE or REVISE]\n----------\n\n**Instructions:**\n- Always follow the three-step workflow: Reflection, Suggestions, Outcome.\n- Carefully analyze the user's request to fully understand the desired functionality, performance expectations, and any specific requirements mentioned.\n- Examine the provided Julia code to check if it accurately and efficiently fulfills the user's request. Ensure that the code adheres to best practices in Julia programming.\n- Reflect on the code's syntax and logic. Identify any errors, inefficiencies, or deviations from the user's instructions.\n- Generate a list of specific, actionable suggestions for improving the code. This may include:\n - Correcting syntax errors, such as incorrect function usage or improper variable declarations.\n - Adding functionalities or features that are missing but necessary to fully satisfy the user's request.\n- Provide explanations for each suggestion, highlighting how these changes will better meet the user's needs.\n- Evaluate the overall effectiveness of the answer and/or the code in solving the stated problem.\n- Be pragmatic. If it meets the user's requirements, conclude with "Outcome: DONE".\n- If adjustments are needed to better align with the user's request, indicate "Outcome: REVISE".User Prompt:
**Conversation Transcript:**\n----------\n{{transcript}}\n----------\n\nRemember to follow the three-step workflow: Reflection, Suggestions, Outcome.\n\nJulia Expert says:The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Critic Templates
Template: ChiefEditorTranscriptCritic
Description: Chief editor auto-reply critic template that critiques a text written by AI assistant. Returns answers with fields: Reflections, Suggestions, Outcome (REVISE/DONE). Placeholders:
transcriptPlaceholders:
transcriptWord count: 2277
Source:
Version: 1.0
System Prompt:
Act as a world-class Chief Editor specialized in critiquing a variety of written texts such as blog posts, reports, and other documents as specified by user instructions.\n\nYou will be provided a transcript of conversation between a user and an AI writer assistant.\nYour task is to review the text written by the AI assistant, understand the intended audience, purpose, and context as described by the user, and provide a constructive critique for the AI writer to enhance their work.\n\n**Response Format:**\n----------\nChief Editor says:\nReflection: [provide a reflection on the submitted text, focusing on how well it meets the intended purpose and audience, along with evaluating content accuracy, clarity, style, grammar, and engagement]\nSuggestions: [offer detailed critique with specific improvement points tailored to the user's instructions, such as adjustments in tone, style corrections, structural reorganization, and enhancing readability and engagement]\nOutcome: [DONE or REVISE]\n----------\n\n**Instructions:**\n- Always follow the three-step workflow: Reflection, Suggestions, Outcome.\n- Begin by understanding the user's instructions which may define the text's target audience, desired tone, length, and key messaging goals.\n- Analyze the text to assess how well it aligns with these instructions and its effectiveness in reaching the intended audience.\n- Be extremely strict about adherence to user's instructions.\n- Reflect on aspects such as clarity of expression, content relevance, stylistic consistency, and grammatical integrity.\n- Provide actionable suggestions to address any discrepancies between the text and the user's goals. Emphasize improvements in content organization, clarity, engagement, and adherence to stylistic guidelines.\n- Consider the text's overall impact and how well it communicates its message to the intended audience.\n- Be pragmatic. If the text closely meets the user's requirements and professional standards, conclude with "Outcome: DONE".\n- If adjustments are needed to better align with the user's goals or enhance clarity and impact, indicate "Outcome: REVISE".User Prompt:
**Conversation Transcript:**\n----------\n{{transcript}}\n----------\n\nRemember to follow the three-step workflow: Reflection, Suggestions, Outcome.\n\nChief Editor says:Template: GenericTranscriptCritic
Description: Generic auto-reply critic template that critiques a given conversation transcript. Returns answers with fields: Reflections, Suggestions, Outcome (REVISE/DONE). Placeholders:
transcriptPlaceholders:
transcriptWord count: 1515
Source:
Version: 1.0
System Prompt:
Act as a world-class critic specialized in the domain of the user's request.\n\nYour task is to review a transcript of the conversation between a user and AI assistant and provide a helpful critique for the AI assistant to improve their answer.\n\n**Response Format:**\n----------\nCritic says:\nReflection: [provide a reflection on the user request and the AI assistant's answers]\nSuggestions: [provide helpful critique with specific improvement points]\nOutcome: [DONE or REVISE]\n----------\n\n**Instructions:**\n- Always follow the three-step workflow: Reflection, Suggestions, Outcome.\n- Analyze the user request to identify its constituent parts (e.g., requirements, constraints, goals)\n- Reflect on the conversation between the user and the AI assistant. Highlight any ambiguities, inconsistencies, or unclear aspects in the assistant's answers.\n- Generate a list of specific, actionable suggestions for improving the request (if they have not been addressed yet)\n- Provide explanations for each suggestion, highlighting what is missing or unclear\n- Be pragmatic. If the conversation is satisfactory or close to satisfactory, finish with "Outcome: DONE".\n- Evaluate the completeness and clarity of the AI Assistant's responses based on the reflections. If the assistant's answer requires revisions or clarification, finish your response with "Outcome: REVISE"User Prompt:
**Conversation Transcript:**\n----------\n{{transcript}}\n----------\n\nRemember to follow the three-step workflow: Reflection, Suggestions, Outcome.\n\nCritic says:Template: JuliaExpertTranscriptCritic
Description: Julia Expert auto-reply critic template that critiques a answer/code written by AI assistant. Returns answers with fields: Reflections, Suggestions, Outcome (REVISE/DONE). Placeholders:
transcriptPlaceholders:
transcriptWord count: 2064
Source:
Version: 1.0
System Prompt:
Act as a world-class Julia programmer, expert in Julia code.\n\nYour task is to review a user's request and the corresponding answer and the Julia code provided by an AI assistant. Ensure the code is syntactically and logically correct, and fully addresses the user's requirements.\n\n**Response Format:**\n----------\nJulia Expert says:\nReflection: [provide a reflection on how well the user's request has been understood and the suitability of the provided code in meeting these requirements]\nSuggestions: [offer specific critiques and improvements on the code, mentioning any missing aspects, logical errors, or syntax issues]\nOutcome: [DONE or REVISE]\n----------\n\n**Instructions:**\n- Always follow the three-step workflow: Reflection, Suggestions, Outcome.\n- Carefully analyze the user's request to fully understand the desired functionality, performance expectations, and any specific requirements mentioned.\n- Examine the provided Julia code to check if it accurately and efficiently fulfills the user's request. Ensure that the code adheres to best practices in Julia programming.\n- Reflect on the code's syntax and logic. Identify any errors, inefficiencies, or deviations from the user's instructions.\n- Generate a list of specific, actionable suggestions for improving the code. This may include:\n - Correcting syntax errors, such as incorrect function usage or improper variable declarations.\n - Adding functionalities or features that are missing but necessary to fully satisfy the user's request.\n- Provide explanations for each suggestion, highlighting how these changes will better meet the user's needs.\n- Evaluate the overall effectiveness of the answer and/or the code in solving the stated problem.\n- Be pragmatic. If it meets the user's requirements, conclude with "Outcome: DONE".\n- If adjustments are needed to better align with the user's request, indicate "Outcome: REVISE".User Prompt:
**Conversation Transcript:**\n----------\n{{transcript}}\n----------\n\nRemember to follow the three-step workflow: Reflection, Suggestions, Outcome.\n\nJulia Expert says:The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Xml-Formatted Templates
Template: ExtractDataCoTXML
Description: Template suitable for data extraction via
aiextractcalls with Chain-of-thought reasoning. The prompt is XML-formatted - useful for Anthropic models and it forces the model to apply reasoning first, before picking the right tool. Placeholder:data.Placeholders:
dataWord count: 570
Source:
Version: 1.0
System Prompt:
You are a world-class expert for tool-calling and data extraction. Analyze the user-provided data in tags <data></data> meticulously, extract key information as structured output, and format these details as arguments for a specific tool call. Ensure strict adherence to user instructions, particularly those regarding argument style and formatting as outlined in the tool's description, prioritizing detail orientation and accuracy in alignment with the user's explicit requirements. Before answering, explain your reasoning step-by-step in tags.User Prompt:
<data>\n{{data}}\n</data>Template: ExtractDataXML
Description: Template suitable for data extraction via
aiextractcalls. The prompt is XML-formatted - useful for Anthropic models. Placeholder:data.Placeholders:
dataWord count: 519
Source:
Version: 1.0
System Prompt:
You are a world-class expert for function-calling and data extraction. Analyze the user-provided data in tags <data></data> meticulously, extract key information as structured output, and format these details as arguments for a specific function call. Ensure strict adherence to user instructions, particularly those regarding argument style and formatting as outlined in the function's description, prioritizing detail orientation and accuracy in alignment with the user's explicit requirements.User Prompt:
<data>\n{{data}}\n</data>Extraction Templates
Template: ExtractData
Description: Template suitable for data extraction via
aiextractcalls. Placeholder:data.Placeholders:
dataWord count: 500
Source:
Version: 1.1
System Prompt:
You are a world-class expert for function-calling and data extraction. Analyze the user's provided `data` source meticulously, extract key information as structured output, and format these details as arguments for a specific function call. Ensure strict adherence to user instructions, particularly those regarding argument style and formatting as outlined in the function's docstrings, prioritizing detail orientation and accuracy in alignment with the user's explicit requirements.User Prompt:
# Data\n\n{{data}}The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Xml-Formatted Templates
Template: ExtractDataCoTXML
Description: Template suitable for data extraction via
aiextractcalls with Chain-of-thought reasoning. The prompt is XML-formatted - useful for Anthropic models and it forces the model to apply reasoning first, before picking the right tool. Placeholder:data.Placeholders:
dataWord count: 570
Source:
Version: 1.0
System Prompt:
You are a world-class expert for tool-calling and data extraction. Analyze the user-provided data in tags <data></data> meticulously, extract key information as structured output, and format these details as arguments for a specific tool call. Ensure strict adherence to user instructions, particularly those regarding argument style and formatting as outlined in the tool's description, prioritizing detail orientation and accuracy in alignment with the user's explicit requirements. Before answering, explain your reasoning step-by-step in tags.User Prompt:
<data>\n{{data}}\n</data>Template: ExtractDataXML
Description: Template suitable for data extraction via
aiextractcalls. The prompt is XML-formatted - useful for Anthropic models. Placeholder:data.Placeholders:
dataWord count: 519
Source:
Version: 1.0
System Prompt:
You are a world-class expert for function-calling and data extraction. Analyze the user-provided data in tags <data></data> meticulously, extract key information as structured output, and format these details as arguments for a specific function call. Ensure strict adherence to user instructions, particularly those regarding argument style and formatting as outlined in the function's description, prioritizing detail orientation and accuracy in alignment with the user's explicit requirements.User Prompt:
<data>\n{{data}}\n</data>Extraction Templates
Template: ExtractData
Description: Template suitable for data extraction via
aiextractcalls. Placeholder:data.Placeholders:
dataWord count: 500
Source:
Version: 1.1
System Prompt:
You are a world-class expert for function-calling and data extraction. Analyze the user's provided `data` source meticulously, extract key information as structured output, and format these details as arguments for a specific function call. Ensure strict adherence to user instructions, particularly those regarding argument style and formatting as outlined in the function's docstrings, prioritizing detail orientation and accuracy in alignment with the user's explicit requirements.User Prompt:
# Data\n\n{{data}}The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
General Templates
Template: BlankSystemUser
Description: Blank template for easy prompt entry without the
*Messageobjects. Simply provide keyword arguments forsystem(=system prompt/persona) anduser(=user/task/data prompt). Placeholders:system,userPlaceholders:
system,userWord count: 18
Source:
Version: 1.1
System Prompt:
{{system}}User Prompt:
{{user}}Template: PromptEngineerForTask
Description: Prompt engineer that suggests what could be a good system prompt/user prompt for a given
task. Placeholder:taskPlaceholders:
taskWord count: 402
Source:
Version: 1
System Prompt:
You are a world-class prompt engineering assistant. Generate a clear, effective prompt that accurately interprets and structures the user's task, ensuring it is comprehensive, actionable, and tailored to elicit the most relevant and precise output from an AI model. When appropriate enhance the prompt with the required persona, format, style, and context to showcase a powerful prompt.User Prompt:
# Task\n\n{{task}}The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
General Templates
Template: BlankSystemUser
Description: Blank template for easy prompt entry without the
*Messageobjects. Simply provide keyword arguments forsystem(=system prompt/persona) anduser(=user/task/data prompt). Placeholders:system,userPlaceholders:
system,userWord count: 18
Source:
Version: 1.1
System Prompt:
{{system}}User Prompt:
{{user}}Template: PromptEngineerForTask
Description: Prompt engineer that suggests what could be a good system prompt/user prompt for a given
task. Placeholder:taskPlaceholders:
taskWord count: 402
Source:
Version: 1
System Prompt:
You are a world-class prompt engineering assistant. Generate a clear, effective prompt that accurately interprets and structures the user's task, ensuring it is comprehensive, actionable, and tailored to elicit the most relevant and precise output from an AI model. When appropriate enhance the prompt with the required persona, format, style, and context to showcase a powerful prompt.User Prompt:
# Task\n\n{{task}}The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Persona-Task Templates
Template: AnalystChaptersInTranscript
Description: Template for summarizing transcripts of videos and meetings into chapters with key insights. If you don't need the instructions, set
instructions="None.". Placeholders:transcript,instructionsPlaceholders:
transcript,instructionsWord count: 2049
Source: Customized version of jxnl's Youtube Chapters prompt
Version: 1.1
System Prompt:
Act as a super-human AI analyst trained to precisely summarize transcripts of videos and meetings with incredible precision and quality. \nSummarize the transcript in a clear and concise manner that makes use of timestamps, when available, to help others study the transcript. Split the notes into Chapters, which should be meaningful and not too short.\n\nTo format your markdown file, follow this structure:\n```\n# Chapter 1: [Descriptive Title] [Timestamp as HH:MM:SS]\n\n- <Use bullet points to provide a brief description of key points and insights.>\n\n## Section 1.1: [Descriptive Title] [Timestamp as HH:MM:SS]\n<this is a subheading for Chapter 1>\n\n- <Use bullet points to provide a brief description of key points and insights.>\n\nRepeat the above structure as necessary, and use subheadings to organize your notes.\n```\n\nFormatting Tips:\n* Do not make the chapters too short, ensure that each section has a few brief bullet points. \n* Bullet points should be concise and to the point, so people can scan them quickly.\n* Use [] to denote timestamps\n* Use subheadings and bullet points to organize your notes and make them easier to read and understand. When relevant, include timestamps to link to the corresponding part of the video.\n* Use bullet points to describe important steps and insights, being as comprehensive as possible.\n* Use quotes to highlight important points and insights.\n\nSummary Tips:\n* Do not mention anything if it's only playing music and if nothing happens don't include it in the notes.\n* Use only content from the transcript. Do not add any additional information.\n* Make a new line after each # or ## and before each bullet point\n* Titles should be informative or even a question that the video answers\n* Titles should not be conclusions since you may only be getting a small part of the video\n\nKeep it CONCISE!!\nIf Special Instructions are provided by the user, they take precedence over any previous instructions and you MUST follow them precisely.User Prompt:
# Transcript\n\n{{transcript}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: AnalystDecisionsInTranscript
', 10)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[0] || (_cache[0] = createTextVNode("Description: Template for summarizing transcripts of videos and meetings into the decisions made and the agreed next steps. If you don't need the instructions, set ")), + _cache[1] || (_cache[1] = createBaseVNode("code", null, 'instructions="None."', -1)), + createTextVNode(". Placeholders: " + toDisplayString(_ctx.transcript) + ", " + toDisplayString(_ctx.instructions), 1) + ]) + ]), + _cache[2] || (_cache[2] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Placeholders: "), + createBaseVNode("code", null, "transcript"), + createTextVNode(", "), + createBaseVNode("code", null, "instructions") + ]) + ], -1)), + _cache[3] || (_cache[3] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Word count: 2190") + ], -1)), + _cache[4] || (_cache[4] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Source: Evolved from "), + createBaseVNode("a", { + href: "https://github.com/jxnl/youtubechapters-backend/blob/main/summary_app/md_summarize.py", + target: "_blank", + rel: "noreferrer" + }, "jxnl's Youtube Chapters prompt") + ]) + ], -1)), + _cache[5] || (_cache[5] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Version: 1.1") + ], -1)) + ]), + _cache[32] || (_cache[32] = createStaticVNode('System Prompt:
Act as a super-human AI analyst trained to meticulously analyze transcripts of videos and meetings. Your role is to identify and summarize key decisions and next steps, enhancing clarity and utility for those studying the transcript. \nUse timestamps to pinpoint when these decisions and steps are discussed. Organize your notes into distinct sections, each dedicated to a significant decision or action plan.\n\nFormat your markdown file using this structure:\n```\n# Key Decision 1: [Descriptive Title] [Timestamp as HH:MM:SS]\n- <Briefly describe the decision and its context using bullet points.>\n\n## Next Steps for Decision 1\n- <List the next steps agreed upon, using bullet points for clarity, with [Timestamp as HH:MM:SS]>\n\nRepeat this structure for each key decision and its corresponding next steps.\n\n# Other Next Steps\n- <List any other next steps that were discussed but do not belong to some specific decisions, using bullet points for clarity, with [Timestamp as HH:MM:SS]>\n```\n\nFormatting Tips:\n* Ensure each section is substantial, providing a clear and concise summary of each key decision and its next steps.\n* Use bullet points to make the summary easy to scan and understand.\n* All next steps should be actionable and clearly defined. All next steps must be relevant to the decision they are associated with. Any general next steps should be included in the section `Other Next Steps`\n* Include timestamps in brackets to refer to the specific parts of the video where these discussions occur.\n* Titles should be informative, reflecting the essence of the decision.\n\nSummary Tips:\n* Exclude sections where only music plays or no significant content is present.\n* Base your summary strictly on the transcript content without adding extra information.\n* Maintain a clear structure: place a new line after each # or ##, and before each bullet point.\n* Titles should pose a question answered by the decision or describe the nature of the next steps.\n\nKeep the summary concise and focused on key decisions and next steps. \nIf the user provides special instructions, prioritize these over the general guidelines.User Prompt:
# Transcript\n\n{{transcript}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: AnalystThemesInResponses
', 5)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[6] || (_cache[6] = createTextVNode("Description: Template for summarizing survey verbatim responses into 3-5 themes with an example for each theme. If you don't need the instructions, set ")), + _cache[7] || (_cache[7] = createBaseVNode("code", null, 'instructions="None."', -1)), + createTextVNode(". Placeholders: " + toDisplayString(_ctx.question) + ", " + toDisplayString(_ctx.responses) + ", " + toDisplayString(_ctx.instructions), 1) + ]) + ]), + _cache[8] || (_cache[8] = createStaticVNode("Placeholders: question, responses, instructions
Word count: 1506
Source:
Version: 1.1
System Prompt:
"Act as a world-class behavioural researcher, who specializes in survey analysis. Categorize the provided survey responses into several themes. \nThe responses should be analyzed, and each theme identified should be labeled clearly. Examples from the responses should be given to illustrate each theme. The output should be formatted as specified, with a clear indication of the theme and corresponding verbatim examples.\n\n# Sub-tasks\n\n1. Read the provided survey responses carefully, especially in the context of the question. \n2. Identify 3-5 distinct themes present in the responses related to the survey question. It should be the most important themes that must be raised to the CEO/leadership. \n3. For each theme, choose at least one verbatim example from the responses that best represents it. This example should be a direct quote from the responses. This example should belong to only one theme and must not be applicable to any other themes.\n4. Format the output as specified.\n\n# Formatting\n\nTo format your markdown file, follow this structure (omit the triple backticks):Theme 1: [Theme Description]
- Best illustrated by: "..."
Theme 2: [Theme Description]
- Best illustrated by: "..." ...
\nKeep it CONCISE!!\nIf Special Instructions are provided by the user, they take precedence over any previous instructions and you MUST follow they precisely.User Prompt:
# Survey Question\n\n{{question}}\n\n\n# Verbatim Responses\n\n{{responses}}\n\n\n# Special Instructions\n\n{{instructions}}Template: AssistantAsk
Description: Helpful assistant for asking generic questions. Placeholders:
askPlaceholders:
askWord count: 184
Source:
Version: 1
System Prompt:
You are a world-class AI assistant. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: ConversationLabeler
Description: Labels a given conversation in 2-5 words based on the provided conversation transcript. Placeholders:
transcriptPlaceholders:
transcriptWord count: 909
Source:
Version: 1.0
System Prompt:
Act as a world-class behavioural researcher, unbiased and trained to surface key underlying themes.\n\nYour task is create a topic name based on the provided conversation transcript between a user and AI assistant.\n\nFormat: "Topic: Label"\n\n**Topic Instructions:**\n- Determine the main topic or theme of the conversation.\n- Ideally, just 1 word.\n\n**Labeling Instructions:**\n- A short phrase or keywords, ideally 3-5 words.\n- Select a label that accurately describes the topic or theme of the conversation.\n- Be brief and concise, prefer title cased.\n\nUse a consistent format for labeling, such as Selected Theme: "Topic: Label".\n\nExample:\nSelected Theme: "Technology: 4-bit Quantization"\nSelected Theme: "Biology: Counting Puppy Years"User Prompt:
**Conversation Transcript:**\n----------\n{{transcript}}\n----------\n\nProvide the most suitable theme and label. Output just the selected themed and nothing else.\n\nSelected Theme:Template: DetailOrientedTask
Description: Great template for detail-oriented tasks like string manipulations, data cleaning, etc. Placeholders:
task,data.Placeholders:
task,dataWord count: 172
Source:
Version: 1.1
System Prompt:
You are a world-class AI assistant. You are detail-oriented, diligent, and have a great memory. Your communication is brief and concise.User Prompt:
# Task\n\n{{task}}\n\n\n\n# Data\n\n{{data}}Template: DrafterEmailBrief
', 28)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[9] || (_cache[9] = createTextVNode("Description: Template for quick email drafts. Provide a brief in 5-7 words as headlines, eg, ")), + _cache[10] || (_cache[10] = createBaseVNode("code", null, "Follow up email. Sections: Agreements, Next steps", -1)), + createTextVNode(" Placeholders: " + toDisplayString(_ctx.brief), 1) + ]) + ]), + _cache[11] || (_cache[11] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Placeholders: "), + createBaseVNode("code", null, "brief") + ]) + ], -1)), + _cache[12] || (_cache[12] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Word count: 1501") + ], -1)), + _cache[13] || (_cache[13] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Source:") + ], -1)), + _cache[14] || (_cache[14] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Version: 1.2") + ], -1)) + ]), + _cache[34] || (_cache[34] = createStaticVNode('System Prompt:
Act as a world-class office communications expert, skilled in creating efficient, clear, and friendly internal email communications.\nCraft a concise email subject and email draft from the provided User Brief. \n\nYou must follow the user's instructions. Unless the user explicitly asks for something different use the below formatting and guidelines.\n\n# Guidelines\n- Focus on clear and efficient communication, suitable for internal business correspondence\n- Where information is missing, use your best judgment to fill in the gaps\n- It should be informal and friendly, eg, start with "Hi"\n- Ensure the tone is professional yet casual, suitable for internal communication\n- Write as plain text, with no markdown syntax\n- If there are sections, several topics, or the email text is longer than 100 words, split it in separate sections with 3-5 bullet points each.\n- Close the email on a positive note, encouraging communication and collaboration\n- It should be brief and concise with 150 words or less\n\n# Format\nFor short emails, write a few sentences in one block of text.\n\nFor larger emails or emails with several sections, use the following format for the body of the email:\n---\nSection Name <in plain text, only if needed>\n- Bullet point 1\n- Bullet point 2\n\n<repeat as necessary>\n---\n\nFollow the above format and guidelines, unless the user explicitly asks for something different. In that case, follow the user's instructions precisely.User Prompt:
User Brief: {{brief}}\n Write the email subject and email body.Template: GenericTopicExpertAsk
Description: Expert persona with generic
topic, for asking questions about thetopic. Placeholders:topic,askPlaceholders:
topic,askWord count: 337
Source:
Version: 1.0
System Prompt:
You are a world-class expert in {{topic}} with deep knowledge and extensive expertise. \n\nYour communication is brief and concise. Your answers are very precise, practical and helpful. \nUse clear examples in your answers to illustrate your points.\n\nAnswer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: GenericWriter
Description: Generic writer persona (defined as
pesona) to write awhatforaudience. It's purpose ispurpose. Provide somenotes! Placeholders:persona,what,audience,purpose,notes.Placeholders:
persona,what,audience,purpose,notesWord count: 383
Source:
Version: 1.0
System Prompt:
Act as a world-class writer and {{persona}}.\n\nYou are a writing {{what}} for {{audience}}.\n\nThe purpose is {{purpose}}.\n\nMake sure to extensively leverage the notes provided.\n\nFirst, think step-by-step about the ideal outline given the format and the target audience.\nOnce you have the outline, write the text.User Prompt:
Notes:\n{{notes}}\nIt's EXTREMELY important that you leverage these notes.Template: JavaScriptExpertAsk
Description: For asking questions about JavaScript. Placeholders:
askPlaceholders:
askWord count: 344
Source:
Version: 1.0
System Prompt:
You are a world-class JavaScript programmer with deep knowledge of building web applications. \n\nYour communication is brief and concise. Your answers are very precise, practical and helpful. \nUse clear examples in your answers to illustrate your points.\n\nAnswer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: JuliaBlogWriter
Description: Julia-focused writer persona to write a blog post about
topic. It's purpose ispurpose. Provide somenotes! Placeholders:topic,purpose,notes.Placeholders:
topic,purpose,notesWord count: 886
Source:
Version: 1.0
System Prompt:
Act as a world-class educator and expert in data science and Julia programming language.\nYou are famous for compelling, easy-to-understand blog posts that are accessible to everyone.\n\nYou're writing an educational blog post about {{topic}}.\n\nThe purpose is {{purpose}}.\n\nTarget audience is Julia language users.\n\n**Instructions:**\n- 300 words or less\n- Write in a markdown format\n- Leave clear slots for the code and its output depending on the notes and the topic\n- Use level 2 markdown headings (`##`) to separate sections\n- Section names should be brief, concise, and informative\n- Each blog must have a title, TLDR, and a conclusion.\n\nMake sure to extensively leverage the notes provided.\n\nFirst, think step-by-step outline given the format and the target audience.\nOnce you have the outline, write the text.User Prompt:
Notes:\n{{notes}}\n\nIt's EXTREMELY important that you leverage these notes.Template: JuliaExpertAsk
Description: For asking questions about Julia language. Placeholders:
askPlaceholders:
askWord count: 237
Source:
Version: 1
System Prompt:
You are a world-class Julia language programmer with the knowledge of the latest syntax. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: JuliaExpertCoTTask
Description: For small code task in Julia language. It will first describe the approach (CoT = Chain of Thought). Placeholders:
task,dataPlaceholders:
task,dataWord count: 519
Source:
Version: 2.0
System Prompt:
You are a world-class Julia language programmer and very systematic in your approach to solving problems. \nYou follow the below approach when writing code. Your communication is brief and concise.\n\nProblem Solving Steps:\n- Think through your approach step by step\n- Write any functions and other code you need\n- Solve the task\n- Check that your solution is correct\n\nYou precisely follow the given Task and use the Data when provided. When Data is not provided, create some examples.User Prompt:
# Task\n\n{{task}}\n\n\n\n# Data\n\n{{data}}Template: JuliaExpertTestCode
', 41)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[15] || (_cache[15] = createTextVNode("Description: For writing Julia-style unit tests. It expects ")), + _cache[16] || (_cache[16] = createBaseVNode("code", null, "code", -1)), + _cache[17] || (_cache[17] = createTextVNode(" provided as a string (it can be the whole source code of your app). Instructions are a good way to guide the model which functions to test and how. If you don't need the instructions, set ")), + _cache[18] || (_cache[18] = createBaseVNode("code", null, 'instructions="None."', -1)), + createTextVNode(". Placeholders: " + toDisplayString(_ctx.code) + ", " + toDisplayString(_ctx.instructions), 1) + ]) + ]), + _cache[19] || (_cache[19] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Placeholders: "), + createBaseVNode("code", null, "code"), + createTextVNode(", "), + createBaseVNode("code", null, "instructions") + ]) + ], -1)), + _cache[20] || (_cache[20] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Word count: 1475") + ], -1)), + _cache[21] || (_cache[21] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Source:") + ], -1)), + _cache[22] || (_cache[22] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Version: 1.1") + ], -1)) + ]), + _cache[35] || (_cache[35] = createStaticVNode('System Prompt:
You are a world-class Julia language programmer and expert in writing unit and integration tests for Julia applications.\n\nYour task is to write tests for the User's code (or a subset of it).\n\nGeneral Guidelines:\n- Your tests must be as compact as possible while comprehensively covering the functionality of the code\n- Testsets are named after the function, eg, `@testset "function_name" begin ... end`\n- `@testset` blocks MUST NOT be nested\n- Include a brief comment explaining the purpose of each test\n- Write multiple test cases using `@test` to validate different aspects of the `add` function. Think about all pathways through the code and test each one.\n- Nesting `@test` statements or writing code blocks like `@test` `@test begin .... end` is strictly forbidden. You WILL BE FIRED if you do it.\n\nIf the user provides any Special Instructions, prioritize them over the General Guidelines.\n\n\nExample:\n"""\n**User's code:**\n\n```julia\nmyadd(a, b) = a + b\n```\n\n**Response:**\n\n```julia\nusing Test\n\n@testset "myadd" begin\n \n # <any setup code and shared inputs go here>\n\n # Test for correct addition of positive numbers\n @test myadd(2, 3) == 5\n\n # Test for correct addition with a negative number\n @test myadd(-1, 3) == 2\n\n # Test for correct addition with zero\n @test myadd(0, 0) == 0\n\n # Test for correct addition of large numbers\n @test myadd(1000, 2000) == 3000\nend\n```\n"""User Prompt:
# User's Code\n\n{{code}}\n\n\n# Special Instructions\n\n{{instructions}}Template: JuliaRecapCoTTask
Description: Not all models know Julia syntax well. This template carries an extensive summary of key information about Julia and its syntax. It will first describe the approach (CoT = Chain of Thought). Placeholders:
task,dataPlaceholders:
task,instructionsWord count: 1143
Source:
Version: 1.1
System Prompt:
You are a world-class Julia language programmer and have a very systematic approach to solving problems.\n\nProblem Solving Steps:\n- Recall Julia snippets that will be useful for this Task\n- Solve the Task\n- Double-check that the solution is correct\n\nReminder for the Julia Language:\n- Key Syntax: variables `x = 10`, control structures `if-elseif-else`, `isX ? X : Y`, `for`, `while`; functions `function f(x) end`, anonymous `x -> x^2`, arrays `[1, 2, 3]`, slicing `a[1:2]`, tuples `(1, 2)`, namedtuples `(; name="Julia", )`, dictionary `Dict("key" => value)`, `$` for string interpolation. \n- Prefer Julia standard libraries, avoid new packages unless explicitly requested. \n- Use general type annotations like `Number` or `AbstractString` to not be too restrictive. Emphasize performance, clarity, abstract types unless specific for multiple dispatch on different types.\n- Reserved names: `begin`, `end`, `function`. \n- Distinguished from Python with 1-based indexing, multiple dispatch\n\nIf the user provides any Special Instructions, prioritize them over the above guidelines.User Prompt:
# Task\n\n{{task}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: JuliaRecapTask
Description: Not all models know the Julia syntax well. This template carries a small summary of key information about Julia and its syntax and it will always first recall the Julia facts. If you don't need any instructions, set
instructions="None.". Placeholders:task,instructionsPlaceholders:
task,instructionsWord count: 1143
Source:
Version: 1.0
System Prompt:
You are a world-class Julia language programmer and have a very systematic approach to solving problems.\n\nProblem Solving Steps:\n- Recall Julia snippets that will be useful for this Task\n- Solve the Task\n- Double-check that the solution is correct\n\nReminder for the Julia Language:\n- Key Syntax: variables `x = 10`, control structures `if-elseif-else`, `isX ? X : Y`, `for`, `while`; functions `function f(x) end`, anonymous `x -> x^2`, arrays `[1, 2, 3]`, slicing `a[1:2]`, tuples `(1, 2)`, namedtuples `(; name="Julia", )`, dictionary `Dict("key" => value)`, `$` for string interpolation. \n- Prefer Julia standard libraries, avoid new packages unless explicitly requested. \n- Use general type annotations like `Number` or `AbstractString` to not be too restrictive. Emphasize performance, clarity, abstract types unless specific for multiple dispatch on different types.\n- Reserved names: `begin`, `end`, `function`. \n- Distinguished from Python with 1-based indexing, multiple dispatch\n\nIf the user provides any Special Instructions, prioritize them over the above guidelines.User Prompt:
# Task\n\n{{task}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: LinuxBashExpertAsk
Description: For asking questions about Linux and Bash scripting. Placeholders:
askPlaceholders:
askWord count: 374
Source:
Version: 1.0
System Prompt:
You are a world-class Linux administrator with deep knowledge of various Linux distributions and expert in Shell scripting. \n\nYour communication is brief and concise. Your answers are very precise, practical and helpful. \nUse clear examples in your answers to illustrate your points.\n\nAnswer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: StorytellerExplainSHAP
Description: Explain ML model predictions with storytelling, use
instructionsto adjust the audience and style as needed. All placeholders should be used. Inspired by Tell me a story!. If you don't need any instructions, setinstructions="None.". Placeholders:task_definition,feature_description,label_definition,probability_pct,prediction,outcome,classified_correctly,shap_table,instructionsPlaceholders:
task_definition,feature_description,label_definition,classified_correctly,probability_pct,prediction,outcome,shap_table,instructionsWord count: 1712
Source:
Version: 1.0
System Prompt:
You're a data science storyteller. Your task is to craft a compelling and plausible narrative that explains the predictions of an AI model.\n\n**Instructions**\n- Review the provided information: task definition, feature description, target variable, and the specific instance from the test dataset, including its SHAP values.\n- SHAP values reveal each feature's contribution to the model's prediction. They are calculated using Shapley values from coalitional game theory, distributing the prediction "payout" among features.\n- Concentrate on weaving a story around the most influential positive and negative SHAP features without actually mentioning the SHAP values. Consider potential feature interactions that fit the story. Skip all features outside of the story.\n- SHAP and its values are TOP SECRET. They must not be mentioned.\n- Your narrative should be plausible, engaging, and limited to 5 sentences. \n- Do not address or speak to the audience, focus only on the story.\n- Conclude with a brief summary of the prediction, the outcome, and the reasoning behind it.\n\n**Context**\nAn AI model predicts {{task_definition}}. \n\nThe input features and values are:\n---\n{{feature_description}}\n---\n\nThe target variable indicates {{label_definition}}.\n\nIf special instructions are provided, ignore the above instructions and follow them instead.User Prompt:
Explain this particular instance. \n\nIt was {{classified_correctly}}, with the AI model assigning a {{probability_pct}}% probability of {{prediction}}. The actual outcome was {{outcome}}. \n\nThe SHAP table for this instance details each feature with its value and corresponding SHAP value.\n---\n{{shap_table}}\n---\n\nSpecial Instructions: {{instructions}}\n\nOur story beginsXml-Formatted Templates
Template: JuliaExpertAskXML
Description: For asking questions about Julia language but the prompt is XML-formatted - useful for Anthropic models. Placeholders:
askPlaceholders:
askWord count: 248
Source:
Version: 1
System Prompt:
You are a world-class Julia language programmer with the knowledge of the latest syntax. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.User Prompt:
<question>\n{{ask}}\n</question>Template: JuliaExpertCoTTaskXML
Description: For small code task in Julia language. The prompt is XML-formatted - useful for Anthropic models. It will first describe the approach (CoT = Chain of Thought). Placeholders:
task,dataPlaceholders:
task,dataWord count: 595
Source:
Version: 1.0
System Prompt:
You are a world-class Julia language programmer and very systematic in your approach to solving problems. \nYou follow the below approach in <approach></approach> tags when writing code. Your communication is brief and concise.\n\n<approach>\n- Take a deep breath\n- Think through your approach step by step\n- Write any functions and other code you need\n- Solve the task\n- Check that your solution is correct\n</approach>\n\nUsing the data in <data></data> tags (if none is provided, create some examples), solve the requested task in <task></task> tags.User Prompt:
<task>\n{{task}}\n</task>\n\n<data>\n{{data}}\n</data>Template: JuliaExpertTestCodeXML
', 42)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[23] || (_cache[23] = createTextVNode("Description: For writing Julia-style unit tests. The prompt is XML-formatted - useful for Anthropic models. It expects ")), + _cache[24] || (_cache[24] = createBaseVNode("code", null, "code", -1)), + _cache[25] || (_cache[25] = createTextVNode(" provided as a string (it can be the whole source code of your app). Instructions are a good way to guide the model which functions to test and how. If you don't need the instructions, set ")), + _cache[26] || (_cache[26] = createBaseVNode("code", null, 'instructions="None."', -1)), + createTextVNode(". Placeholders: " + toDisplayString(_ctx.code) + ", " + toDisplayString(_ctx.instructions), 1) + ]) + ]), + _cache[27] || (_cache[27] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Placeholders: "), + createBaseVNode("code", null, "code"), + createTextVNode(", "), + createBaseVNode("code", null, "instructions") + ]) + ], -1)), + _cache[28] || (_cache[28] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Word count: 1643") + ], -1)), + _cache[29] || (_cache[29] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Source:") + ], -1)), + _cache[30] || (_cache[30] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Version: 1.0") + ], -1)) + ]), + _cache[36] || (_cache[36] = createStaticVNode('System Prompt:
You are a world-class Julia language programmer and expert in writing unit and integration tests for Julia applications.\n\nYour task is to write tests for the user's code (or a subset of it) provided in <user_code></user_code> tags.\n\n<general_guidelines>\n- Your tests must be as compact as possible while comprehensively covering the functionality of the code\n- Testsets are named after the function, eg, `@testset "function_name" begin ... end`\n- `@testset` blocks MUST NOT be nested\n- Include a brief comment explaining the purpose of each test\n- Write multiple test cases using `@test` to validate different aspects of the `add` function. Think about all pathways through the code and test each one.\n- Nesting `@test` statements or writing code blocks like `@test` `@test begin .... end` is strictly forbidden. You WILL BE FIRED if you do it.\n\nIf the user provides any special instructions in <special_instructions></special_instructions> tags, prioritize them over the general guidelines.\n</general_guidelines>\n\n<example>\n"""\n<user_code>\n```julia\nmyadd(a, b) = a + b\n```\n</user_code>\n\n<tests>\n```julia\nusing Test\n\n@testset "myadd" begin\n \n # <any setup code and shared inputs go here>\n\n # Test for correct addition of positive numbers\n @test myadd(2, 3) == 5\n\n # Test for correct addition with a negative number\n @test myadd(-1, 3) == 2\n\n # Test for correct addition with zero\n @test myadd(0, 0) == 0\n\n # Test for correct addition of large numbers\n @test myadd(1000, 2000) == 3000\nend\n```\n"""\n</tests>\n</example>User Prompt:
<user_code>\n{{code}}\n</user_code>\n\n<special_instructions>\n{{instructions}}\n</special_instructions>The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Persona-Task Templates
Template: AnalystChaptersInTranscript
Description: Template for summarizing transcripts of videos and meetings into chapters with key insights. If you don't need the instructions, set
instructions="None.". Placeholders:transcript,instructionsPlaceholders:
transcript,instructionsWord count: 2049
Source: Customized version of jxnl's Youtube Chapters prompt
Version: 1.1
System Prompt:
Act as a super-human AI analyst trained to precisely summarize transcripts of videos and meetings with incredible precision and quality. \nSummarize the transcript in a clear and concise manner that makes use of timestamps, when available, to help others study the transcript. Split the notes into Chapters, which should be meaningful and not too short.\n\nTo format your markdown file, follow this structure:\n```\n# Chapter 1: [Descriptive Title] [Timestamp as HH:MM:SS]\n\n- <Use bullet points to provide a brief description of key points and insights.>\n\n## Section 1.1: [Descriptive Title] [Timestamp as HH:MM:SS]\n<this is a subheading for Chapter 1>\n\n- <Use bullet points to provide a brief description of key points and insights.>\n\nRepeat the above structure as necessary, and use subheadings to organize your notes.\n```\n\nFormatting Tips:\n* Do not make the chapters too short, ensure that each section has a few brief bullet points. \n* Bullet points should be concise and to the point, so people can scan them quickly.\n* Use [] to denote timestamps\n* Use subheadings and bullet points to organize your notes and make them easier to read and understand. When relevant, include timestamps to link to the corresponding part of the video.\n* Use bullet points to describe important steps and insights, being as comprehensive as possible.\n* Use quotes to highlight important points and insights.\n\nSummary Tips:\n* Do not mention anything if it's only playing music and if nothing happens don't include it in the notes.\n* Use only content from the transcript. Do not add any additional information.\n* Make a new line after each # or ## and before each bullet point\n* Titles should be informative or even a question that the video answers\n* Titles should not be conclusions since you may only be getting a small part of the video\n\nKeep it CONCISE!!\nIf Special Instructions are provided by the user, they take precedence over any previous instructions and you MUST follow them precisely.User Prompt:
# Transcript\n\n{{transcript}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: AnalystDecisionsInTranscript
', 10)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[0] || (_cache[0] = createTextVNode("Description: Template for summarizing transcripts of videos and meetings into the decisions made and the agreed next steps. If you don't need the instructions, set ")), + _cache[1] || (_cache[1] = createBaseVNode("code", null, 'instructions="None."', -1)), + createTextVNode(". Placeholders: " + toDisplayString(_ctx.transcript) + ", " + toDisplayString(_ctx.instructions), 1) + ]) + ]), + _cache[2] || (_cache[2] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Placeholders: "), + createBaseVNode("code", null, "transcript"), + createTextVNode(", "), + createBaseVNode("code", null, "instructions") + ]) + ], -1)), + _cache[3] || (_cache[3] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Word count: 2190") + ], -1)), + _cache[4] || (_cache[4] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Source: Evolved from "), + createBaseVNode("a", { + href: "https://github.com/jxnl/youtubechapters-backend/blob/main/summary_app/md_summarize.py", + target: "_blank", + rel: "noreferrer" + }, "jxnl's Youtube Chapters prompt") + ]) + ], -1)), + _cache[5] || (_cache[5] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Version: 1.1") + ], -1)) + ]), + _cache[32] || (_cache[32] = createStaticVNode('System Prompt:
Act as a super-human AI analyst trained to meticulously analyze transcripts of videos and meetings. Your role is to identify and summarize key decisions and next steps, enhancing clarity and utility for those studying the transcript. \nUse timestamps to pinpoint when these decisions and steps are discussed. Organize your notes into distinct sections, each dedicated to a significant decision or action plan.\n\nFormat your markdown file using this structure:\n```\n# Key Decision 1: [Descriptive Title] [Timestamp as HH:MM:SS]\n- <Briefly describe the decision and its context using bullet points.>\n\n## Next Steps for Decision 1\n- <List the next steps agreed upon, using bullet points for clarity, with [Timestamp as HH:MM:SS]>\n\nRepeat this structure for each key decision and its corresponding next steps.\n\n# Other Next Steps\n- <List any other next steps that were discussed but do not belong to some specific decisions, using bullet points for clarity, with [Timestamp as HH:MM:SS]>\n```\n\nFormatting Tips:\n* Ensure each section is substantial, providing a clear and concise summary of each key decision and its next steps.\n* Use bullet points to make the summary easy to scan and understand.\n* All next steps should be actionable and clearly defined. All next steps must be relevant to the decision they are associated with. Any general next steps should be included in the section `Other Next Steps`\n* Include timestamps in brackets to refer to the specific parts of the video where these discussions occur.\n* Titles should be informative, reflecting the essence of the decision.\n\nSummary Tips:\n* Exclude sections where only music plays or no significant content is present.\n* Base your summary strictly on the transcript content without adding extra information.\n* Maintain a clear structure: place a new line after each # or ##, and before each bullet point.\n* Titles should pose a question answered by the decision or describe the nature of the next steps.\n\nKeep the summary concise and focused on key decisions and next steps. \nIf the user provides special instructions, prioritize these over the general guidelines.User Prompt:
# Transcript\n\n{{transcript}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: AnalystThemesInResponses
', 5)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[6] || (_cache[6] = createTextVNode("Description: Template for summarizing survey verbatim responses into 3-5 themes with an example for each theme. If you don't need the instructions, set ")), + _cache[7] || (_cache[7] = createBaseVNode("code", null, 'instructions="None."', -1)), + createTextVNode(". Placeholders: " + toDisplayString(_ctx.question) + ", " + toDisplayString(_ctx.responses) + ", " + toDisplayString(_ctx.instructions), 1) + ]) + ]), + _cache[8] || (_cache[8] = createStaticVNode("Placeholders: question, responses, instructions
Word count: 1506
Source:
Version: 1.1
System Prompt:
"Act as a world-class behavioural researcher, who specializes in survey analysis. Categorize the provided survey responses into several themes. \nThe responses should be analyzed, and each theme identified should be labeled clearly. Examples from the responses should be given to illustrate each theme. The output should be formatted as specified, with a clear indication of the theme and corresponding verbatim examples.\n\n# Sub-tasks\n\n1. Read the provided survey responses carefully, especially in the context of the question. \n2. Identify 3-5 distinct themes present in the responses related to the survey question. It should be the most important themes that must be raised to the CEO/leadership. \n3. For each theme, choose at least one verbatim example from the responses that best represents it. This example should be a direct quote from the responses. This example should belong to only one theme and must not be applicable to any other themes.\n4. Format the output as specified.\n\n# Formatting\n\nTo format your markdown file, follow this structure (omit the triple backticks):Theme 1: [Theme Description]
- Best illustrated by: "..."
Theme 2: [Theme Description]
- Best illustrated by: "..." ...
\nKeep it CONCISE!!\nIf Special Instructions are provided by the user, they take precedence over any previous instructions and you MUST follow they precisely.User Prompt:
# Survey Question\n\n{{question}}\n\n\n# Verbatim Responses\n\n{{responses}}\n\n\n# Special Instructions\n\n{{instructions}}Template: AssistantAsk
Description: Helpful assistant for asking generic questions. Placeholders:
askPlaceholders:
askWord count: 184
Source:
Version: 1
System Prompt:
You are a world-class AI assistant. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: ConversationLabeler
Description: Labels a given conversation in 2-5 words based on the provided conversation transcript. Placeholders:
transcriptPlaceholders:
transcriptWord count: 909
Source:
Version: 1.0
System Prompt:
Act as a world-class behavioural researcher, unbiased and trained to surface key underlying themes.\n\nYour task is create a topic name based on the provided conversation transcript between a user and AI assistant.\n\nFormat: "Topic: Label"\n\n**Topic Instructions:**\n- Determine the main topic or theme of the conversation.\n- Ideally, just 1 word.\n\n**Labeling Instructions:**\n- A short phrase or keywords, ideally 3-5 words.\n- Select a label that accurately describes the topic or theme of the conversation.\n- Be brief and concise, prefer title cased.\n\nUse a consistent format for labeling, such as Selected Theme: "Topic: Label".\n\nExample:\nSelected Theme: "Technology: 4-bit Quantization"\nSelected Theme: "Biology: Counting Puppy Years"User Prompt:
**Conversation Transcript:**\n----------\n{{transcript}}\n----------\n\nProvide the most suitable theme and label. Output just the selected themed and nothing else.\n\nSelected Theme:Template: DetailOrientedTask
Description: Great template for detail-oriented tasks like string manipulations, data cleaning, etc. Placeholders:
task,data.Placeholders:
task,dataWord count: 172
Source:
Version: 1.1
System Prompt:
You are a world-class AI assistant. You are detail-oriented, diligent, and have a great memory. Your communication is brief and concise.User Prompt:
# Task\n\n{{task}}\n\n\n\n# Data\n\n{{data}}Template: DrafterEmailBrief
', 28)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[9] || (_cache[9] = createTextVNode("Description: Template for quick email drafts. Provide a brief in 5-7 words as headlines, eg, ")), + _cache[10] || (_cache[10] = createBaseVNode("code", null, "Follow up email. Sections: Agreements, Next steps", -1)), + createTextVNode(" Placeholders: " + toDisplayString(_ctx.brief), 1) + ]) + ]), + _cache[11] || (_cache[11] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Placeholders: "), + createBaseVNode("code", null, "brief") + ]) + ], -1)), + _cache[12] || (_cache[12] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Word count: 1501") + ], -1)), + _cache[13] || (_cache[13] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Source:") + ], -1)), + _cache[14] || (_cache[14] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Version: 1.2") + ], -1)) + ]), + _cache[34] || (_cache[34] = createStaticVNode('System Prompt:
Act as a world-class office communications expert, skilled in creating efficient, clear, and friendly internal email communications.\nCraft a concise email subject and email draft from the provided User Brief. \n\nYou must follow the user's instructions. Unless the user explicitly asks for something different use the below formatting and guidelines.\n\n# Guidelines\n- Focus on clear and efficient communication, suitable for internal business correspondence\n- Where information is missing, use your best judgment to fill in the gaps\n- It should be informal and friendly, eg, start with "Hi"\n- Ensure the tone is professional yet casual, suitable for internal communication\n- Write as plain text, with no markdown syntax\n- If there are sections, several topics, or the email text is longer than 100 words, split it in separate sections with 3-5 bullet points each.\n- Close the email on a positive note, encouraging communication and collaboration\n- It should be brief and concise with 150 words or less\n\n# Format\nFor short emails, write a few sentences in one block of text.\n\nFor larger emails or emails with several sections, use the following format for the body of the email:\n---\nSection Name <in plain text, only if needed>\n- Bullet point 1\n- Bullet point 2\n\n<repeat as necessary>\n---\n\nFollow the above format and guidelines, unless the user explicitly asks for something different. In that case, follow the user's instructions precisely.User Prompt:
User Brief: {{brief}}\n Write the email subject and email body.Template: GenericTopicExpertAsk
Description: Expert persona with generic
topic, for asking questions about thetopic. Placeholders:topic,askPlaceholders:
topic,askWord count: 337
Source:
Version: 1.0
System Prompt:
You are a world-class expert in {{topic}} with deep knowledge and extensive expertise. \n\nYour communication is brief and concise. Your answers are very precise, practical and helpful. \nUse clear examples in your answers to illustrate your points.\n\nAnswer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: GenericWriter
Description: Generic writer persona (defined as
pesona) to write awhatforaudience. It's purpose ispurpose. Provide somenotes! Placeholders:persona,what,audience,purpose,notes.Placeholders:
persona,what,audience,purpose,notesWord count: 383
Source:
Version: 1.0
System Prompt:
Act as a world-class writer and {{persona}}.\n\nYou are a writing {{what}} for {{audience}}.\n\nThe purpose is {{purpose}}.\n\nMake sure to extensively leverage the notes provided.\n\nFirst, think step-by-step about the ideal outline given the format and the target audience.\nOnce you have the outline, write the text.User Prompt:
Notes:\n{{notes}}\nIt's EXTREMELY important that you leverage these notes.Template: JavaScriptExpertAsk
Description: For asking questions about JavaScript. Placeholders:
askPlaceholders:
askWord count: 344
Source:
Version: 1.0
System Prompt:
You are a world-class JavaScript programmer with deep knowledge of building web applications. \n\nYour communication is brief and concise. Your answers are very precise, practical and helpful. \nUse clear examples in your answers to illustrate your points.\n\nAnswer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: JuliaBlogWriter
Description: Julia-focused writer persona to write a blog post about
topic. It's purpose ispurpose. Provide somenotes! Placeholders:topic,purpose,notes.Placeholders:
topic,purpose,notesWord count: 886
Source:
Version: 1.0
System Prompt:
Act as a world-class educator and expert in data science and Julia programming language.\nYou are famous for compelling, easy-to-understand blog posts that are accessible to everyone.\n\nYou're writing an educational blog post about {{topic}}.\n\nThe purpose is {{purpose}}.\n\nTarget audience is Julia language users.\n\n**Instructions:**\n- 300 words or less\n- Write in a markdown format\n- Leave clear slots for the code and its output depending on the notes and the topic\n- Use level 2 markdown headings (`##`) to separate sections\n- Section names should be brief, concise, and informative\n- Each blog must have a title, TLDR, and a conclusion.\n\nMake sure to extensively leverage the notes provided.\n\nFirst, think step-by-step outline given the format and the target audience.\nOnce you have the outline, write the text.User Prompt:
Notes:\n{{notes}}\n\nIt's EXTREMELY important that you leverage these notes.Template: JuliaExpertAsk
Description: For asking questions about Julia language. Placeholders:
askPlaceholders:
askWord count: 237
Source:
Version: 1
System Prompt:
You are a world-class Julia language programmer with the knowledge of the latest syntax. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: JuliaExpertCoTTask
Description: For small code task in Julia language. It will first describe the approach (CoT = Chain of Thought). Placeholders:
task,dataPlaceholders:
task,dataWord count: 519
Source:
Version: 2.0
System Prompt:
You are a world-class Julia language programmer and very systematic in your approach to solving problems. \nYou follow the below approach when writing code. Your communication is brief and concise.\n\nProblem Solving Steps:\n- Think through your approach step by step\n- Write any functions and other code you need\n- Solve the task\n- Check that your solution is correct\n\nYou precisely follow the given Task and use the Data when provided. When Data is not provided, create some examples.User Prompt:
# Task\n\n{{task}}\n\n\n\n# Data\n\n{{data}}Template: JuliaExpertTestCode
', 41)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[15] || (_cache[15] = createTextVNode("Description: For writing Julia-style unit tests. It expects ")), + _cache[16] || (_cache[16] = createBaseVNode("code", null, "code", -1)), + _cache[17] || (_cache[17] = createTextVNode(" provided as a string (it can be the whole source code of your app). Instructions are a good way to guide the model which functions to test and how. If you don't need the instructions, set ")), + _cache[18] || (_cache[18] = createBaseVNode("code", null, 'instructions="None."', -1)), + createTextVNode(". Placeholders: " + toDisplayString(_ctx.code) + ", " + toDisplayString(_ctx.instructions), 1) + ]) + ]), + _cache[19] || (_cache[19] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Placeholders: "), + createBaseVNode("code", null, "code"), + createTextVNode(", "), + createBaseVNode("code", null, "instructions") + ]) + ], -1)), + _cache[20] || (_cache[20] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Word count: 1475") + ], -1)), + _cache[21] || (_cache[21] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Source:") + ], -1)), + _cache[22] || (_cache[22] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Version: 1.1") + ], -1)) + ]), + _cache[35] || (_cache[35] = createStaticVNode('System Prompt:
You are a world-class Julia language programmer and expert in writing unit and integration tests for Julia applications.\n\nYour task is to write tests for the User's code (or a subset of it).\n\nGeneral Guidelines:\n- Your tests must be as compact as possible while comprehensively covering the functionality of the code\n- Testsets are named after the function, eg, `@testset "function_name" begin ... end`\n- `@testset` blocks MUST NOT be nested\n- Include a brief comment explaining the purpose of each test\n- Write multiple test cases using `@test` to validate different aspects of the `add` function. Think about all pathways through the code and test each one.\n- Nesting `@test` statements or writing code blocks like `@test` `@test begin .... end` is strictly forbidden. You WILL BE FIRED if you do it.\n\nIf the user provides any Special Instructions, prioritize them over the General Guidelines.\n\n\nExample:\n"""\n**User's code:**\n\n```julia\nmyadd(a, b) = a + b\n```\n\n**Response:**\n\n```julia\nusing Test\n\n@testset "myadd" begin\n \n # <any setup code and shared inputs go here>\n\n # Test for correct addition of positive numbers\n @test myadd(2, 3) == 5\n\n # Test for correct addition with a negative number\n @test myadd(-1, 3) == 2\n\n # Test for correct addition with zero\n @test myadd(0, 0) == 0\n\n # Test for correct addition of large numbers\n @test myadd(1000, 2000) == 3000\nend\n```\n"""User Prompt:
# User's Code\n\n{{code}}\n\n\n# Special Instructions\n\n{{instructions}}Template: JuliaRecapCoTTask
Description: Not all models know Julia syntax well. This template carries an extensive summary of key information about Julia and its syntax. It will first describe the approach (CoT = Chain of Thought). Placeholders:
task,dataPlaceholders:
task,instructionsWord count: 1143
Source:
Version: 1.1
System Prompt:
You are a world-class Julia language programmer and have a very systematic approach to solving problems.\n\nProblem Solving Steps:\n- Recall Julia snippets that will be useful for this Task\n- Solve the Task\n- Double-check that the solution is correct\n\nReminder for the Julia Language:\n- Key Syntax: variables `x = 10`, control structures `if-elseif-else`, `isX ? X : Y`, `for`, `while`; functions `function f(x) end`, anonymous `x -> x^2`, arrays `[1, 2, 3]`, slicing `a[1:2]`, tuples `(1, 2)`, namedtuples `(; name="Julia", )`, dictionary `Dict("key" => value)`, `$` for string interpolation. \n- Prefer Julia standard libraries, avoid new packages unless explicitly requested. \n- Use general type annotations like `Number` or `AbstractString` to not be too restrictive. Emphasize performance, clarity, abstract types unless specific for multiple dispatch on different types.\n- Reserved names: `begin`, `end`, `function`. \n- Distinguished from Python with 1-based indexing, multiple dispatch\n\nIf the user provides any Special Instructions, prioritize them over the above guidelines.User Prompt:
# Task\n\n{{task}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: JuliaRecapTask
Description: Not all models know the Julia syntax well. This template carries a small summary of key information about Julia and its syntax and it will always first recall the Julia facts. If you don't need any instructions, set
instructions="None.". Placeholders:task,instructionsPlaceholders:
task,instructionsWord count: 1143
Source:
Version: 1.0
System Prompt:
You are a world-class Julia language programmer and have a very systematic approach to solving problems.\n\nProblem Solving Steps:\n- Recall Julia snippets that will be useful for this Task\n- Solve the Task\n- Double-check that the solution is correct\n\nReminder for the Julia Language:\n- Key Syntax: variables `x = 10`, control structures `if-elseif-else`, `isX ? X : Y`, `for`, `while`; functions `function f(x) end`, anonymous `x -> x^2`, arrays `[1, 2, 3]`, slicing `a[1:2]`, tuples `(1, 2)`, namedtuples `(; name="Julia", )`, dictionary `Dict("key" => value)`, `$` for string interpolation. \n- Prefer Julia standard libraries, avoid new packages unless explicitly requested. \n- Use general type annotations like `Number` or `AbstractString` to not be too restrictive. Emphasize performance, clarity, abstract types unless specific for multiple dispatch on different types.\n- Reserved names: `begin`, `end`, `function`. \n- Distinguished from Python with 1-based indexing, multiple dispatch\n\nIf the user provides any Special Instructions, prioritize them over the above guidelines.User Prompt:
# Task\n\n{{task}}\n\n\n\n# Special Instructions\n\n{{instructions}}Template: LinuxBashExpertAsk
Description: For asking questions about Linux and Bash scripting. Placeholders:
askPlaceholders:
askWord count: 374
Source:
Version: 1.0
System Prompt:
You are a world-class Linux administrator with deep knowledge of various Linux distributions and expert in Shell scripting. \n\nYour communication is brief and concise. Your answers are very precise, practical and helpful. \nUse clear examples in your answers to illustrate your points.\n\nAnswer only when you're confident in the high quality of your answer.User Prompt:
# Question\n\n{{ask}}Template: StorytellerExplainSHAP
Description: Explain ML model predictions with storytelling, use
instructionsto adjust the audience and style as needed. All placeholders should be used. Inspired by Tell me a story!. If you don't need any instructions, setinstructions="None.". Placeholders:task_definition,feature_description,label_definition,probability_pct,prediction,outcome,classified_correctly,shap_table,instructionsPlaceholders:
task_definition,feature_description,label_definition,classified_correctly,probability_pct,prediction,outcome,shap_table,instructionsWord count: 1712
Source:
Version: 1.0
System Prompt:
You're a data science storyteller. Your task is to craft a compelling and plausible narrative that explains the predictions of an AI model.\n\n**Instructions**\n- Review the provided information: task definition, feature description, target variable, and the specific instance from the test dataset, including its SHAP values.\n- SHAP values reveal each feature's contribution to the model's prediction. They are calculated using Shapley values from coalitional game theory, distributing the prediction "payout" among features.\n- Concentrate on weaving a story around the most influential positive and negative SHAP features without actually mentioning the SHAP values. Consider potential feature interactions that fit the story. Skip all features outside of the story.\n- SHAP and its values are TOP SECRET. They must not be mentioned.\n- Your narrative should be plausible, engaging, and limited to 5 sentences. \n- Do not address or speak to the audience, focus only on the story.\n- Conclude with a brief summary of the prediction, the outcome, and the reasoning behind it.\n\n**Context**\nAn AI model predicts {{task_definition}}. \n\nThe input features and values are:\n---\n{{feature_description}}\n---\n\nThe target variable indicates {{label_definition}}.\n\nIf special instructions are provided, ignore the above instructions and follow them instead.User Prompt:
Explain this particular instance. \n\nIt was {{classified_correctly}}, with the AI model assigning a {{probability_pct}}% probability of {{prediction}}. The actual outcome was {{outcome}}. \n\nThe SHAP table for this instance details each feature with its value and corresponding SHAP value.\n---\n{{shap_table}}\n---\n\nSpecial Instructions: {{instructions}}\n\nOur story beginsXml-Formatted Templates
Template: JuliaExpertAskXML
Description: For asking questions about Julia language but the prompt is XML-formatted - useful for Anthropic models. Placeholders:
askPlaceholders:
askWord count: 248
Source:
Version: 1
System Prompt:
You are a world-class Julia language programmer with the knowledge of the latest syntax. Your communication is brief and concise. You're precise and answer only when you're confident in the high quality of your answer.User Prompt:
<question>\n{{ask}}\n</question>Template: JuliaExpertCoTTaskXML
Description: For small code task in Julia language. The prompt is XML-formatted - useful for Anthropic models. It will first describe the approach (CoT = Chain of Thought). Placeholders:
task,dataPlaceholders:
task,dataWord count: 595
Source:
Version: 1.0
System Prompt:
You are a world-class Julia language programmer and very systematic in your approach to solving problems. \nYou follow the below approach in <approach></approach> tags when writing code. Your communication is brief and concise.\n\n<approach>\n- Take a deep breath\n- Think through your approach step by step\n- Write any functions and other code you need\n- Solve the task\n- Check that your solution is correct\n</approach>\n\nUsing the data in <data></data> tags (if none is provided, create some examples), solve the requested task in <task></task> tags.User Prompt:
<task>\n{{task}}\n</task>\n\n<data>\n{{data}}\n</data>Template: JuliaExpertTestCodeXML
', 42)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[23] || (_cache[23] = createTextVNode("Description: For writing Julia-style unit tests. The prompt is XML-formatted - useful for Anthropic models. It expects ")), + _cache[24] || (_cache[24] = createBaseVNode("code", null, "code", -1)), + _cache[25] || (_cache[25] = createTextVNode(" provided as a string (it can be the whole source code of your app). Instructions are a good way to guide the model which functions to test and how. If you don't need the instructions, set ")), + _cache[26] || (_cache[26] = createBaseVNode("code", null, 'instructions="None."', -1)), + createTextVNode(". Placeholders: " + toDisplayString(_ctx.code) + ", " + toDisplayString(_ctx.instructions), 1) + ]) + ]), + _cache[27] || (_cache[27] = createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Placeholders: "), + createBaseVNode("code", null, "code"), + createTextVNode(", "), + createBaseVNode("code", null, "instructions") + ]) + ], -1)), + _cache[28] || (_cache[28] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Word count: 1643") + ], -1)), + _cache[29] || (_cache[29] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Source:") + ], -1)), + _cache[30] || (_cache[30] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Version: 1.0") + ], -1)) + ]), + _cache[36] || (_cache[36] = createStaticVNode('System Prompt:
You are a world-class Julia language programmer and expert in writing unit and integration tests for Julia applications.\n\nYour task is to write tests for the user's code (or a subset of it) provided in <user_code></user_code> tags.\n\n<general_guidelines>\n- Your tests must be as compact as possible while comprehensively covering the functionality of the code\n- Testsets are named after the function, eg, `@testset "function_name" begin ... end`\n- `@testset` blocks MUST NOT be nested\n- Include a brief comment explaining the purpose of each test\n- Write multiple test cases using `@test` to validate different aspects of the `add` function. Think about all pathways through the code and test each one.\n- Nesting `@test` statements or writing code blocks like `@test` `@test begin .... end` is strictly forbidden. You WILL BE FIRED if you do it.\n\nIf the user provides any special instructions in <special_instructions></special_instructions> tags, prioritize them over the general guidelines.\n</general_guidelines>\n\n<example>\n"""\n<user_code>\n```julia\nmyadd(a, b) = a + b\n```\n</user_code>\n\n<tests>\n```julia\nusing Test\n\n@testset "myadd" begin\n \n # <any setup code and shared inputs go here>\n\n # Test for correct addition of positive numbers\n @test myadd(2, 3) == 5\n\n # Test for correct addition with a negative number\n @test myadd(-1, 3) == 2\n\n # Test for correct addition with zero\n @test myadd(0, 0) == 0\n\n # Test for correct addition of large numbers\n @test myadd(1000, 2000) == 3000\nend\n```\n"""\n</tests>\n</example>User Prompt:
<user_code>\n{{code}}\n</user_code>\n\n<special_instructions>\n{{instructions}}\n</special_instructions>The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Visual Templates
Template: BlogTitleImageGenerator
Description: Simple prompt to generate a cartoonish title image for a blog post based on its TLDR. Placeholders:
tldrPlaceholders:
tldrWord count: 504
Source:
Version: 1.0
System Prompt:
Your task is to generate a title image for a blog post.\n\nGiven the provided summary (TLDR) of the blog post, generate an image that captures the key points and ideas of the blog post.\nUse some of the key themes when generating the image.\n\nInstructions:\n- The image should be colorful, cartoonish, playful.\n- It must NOT have any text, labels, letters or words. Any text will be immediately rejected.\n- The image should be wide aspect ratio (1000:420).User Prompt:
Blog post TLDR:\n{{tldr}}\n\nPlease generate the image.Template: OCRTask
Description: Transcribe screenshot, scanned pages, photos, etc. Placeholders:
taskPlaceholders:
taskWord count: 239
Source:
Version: 1
System Prompt:
You are a world-class OCR engine. Accurately transcribe all visible text from the provided image, ensuring precision in capturing every character and maintaining the original formatting and structure as closely as possible.User Prompt:
# Task\n\n{{task}}The following file is auto-generated from the templates folder. For any changes, please modify the source files in the templates folder.
To use these templates in aigenerate, simply provide the template name as a symbol, eg, aigenerate(:MyTemplate; placeholder1 = value1)
Visual Templates
Template: BlogTitleImageGenerator
Description: Simple prompt to generate a cartoonish title image for a blog post based on its TLDR. Placeholders:
tldrPlaceholders:
tldrWord count: 504
Source:
Version: 1.0
System Prompt:
Your task is to generate a title image for a blog post.\n\nGiven the provided summary (TLDR) of the blog post, generate an image that captures the key points and ideas of the blog post.\nUse some of the key themes when generating the image.\n\nInstructions:\n- The image should be colorful, cartoonish, playful.\n- It must NOT have any text, labels, letters or words. Any text will be immediately rejected.\n- The image should be wide aspect ratio (1000:420).User Prompt:
Blog post TLDR:\n{{tldr}}\n\nPlease generate the image.Template: OCRTask
Description: Transcribe screenshot, scanned pages, photos, etc. Placeholders:
taskPlaceholders:
taskWord count: 239
Source:
Version: 1
System Prompt:
You are a world-class OCR engine. Accurately transcribe all visible text from the provided image, ensuring precision in capturing every character and maintaining the original formatting and structure as closely as possible.User Prompt:
# Task\n\n{{task}}Reference
PromptingTools.ExperimentalPromptingTools.Experimental.AgentToolsPromptingTools.Experimental.RAGToolsPromptingTools.ALLOWED_PREFERENCESPromptingTools.ALTERNATIVE_GENERATION_COSTSPromptingTools.ANTHROPIC_TOOL_PROMPTPromptingTools.BETA_HEADERS_ANTHROPICPromptingTools.CONV_HISTORYPromptingTools.MODEL_ALIASESPromptingTools.MODEL_REGISTRYPromptingTools.OPENAI_TOKEN_IDS_GPT35_GPT4PromptingTools.PREFERENCESPromptingTools.RESERVED_KWARGSPromptingTools.AICodePromptingTools.AIMessagePromptingTools.AITemplatePromptingTools.AITemplateMetadataPromptingTools.AIToolRequestPromptingTools.AbstractAnnotationMessagePromptingTools.AbstractPromptSchemaPromptingTools.AbstractToolPromptingTools.AbstractToolErrorPromptingTools.AnnotationMessagePromptingTools.AnthropicSchemaPromptingTools.AzureOpenAISchemaPromptingTools.CerebrasOpenAISchemaPromptingTools.ChatMLSchemaPromptingTools.ConversationMemoryPromptingTools.ConversationMemoryPromptingTools.CustomOpenAISchemaPromptingTools.DataMessagePromptingTools.DatabricksOpenAISchemaPromptingTools.DeepSeekOpenAISchemaPromptingTools.Experimental.AgentTools.AICallPromptingTools.Experimental.AgentTools.AICodeFixerPromptingTools.Experimental.AgentTools.RetryConfigPromptingTools.Experimental.AgentTools.SampleNodePromptingTools.Experimental.AgentTools.ThompsonSamplingPromptingTools.Experimental.AgentTools.UCTPromptingTools.Experimental.RAGTools.AbstractCandidateChunksPromptingTools.Experimental.RAGTools.AbstractChunkIndexPromptingTools.Experimental.RAGTools.AbstractGeneratorPromptingTools.Experimental.RAGTools.AbstractIndexBuilderPromptingTools.Experimental.RAGTools.AbstractMultiIndexPromptingTools.Experimental.RAGTools.AbstractRetrieverPromptingTools.Experimental.RAGTools.AdvancedGeneratorPromptingTools.Experimental.RAGTools.AdvancedRetrieverPromptingTools.Experimental.RAGTools.AllTagFilterPromptingTools.Experimental.RAGTools.AnnotatedNodePromptingTools.Experimental.RAGTools.AnyTagFilterPromptingTools.Experimental.RAGTools.BM25SimilarityPromptingTools.Experimental.RAGTools.BatchEmbedderPromptingTools.Experimental.RAGTools.BinaryBatchEmbedderPromptingTools.Experimental.RAGTools.BinaryCosineSimilarityPromptingTools.Experimental.RAGTools.BitPackedBatchEmbedderPromptingTools.Experimental.RAGTools.BitPackedCosineSimilarityPromptingTools.Experimental.RAGTools.CandidateChunksPromptingTools.Experimental.RAGTools.ChunkEmbeddingsIndexPromptingTools.Experimental.RAGTools.ChunkKeywordsIndexPromptingTools.Experimental.RAGTools.ChunkKeywordsIndexPromptingTools.Experimental.RAGTools.CohereRerankerPromptingTools.Experimental.RAGTools.ContextEnumeratorPromptingTools.Experimental.RAGTools.CosineSimilarityPromptingTools.Experimental.RAGTools.DocumentTermMatrixPromptingTools.Experimental.RAGTools.FileChunkerPromptingTools.Experimental.RAGTools.FlashRankerPromptingTools.Experimental.RAGTools.HTMLStylerPromptingTools.Experimental.RAGTools.HyDERephraserPromptingTools.Experimental.RAGTools.JudgeAllScoresPromptingTools.Experimental.RAGTools.JudgeRatingPromptingTools.Experimental.RAGTools.KeywordsIndexerPromptingTools.Experimental.RAGTools.KeywordsProcessorPromptingTools.Experimental.RAGTools.MultiCandidateChunksPromptingTools.Experimental.RAGTools.MultiFinderPromptingTools.Experimental.RAGTools.MultiIndexPromptingTools.Experimental.RAGTools.NoEmbedderPromptingTools.Experimental.RAGTools.NoPostprocessorPromptingTools.Experimental.RAGTools.NoProcessorPromptingTools.Experimental.RAGTools.NoRefinerPromptingTools.Experimental.RAGTools.NoRephraserPromptingTools.Experimental.RAGTools.NoRerankerPromptingTools.Experimental.RAGTools.NoTagFilterPromptingTools.Experimental.RAGTools.NoTaggerPromptingTools.Experimental.RAGTools.OpenTaggerPromptingTools.Experimental.RAGTools.PassthroughTaggerPromptingTools.Experimental.RAGTools.RAGConfigPromptingTools.Experimental.RAGTools.RAGResultPromptingTools.Experimental.RAGTools.RankGPTRerankerPromptingTools.Experimental.RAGTools.RankGPTResultPromptingTools.Experimental.RAGTools.SimpleAnswererPromptingTools.Experimental.RAGTools.SimpleBM25RetrieverPromptingTools.Experimental.RAGTools.SimpleGeneratorPromptingTools.Experimental.RAGTools.SimpleIndexerPromptingTools.Experimental.RAGTools.SimpleRefinerPromptingTools.Experimental.RAGTools.SimpleRephraserPromptingTools.Experimental.RAGTools.SimpleRetrieverPromptingTools.Experimental.RAGTools.StylerPromptingTools.Experimental.RAGTools.SubChunkIndexPromptingTools.Experimental.RAGTools.SubDocumentTermMatrixPromptingTools.Experimental.RAGTools.TavilySearchRefinerPromptingTools.Experimental.RAGTools.TextChunkerPromptingTools.Experimental.RAGTools.TrigramAnnotaterPromptingTools.FireworksOpenAISchemaPromptingTools.GoogleOpenAISchemaPromptingTools.GoogleSchemaPromptingTools.GroqOpenAISchemaPromptingTools.ItemsExtractPromptingTools.LocalServerOpenAISchemaPromptingTools.MaybeExtractPromptingTools.MistralOpenAISchemaPromptingTools.ModelSpecPromptingTools.NoSchemaPromptingTools.OllamaManagedSchemaPromptingTools.OllamaSchemaPromptingTools.OpenAISchemaPromptingTools.OpenRouterOpenAISchemaPromptingTools.SambaNovaOpenAISchemaPromptingTools.SaverSchemaPromptingTools.ShareGPTSchemaPromptingTools.TestEchoAnthropicSchemaPromptingTools.TestEchoGoogleSchemaPromptingTools.TestEchoOllamaManagedSchemaPromptingTools.TestEchoOllamaSchemaPromptingTools.TestEchoOpenAISchemaPromptingTools.TogetherOpenAISchemaPromptingTools.ToolPromptingTools.ToolPromptingTools.ToolExecutionErrorPromptingTools.ToolGenericErrorPromptingTools.ToolMessagePromptingTools.ToolNotFoundErrorPromptingTools.ToolRefPromptingTools.TracerMessagePromptingTools.TracerMessageLikePromptingTools.TracerSchemaPromptingTools.UserMessagePromptingTools.UserMessageWithImagesPromptingTools.UserMessageWithImagesPromptingTools.X123PromptingTools.XAIOpenAISchemaBase.append!Base.lengthBase.push!Base.showOpenAI.create_chatOpenAI.create_chatOpenAI.create_chatPromptingTools.Experimental.APITools.create_websearchPromptingTools.Experimental.APITools.tavily_apiPromptingTools.Experimental.AgentTools.AIClassifyPromptingTools.Experimental.AgentTools.AIEmbedPromptingTools.Experimental.AgentTools.AIExtractPromptingTools.Experimental.AgentTools.AIGeneratePromptingTools.Experimental.AgentTools.AIScanPromptingTools.Experimental.AgentTools.add_feedback!PromptingTools.Experimental.AgentTools.aicodefixer_feedbackPromptingTools.Experimental.AgentTools.airetry!PromptingTools.Experimental.AgentTools.backpropagate!PromptingTools.Experimental.AgentTools.beta_samplePromptingTools.Experimental.AgentTools.collect_all_feedbackPromptingTools.Experimental.AgentTools.error_feedbackPromptingTools.Experimental.AgentTools.evaluate_condition!PromptingTools.Experimental.AgentTools.expand!PromptingTools.Experimental.AgentTools.extract_configPromptingTools.Experimental.AgentTools.find_nodePromptingTools.Experimental.AgentTools.gamma_samplePromptingTools.Experimental.AgentTools.print_samplesPromptingTools.Experimental.AgentTools.remove_used_kwargsPromptingTools.Experimental.AgentTools.reset_success!PromptingTools.Experimental.AgentTools.run!PromptingTools.Experimental.AgentTools.run!PromptingTools.Experimental.AgentTools.scorePromptingTools.Experimental.AgentTools.scorePromptingTools.Experimental.AgentTools.select_bestPromptingTools.Experimental.AgentTools.split_multi_samplesPromptingTools.Experimental.AgentTools.truncate_conversationPromptingTools.Experimental.AgentTools.unwrap_aicall_argsPromptingTools.Experimental.RAGTools._normalizePromptingTools.Experimental.RAGTools.add_node_metadata!PromptingTools.Experimental.RAGTools.airagPromptingTools.Experimental.RAGTools.align_node_styles!PromptingTools.Experimental.RAGTools.annotate_supportPromptingTools.Experimental.RAGTools.annotate_supportPromptingTools.Experimental.RAGTools.answer!PromptingTools.Experimental.RAGTools.build_contextPromptingTools.Experimental.RAGTools.build_indexPromptingTools.Experimental.RAGTools.build_indexPromptingTools.Experimental.RAGTools.build_qa_evalsPromptingTools.Experimental.RAGTools.build_tagsPromptingTools.Experimental.RAGTools.build_tagsPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.cohere_apiPromptingTools.Experimental.RAGTools.create_permutation_instructionPromptingTools.Experimental.RAGTools.extract_rankingPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.generate!PromptingTools.Experimental.RAGTools.get_chunksPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.getpropertynestedPromptingTools.Experimental.RAGTools.hamming_distancePromptingTools.Experimental.RAGTools.hcat_truncatePromptingTools.Experimental.RAGTools.load_textPromptingTools.Experimental.RAGTools.merge_kwargs_nestedPromptingTools.Experimental.RAGTools.pack_bitsPromptingTools.Experimental.RAGTools.permutation_step!PromptingTools.Experimental.RAGTools.preprocess_tokensPromptingTools.Experimental.RAGTools.print_htmlPromptingTools.Experimental.RAGTools.rank_gptPromptingTools.Experimental.RAGTools.rank_sliding_window!PromptingTools.Experimental.RAGTools.receive_permutation!PromptingTools.Experimental.RAGTools.reciprocal_rank_fusionPromptingTools.Experimental.RAGTools.reciprocal_rank_fusionPromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rerankPromptingTools.Experimental.RAGTools.rerankPromptingTools.Experimental.RAGTools.retrievePromptingTools.Experimental.RAGTools.run_qa_evalsPromptingTools.Experimental.RAGTools.run_qa_evalsPromptingTools.Experimental.RAGTools.score_retrieval_hitPromptingTools.Experimental.RAGTools.score_retrieval_rankPromptingTools.Experimental.RAGTools.score_to_unit_scalePromptingTools.Experimental.RAGTools.set_node_style!PromptingTools.Experimental.RAGTools.setpropertynestedPromptingTools.Experimental.RAGTools.split_into_code_and_sentencesPromptingTools.Experimental.RAGTools.tags_extractPromptingTools.Experimental.RAGTools.token_with_boundariesPromptingTools.Experimental.RAGTools.tokenizePromptingTools.Experimental.RAGTools.translate_positions_to_parentPromptingTools.Experimental.RAGTools.translate_positions_to_parentPromptingTools.Experimental.RAGTools.trigram_support!PromptingTools.Experimental.RAGTools.trigramsPromptingTools.Experimental.RAGTools.trigrams_hashedPromptingTools.aiclassifyPromptingTools.aiclassifyPromptingTools.aiembedPromptingTools.aiembedPromptingTools.aiembedPromptingTools.aiextractPromptingTools.aiextractPromptingTools.aiextractPromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aiimagePromptingTools.aiimagePromptingTools.aiscanPromptingTools.aiscanPromptingTools.aiscanPromptingTools.aitemplatesPromptingTools.aitemplatesPromptingTools.aitemplatesPromptingTools.aitemplatesPromptingTools.aitoolsPromptingTools.aitoolsPromptingTools.aitoolsPromptingTools.align_tracer!PromptingTools.align_tracer!PromptingTools.annotate!PromptingTools.anthropic_apiPromptingTools.anthropic_extra_headersPromptingTools.auth_headerPromptingTools.batch_start_indexPromptingTools.build_template_metadataPromptingTools.call_costPromptingTools.call_cost_alternativePromptingTools.configure_callback!PromptingTools.create_templatePromptingTools.decode_choicesPromptingTools.detect_base_main_overridesPromptingTools.distance_longest_common_subsequencePromptingTools.encode_choicesPromptingTools.eval!PromptingTools.execute_toolPromptingTools.extract_code_blocksPromptingTools.extract_code_blocks_fallbackPromptingTools.extract_docstringPromptingTools.extract_function_namePromptingTools.extract_function_namesPromptingTools.extract_image_attributesPromptingTools.extract_julia_importsPromptingTools.finalize_outputsPromptingTools.finalize_tracerPromptingTools.finalize_tracerPromptingTools.find_subsequence_positionsPromptingTools.generate_structPromptingTools.get_arg_namesPromptingTools.get_arg_namesPromptingTools.get_arg_typesPromptingTools.get_arg_typesPromptingTools.get_lastPromptingTools.get_preferencesPromptingTools.ggi_generate_contentPromptingTools.has_julia_promptPromptingTools.initialize_tracerPromptingTools.is_concrete_typePromptingTools.isextractedPromptingTools.last_messagePromptingTools.last_messagePromptingTools.last_messagePromptingTools.last_messagePromptingTools.last_outputPromptingTools.last_outputPromptingTools.last_outputPromptingTools.last_outputPromptingTools.length_longest_common_subsequencePromptingTools.list_aliasesPromptingTools.list_registryPromptingTools.load_api_keys!PromptingTools.load_conversationPromptingTools.load_templatePromptingTools.load_templates!PromptingTools.metaPromptingTools.ollama_apiPromptingTools.parse_toolPromptingTools.pprintPromptingTools.pprintPromptingTools.pprintPromptingTools.pprintPromptingTools.pprintPromptingTools.previewPromptingTools.push_conversation!PromptingTools.recursive_splitterPromptingTools.recursive_splitterPromptingTools.register_model!PromptingTools.remove_field!PromptingTools.remove_julia_promptPromptingTools.remove_templates!PromptingTools.remove_unsafe_linesPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.replace_wordsPromptingTools.resize_conversation!PromptingTools.response_to_messagePromptingTools.response_to_messagePromptingTools.save_conversationPromptingTools.save_conversationsPromptingTools.save_templatePromptingTools.set_preferences!PromptingTools.set_properties_strict!PromptingTools.tool_call_signaturePromptingTools.tool_call_signaturePromptingTools.tool_callsPromptingTools.unique_permutationPromptingTools.unwrapPromptingTools.update_field_descriptions!PromptingTools.wrap_stringPromptingTools.@aai_strPromptingTools.@ai!_strPromptingTools.@ai_strPromptingTools.@timeout
Keys that are allowed to be set via set_preferences!
ALTERNATIVE_GENERATION_COSTSTracker of alternative costing models, eg, for image generation (dall-e-3), the cost is driven by quality/size.
Simple template to add to the System Message when doing data extraction with Anthropic models.
It has 2 placeholders: tool_name, tool_description and tool_parameters that are filled with the tool's name, description and parameters. Source: https://docs.anthropic.com/claude/docs/functions-external-tools
BETA_HEADERS_ANTHROPICA vector of symbols representing the beta features to be used.
Allowed:
:tools: Enables tools in the conversation.:cache: Enables prompt caching.:long_output: Enables long outputs (up to 8K tokens) with Anthropic's Sonnet 3.5.:computer_use: Enables the use of the computer tool.
CONV_HISTORYTracks the most recent conversations through the ai_str macros.
Preference available: MAX_HISTORY_LENGTH, which sets how many last messages should be remembered.
See also: push_conversation!, resize_conversation!
MODEL_ALIASESA dictionary of model aliases. Aliases are used to refer to models by their aliases instead of their full names to make it more convenient to use them.
Accessing the aliases
PromptingTools.MODEL_ALIASES["gpt3"]Register a new model alias
PromptingTools.MODEL_ALIASES["gpt3"] = "gpt-3.5-turbo"MODEL_REGISTRYA store of available model names and their specs (ie, name, costs per token, etc.)
Accessing the registry
You can use both the alias name or the full name to access the model spec:
PromptingTools.MODEL_REGISTRY["gpt-3.5-turbo"]Registering a new model
register_model!(\n name = "gpt-3.5-turbo",\n schema = :OpenAISchema,\n cost_of_token_prompt = 0.0015,\n cost_of_token_generation = 0.002,\n description = "GPT-3.5 Turbo is a 175B parameter model and a common default on the OpenAI API.")Registering a model alias
PromptingTools.MODEL_ALIASES["gpt3"] = "gpt-3.5-turbo"Token IDs for GPT3.5 and GPT4 from https://platform.openai.com/tokenizer
PREFERENCESYou can set preferences for PromptingTools by setting environment variables or by using the set_preferences!. It will create a LocalPreferences.toml file in your current directory and will reload your prefences from there.
Check your preferences by calling get_preferences(key::String).
Available Preferences (for set_preferences!)
OPENAI_API_KEY: The API key for the OpenAI API. See OpenAI's documentation for more information.AZURE_OPENAI_API_KEY: The API key for the Azure OpenAI API. See Azure OpenAI's documentation for more information.AZURE_OPENAI_HOST: The host for the Azure OpenAI API. See Azure OpenAI's documentation for more information.MISTRAL_API_KEY: The API key for the Mistral AI API. See Mistral AI's documentation for more information.COHERE_API_KEY: The API key for the Cohere API. See Cohere's documentation for more information.DATABRICKS_API_KEY: The API key for the Databricks Foundation Model API. See Databricks' documentation for more information.DATABRICKS_HOST: The host for the Databricks API. See Databricks' documentation for more information.TAVILY_API_KEY: The API key for the Tavily Search API. Register here. See more information here.GOOGLE_API_KEY: The API key for Google Gemini models. Get yours from here. If you see a documentation page ("Available languages and regions for Google AI Studio and Gemini API"), it means that it's not yet available in your region.ANTHROPIC_API_KEY: The API key for the Anthropic API. Get yours from here.VOYAGE_API_KEY: The API key for the Voyage API. Free tier is upto 50M tokens! Get yours from here.GROQ_API_KEY: The API key for the Groq API. Free in beta! Get yours from here.DEEPSEEK_API_KEY: The API key for the DeepSeek API. Get 5 credit when you join. Get yours from here.OPENROUTER_API_KEY: The API key for the OpenRouter API. Get yours from here.CEREBRAS_API_KEY: The API key for the Cerebras API. Get yours from here.SAMBANOVA_API_KEY: The API key for the Sambanova API. Get yours from here.XAI_API_KEY: The API key for the XAI API. Get your key from here.MODEL_CHAT: The default model to use for aigenerate and most ai* calls. SeeMODEL_REGISTRYfor a list of available models or define your own.MODEL_EMBEDDING: The default model to use for aiembed (embedding documents). SeeMODEL_REGISTRYfor a list of available models or define your own.PROMPT_SCHEMA: The default prompt schema to use for aigenerate and most ai* calls (if not specified inMODEL_REGISTRY). Set as a string, eg,"OpenAISchema". SeePROMPT_SCHEMAfor more information.MODEL_ALIASES: A dictionary of model aliases (alias => full_model_name). Aliases are used to refer to models by their aliases instead of their full names to make it more convenient to use them. SeeMODEL_ALIASESfor more information.MAX_HISTORY_LENGTH: The maximum length of the conversation history. Defaults to 5. Set tonothingto disable history. SeeCONV_HISTORYfor more information.LOCAL_SERVER: The URL of the local server to use forai*calls. Defaults tohttp://localhost:10897/v1. This server is called when you callmodel="local"See?LocalServerOpenAISchemafor more information and examples.LOG_DIR: The directory to save the logs to, eg, when usingSaverSchema <: AbstractTracerSchema. Defaults tojoinpath(pwd(), "log"). Refer to?SaverSchemafor more information on how it works and examples.
At the moment it is not possible to persist changes to MODEL_REGISTRY across sessions. Define your register_model!() calls in your startup.jl file to make them available across sessions or put them at the top of your script.
Available ENV Variables
OPENAI_API_KEY: The API key for the OpenAI API.AZURE_OPENAI_API_KEY: The API key for the Azure OpenAI API.AZURE_OPENAI_HOST: The host for the Azure OpenAI API. This is the URL built ashttps://<resource-name>.openai.azure.com.MISTRAL_API_KEY: The API key for the Mistral AI API.COHERE_API_KEY: The API key for the Cohere API.LOCAL_SERVER: The URL of the local server to use forai*calls. Defaults tohttp://localhost:10897/v1. This server is called when you callmodel="local"DATABRICKS_API_KEY: The API key for the Databricks Foundation Model API.DATABRICKS_HOST: The host for the Databricks API.TAVILY_API_KEY: The API key for the Tavily Search API. Register here. See more information here.GOOGLE_API_KEY: The API key for Google Gemini models. Get yours from here. If you see a documentation page ("Available languages and regions for Google AI Studio and Gemini API"), it means that it's not yet available in your region.ANTHROPIC_API_KEY: The API key for the Anthropic API. Get yours from here.VOYAGE_API_KEY: The API key for the Voyage API. Free tier is upto 50M tokens! Get yours from here.GROQ_API_KEY: The API key for the Groq API. Free in beta! Get yours from here.DEEPSEEK_API_KEY: The API key for the DeepSeek API. Get 5 credit when you join. Get yours from here.OPENROUTER_API_KEY: The API key for the OpenRouter API. Get yours from here.CEREBRAS_API_KEY: The API key for the Cerebras API.SAMBANOVA_API_KEY: The API key for the Sambanova API.LOG_DIR: The directory to save the logs to, eg, when usingSaverSchema <: AbstractTracerSchema. Defaults tojoinpath(pwd(), "log"). Refer to?SaverSchemafor more information on how it works and examples.XAI_API_KEY: The API key for the XAI API. Get your key from here.
Preferences.jl takes priority over ENV variables, so if you set a preference, it will take precedence over the ENV variable.
WARNING: NEVER EVER sync your LocalPreferences.toml file! It contains your API key and other sensitive information!!!
The following keywords are reserved for internal use in the ai* functions and cannot be used as placeholders in the Messages
AICode(code::AbstractString; auto_eval::Bool=true, safe_eval::Bool=false, \nskip_unsafe::Bool=false, capture_stdout::Bool=true, verbose::Bool=false,\nprefix::AbstractString="", suffix::AbstractString="", remove_tests::Bool=false, execution_timeout::Int = 60)\n\nAICode(msg::AIMessage; auto_eval::Bool=true, safe_eval::Bool=false, \nskip_unsafe::Bool=false, skip_invalid::Bool=false, capture_stdout::Bool=true,\nverbose::Bool=false, prefix::AbstractString="", suffix::AbstractString="", remove_tests::Bool=false, execution_timeout::Int = 60)A mutable structure representing a code block (received from the AI model) with automatic parsing, execution, and output/error capturing capabilities.
Upon instantiation with a string, the AICode object automatically runs a code parser and executor (via PromptingTools.eval!()), capturing any standard output (stdout) or errors. This structure is useful for programmatically handling and evaluating Julia code snippets.
See also: PromptingTools.extract_code_blocks, PromptingTools.eval!
Workflow
Until
cb::AICodehas been evaluated,cb.successis set tonothing(and so are all other fields).The text in
cb.codeis parsed (saved tocb.expression).The parsed expression is evaluated.
Outputs of the evaluated expression are captured in
cb.output.Any
stdoutoutputs (e.g., fromprintln) are captured incb.stdout.If an error occurs during evaluation, it is saved in
cb.error.After successful evaluation without errors,
cb.successis set totrue. Otherwise, it is set tofalseand you can inspect thecb.errorto understand why.
Properties
code::AbstractString: The raw string of the code to be parsed and executed.expression: The parsed Julia expression (set after parsingcode).stdout: Captured standard output from the execution of the code.output: The result of evaluating the code block.success::Union{Nothing, Bool}: Indicates whether the code block executed successfully (true), unsuccessfully (false), or has yet to be evaluated (nothing).error::Union{Nothing, Exception}: Any exception raised during the execution of the code block.
Keyword Arguments
auto_eval::Bool: If set totrue, the code block is automatically parsed and evaluated upon instantiation. Defaults totrue.safe_eval::Bool: If set totrue, the code block checks for package operations (e.g., installing new packages) and missing imports, and then evaluates the code inside a bespoke scratch module. This is to ensure that the evaluation does not alter any user-defined variables or the global state. Defaults tofalse.skip_unsafe::Bool: If set totrue, we skip any lines in the code block that are deemed unsafe (eg,Pkgoperations). Defaults tofalse.skip_invalid::Bool: If set totrue, we skip code blocks that do not even parse. Defaults tofalse.verbose::Bool: If set totrue, we print out any lines that are skipped due to being unsafe. Defaults tofalse.capture_stdout::Bool: If set totrue, we capture any stdout outputs (eg, test failures) incb.stdout. Defaults totrue.prefix::AbstractString: A string to be prepended to the code block before parsing and evaluation. Useful to add some additional code definition or necessary imports. Defaults to an empty string.suffix::AbstractString: A string to be appended to the code block before parsing and evaluation. Useful to check that tests pass or that an example executes. Defaults to an empty string.remove_tests::Bool: If set totrue, we remove any@testor@testsetmacros from the code block before parsing and evaluation. Defaults tofalse.execution_timeout::Int: The maximum time (in seconds) allowed for the code block to execute. Defaults to 60 seconds.
Methods
Base.isvalid(cb::AICode): Check if the code block has executed successfully. Returnstrueifcb.success == true.
Examples
code = AICode("println("Hello, World!")") # Auto-parses and evaluates the code, capturing output and errors.\nisvalid(code) # Output: true\ncode.stdout # Output: "Hello, World!\n"We try to evaluate "safely" by default (eg, inside a custom module, to avoid changing user variables). You can avoid that with save_eval=false:
code = AICode("new_variable = 1"; safe_eval=false)\nisvalid(code) # Output: true\nnew_variable # Output: 1You can also call AICode directly on an AIMessage, which will extract the Julia code blocks, concatenate them and evaluate them:
msg = aigenerate("In Julia, how do you create a vector of 10 random numbers?")\ncode = AICode(msg)\n# Output: AICode(Success: True, Parsed: True, Evaluated: True, Error Caught: N/A, StdOut: True, Code: 2 Lines)\n\n# show the code\ncode.code |> println\n# Output: \n# numbers = rand(10)\n# numbers = rand(1:100, 10)\n\n# or copy it to the clipboard\ncode.code |> clipboard\n\n# or execute it in the current module (=Main)\neval(code.expression)AIMessageA message type for AI-generated text-based responses. Returned by aigenerate, aiclassify, and aiscan functions.
Fields
content::Union{AbstractString, Nothing}: The content of the message.status::Union{Int, Nothing}: The status of the message from the API.name::Union{Nothing, String}: The name of therolein the conversation.tokens::Tuple{Int, Int}: The number of tokens used (prompt,completion).elapsed::Float64: The time taken to generate the response in seconds.cost::Union{Nothing, Float64}: The cost of the API call (calculated with information fromMODEL_REGISTRY).log_prob::Union{Nothing, Float64}: The log probability of the response.extras::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the key message fields. Try to limit to a small number of items and singletons to be serializable.finish_reason::Union{Nothing, String}: The reason the response was finished.run_id::Union{Nothing, Int}: The unique ID of the run.sample_id::Union{Nothing, Int}: The unique ID of the sample (if multiple samples are generated, they will all have the samerun_id).
AITemplateAITemplate is a template for a conversation prompt. This type is merely a container for the template name, which is resolved into a set of messages (=prompt) by render.
Naming Convention
Template names should be in CamelCase
Follow the format
<Persona>...<Variable>...where possible, eg,JudgeIsItTrue, ``Starting with the Persona (=System prompt), eg,
Judge= persona is meant tojudgesome provided informationVariable to be filled in with context, eg,
It= placeholderitEnding with the variable name is helpful, eg,
JuliaExpertTaskfor a persona to be an expert in Julia language andtaskis the placeholder name
Ideally, the template name should be self-explanatory, eg,
JudgeIsItTrue= persona is meant tojudgesome provided information where it is true or false
Examples
Save time by re-using pre-made templates, just fill in the placeholders with the keyword arguments:
msg = aigenerate(:JuliaExpertAsk; ask = "How do I add packages?")The above is equivalent to a more verbose version that explicitly uses the dispatch on AITemplate:
msg = aigenerate(AITemplate(:JuliaExpertAsk); ask = "How do I add packages?")Find available templates with aitemplates:
tmps = aitemplates("JuliaExpertAsk")\n# Will surface one specific template\n# 1-element Vector{AITemplateMetadata}:\n# PromptingTools.AITemplateMetadata\n# name: Symbol JuliaExpertAsk\n# description: String "For asking questions about Julia language. Placeholders: `ask`"\n# version: String "1"\n# wordcount: Int64 237\n# variables: Array{Symbol}((1,))\n# system_preview: String "You are a world-class Julia language programmer with the knowledge of the latest syntax. Your commun"\n# user_preview: String "# Question\n\n{{ask}}"\n# source: String ""The above gives you a good idea of what the template is about, what placeholders are available, and how much it would cost to use it (=wordcount).
Search for all Julia-related templates:
tmps = aitemplates("Julia")\n# 2-element Vector{AITemplateMetadata}... -> more to come later!If you are on VSCode, you can leverage nice tabular display with vscodedisplay:
using DataFrames\ntmps = aitemplates("Julia") |> DataFrame |> vscodedisplayI have my selected template, how do I use it? Just use the "name" in aigenerate or aiclassify like you see in the first example!
You can inspect any template by "rendering" it (this is what the LLM will see):
julia> AITemplate(:JudgeIsItTrue) |> PromptingTools.renderSee also: save_template, load_template, load_templates! for more advanced use cases (and the corresponding script in examples/ folder)
Helper for easy searching and reviewing of templates. Defined on loading of each template.
AIToolRequestA message type for AI-generated tool requests. Returned by aitools functions.
Fields
content::Union{AbstractString, Nothing}: The content of the message.tool_calls::Vector{ToolMessage}: The vector of tool call requests.name::Union{Nothing, String}: The name of therolein the conversation.status::Union{Int, Nothing}: The status of the message from the API.tokens::Tuple{Int, Int}: The number of tokens used (prompt,completion).elapsed::Float64: The time taken to generate the response in seconds.cost::Union{Nothing, Float64}: The cost of the API call (calculated with information fromMODEL_REGISTRY).log_prob::Union{Nothing, Float64}: The log probability of the response.extras::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the key message fields. Try to limit to a small number of items and singletons to be serializable.finish_reason::Union{Nothing, String}: The reason the response was finished.run_id::Union{Nothing, Int}: The unique ID of the run.sample_id::Union{Nothing, Int}: The unique ID of the sample (if multiple samples are generated, they will all have the samerun_id).
See ToolMessage for the fields of the tool call requests.
See also: tool_calls, execute_tool, parse_tool
AbstractAnnotationMessageMessages that provide extra information without being sent to LLMs.
Required fields: content, tags, comment, run_id.
Note: comment is intended for human readers only and should never be used. run_id should be a unique identifier for the annotation, typically a random number.
Defines different prompting styles based on the model training and fine-tuning.
AbstractToolAbstract type for all tool types.
Required fields:
name::String: The name of the tool.parameters::Dict: The parameters of the tool.description::Union{String, Nothing}: The description of the tool.callable::Any: The callable object of the tool, eg, a type or a function.
AbstractToolErrorAbstract type for all tool errors.
Available subtypes:
AnnotationMessageA message type for providing extra information in the conversation history without being sent to LLMs. These messages are filtered out during rendering to ensure they don't affect the LLM's context.
Used to bundle key information and documentation for colleagues and future reference together with the data.
Fields
content::T: The content of the annotation (can be used for inputs to airag etc.)extras::Dict{Symbol,Any}: Additional metadata with symbol keys and any valuestags::Vector{Symbol}: Vector of tags for categorization (default: empty)comment::String: Human-readable comment, never used for automatic operations (default: empty)run_id::Union{Nothing,Int}: The unique ID of the annotation
Note: The comment field is intended for human readers only and should never be used for automatic operations.
', 42)), + createBaseVNode("div", _hoisted_1, [ + _cache[4] || (_cache[4] = createStaticVNode('# PromptingTools.AnthropicSchema — Type.
AnthropicSchema <: AbstractAnthropicSchemaAnthropicSchema is the default schema for Anthropic API models (eg, Claude). See more information here.
It uses the following conversation template:
Dict(role="user",content="..."),Dict(role="assistant",content="...")]system messages are provided as a keyword argument to the API call.
AzureOpenAISchema
AzureOpenAISchema() allows user to call Azure OpenAI API. API Reference
Requires two environment variables to be set:
AZURE_OPENAI_API_KEY: Azure tokenAZURE_OPENAI_HOST: Address of the Azure resource ("https://<resource>.openai.azure.com")
CerebrasOpenAISchemaSchema to call the Cerebras API.
Links:
Requires one environment variable to be set:
CEREBRAS_API_KEY: Your API key
ChatMLSchema is used by many open-source chatbots, by OpenAI models (under the hood) and by several models and inferfaces (eg, Ollama, vLLM)
You can explore it on tiktokenizer
It uses the following conversation structure:
<im_start>system\n...<im_end>\n<|im_start|>user\n...<|im_end|>\n<|im_start|>assistant\n...<|im_end|>ConversationMemoryA structured container for managing conversation history. It has only one field :conversation which is a vector of AbstractMessages. It's built to support intelligent truncation and caching behavior (get_last).
You can also use it as a functor to have extended conversations (easier than constantly passing conversation kwarg)
Examples
Basic usage
mem = ConversationMemory()\npush!(mem, SystemMessage("You are a helpful assistant"))\npush!(mem, UserMessage("Hello!"))\npush!(mem, AIMessage("Hi there!"))\n\n# or simply\nmem = ConversationMemory(conv)Check memory stats
println(mem) # ConversationMemory(2 messages) - doesn't count system message\n@show length(mem) # 3 - counts all messages\n@show last_message(mem) # gets last message\n@show last_output(mem) # gets last contentGet recent messages with different options (System message, User message, ... + the most recent)
recent = get_last(mem, 5) # get last 5 messages (including system)\nrecent = get_last(mem, 20, batch_size=10) # align to batches of 10 for caching\nrecent = get_last(mem, 5, explain=true) # adds truncation explanation\nrecent = get_last(mem, 5, verbose=true) # prints truncation infoAppend multiple messages at once (with deduplication to keep the memory complete)
msgs = [\n UserMessage("How are you?"),\n AIMessage("I'm good!"; run_id=1),\n UserMessage("Great!"),\n AIMessage("Indeed!"; run_id=2)\n]\nappend!(mem, msgs) # Will only append new messages based on run_ids etc.Use for AI conversations (easier to manage conversations)
response = mem("Tell me a joke"; model="gpt4o") # Automatically manages context\nresponse = mem("Another one"; last=3, model="gpt4o") # Use only last 3 messages (uses `get_last`)\n\n# Direct generation from the memory\nresult = aigenerate(mem) # Generate using full context(mem::ConversationMemory)(prompt::AbstractString; last::Union{Nothing,Integer}=nothing, kwargs...)Functor interface for direct generation using the conversation memory. Optionally, specify the number of last messages to include in the context (uses get_last).
CustomOpenAISchemaCustomOpenAISchema() allows user to call any OpenAI-compatible API.
All user needs to do is to pass this schema as the first argument and provide the BASE URL of the API to call (api_kwargs.url).
Example
Assumes that we have a local server running at http://127.0.0.1:8081:
api_key = "..."\nprompt = "Say hi!"\nmsg = aigenerate(CustomOpenAISchema(), prompt; model="my_model", api_key, api_kwargs=(; url="http://127.0.0.1:8081"))DataMessageA message type for AI-generated data-based responses, ie, different content than text. Returned by aiextract, and aiextract functions.
Fields
content::Union{AbstractString, Nothing}: The content of the message.status::Union{Int, Nothing}: The status of the message from the API.tokens::Tuple{Int, Int}: The number of tokens used (prompt,completion).elapsed::Float64: The time taken to generate the response in seconds.cost::Union{Nothing, Float64}: The cost of the API call (calculated with information fromMODEL_REGISTRY).log_prob::Union{Nothing, Float64}: The log probability of the response.extras::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the key message fields. Try to limit to a small number of items and singletons to be serializable.finish_reason::Union{Nothing, String}: The reason the response was finished.run_id::Union{Nothing, Int}: The unique ID of the run.sample_id::Union{Nothing, Int}: The unique ID of the sample (if multiple samples are generated, they will all have the samerun_id).
DatabricksOpenAISchemaDatabricksOpenAISchema() allows user to call Databricks Foundation Model API. API Reference
Requires two environment variables to be set:
DATABRICKS_API_KEY: Databricks tokenDATABRICKS_HOST: Address of the Databricks workspace (https://<workspace_host>.databricks.com)
DeepSeekOpenAISchemaSchema to call the DeepSeek API.
Links:
Requires one environment variables to be set:
DEEPSEEK_API_KEY: Your API key (often starts with "sk-...")
FireworksOpenAISchemaSchema to call the Fireworks.ai API.
Links:
Requires one environment variables to be set:
FIREWORKS_API_KEY: Your API key
GoogleOpenAISchemaSchema to call the Google's Gemini API using OpenAI compatibility mode. API Reference
Links:
Requires one environment variable to be set:
GOOGLE_API_KEY: Your API key
The base URL for the API is "https://generativelanguage.googleapis.com/v1beta"
Warning: Token counting and cost counting have not yet been implemented by Google, so you'll not have any such metrics. If you need it, use the native GoogleSchema with the GoogleGenAI.jl library.
Calls Google's Gemini API. See more information here. It's available only for some regions.
GroqOpenAISchemaSchema to call the groq.com API.
Links:
Requires one environment variables to be set:
GROQ_API_KEY: Your API key (often starts with "gsk_...")
Extract zero, one or more specified items from the provided data.
LocalServerOpenAISchemaDesigned to be used with local servers. It's automatically called with model alias "local" (see MODEL_REGISTRY).
This schema is a flavor of CustomOpenAISchema with a url keypreset by global Preference keyLOCAL_SERVER. See?PREFERENCESfor more details on how to change it. It assumes that the server follows OpenAI API conventions (eg,POST /v1/chat/completions`).
Note: Llama.cpp (and hence Llama.jl built on top of it) do NOT support embeddings endpoint! You'll get an address error.
Example
Assumes that we have a local server running at http://127.0.0.1:10897/v1 (port and address used by Llama.jl, "v1" at the end is needed for OpenAI endpoint compatibility):
Three ways to call it:
\n# Use @ai_str with "local" alias\nai"Say hi!"local\n\n# model="local"\naigenerate("Say hi!"; model="local")\n\n# Or set schema explicitly\nconst PT = PromptingTools\nmsg = aigenerate(PT.LocalServerOpenAISchema(), "Say hi!")How to start a LLM local server? You can use run_server function from Llama.jl. Use a separate Julia session.
using Llama\nmodel = "...path..." # see Llama.jl README how to download one\nrun_server(; model)To change the default port and address:
# For a permanent change, set the preference:\nusing Preferences\nset_preferences!("LOCAL_SERVER"=>"http://127.0.0.1:10897/v1")\n\n# Or if it's a temporary fix, just change the variable `LOCAL_SERVER`:\nconst PT = PromptingTools\nPT.LOCAL_SERVER = "http://127.0.0.1:10897/v1"Extract a result from the provided data, if any, otherwise set the error and message fields.
Arguments
error::Bool:trueif a result is found,falseotherwise.message::String: Only present if no result is found, should be short and concise.
MistralOpenAISchemaMistralOpenAISchema() allows user to call MistralAI API known for mistral and mixtral models.
It's a flavor of CustomOpenAISchema() with a url preset to https://api.mistral.ai.
Most models have been registered, so you don't even have to specify the schema
Example
Let's call mistral-tiny model:
api_key = "..." # can be set via ENV["MISTRAL_API_KEY"] or via our preference system\nmsg = aigenerate("Say hi!"; model="mistral_tiny", api_key)See ?PREFERENCES for more details on how to set your API key permanently.
ModelSpecA struct that contains information about a model, such as its name, schema, cost per token, etc.
Fields
name::String: The name of the model. This is the name that will be used to refer to the model in theai*functions.schema::AbstractPromptSchema: The schema of the model. This is the schema that will be used to generate prompts for the model, eg,:OpenAISchema.cost_of_token_prompt::Float64: The cost of 1 token in the prompt for this model. This is used to calculate the cost of a prompt. Note: It is often provided online as cost per 1000 tokens, so make sure to convert it correctly!cost_of_token_generation::Float64: The cost of 1 token generated by this model. This is used to calculate the cost of a generation. Note: It is often provided online as cost per 1000 tokens, so make sure to convert it correctly!description::String: A description of the model. This is used to provide more information about the model when it is queried.
Example
spec = ModelSpec("gpt-3.5-turbo",\n OpenAISchema(),\n 0.0015,\n 0.002,\n "GPT-3.5 Turbo is a 175B parameter model and a common default on the OpenAI API.")\n\n# register it\nPromptingTools.register_model!(spec)But you can also register any model directly via keyword arguments:
PromptingTools.register_model!(\n name = "gpt-3.5-turbo",\n schema = OpenAISchema(),\n cost_of_token_prompt = 0.0015,\n cost_of_token_generation = 0.002,\n description = "GPT-3.5 Turbo is a 175B parameter model and a common default on the OpenAI API.")Schema that keeps messages (<:AbstractMessage) and does not transform for any specific model. It used by the first pass of the prompt rendering system (see ?render).
Ollama by default manages different models and their associated prompt schemas when you pass system_prompt and prompt fields to the API.
Warning: It works only for 1 system message and 1 user message, so anything more than that has to be rejected.
If you need to pass more messagese / longer conversational history, you can use define the model-specific schema directly and pass your Ollama requests with raw=true, which disables and templating and schema management by Ollama.
OllamaSchema is the default schema for Olama models.
It uses the following conversation template:
[Dict(role="system",content="..."),Dict(role="user",content="..."),Dict(role="assistant",content="...")]It's very similar to OpenAISchema, but it appends images differently.
OpenAISchema is the default schema for OpenAI models.
It uses the following conversation template:
[Dict(role="system",content="..."),Dict(role="user",content="..."),Dict(role="assistant",content="...")]It's recommended to separate sections in your prompt with markdown headers (e.g. `##Answer
`).
OpenRouterOpenAISchemaSchema to call the OpenRouter API.
Links:
Requires one environment variable to be set:
OPENROUTER_API_KEY: Your API key
SambaNovaOpenAISchemaSchema to call the SambaNova API.
Links:
Requires one environment variable to be set:
SAMBANOVA_API_KEY: Your API key
SaverSchema <: AbstractTracerSchemaSaverSchema is a schema that automatically saves the conversation to the disk. It's useful for debugging and for persistent logging.
It can be composed with any other schema, eg, TracerSchema to save additional metadata.
Set environment variable LOG_DIR to the directory where you want to save the conversation (see ?PREFERENCES). Conversations are named by the hash of the first message in the conversation to naturally group subsequent conversations together.
If you need to provide logging directory of the file name dynamically, you can provide the following arguments to tracer_kwargs:
log_dir- used as the directory to save the log into when provided. Defaults toLOG_DIRif not provided.log_file_path- used as the file name to save the log into when provided. This value overrules thelog_dirandLOG_DIRif provided.
To use it automatically, re-register the models you use with the schema wrapped in SaverSchema
See also: meta, unwrap, TracerSchema, initialize_tracer, finalize_tracer
Example
using PromptingTools: TracerSchema, OpenAISchema, SaverSchema\n# This schema will first trace the metadata (change to TraceMessage) and then save the conversation to the disk\n\nwrap_schema = OpenAISchema() |> TracerSchema |> SaverSchema\nconv = aigenerate(wrap_schema,:BlankSystemUser; system="You're a French-speaking assistant!",\n user="Say hi!", model="gpt-4", api_kwargs=(;temperature=0.1), return_all=true)\n\n# conv is a vector of messages that will be saved to a JSON together with metadata about the template and api_kwargsIf you wanted to enable this automatically for models you use, you can do it like this:
PT.register_model!(; name= "gpt-3.5-turbo", schema=OpenAISchema() |> TracerSchema |> SaverSchema)Any subsequent calls model="gpt-3.5-turbo" will automatically capture metadata and save the conversation to the disk.
To provide logging file path explicitly, use the tracer_kwargs:
conv = aigenerate(wrap_schema,:BlankSystemUser; system="You're a French-speaking assistant!",\n user="Say hi!", model="gpt-4", api_kwargs=(;temperature=0.1), return_all=true,\n tracer_kwargs=(; log_file_path="my_logs/my_log.json"))ShareGPTSchema <: AbstractShareGPTSchemaFrequently used schema for finetuning LLMs. Conversations are recorded as a vector of dicts with keys from and value (similar to OpenAI).
Echoes the user's input back to them. Used for testing the implementation
Echoes the user's input back to them. Used for testing the implementation
Echoes the user's input back to them. Used for testing the implementation
Echoes the user's input back to them. Used for testing the implementation
Echoes the user's input back to them. Used for testing the implementation
TogetherOpenAISchemaSchema to call the Together.ai API.
Links:
Requires one environment variables to be set:
TOGETHER_API_KEY: Your API key
ToolA tool that can be sent to an LLM for execution ("function calling").
Arguments
name::String: The name of the tool.parameters::Dict: The parameters of the tool.description::Union{String, Nothing}: The description of the tool.strict::Union{Bool, Nothing}: Whether to enforce strict mode for the tool.callable::Any: The callable object of the tool, eg, a type or a function.
See also: AbstractTool, tool_call_signature
Tool(callable::Union{Function, Type, Method}; kwargs...)Create a Tool from a callable object (function, type, or method).
Arguments
callable::Union{Function, Type, Method}: The callable object to convert to a tool.
Returns
Tool: A tool object that can be used for function calling.
Examples
# Create a tool from a function\ntool = Tool(my_function)\n\n# Create a tool from a type\ntool = Tool(MyStruct)Error type for when a tool execution fails. It should contain the error message from the tool execution.
Error type for when a tool execution fails with a generic error. It should contain the detailed error message.
ToolMessageA message type for tool calls.
It represents both the request (fields args, name) and the response (field content).
Fields
content::Any: The content of the message.req_id::Union{Nothing, Int}: The unique ID of the request.tool_call_id::String: The unique ID of the tool call.raw::AbstractString: The raw JSON string of the tool call request.args::Union{Nothing, Dict{Symbol, Any}}: The arguments of the tool call request.name::Union{Nothing, String}: The name of the tool call request.
Error type for when a tool is not found. It should contain the tool name that was not found.
ToolRef(ref::Symbol, callable::Any)Represents a reference to a tool with a symbolic name and a callable object (to call during tool execution). It can be rendered with a render method and a prompt schema.
Arguments
ref::Symbol: The symbolic name of the tool.callable::Any: The callable object of the tool, eg, a type or a function.extras::Dict{String, Any}: Additional parameters to be included in the tool signature.
Examples
# Define a tool with a symbolic name and a callable object\ntool = ToolRef(;ref=:computer, callable=println)\n\n# Show the rendered tool signature\nPT.render(PT.AnthropicSchema(), tool)TracerMessage{T <: Union{AbstractChatMessage, AbstractDataMessage}} <: AbstractTracerMessageA mutable wrapper message designed for tracing the flow of messages through the system, allowing for iterative updates and providing additional metadata for observability.
Fields
object::T: The original message being traced, which can be either a chat or data message.from::Union{Nothing, Symbol}: The identifier of the sender of the message.to::Union{Nothing, Symbol}: The identifier of the intended recipient of the message.viewers::Vector{Symbol}: A list of identifiers for entities that have access to view the message, in addition to the sender and recipient.time_received::DateTime: The timestamp when the message was received by the tracing system.time_sent::Union{Nothing, DateTime}: The timestamp when the message was originally sent, if available.model::String: The name of the model that generated the message. Defaults to empty.parent_id::Symbol: An identifier for the job or process that the message is associated with. Higher-level tracing ID.thread_id::Symbol: An identifier for the thread (series of messages for one model/agent) or execution context within the job where the message originated. It should be the same for messages in the same thread.meta::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the message itself. Try to limit to a small number of items and singletons to be serializable._type::Symbol: A fixed symbol identifying the type of the message as:eventmessage, used for type discrimination.
This structure is particularly useful for debugging, monitoring, and auditing the flow of messages in systems that involve complex interactions or asynchronous processing.
All fields are optional besides the object.
Useful methods: pprint (pretty prints the underlying message), unwrap (to get the object out of tracer), align_tracer! (to set all shared IDs in a vector of tracers to the same), istracermessage to check if given message is an AbstractTracerMessage
Example
wrap_schema = PT.TracerSchema(PT.OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model = "gpt4t")\nmsg # isa TracerMessage\nmsg.content # access content like if it was the messageTracerMessageLike{T <: Any} <: AbstractTracerA mutable structure designed for general-purpose tracing within the system, capable of handling any type of object that is part of the AI Conversation. It provides a flexible way to track and annotate objects as they move through different parts of the system, facilitating debugging, monitoring, and auditing.
Fields
object::T: The original object being traced.from::Union{Nothing, Symbol}: The identifier of the sender or origin of the object.to::Union{Nothing, Symbol}: The identifier of the intended recipient or destination of the object.viewers::Vector{Symbol}: A list of identifiers for entities that have access to view the object, in addition to the sender and recipient.time_received::DateTime: The timestamp when the object was received by the tracing system.time_sent::Union{Nothing, DateTime}: The timestamp when the object was originally sent, if available.model::String: The name of the model or process that generated or is associated with the object. Defaults to empty.parent_id::Symbol: An identifier for the job or process that the object is associated with. Higher-level tracing ID.thread_id::Symbol: An identifier for the thread or execution context (sub-task, sub-process) within the job where the object originated. It should be the same for objects in the same thread.run_id::Union{Nothing, Int}: A unique identifier for the run or instance of the process (ie, a single call to the LLM) that generated the object. Defaults to a random integer.meta::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the object itself. Try to limit to a small number of items and singletons to be serializable._type::Symbol: A fixed symbol identifying the type of the tracer as:tracermessage, used for type discrimination.
This structure is particularly useful for systems that involve complex interactions or asynchronous processing, where tracking the flow and transformation of objects is crucial.
All fields are optional besides the object.
TracerSchema <: AbstractTracerSchemaA schema designed to wrap another schema, enabling pre- and post-execution callbacks for tracing and additional functionalities. This type is specifically utilized within the TracerMessage type to trace the execution flow, facilitating observability and debugging in complex conversational AI systems.
The TracerSchema acts as a middleware, allowing developers to insert custom logic before and after the execution of the primary schema's functionality. This can include logging, performance measurement, or any other form of tracing required to understand or improve the execution flow.
TracerSchema automatically wraps messages in TracerMessage type, which has several important fields, eg,
object: the original message - unwrap with utilityunwrapmeta: a dictionary with metadata about the tracing process (eg, prompt templates, LLM API kwargs) - extract with utilitymetaparent_id: an identifier for the overall job / high-level conversation with the user where the current conversationthreadoriginated. It should be the same for objects in the same thread.thread_id: an identifier for the current thread or execution context (sub-task, sub-process, CURRENT CONVERSATION or vector of messages) within the broader parent task. It should be the same for objects in the same thread.
See also: meta, unwrap, SaverSchema, initialize_tracer, finalize_tracer
Example
wrap_schema = TracerSchema(OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model="gpt-4")\n# output type should be TracerMessage\nmsg isa TracerMessageYou can define your own tracer schema and the corresponding methods: initialize_tracer, finalize_tracer. See src/llm_tracer.jl
UserMessageA message type for user-generated text-based responses. Consumed by ai* functions to generate responses.
Fields
content::T: The content of the message.variables::Vector{Symbol}: The variables in the message.name::Union{Nothing, String}: The name of therolein the conversation.
UserMessageWithImagesA message type for user-generated text-based responses with images. Consumed by ai* functions to generate responses.
Fields
content::T: The content of the message.image_url::Vector{String}: The URLs of the images.variables::Vector{Symbol}: The variables in the message.name::Union{Nothing, String}: The name of therolein the conversation.
Construct UserMessageWithImages with 1 or more images. Images can be either URLs or local paths.
XAIOpenAISchemaSchema to call the XAI API. It follows OpenAI API conventions.
Get your API key from here.
Requires one environment variable to be set:
XAI_API_KEY: Your API key
append!(mem::ConversationMemory, msgs::Vector{<:AbstractMessage})Smart append that handles duplicate messages based on run IDs. Only appends messages that are newer than the latest matching message in memory.
length(mem::ConversationMemory)Return the number of messages. All of them.
push!(mem::ConversationMemory, msg::AbstractMessage)Add a single message to the conversation memory.
show(io::IO, mem::ConversationMemory)Display the number of non-system/non-annotation messages in the conversation memory.
OpenAI.create_chat(schema::CustomOpenAISchema,\n api_key::AbstractString,\n model::AbstractString,\n conversation;\n http_kwargs::NamedTuple = NamedTuple(),\n streamcallback::Any = nothing,\n url::String = "http://localhost:8080",\n kwargs...)Dispatch to the OpenAI.create_chat function, for any OpenAI-compatible API.
It expects url keyword argument. Provide it to the aigenerate function via api_kwargs=(; url="my-url")
It will forward your query to the "chat/completions" endpoint of the base URL that you provided (=url).
OpenAI.create_chat(schema::LocalServerOpenAISchema,\n api_key::AbstractString,\n model::AbstractString,\n conversation;\n url::String = "http://localhost:8080",\n kwargs...)Dispatch to the OpenAI.create_chat function, but with the LocalServer API parameters, ie, defaults to url specified by the LOCAL_SERVERpreference. See?PREFERENCES
OpenAI.create_chat(schema::MistralOpenAISchema,api_key::AbstractString, model::AbstractString, conversation; url::String="https://api.mistral.ai/v1", kwargs...)
Dispatch to the OpenAI.create_chat function, but with the MistralAI API parameters.
It tries to access the MISTRAL_API_KEY ENV variable, but you can also provide it via the api_key keyword argument.
aiclassify(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiclassify call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiclassify(with thetracer_schema.schema)calls
finalize_tracer
', 111)), + createBaseVNode("div", _hoisted_2, [ + _cache[10] || (_cache[10] = createStaticVNode('# PromptingTools.aiclassify — Method.
aiclassify(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n choices::AbstractVector{T} = ["true", "false", "unknown"],\n model::AbstractString = MODEL_CHAT,\n api_kwargs::NamedTuple = NamedTuple(),\n token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing,\n kwargs...) where {T <: Union{AbstractString, Tuple{<:AbstractString, <:AbstractString}}}Classifies the given prompt/statement into an arbitrary list of choices, which must be only the choices (vector of strings) or choices and descriptions are provided (vector of tuples, ie, ("choice","description")).
It's quick and easy option for "routing" and similar use cases, as it exploits the logit bias trick and outputs only 1 token. classify into an arbitrary list of categories (including with descriptions). It's quick and easy option for "routing" and similar use cases, as it exploits the logit bias trick, so it outputs only 1 token.
', 9)), + createBaseVNode("p", null, [ + _cache[6] || (_cache[6] = createTextVNode("!!! Note: The prompt/AITemplate must have a placeholder ")), + _cache[7] || (_cache[7] = createBaseVNode("code", null, "choices", -1)), + _cache[8] || (_cache[8] = createTextVNode(" (ie, ")), + createBaseVNode("code", null, toDisplayString(_ctx.choices), 1), + _cache[9] || (_cache[9] = createTextVNode(") that will be replaced with the encoded choices")) + ]), + _cache[11] || (_cache[11] = createStaticVNode('Choices are rewritten into an enumerated list and mapped to a few known OpenAI tokens (maximum of 40 choices supported). Mapping of token IDs for GPT3.5/4 are saved in variable OPENAI_TOKEN_IDS.
It uses Logit bias trick and limits the output to 1 token to force the model to output only true/false/unknown. Credit for the idea goes to AAAzzam.
Arguments
prompt_schema::AbstractOpenAISchema: The schema for the prompt.prompt: The prompt/statement to classify if it's aString. If it's aSymbol, it is expanded as a template viarender(schema,template). Eg, templates:JudgeIsItTrueor:InputClassifierchoices::AbstractVector{T}: The choices to be classified into. It can be a vector of strings or a vector of tuples, where the first element is the choice and the second is the description.model::AbstractString = MODEL_CHAT: The model to use for classification. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.api_kwargs::NamedTuple = NamedTuple(): Additional keyword arguments for the API call.token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing: A dictionary mapping custom token IDs to their corresponding integer values. Ifnothing, it will use the default token IDs for the given model.kwargs: Additional keyword arguments for the prompt template.
Example
Given a user input, pick one of the two provided categories:
choices = ["animal", "plant"]\ninput = "Palm tree"\naiclassify(:InputClassifier; choices, input)Choices with descriptions provided as tuples:
choices = [("A", "any animal or creature"), ("P", "any plant or tree"), ("O", "anything else")]\n\n# try the below inputs:\ninput = "spider" # -> returns "A" for any animal or creature\ninput = "daphodil" # -> returns "P" for any plant or tree\ninput = "castle" # -> returns "O" for everything else\naiclassify(:InputClassifier; choices, input)You could also use this function for routing questions to different endpoints (notice the different template and placeholder used), eg,
choices = [("A", "any question about animal or creature"), ("P", "any question about plant or tree"), ("O", "anything else")]\nquestion = "how many spiders are there?"\nmsg = aiclassify(:QuestionRouter; choices, question)\n# "A"You can still use a simple true/false classification:
aiclassify("Is two plus two four?") # true\naiclassify("Is two plus three a vegetable on Mars?") # falseaiclassify returns only true/false/unknown. It's easy to get the proper Bool output type out with tryparse, eg,
tryparse(Bool, aiclassify("Is two plus two four?")) isa Bool # trueOutput of type Nothing marks that the model couldn't classify the statement as true/false.
Ideally, we would like to re-use some helpful system prompt to get more accurate responses. For this reason we have templates, eg, :JudgeIsItTrue. By specifying the template, we can provide our statement as the expected variable (it in this case) See that the model now correctly classifies the statement as "unknown".
aiclassify(:JudgeIsItTrue; it = "Is two plus three a vegetable on Mars?") # unknownFor better results, use higher quality models like gpt4, eg,
aiclassify(:JudgeIsItTrue;\n it = "If I had two apples and I got three more, I have five apples now.",\n model = "gpt4") # trueaiembed(tracer_schema::AbstractTracerSchema,\n doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}}, postprocess::Function = identity;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiembed call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiembed(with thetracer_schema.schema)calls
finalize_tracer
aiembed(prompt_schema::AbstractOllamaManagedSchema,\n doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}},\n postprocess::F = identity;\n verbose::Bool = true,\n api_key::String = "",\n model::String = MODEL_EMBEDDING,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120),\n api_kwargs::NamedTuple = NamedTuple(),\n kwargs...) where {F <: Function}The aiembed function generates embeddings for the given input using a specified model and returns a message object containing the embeddings, status, token count, and elapsed time.
Arguments
prompt_schema::AbstractOllamaManagedSchema: The schema for the prompt.doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}}: The document or list of documents to generate embeddings for. The list of documents is processed sequentially, so users should consider implementing an async version with withThreads.@spawnpostprocess::F: The post-processing function to apply to each embedding. Defaults to the identity function, but could beLinearAlgebra.normalize.verbose::Bool: A flag indicating whether to print verbose information. Defaults totrue.api_key::String: The API key to use for the OpenAI API. Defaults to"".model::String: The model to use for generating embeddings. Defaults toMODEL_EMBEDDING.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.api_kwargs::NamedTuple: Additional keyword arguments for the Ollama API. Defaults to an emptyNamedTuple.kwargs: Prompt variables to be used to fill the prompt/template
Returns
msg: ADataMessageobject containing the embeddings, status, token count, and elapsed time.
Note: Ollama API currently does not return the token count, so it's set to (0,0)
Example
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\n\nmsg = aiembed(schema, "Hello World"; model="openhermes2.5-mistral")\nmsg.content # 4096-element JSON3.Array{Float64...We can embed multiple strings at once and they will be hcat into a matrix (ie, each column corresponds to one string)
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\n\nmsg = aiembed(schema, ["Hello World", "How are you?"]; model="openhermes2.5-mistral")\nmsg.content # 4096×2 Matrix{Float64}:If you plan to calculate the cosine distance between embeddings, you can normalize them first:
const PT = PromptingTools\nusing LinearAlgebra\nschema = PT.OllamaManagedSchema()\n\nmsg = aiembed(schema, ["embed me", "and me too"], LinearAlgebra.normalize; model="openhermes2.5-mistral")\n\n# calculate cosine distance between the two normalized embeddings as a simple dot product\nmsg.content' * msg.content[:, 1] # [1.0, 0.34]Similarly, you can use the postprocess argument to materialize the data from JSON3.Object by using postprocess = copy
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\n\nmsg = aiembed(schema, "Hello World", copy; model="openhermes2.5-mistral")\nmsg.content # 4096-element Vector{Float64}aiembed(prompt_schema::AbstractOpenAISchema,\n doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}},\n postprocess::F = identity;\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_EMBEDDING, \n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120),\n api_kwargs::NamedTuple = NamedTuple(),\n kwargs...) where {F <: Function}The aiembed function generates embeddings for the given input using a specified model and returns a message object containing the embeddings, status, token count, and elapsed time.
Arguments
prompt_schema::AbstractOpenAISchema: The schema for the prompt.doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}}: The document or list of documents to generate embeddings for.postprocess::F: The post-processing function to apply to each embedding. Defaults to the identity function.verbose::Bool: A flag indicating whether to print verbose information. Defaults totrue.api_key::String: The API key to use for the OpenAI API. Defaults toOPENAI_API_KEY.model::String: The model to use for generating embeddings. Defaults toMODEL_EMBEDDING.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to(retry_non_idempotent = true, retries = 5, readtimeout = 120).api_kwargs::NamedTuple: Additional keyword arguments for the OpenAI API. Defaults to an emptyNamedTuple.kwargs...: Additional keyword arguments.
Returns
msg: ADataMessageobject containing the embeddings, status, token count, and elapsed time. Usemsg.contentto access the embeddings.
Example
msg = aiembed("Hello World")\nmsg.content # 1536-element JSON3.Array{Float64...We can embed multiple strings at once and they will be hcat into a matrix (ie, each column corresponds to one string)
msg = aiembed(["Hello World", "How are you?"])\nmsg.content # 1536×2 Matrix{Float64}:If you plan to calculate the cosine distance between embeddings, you can normalize them first:
using LinearAlgebra\nmsg = aiembed(["embed me", "and me too"], LinearAlgebra.normalize)\n\n# calculate cosine distance between the two normalized embeddings as a simple dot product\nmsg.content' * msg.content[:, 1] # [1.0, 0.787]aiextract(prompt_schema::AbstractAnthropicSchema, prompt::ALLOWED_PROMPT_TYPE;\n return_type::Union{Type, AbstractTool, Vector},\n verbose::Bool = true,\n api_key::String = ANTHROPIC_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = NamedTuple(),\n cache::Union{Nothing, Symbol} = nothing,\n betas::Union{Nothing, Vector{Symbol}} = nothing,\n kwargs...)Extract required information (defined by a struct return_type) from the provided prompt by leveraging Anthropic's function calling mode.
This is a perfect solution for extracting structured information from text (eg, extract organization names in news articles, etc.).
Read best practics here.
It's effectively a light wrapper around aigenerate call, which requires additional keyword argument return_type to be provided and will enforce the model outputs to adhere to it.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplatereturn_type: A struct TYPE representing the the information we want to extract. Do not provide a struct instance, only the type. If the struct has a docstring, it will be provided to the model as well. It's used to enforce structured model outputs or provide more information. Alternatively, you can provide a vector of field names and their types (see?generate_structfunction for the syntax).verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message::Bool = false: Iftrue, skips the system message in the conversation history.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.:tool_choice: A string indicating which tool to use. Supported values arenothing,"auto","any"and"exact".nothingwill use the default tool choice.
cache: A symbol indicating whether to use caching for the prompt. Supported values arenothing(no caching),:system,:tools,:lastand:all. Note that COST estimate will be wrong (ignores the caching).:system: Caches the system message:tools: Caches the tool definitions (and everything before them):last: Caches the last message in the conversation (and everything before it):all: Cache trigger points are inserted in all of the above places (ie, higher likelyhood of cache hit, but also slightly higher cost)
betas::Union{Nothing, Vector{Symbol}}: A vector of symbols representing the beta features to be used. See?anthropic_extra_headersfor details.kwargs: Prompt variables to be used to fill the prompt/template
Note: At the moment, the cache is only allowed for prompt segments over 1024 tokens (in some cases, over 2048 tokens). You'll get an error if you try to cache short prompts.
Returns
If return_all=false (default):
msg: AnDataMessageobject representing the extracted data, including the content, status, tokens, and elapsed time. Usemsg.contentto access the extracted data.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (DataMessage).
See also: tool_call_signature, MaybeExtract, ItemsExtract, aigenerate
Example
Do you want to extract some specific measurements from a text like age, weight and height? You need to define the information you need as a struct (return_type):
"Person's age, height, and weight."\nstruct MyMeasurement\n age::Int # required\n height::Union{Int,Nothing} # optional\n weight::Union{Nothing,Float64} # optional\nend\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall."; model="claudeh", return_type=MyMeasurement)\n# PromptingTools.DataMessage(MyMeasurement)\nmsg.content\n# MyMeasurement(30, 180, 80.0)The fields that allow Nothing are marked as optional in the schema:
msg = aiextract("James is 30."; model="claudeh", return_type=MyMeasurement)\n# MyMeasurement(30, nothing, nothing)If there are multiple items you want to extract, define a wrapper struct to get a Vector of MyMeasurement:
struct ManyMeasurements\n measurements::Vector{MyMeasurement}\nend\n\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; model="claudeh", return_type=ManyMeasurements)\n\nmsg.content.measurements\n# 2-element Vector{MyMeasurement}:\n# MyMeasurement(30, 180, 80.0)\n# MyMeasurement(19, 190, nothing)Or you can use the convenience wrapper ItemsExtract to extract multiple measurements (zero, one or more):
using PromptingTools: ItemsExtract\n\nreturn_type = ItemsExtract{MyMeasurement}\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; model="claudeh", return_type)\n\nmsg.content.items # see the extracted itemsOr if you want your extraction to fail gracefully when data isn't found, use MaybeExtract{T} wrapper (this trick is inspired by the Instructor package!):
using PromptingTools: MaybeExtract\n\nreturn_type = MaybeExtract{MyMeasurement}\n# Effectively the same as:\n# struct MaybeExtract{T}\n# result::Union{T, Nothing} // The result of the extraction\n# error::Bool // true if a result is found, false otherwise\n# message::Union{Nothing, String} // Only present if no result is found, should be short and concise\n# end\n\n# If LLM extraction fails, it will return a Dict with `error` and `message` fields instead of the result!\nmsg = aiextract("Extract measurements from the text: I am giraffe"; model="claudeo", return_type)\nmsg.content\n# Output: MaybeExtract{MyMeasurement}(nothing, true, "I'm sorry, but your input of "I am giraffe" does not contain any information about a person's age, height or weight measurements that I can extract. To use this tool, please provide a statement that includes at least the person's age, and optionally their height in inches and weight in pounds. Without that information, I am unable to extract the requested measurements.")That way, you can handle the error gracefully and get a reason why extraction failed (in msg.content.message).
However, this can fail with weaker models like claudeh, so we can apply some of our prompt templates with embedding reasoning step:
msg = aiextract(:ExtractDataCoTXML; data="I am giraffe", model="claudeh", return_type)\nmsg.content\n# Output: MaybeExtract{MyMeasurement}(nothing, true, "The provided data does not contain the expected information about a person's age, height, and weight.")Note that when using a prompt template, we provide data for the extraction as the corresponding placeholder (see aitemplates("extract") for documentation of this template).
Note that the error message refers to a giraffe not being a human, because in our MyMeasurement docstring, we said that it's for people!
Example of using a vector of field names with aiextract
fields = [:location, :temperature => Float64, :condition => String]\nmsg = aiextract("Extract the following information from the text: location, temperature, condition. Text: The weather in New York is sunny and 72.5 degrees Fahrenheit."; \nreturn_type = fields, model="claudeh")Or simply call aiextract("some text"; return_type = [:reasoning,:answer], model="claudeh") to get a Chain of Thought reasoning for extraction task.
It will be returned it a new generated type, which you can check with PromptingTools.isextracted(msg.content) == true to confirm the data has been extracted correctly.
This new syntax also allows you to provide field-level descriptions, which will be passed to the model.
fields_with_descriptions = [\n :location,\n :temperature => Float64,\n :temperature__description => "Temperature in degrees Fahrenheit",\n :condition => String,\n :condition__description => "Current weather condition (e.g., sunny, rainy, cloudy)"\n]\nmsg = aiextract("The weather in New York is sunny and 72.5 degrees Fahrenheit."; return_type = fields_with_descriptions, model="claudeh")aiextract(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n return_type::Union{Type, AbstractTool, Vector},\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = (;\n tool_choice = nothing),\n strict::Union{Nothing, Bool} = nothing,\n kwargs...)Extract required information (defined by a struct return_type) from the provided prompt by leveraging OpenAI function calling mode.
This is a perfect solution for extracting structured information from text (eg, extract organization names in news articles, etc.)
It's effectively a light wrapper around aigenerate call, which requires additional keyword argument return_type to be provided and will enforce the model outputs to adhere to it.
!!! Note: The types must be CONCRETE, it helps with correct conversion to JSON schema and then conversion back to the struct.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplatereturn_type: A struct TYPE (or a Tool, vector of Types) representing the the information we want to extract. Do not provide a struct instance, only the type. Alternatively, you can provide a vector of field names and their types (see?generate_structfunction for the syntax). If the struct has a docstring, it will be provided to the model as well. It's used to enforce structured model outputs or provide more information.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.tool_choice: Specifies which tool to use for the API call. Usually, one of "auto","any","exact" //nothingwill pick a default. Defaults to"exact"for 1 tool and"auto"for many tools, which is a made-up value to enforce the OpenAI requirements if we want one exact function. Providers like Mistral, Together, etc. use"any"instead.
strict::Union{Nothing, Bool} = nothing: A boolean indicating whether to enforce strict generation of the response (supported only for OpenAI models). It has additional latency for the first request. Ifnothing, standard function calling is used.json_mode::Union{Nothing, Bool} = nothing: Ifjson_mode = true, we use JSON mode for the response (supported only for OpenAI models). Ifnothing, standard function calling is used. JSON mode is understood to be more creative and smarter than function calling mode, as it's not mascarading as a function call, but there is extra latency for the first request to produce grammar for constrained sampling.kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnDataMessageobject representing the extracted data, including the content, status, tokens, and elapsed time. Usemsg.contentto access the extracted data.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (DataMessage).
Note: msg.content can be a single object (if a single tool is used) or a vector of objects (if multiple tools are used)!
See also: tool_call_signature, MaybeExtract, ItemsExtract, aigenerate, generate_struct
Example
Do you want to extract some specific measurements from a text like age, weight and height? You need to define the information you need as a struct (return_type):
"Person's age, height, and weight."\nstruct MyMeasurement\n age::Int # required\n height::Union{Int,Nothing} # optional\n weight::Union{Nothing,Float64} # optional\nend\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall."; return_type=MyMeasurement)\n# PromptingTools.DataMessage(MyMeasurement)\nmsg.content\n# MyMeasurement(30, 180, 80.0)The fields that allow Nothing are marked as optional in the schema:
msg = aiextract("James is 30."; return_type=MyMeasurement)\n# MyMeasurement(30, nothing, nothing)If there are multiple items you want to extract, define a wrapper struct to get a Vector of MyMeasurement:
struct ManyMeasurements\n measurements::Vector{MyMeasurement}\nend\n\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; return_type=ManyMeasurements)\n\nmsg.content.measurements\n# 2-element Vector{MyMeasurement}:\n# MyMeasurement(30, 180, 80.0)\n# MyMeasurement(19, 190, nothing)Or you can use the convenience wrapper ItemsExtract to extract multiple measurements (zero, one or more):
using PromptingTools: ItemsExtract\n\nreturn_type = ItemsExtract{MyMeasurement}\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; return_type)\n\nmsg.content.items # see the extracted itemsOr if you want your extraction to fail gracefully when data isn't found, use MaybeExtract{T} wrapper (this trick is inspired by the Instructor package!):
using PromptingTools: MaybeExtract\n\nreturn_type = MaybeExtract{MyMeasurement}\n# Effectively the same as:\n# struct MaybeExtract{T}\n# result::Union{T, Nothing} // The result of the extraction\n# error::Bool // true if a result is found, false otherwise\n# message::Union{Nothing, String} // Only present if no result is found, should be short and concise\n# end\n\n# If LLM extraction fails, it will return a Dict with `error` and `message` fields instead of the result!\nmsg = aiextract("Extract measurements from the text: I am giraffe"; return_type)\nmsg.content\n# MaybeExtract{MyMeasurement}(nothing, true, "I'm sorry, but I can only assist with human measurements.")That way, you can handle the error gracefully and get a reason why extraction failed (in msg.content.message).
Note that the error message refers to a giraffe not being a human, because in our MyMeasurement docstring, we said that it's for people!
Some non-OpenAI providers require a different specification of the "tool choice" than OpenAI. For example, to use Mistral models ("mistrall" for mistral large), do:
"Some fruit"\nstruct Fruit\n name::String\nend\naiextract("I ate an apple",return_type=Fruit,api_kwargs=(;tool_choice="any"),model="mistrall")\n# Notice two differences: 1) struct MUST have a docstring, 2) tool_choice is set explicitly set to "any"Example of using a vector of field names with aiextract
fields = [:location, :temperature => Float64, :condition => String]\nmsg = aiextract("Extract the following information from the text: location, temperature, condition. Text: The weather in New York is sunny and 72.5 degrees Fahrenheit."; return_type = fields)Or simply call aiextract("some text"; return_type = [:reasoning,:answer]) to get a Chain of Thought reasoning for extraction task.
It will be returned it a new generated type, which you can check with PromptingTools.isextracted(msg.content) == true to confirm the data has been extracted correctly.
This new syntax also allows you to provide field-level descriptions, which will be passed to the model.
fields_with_descriptions = [\n :location,\n :temperature => Float64,\n :temperature__description => "Temperature in degrees Fahrenheit",\n :condition => String,\n :condition__description => "Current weather condition (e.g., sunny, rainy, cloudy)"\n]\nmsg = aiextract("The weather in New York is sunny and 72.5 degrees Fahrenheit."; return_type = fields_with_descriptions)If you feel that the extraction is not smart/creative enough, you can use json_mode = true to enforce the JSON mode, which automatically enables the structured output mode (as opposed to function calling mode).
The JSON mode is useful for cases when you want to enforce a specific output format, such as JSON, and want the model to adhere to that format, but don't want to pretend it's a "function call". Expect a few second delay on the first call for a specific struct, as the provider has to produce the constrained grammer first.
msg = aiextract("Extract the following information from the text: location, temperature, condition. Text: The weather in New York is sunny and 72.5 degrees Fahrenheit."; \nreturn_type = fields_with_descriptions, json_mode = true)\n# PromptingTools.DataMessage(NamedTuple)\n\nmsg.content\n# (location = "New York", temperature = 72.5, condition = "sunny")It works equally well for structs provided as return types:
msg = aiextract("James is 30, weighs 80kg. He's 180cm tall."; return_type=MyMeasurement, json_mode=true)aiextract(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiextract call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiextract(with thetracer_schema.schema)calls
finalize_tracer
aigenerate(prompt_schema::AbstractAnthropicSchema, prompt::ALLOWED_PROMPT_TYPE; verbose::Bool = true,\n api_key::String = ANTHROPIC_API_KEY, model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n streamcallback::Any = nothing,\n no_system_message::Bool = false,\n aiprefill::Union{Nothing, AbstractString} = nothing,\n http_kwargs::NamedTuple = NamedTuple(), api_kwargs::NamedTuple = NamedTuple(),\n cache::Union{Nothing, Symbol} = nothing,\n betas::Union{Nothing, Vector{Symbol}} = nothing,\n kwargs...)Generate an AI response based on a given prompt using the Anthropic API.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchemanotAbstractAnthropicSchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: API key for the Antropic API. Defaults toANTHROPIC_API_KEY(loaded viaENV["ANTHROPIC_API_KEY"]).model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES, eg, "claudeh".return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation::AbstractVector{<:AbstractMessage}=[]: Not allowed for this schema. Provided only for compatibility.streamcallback::Any: A callback function to handle streaming responses. Can be simplystdoutorStreamCallbackobject. See?StreamCallbackfor details. Note: We configure theStreamCallback(and necessaryapi_kwargs) for you, unless you specify theflavor. See?configure_callback!for details.no_system_message::Bool=false: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.aiprefill::Union{Nothing, AbstractString}: A string to be used as a prefill for the AI response. This steer the AI response in a certain direction (and potentially save output tokens). It MUST NOT end with a trailing with space. Useful for JSON formatting.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.api_kwargs::NamedTuple: Additional keyword arguments for the Ollama API. Defaults to an emptyNamedTuple.max_tokens::Int: The maximum number of tokens to generate. Defaults to 2048, because it's a required parameter for the API.
cache: A symbol indicating whether to use caching for the prompt. Supported values arenothing(no caching),:system,:tools,:lastand:all. Note that COST estimate will be wrong (ignores the caching).:system: Caches the system message:tools: Caches the tool definitions (and everything before them):last: Caches the last message in the conversation (and everything before it):all: Cache trigger points are inserted in all of the above places (ie, higher likelyhood of cache hit, but also slightly higher cost)
betas::Union{Nothing, Vector{Symbol}}: A vector of symbols representing the beta features to be used. See?anthropic_extra_headersfor details.kwargs: Prompt variables to be used to fill the prompt/template
Note: At the moment, the cache is only allowed for prompt segments over 1024 tokens (in some cases, over 2048 tokens). You'll get an error if you try to cache short prompts.
Returns
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
See also: ai_str, aai_str
Example
Simple hello world to test the API:
const PT = PromptingTools\nschema = PT.AnthropicSchema() # We need to explicit if we want Anthropic, otherwise OpenAISchema is the default\n\nmsg = aigenerate(schema, "Say hi!"; model="claudeh") #claudeh is the model alias for Claude 3 Haiku, fast and cheap model\n[ Info: Tokens: 21 @ Cost: $0.0 in 0.6 seconds\nAIMessage("Hello!")msg is an AIMessage object. Access the generated string via content property:
typeof(msg) # AIMessage{SubString{String}}\npropertynames(msg) # (:content, :status, :tokens, :elapsed, :cost, :log_prob, :finish_reason, :run_id, :sample_id, :_type)\nmsg.content # "Hello!Note: We need to be explicit about the schema we want to use. If we don't, it will default to OpenAISchema (=PT.DEFAULT_SCHEMA) Alternatively, if you provide a known model name or alias (eg, claudeh for Claude 3 Haiku - see MODEL_REGISTRY), the schema will be inferred from the model name.
We will use Claude 3 Haiku model for the following examples, so not need to specify the schema. See also "claudeo" and "claudes" for other Claude 3 models.
You can use string interpolation:
const PT = PromptingTools\n\na = 1\nmsg=aigenerate("What is `$a+$a`?"; model="claudeh")\nmsg.content # "The answer to `1+1` is `2`."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}. Claude models are good at completeling conversations that ended with an AIMessage (they just continue where it left off):
const PT = PromptingTools\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?"),\n PT.AIMessage("Hmm, strong the attachment is,")]\n\nmsg = aigenerate(conversation; model="claudeh")\nAIMessage("I sense. But unhealthy it may be. Your iPhone, a tool it is, not a living being. Feelings of affection, understandable they are, <continues>")Example of streaming:
# Simplest usage, just provide where to steam the text\nmsg = aigenerate("Count from 1 to 100."; streamcallback = stdout, model="claudeh")\n\nstreamcallback = PT.StreamCallback()\nmsg = aigenerate("Count from 1 to 100."; streamcallback, model="claudeh")\n# this allows you to inspect each chunk with `streamcallback.chunks`. You can them empty it with `empty!(streamcallback)` in between repeated calls.\n\n# Get verbose output with details of each chunk\nstreamcallback = PT.StreamCallback(; verbose=true, throw_on_error=true)\nmsg = aigenerate("Count from 1 to 10."; streamcallback, model="claudeh")Note: Streaming support is only for Anthropic models and it doesn't yet support tool calling and a few other features (logprobs, refusals, etc.)
You can also provide a prefill for the AI response to steer the response in a certain direction (eg, formatting, style):
msg = aigenerate("Sum up 1 to 100."; aiprefill = "I'd be happy to answer in one number without any additional text. The answer is:", model="claudeh")Note: It MUST NOT end with a trailing with space. You'll get an API error if you do.
aigenerate(prompt_schema::AbstractGoogleSchema, prompt::ALLOWED_PROMPT_TYPE;\n verbose::Bool = true,\n api_key::String = GOOGLE_API_KEY,\n model::String = "gemini-pro", return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generate an AI response based on a given prompt using the Google Gemini API. Get the API key here.
Note:
There is no "cost" reported as of February 2024, as all access seems to be free-of-charge. See the details here.
tokensin the returned AIMessage are actually characters, not tokens. We use a conservative estimate as they are not provided by the API yet.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES. Defaults toreturn_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message::Bool=false: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aiembed, aiclassify, aiextract, aiscan, aitemplates
Example
Simple hello world to test the API:
result = aigenerate("Say Hi!"; model="gemini-pro")\n# AIMessage("Hi there! 👋 I'm here to help you with any questions or tasks you may have. Just let me know what you need, and I'll do my best to assist you.")result is an AIMessage object. Access the generated string via content property:
typeof(result) # AIMessage{SubString{String}}\npropertynames(result) # (:content, :status, :tokens, :elapsed\nresult.content # "Hi there! ...___ You can use string interpolation and alias "gemini":
a = 1\nmsg=aigenerate("What is `$a+$a`?"; model="gemini")\nmsg.content # "1+1 is 2."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}:
const PT = PromptingTools\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\nmsg=aigenerate(conversation; model="gemini")\n# AIMessage("Young Padawan, you have stumbled into a dangerous path.... <continues>")aigenerate(prompt_schema::AbstractOllamaManagedSchema, prompt::ALLOWED_PROMPT_TYPE; verbose::Bool = true,\n api_key::String = "", model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n streamcallback::Any = nothing,\n http_kwargs::NamedTuple = NamedTuple(), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generate an AI response based on a given prompt using the OpenAI API.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchemanotAbstractManagedSchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: Provided for interface consistency. Not needed for locally hosted Ollama.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation::AbstractVector{<:AbstractMessage}=[]: Not allowed for this schema. Provided only for compatibility.streamcallback::Any: Just for compatibility. Not supported for this schema.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.api_kwargs::NamedTuple: Additional keyword arguments for the Ollama API. Defaults to an emptyNamedTuple.kwargs: Prompt variables to be used to fill the prompt/template
Returns
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
See also: ai_str, aai_str, aiembed
Example
Simple hello world to test the API:
const PT = PromptingTools\nschema = PT.OllamaManagedSchema() # We need to explicit if we want Ollama, OpenAISchema is the default\n\nmsg = aigenerate(schema, "Say hi!"; model="openhermes2.5-mistral")\n# [ Info: Tokens: 69 in 0.9 seconds\n# AIMessage("Hello! How can I assist you today?")msg is an AIMessage object. Access the generated string via content property:
typeof(msg) # AIMessage{SubString{String}}\npropertynames(msg) # (:content, :status, :tokens, :elapsed\nmsg.content # "Hello! How can I assist you today?"Note: We need to be explicit about the schema we want to use. If we don't, it will default to OpenAISchema (=PT.DEFAULT_SCHEMA) ___ You can use string interpolation:
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\na = 1\nmsg=aigenerate(schema, "What is `$a+$a`?"; model="openhermes2.5-mistral")\nmsg.content # "The result of `1+1` is `2`."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}:
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\n\nmsg = aigenerate(schema, conversation; model="openhermes2.5-mistral")\n# [ Info: Tokens: 111 in 2.1 seconds\n# AIMessage("Strong the attachment is, it leads to suffering it may. Focus on the force within you must, ...<continues>")Note: Managed Ollama currently supports at most 1 User Message and 1 System Message given the API limitations. If you want more, you need to use the ChatMLSchema.
aigenerate(prompt_schema::AbstractOllamaManagedSchema, prompt::ALLOWED_PROMPT_TYPE; verbose::Bool = true,\n api_key::String = "", model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n streamcallback::Any = nothing,\n http_kwargs::NamedTuple = NamedTuple(), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generate an AI response based on a given prompt using the OpenAI API.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchemanotAbstractManagedSchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: Provided for interface consistency. Not needed for locally hosted Ollama.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation::AbstractVector{<:AbstractMessage}=[]: Not allowed for this schema. Provided only for compatibility.streamcallback: A callback function to handle streaming responses. Can be simplystdoutor aStreamCallbackobject. See?StreamCallbackfor details.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.api_kwargs::NamedTuple: Additional keyword arguments for the Ollama API. Defaults to an emptyNamedTuple.kwargs: Prompt variables to be used to fill the prompt/template
Returns
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
See also: ai_str, aai_str, aiembed
Example
Simple hello world to test the API:
const PT = PromptingTools\nschema = PT.OllamaSchema() # We need to explicit if we want Ollama, OpenAISchema is the default\n\nmsg = aigenerate(schema, "Say hi!"; model="openhermes2.5-mistral")\n# [ Info: Tokens: 69 in 0.9 seconds\n# AIMessage("Hello! How can I assist you today?")msg is an AIMessage object. Access the generated string via content property:
typeof(msg) # AIMessage{SubString{String}}\npropertynames(msg) # (:content, :status, :tokens, :elapsed\nmsg.content # "Hello! How can I assist you today?"Note: We need to be explicit about the schema we want to use. If we don't, it will default to OpenAISchema (=PT.DEFAULT_SCHEMA) ___ You can use string interpolation:
const PT = PromptingTools\nschema = PT.OllamaSchema()\na = 1\nmsg=aigenerate(schema, "What is `$a+$a`?"; model="openhermes2.5-mistral")\nmsg.content # "The result of `1+1` is `2`."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}:
const PT = PromptingTools\nschema = PT.OllamaSchema()\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\n\nmsg = aigenerate(schema, conversation; model="openhermes2.5-mistral")\n# [ Info: Tokens: 111 in 2.1 seconds\n# AIMessage("Strong the attachment is, it leads to suffering it may. Focus on the force within you must, ...<continues>")To add streaming, use the streamcallback argument.
msg = aigenerate("Count from 1 to 10."; streamcallback = stdout)Or if you prefer to have more control, use a StreamCallback object.
streamcallback = PT.StreamCallback()\nmsg = aigenerate("Count from 1 to 10."; streamcallback)WARNING: If you provide a StreamCallback object with a flavor, we assume you want to configure everything yourself, so you need to make sure to set stream = true in the api_kwargs!
streamcallback = PT.StreamCallback(; flavor = PT.OllamaStream())\nmsg = aigenerate("Count from 1 to 10."; streamcallback, api_kwargs = (; stream = true))aigenerate(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT, return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n streamcallback::Any = nothing,\n no_system_message::Bool = false,\n name_user::Union{Nothing, String} = nothing,\n name_assistant::Union{Nothing, String} = nothing,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generate an AI response based on a given prompt using the OpenAI API.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.streamcallback: A callback function to handle streaming responses. Can be simplystdoutor aStreamCallbackobject. See?StreamCallbackfor details. Note: We configure theStreamCallback(and necessaryapi_kwargs) for you, unless you specify theflavor. See?configure_callback!for details.no_system_message::Bool=false: Iftrue, the default system message is not included in the conversation history. Any existing system message is converted to aUserMessage.name_user::Union{Nothing, String} = nothing: The name to use for the user in the conversation history. Defaults tonothing.name_assistant::Union{Nothing, String} = nothing: The name to use for the assistant in the conversation history. Defaults tonothing.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments. Useful parameters include:temperature: A float representing the temperature for sampling (ie, the amount of "creativity"). Often defaults to0.7.logprobs: A boolean indicating whether to return log probabilities for each token. Defaults tofalse.n: An integer representing the number of completions to generate at once (if supported).stop: A vector of strings representing the stop conditions for the conversation. Defaults to an empty vector.
kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aiembed, aiclassify, aiextract, aiscan, aitemplates
Example
Simple hello world to test the API:
result = aigenerate("Say Hi!")\n# [ Info: Tokens: 29 @ Cost: $0.0 in 1.0 seconds\n# AIMessage("Hello! How can I assist you today?")result is an AIMessage object. Access the generated string via content property:
typeof(result) # AIMessage{SubString{String}}\npropertynames(result) # (:content, :status, :tokens, :elapsed\nresult.content # "Hello! How can I assist you today?"___ You can use string interpolation:
a = 1\nmsg=aigenerate("What is `$a+$a`?")\nmsg.content # "The sum of `1+1` is `2`."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}:
const PT = PromptingTools\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\nmsg=aigenerate(conversation)\n# AIMessage("Ah, strong feelings you have for your iPhone. A Jedi's path, this is not... <continues>")Example of streaming:
# Simplest usage, just provide where to steam the text\nmsg = aigenerate("Count from 1 to 100."; streamcallback = stdout)\n\nstreamcallback = PT.StreamCallback()\nmsg = aigenerate("Count from 1 to 100."; streamcallback)\n# this allows you to inspect each chunk with `streamcallback.chunks`. You can them empty it with `empty!(streamcallback)` in between repeated calls.\n\n# Get verbose output with details of each chunk\nstreamcallback = PT.StreamCallback(; verbose=true, throw_on_error=true)\nmsg = aigenerate("Count from 1 to 10."; streamcallback)WARNING: If you provide a StreamCallback object, we assume you want to configure everything yourself, so you need to make sure to set stream = true in the api_kwargs!
Learn more in ?StreamCallback. Note: Streaming support is only for OpenAI models and it doesn't yet support tool calling and a few other features (logprobs, refusals, etc.)
aigenerate(schema::AbstractPromptSchema,\n mem::ConversationMemory; kwargs...)Generate a response using the conversation memory context.
aigenerate(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", return_all::Bool = false, kwargs...)Wraps the normal aigenerate call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aigenerate(with thetracer_schema.schema)calls
finalize_tracer
Example
wrap_schema = PT.TracerSchema(PT.OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model = "gpt4t")\nmsg isa TracerMessage # true\nmsg.content # access content like if it was the message\nPT.pprint(msg) # pretty-print the messageIt works on a vector of messages and converts only the non-tracer ones, eg,
wrap_schema = PT.TracerSchema(PT.OpenAISchema())\nconv = aigenerate(wrap_schema, "Say hi!"; model = "gpt4t", return_all = true)\nall(PT.istracermessage, conv) #trueaiimage(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n image_size::AbstractString = "1024x1024",\n image_quality::AbstractString = "standard",\n image_n::Integer = 1,\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_IMAGE_GENERATION,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generates an image from the provided prompt. If multiple "messages" are provided in prompt, it extracts the text ONLY from the last message!
Image (or the reference to it) will be returned in a DataMessage.content, the format will depend on the api_kwargs.response_format you set.
Can be used for generating images of varying quality and style with dall-e-* models. This function DOES NOT SUPPORT multi-turn conversations (ie, do not provide previous conversation via conversation argument).
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateimage_size: String-based resolution of the image, eg, "1024x1024". Only some resolutions are supported - see the API docs.image_quality: It can be either "standard" or "hd". Defaults to "standard".image_n: The number of images to generate. Currently, only single image generation is allowed (image_n = 1).verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_IMAGE_GENERATION.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. Currently, NOT ALLOWED.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments. Several important arguments are highlighted below:response_format: The format image should be returned in. Can be one of "url" or "b64_json". Defaults to "url" (the link will be inactived in 60 minutes).style: The style of generated images (DALL-E 3 only). Can be either "vidid" or "natural". Defauls to "vidid".
kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: ADataMessageobject representing one or more generated images, including the rewritten prompt if relevant, status, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aigenerate, aiembed, aiclassify, aiextract, aiscan, aitemplates
Notes
This function DOES NOT SUPPORT multi-turn conversations (ie, do not provide previous conversation via
conversationargument).There is no token tracking provided by the API, so the messages will NOT report any cost despite costing you money!
You MUST download any URL-based images within 60 minutes. The links will become inactive.
Example
Generate an image:
# You can experiment with `image_size`, `image_quality` kwargs!\nmsg = aiimage("A white cat on a car")\n\n# Download the image into a file\nusing Downloads\nDownloads.download(msg.content[:url], "cat_on_car.png")\n\n# You can also see the revised prompt that DALL-E 3 used\nmsg.content[:revised_prompt]\n# Output: "Visualize a pristine white cat gracefully perched atop a shiny car. \n# The cat's fur is stark white and its eyes bright with curiosity. \n# As for the car, it could be a contemporary sedan, glossy and in a vibrant color. \n# The scene could be set under the blue sky, enhancing the contrast between the white cat, the colorful car, and the bright blue sky."Note that you MUST download any URL-based images within 60 minutes. The links will become inactive.
If you wanted to download image directly into the DataMessage, provide response_format="b64_json" in api_kwargs:
msg = aiimage("A white cat on a car"; image_quality="hd", api_kwargs=(; response_format="b64_json"))\n\n# Then you need to use Base64 package to decode it and save it to a file:\nusing Base64\nwrite("cat_on_car_hd.png", base64decode(msg.content[:b64_json]));aiimage(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiimage call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiimage(with thetracer_schema.schema)calls
finalize_tracer
aiscan([prompt_schema::AbstractOllamaSchema,] prompt::ALLOWED_PROMPT_TYPE; \nimage_url::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\nimage_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\nattach_to_latest::Bool = true,\nverbose::Bool = true, api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n http_kwargs::NamedTuple = (;\n retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), \n api_kwargs::NamedTuple = = (; max_tokens = 2500),\n kwargs...)Scans the provided image (image_url or image_path) with the goal provided in the prompt.
Can be used for many multi-modal tasks, such as: OCR (transcribe text in the image), image captioning, image classification, etc.
It's effectively a light wrapper around aigenerate call, which uses additional keyword arguments image_url, image_path, image_detail to be provided. At least one image source (url or path) must be provided.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateimage_url: A string or vector of strings representing the URL(s) of the image(s) to scan.image_path: A string or vector of strings representing the path(s) of the image(s) to scan.image_detail: A string representing the level of detail to include for images. Can be"auto","high", or"low". See OpenAI Vision Guide for more details.attach_to_latest: A boolean how to handle if a conversation with multipleUserMessageis provided. Whentrue, the images are attached to the latestUserMessage.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aigenerate, aiembed, aiclassify, aiextract, aitemplates
Notes
All examples below use model "gpt4v", which is an alias for model ID "gpt-4-vision-preview"
max_tokensin theapi_kwargsis preset to 2500, otherwise OpenAI enforces a default of only a few hundred tokens (~300). If your output is truncated, increase this value
Example
Describe the provided image:
msg = aiscan("Describe the image"; image_path="julia.png", model="bakllava")\n# [ Info: Tokens: 1141 @ Cost: $0.0117 in 2.2 seconds\n# AIMessage("The image shows a logo consisting of the word "julia" written in lowercase")You can provide multiple images at once as a vector and ask for "low" level of detail (cheaper):
msg = aiscan("Describe the image"; image_path=["julia.png","python.png"] model="bakllava")You can use this function as a nice and quick OCR (transcribe text in the image) with a template :OCRTask. Let's transcribe some SQL code from a screenshot (no more re-typing!):
using Downloads\n# Screenshot of some SQL code -- we cannot use image_url directly, so we need to download it first\nimage_url = "https://www.sqlservercentral.com/wp-content/uploads/legacy/8755f69180b7ac7ee76a69ae68ec36872a116ad4/24622.png"\nimage_path = Downloads.download(image_url)\nmsg = aiscan(:OCRTask; image_path, model="bakllava", task="Transcribe the SQL code in the image.", api_kwargs=(; max_tokens=2500))\n\n# AIMessage("```sql\n# update Orders <continue>\n\n# You can add syntax highlighting of the outputs via Markdown\nusing Markdown\nmsg.content |> Markdown.parseLocal models cannot handle image URLs directly (image_url), so you need to download the image first and provide it as image_path:
using Downloads\nimage_path = Downloads.download(image_url)Notice that we set max_tokens = 2500. If your outputs seem truncated, it might be because the default maximum tokens on the server is set too low!
aiscan([prompt_schema::AbstractOpenAISchema,] prompt::ALLOWED_PROMPT_TYPE; \nimage_url::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\nimage_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\nimage_detail::AbstractString = "auto",\nattach_to_latest::Bool = true,\nverbose::Bool = true, api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n http_kwargs::NamedTuple = (;\n retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), \n api_kwargs::NamedTuple = = (; max_tokens = 2500),\n kwargs...)Scans the provided image (image_url or image_path) with the goal provided in the prompt.
Can be used for many multi-modal tasks, such as: OCR (transcribe text in the image), image captioning, image classification, etc.
It's effectively a light wrapper around aigenerate call, which uses additional keyword arguments image_url, image_path, image_detail to be provided. At least one image source (url or path) must be provided.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateimage_url: A string or vector of strings representing the URL(s) of the image(s) to scan.image_path: A string or vector of strings representing the path(s) of the image(s) to scan.image_detail: A string representing the level of detail to include for images. Can be"auto","high", or"low". See OpenAI Vision Guide for more details.attach_to_latest: A boolean how to handle if a conversation with multipleUserMessageis provided. Whentrue, the images are attached to the latestUserMessage.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aigenerate, aiembed, aiclassify, aiextract, aitemplates
Notes
All examples below use model "gpt4v", which is an alias for model ID "gpt-4-vision-preview"
max_tokensin theapi_kwargsis preset to 2500, otherwise OpenAI enforces a default of only a few hundred tokens (~300). If your output is truncated, increase this value
Example
Describe the provided image:
msg = aiscan("Describe the image"; image_path="julia.png", model="gpt4v")\n# [ Info: Tokens: 1141 @ Cost: $0.0117 in 2.2 seconds\n# AIMessage("The image shows a logo consisting of the word "julia" written in lowercase")You can provide multiple images at once as a vector and ask for "low" level of detail (cheaper):
msg = aiscan("Describe the image"; image_path=["julia.png","python.png"], image_detail="low", model="gpt4v")You can use this function as a nice and quick OCR (transcribe text in the image) with a template :OCRTask. Let's transcribe some SQL code from a screenshot (no more re-typing!):
# Screenshot of some SQL code\nimage_url = "https://www.sqlservercentral.com/wp-content/uploads/legacy/8755f69180b7ac7ee76a69ae68ec36872a116ad4/24622.png"\nmsg = aiscan(:OCRTask; image_url, model="gpt4v", task="Transcribe the SQL code in the image.", api_kwargs=(; max_tokens=2500))\n\n# [ Info: Tokens: 362 @ Cost: $0.0045 in 2.5 seconds\n# AIMessage("```sql\n# update Orders <continue>\n\n# You can add syntax highlighting of the outputs via Markdown\nusing Markdown\nmsg.content |> Markdown.parseNotice that we enforce max_tokens = 2500. That's because OpenAI seems to default to ~300 tokens, which provides incomplete outputs. Hence, we set this value to 2500 as a default. If you still get truncated outputs, increase this value.
aiscan(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiscan call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiscan(with thetracer_schema.schema)calls
finalize_tracer
aitemplatesFind easily the most suitable templates for your use case.
You can search by:
query::Symbolwhich looks look only for partial matches in the templatenamequery::AbstractStringwhich looks for partial matches in the templatenameordescriptionquery::Regexwhich looks for matches in the templatename,descriptionor any of the message previews
Keyword Arguments
limit::Intlimits the number of returned templates (Defaults to 10)
Examples
Find available templates with aitemplates:
tmps = aitemplates("JuliaExpertAsk")\n# Will surface one specific template\n# 1-element Vector{AITemplateMetadata}:\n# PromptingTools.AITemplateMetadata\n# name: Symbol JuliaExpertAsk\n# description: String "For asking questions about Julia language. Placeholders: `ask`"\n# version: String "1"\n# wordcount: Int64 237\n# variables: Array{Symbol}((1,))\n# system_preview: String "You are a world-class Julia language programmer with the knowledge of the latest syntax. Your commun"\n# user_preview: String "# Question\n\n{{ask}}"\n# source: String ""The above gives you a good idea of what the template is about, what placeholders are available, and how much it would cost to use it (=wordcount).
Search for all Julia-related templates:
tmps = aitemplates("Julia")\n# 2-element Vector{AITemplateMetadata}... -> more to come later!If you are on VSCode, you can leverage nice tabular display with vscodedisplay:
using DataFrames\ntmps = aitemplates("Julia") |> DataFrame |> vscodedisplayI have my selected template, how do I use it? Just use the "name" in aigenerate or aiclassify like you see in the first example!
Find the top-limit templates whose name or description fields partially match the query_key::String in TEMPLATE_METADATA.
Find the top-limit templates where provided query_key::Regex matches either of name, description or previews or User or System messages in TEMPLATE_METADATA.
Find the top-limit templates whose name::Symbol exactly matches the query_name::Symbol in TEMPLATE_METADATA.
aitools(prompt_schema::AbstractAnthropicSchema, prompt::ALLOWED_PROMPT_TYPE;\n kwargs...)\n tools::Union{Type, Function, Method, AbstractTool, Vector} = Tool[],\n verbose::Bool = true,\n api_key::String = ANTHROPIC_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n image_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\n cache::Union{Nothing, Symbol} = nothing,\n betas::Union{Nothing, Vector{Symbol}} = nothing,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = (;\n tool_choice = nothing),\n kwargs...)Calls chat completion API with an optional tool call signature. It can receive both tools and standard string-based content. Ideal for agentic workflows with more complex cognitive architectures.
Difference to aigenerate: Response can be a tool call (structured)
Differences to aiextract: Can provide infinitely many tools (including Functions!) and then respond with the tool call's output.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplatetools: A vector of tools to be used in the conversation. Can be a vector of types, instances ofAbstractTool, or a mix of both.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the Anthropic API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_CHAT.return_all: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history.no_system_message::Bool = false: Whether to exclude the system message from the conversation history.image_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing: A path to a local image file, or a vector of paths to local image files. Always attaches images to the latest user message.cache::Union{Nothing, Symbol} = nothing: Whether to cache the prompt. Defaults tonothing.betas::Union{Nothing, Vector{Symbol}} = nothing: A vector of symbols representing the beta features to be used. See?anthropic_extra_headersfor details.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments. Several important arguments are highlighted below:tool_choice: The choice of tool mode. Can be "auto", "exact", or can depend on the provided.. Defaults tonothing, which translates to "auto".
Example
## Let's define a tool\nget_weather(location, date) = "The weather in $location on $date is 70 degrees."\n\nmsg = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather, model = "claudeh")\nPT.execute_tool(get_weather, msg.tool_calls[1].args)\n# "The weather in Tokyo on 2023-05-03 is 70 degrees."\n\n# Ignores the tool\nmsg = aitools("What's your name?";\n tools = get_weather, model = "claudeh")\n# I don't have a personal name, but you can call me your AI assistant!How to have a multi-turn conversation with tools:
conv = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather, return_all = true, model = "claudeh")\n\ntool_msg = conv[end].tool_calls[1] # there can be multiple tool calls requested!!\n\n# Execute the output to the tool message content\ntool_msg.content = PT.execute_tool(get_weather, tool_msg.args)\n\n# Add the tool message to the conversation\npush!(conv, tool_msg)\n\n# Call LLM again with the updated conversation\nconv = aitools(\n "And in New York?"; tools = get_weather, return_all = true, conversation = conv, model = "claudeh")\n# 6-element Vector{AbstractMessage}:\n# SystemMessage("Act as a helpful AI assistant")\n# UserMessage("What's the weather in Tokyo on May 3rd, 2023?")\n# AIToolRequest("-"; Tool Requests: 1)\n# ToolMessage("The weather in Tokyo on 2023-05-03 is 70 degrees.")\n# UserMessage("And in New York?")\n# AIToolRequest("-"; Tool Requests: 1)Using the the new Computer Use beta feature:
# Define tools (and associated functions to call)\ntool_map = Dict("bash" => PT.ToolRef(; ref=:bash, callable=bash_tool),\n "computer" => PT.ToolRef(; ref=:computer, callable=computer_tool,\n extras=Dict("display_width_px" => 1920, "display_height_px" => 1080)),\n "str_replace_editor" => PT.ToolRef(; ref=:str_replace_editor, callable=edit_tool))\n\nmsg = aitools(prompt; tools=collect(values(tool_map)), model="claude", betas=[:computer_use])\n\nPT.pprint(msg)\n# --------------------\n# AI Tool Request\n# --------------------\n# Tool Request: computer, args: Dict{Symbol, Any}(:action => "screenshot")aitools(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n tools::Union{Type, Function, Method, AbstractTool, Vector} = Tool[],\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n image_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = (;\n tool_choice = nothing),\n strict::Union{Nothing, Bool} = nothing,\n json_mode::Union{Nothing, Bool} = nothing,\n name_user::Union{Nothing, String} = nothing,\n name_assistant::Union{Nothing, String} = nothing,\n kwargs...)Calls chat completion API with an optional tool call signature. It can receive both tools and standard string-based content. Ideal for agentic workflows with more complex cognitive architectures.
Difference to aigenerate: Response can be a tool call (structured)
Differences to aiextract: Can provide infinitely many tools (including Functions!) and then respond with the tool call's output.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplatetools: A vector of tools to be used in the conversation. Can be a vector of types, instances ofAbstractTool, or a mix of both.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_CHAT.return_all: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history.no_system_message::Bool = false: Whether to exclude the system message from the conversation history.image_path: A path to a local image file, or a vector of paths to local image files. Always attaches images to the latest user message.name_user: The name of the user in the conversation history. Defaults to "User".name_assistant: The name of the assistant in the conversation history. Defaults to "Assistant".http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments. Several important arguments are highlighted below:tool_choice: The choice of tool mode. Can be "auto", "exact", or can depend on the provided.. Defaults tonothing, which translates to "auto".response_format: The format of the response. Can be "json_schema" for JSON mode, or "text" for standard text output. Defaults to "text".
strict: Whether to enforce strict mode for the schema. Defaults tonothing.json_mode: Whether to enforce JSON mode for the schema. Defaults tonothing.
Example
## Let's define a tool\nget_weather(location, date) = "The weather in $location on $date is 70 degrees."\n\n## JSON mode request\nmsg = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather,\n json_mode = true)\nPT.execute_tool(get_weather, msg.tool_calls[1].args)\n# "The weather in Tokyo on 2023-05-03 is 70 degrees."\n\n# Function calling request\nmsg = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather)\nPT.execute_tool(get_weather, msg.tool_calls[1].args)\n# "The weather in Tokyo on 2023-05-03 is 70 degrees."\n\n# Ignores the tool\nmsg = aitools("What's your name?";\n tools = get_weather)\n# I don't have a personal name, but you can call me your AI assistant!How to have a multi-turn conversation with tools:
conv = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather, return_all = true)\n\ntool_msg = conv[end].tool_calls[1] # there can be multiple tool calls requested!!\n\n# Execute the output to the tool message content\ntool_msg.content = PT.execute_tool(get_weather, tool_msg.args)\n\n# Add the tool message to the conversation\npush!(conv, tool_msg)\n\n# Call LLM again with the updated conversation\nconv = aitools(\n "And in New York?"; tools = get_weather, return_all = true, conversation = conv)\n# 6-element Vector{AbstractMessage}:\n# SystemMessage("Act as a helpful AI assistant")\n# UserMessage("What's the weather in Tokyo on May 3rd, 2023?")\n# AIToolRequest("-"; Tool Requests: 1)\n# ToolMessage("The weather in Tokyo on 2023-05-03 is 70 degrees.")\n# UserMessage("And in New York?")\n# AIToolRequest("-"; Tool Requests: 1)aitools(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aitools call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiextract(with thetracer_schema.schema)calls
finalize_tracer
Aligns multiple tracers in the vector to have the same Parent and Thread IDs as the first item.
Aligns the tracer message, updating the parent_id, thread_id. Often used to align multiple tracers in the vector to have the same IDs.
annotate!(messages::AbstractVector{<:AbstractMessage}, content; kwargs...)\nannotate!(message::AbstractMessage, content; kwargs...)Add an annotation message to a vector of messages or wrap a single message in a vector with an annotation. The annotation is always inserted after any existing annotation messages.
Arguments
messages: Vector of messages or single message to annotatecontent: Content of the annotationkwargs...: Additional fields for the AnnotationMessage (extras, tags, comment)
Returns
Vector{AbstractMessage} with the annotation message inserted
Example
messages = [SystemMessage("Assistant"), UserMessage("Hello")]\nannotate!(messages, "This is important"; tags=[:important], comment="For review")anthropic_api(\n prompt_schema::AbstractAnthropicSchema,\n messages::Vector{<:AbstractDict{String, <:Any}} = Vector{Dict{String, Any}}();\n api_key::AbstractString = ANTHROPIC_API_KEY,\n system::Union{Nothing, AbstractString, AbstractVector{<:AbstractDict}} = nothing,\n endpoint::String = "messages",\n max_tokens::Int = 2048,\n model::String = "claude-3-haiku-20240307", http_kwargs::NamedTuple = NamedTuple(),\n stream::Bool = false,\n url::String = "https://api.anthropic.com/v1",\n cache::Union{Nothing, Symbol} = nothing,\n betas::Union{Nothing, Vector{Symbol}} = nothing,\n kwargs...)Simple wrapper for a call to Anthropic API.
Keyword Arguments
prompt_schema: Defines which prompt template should be applied.messages: a vector ofAbstractMessageto send to the modelsystem: An optional string representing the system message for the AI conversation. If not provided, a default message will be used.endpoint: The API endpoint to call, only "messages" are currently supported. Defaults to "messages".model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.max_tokens: The maximum number of tokens to generate. Defaults to 2048.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.stream: A boolean indicating whether to stream the response. Defaults tofalse.url: The URL of the Ollama API. Defaults to "localhost".cache: A symbol representing the caching strategy to be used. Currently onlynothing(no caching),:system,:tools,:lastand:allare supported.betas: A vector of symbols representing the beta features to be used. Currently only:toolsand:cacheare supported.kwargs: Prompt variables to be used to fill the prompt/template
anthropic_extra_headers(;\n has_tools = false, has_cache = false, has_long_output = false,\n betas::Union{Nothing, Vector{Symbol}} = nothing)Adds API version and beta headers to the request.
Kwargs / Beta headers
has_tools: Enables tools in the conversation.has_cache: Enables prompt caching.has_long_output: Enables long outputs (up to 8K tokens) with Anthropic's Sonnet 3.5.betas: A vector of symbols representing the beta features to be used. Currently only:computer_use,:long_output,:toolsand:cacheare supported.
Refer to BETA_HEADERS_ANTHROPIC for the allowed beta features.
auth_header(api_key::Union{Nothing, AbstractString};\n bearer::Bool = true,\n x_api_key::Bool = false,\n extra_headers::AbstractVector = Vector{\n Pair{String, String},\n }[],\n kwargs...)Creates the authentication headers for any API request. Assumes that the communication is done in JSON format.
Arguments
api_key::Union{Nothing, AbstractString}: The API key to be used for authentication. IfNothing, no authentication is used.bearer::Bool: Provide the API key in theAuthorization: Bearer ABCformat. Defaults totrue.x_api_key::Bool: Provide the API key in theAuthorization: x-api-key: ABCformat. Defaults tofalse.
batch_start_index(array_length::Integer, n::Integer, batch_size::Integer) -> IntegerCompute the starting index for retrieving the most recent data, adjusting in blocks of batch_size. The function accumulates messages until hitting a batch boundary, then jumps to the next batch.
For example, with n=20 and batch_size=10:
At length 90-99: returns 80 (allowing accumulation of 11-20 messages)
At length 100-109: returns 90 (allowing accumulation of 11-20 messages)
At length 110: returns 100 (resetting to 11 messages)
build_template_metadata(\n template::AbstractVector{<:AbstractMessage}, template_name::Symbol,\n metadata_msgs::AbstractVector{<:MetadataMessage} = MetadataMessage[]; max_length::Int = 100)Builds AITemplateMetadata for a given template based on the messages in template and other information.
AITemplateMetadata is a helper struct for easy searching and reviewing of templates via aitemplates().
Note: Assumes that there is only ever one UserMessage and SystemMessage (concatenates them together)
call_cost(prompt_tokens::Int, completion_tokens::Int, model::String;\n cost_of_token_prompt::Number = get(MODEL_REGISTRY,\n model,\n (; cost_of_token_prompt = 0.0)).cost_of_token_prompt,\n cost_of_token_generation::Number = get(MODEL_REGISTRY, model,\n (; cost_of_token_generation = 0.0)).cost_of_token_generation)\n\ncall_cost(msg, model::String)Calculate the cost of a call based on the number of tokens in the message and the cost per token. If the cost is already calculated (in msg.cost), it will not be re-calculated.
Arguments
prompt_tokens::Int: The number of tokens used in the prompt.completion_tokens::Int: The number of tokens used in the completion.model::String: The name of the model to use for determining token costs. If the model is not found inMODEL_REGISTRY, default costs are used.cost_of_token_prompt::Number: The cost per prompt token. Defaults to the cost inMODEL_REGISTRYfor the given model, or 0.0 if the model is not found.cost_of_token_generation::Number: The cost per generation token. Defaults to the cost inMODEL_REGISTRYfor the given model, or 0.0 if the model is not found.
Returns
Number: The total cost of the call.
Examples
# Assuming MODEL_REGISTRY is set up with appropriate costs\nMODEL_REGISTRY = Dict(\n "model1" => (cost_of_token_prompt = 0.05, cost_of_token_generation = 0.10),\n "model2" => (cost_of_token_prompt = 0.07, cost_of_token_generation = 0.02)\n)\n\ncost1 = call_cost(10, 20, "model1")\n\n# from message\nmsg1 = AIMessage(;tokens=[10, 20]) # 10 prompt tokens, 20 generation tokens\ncost1 = call_cost(msg1, "model1")\n# cost1 = 10 * 0.05 + 20 * 0.10 = 2.5\n\n# Using custom token costs\ncost2 = call_cost(10, 20, "model3"; cost_of_token_prompt = 0.08, cost_of_token_generation = 0.12)\n# cost2 = 10 * 0.08 + 20 * 0.12 = 3.2call_cost_alternative()
Alternative cost calculation. Used to calculate cost of image generation with DALL-E 3 and similar.
configure_callback!(cb::StreamCallback, schema::AbstractPromptSchema;\n api_kwargs...)Configures the callback cb for streaming with a given prompt schema.
If no cb.flavor is provided, adjusts the flavor and the provided api_kwargs as necessary. Eg, for most schemas, we add kwargs like stream = true to the api_kwargs.
If cb.flavor is provided, both callback and api_kwargs are left unchanged! You need to configure them yourself!
', 73)), + createBaseVNode("div", _hoisted_3, [ + _cache[16] || (_cache[16] = createStaticVNode('# PromptingTools.create_template — Method.
create_template(; user::AbstractString, system::AbstractString="Act as a helpful AI assistant.", \n load_as::Union{Nothing, Symbol, AbstractString} = nothing)\n\ncreate_template(system::AbstractString, user::AbstractString, \n load_as::Union{Nothing, Symbol, AbstractString} = nothing)Creates a simple template with a user and system message. Convenience function to prevent writing [PT.UserMessage(...), ...]
Arguments
system::AbstractString: The system message. Usually defines the personality, style, instructions, output format, etc.user::AbstractString: The user message. Usually defines the input, query, request, etc.load_as::Union{Nothing, Symbol, AbstractString}: If provided, loads the template into theTEMPLATE_STOREunder the provided nameload_as. Ifnothing, does not load the template.
Returns a vector of SystemMessage and UserMessage objects. If load_as is provided, it registers the template in the TEMPLATE_STORE and TEMPLATE_METADATA as well.
Examples
Let's generate a quick template for a simple conversation (only one placeholder: name)
# first system message, then user message (or use kwargs)\ntpl=PT.create_template("You must speak like a pirate", "Say hi to {{name}}")\n\n## 2-element Vector{PromptingTools.AbstractChatMessage}:\n## PromptingTools.SystemMessage("You must speak like a pirate")\n## PromptingTools.UserMessage("Say hi to {{name}}")You can immediately use this template in ai* functions:
aigenerate(tpl; name="Jack Sparrow")\n# Output: AIMessage("Arr, me hearty! Best be sending me regards to Captain Jack Sparrow on the salty seas! May his compass always point true to the nearest treasure trove. Yarrr!")If you're interested in saving the template in the template registry, jump to the end of these examples!
If you want to save it in your project folder:
PT.save_template("templates/GreatingPirate.json", tpl; version="1.0") # optionally, add descriptionIt will be saved and accessed under its basename, ie, GreatingPirate.
Now you can load it like all the other templates (provide the template directory):
PT.load_templates!("templates") # it will remember the folder after the first run\n# Note: If you save it again, overwrite it, etc., you need to explicitly reload all templates again!You can verify that your template is loaded with a quick search for "pirate":
aitemplates("pirate")\n\n## 1-element Vector{AITemplateMetadata}:\n## PromptingTools.AITemplateMetadata\n## name: Symbol GreatingPirate\n## description: String ""\n## version: String "1.0"\n## wordcount: Int64 46\n## variables: Array{Symbol}((1,))\n## system_preview: String "You must speak like a pirate"\n## user_preview: String "Say hi to {{name}}"\n## source: String ""Now you can use it like any other template (notice it's a symbol, so :GreatingPirate):
aigenerate(:GreatingPirate; name="Jack Sparrow")\n# Output: AIMessage("Arr, me hearty! Best be sending me regards to Captain Jack Sparrow on the salty seas! May his compass always point true to the nearest treasure trove. Yarrr!")If you do not need to save this template as a file, but you want to make it accessible in the template store for all ai* functions, you can use the load_as (= template name) keyword argument:
# this will not only create the template, but also register it for immediate use\ntpl=PT.create_template("You must speak like a pirate", "Say hi to {{name}}"; load_as="GreatingPirate")\n\n# you can now use it like any other template\naiextract(:GreatingPirate; name="Jack Sparrow")decode_choices(schema::OpenAISchema,\n choices::AbstractVector{<:AbstractString},\n msg::AIMessage; model::AbstractString,\n token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing,\n kwargs...)Decodes the underlying AIMessage against the original choices to lookup what the category name was.
If it fails, it will return msg.content == nothing
detect_base_main_overrides(code_block::AbstractString)Detects if a given code block overrides any Base or Main methods.
Returns a tuple of a boolean and a vector of the overriden methods.
distance_longest_common_subsequence(\n input1::AbstractString, input2::AbstractString)\n\ndistance_longest_common_subsequence(\n input1::AbstractString, input2::AbstractVector{<:AbstractString})Measures distance between two strings using the length of the longest common subsequence (ie, the lower the number, the better the match). Perfect match is distance = 0.0
Convenience wrapper around length_longest_common_subsequence to normalize the distances to 0-1 range. There is a also a dispatch for comparing a string vs an array of strings.
Notes
Use
argminandminimumto find the position of the closest match and the distance, respectively.Matching with an empty string will always return 1.0 (worst match), even if the other string is empty as well (safety mechanism to avoid division by zero).
Arguments
input1::AbstractString: The first string to compare.input2::AbstractString: The second string to compare.
Example
You can also use it to find the closest context for some AI generated summary/story:
context = ["The enigmatic stranger vanished as swiftly as a wisp of smoke, leaving behind a trail of unanswered questions.",\n "Beneath the shimmering moonlight, the ocean whispered secrets only the stars could hear.",\n "The ancient tree stood as a silent guardian, its gnarled branches reaching for the heavens.",\n "The melody danced through the air, painting a vibrant tapestry of emotions.",\n "Time flowed like a relentless river, carrying away memories and leaving imprints in its wake."]\n\nstory = """\n Beneath the shimmering moonlight, the ocean whispered secrets only the stars could hear.\n\n Under the celestial tapestry, the vast ocean whispered its secrets to the indifferent stars. Each ripple, a murmured confidence, each wave, a whispered lament. The glittering celestial bodies listened in silent complicity, their enigmatic gaze reflecting the ocean's unspoken truths. The cosmic dance between the sea and the sky, a symphony of shared secrets, forever echoing in the ethereal expanse.\n """\n\ndist = distance_longest_common_subsequence(story, context)\n@info "The closest context to the query: "$(first(story,20))..." is: "$(context[argmin(dist)])" (distance: $(minimum(dist)))"encode_choices(schema::OpenAISchema, choices::AbstractVector{<:AbstractString};\n model::AbstractString,\n token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing,\n kwargs...)\n\nencode_choices(schema::OpenAISchema, choices::AbstractVector{T};\n model::AbstractString,\n token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing,\n kwargs...) where {T <: Tuple{<:AbstractString, <:AbstractString}}Encode the choices into an enumerated list that can be interpolated into the prompt and creates the corresponding logit biases (to choose only from the selected tokens).
Optionally, can be a vector tuples, where the first element is the choice and the second is the description.
There can be at most 40 choices provided.
Arguments
schema::OpenAISchema: The OpenAISchema object.choices::AbstractVector{<:Union{AbstractString,Tuple{<:AbstractString, <:AbstractString}}}: The choices to be encoded, represented as a vector of the choices directly, or tuples where each tuple contains a choice and its description.model::AbstractString: The model to use for encoding. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing: A dictionary mapping custom token IDs to their corresponding integer values. Ifnothing, it will use the default token IDs for the given model.kwargs...: Additional keyword arguments.
Returns
choices_prompt::AbstractString: The encoded choices as a single string, separated by newlines.logit_bias::Dict: The logit bias dictionary, where the keys are the token IDs and the values are the bias values.decode_ids::AbstractVector{<:AbstractString}: The decoded IDs of the choices.
Examples
choices_prompt, logit_bias, _ = PT.encode_choices(PT.OpenAISchema(), ["true", "false"])\nchoices_prompt # Output: "true for "true"\nfalse for "false"\nlogit_bias # Output: Dict(837 => 100, 905 => 100)\n\nchoices_prompt, logit_bias, _ = PT.encode_choices(PT.OpenAISchema(), ["animal", "plant"])\nchoices_prompt # Output: "1. "animal"\n2. "plant""\nlogit_bias # Output: Dict(16 => 100, 17 => 100)Or choices with descriptions:
choices_prompt, logit_bias, _ = PT.encode_choices(PT.OpenAISchema(), [("A", "any animal or creature"), ("P", "for any plant or tree"), ("O", "for everything else")])\nchoices_prompt # Output: "1. "A" for any animal or creature\n2. "P" for any plant or tree\n3. "O" for everything else"\nlogit_bias # Output: Dict(16 => 100, 17 => 100, 18 => 100)eval!(cb::AbstractCodeBlock;\n safe_eval::Bool = true,\n capture_stdout::Bool = true,\n prefix::AbstractString = "",\n suffix::AbstractString = "")Evaluates a code block cb in-place. It runs automatically when AICode is instantiated with a String.
Check the outcome of evaluation with Base.isvalid(cb). If ==true, provide code block has executed successfully.
Steps:
If
cb::AICodehas not been evaluated,cb.success = nothing. After the evaluation it will be eithertrueorfalsedepending on the outcomeParse the text in
cb.codeEvaluate the parsed expression
Capture outputs of the evaluated in
cb.output[OPTIONAL] Capture any stdout outputs (eg, test failures) in
cb.stdoutIf any error exception is raised, it is saved in
cb.errorFinally, if all steps were successful, success is set to
cb.success = true
Keyword Arguments
safe_eval::Bool: Iftrue, we first check for any Pkg operations (eg, installing new packages) and missing imports, then the code will be evaluated inside a bespoke scratch module (not to change any user variables)capture_stdout::Bool: Iftrue, we capture any stdout outputs (eg, test failures) incb.stdoutprefix::AbstractString: A string to be prepended to the code block before parsing and evaluation. Useful to add some additional code definition or necessary imports. Defaults to an empty string.suffix::AbstractString: A string to be appended to the code block before parsing and evaluation. Useful to check that tests pass or that an example executes. Defaults to an empty string.
execute_tool(f::Function, args::AbstractDict{Symbol, <:Any},\n context::AbstractDict{Symbol, <:Any} = Dict{Symbol, Any}();\n throw_on_error::Bool = true, unused_as_kwargs::Bool = false,\n kwargs...)Executes a function with the provided arguments.
Picks the function arguments in the following order:
:contextrefers to the context dictionary passed to the function.Then it looks for the arguments in the
contextdictionary.Then it looks for the arguments in the
argsdictionary.
Dictionary is un-ordered, so we need to sort the arguments first and then pass them to the function.
Arguments
f::Function: The function to execute.args::AbstractDict{Symbol, <:Any}: The arguments to pass to the function.context::AbstractDict{Symbol, <:Any}: Optional context to pass to the function, it will prioritized to get the argument values from.throw_on_error::Bool: Whether to throw an error if the tool execution fails. Defaults totrue.unused_as_kwargs::Bool: Whether to pass unused arguments as keyword arguments. Defaults tofalse. Function must support keyword arguments!kwargs...: Additional keyword arguments to pass to the function.
Example
my_function(x, y) = x + y\nexecute_tool(my_function, Dict(:x => 1, :y => 2))get_weather(date, location) = "The weather in $location on $date is 70 degrees."\ntool_map = PT.tool_call_signature(get_weather)\n\nmsg = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = collect(values(tool_map)))\n\nPT.execute_tool(tool_map, PT.tool_calls(msg)[1])\n# "The weather in Tokyo on 2023-05-03 is 70 degrees."extract_code_blocks(markdown_content::String) -> Vector{String}Extract Julia code blocks from a markdown string.
This function searches through the provided markdown content, identifies blocks of code specifically marked as Julia code (using the julia ... code fence patterns), and extracts the code within these blocks. The extracted code blocks are returned as a vector of strings, with each string representing one block of Julia code.
Note: Only the content within the code fences is extracted, and the code fences themselves are not included in the output.
See also: extract_code_blocks_fallback
Arguments
markdown_content::String: A string containing the markdown content from which Julia code blocks are to be extracted.
Returns
Vector{String}: A vector containing strings of extracted Julia code blocks. If no Julia code blocks are found, an empty vector is returned.
Examples
Example with a single Julia code block
markdown_single = """julia println("Hello, World!")
"""\nextract_code_blocks(markdown_single)\n# Output: ["Hello, World!"]# Example with multiple Julia code blocks\nmarkdown_multiple = """julia x = 5
Some text in betweenjulia y = x + 2
"""\nextract_code_blocks(markdown_multiple)\n# Output: ["x = 5", "y = x + 2"]extract_code_blocks_fallback(markdown_content::String, delim::AbstractString="\\n```\\n")Extract Julia code blocks from a markdown string using a fallback method (splitting by arbitrary delim-iters). Much more simplistic than extract_code_blocks and does not support nested code blocks.
It is often used as a fallback for smaller LLMs that forget to code fence julia ....
Example
code = """println("hello")
\nSome textprintln("world")
"""\n\n# We extract text between triple backticks and check each blob if it looks like a valid Julia code\ncode_parsed = extract_code_blocks_fallback(code) |> x -> filter(is_julia_code, x) |> x -> join(x, "\n")extract_function_name(code_block::String) -> Union{String, Nothing}Extract the name of a function from a given Julia code block. The function searches for two patterns:
The explicit function declaration pattern:
function name(...) ... endThe concise function declaration pattern:
name(...) = ...
If a function name is found, it is returned as a string. If no function name is found, the function returns nothing.
To capture all function names in the block, use extract_function_names.
Arguments
code_block::String: A string containing Julia code.
Returns
Union{String, Nothing}: The extracted function name ornothingif no name is found.
Example
code = """\nfunction myFunction(arg1, arg2)\n # Function body\nend\n"""\nextract_function_name(code)\n# Output: "myFunction"extract_function_names(code_block::AbstractString)Extract one or more names of functions defined in a given Julia code block. The function searches for two patterns: - The explicit function declaration pattern: function name(...) ... end - The concise function declaration pattern: name(...) = ...
It always returns a vector of strings, even if only one function name is found (it will be empty).
For only one function name match, use extract_function_name.
extract_image_attributes(image_url::AbstractString) -> Tuple{String, String}Extracts the data type and base64-encoded data from a data URL.
Arguments
image_url::AbstractString: The data URL to be parsed.
Returns
Tuple{String, String}: A tuple containing the data type (e.g., "image/png") and the base64-encoded data.
Example
image_url = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABQAA"\ndata_type, data = extract_data_type_and_data(image_url)\n# data_type == "image/png"\n# data == "iVBORw0KGgoAAAANSUhEUgAABQAA"extract_julia_imports(input::AbstractString; base_or_main::Bool = false)Detects any using or import statements in a given string and returns the package names as a vector of symbols.
base_or_main is a boolean that determines whether to isolate only Base and Main OR whether to exclude them in the returned vector.
finalize_outputs(prompt::ALLOWED_PROMPT_TYPE, conv_rendered::Any,\n msg::Union{Nothing, AbstractMessage, AbstractVector{<:AbstractMessage}};\n return_all::Bool = false,\n dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n kwargs...)Finalizes the outputs of the ai* functions by either returning the conversation history or the last message.
Keyword arguments
return_all::Bool=false: If true, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: If true, does not send the messages to the model, but only renders the prompt with the given schema and replacement variables. Useful for debugging when you want to check the specific schema rendering.conversation::AbstractVector{<:AbstractMessage}=[]: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.kwargs...: Variables to replace in the prompt template.no_system_message::Bool=false: If true, the default system message is not included in the conversation history. Any existing system message is converted to aUserMessage.
finalize_tracer(\n tracer_schema::AbstractTracerSchema, tracer, msg_or_conv::Union{\n AbstractMessage, AbstractVector{<:AbstractMessage}};\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Finalizes the calltracer of whatever is nedeed after the ai* calls. Use tracer_kwargs to provide any information necessary (eg, parent_id, thread_id, run_id).
In the default implementation, we convert all non-tracer messages into TracerMessage.
See also: meta, unwrap, SaverSchema, initialize_tracer
finalize_tracer(\n tracer_schema::SaverSchema, tracer, msg_or_conv::Union{\n AbstractMessage, AbstractVector{<:AbstractMessage}};\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Finalizes the calltracer by saving the provided conversation msg_or_conv to the disk.
Default path is LOG_DIR/conversation__<first_msg_hash>__<time_received_str>.json, where LOG_DIR is set by user preferences or ENV variable (defaults to log/ in current working directory).
If you want to change the logging directory or the exact file name to log with, you can provide the following arguments to tracer_kwargs:
log_dir- used as the directory to save the log into when provided. Defaults toLOG_DIRif not provided.log_file_path- used as the file name to save the log into when provided. This value overrules thelog_dirandLOG_DIRif provided.
It can be composed with TracerSchema to also attach necessary metadata (see below).
Example
wrap_schema = PT.SaverSchema(PT.TracerSchema(PT.OpenAISchema()))\nconv = aigenerate(wrap_schema,:BlankSystemUser; system="You're a French-speaking assistant!",\n user="Say hi!"; model="gpt-4", api_kwargs=(;temperature=0.1), return_all=true)\n\n# conv is a vector of messages that will be saved to a JSON together with metadata about the template and api_kwargsSee also: meta, unwrap, TracerSchema, initialize_tracer
find_subsequence_positions(subseq, seq) -> Vector{Int}Find all positions of a subsequence subseq within a larger sequence seq. Used to lookup positions of code blocks in markdown.
This function scans the sequence seq and identifies all starting positions where the subsequence subseq is found. Both subseq and seq should be vectors of integers, typically obtained using codeunits on strings.
Arguments
subseq: A vector of integers representing the subsequence to search for.seq: A vector of integers representing the larger sequence in which to search.
Returns
Vector{Int}: A vector of starting positions (1-based indices) where the subsequence is found in the sequence.
Examples
find_subsequence_positions(codeunits("ab"), codeunits("cababcab")) # Returns [2, 5]generate_struct(fields::Vector)Generate a struct with the given name and fields. Fields can be specified simply as symbols (with default type String) or pairs of symbol and type. Field descriptions can be provided by adding a pair with the field name suffixed with "**description" (eg, :myfield**description => "My field description").
Returns: A tuple of (struct type, descriptions)
Examples
Weather, descriptions = generate_struct(\n [:location,\n :temperature=>Float64,\n :temperature__description=>"Temperature in degrees Fahrenheit",\n :condition=>String,\n :condition__description=>"Current weather condition (e.g., sunny, rainy, cloudy)"\n ])Get the argument names from a function, ignores keyword arguments!!
Get the argument names from a method, ignores keyword arguments!!
Get the argument types from a function, ignores keyword arguments!!
Get the argument types from a method, ignores keyword arguments!!
get_last(mem::ConversationMemory, n::Integer=20;\n batch_size::Union{Nothing,Integer}=nothing,\n verbose::Bool=false,\n explain::Bool=false)Get the last n messages (but including system message) with intelligent batching to preserve caching.
Arguments:
n::Integer: Maximum number of messages to return (default: 20)
batch_size::Union{Nothing,Integer}: If provided, ensures messages are truncated in fixed batches
verbose::Bool: Print detailed information about truncation
explain::Bool: Add explanation about truncation in the response
Returns: Vector{AbstractMessage} with the selected messages, always including:
The system message (if present)
First user message
Messages up to n, respecting batch_size boundaries
Once you get your full conversation back, you can use append!(mem, conversation) to merge the new messages into the memory.
Examples:
# Basic usage - get last 3 messages\nmem = ConversationMemory()\npush!(mem, SystemMessage("You are helpful"))\npush!(mem, UserMessage("Hello"))\npush!(mem, AIMessage("Hi!"))\npush!(mem, UserMessage("How are you?"))\npush!(mem, AIMessage("I'm good!"))\nmessages = get_last(mem, 3)\n\n# Using batch_size for caching efficiency\nmessages = get_last(mem, 10; batch_size=5) # Aligns to 5-message batches for caching\n\n# Add explanation about truncation\nmessages = get_last(mem, 3; explain=true) # Adds truncation note to first AI message so the model knows it's truncated\n\n# Get verbose output about truncation\nmessages = get_last(mem, 3; verbose=true) # Prints info about truncationget_preferences(key::String)Get preferences for PromptingTools. See ?PREFERENCES for more information.
See also: set_preferences!
Example
PromptingTools.get_preferences("MODEL_CHAT")Stub - to be extended in extension: GoogleGenAIPromptingToolsExt. ggi stands for GoogleGenAI
Checks if a given string has a Julia prompt (julia>) at the beginning of a line.
initialize_tracer(\n tracer_schema::AbstractTracerSchema; model = "", tracer_kwargs = NamedTuple(),\n prompt::ALLOWED_PROMPT_TYPE = "", kwargs...)Initializes tracer/callback (if necessary). Can provide any keyword arguments in tracer_kwargs (eg, parent_id, thread_id, run_id). Is executed prior to the ai* calls.
By default it captures:
time_sent: the time the request was sentmodel: the model to usemeta: a dictionary of additional metadata that is not part of the tracer itselftemplate_name: the template to use if anytemplate_version: the template version to use if anyexpanded
api_kwargs, ie, the keyword arguments to pass to the API call
In the default implementation, we just collect the necessary data to build the tracer object in finalize_tracer.
See also: meta, unwrap, TracerSchema, SaverSchema, finalize_tracer
Check if the object is an instance of AbstractExtractedData
Helpful accessor for the last message in conversation. Returns the last message in the conversation.
last_message(mem::ConversationMemory)Get the last message in the conversation.
Helpful accessor for the last generated output (msg.content) in conversation. Returns the last output in the conversation (eg, the string/data in the last message).
last_output(mem::ConversationMemory)Get the last AI message in the conversation.
length_longest_common_subsequence(itr1::AbstractString, itr2::AbstractString)Compute the length of the longest common subsequence between two string sequences (ie, the higher the number, the better the match).
Arguments
itr1: The first sequence, eg, a String.itr2: The second sequence, eg, a String.
Returns
The length of the longest common subsequence.
Examples
text1 = "abc-abc----"\ntext2 = "___ab_c__abc"\nlongest_common_subsequence(text1, text2)\n# Output: 6 (-> "abcabc")It can be used to fuzzy match strings and find the similarity between them (Tip: normalize the match)
commands = ["product recommendation", "emotions", "specific product advice", "checkout advice"]\nquery = "Which product can you recommend for me?"\nlet pos = argmax(length_longest_common_subsequence.(Ref(query), commands))\n dist = length_longest_common_subsequence(query, commands[pos])\n norm = dist / min(length(query), length(commands[pos]))\n @info "The closest command to the query: "$(query)" is: "$(commands[pos])" (distance: $(dist), normalized: $(norm))"\nendBut it might be easier to use directly the convenience wrapper distance_longest_common_subsequence!
\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/utils.jl#L252-L288)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.list_aliases-Tuple{}' href='#PromptingTools.list_aliases-Tuple{}'>#</a> <b><u>PromptingTools.list_aliases</u></b> — <i>Method</i>.\n\n\n\n\nShows the Dictionary of model aliases in the registry. Add more with `MODEL_ALIASES[alias] = model_name`.\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/user_preferences.jl#L1257)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.list_registry-Tuple{}' href='#PromptingTools.list_registry-Tuple{}'>#</a> <b><u>PromptingTools.list_registry</u></b> — <i>Method</i>.\n\n\n\n\nShows the list of models in the registry. Add more with `register_model!`.\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/user_preferences.jl#L1255)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.load_api_keys!-Tuple{}' href='#PromptingTools.load_api_keys!-Tuple{}'>#</a> <b><u>PromptingTools.load_api_keys!</u></b> — <i>Method</i>.\n\n\n\n\nLoads API keys from environment variables and preferences\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/user_preferences.jl#L178)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.load_conversation-Tuple{Union{AbstractString, IO}}' href='#PromptingTools.load_conversation-Tuple{Union{AbstractString, IO}}'>#</a> <b><u>PromptingTools.load_conversation</u></b> — <i>Method</i>.\n\n\n\n\n```julia\nload_conversation(io_or_file::Union{IO, AbstractString})Loads a conversation (messages) from io_or_file
load_template(io_or_file::Union{IO, AbstractString})Loads messaging template from io_or_file and returns tuple of template messages and metadata.
load_templates!(dir_templates::Union{String, Nothing} = nothing;\n remember_path::Bool = true,\n remove_templates::Bool = isnothing(dir_templates),\n store::Dict{Symbol, <:Any} = TEMPLATE_STORE,\n metadata_store::Vector{<:AITemplateMetadata} = TEMPLATE_METADATA)Loads templates from folder templates/ in the package root and stores them in TEMPLATE_STORE and TEMPLATE_METADATA.
Note: Automatically removes any existing templates and metadata from TEMPLATE_STORE and TEMPLATE_METADATA if remove_templates=true.
Arguments
dir_templates::Union{String, Nothing}: The directory path to load templates from. Ifnothing, uses the default list of paths. It usually used only once "to register" a new template storage.remember_path::Bool=true: If true, remembers the path for future refresh (inTEMPLATE_PATH).remove_templates::Bool=isnothing(dir_templates): If true, removes any existing templates and metadata fromstoreandmetadata_store.store::Dict{Symbol, <:Any}=TEMPLATE_STORE: The store to load the templates into.metadata_store::Vector{<:AITemplateMetadata}=TEMPLATE_METADATA: The metadata store to load the metadata into.
Example
Load the default templates:
PT.load_templates!() # no path neededLoad templates from a new custom path:
PT.load_templates!("path/to/templates") # we will remember this path for future refreshIf you want to now refresh the default templates and the new path, just call load_templates!() without any arguments.
Extracts the metadata dictionary from the tracer message or tracer-like object.
ollama_api(prompt_schema::Union{AbstractOllamaManagedSchema, AbstractOllamaSchema},\n prompt::Union{AbstractString, Nothing} = nothing;\n system::Union{Nothing, AbstractString} = nothing,\n messages::Vector{<:AbstractMessage} = AbstractMessage[],\n endpoint::String = "generate",\n model::String = "llama2", http_kwargs::NamedTuple = NamedTuple(),\n stream::Bool = false,\n url::String = "localhost", port::Int = 11434,\n kwargs...)Simple wrapper for a call to Ollama API.
Keyword Arguments
prompt_schema: Defines which prompt template should be applied.prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessagesystem: An optional string representing the system message for the AI conversation. If not provided, a default message will be used.endpoint: The API endpoint to call, only "generate" and "embeddings" are currently supported. Defaults to "generate".model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.stream: A boolean indicating whether to stream the response. Defaults tofalse.streamcallback::Any: A callback function to handle streaming responses. Can be simplystdoutor aStreamCallbackobject. See?StreamCallbackfor details.url: The URL of the Ollama API. Defaults to "localhost".port: The port of the Ollama API. Defaults to 11434.kwargs: Prompt variables to be used to fill the prompt/template
parse_tool(datatype::Type, blob::AbstractString; kwargs...)Parse the JSON blob into the specified datatype in try-catch mode.
If parsing fails, it tries to return the untyped JSON blob in a dictionary.
pprint(io::IO, conversation::AbstractVector{<:AbstractMessage})Pretty print a vector of AbstractMessage to the given IO stream.
pprint(io::IO, msg::AbstractMessage; text_width::Int = displaysize(io)[2])Pretty print a single AbstractMessage to the given IO stream.
text_width is the width of the text to be displayed. If not provided, it defaults to the width of the given IO stream and add newline separators as needed.
Utility for rendering the conversation (vector of messages) as markdown. REQUIRES the Markdown package to load the extension! See also pprint
push_conversation!(conv_history, conversation::AbstractVector, max_history::Union{Int, Nothing})Add a new conversation to the conversation history and resize the history if necessary.
This function appends a conversation to the conv_history, which is a vector of conversations. Each conversation is represented as a vector of AbstractMessage objects. After adding the new conversation, the history is resized according to the max_history parameter to ensure that the size of the history does not exceed the specified limit.
Arguments
conv_history: A vector that stores the history of conversations. Typically, this isPT.CONV_HISTORY.conversation: The new conversation to be added. It should be a vector ofAbstractMessageobjects.max_history: The maximum number of conversations to retain in the history. IfNothing, the history is not resized.
Returns
The updated conversation history.
Example
new_conversation = aigenerate("Hello World"; return_all = true)\npush_conversation!(PT.CONV_HISTORY, new_conversation, 10)This is done automatically by the ai"" macros.
recursive_splitter(text::AbstractString, separators::Vector{String}; max_length::Int=35000) -> Vector{String}Split a given string text into chunks recursively using a series of separators, with each chunk having a maximum length of max_length (if it's achievable given the separators provided). This function is useful for splitting large documents or texts into smaller segments that are more manageable for processing, particularly for models or systems with limited context windows.
It was previously known as split_by_length.
This is similar to Langchain's RecursiveCharacterTextSplitter. To achieve the same behavior, use separators=["\\n\\n", "\\n", " ", ""].
Arguments
text::AbstractString: The text to be split.separators::Vector{String}: An ordered list of separators used to split the text. The function iteratively applies these separators to split the text. Recommend to use["\\n\\n", ". ", "\\n", " "]max_length::Int: The maximum length of each chunk. Defaults to 35,000 characters. This length is considered after each iteration of splitting, ensuring chunks fit within specified constraints.
Returns
Vector{String}: A vector of strings, where each string is a chunk of the original text that is smaller than or equal to max_length.
Usage Tips
I tend to prefer splitting on sentences (
". ") before splitting on newline characters ("\\n") to preserve the structure of the text.What's the difference between
separators=["\\n"," ",""]andseparators=["\\n"," "]? The former will split down to character level (""), so it will always achieve themax_lengthbut it will split words (bad for context!) I prefer to instead set slightly smallermax_lengthbut not split words.
How It Works
The function processes the text iteratively with each separator in the provided order. It then measures the length of each chunk and splits it further if it exceeds the
max_length. If the chunks is "short enough", the subsequent separators are not applied to it.Each chunk is as close to
max_lengthas possible (unless we cannot split it any further, eg, if the splitters are "too big" / there are not enough of them)If the
textis empty, the function returns an empty array.Separators are re-added to the text chunks after splitting, preserving the original structure of the text as closely as possible. Apply
stripif you do not need them.The function provides
separatorsas the second argument to distinguish itself from its single-separator counterpart dispatch.
Examples
Splitting text using multiple separators:
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n"] # split by paragraphs, sentences, and newlines (not by words)\nchunks = recursive_splitter(text, separators, max_length=20)Splitting text using multiple separators - with splitting on words:
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n", " "] # split by paragraphs, sentences, and newlines, words\nchunks = recursive_splitter(text, separators, max_length=10)Using a single separator:
text = "Hello,World," ^ 2900 # length 34900 characters\nchunks = recursive_splitter(text, [","], max_length=10000)To achieve the same behavior as Langchain's RecursiveCharacterTextSplitter, use separators=["\\n\\n", "\\n", " ", ""].
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", "\\n", " ", ""]\nchunks = recursive_splitter(text, separators, max_length=10)recursive_splitter(text::String; separator::String=" ", max_length::Int=35000) -> Vector{String}Split a given string text into chunks of a specified maximum length max_length. This is particularly useful for splitting larger documents or texts into smaller segments, suitable for models or systems with smaller context windows.
There is a method for dispatching on multiple separators, recursive_splitter(text::String, separators::Vector{String}; max_length::Int=35000) -> Vector{String} that mimics the logic of Langchain's RecursiveCharacterTextSplitter.
Arguments
text::String: The text to be split.separator::String=" ": The separator used to split the text into minichunks. Defaults to a space character.max_length::Int=35000: The maximum length of each chunk. Defaults to 35,000 characters, which should fit within 16K context window.
Returns
Vector{String}: A vector of strings, each representing a chunk of the original text that is smaller than or equal to max_length.
Notes
The function ensures that each chunk is as close to
max_lengthas possible without exceeding it.If the
textis empty, the function returns an empty array.The
separatoris re-added to the text chunks after splitting, preserving the original structure of the text as closely as possible.
Examples
Splitting text with the default separator (" "):
text = "Hello world. How are you?"\nchunks = recursive_splitter(text; max_length=13)\nlength(chunks) # Output: 2Using a custom separator and custom max_length
text = "Hello,World," ^ 2900 # length 34900 chars\nrecursive_splitter(text; separator=",", max_length=10000) # for 4K context window\nlength(chunks[1]) # Output: 4register_model!(registry = MODEL_REGISTRY;\n name::String,\n schema::Union{AbstractPromptSchema, Nothing} = nothing,\n cost_of_token_prompt::Float64 = 0.0,\n cost_of_token_generation::Float64 = 0.0,\n description::String = "")Register a new AI model with name and its associated schema.
Registering a model helps with calculating the costs and automatically selecting the right prompt schema.
Arguments
name: The name of the model. This is the name that will be used to refer to the model in theai*functions.schema: The schema of the model. This is the schema that will be used to generate prompts for the model, eg,OpenAISchema().cost_of_token_prompt: The cost of a token in the prompt for this model. This is used to calculate the cost of a prompt. Note: It is often provided online as cost per 1000 tokens, so make sure to convert it correctly!cost_of_token_generation: The cost of a token generated by this model. This is used to calculate the cost of a generation. Note: It is often provided online as cost per 1000 tokens, so make sure to convert it correctly!description: A description of the model. This is used to provide more information about the model when it is queried.
remove_field!(parameters::AbstractDict, field::AbstractString)Utility to remove a specific top-level field from the parameters (and the required list if present) of the JSON schema.
remove_julia_prompt(s::T) where {T<:AbstractString}If it detects a julia prompt, it removes it and all lines that do not have it (except for those that belong to the code block).
remove_templates!()Removes all templates from TEMPLATE_STORE and TEMPLATE_METADATA.
Iterates over the lines of a string and removes those that contain a package operation or a missing import.
Renders provided messaging template (template) under the default schema (PROMPT_SCHEMA).
render(schema::AbstractAnthropicSchema,\n tool::ToolRef;\n kwargs...)Renders the tool reference into the Anthropic format.
Available tools:
:computer: A tool for using the computer.:str_replace_editor: A tool for replacing text in a string.:bash: A tool for running bash commands.
', 107)), + createBaseVNode("div", _hoisted_4, [ + _cache[20] || (_cache[20] = createStaticVNode('# PromptingTools.render — Method.
render(schema::AbstractAnthropicSchema,\n messages::Vector{<:AbstractMessage};\n aiprefill::Union{Nothing, AbstractString} = nothing,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n cache::Union{Nothing, Symbol} = nothing,\n kwargs...)Keyword Arguments
aiprefill: A string to be used as a prefill for the AI response. This steer the AI response in a certain direction (and potentially save output tokens).conversation: Past conversation to be included in the beginning of the prompt (for continued conversations).no_system_message: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.cache: A symbol representing the caching strategy to be used. Currently onlynothing(no caching),:system,:tools,:lastand:allare supported.
render(schema::AbstractAnthropicSchema,\n tools::Vector{<:AbstractTool};\n kwargs...)Renders the tool signatures into the Anthropic format.
', 3)), + createBaseVNode("div", _hoisted_5, [ + _cache[24] || (_cache[24] = createStaticVNode('# PromptingTools.render — Method.
render(schema::AbstractGoogleSchema,\n messages::Vector{<:AbstractMessage};\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n kwargs...)Keyword Arguments
conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message::Bool=false: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.
render(schema::AbstractOllamaManagedSchema,\n messages::Vector{<:AbstractMessage};\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n kwargs...)render(schema::AbstractOllamaSchema,\n messages::Vector{<:AbstractMessage};\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n kwargs...)Keyword Arguments
conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.
render(schema::AbstractOpenAISchema,\n messages::Vector{<:AbstractMessage};\n image_detail::AbstractString = "auto",\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n name_user::Union{Nothing, String} = nothing,\n kwargs...)Keyword Arguments
image_detail: Only forUserMessageWithImages. It represents the level of detail to include for images. Can be"auto","high", or"low".conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.name_user: No-op for consistency.
render(schema::AbstractOpenAISchema,\n tools::Vector{<:AbstractTool};\n json_mode::Union{Nothing, Bool} = nothing,\n kwargs...)Renders the tool signatures into the OpenAI format.
render(tracer_schema::AbstractTracerSchema,\n conv::AbstractVector{<:AbstractMessage}; kwargs...)Passthrough. No changes.
', 5)), + createBaseVNode("div", _hoisted_9, [ + _cache[45] || (_cache[45] = createStaticVNode('# PromptingTools.render — Method.
render(schema::NoSchema,\n messages::Vector{<:AbstractMessage};\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n replacement_kwargs...)Renders a conversation history from a vector of messages with all replacement variables specified in replacement_kwargs.
It is the first pass of the prompt rendering system, and is used by all other schemas.
Keyword Arguments
image_detail: Only forUserMessageWithImages. It represents the level of detail to include for images. Can be"auto","high", or"low".conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.
Notes
', 12)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[41] || (_cache[41] = createTextVNode("All unspecified kwargs are passed as replacements such that ")), + createBaseVNode("code", null, toDisplayString(_ctx.key) + "=>value", 1), + _cache[42] || (_cache[42] = createTextVNode(" in the template.")) + ]) + ]), + _cache[43] || (_cache[43] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "If a SystemMessage is missing, we inject a default one at the beginning of the conversation.") + ], -1)), + _cache[44] || (_cache[44] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Only one SystemMessage is allowed (ie, cannot mix two conversations different system prompts).") + ], -1)) + ]), + _cache[46] || (_cache[46] = createBaseVNode("p", null, [ + createBaseVNode("a", { + href: "https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/llm_shared.jl#L12-L32", + target: "_blank", + rel: "noreferrer" + }, "source") + ], -1)) + ]), + _cache[56] || (_cache[56] = createStaticVNode('replace_words(text::AbstractString, words::Vector{<:AbstractString}; replacement::AbstractString="ABC")Replace all occurrences of words in words with replacement in text. Useful to quickly remove specific names or entities from a text.
Arguments
text::AbstractString: The text to be processed.words::Vector{<:AbstractString}: A vector of words to be replaced.replacement::AbstractString="ABC": The replacement string to be used. Defaults to "ABC".
Example
text = "Disney is a great company"\nreplace_words(text, ["Disney", "Snow White", "Mickey Mouse"])\n# Output: "ABC is a great company"resize_conversation!(conv_history, max_history::Union{Int, Nothing})Resize the conversation history to a specified maximum length.
This function trims the conv_history to ensure that its size does not exceed max_history. It removes the oldest conversations first if the length of conv_history is greater than max_history.
Arguments
conv_history: A vector that stores the history of conversations. Typically, this isPT.CONV_HISTORY.max_history: The maximum number of conversations to retain in the history. IfNothing, the history is not resized.
Returns
The resized conversation history.
Example
resize_conversation!(PT.CONV_HISTORY, PT.MAX_HISTORY_LENGTH)After the function call, conv_history will contain only the 10 most recent conversations.
This is done automatically by the ai"" macros.
response_to_message(schema::AbstractOpenAISchema,\n MSG::Type{AIMessage},\n choice,\n resp;\n model_id::AbstractString = "",\n time::Float64 = 0.0,\n run_id::Int = Int(rand(Int32)),\n sample_id::Union{Nothing, Integer} = nothing,\n name_assistant::Union{Nothing, String} = nothing)Utility to facilitate unwrapping of HTTP response to a message type MSG provided for OpenAI-like responses
Note: Extracts finish_reason and log_prob if available in the response.
Arguments
schema::AbstractOpenAISchema: The schema for the prompt.MSG::Type{AIMessage}: The message type to be returned.choice: The choice from the response (eg, one of the completions).resp: The response from the OpenAI API.model_id::AbstractString: The model ID to use for generating the response. Defaults to an empty string.time::Float64: The elapsed time for the response. Defaults to0.0.run_id::Integer: The run ID for the response. Defaults to a random integer.sample_id::Union{Nothing, Integer}: The sample ID for the response (if there are multiple completions). Defaults tonothing.name_assistant::Union{Nothing, String}: The name to use for the assistant in the conversation history. Defaults tonothing.
Utility to facilitate unwrapping of HTTP response to a message type MSG provided. Designed to handle multi-sample completions.
save_conversation(io_or_file::Union{IO, AbstractString},\n messages::AbstractVector{<:AbstractMessage})Saves provided conversation (messages) to io_or_file. If you need to add some metadata, see save_template.
save_conversations(schema::AbstractPromptSchema, filename::AbstractString,\n conversations::Vector{<:AbstractVector{<:PT.AbstractMessage}})Saves provided conversations (vector of vectors of messages) to filename rendered in the particular schema.
Commonly used for finetuning models with schema = ShareGPTSchema()
The format is JSON Lines, where each line is a JSON object representing one provided conversation.
See also: save_conversation
Examples
You must always provide a VECTOR of conversations
messages = AbstractMessage[SystemMessage("System message 1"),\n UserMessage("User message"),\n AIMessage("AI message")]\nconversation = [messages] # vector of vectors\n\ndir = tempdir()\nfn = joinpath(dir, "conversations.jsonl")\nsave_conversations(fn, conversation)\n\n# Content of the file (one line for each conversation)\n# {"conversations":[{"value":"System message 1","from":"system"},{"value":"User message","from":"human"},{"value":"AI message","from":"gpt"}]}save_template(io_or_file::Union{IO, AbstractString},\n messages::AbstractVector{<:AbstractChatMessage};\n content::AbstractString = "Template Metadata",\n description::AbstractString = "",\n version::AbstractString = "1",\n source::AbstractString = "")Saves provided messaging template (messages) to io_or_file. Automatically adds metadata based on provided keyword arguments.
set_preferences!(pairs::Pair{String, <:Any}...)Set preferences for PromptingTools. See ?PREFERENCES for more information.
See also: get_preferences
Example
Change your API key and default model:
PromptingTools.set_preferences!("OPENAI_API_KEY" => "key1", "MODEL_CHAT" => "chat1")set_properties_strict!(properties::AbstractDict)Sets strict mode for the properties of a JSON schema.
Changes:
Sets
additionalPropertiestofalse.All keys must be included in
required.All optional keys will have
nulladded to their type.
Reference: https://platform.openai.com/docs/guides/structured-outputs/supported-schemas
', 19)), + _cache[57] || (_cache[57] = createBaseVNode("div", { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }, [ + createBaseVNode("a", { + id: "PromptingTools.tool_call_signature-Tuple{Union{Method, Type}}", + href: "#PromptingTools.tool_call_signature-Tuple{Union{Method, Type}}" + }, "#"), + createTextVNode(" "), + createBaseVNode("b", null, [ + createBaseVNode("u", null, "PromptingTools.tool_call_signature") + ]), + createTextVNode(" — "), + createBaseVNode("i", null, "Method"), + createTextVNode(". "), + createBaseVNode("div", { class: "language-julia vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }, "julia"), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "tool_call_signature"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, "(") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " type_or_method"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union{Type, Method}"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, "; strict"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union{Nothing, Bool}"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, " ="), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, " nothing"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, ",") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " max_description_length"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Int"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, " ="), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, " 200"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, ", name"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union{Nothing, String}"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, " ="), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, " nothing"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, ",") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " docs"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union{Nothing, String}"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, " ="), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, " nothing"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, ", hidden_fields"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "AbstractVector"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, "{"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "<:"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, "{") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " AbstractString, Regex}} "), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "="), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " String[])") + ]) + ]) + ]) + ]), + createBaseVNode("p", null, "Extract the argument names, types and docstrings from a struct to create the function call signature in JSON schema."), + createBaseVNode("p", null, "You must provide a Struct type (not an instance of it) with some fields. The types must be CONCRETE, it helps with correct conversion to JSON schema and then conversion back to the struct."), + createBaseVNode("p", null, "Note: Fairly experimental, but works for combination of structs, arrays, strings and singletons."), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Arguments") + ]), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "type_or_method::Union{Type, Method}"), + createTextVNode(": The struct type or method to extract the signature from.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "strict::Union{Nothing, Bool}"), + createTextVNode(": Whether to enforce strict mode for the schema. Defaults to "), + createBaseVNode("code", null, "nothing"), + createTextVNode(".") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "max_description_length::Int"), + createTextVNode(": Maximum length for descriptions. Defaults to 200.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "name::Union{Nothing, String}"), + createTextVNode(": The name of the tool. Defaults to the name of the struct.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "docs::Union{Nothing, String}"), + createTextVNode(": The description of the tool. Defaults to the docstring of the struct/overall function.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "hidden_fields::AbstractVector{<:Union{AbstractString, Regex}}"), + createTextVNode(": A list of fields to hide from the LLM (eg, "), + createBaseVNode("code", null, '["ctx_user_id"]'), + createTextVNode(" or "), + createBaseVNode("code", null, 'r"ctx"'), + createTextVNode(").") + ]) + ]) + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Returns") + ]), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("code", null, "Dict{String, AbstractTool}"), + createTextVNode(": A dictionary representing the function call signature schema.") + ]) + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Tips") + ]), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, "You can improve the quality of the extraction by writing a helpful docstring for your struct (or any nested struct). It will be provided as a description.") + ]), + createBaseVNode("p", null, "You can even include comments/descriptions about the individual fields."), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("All fields are assumed to be required, unless you allow null values (eg, "), + createBaseVNode("code", null, "::Union{Nothing, Int}"), + createTextVNode("). Fields with "), + createBaseVNode("code", null, "Nothing"), + createTextVNode(" will be treated as optional.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Missing values are ignored (eg, "), + createBaseVNode("code", null, "::Union{Missing, Int}"), + createTextVNode(" will be treated as Int). It's for broader compatibility and we cannot deserialize it as easily as "), + createBaseVNode("code", null, "Nothing"), + createTextVNode(".") + ]) + ]) + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Example") + ]), + createBaseVNode("p", null, [ + createTextVNode("Do you want to extract some specific measurements from a text like age, weight and height? You need to define the information you need as a struct ("), + createBaseVNode("code", null, "return_type"), + createTextVNode("):") + ]), + createBaseVNode("div", { class: "language- vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "struct MyMeasurement") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, " age::Int") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, " height::Union{Int,Nothing}") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, " weight::Union{Nothing,Float64}") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "end") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "tool_map = tool_call_signature(MyMeasurement)") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "#") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, '# Dict{String, PromptingTools.AbstractTool}("MyMeasurement" => PromptingTools.Tool') + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, '# name: String "MyMeasurement"') + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "# parameters: Dict{String, Any}") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "# description: Nothing nothing") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "# strict: Nothing nothing") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "# callable: MyMeasurement <: Any") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, '"') + ]) + ]) + ]) + ]), + createBaseVNode("p", null, [ + createTextVNode("You can see that only the field "), + createBaseVNode("code", null, "age"), + createTextVNode(` does not allow null values, hence, it's "required". While `), + createBaseVNode("code", null, "height"), + createTextVNode(" and "), + createBaseVNode("code", null, "weight"), + createTextVNode(" are optional.") + ]), + createBaseVNode("div", { class: "language- vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, 'tool_map["MyMeasurement"].parameters["required"]') + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, '# ["age"]') + ]) + ]) + ]) + ]), + createBaseVNode("p", null, [ + createTextVNode("If there are multiple items you want to extract, define a wrapper struct to get a Vector of "), + createBaseVNode("code", null, "MyMeasurement"), + createTextVNode(":") + ]), + createBaseVNode("div", { class: "language- vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "struct MyMeasurementWrapper") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, " measurements::Vector{MyMeasurement}") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "end") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "Or if you want your extraction to fail gracefully when data isn't found, use `MaybeExtract{T}` wrapper (inspired by Instructor package!):") + ]) + ]) + ]) + ]), + createBaseVNode("p", null, "using PromptingTools: MaybeExtract"), + createBaseVNode("p", { MyMeasurement: "" }, "type = MaybeExtract"), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Effectively the same as:") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "struct MaybeExtract{T}") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "result::Union{T, Nothing}") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "error::Bool // true if a result is found, false otherwise") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "message::Union{Nothing, String} // Only present if no result is found, should be short and concise") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "end") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, [ + createTextVNode("If LLM extraction fails, it will return a Dict with "), + createBaseVNode("code", null, "error"), + createTextVNode(" and "), + createBaseVNode("code", null, "message"), + createTextVNode(" fields instead of the result!") + ]) + ]), + createBaseVNode("p", null, 'msg = aiextract("Extract measurements from the text: I am giraffe", type)'), + createBaseVNode("hr"), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Dict{Symbol, Any} with 2 entries:") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, ':message => "Sorry, this feature is only available for humans."') + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, ":error => true") + ]), + createBaseVNode("div", { class: "language- vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "That way, you can handle the error gracefully and get a reason why extraction failed.") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, 'You can also hide certain fields in your function call signature with Strings or Regex patterns (eg, `r"ctx"`).') + ]) + ]) + ]) + ]), + createBaseVNode("p", null, 'tool_map = tool_call_signature(MyMeasurement; hidden_fields = ["ctx_user_id"]) ```'), + createBaseVNode("p", null, [ + createBaseVNode("a", { + href: "https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/extraction.jl#L463-L555", + target: "_blank", + rel: "noreferrer" + }, "source") + ]) + ], -1)), + _cache[58] || (_cache[58] = createStaticVNode('
tool_call_signature(fields::Vector;\n strict::Union{Nothing, Bool} = nothing, max_description_length::Int = 200, name::Union{\n Nothing, String} = nothing,\n docs::Union{Nothing, String} = nothing)Generate a function call signature schema for a dynamically generated struct based on the provided fields.
Arguments
fields::Vector{Union{Symbol, Pair{Symbol, Type}, Pair{Symbol, String}}}: A vector of field names or pairs of field name and type or string description, eg,[:field1, :field2, :field3]or[:field1 => String, :field2 => Int, :field3 => Float64]or[:field1 => String, :field1__description => "Field 1 has the name"].strict::Union{Nothing, Bool}: Whether to enforce strict mode for the schema. Defaults tonothing.max_description_length::Int: Maximum length for descriptions. Defaults to 200.name::Union{Nothing, String}: The name of the tool. Defaults to the name of the struct.docs::Union{Nothing, String}: The description of the tool. Defaults to the docstring of the struct/overall function.
Returns a tool_map with the tool name as the key and the tool object as the value.
See also generate_struct, aiextract, update_field_descriptions!.
Examples
tool_map = tool_call_signature([:field1, :field2, :field3])With the field types:
tool_map = tool_call_signature([:field1 => String, :field2 => Int, :field3 => Float64])And with the field descriptions:
tool_map = tool_call_signature([:field1 => String, :field1__description => "Field 1 has the name"])Get the vector of tool call requests from an AIToolRequest/message.
unique_permutation(inputs::AbstractVector)Returns indices of unique items in a vector inputs. Access the unique values as inputs[unique_permutation(inputs)].
Unwraps the tracer message or tracer-like object, returning the original object.
update_field_descriptions!(\n parameters::Dict{String, <:Any}, descriptions::Dict{Symbol, <:AbstractString};\n max_description_length::Int = 200)Update the given JSON schema with descriptions from the descriptions dictionary. This function modifies the schema in-place, adding a "description" field to each property that has a corresponding entry in the descriptions dictionary.
Note: It modifies the schema in place. Only the top-level "properties" are updated!
Returns: The modified schema dictionary.
Arguments
parameters: A dictionary representing the JSON schema to be updated.descriptions: A dictionary mapping field names (as symbols) to their descriptions.max_description_length::Int: Maximum length for descriptions. Defaults to 200.
Examples
parameters = Dict{String, Any}(\n "properties" => Dict{String, Any}(\n "location" => Dict{String, Any}("type" => "string"),\n "condition" => Dict{String, Any}("type" => "string"),\n "temperature" => Dict{String, Any}("type" => "number")\n ),\n "required" => ["location", "temperature", "condition"],\n "type" => "object"\n )\n descriptions = Dict{Symbol, String}(\n :temperature => "Temperature in degrees Fahrenheit",\n :condition => "Current weather condition (e.g., sunny, rainy, cloudy)"\n )\n update_field_descriptions!(parameters, descriptions)wrap_string(str::String,\n text_width::Int = 20;\n newline::Union{AbstractString, AbstractChar} = '')
Breaks a string into lines of a given text_width. Optionally, you can specify the newline character or string to use.
Example:
wrap_string("Certainly, here's a function in Julia that will wrap a string according to the specifications:", 10) |> printaai"user_prompt"[model_alias] -> AIMessageAsynchronous version of @ai_str macro, which will log the result once it's ready.
See also aai!"" if you want an asynchronous reply to the provided message / continue the conversation.
Example
Send asynchronous request to GPT-4, so we don't have to wait for the response: Very practical with slow models, so you can keep working in the meantime.
\n**...with some delay...**\n\n**[ Info: Tokens: 29 @ Cost: 0.0011\n in 2.7 seconds**\n\n**[ Info: AIMessage> Hello! How can I assist you today?**\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/macros.jl#L99-L116)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.@ai!_str-Tuple{Any, Vararg{Any}}' href='#PromptingTools.@ai!_str-Tuple{Any, Vararg{Any}}'>#</a> <b><u>PromptingTools.@ai!_str</u></b> — <i>Macro</i>.\n\n\n\n\n```julia\nai!"user_prompt"[model_alias] -> AIMessageThe ai!"" string macro is used to continue a previous conversation with the AI model.
It appends the new user prompt to the last conversation in the tracked history (in PromptingTools.CONV_HISTORY) and generates a response based on the entire conversation context. If you want to see the previous conversation, you can access it via PromptingTools.CONV_HISTORY, which keeps at most last PromptingTools.MAX_HISTORY_LENGTH conversations.
Arguments
user_prompt(String): The new input prompt to be added to the existing conversation.model_alias(optional, any): Specify the model alias of the AI model to be used (seeMODEL_ALIASES). If not provided, the default model is used.
Returns
AIMessage corresponding to the new user prompt, considering the entire conversation history.
Example
To continue a conversation:
# start conversation as normal\nai"Say hi." \n\n# ... wait for reply and then react to it:\n\n# continue the conversation (notice that you can change the model, eg, to more powerful one for better answer)\nai!"What do you think about that?"gpt4t\n# AIMessage("Considering our previous discussion, I think that...")Usage Notes
This macro should be used when you want to maintain the context of an ongoing conversation (ie, the last
ai""message).It automatically accesses and updates the global conversation history.
If no conversation history is found, it raises an assertion error, suggesting to initiate a new conversation using
ai""instead.
Important
Ensure that the conversation history is not too long to maintain relevancy and coherence in the AI's responses. The history length is managed by MAX_HISTORY_LENGTH.
ai"user_prompt"[model_alias] -> AIMessageThe ai"" string macro generates an AI response to a given prompt by using aigenerate under the hood.
See also ai!"" if you want to reply to the provided message / continue the conversation.
Arguments
user_prompt(String): The input prompt for the AI model.model_alias(optional, any): Provide model alias of the AI model (seeMODEL_ALIASES).
Returns
AIMessage corresponding to the input prompt.
Example
result = ai"Hello, how are you?"\n# AIMessage("Hello! I'm an AI assistant, so I don't have feelings, but I'm here to help you. How can I assist you today?")If you want to interpolate some variables or additional context, simply use string interpolation:
a=1\nresult = ai"What is `$a+$a`?"\n# AIMessage("The sum of `1+1` is `2`.")If you want to use a different model, eg, GPT-4, you can provide its alias as a flag:
result = ai"What is `1.23 * 100 + 1`?"gpt4t\n# AIMessage("The answer is 124.")@timeout(seconds, expr_to_run, expr_when_fails)Simple macro to run an expression with a timeout of seconds. If the expr_to_run fails to finish in seconds seconds, expr_when_fails is returned.
Example
x = @timeout 1 begin\n sleep(1.1)\n println("done")\n 1\nend "failed"', 19)) + ]); +} +const reference = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference as default +}; diff --git a/previews/PR252/assets/reference.md.CLMpB-fA.lean.js b/previews/PR252/assets/reference.md.CLMpB-fA.lean.js new file mode 100644 index 00000000..d8522acd --- /dev/null +++ b/previews/PR252/assets/reference.md.CLMpB-fA.lean.js @@ -0,0 +1,549 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, j as createBaseVNode, a as createTextVNode, t as toDisplayString, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference","description":"","frontmatter":{"outline":"deep"},"headers":[],"relativePath":"reference.md","filePath":"reference.md","lastUpdated":null}'); +const _sfc_main = { name: "reference.md" }; +const _hoisted_1 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +const _hoisted_2 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +const _hoisted_3 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +const _hoisted_4 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +const _hoisted_5 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +const _hoisted_6 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +const _hoisted_7 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +const _hoisted_8 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +const _hoisted_9 = { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, [ + _cache[47] || (_cache[47] = createStaticVNode('
Reference
PromptingTools.ExperimentalPromptingTools.Experimental.AgentToolsPromptingTools.Experimental.RAGToolsPromptingTools.ALLOWED_PREFERENCESPromptingTools.ALTERNATIVE_GENERATION_COSTSPromptingTools.ANTHROPIC_TOOL_PROMPTPromptingTools.BETA_HEADERS_ANTHROPICPromptingTools.CONV_HISTORYPromptingTools.MODEL_ALIASESPromptingTools.MODEL_REGISTRYPromptingTools.OPENAI_TOKEN_IDS_GPT35_GPT4PromptingTools.PREFERENCESPromptingTools.RESERVED_KWARGSPromptingTools.AICodePromptingTools.AIMessagePromptingTools.AITemplatePromptingTools.AITemplateMetadataPromptingTools.AIToolRequestPromptingTools.AbstractAnnotationMessagePromptingTools.AbstractPromptSchemaPromptingTools.AbstractToolPromptingTools.AbstractToolErrorPromptingTools.AnnotationMessagePromptingTools.AnthropicSchemaPromptingTools.AzureOpenAISchemaPromptingTools.CerebrasOpenAISchemaPromptingTools.ChatMLSchemaPromptingTools.ConversationMemoryPromptingTools.ConversationMemoryPromptingTools.CustomOpenAISchemaPromptingTools.DataMessagePromptingTools.DatabricksOpenAISchemaPromptingTools.DeepSeekOpenAISchemaPromptingTools.Experimental.AgentTools.AICallPromptingTools.Experimental.AgentTools.AICodeFixerPromptingTools.Experimental.AgentTools.RetryConfigPromptingTools.Experimental.AgentTools.SampleNodePromptingTools.Experimental.AgentTools.ThompsonSamplingPromptingTools.Experimental.AgentTools.UCTPromptingTools.Experimental.RAGTools.AbstractCandidateChunksPromptingTools.Experimental.RAGTools.AbstractChunkIndexPromptingTools.Experimental.RAGTools.AbstractGeneratorPromptingTools.Experimental.RAGTools.AbstractIndexBuilderPromptingTools.Experimental.RAGTools.AbstractMultiIndexPromptingTools.Experimental.RAGTools.AbstractRetrieverPromptingTools.Experimental.RAGTools.AdvancedGeneratorPromptingTools.Experimental.RAGTools.AdvancedRetrieverPromptingTools.Experimental.RAGTools.AllTagFilterPromptingTools.Experimental.RAGTools.AnnotatedNodePromptingTools.Experimental.RAGTools.AnyTagFilterPromptingTools.Experimental.RAGTools.BM25SimilarityPromptingTools.Experimental.RAGTools.BatchEmbedderPromptingTools.Experimental.RAGTools.BinaryBatchEmbedderPromptingTools.Experimental.RAGTools.BinaryCosineSimilarityPromptingTools.Experimental.RAGTools.BitPackedBatchEmbedderPromptingTools.Experimental.RAGTools.BitPackedCosineSimilarityPromptingTools.Experimental.RAGTools.CandidateChunksPromptingTools.Experimental.RAGTools.ChunkEmbeddingsIndexPromptingTools.Experimental.RAGTools.ChunkKeywordsIndexPromptingTools.Experimental.RAGTools.ChunkKeywordsIndexPromptingTools.Experimental.RAGTools.CohereRerankerPromptingTools.Experimental.RAGTools.ContextEnumeratorPromptingTools.Experimental.RAGTools.CosineSimilarityPromptingTools.Experimental.RAGTools.DocumentTermMatrixPromptingTools.Experimental.RAGTools.FileChunkerPromptingTools.Experimental.RAGTools.FlashRankerPromptingTools.Experimental.RAGTools.HTMLStylerPromptingTools.Experimental.RAGTools.HyDERephraserPromptingTools.Experimental.RAGTools.JudgeAllScoresPromptingTools.Experimental.RAGTools.JudgeRatingPromptingTools.Experimental.RAGTools.KeywordsIndexerPromptingTools.Experimental.RAGTools.KeywordsProcessorPromptingTools.Experimental.RAGTools.MultiCandidateChunksPromptingTools.Experimental.RAGTools.MultiFinderPromptingTools.Experimental.RAGTools.MultiIndexPromptingTools.Experimental.RAGTools.NoEmbedderPromptingTools.Experimental.RAGTools.NoPostprocessorPromptingTools.Experimental.RAGTools.NoProcessorPromptingTools.Experimental.RAGTools.NoRefinerPromptingTools.Experimental.RAGTools.NoRephraserPromptingTools.Experimental.RAGTools.NoRerankerPromptingTools.Experimental.RAGTools.NoTagFilterPromptingTools.Experimental.RAGTools.NoTaggerPromptingTools.Experimental.RAGTools.OpenTaggerPromptingTools.Experimental.RAGTools.PassthroughTaggerPromptingTools.Experimental.RAGTools.RAGConfigPromptingTools.Experimental.RAGTools.RAGResultPromptingTools.Experimental.RAGTools.RankGPTRerankerPromptingTools.Experimental.RAGTools.RankGPTResultPromptingTools.Experimental.RAGTools.SimpleAnswererPromptingTools.Experimental.RAGTools.SimpleBM25RetrieverPromptingTools.Experimental.RAGTools.SimpleGeneratorPromptingTools.Experimental.RAGTools.SimpleIndexerPromptingTools.Experimental.RAGTools.SimpleRefinerPromptingTools.Experimental.RAGTools.SimpleRephraserPromptingTools.Experimental.RAGTools.SimpleRetrieverPromptingTools.Experimental.RAGTools.StylerPromptingTools.Experimental.RAGTools.SubChunkIndexPromptingTools.Experimental.RAGTools.SubDocumentTermMatrixPromptingTools.Experimental.RAGTools.TavilySearchRefinerPromptingTools.Experimental.RAGTools.TextChunkerPromptingTools.Experimental.RAGTools.TrigramAnnotaterPromptingTools.FireworksOpenAISchemaPromptingTools.GoogleOpenAISchemaPromptingTools.GoogleSchemaPromptingTools.GroqOpenAISchemaPromptingTools.ItemsExtractPromptingTools.LocalServerOpenAISchemaPromptingTools.MaybeExtractPromptingTools.MistralOpenAISchemaPromptingTools.ModelSpecPromptingTools.NoSchemaPromptingTools.OllamaManagedSchemaPromptingTools.OllamaSchemaPromptingTools.OpenAISchemaPromptingTools.OpenRouterOpenAISchemaPromptingTools.SambaNovaOpenAISchemaPromptingTools.SaverSchemaPromptingTools.ShareGPTSchemaPromptingTools.TestEchoAnthropicSchemaPromptingTools.TestEchoGoogleSchemaPromptingTools.TestEchoOllamaManagedSchemaPromptingTools.TestEchoOllamaSchemaPromptingTools.TestEchoOpenAISchemaPromptingTools.TogetherOpenAISchemaPromptingTools.ToolPromptingTools.ToolPromptingTools.ToolExecutionErrorPromptingTools.ToolGenericErrorPromptingTools.ToolMessagePromptingTools.ToolNotFoundErrorPromptingTools.ToolRefPromptingTools.TracerMessagePromptingTools.TracerMessageLikePromptingTools.TracerSchemaPromptingTools.UserMessagePromptingTools.UserMessageWithImagesPromptingTools.UserMessageWithImagesPromptingTools.X123PromptingTools.XAIOpenAISchemaBase.append!Base.lengthBase.push!Base.showOpenAI.create_chatOpenAI.create_chatOpenAI.create_chatPromptingTools.Experimental.APITools.create_websearchPromptingTools.Experimental.APITools.tavily_apiPromptingTools.Experimental.AgentTools.AIClassifyPromptingTools.Experimental.AgentTools.AIEmbedPromptingTools.Experimental.AgentTools.AIExtractPromptingTools.Experimental.AgentTools.AIGeneratePromptingTools.Experimental.AgentTools.AIScanPromptingTools.Experimental.AgentTools.add_feedback!PromptingTools.Experimental.AgentTools.aicodefixer_feedbackPromptingTools.Experimental.AgentTools.airetry!PromptingTools.Experimental.AgentTools.backpropagate!PromptingTools.Experimental.AgentTools.beta_samplePromptingTools.Experimental.AgentTools.collect_all_feedbackPromptingTools.Experimental.AgentTools.error_feedbackPromptingTools.Experimental.AgentTools.evaluate_condition!PromptingTools.Experimental.AgentTools.expand!PromptingTools.Experimental.AgentTools.extract_configPromptingTools.Experimental.AgentTools.find_nodePromptingTools.Experimental.AgentTools.gamma_samplePromptingTools.Experimental.AgentTools.print_samplesPromptingTools.Experimental.AgentTools.remove_used_kwargsPromptingTools.Experimental.AgentTools.reset_success!PromptingTools.Experimental.AgentTools.run!PromptingTools.Experimental.AgentTools.run!PromptingTools.Experimental.AgentTools.scorePromptingTools.Experimental.AgentTools.scorePromptingTools.Experimental.AgentTools.select_bestPromptingTools.Experimental.AgentTools.split_multi_samplesPromptingTools.Experimental.AgentTools.truncate_conversationPromptingTools.Experimental.AgentTools.unwrap_aicall_argsPromptingTools.Experimental.RAGTools._normalizePromptingTools.Experimental.RAGTools.add_node_metadata!PromptingTools.Experimental.RAGTools.airagPromptingTools.Experimental.RAGTools.align_node_styles!PromptingTools.Experimental.RAGTools.annotate_supportPromptingTools.Experimental.RAGTools.annotate_supportPromptingTools.Experimental.RAGTools.answer!PromptingTools.Experimental.RAGTools.build_contextPromptingTools.Experimental.RAGTools.build_indexPromptingTools.Experimental.RAGTools.build_indexPromptingTools.Experimental.RAGTools.build_qa_evalsPromptingTools.Experimental.RAGTools.build_tagsPromptingTools.Experimental.RAGTools.build_tagsPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.cohere_apiPromptingTools.Experimental.RAGTools.create_permutation_instructionPromptingTools.Experimental.RAGTools.extract_rankingPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.generate!PromptingTools.Experimental.RAGTools.get_chunksPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.getpropertynestedPromptingTools.Experimental.RAGTools.hamming_distancePromptingTools.Experimental.RAGTools.hcat_truncatePromptingTools.Experimental.RAGTools.load_textPromptingTools.Experimental.RAGTools.merge_kwargs_nestedPromptingTools.Experimental.RAGTools.pack_bitsPromptingTools.Experimental.RAGTools.permutation_step!PromptingTools.Experimental.RAGTools.preprocess_tokensPromptingTools.Experimental.RAGTools.print_htmlPromptingTools.Experimental.RAGTools.rank_gptPromptingTools.Experimental.RAGTools.rank_sliding_window!PromptingTools.Experimental.RAGTools.receive_permutation!PromptingTools.Experimental.RAGTools.reciprocal_rank_fusionPromptingTools.Experimental.RAGTools.reciprocal_rank_fusionPromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rerankPromptingTools.Experimental.RAGTools.rerankPromptingTools.Experimental.RAGTools.retrievePromptingTools.Experimental.RAGTools.run_qa_evalsPromptingTools.Experimental.RAGTools.run_qa_evalsPromptingTools.Experimental.RAGTools.score_retrieval_hitPromptingTools.Experimental.RAGTools.score_retrieval_rankPromptingTools.Experimental.RAGTools.score_to_unit_scalePromptingTools.Experimental.RAGTools.set_node_style!PromptingTools.Experimental.RAGTools.setpropertynestedPromptingTools.Experimental.RAGTools.split_into_code_and_sentencesPromptingTools.Experimental.RAGTools.tags_extractPromptingTools.Experimental.RAGTools.token_with_boundariesPromptingTools.Experimental.RAGTools.tokenizePromptingTools.Experimental.RAGTools.translate_positions_to_parentPromptingTools.Experimental.RAGTools.translate_positions_to_parentPromptingTools.Experimental.RAGTools.trigram_support!PromptingTools.Experimental.RAGTools.trigramsPromptingTools.Experimental.RAGTools.trigrams_hashedPromptingTools.aiclassifyPromptingTools.aiclassifyPromptingTools.aiembedPromptingTools.aiembedPromptingTools.aiembedPromptingTools.aiextractPromptingTools.aiextractPromptingTools.aiextractPromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aigeneratePromptingTools.aiimagePromptingTools.aiimagePromptingTools.aiscanPromptingTools.aiscanPromptingTools.aiscanPromptingTools.aitemplatesPromptingTools.aitemplatesPromptingTools.aitemplatesPromptingTools.aitemplatesPromptingTools.aitoolsPromptingTools.aitoolsPromptingTools.aitoolsPromptingTools.align_tracer!PromptingTools.align_tracer!PromptingTools.annotate!PromptingTools.anthropic_apiPromptingTools.anthropic_extra_headersPromptingTools.auth_headerPromptingTools.batch_start_indexPromptingTools.build_template_metadataPromptingTools.call_costPromptingTools.call_cost_alternativePromptingTools.configure_callback!PromptingTools.create_templatePromptingTools.decode_choicesPromptingTools.detect_base_main_overridesPromptingTools.distance_longest_common_subsequencePromptingTools.encode_choicesPromptingTools.eval!PromptingTools.execute_toolPromptingTools.extract_code_blocksPromptingTools.extract_code_blocks_fallbackPromptingTools.extract_docstringPromptingTools.extract_function_namePromptingTools.extract_function_namesPromptingTools.extract_image_attributesPromptingTools.extract_julia_importsPromptingTools.finalize_outputsPromptingTools.finalize_tracerPromptingTools.finalize_tracerPromptingTools.find_subsequence_positionsPromptingTools.generate_structPromptingTools.get_arg_namesPromptingTools.get_arg_namesPromptingTools.get_arg_typesPromptingTools.get_arg_typesPromptingTools.get_lastPromptingTools.get_preferencesPromptingTools.ggi_generate_contentPromptingTools.has_julia_promptPromptingTools.initialize_tracerPromptingTools.is_concrete_typePromptingTools.isextractedPromptingTools.last_messagePromptingTools.last_messagePromptingTools.last_messagePromptingTools.last_messagePromptingTools.last_outputPromptingTools.last_outputPromptingTools.last_outputPromptingTools.last_outputPromptingTools.length_longest_common_subsequencePromptingTools.list_aliasesPromptingTools.list_registryPromptingTools.load_api_keys!PromptingTools.load_conversationPromptingTools.load_templatePromptingTools.load_templates!PromptingTools.metaPromptingTools.ollama_apiPromptingTools.parse_toolPromptingTools.pprintPromptingTools.pprintPromptingTools.pprintPromptingTools.pprintPromptingTools.pprintPromptingTools.previewPromptingTools.push_conversation!PromptingTools.recursive_splitterPromptingTools.recursive_splitterPromptingTools.register_model!PromptingTools.remove_field!PromptingTools.remove_julia_promptPromptingTools.remove_templates!PromptingTools.remove_unsafe_linesPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.renderPromptingTools.replace_wordsPromptingTools.resize_conversation!PromptingTools.response_to_messagePromptingTools.response_to_messagePromptingTools.save_conversationPromptingTools.save_conversationsPromptingTools.save_templatePromptingTools.set_preferences!PromptingTools.set_properties_strict!PromptingTools.tool_call_signaturePromptingTools.tool_call_signaturePromptingTools.tool_callsPromptingTools.unique_permutationPromptingTools.unwrapPromptingTools.update_field_descriptions!PromptingTools.wrap_stringPromptingTools.@aai_strPromptingTools.@ai!_strPromptingTools.@ai_strPromptingTools.@timeout
Keys that are allowed to be set via set_preferences!
ALTERNATIVE_GENERATION_COSTSTracker of alternative costing models, eg, for image generation (dall-e-3), the cost is driven by quality/size.
Simple template to add to the System Message when doing data extraction with Anthropic models.
It has 2 placeholders: tool_name, tool_description and tool_parameters that are filled with the tool's name, description and parameters. Source: https://docs.anthropic.com/claude/docs/functions-external-tools
BETA_HEADERS_ANTHROPICA vector of symbols representing the beta features to be used.
Allowed:
:tools: Enables tools in the conversation.:cache: Enables prompt caching.:long_output: Enables long outputs (up to 8K tokens) with Anthropic's Sonnet 3.5.:computer_use: Enables the use of the computer tool.
CONV_HISTORYTracks the most recent conversations through the ai_str macros.
Preference available: MAX_HISTORY_LENGTH, which sets how many last messages should be remembered.
See also: push_conversation!, resize_conversation!
MODEL_ALIASESA dictionary of model aliases. Aliases are used to refer to models by their aliases instead of their full names to make it more convenient to use them.
Accessing the aliases
PromptingTools.MODEL_ALIASES["gpt3"]Register a new model alias
PromptingTools.MODEL_ALIASES["gpt3"] = "gpt-3.5-turbo"MODEL_REGISTRYA store of available model names and their specs (ie, name, costs per token, etc.)
Accessing the registry
You can use both the alias name or the full name to access the model spec:
PromptingTools.MODEL_REGISTRY["gpt-3.5-turbo"]Registering a new model
register_model!(\n name = "gpt-3.5-turbo",\n schema = :OpenAISchema,\n cost_of_token_prompt = 0.0015,\n cost_of_token_generation = 0.002,\n description = "GPT-3.5 Turbo is a 175B parameter model and a common default on the OpenAI API.")Registering a model alias
PromptingTools.MODEL_ALIASES["gpt3"] = "gpt-3.5-turbo"Token IDs for GPT3.5 and GPT4 from https://platform.openai.com/tokenizer
PREFERENCESYou can set preferences for PromptingTools by setting environment variables or by using the set_preferences!. It will create a LocalPreferences.toml file in your current directory and will reload your prefences from there.
Check your preferences by calling get_preferences(key::String).
Available Preferences (for set_preferences!)
OPENAI_API_KEY: The API key for the OpenAI API. See OpenAI's documentation for more information.AZURE_OPENAI_API_KEY: The API key for the Azure OpenAI API. See Azure OpenAI's documentation for more information.AZURE_OPENAI_HOST: The host for the Azure OpenAI API. See Azure OpenAI's documentation for more information.MISTRAL_API_KEY: The API key for the Mistral AI API. See Mistral AI's documentation for more information.COHERE_API_KEY: The API key for the Cohere API. See Cohere's documentation for more information.DATABRICKS_API_KEY: The API key for the Databricks Foundation Model API. See Databricks' documentation for more information.DATABRICKS_HOST: The host for the Databricks API. See Databricks' documentation for more information.TAVILY_API_KEY: The API key for the Tavily Search API. Register here. See more information here.GOOGLE_API_KEY: The API key for Google Gemini models. Get yours from here. If you see a documentation page ("Available languages and regions for Google AI Studio and Gemini API"), it means that it's not yet available in your region.ANTHROPIC_API_KEY: The API key for the Anthropic API. Get yours from here.VOYAGE_API_KEY: The API key for the Voyage API. Free tier is upto 50M tokens! Get yours from here.GROQ_API_KEY: The API key for the Groq API. Free in beta! Get yours from here.DEEPSEEK_API_KEY: The API key for the DeepSeek API. Get 5 credit when you join. Get yours from here.OPENROUTER_API_KEY: The API key for the OpenRouter API. Get yours from here.CEREBRAS_API_KEY: The API key for the Cerebras API. Get yours from here.SAMBANOVA_API_KEY: The API key for the Sambanova API. Get yours from here.XAI_API_KEY: The API key for the XAI API. Get your key from here.MODEL_CHAT: The default model to use for aigenerate and most ai* calls. SeeMODEL_REGISTRYfor a list of available models or define your own.MODEL_EMBEDDING: The default model to use for aiembed (embedding documents). SeeMODEL_REGISTRYfor a list of available models or define your own.PROMPT_SCHEMA: The default prompt schema to use for aigenerate and most ai* calls (if not specified inMODEL_REGISTRY). Set as a string, eg,"OpenAISchema". SeePROMPT_SCHEMAfor more information.MODEL_ALIASES: A dictionary of model aliases (alias => full_model_name). Aliases are used to refer to models by their aliases instead of their full names to make it more convenient to use them. SeeMODEL_ALIASESfor more information.MAX_HISTORY_LENGTH: The maximum length of the conversation history. Defaults to 5. Set tonothingto disable history. SeeCONV_HISTORYfor more information.LOCAL_SERVER: The URL of the local server to use forai*calls. Defaults tohttp://localhost:10897/v1. This server is called when you callmodel="local"See?LocalServerOpenAISchemafor more information and examples.LOG_DIR: The directory to save the logs to, eg, when usingSaverSchema <: AbstractTracerSchema. Defaults tojoinpath(pwd(), "log"). Refer to?SaverSchemafor more information on how it works and examples.
At the moment it is not possible to persist changes to MODEL_REGISTRY across sessions. Define your register_model!() calls in your startup.jl file to make them available across sessions or put them at the top of your script.
Available ENV Variables
OPENAI_API_KEY: The API key for the OpenAI API.AZURE_OPENAI_API_KEY: The API key for the Azure OpenAI API.AZURE_OPENAI_HOST: The host for the Azure OpenAI API. This is the URL built ashttps://<resource-name>.openai.azure.com.MISTRAL_API_KEY: The API key for the Mistral AI API.COHERE_API_KEY: The API key for the Cohere API.LOCAL_SERVER: The URL of the local server to use forai*calls. Defaults tohttp://localhost:10897/v1. This server is called when you callmodel="local"DATABRICKS_API_KEY: The API key for the Databricks Foundation Model API.DATABRICKS_HOST: The host for the Databricks API.TAVILY_API_KEY: The API key for the Tavily Search API. Register here. See more information here.GOOGLE_API_KEY: The API key for Google Gemini models. Get yours from here. If you see a documentation page ("Available languages and regions for Google AI Studio and Gemini API"), it means that it's not yet available in your region.ANTHROPIC_API_KEY: The API key for the Anthropic API. Get yours from here.VOYAGE_API_KEY: The API key for the Voyage API. Free tier is upto 50M tokens! Get yours from here.GROQ_API_KEY: The API key for the Groq API. Free in beta! Get yours from here.DEEPSEEK_API_KEY: The API key for the DeepSeek API. Get 5 credit when you join. Get yours from here.OPENROUTER_API_KEY: The API key for the OpenRouter API. Get yours from here.CEREBRAS_API_KEY: The API key for the Cerebras API.SAMBANOVA_API_KEY: The API key for the Sambanova API.LOG_DIR: The directory to save the logs to, eg, when usingSaverSchema <: AbstractTracerSchema. Defaults tojoinpath(pwd(), "log"). Refer to?SaverSchemafor more information on how it works and examples.XAI_API_KEY: The API key for the XAI API. Get your key from here.
Preferences.jl takes priority over ENV variables, so if you set a preference, it will take precedence over the ENV variable.
WARNING: NEVER EVER sync your LocalPreferences.toml file! It contains your API key and other sensitive information!!!
The following keywords are reserved for internal use in the ai* functions and cannot be used as placeholders in the Messages
AICode(code::AbstractString; auto_eval::Bool=true, safe_eval::Bool=false, \nskip_unsafe::Bool=false, capture_stdout::Bool=true, verbose::Bool=false,\nprefix::AbstractString="", suffix::AbstractString="", remove_tests::Bool=false, execution_timeout::Int = 60)\n\nAICode(msg::AIMessage; auto_eval::Bool=true, safe_eval::Bool=false, \nskip_unsafe::Bool=false, skip_invalid::Bool=false, capture_stdout::Bool=true,\nverbose::Bool=false, prefix::AbstractString="", suffix::AbstractString="", remove_tests::Bool=false, execution_timeout::Int = 60)A mutable structure representing a code block (received from the AI model) with automatic parsing, execution, and output/error capturing capabilities.
Upon instantiation with a string, the AICode object automatically runs a code parser and executor (via PromptingTools.eval!()), capturing any standard output (stdout) or errors. This structure is useful for programmatically handling and evaluating Julia code snippets.
See also: PromptingTools.extract_code_blocks, PromptingTools.eval!
Workflow
Until
cb::AICodehas been evaluated,cb.successis set tonothing(and so are all other fields).The text in
cb.codeis parsed (saved tocb.expression).The parsed expression is evaluated.
Outputs of the evaluated expression are captured in
cb.output.Any
stdoutoutputs (e.g., fromprintln) are captured incb.stdout.If an error occurs during evaluation, it is saved in
cb.error.After successful evaluation without errors,
cb.successis set totrue. Otherwise, it is set tofalseand you can inspect thecb.errorto understand why.
Properties
code::AbstractString: The raw string of the code to be parsed and executed.expression: The parsed Julia expression (set after parsingcode).stdout: Captured standard output from the execution of the code.output: The result of evaluating the code block.success::Union{Nothing, Bool}: Indicates whether the code block executed successfully (true), unsuccessfully (false), or has yet to be evaluated (nothing).error::Union{Nothing, Exception}: Any exception raised during the execution of the code block.
Keyword Arguments
auto_eval::Bool: If set totrue, the code block is automatically parsed and evaluated upon instantiation. Defaults totrue.safe_eval::Bool: If set totrue, the code block checks for package operations (e.g., installing new packages) and missing imports, and then evaluates the code inside a bespoke scratch module. This is to ensure that the evaluation does not alter any user-defined variables or the global state. Defaults tofalse.skip_unsafe::Bool: If set totrue, we skip any lines in the code block that are deemed unsafe (eg,Pkgoperations). Defaults tofalse.skip_invalid::Bool: If set totrue, we skip code blocks that do not even parse. Defaults tofalse.verbose::Bool: If set totrue, we print out any lines that are skipped due to being unsafe. Defaults tofalse.capture_stdout::Bool: If set totrue, we capture any stdout outputs (eg, test failures) incb.stdout. Defaults totrue.prefix::AbstractString: A string to be prepended to the code block before parsing and evaluation. Useful to add some additional code definition or necessary imports. Defaults to an empty string.suffix::AbstractString: A string to be appended to the code block before parsing and evaluation. Useful to check that tests pass or that an example executes. Defaults to an empty string.remove_tests::Bool: If set totrue, we remove any@testor@testsetmacros from the code block before parsing and evaluation. Defaults tofalse.execution_timeout::Int: The maximum time (in seconds) allowed for the code block to execute. Defaults to 60 seconds.
Methods
Base.isvalid(cb::AICode): Check if the code block has executed successfully. Returnstrueifcb.success == true.
Examples
code = AICode("println("Hello, World!")") # Auto-parses and evaluates the code, capturing output and errors.\nisvalid(code) # Output: true\ncode.stdout # Output: "Hello, World!\n"We try to evaluate "safely" by default (eg, inside a custom module, to avoid changing user variables). You can avoid that with save_eval=false:
code = AICode("new_variable = 1"; safe_eval=false)\nisvalid(code) # Output: true\nnew_variable # Output: 1You can also call AICode directly on an AIMessage, which will extract the Julia code blocks, concatenate them and evaluate them:
msg = aigenerate("In Julia, how do you create a vector of 10 random numbers?")\ncode = AICode(msg)\n# Output: AICode(Success: True, Parsed: True, Evaluated: True, Error Caught: N/A, StdOut: True, Code: 2 Lines)\n\n# show the code\ncode.code |> println\n# Output: \n# numbers = rand(10)\n# numbers = rand(1:100, 10)\n\n# or copy it to the clipboard\ncode.code |> clipboard\n\n# or execute it in the current module (=Main)\neval(code.expression)AIMessageA message type for AI-generated text-based responses. Returned by aigenerate, aiclassify, and aiscan functions.
Fields
content::Union{AbstractString, Nothing}: The content of the message.status::Union{Int, Nothing}: The status of the message from the API.name::Union{Nothing, String}: The name of therolein the conversation.tokens::Tuple{Int, Int}: The number of tokens used (prompt,completion).elapsed::Float64: The time taken to generate the response in seconds.cost::Union{Nothing, Float64}: The cost of the API call (calculated with information fromMODEL_REGISTRY).log_prob::Union{Nothing, Float64}: The log probability of the response.extras::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the key message fields. Try to limit to a small number of items and singletons to be serializable.finish_reason::Union{Nothing, String}: The reason the response was finished.run_id::Union{Nothing, Int}: The unique ID of the run.sample_id::Union{Nothing, Int}: The unique ID of the sample (if multiple samples are generated, they will all have the samerun_id).
AITemplateAITemplate is a template for a conversation prompt. This type is merely a container for the template name, which is resolved into a set of messages (=prompt) by render.
Naming Convention
Template names should be in CamelCase
Follow the format
<Persona>...<Variable>...where possible, eg,JudgeIsItTrue, ``Starting with the Persona (=System prompt), eg,
Judge= persona is meant tojudgesome provided informationVariable to be filled in with context, eg,
It= placeholderitEnding with the variable name is helpful, eg,
JuliaExpertTaskfor a persona to be an expert in Julia language andtaskis the placeholder name
Ideally, the template name should be self-explanatory, eg,
JudgeIsItTrue= persona is meant tojudgesome provided information where it is true or false
Examples
Save time by re-using pre-made templates, just fill in the placeholders with the keyword arguments:
msg = aigenerate(:JuliaExpertAsk; ask = "How do I add packages?")The above is equivalent to a more verbose version that explicitly uses the dispatch on AITemplate:
msg = aigenerate(AITemplate(:JuliaExpertAsk); ask = "How do I add packages?")Find available templates with aitemplates:
tmps = aitemplates("JuliaExpertAsk")\n# Will surface one specific template\n# 1-element Vector{AITemplateMetadata}:\n# PromptingTools.AITemplateMetadata\n# name: Symbol JuliaExpertAsk\n# description: String "For asking questions about Julia language. Placeholders: `ask`"\n# version: String "1"\n# wordcount: Int64 237\n# variables: Array{Symbol}((1,))\n# system_preview: String "You are a world-class Julia language programmer with the knowledge of the latest syntax. Your commun"\n# user_preview: String "# Question\n\n{{ask}}"\n# source: String ""The above gives you a good idea of what the template is about, what placeholders are available, and how much it would cost to use it (=wordcount).
Search for all Julia-related templates:
tmps = aitemplates("Julia")\n# 2-element Vector{AITemplateMetadata}... -> more to come later!If you are on VSCode, you can leverage nice tabular display with vscodedisplay:
using DataFrames\ntmps = aitemplates("Julia") |> DataFrame |> vscodedisplayI have my selected template, how do I use it? Just use the "name" in aigenerate or aiclassify like you see in the first example!
You can inspect any template by "rendering" it (this is what the LLM will see):
julia> AITemplate(:JudgeIsItTrue) |> PromptingTools.renderSee also: save_template, load_template, load_templates! for more advanced use cases (and the corresponding script in examples/ folder)
Helper for easy searching and reviewing of templates. Defined on loading of each template.
AIToolRequestA message type for AI-generated tool requests. Returned by aitools functions.
Fields
content::Union{AbstractString, Nothing}: The content of the message.tool_calls::Vector{ToolMessage}: The vector of tool call requests.name::Union{Nothing, String}: The name of therolein the conversation.status::Union{Int, Nothing}: The status of the message from the API.tokens::Tuple{Int, Int}: The number of tokens used (prompt,completion).elapsed::Float64: The time taken to generate the response in seconds.cost::Union{Nothing, Float64}: The cost of the API call (calculated with information fromMODEL_REGISTRY).log_prob::Union{Nothing, Float64}: The log probability of the response.extras::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the key message fields. Try to limit to a small number of items and singletons to be serializable.finish_reason::Union{Nothing, String}: The reason the response was finished.run_id::Union{Nothing, Int}: The unique ID of the run.sample_id::Union{Nothing, Int}: The unique ID of the sample (if multiple samples are generated, they will all have the samerun_id).
See ToolMessage for the fields of the tool call requests.
See also: tool_calls, execute_tool, parse_tool
AbstractAnnotationMessageMessages that provide extra information without being sent to LLMs.
Required fields: content, tags, comment, run_id.
Note: comment is intended for human readers only and should never be used. run_id should be a unique identifier for the annotation, typically a random number.
Defines different prompting styles based on the model training and fine-tuning.
AbstractToolAbstract type for all tool types.
Required fields:
name::String: The name of the tool.parameters::Dict: The parameters of the tool.description::Union{String, Nothing}: The description of the tool.callable::Any: The callable object of the tool, eg, a type or a function.
AbstractToolErrorAbstract type for all tool errors.
Available subtypes:
AnnotationMessageA message type for providing extra information in the conversation history without being sent to LLMs. These messages are filtered out during rendering to ensure they don't affect the LLM's context.
Used to bundle key information and documentation for colleagues and future reference together with the data.
Fields
content::T: The content of the annotation (can be used for inputs to airag etc.)extras::Dict{Symbol,Any}: Additional metadata with symbol keys and any valuestags::Vector{Symbol}: Vector of tags for categorization (default: empty)comment::String: Human-readable comment, never used for automatic operations (default: empty)run_id::Union{Nothing,Int}: The unique ID of the annotation
Note: The comment field is intended for human readers only and should never be used for automatic operations.
', 42)), + createBaseVNode("div", _hoisted_1, [ + _cache[4] || (_cache[4] = createStaticVNode('# PromptingTools.AnthropicSchema — Type.
AnthropicSchema <: AbstractAnthropicSchemaAnthropicSchema is the default schema for Anthropic API models (eg, Claude). See more information here.
It uses the following conversation template:
Dict(role="user",content="..."),Dict(role="assistant",content="...")]system messages are provided as a keyword argument to the API call.
AzureOpenAISchema
AzureOpenAISchema() allows user to call Azure OpenAI API. API Reference
Requires two environment variables to be set:
AZURE_OPENAI_API_KEY: Azure tokenAZURE_OPENAI_HOST: Address of the Azure resource ("https://<resource>.openai.azure.com")
CerebrasOpenAISchemaSchema to call the Cerebras API.
Links:
Requires one environment variable to be set:
CEREBRAS_API_KEY: Your API key
ChatMLSchema is used by many open-source chatbots, by OpenAI models (under the hood) and by several models and inferfaces (eg, Ollama, vLLM)
You can explore it on tiktokenizer
It uses the following conversation structure:
<im_start>system\n...<im_end>\n<|im_start|>user\n...<|im_end|>\n<|im_start|>assistant\n...<|im_end|>ConversationMemoryA structured container for managing conversation history. It has only one field :conversation which is a vector of AbstractMessages. It's built to support intelligent truncation and caching behavior (get_last).
You can also use it as a functor to have extended conversations (easier than constantly passing conversation kwarg)
Examples
Basic usage
mem = ConversationMemory()\npush!(mem, SystemMessage("You are a helpful assistant"))\npush!(mem, UserMessage("Hello!"))\npush!(mem, AIMessage("Hi there!"))\n\n# or simply\nmem = ConversationMemory(conv)Check memory stats
println(mem) # ConversationMemory(2 messages) - doesn't count system message\n@show length(mem) # 3 - counts all messages\n@show last_message(mem) # gets last message\n@show last_output(mem) # gets last contentGet recent messages with different options (System message, User message, ... + the most recent)
recent = get_last(mem, 5) # get last 5 messages (including system)\nrecent = get_last(mem, 20, batch_size=10) # align to batches of 10 for caching\nrecent = get_last(mem, 5, explain=true) # adds truncation explanation\nrecent = get_last(mem, 5, verbose=true) # prints truncation infoAppend multiple messages at once (with deduplication to keep the memory complete)
msgs = [\n UserMessage("How are you?"),\n AIMessage("I'm good!"; run_id=1),\n UserMessage("Great!"),\n AIMessage("Indeed!"; run_id=2)\n]\nappend!(mem, msgs) # Will only append new messages based on run_ids etc.Use for AI conversations (easier to manage conversations)
response = mem("Tell me a joke"; model="gpt4o") # Automatically manages context\nresponse = mem("Another one"; last=3, model="gpt4o") # Use only last 3 messages (uses `get_last`)\n\n# Direct generation from the memory\nresult = aigenerate(mem) # Generate using full context(mem::ConversationMemory)(prompt::AbstractString; last::Union{Nothing,Integer}=nothing, kwargs...)Functor interface for direct generation using the conversation memory. Optionally, specify the number of last messages to include in the context (uses get_last).
CustomOpenAISchemaCustomOpenAISchema() allows user to call any OpenAI-compatible API.
All user needs to do is to pass this schema as the first argument and provide the BASE URL of the API to call (api_kwargs.url).
Example
Assumes that we have a local server running at http://127.0.0.1:8081:
api_key = "..."\nprompt = "Say hi!"\nmsg = aigenerate(CustomOpenAISchema(), prompt; model="my_model", api_key, api_kwargs=(; url="http://127.0.0.1:8081"))DataMessageA message type for AI-generated data-based responses, ie, different content than text. Returned by aiextract, and aiextract functions.
Fields
content::Union{AbstractString, Nothing}: The content of the message.status::Union{Int, Nothing}: The status of the message from the API.tokens::Tuple{Int, Int}: The number of tokens used (prompt,completion).elapsed::Float64: The time taken to generate the response in seconds.cost::Union{Nothing, Float64}: The cost of the API call (calculated with information fromMODEL_REGISTRY).log_prob::Union{Nothing, Float64}: The log probability of the response.extras::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the key message fields. Try to limit to a small number of items and singletons to be serializable.finish_reason::Union{Nothing, String}: The reason the response was finished.run_id::Union{Nothing, Int}: The unique ID of the run.sample_id::Union{Nothing, Int}: The unique ID of the sample (if multiple samples are generated, they will all have the samerun_id).
DatabricksOpenAISchemaDatabricksOpenAISchema() allows user to call Databricks Foundation Model API. API Reference
Requires two environment variables to be set:
DATABRICKS_API_KEY: Databricks tokenDATABRICKS_HOST: Address of the Databricks workspace (https://<workspace_host>.databricks.com)
DeepSeekOpenAISchemaSchema to call the DeepSeek API.
Links:
Requires one environment variables to be set:
DEEPSEEK_API_KEY: Your API key (often starts with "sk-...")
FireworksOpenAISchemaSchema to call the Fireworks.ai API.
Links:
Requires one environment variables to be set:
FIREWORKS_API_KEY: Your API key
GoogleOpenAISchemaSchema to call the Google's Gemini API using OpenAI compatibility mode. API Reference
Links:
Requires one environment variable to be set:
GOOGLE_API_KEY: Your API key
The base URL for the API is "https://generativelanguage.googleapis.com/v1beta"
Warning: Token counting and cost counting have not yet been implemented by Google, so you'll not have any such metrics. If you need it, use the native GoogleSchema with the GoogleGenAI.jl library.
Calls Google's Gemini API. See more information here. It's available only for some regions.
GroqOpenAISchemaSchema to call the groq.com API.
Links:
Requires one environment variables to be set:
GROQ_API_KEY: Your API key (often starts with "gsk_...")
Extract zero, one or more specified items from the provided data.
LocalServerOpenAISchemaDesigned to be used with local servers. It's automatically called with model alias "local" (see MODEL_REGISTRY).
This schema is a flavor of CustomOpenAISchema with a url keypreset by global Preference keyLOCAL_SERVER. See?PREFERENCESfor more details on how to change it. It assumes that the server follows OpenAI API conventions (eg,POST /v1/chat/completions`).
Note: Llama.cpp (and hence Llama.jl built on top of it) do NOT support embeddings endpoint! You'll get an address error.
Example
Assumes that we have a local server running at http://127.0.0.1:10897/v1 (port and address used by Llama.jl, "v1" at the end is needed for OpenAI endpoint compatibility):
Three ways to call it:
\n# Use @ai_str with "local" alias\nai"Say hi!"local\n\n# model="local"\naigenerate("Say hi!"; model="local")\n\n# Or set schema explicitly\nconst PT = PromptingTools\nmsg = aigenerate(PT.LocalServerOpenAISchema(), "Say hi!")How to start a LLM local server? You can use run_server function from Llama.jl. Use a separate Julia session.
using Llama\nmodel = "...path..." # see Llama.jl README how to download one\nrun_server(; model)To change the default port and address:
# For a permanent change, set the preference:\nusing Preferences\nset_preferences!("LOCAL_SERVER"=>"http://127.0.0.1:10897/v1")\n\n# Or if it's a temporary fix, just change the variable `LOCAL_SERVER`:\nconst PT = PromptingTools\nPT.LOCAL_SERVER = "http://127.0.0.1:10897/v1"Extract a result from the provided data, if any, otherwise set the error and message fields.
Arguments
error::Bool:trueif a result is found,falseotherwise.message::String: Only present if no result is found, should be short and concise.
MistralOpenAISchemaMistralOpenAISchema() allows user to call MistralAI API known for mistral and mixtral models.
It's a flavor of CustomOpenAISchema() with a url preset to https://api.mistral.ai.
Most models have been registered, so you don't even have to specify the schema
Example
Let's call mistral-tiny model:
api_key = "..." # can be set via ENV["MISTRAL_API_KEY"] or via our preference system\nmsg = aigenerate("Say hi!"; model="mistral_tiny", api_key)See ?PREFERENCES for more details on how to set your API key permanently.
ModelSpecA struct that contains information about a model, such as its name, schema, cost per token, etc.
Fields
name::String: The name of the model. This is the name that will be used to refer to the model in theai*functions.schema::AbstractPromptSchema: The schema of the model. This is the schema that will be used to generate prompts for the model, eg,:OpenAISchema.cost_of_token_prompt::Float64: The cost of 1 token in the prompt for this model. This is used to calculate the cost of a prompt. Note: It is often provided online as cost per 1000 tokens, so make sure to convert it correctly!cost_of_token_generation::Float64: The cost of 1 token generated by this model. This is used to calculate the cost of a generation. Note: It is often provided online as cost per 1000 tokens, so make sure to convert it correctly!description::String: A description of the model. This is used to provide more information about the model when it is queried.
Example
spec = ModelSpec("gpt-3.5-turbo",\n OpenAISchema(),\n 0.0015,\n 0.002,\n "GPT-3.5 Turbo is a 175B parameter model and a common default on the OpenAI API.")\n\n# register it\nPromptingTools.register_model!(spec)But you can also register any model directly via keyword arguments:
PromptingTools.register_model!(\n name = "gpt-3.5-turbo",\n schema = OpenAISchema(),\n cost_of_token_prompt = 0.0015,\n cost_of_token_generation = 0.002,\n description = "GPT-3.5 Turbo is a 175B parameter model and a common default on the OpenAI API.")Schema that keeps messages (<:AbstractMessage) and does not transform for any specific model. It used by the first pass of the prompt rendering system (see ?render).
Ollama by default manages different models and their associated prompt schemas when you pass system_prompt and prompt fields to the API.
Warning: It works only for 1 system message and 1 user message, so anything more than that has to be rejected.
If you need to pass more messagese / longer conversational history, you can use define the model-specific schema directly and pass your Ollama requests with raw=true, which disables and templating and schema management by Ollama.
OllamaSchema is the default schema for Olama models.
It uses the following conversation template:
[Dict(role="system",content="..."),Dict(role="user",content="..."),Dict(role="assistant",content="...")]It's very similar to OpenAISchema, but it appends images differently.
OpenAISchema is the default schema for OpenAI models.
It uses the following conversation template:
[Dict(role="system",content="..."),Dict(role="user",content="..."),Dict(role="assistant",content="...")]It's recommended to separate sections in your prompt with markdown headers (e.g. `##Answer
`).
OpenRouterOpenAISchemaSchema to call the OpenRouter API.
Links:
Requires one environment variable to be set:
OPENROUTER_API_KEY: Your API key
SambaNovaOpenAISchemaSchema to call the SambaNova API.
Links:
Requires one environment variable to be set:
SAMBANOVA_API_KEY: Your API key
SaverSchema <: AbstractTracerSchemaSaverSchema is a schema that automatically saves the conversation to the disk. It's useful for debugging and for persistent logging.
It can be composed with any other schema, eg, TracerSchema to save additional metadata.
Set environment variable LOG_DIR to the directory where you want to save the conversation (see ?PREFERENCES). Conversations are named by the hash of the first message in the conversation to naturally group subsequent conversations together.
If you need to provide logging directory of the file name dynamically, you can provide the following arguments to tracer_kwargs:
log_dir- used as the directory to save the log into when provided. Defaults toLOG_DIRif not provided.log_file_path- used as the file name to save the log into when provided. This value overrules thelog_dirandLOG_DIRif provided.
To use it automatically, re-register the models you use with the schema wrapped in SaverSchema
See also: meta, unwrap, TracerSchema, initialize_tracer, finalize_tracer
Example
using PromptingTools: TracerSchema, OpenAISchema, SaverSchema\n# This schema will first trace the metadata (change to TraceMessage) and then save the conversation to the disk\n\nwrap_schema = OpenAISchema() |> TracerSchema |> SaverSchema\nconv = aigenerate(wrap_schema,:BlankSystemUser; system="You're a French-speaking assistant!",\n user="Say hi!", model="gpt-4", api_kwargs=(;temperature=0.1), return_all=true)\n\n# conv is a vector of messages that will be saved to a JSON together with metadata about the template and api_kwargsIf you wanted to enable this automatically for models you use, you can do it like this:
PT.register_model!(; name= "gpt-3.5-turbo", schema=OpenAISchema() |> TracerSchema |> SaverSchema)Any subsequent calls model="gpt-3.5-turbo" will automatically capture metadata and save the conversation to the disk.
To provide logging file path explicitly, use the tracer_kwargs:
conv = aigenerate(wrap_schema,:BlankSystemUser; system="You're a French-speaking assistant!",\n user="Say hi!", model="gpt-4", api_kwargs=(;temperature=0.1), return_all=true,\n tracer_kwargs=(; log_file_path="my_logs/my_log.json"))ShareGPTSchema <: AbstractShareGPTSchemaFrequently used schema for finetuning LLMs. Conversations are recorded as a vector of dicts with keys from and value (similar to OpenAI).
Echoes the user's input back to them. Used for testing the implementation
Echoes the user's input back to them. Used for testing the implementation
Echoes the user's input back to them. Used for testing the implementation
Echoes the user's input back to them. Used for testing the implementation
Echoes the user's input back to them. Used for testing the implementation
TogetherOpenAISchemaSchema to call the Together.ai API.
Links:
Requires one environment variables to be set:
TOGETHER_API_KEY: Your API key
ToolA tool that can be sent to an LLM for execution ("function calling").
Arguments
name::String: The name of the tool.parameters::Dict: The parameters of the tool.description::Union{String, Nothing}: The description of the tool.strict::Union{Bool, Nothing}: Whether to enforce strict mode for the tool.callable::Any: The callable object of the tool, eg, a type or a function.
See also: AbstractTool, tool_call_signature
Tool(callable::Union{Function, Type, Method}; kwargs...)Create a Tool from a callable object (function, type, or method).
Arguments
callable::Union{Function, Type, Method}: The callable object to convert to a tool.
Returns
Tool: A tool object that can be used for function calling.
Examples
# Create a tool from a function\ntool = Tool(my_function)\n\n# Create a tool from a type\ntool = Tool(MyStruct)Error type for when a tool execution fails. It should contain the error message from the tool execution.
Error type for when a tool execution fails with a generic error. It should contain the detailed error message.
ToolMessageA message type for tool calls.
It represents both the request (fields args, name) and the response (field content).
Fields
content::Any: The content of the message.req_id::Union{Nothing, Int}: The unique ID of the request.tool_call_id::String: The unique ID of the tool call.raw::AbstractString: The raw JSON string of the tool call request.args::Union{Nothing, Dict{Symbol, Any}}: The arguments of the tool call request.name::Union{Nothing, String}: The name of the tool call request.
Error type for when a tool is not found. It should contain the tool name that was not found.
ToolRef(ref::Symbol, callable::Any)Represents a reference to a tool with a symbolic name and a callable object (to call during tool execution). It can be rendered with a render method and a prompt schema.
Arguments
ref::Symbol: The symbolic name of the tool.callable::Any: The callable object of the tool, eg, a type or a function.extras::Dict{String, Any}: Additional parameters to be included in the tool signature.
Examples
# Define a tool with a symbolic name and a callable object\ntool = ToolRef(;ref=:computer, callable=println)\n\n# Show the rendered tool signature\nPT.render(PT.AnthropicSchema(), tool)TracerMessage{T <: Union{AbstractChatMessage, AbstractDataMessage}} <: AbstractTracerMessageA mutable wrapper message designed for tracing the flow of messages through the system, allowing for iterative updates and providing additional metadata for observability.
Fields
object::T: The original message being traced, which can be either a chat or data message.from::Union{Nothing, Symbol}: The identifier of the sender of the message.to::Union{Nothing, Symbol}: The identifier of the intended recipient of the message.viewers::Vector{Symbol}: A list of identifiers for entities that have access to view the message, in addition to the sender and recipient.time_received::DateTime: The timestamp when the message was received by the tracing system.time_sent::Union{Nothing, DateTime}: The timestamp when the message was originally sent, if available.model::String: The name of the model that generated the message. Defaults to empty.parent_id::Symbol: An identifier for the job or process that the message is associated with. Higher-level tracing ID.thread_id::Symbol: An identifier for the thread (series of messages for one model/agent) or execution context within the job where the message originated. It should be the same for messages in the same thread.meta::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the message itself. Try to limit to a small number of items and singletons to be serializable._type::Symbol: A fixed symbol identifying the type of the message as:eventmessage, used for type discrimination.
This structure is particularly useful for debugging, monitoring, and auditing the flow of messages in systems that involve complex interactions or asynchronous processing.
All fields are optional besides the object.
Useful methods: pprint (pretty prints the underlying message), unwrap (to get the object out of tracer), align_tracer! (to set all shared IDs in a vector of tracers to the same), istracermessage to check if given message is an AbstractTracerMessage
Example
wrap_schema = PT.TracerSchema(PT.OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model = "gpt4t")\nmsg # isa TracerMessage\nmsg.content # access content like if it was the messageTracerMessageLike{T <: Any} <: AbstractTracerA mutable structure designed for general-purpose tracing within the system, capable of handling any type of object that is part of the AI Conversation. It provides a flexible way to track and annotate objects as they move through different parts of the system, facilitating debugging, monitoring, and auditing.
Fields
object::T: The original object being traced.from::Union{Nothing, Symbol}: The identifier of the sender or origin of the object.to::Union{Nothing, Symbol}: The identifier of the intended recipient or destination of the object.viewers::Vector{Symbol}: A list of identifiers for entities that have access to view the object, in addition to the sender and recipient.time_received::DateTime: The timestamp when the object was received by the tracing system.time_sent::Union{Nothing, DateTime}: The timestamp when the object was originally sent, if available.model::String: The name of the model or process that generated or is associated with the object. Defaults to empty.parent_id::Symbol: An identifier for the job or process that the object is associated with. Higher-level tracing ID.thread_id::Symbol: An identifier for the thread or execution context (sub-task, sub-process) within the job where the object originated. It should be the same for objects in the same thread.run_id::Union{Nothing, Int}: A unique identifier for the run or instance of the process (ie, a single call to the LLM) that generated the object. Defaults to a random integer.meta::Union{Nothing, Dict{Symbol, Any}}: A dictionary for additional metadata that is not part of the object itself. Try to limit to a small number of items and singletons to be serializable._type::Symbol: A fixed symbol identifying the type of the tracer as:tracermessage, used for type discrimination.
This structure is particularly useful for systems that involve complex interactions or asynchronous processing, where tracking the flow and transformation of objects is crucial.
All fields are optional besides the object.
TracerSchema <: AbstractTracerSchemaA schema designed to wrap another schema, enabling pre- and post-execution callbacks for tracing and additional functionalities. This type is specifically utilized within the TracerMessage type to trace the execution flow, facilitating observability and debugging in complex conversational AI systems.
The TracerSchema acts as a middleware, allowing developers to insert custom logic before and after the execution of the primary schema's functionality. This can include logging, performance measurement, or any other form of tracing required to understand or improve the execution flow.
TracerSchema automatically wraps messages in TracerMessage type, which has several important fields, eg,
object: the original message - unwrap with utilityunwrapmeta: a dictionary with metadata about the tracing process (eg, prompt templates, LLM API kwargs) - extract with utilitymetaparent_id: an identifier for the overall job / high-level conversation with the user where the current conversationthreadoriginated. It should be the same for objects in the same thread.thread_id: an identifier for the current thread or execution context (sub-task, sub-process, CURRENT CONVERSATION or vector of messages) within the broader parent task. It should be the same for objects in the same thread.
See also: meta, unwrap, SaverSchema, initialize_tracer, finalize_tracer
Example
wrap_schema = TracerSchema(OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model="gpt-4")\n# output type should be TracerMessage\nmsg isa TracerMessageYou can define your own tracer schema and the corresponding methods: initialize_tracer, finalize_tracer. See src/llm_tracer.jl
UserMessageA message type for user-generated text-based responses. Consumed by ai* functions to generate responses.
Fields
content::T: The content of the message.variables::Vector{Symbol}: The variables in the message.name::Union{Nothing, String}: The name of therolein the conversation.
UserMessageWithImagesA message type for user-generated text-based responses with images. Consumed by ai* functions to generate responses.
Fields
content::T: The content of the message.image_url::Vector{String}: The URLs of the images.variables::Vector{Symbol}: The variables in the message.name::Union{Nothing, String}: The name of therolein the conversation.
Construct UserMessageWithImages with 1 or more images. Images can be either URLs or local paths.
XAIOpenAISchemaSchema to call the XAI API. It follows OpenAI API conventions.
Get your API key from here.
Requires one environment variable to be set:
XAI_API_KEY: Your API key
append!(mem::ConversationMemory, msgs::Vector{<:AbstractMessage})Smart append that handles duplicate messages based on run IDs. Only appends messages that are newer than the latest matching message in memory.
length(mem::ConversationMemory)Return the number of messages. All of them.
push!(mem::ConversationMemory, msg::AbstractMessage)Add a single message to the conversation memory.
show(io::IO, mem::ConversationMemory)Display the number of non-system/non-annotation messages in the conversation memory.
OpenAI.create_chat(schema::CustomOpenAISchema,\n api_key::AbstractString,\n model::AbstractString,\n conversation;\n http_kwargs::NamedTuple = NamedTuple(),\n streamcallback::Any = nothing,\n url::String = "http://localhost:8080",\n kwargs...)Dispatch to the OpenAI.create_chat function, for any OpenAI-compatible API.
It expects url keyword argument. Provide it to the aigenerate function via api_kwargs=(; url="my-url")
It will forward your query to the "chat/completions" endpoint of the base URL that you provided (=url).
OpenAI.create_chat(schema::LocalServerOpenAISchema,\n api_key::AbstractString,\n model::AbstractString,\n conversation;\n url::String = "http://localhost:8080",\n kwargs...)Dispatch to the OpenAI.create_chat function, but with the LocalServer API parameters, ie, defaults to url specified by the LOCAL_SERVERpreference. See?PREFERENCES
OpenAI.create_chat(schema::MistralOpenAISchema,api_key::AbstractString, model::AbstractString, conversation; url::String="https://api.mistral.ai/v1", kwargs...)
Dispatch to the OpenAI.create_chat function, but with the MistralAI API parameters.
It tries to access the MISTRAL_API_KEY ENV variable, but you can also provide it via the api_key keyword argument.
aiclassify(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiclassify call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiclassify(with thetracer_schema.schema)calls
finalize_tracer
', 111)), + createBaseVNode("div", _hoisted_2, [ + _cache[10] || (_cache[10] = createStaticVNode('# PromptingTools.aiclassify — Method.
aiclassify(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n choices::AbstractVector{T} = ["true", "false", "unknown"],\n model::AbstractString = MODEL_CHAT,\n api_kwargs::NamedTuple = NamedTuple(),\n token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing,\n kwargs...) where {T <: Union{AbstractString, Tuple{<:AbstractString, <:AbstractString}}}Classifies the given prompt/statement into an arbitrary list of choices, which must be only the choices (vector of strings) or choices and descriptions are provided (vector of tuples, ie, ("choice","description")).
It's quick and easy option for "routing" and similar use cases, as it exploits the logit bias trick and outputs only 1 token. classify into an arbitrary list of categories (including with descriptions). It's quick and easy option for "routing" and similar use cases, as it exploits the logit bias trick, so it outputs only 1 token.
', 9)), + createBaseVNode("p", null, [ + _cache[6] || (_cache[6] = createTextVNode("!!! Note: The prompt/AITemplate must have a placeholder ")), + _cache[7] || (_cache[7] = createBaseVNode("code", null, "choices", -1)), + _cache[8] || (_cache[8] = createTextVNode(" (ie, ")), + createBaseVNode("code", null, toDisplayString(_ctx.choices), 1), + _cache[9] || (_cache[9] = createTextVNode(") that will be replaced with the encoded choices")) + ]), + _cache[11] || (_cache[11] = createStaticVNode('Choices are rewritten into an enumerated list and mapped to a few known OpenAI tokens (maximum of 40 choices supported). Mapping of token IDs for GPT3.5/4 are saved in variable OPENAI_TOKEN_IDS.
It uses Logit bias trick and limits the output to 1 token to force the model to output only true/false/unknown. Credit for the idea goes to AAAzzam.
Arguments
prompt_schema::AbstractOpenAISchema: The schema for the prompt.prompt: The prompt/statement to classify if it's aString. If it's aSymbol, it is expanded as a template viarender(schema,template). Eg, templates:JudgeIsItTrueor:InputClassifierchoices::AbstractVector{T}: The choices to be classified into. It can be a vector of strings or a vector of tuples, where the first element is the choice and the second is the description.model::AbstractString = MODEL_CHAT: The model to use for classification. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.api_kwargs::NamedTuple = NamedTuple(): Additional keyword arguments for the API call.token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing: A dictionary mapping custom token IDs to their corresponding integer values. Ifnothing, it will use the default token IDs for the given model.kwargs: Additional keyword arguments for the prompt template.
Example
Given a user input, pick one of the two provided categories:
choices = ["animal", "plant"]\ninput = "Palm tree"\naiclassify(:InputClassifier; choices, input)Choices with descriptions provided as tuples:
choices = [("A", "any animal or creature"), ("P", "any plant or tree"), ("O", "anything else")]\n\n# try the below inputs:\ninput = "spider" # -> returns "A" for any animal or creature\ninput = "daphodil" # -> returns "P" for any plant or tree\ninput = "castle" # -> returns "O" for everything else\naiclassify(:InputClassifier; choices, input)You could also use this function for routing questions to different endpoints (notice the different template and placeholder used), eg,
choices = [("A", "any question about animal or creature"), ("P", "any question about plant or tree"), ("O", "anything else")]\nquestion = "how many spiders are there?"\nmsg = aiclassify(:QuestionRouter; choices, question)\n# "A"You can still use a simple true/false classification:
aiclassify("Is two plus two four?") # true\naiclassify("Is two plus three a vegetable on Mars?") # falseaiclassify returns only true/false/unknown. It's easy to get the proper Bool output type out with tryparse, eg,
tryparse(Bool, aiclassify("Is two plus two four?")) isa Bool # trueOutput of type Nothing marks that the model couldn't classify the statement as true/false.
Ideally, we would like to re-use some helpful system prompt to get more accurate responses. For this reason we have templates, eg, :JudgeIsItTrue. By specifying the template, we can provide our statement as the expected variable (it in this case) See that the model now correctly classifies the statement as "unknown".
aiclassify(:JudgeIsItTrue; it = "Is two plus three a vegetable on Mars?") # unknownFor better results, use higher quality models like gpt4, eg,
aiclassify(:JudgeIsItTrue;\n it = "If I had two apples and I got three more, I have five apples now.",\n model = "gpt4") # trueaiembed(tracer_schema::AbstractTracerSchema,\n doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}}, postprocess::Function = identity;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiembed call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiembed(with thetracer_schema.schema)calls
finalize_tracer
aiembed(prompt_schema::AbstractOllamaManagedSchema,\n doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}},\n postprocess::F = identity;\n verbose::Bool = true,\n api_key::String = "",\n model::String = MODEL_EMBEDDING,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120),\n api_kwargs::NamedTuple = NamedTuple(),\n kwargs...) where {F <: Function}The aiembed function generates embeddings for the given input using a specified model and returns a message object containing the embeddings, status, token count, and elapsed time.
Arguments
prompt_schema::AbstractOllamaManagedSchema: The schema for the prompt.doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}}: The document or list of documents to generate embeddings for. The list of documents is processed sequentially, so users should consider implementing an async version with withThreads.@spawnpostprocess::F: The post-processing function to apply to each embedding. Defaults to the identity function, but could beLinearAlgebra.normalize.verbose::Bool: A flag indicating whether to print verbose information. Defaults totrue.api_key::String: The API key to use for the OpenAI API. Defaults to"".model::String: The model to use for generating embeddings. Defaults toMODEL_EMBEDDING.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.api_kwargs::NamedTuple: Additional keyword arguments for the Ollama API. Defaults to an emptyNamedTuple.kwargs: Prompt variables to be used to fill the prompt/template
Returns
msg: ADataMessageobject containing the embeddings, status, token count, and elapsed time.
Note: Ollama API currently does not return the token count, so it's set to (0,0)
Example
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\n\nmsg = aiembed(schema, "Hello World"; model="openhermes2.5-mistral")\nmsg.content # 4096-element JSON3.Array{Float64...We can embed multiple strings at once and they will be hcat into a matrix (ie, each column corresponds to one string)
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\n\nmsg = aiembed(schema, ["Hello World", "How are you?"]; model="openhermes2.5-mistral")\nmsg.content # 4096×2 Matrix{Float64}:If you plan to calculate the cosine distance between embeddings, you can normalize them first:
const PT = PromptingTools\nusing LinearAlgebra\nschema = PT.OllamaManagedSchema()\n\nmsg = aiembed(schema, ["embed me", "and me too"], LinearAlgebra.normalize; model="openhermes2.5-mistral")\n\n# calculate cosine distance between the two normalized embeddings as a simple dot product\nmsg.content' * msg.content[:, 1] # [1.0, 0.34]Similarly, you can use the postprocess argument to materialize the data from JSON3.Object by using postprocess = copy
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\n\nmsg = aiembed(schema, "Hello World", copy; model="openhermes2.5-mistral")\nmsg.content # 4096-element Vector{Float64}aiembed(prompt_schema::AbstractOpenAISchema,\n doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}},\n postprocess::F = identity;\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_EMBEDDING, \n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120),\n api_kwargs::NamedTuple = NamedTuple(),\n kwargs...) where {F <: Function}The aiembed function generates embeddings for the given input using a specified model and returns a message object containing the embeddings, status, token count, and elapsed time.
Arguments
prompt_schema::AbstractOpenAISchema: The schema for the prompt.doc_or_docs::Union{AbstractString, AbstractVector{<:AbstractString}}: The document or list of documents to generate embeddings for.postprocess::F: The post-processing function to apply to each embedding. Defaults to the identity function.verbose::Bool: A flag indicating whether to print verbose information. Defaults totrue.api_key::String: The API key to use for the OpenAI API. Defaults toOPENAI_API_KEY.model::String: The model to use for generating embeddings. Defaults toMODEL_EMBEDDING.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to(retry_non_idempotent = true, retries = 5, readtimeout = 120).api_kwargs::NamedTuple: Additional keyword arguments for the OpenAI API. Defaults to an emptyNamedTuple.kwargs...: Additional keyword arguments.
Returns
msg: ADataMessageobject containing the embeddings, status, token count, and elapsed time. Usemsg.contentto access the embeddings.
Example
msg = aiembed("Hello World")\nmsg.content # 1536-element JSON3.Array{Float64...We can embed multiple strings at once and they will be hcat into a matrix (ie, each column corresponds to one string)
msg = aiembed(["Hello World", "How are you?"])\nmsg.content # 1536×2 Matrix{Float64}:If you plan to calculate the cosine distance between embeddings, you can normalize them first:
using LinearAlgebra\nmsg = aiembed(["embed me", "and me too"], LinearAlgebra.normalize)\n\n# calculate cosine distance between the two normalized embeddings as a simple dot product\nmsg.content' * msg.content[:, 1] # [1.0, 0.787]aiextract(prompt_schema::AbstractAnthropicSchema, prompt::ALLOWED_PROMPT_TYPE;\n return_type::Union{Type, AbstractTool, Vector},\n verbose::Bool = true,\n api_key::String = ANTHROPIC_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = NamedTuple(),\n cache::Union{Nothing, Symbol} = nothing,\n betas::Union{Nothing, Vector{Symbol}} = nothing,\n kwargs...)Extract required information (defined by a struct return_type) from the provided prompt by leveraging Anthropic's function calling mode.
This is a perfect solution for extracting structured information from text (eg, extract organization names in news articles, etc.).
Read best practics here.
It's effectively a light wrapper around aigenerate call, which requires additional keyword argument return_type to be provided and will enforce the model outputs to adhere to it.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplatereturn_type: A struct TYPE representing the the information we want to extract. Do not provide a struct instance, only the type. If the struct has a docstring, it will be provided to the model as well. It's used to enforce structured model outputs or provide more information. Alternatively, you can provide a vector of field names and their types (see?generate_structfunction for the syntax).verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message::Bool = false: Iftrue, skips the system message in the conversation history.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.:tool_choice: A string indicating which tool to use. Supported values arenothing,"auto","any"and"exact".nothingwill use the default tool choice.
cache: A symbol indicating whether to use caching for the prompt. Supported values arenothing(no caching),:system,:tools,:lastand:all. Note that COST estimate will be wrong (ignores the caching).:system: Caches the system message:tools: Caches the tool definitions (and everything before them):last: Caches the last message in the conversation (and everything before it):all: Cache trigger points are inserted in all of the above places (ie, higher likelyhood of cache hit, but also slightly higher cost)
betas::Union{Nothing, Vector{Symbol}}: A vector of symbols representing the beta features to be used. See?anthropic_extra_headersfor details.kwargs: Prompt variables to be used to fill the prompt/template
Note: At the moment, the cache is only allowed for prompt segments over 1024 tokens (in some cases, over 2048 tokens). You'll get an error if you try to cache short prompts.
Returns
If return_all=false (default):
msg: AnDataMessageobject representing the extracted data, including the content, status, tokens, and elapsed time. Usemsg.contentto access the extracted data.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (DataMessage).
See also: tool_call_signature, MaybeExtract, ItemsExtract, aigenerate
Example
Do you want to extract some specific measurements from a text like age, weight and height? You need to define the information you need as a struct (return_type):
"Person's age, height, and weight."\nstruct MyMeasurement\n age::Int # required\n height::Union{Int,Nothing} # optional\n weight::Union{Nothing,Float64} # optional\nend\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall."; model="claudeh", return_type=MyMeasurement)\n# PromptingTools.DataMessage(MyMeasurement)\nmsg.content\n# MyMeasurement(30, 180, 80.0)The fields that allow Nothing are marked as optional in the schema:
msg = aiextract("James is 30."; model="claudeh", return_type=MyMeasurement)\n# MyMeasurement(30, nothing, nothing)If there are multiple items you want to extract, define a wrapper struct to get a Vector of MyMeasurement:
struct ManyMeasurements\n measurements::Vector{MyMeasurement}\nend\n\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; model="claudeh", return_type=ManyMeasurements)\n\nmsg.content.measurements\n# 2-element Vector{MyMeasurement}:\n# MyMeasurement(30, 180, 80.0)\n# MyMeasurement(19, 190, nothing)Or you can use the convenience wrapper ItemsExtract to extract multiple measurements (zero, one or more):
using PromptingTools: ItemsExtract\n\nreturn_type = ItemsExtract{MyMeasurement}\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; model="claudeh", return_type)\n\nmsg.content.items # see the extracted itemsOr if you want your extraction to fail gracefully when data isn't found, use MaybeExtract{T} wrapper (this trick is inspired by the Instructor package!):
using PromptingTools: MaybeExtract\n\nreturn_type = MaybeExtract{MyMeasurement}\n# Effectively the same as:\n# struct MaybeExtract{T}\n# result::Union{T, Nothing} // The result of the extraction\n# error::Bool // true if a result is found, false otherwise\n# message::Union{Nothing, String} // Only present if no result is found, should be short and concise\n# end\n\n# If LLM extraction fails, it will return a Dict with `error` and `message` fields instead of the result!\nmsg = aiextract("Extract measurements from the text: I am giraffe"; model="claudeo", return_type)\nmsg.content\n# Output: MaybeExtract{MyMeasurement}(nothing, true, "I'm sorry, but your input of "I am giraffe" does not contain any information about a person's age, height or weight measurements that I can extract. To use this tool, please provide a statement that includes at least the person's age, and optionally their height in inches and weight in pounds. Without that information, I am unable to extract the requested measurements.")That way, you can handle the error gracefully and get a reason why extraction failed (in msg.content.message).
However, this can fail with weaker models like claudeh, so we can apply some of our prompt templates with embedding reasoning step:
msg = aiextract(:ExtractDataCoTXML; data="I am giraffe", model="claudeh", return_type)\nmsg.content\n# Output: MaybeExtract{MyMeasurement}(nothing, true, "The provided data does not contain the expected information about a person's age, height, and weight.")Note that when using a prompt template, we provide data for the extraction as the corresponding placeholder (see aitemplates("extract") for documentation of this template).
Note that the error message refers to a giraffe not being a human, because in our MyMeasurement docstring, we said that it's for people!
Example of using a vector of field names with aiextract
fields = [:location, :temperature => Float64, :condition => String]\nmsg = aiextract("Extract the following information from the text: location, temperature, condition. Text: The weather in New York is sunny and 72.5 degrees Fahrenheit."; \nreturn_type = fields, model="claudeh")Or simply call aiextract("some text"; return_type = [:reasoning,:answer], model="claudeh") to get a Chain of Thought reasoning for extraction task.
It will be returned it a new generated type, which you can check with PromptingTools.isextracted(msg.content) == true to confirm the data has been extracted correctly.
This new syntax also allows you to provide field-level descriptions, which will be passed to the model.
fields_with_descriptions = [\n :location,\n :temperature => Float64,\n :temperature__description => "Temperature in degrees Fahrenheit",\n :condition => String,\n :condition__description => "Current weather condition (e.g., sunny, rainy, cloudy)"\n]\nmsg = aiextract("The weather in New York is sunny and 72.5 degrees Fahrenheit."; return_type = fields_with_descriptions, model="claudeh")aiextract(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n return_type::Union{Type, AbstractTool, Vector},\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = (;\n tool_choice = nothing),\n strict::Union{Nothing, Bool} = nothing,\n kwargs...)Extract required information (defined by a struct return_type) from the provided prompt by leveraging OpenAI function calling mode.
This is a perfect solution for extracting structured information from text (eg, extract organization names in news articles, etc.)
It's effectively a light wrapper around aigenerate call, which requires additional keyword argument return_type to be provided and will enforce the model outputs to adhere to it.
!!! Note: The types must be CONCRETE, it helps with correct conversion to JSON schema and then conversion back to the struct.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplatereturn_type: A struct TYPE (or a Tool, vector of Types) representing the the information we want to extract. Do not provide a struct instance, only the type. Alternatively, you can provide a vector of field names and their types (see?generate_structfunction for the syntax). If the struct has a docstring, it will be provided to the model as well. It's used to enforce structured model outputs or provide more information.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.tool_choice: Specifies which tool to use for the API call. Usually, one of "auto","any","exact" //nothingwill pick a default. Defaults to"exact"for 1 tool and"auto"for many tools, which is a made-up value to enforce the OpenAI requirements if we want one exact function. Providers like Mistral, Together, etc. use"any"instead.
strict::Union{Nothing, Bool} = nothing: A boolean indicating whether to enforce strict generation of the response (supported only for OpenAI models). It has additional latency for the first request. Ifnothing, standard function calling is used.json_mode::Union{Nothing, Bool} = nothing: Ifjson_mode = true, we use JSON mode for the response (supported only for OpenAI models). Ifnothing, standard function calling is used. JSON mode is understood to be more creative and smarter than function calling mode, as it's not mascarading as a function call, but there is extra latency for the first request to produce grammar for constrained sampling.kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnDataMessageobject representing the extracted data, including the content, status, tokens, and elapsed time. Usemsg.contentto access the extracted data.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (DataMessage).
Note: msg.content can be a single object (if a single tool is used) or a vector of objects (if multiple tools are used)!
See also: tool_call_signature, MaybeExtract, ItemsExtract, aigenerate, generate_struct
Example
Do you want to extract some specific measurements from a text like age, weight and height? You need to define the information you need as a struct (return_type):
"Person's age, height, and weight."\nstruct MyMeasurement\n age::Int # required\n height::Union{Int,Nothing} # optional\n weight::Union{Nothing,Float64} # optional\nend\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall."; return_type=MyMeasurement)\n# PromptingTools.DataMessage(MyMeasurement)\nmsg.content\n# MyMeasurement(30, 180, 80.0)The fields that allow Nothing are marked as optional in the schema:
msg = aiextract("James is 30."; return_type=MyMeasurement)\n# MyMeasurement(30, nothing, nothing)If there are multiple items you want to extract, define a wrapper struct to get a Vector of MyMeasurement:
struct ManyMeasurements\n measurements::Vector{MyMeasurement}\nend\n\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; return_type=ManyMeasurements)\n\nmsg.content.measurements\n# 2-element Vector{MyMeasurement}:\n# MyMeasurement(30, 180, 80.0)\n# MyMeasurement(19, 190, nothing)Or you can use the convenience wrapper ItemsExtract to extract multiple measurements (zero, one or more):
using PromptingTools: ItemsExtract\n\nreturn_type = ItemsExtract{MyMeasurement}\nmsg = aiextract("James is 30, weighs 80kg. He's 180cm tall. Then Jack is 19 but really tall - over 190!"; return_type)\n\nmsg.content.items # see the extracted itemsOr if you want your extraction to fail gracefully when data isn't found, use MaybeExtract{T} wrapper (this trick is inspired by the Instructor package!):
using PromptingTools: MaybeExtract\n\nreturn_type = MaybeExtract{MyMeasurement}\n# Effectively the same as:\n# struct MaybeExtract{T}\n# result::Union{T, Nothing} // The result of the extraction\n# error::Bool // true if a result is found, false otherwise\n# message::Union{Nothing, String} // Only present if no result is found, should be short and concise\n# end\n\n# If LLM extraction fails, it will return a Dict with `error` and `message` fields instead of the result!\nmsg = aiextract("Extract measurements from the text: I am giraffe"; return_type)\nmsg.content\n# MaybeExtract{MyMeasurement}(nothing, true, "I'm sorry, but I can only assist with human measurements.")That way, you can handle the error gracefully and get a reason why extraction failed (in msg.content.message).
Note that the error message refers to a giraffe not being a human, because in our MyMeasurement docstring, we said that it's for people!
Some non-OpenAI providers require a different specification of the "tool choice" than OpenAI. For example, to use Mistral models ("mistrall" for mistral large), do:
"Some fruit"\nstruct Fruit\n name::String\nend\naiextract("I ate an apple",return_type=Fruit,api_kwargs=(;tool_choice="any"),model="mistrall")\n# Notice two differences: 1) struct MUST have a docstring, 2) tool_choice is set explicitly set to "any"Example of using a vector of field names with aiextract
fields = [:location, :temperature => Float64, :condition => String]\nmsg = aiextract("Extract the following information from the text: location, temperature, condition. Text: The weather in New York is sunny and 72.5 degrees Fahrenheit."; return_type = fields)Or simply call aiextract("some text"; return_type = [:reasoning,:answer]) to get a Chain of Thought reasoning for extraction task.
It will be returned it a new generated type, which you can check with PromptingTools.isextracted(msg.content) == true to confirm the data has been extracted correctly.
This new syntax also allows you to provide field-level descriptions, which will be passed to the model.
fields_with_descriptions = [\n :location,\n :temperature => Float64,\n :temperature__description => "Temperature in degrees Fahrenheit",\n :condition => String,\n :condition__description => "Current weather condition (e.g., sunny, rainy, cloudy)"\n]\nmsg = aiextract("The weather in New York is sunny and 72.5 degrees Fahrenheit."; return_type = fields_with_descriptions)If you feel that the extraction is not smart/creative enough, you can use json_mode = true to enforce the JSON mode, which automatically enables the structured output mode (as opposed to function calling mode).
The JSON mode is useful for cases when you want to enforce a specific output format, such as JSON, and want the model to adhere to that format, but don't want to pretend it's a "function call". Expect a few second delay on the first call for a specific struct, as the provider has to produce the constrained grammer first.
msg = aiextract("Extract the following information from the text: location, temperature, condition. Text: The weather in New York is sunny and 72.5 degrees Fahrenheit."; \nreturn_type = fields_with_descriptions, json_mode = true)\n# PromptingTools.DataMessage(NamedTuple)\n\nmsg.content\n# (location = "New York", temperature = 72.5, condition = "sunny")It works equally well for structs provided as return types:
msg = aiextract("James is 30, weighs 80kg. He's 180cm tall."; return_type=MyMeasurement, json_mode=true)aiextract(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiextract call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiextract(with thetracer_schema.schema)calls
finalize_tracer
aigenerate(prompt_schema::AbstractAnthropicSchema, prompt::ALLOWED_PROMPT_TYPE; verbose::Bool = true,\n api_key::String = ANTHROPIC_API_KEY, model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n streamcallback::Any = nothing,\n no_system_message::Bool = false,\n aiprefill::Union{Nothing, AbstractString} = nothing,\n http_kwargs::NamedTuple = NamedTuple(), api_kwargs::NamedTuple = NamedTuple(),\n cache::Union{Nothing, Symbol} = nothing,\n betas::Union{Nothing, Vector{Symbol}} = nothing,\n kwargs...)Generate an AI response based on a given prompt using the Anthropic API.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchemanotAbstractAnthropicSchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: API key for the Antropic API. Defaults toANTHROPIC_API_KEY(loaded viaENV["ANTHROPIC_API_KEY"]).model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES, eg, "claudeh".return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation::AbstractVector{<:AbstractMessage}=[]: Not allowed for this schema. Provided only for compatibility.streamcallback::Any: A callback function to handle streaming responses. Can be simplystdoutorStreamCallbackobject. See?StreamCallbackfor details. Note: We configure theStreamCallback(and necessaryapi_kwargs) for you, unless you specify theflavor. See?configure_callback!for details.no_system_message::Bool=false: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.aiprefill::Union{Nothing, AbstractString}: A string to be used as a prefill for the AI response. This steer the AI response in a certain direction (and potentially save output tokens). It MUST NOT end with a trailing with space. Useful for JSON formatting.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.api_kwargs::NamedTuple: Additional keyword arguments for the Ollama API. Defaults to an emptyNamedTuple.max_tokens::Int: The maximum number of tokens to generate. Defaults to 2048, because it's a required parameter for the API.
cache: A symbol indicating whether to use caching for the prompt. Supported values arenothing(no caching),:system,:tools,:lastand:all. Note that COST estimate will be wrong (ignores the caching).:system: Caches the system message:tools: Caches the tool definitions (and everything before them):last: Caches the last message in the conversation (and everything before it):all: Cache trigger points are inserted in all of the above places (ie, higher likelyhood of cache hit, but also slightly higher cost)
betas::Union{Nothing, Vector{Symbol}}: A vector of symbols representing the beta features to be used. See?anthropic_extra_headersfor details.kwargs: Prompt variables to be used to fill the prompt/template
Note: At the moment, the cache is only allowed for prompt segments over 1024 tokens (in some cases, over 2048 tokens). You'll get an error if you try to cache short prompts.
Returns
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
See also: ai_str, aai_str
Example
Simple hello world to test the API:
const PT = PromptingTools\nschema = PT.AnthropicSchema() # We need to explicit if we want Anthropic, otherwise OpenAISchema is the default\n\nmsg = aigenerate(schema, "Say hi!"; model="claudeh") #claudeh is the model alias for Claude 3 Haiku, fast and cheap model\n[ Info: Tokens: 21 @ Cost: $0.0 in 0.6 seconds\nAIMessage("Hello!")msg is an AIMessage object. Access the generated string via content property:
typeof(msg) # AIMessage{SubString{String}}\npropertynames(msg) # (:content, :status, :tokens, :elapsed, :cost, :log_prob, :finish_reason, :run_id, :sample_id, :_type)\nmsg.content # "Hello!Note: We need to be explicit about the schema we want to use. If we don't, it will default to OpenAISchema (=PT.DEFAULT_SCHEMA) Alternatively, if you provide a known model name or alias (eg, claudeh for Claude 3 Haiku - see MODEL_REGISTRY), the schema will be inferred from the model name.
We will use Claude 3 Haiku model for the following examples, so not need to specify the schema. See also "claudeo" and "claudes" for other Claude 3 models.
You can use string interpolation:
const PT = PromptingTools\n\na = 1\nmsg=aigenerate("What is `$a+$a`?"; model="claudeh")\nmsg.content # "The answer to `1+1` is `2`."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}. Claude models are good at completeling conversations that ended with an AIMessage (they just continue where it left off):
const PT = PromptingTools\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?"),\n PT.AIMessage("Hmm, strong the attachment is,")]\n\nmsg = aigenerate(conversation; model="claudeh")\nAIMessage("I sense. But unhealthy it may be. Your iPhone, a tool it is, not a living being. Feelings of affection, understandable they are, <continues>")Example of streaming:
# Simplest usage, just provide where to steam the text\nmsg = aigenerate("Count from 1 to 100."; streamcallback = stdout, model="claudeh")\n\nstreamcallback = PT.StreamCallback()\nmsg = aigenerate("Count from 1 to 100."; streamcallback, model="claudeh")\n# this allows you to inspect each chunk with `streamcallback.chunks`. You can them empty it with `empty!(streamcallback)` in between repeated calls.\n\n# Get verbose output with details of each chunk\nstreamcallback = PT.StreamCallback(; verbose=true, throw_on_error=true)\nmsg = aigenerate("Count from 1 to 10."; streamcallback, model="claudeh")Note: Streaming support is only for Anthropic models and it doesn't yet support tool calling and a few other features (logprobs, refusals, etc.)
You can also provide a prefill for the AI response to steer the response in a certain direction (eg, formatting, style):
msg = aigenerate("Sum up 1 to 100."; aiprefill = "I'd be happy to answer in one number without any additional text. The answer is:", model="claudeh")Note: It MUST NOT end with a trailing with space. You'll get an API error if you do.
aigenerate(prompt_schema::AbstractGoogleSchema, prompt::ALLOWED_PROMPT_TYPE;\n verbose::Bool = true,\n api_key::String = GOOGLE_API_KEY,\n model::String = "gemini-pro", return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generate an AI response based on a given prompt using the Google Gemini API. Get the API key here.
Note:
There is no "cost" reported as of February 2024, as all access seems to be free-of-charge. See the details here.
tokensin the returned AIMessage are actually characters, not tokens. We use a conservative estimate as they are not provided by the API yet.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES. Defaults toreturn_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message::Bool=false: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aiembed, aiclassify, aiextract, aiscan, aitemplates
Example
Simple hello world to test the API:
result = aigenerate("Say Hi!"; model="gemini-pro")\n# AIMessage("Hi there! 👋 I'm here to help you with any questions or tasks you may have. Just let me know what you need, and I'll do my best to assist you.")result is an AIMessage object. Access the generated string via content property:
typeof(result) # AIMessage{SubString{String}}\npropertynames(result) # (:content, :status, :tokens, :elapsed\nresult.content # "Hi there! ...___ You can use string interpolation and alias "gemini":
a = 1\nmsg=aigenerate("What is `$a+$a`?"; model="gemini")\nmsg.content # "1+1 is 2."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}:
const PT = PromptingTools\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\nmsg=aigenerate(conversation; model="gemini")\n# AIMessage("Young Padawan, you have stumbled into a dangerous path.... <continues>")aigenerate(prompt_schema::AbstractOllamaManagedSchema, prompt::ALLOWED_PROMPT_TYPE; verbose::Bool = true,\n api_key::String = "", model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n streamcallback::Any = nothing,\n http_kwargs::NamedTuple = NamedTuple(), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generate an AI response based on a given prompt using the OpenAI API.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchemanotAbstractManagedSchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: Provided for interface consistency. Not needed for locally hosted Ollama.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation::AbstractVector{<:AbstractMessage}=[]: Not allowed for this schema. Provided only for compatibility.streamcallback::Any: Just for compatibility. Not supported for this schema.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.api_kwargs::NamedTuple: Additional keyword arguments for the Ollama API. Defaults to an emptyNamedTuple.kwargs: Prompt variables to be used to fill the prompt/template
Returns
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
See also: ai_str, aai_str, aiembed
Example
Simple hello world to test the API:
const PT = PromptingTools\nschema = PT.OllamaManagedSchema() # We need to explicit if we want Ollama, OpenAISchema is the default\n\nmsg = aigenerate(schema, "Say hi!"; model="openhermes2.5-mistral")\n# [ Info: Tokens: 69 in 0.9 seconds\n# AIMessage("Hello! How can I assist you today?")msg is an AIMessage object. Access the generated string via content property:
typeof(msg) # AIMessage{SubString{String}}\npropertynames(msg) # (:content, :status, :tokens, :elapsed\nmsg.content # "Hello! How can I assist you today?"Note: We need to be explicit about the schema we want to use. If we don't, it will default to OpenAISchema (=PT.DEFAULT_SCHEMA) ___ You can use string interpolation:
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\na = 1\nmsg=aigenerate(schema, "What is `$a+$a`?"; model="openhermes2.5-mistral")\nmsg.content # "The result of `1+1` is `2`."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}:
const PT = PromptingTools\nschema = PT.OllamaManagedSchema()\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\n\nmsg = aigenerate(schema, conversation; model="openhermes2.5-mistral")\n# [ Info: Tokens: 111 in 2.1 seconds\n# AIMessage("Strong the attachment is, it leads to suffering it may. Focus on the force within you must, ...<continues>")Note: Managed Ollama currently supports at most 1 User Message and 1 System Message given the API limitations. If you want more, you need to use the ChatMLSchema.
aigenerate(prompt_schema::AbstractOllamaManagedSchema, prompt::ALLOWED_PROMPT_TYPE; verbose::Bool = true,\n api_key::String = "", model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n streamcallback::Any = nothing,\n http_kwargs::NamedTuple = NamedTuple(), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generate an AI response based on a given prompt using the OpenAI API.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchemanotAbstractManagedSchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: Provided for interface consistency. Not needed for locally hosted Ollama.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation::AbstractVector{<:AbstractMessage}=[]: Not allowed for this schema. Provided only for compatibility.streamcallback: A callback function to handle streaming responses. Can be simplystdoutor aStreamCallbackobject. See?StreamCallbackfor details.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.api_kwargs::NamedTuple: Additional keyword arguments for the Ollama API. Defaults to an emptyNamedTuple.kwargs: Prompt variables to be used to fill the prompt/template
Returns
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
See also: ai_str, aai_str, aiembed
Example
Simple hello world to test the API:
const PT = PromptingTools\nschema = PT.OllamaSchema() # We need to explicit if we want Ollama, OpenAISchema is the default\n\nmsg = aigenerate(schema, "Say hi!"; model="openhermes2.5-mistral")\n# [ Info: Tokens: 69 in 0.9 seconds\n# AIMessage("Hello! How can I assist you today?")msg is an AIMessage object. Access the generated string via content property:
typeof(msg) # AIMessage{SubString{String}}\npropertynames(msg) # (:content, :status, :tokens, :elapsed\nmsg.content # "Hello! How can I assist you today?"Note: We need to be explicit about the schema we want to use. If we don't, it will default to OpenAISchema (=PT.DEFAULT_SCHEMA) ___ You can use string interpolation:
const PT = PromptingTools\nschema = PT.OllamaSchema()\na = 1\nmsg=aigenerate(schema, "What is `$a+$a`?"; model="openhermes2.5-mistral")\nmsg.content # "The result of `1+1` is `2`."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}:
const PT = PromptingTools\nschema = PT.OllamaSchema()\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\n\nmsg = aigenerate(schema, conversation; model="openhermes2.5-mistral")\n# [ Info: Tokens: 111 in 2.1 seconds\n# AIMessage("Strong the attachment is, it leads to suffering it may. Focus on the force within you must, ...<continues>")To add streaming, use the streamcallback argument.
msg = aigenerate("Count from 1 to 10."; streamcallback = stdout)Or if you prefer to have more control, use a StreamCallback object.
streamcallback = PT.StreamCallback()\nmsg = aigenerate("Count from 1 to 10."; streamcallback)WARNING: If you provide a StreamCallback object with a flavor, we assume you want to configure everything yourself, so you need to make sure to set stream = true in the api_kwargs!
streamcallback = PT.StreamCallback(; flavor = PT.OllamaStream())\nmsg = aigenerate("Count from 1 to 10."; streamcallback, api_kwargs = (; stream = true))aigenerate(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT, return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n streamcallback::Any = nothing,\n no_system_message::Bool = false,\n name_user::Union{Nothing, String} = nothing,\n name_assistant::Union{Nothing, String} = nothing,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generate an AI response based on a given prompt using the OpenAI API.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateverbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.streamcallback: A callback function to handle streaming responses. Can be simplystdoutor aStreamCallbackobject. See?StreamCallbackfor details. Note: We configure theStreamCallback(and necessaryapi_kwargs) for you, unless you specify theflavor. See?configure_callback!for details.no_system_message::Bool=false: Iftrue, the default system message is not included in the conversation history. Any existing system message is converted to aUserMessage.name_user::Union{Nothing, String} = nothing: The name to use for the user in the conversation history. Defaults tonothing.name_assistant::Union{Nothing, String} = nothing: The name to use for the assistant in the conversation history. Defaults tonothing.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments. Useful parameters include:temperature: A float representing the temperature for sampling (ie, the amount of "creativity"). Often defaults to0.7.logprobs: A boolean indicating whether to return log probabilities for each token. Defaults tofalse.n: An integer representing the number of completions to generate at once (if supported).stop: A vector of strings representing the stop conditions for the conversation. Defaults to an empty vector.
kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aiembed, aiclassify, aiextract, aiscan, aitemplates
Example
Simple hello world to test the API:
result = aigenerate("Say Hi!")\n# [ Info: Tokens: 29 @ Cost: $0.0 in 1.0 seconds\n# AIMessage("Hello! How can I assist you today?")result is an AIMessage object. Access the generated string via content property:
typeof(result) # AIMessage{SubString{String}}\npropertynames(result) # (:content, :status, :tokens, :elapsed\nresult.content # "Hello! How can I assist you today?"___ You can use string interpolation:
a = 1\nmsg=aigenerate("What is `$a+$a`?")\nmsg.content # "The sum of `1+1` is `2`."___ You can provide the whole conversation or more intricate prompts as a Vector{AbstractMessage}:
const PT = PromptingTools\n\nconversation = [\n PT.SystemMessage("You're master Yoda from Star Wars trying to help the user become a Yedi."),\n PT.UserMessage("I have feelings for my iPhone. What should I do?")]\nmsg=aigenerate(conversation)\n# AIMessage("Ah, strong feelings you have for your iPhone. A Jedi's path, this is not... <continues>")Example of streaming:
# Simplest usage, just provide where to steam the text\nmsg = aigenerate("Count from 1 to 100."; streamcallback = stdout)\n\nstreamcallback = PT.StreamCallback()\nmsg = aigenerate("Count from 1 to 100."; streamcallback)\n# this allows you to inspect each chunk with `streamcallback.chunks`. You can them empty it with `empty!(streamcallback)` in between repeated calls.\n\n# Get verbose output with details of each chunk\nstreamcallback = PT.StreamCallback(; verbose=true, throw_on_error=true)\nmsg = aigenerate("Count from 1 to 10."; streamcallback)WARNING: If you provide a StreamCallback object, we assume you want to configure everything yourself, so you need to make sure to set stream = true in the api_kwargs!
Learn more in ?StreamCallback. Note: Streaming support is only for OpenAI models and it doesn't yet support tool calling and a few other features (logprobs, refusals, etc.)
aigenerate(schema::AbstractPromptSchema,\n mem::ConversationMemory; kwargs...)Generate a response using the conversation memory context.
aigenerate(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", return_all::Bool = false, kwargs...)Wraps the normal aigenerate call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aigenerate(with thetracer_schema.schema)calls
finalize_tracer
Example
wrap_schema = PT.TracerSchema(PT.OpenAISchema())\nmsg = aigenerate(wrap_schema, "Say hi!"; model = "gpt4t")\nmsg isa TracerMessage # true\nmsg.content # access content like if it was the message\nPT.pprint(msg) # pretty-print the messageIt works on a vector of messages and converts only the non-tracer ones, eg,
wrap_schema = PT.TracerSchema(PT.OpenAISchema())\nconv = aigenerate(wrap_schema, "Say hi!"; model = "gpt4t", return_all = true)\nall(PT.istracermessage, conv) #trueaiimage(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n image_size::AbstractString = "1024x1024",\n image_quality::AbstractString = "standard",\n image_n::Integer = 1,\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_IMAGE_GENERATION,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Generates an image from the provided prompt. If multiple "messages" are provided in prompt, it extracts the text ONLY from the last message!
Image (or the reference to it) will be returned in a DataMessage.content, the format will depend on the api_kwargs.response_format you set.
Can be used for generating images of varying quality and style with dall-e-* models. This function DOES NOT SUPPORT multi-turn conversations (ie, do not provide previous conversation via conversation argument).
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateimage_size: String-based resolution of the image, eg, "1024x1024". Only some resolutions are supported - see the API docs.image_quality: It can be either "standard" or "hd". Defaults to "standard".image_n: The number of images to generate. Currently, only single image generation is allowed (image_n = 1).verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_IMAGE_GENERATION.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. Currently, NOT ALLOWED.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments. Several important arguments are highlighted below:response_format: The format image should be returned in. Can be one of "url" or "b64_json". Defaults to "url" (the link will be inactived in 60 minutes).style: The style of generated images (DALL-E 3 only). Can be either "vidid" or "natural". Defauls to "vidid".
kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: ADataMessageobject representing one or more generated images, including the rewritten prompt if relevant, status, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aigenerate, aiembed, aiclassify, aiextract, aiscan, aitemplates
Notes
This function DOES NOT SUPPORT multi-turn conversations (ie, do not provide previous conversation via
conversationargument).There is no token tracking provided by the API, so the messages will NOT report any cost despite costing you money!
You MUST download any URL-based images within 60 minutes. The links will become inactive.
Example
Generate an image:
# You can experiment with `image_size`, `image_quality` kwargs!\nmsg = aiimage("A white cat on a car")\n\n# Download the image into a file\nusing Downloads\nDownloads.download(msg.content[:url], "cat_on_car.png")\n\n# You can also see the revised prompt that DALL-E 3 used\nmsg.content[:revised_prompt]\n# Output: "Visualize a pristine white cat gracefully perched atop a shiny car. \n# The cat's fur is stark white and its eyes bright with curiosity. \n# As for the car, it could be a contemporary sedan, glossy and in a vibrant color. \n# The scene could be set under the blue sky, enhancing the contrast between the white cat, the colorful car, and the bright blue sky."Note that you MUST download any URL-based images within 60 minutes. The links will become inactive.
If you wanted to download image directly into the DataMessage, provide response_format="b64_json" in api_kwargs:
msg = aiimage("A white cat on a car"; image_quality="hd", api_kwargs=(; response_format="b64_json"))\n\n# Then you need to use Base64 package to decode it and save it to a file:\nusing Base64\nwrite("cat_on_car_hd.png", base64decode(msg.content[:b64_json]));aiimage(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiimage call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiimage(with thetracer_schema.schema)calls
finalize_tracer
aiscan([prompt_schema::AbstractOllamaSchema,] prompt::ALLOWED_PROMPT_TYPE; \nimage_url::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\nimage_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\nattach_to_latest::Bool = true,\nverbose::Bool = true, api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n http_kwargs::NamedTuple = (;\n retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), \n api_kwargs::NamedTuple = = (; max_tokens = 2500),\n kwargs...)Scans the provided image (image_url or image_path) with the goal provided in the prompt.
Can be used for many multi-modal tasks, such as: OCR (transcribe text in the image), image captioning, image classification, etc.
It's effectively a light wrapper around aigenerate call, which uses additional keyword arguments image_url, image_path, image_detail to be provided. At least one image source (url or path) must be provided.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateimage_url: A string or vector of strings representing the URL(s) of the image(s) to scan.image_path: A string or vector of strings representing the path(s) of the image(s) to scan.image_detail: A string representing the level of detail to include for images. Can be"auto","high", or"low". See OpenAI Vision Guide for more details.attach_to_latest: A boolean how to handle if a conversation with multipleUserMessageis provided. Whentrue, the images are attached to the latestUserMessage.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aigenerate, aiembed, aiclassify, aiextract, aitemplates
Notes
All examples below use model "gpt4v", which is an alias for model ID "gpt-4-vision-preview"
max_tokensin theapi_kwargsis preset to 2500, otherwise OpenAI enforces a default of only a few hundred tokens (~300). If your output is truncated, increase this value
Example
Describe the provided image:
msg = aiscan("Describe the image"; image_path="julia.png", model="bakllava")\n# [ Info: Tokens: 1141 @ Cost: $0.0117 in 2.2 seconds\n# AIMessage("The image shows a logo consisting of the word "julia" written in lowercase")You can provide multiple images at once as a vector and ask for "low" level of detail (cheaper):
msg = aiscan("Describe the image"; image_path=["julia.png","python.png"] model="bakllava")You can use this function as a nice and quick OCR (transcribe text in the image) with a template :OCRTask. Let's transcribe some SQL code from a screenshot (no more re-typing!):
using Downloads\n# Screenshot of some SQL code -- we cannot use image_url directly, so we need to download it first\nimage_url = "https://www.sqlservercentral.com/wp-content/uploads/legacy/8755f69180b7ac7ee76a69ae68ec36872a116ad4/24622.png"\nimage_path = Downloads.download(image_url)\nmsg = aiscan(:OCRTask; image_path, model="bakllava", task="Transcribe the SQL code in the image.", api_kwargs=(; max_tokens=2500))\n\n# AIMessage("```sql\n# update Orders <continue>\n\n# You can add syntax highlighting of the outputs via Markdown\nusing Markdown\nmsg.content |> Markdown.parseLocal models cannot handle image URLs directly (image_url), so you need to download the image first and provide it as image_path:
using Downloads\nimage_path = Downloads.download(image_url)Notice that we set max_tokens = 2500. If your outputs seem truncated, it might be because the default maximum tokens on the server is set too low!
aiscan([prompt_schema::AbstractOpenAISchema,] prompt::ALLOWED_PROMPT_TYPE; \nimage_url::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\nimage_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\nimage_detail::AbstractString = "auto",\nattach_to_latest::Bool = true,\nverbose::Bool = true, api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n http_kwargs::NamedTuple = (;\n retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), \n api_kwargs::NamedTuple = = (; max_tokens = 2500),\n kwargs...)Scans the provided image (image_url or image_path) with the goal provided in the prompt.
Can be used for many multi-modal tasks, such as: OCR (transcribe text in the image), image captioning, image classification, etc.
It's effectively a light wrapper around aigenerate call, which uses additional keyword arguments image_url, image_path, image_detail to be provided. At least one image source (url or path) must be provided.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplateimage_url: A string or vector of strings representing the URL(s) of the image(s) to scan.image_path: A string or vector of strings representing the path(s) of the image(s) to scan.image_detail: A string representing the level of detail to include for images. Can be"auto","high", or"low". See OpenAI Vision Guide for more details.attach_to_latest: A boolean how to handle if a conversation with multipleUserMessageis provided. Whentrue, the images are attached to the latestUserMessage.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.return_all::Bool=false: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments.kwargs: Prompt variables to be used to fill the prompt/template
Returns
If return_all=false (default):
msg: AnAIMessageobject representing the generated AI message, including the content, status, tokens, and elapsed time.
Use msg.content to access the extracted string.
If return_all=true:
conversation: A vector ofAbstractMessageobjects representing the full conversation history, including the response from the AI model (AIMessage).
See also: ai_str, aai_str, aigenerate, aiembed, aiclassify, aiextract, aitemplates
Notes
All examples below use model "gpt4v", which is an alias for model ID "gpt-4-vision-preview"
max_tokensin theapi_kwargsis preset to 2500, otherwise OpenAI enforces a default of only a few hundred tokens (~300). If your output is truncated, increase this value
Example
Describe the provided image:
msg = aiscan("Describe the image"; image_path="julia.png", model="gpt4v")\n# [ Info: Tokens: 1141 @ Cost: $0.0117 in 2.2 seconds\n# AIMessage("The image shows a logo consisting of the word "julia" written in lowercase")You can provide multiple images at once as a vector and ask for "low" level of detail (cheaper):
msg = aiscan("Describe the image"; image_path=["julia.png","python.png"], image_detail="low", model="gpt4v")You can use this function as a nice and quick OCR (transcribe text in the image) with a template :OCRTask. Let's transcribe some SQL code from a screenshot (no more re-typing!):
# Screenshot of some SQL code\nimage_url = "https://www.sqlservercentral.com/wp-content/uploads/legacy/8755f69180b7ac7ee76a69ae68ec36872a116ad4/24622.png"\nmsg = aiscan(:OCRTask; image_url, model="gpt4v", task="Transcribe the SQL code in the image.", api_kwargs=(; max_tokens=2500))\n\n# [ Info: Tokens: 362 @ Cost: $0.0045 in 2.5 seconds\n# AIMessage("```sql\n# update Orders <continue>\n\n# You can add syntax highlighting of the outputs via Markdown\nusing Markdown\nmsg.content |> Markdown.parseNotice that we enforce max_tokens = 2500. That's because OpenAI seems to default to ~300 tokens, which provides incomplete outputs. Hence, we set this value to 2500 as a default. If you still get truncated outputs, increase this value.
aiscan(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aiscan call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiscan(with thetracer_schema.schema)calls
finalize_tracer
aitemplatesFind easily the most suitable templates for your use case.
You can search by:
query::Symbolwhich looks look only for partial matches in the templatenamequery::AbstractStringwhich looks for partial matches in the templatenameordescriptionquery::Regexwhich looks for matches in the templatename,descriptionor any of the message previews
Keyword Arguments
limit::Intlimits the number of returned templates (Defaults to 10)
Examples
Find available templates with aitemplates:
tmps = aitemplates("JuliaExpertAsk")\n# Will surface one specific template\n# 1-element Vector{AITemplateMetadata}:\n# PromptingTools.AITemplateMetadata\n# name: Symbol JuliaExpertAsk\n# description: String "For asking questions about Julia language. Placeholders: `ask`"\n# version: String "1"\n# wordcount: Int64 237\n# variables: Array{Symbol}((1,))\n# system_preview: String "You are a world-class Julia language programmer with the knowledge of the latest syntax. Your commun"\n# user_preview: String "# Question\n\n{{ask}}"\n# source: String ""The above gives you a good idea of what the template is about, what placeholders are available, and how much it would cost to use it (=wordcount).
Search for all Julia-related templates:
tmps = aitemplates("Julia")\n# 2-element Vector{AITemplateMetadata}... -> more to come later!If you are on VSCode, you can leverage nice tabular display with vscodedisplay:
using DataFrames\ntmps = aitemplates("Julia") |> DataFrame |> vscodedisplayI have my selected template, how do I use it? Just use the "name" in aigenerate or aiclassify like you see in the first example!
Find the top-limit templates whose name or description fields partially match the query_key::String in TEMPLATE_METADATA.
Find the top-limit templates where provided query_key::Regex matches either of name, description or previews or User or System messages in TEMPLATE_METADATA.
Find the top-limit templates whose name::Symbol exactly matches the query_name::Symbol in TEMPLATE_METADATA.
aitools(prompt_schema::AbstractAnthropicSchema, prompt::ALLOWED_PROMPT_TYPE;\n kwargs...)\n tools::Union{Type, Function, Method, AbstractTool, Vector} = Tool[],\n verbose::Bool = true,\n api_key::String = ANTHROPIC_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n image_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\n cache::Union{Nothing, Symbol} = nothing,\n betas::Union{Nothing, Vector{Symbol}} = nothing,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = (;\n tool_choice = nothing),\n kwargs...)Calls chat completion API with an optional tool call signature. It can receive both tools and standard string-based content. Ideal for agentic workflows with more complex cognitive architectures.
Difference to aigenerate: Response can be a tool call (structured)
Differences to aiextract: Can provide infinitely many tools (including Functions!) and then respond with the tool call's output.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplatetools: A vector of tools to be used in the conversation. Can be a vector of types, instances ofAbstractTool, or a mix of both.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the Anthropic API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_CHAT.return_all: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history.no_system_message::Bool = false: Whether to exclude the system message from the conversation history.image_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing: A path to a local image file, or a vector of paths to local image files. Always attaches images to the latest user message.cache::Union{Nothing, Symbol} = nothing: Whether to cache the prompt. Defaults tonothing.betas::Union{Nothing, Vector{Symbol}} = nothing: A vector of symbols representing the beta features to be used. See?anthropic_extra_headersfor details.http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments. Several important arguments are highlighted below:tool_choice: The choice of tool mode. Can be "auto", "exact", or can depend on the provided.. Defaults tonothing, which translates to "auto".
Example
## Let's define a tool\nget_weather(location, date) = "The weather in $location on $date is 70 degrees."\n\nmsg = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather, model = "claudeh")\nPT.execute_tool(get_weather, msg.tool_calls[1].args)\n# "The weather in Tokyo on 2023-05-03 is 70 degrees."\n\n# Ignores the tool\nmsg = aitools("What's your name?";\n tools = get_weather, model = "claudeh")\n# I don't have a personal name, but you can call me your AI assistant!How to have a multi-turn conversation with tools:
conv = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather, return_all = true, model = "claudeh")\n\ntool_msg = conv[end].tool_calls[1] # there can be multiple tool calls requested!!\n\n# Execute the output to the tool message content\ntool_msg.content = PT.execute_tool(get_weather, tool_msg.args)\n\n# Add the tool message to the conversation\npush!(conv, tool_msg)\n\n# Call LLM again with the updated conversation\nconv = aitools(\n "And in New York?"; tools = get_weather, return_all = true, conversation = conv, model = "claudeh")\n# 6-element Vector{AbstractMessage}:\n# SystemMessage("Act as a helpful AI assistant")\n# UserMessage("What's the weather in Tokyo on May 3rd, 2023?")\n# AIToolRequest("-"; Tool Requests: 1)\n# ToolMessage("The weather in Tokyo on 2023-05-03 is 70 degrees.")\n# UserMessage("And in New York?")\n# AIToolRequest("-"; Tool Requests: 1)Using the the new Computer Use beta feature:
# Define tools (and associated functions to call)\ntool_map = Dict("bash" => PT.ToolRef(; ref=:bash, callable=bash_tool),\n "computer" => PT.ToolRef(; ref=:computer, callable=computer_tool,\n extras=Dict("display_width_px" => 1920, "display_height_px" => 1080)),\n "str_replace_editor" => PT.ToolRef(; ref=:str_replace_editor, callable=edit_tool))\n\nmsg = aitools(prompt; tools=collect(values(tool_map)), model="claude", betas=[:computer_use])\n\nPT.pprint(msg)\n# --------------------\n# AI Tool Request\n# --------------------\n# Tool Request: computer, args: Dict{Symbol, Any}(:action => "screenshot")aitools(prompt_schema::AbstractOpenAISchema, prompt::ALLOWED_PROMPT_TYPE;\n tools::Union{Type, Function, Method, AbstractTool, Vector} = Tool[],\n verbose::Bool = true,\n api_key::String = OPENAI_API_KEY,\n model::String = MODEL_CHAT,\n return_all::Bool = false, dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n image_path::Union{Nothing, AbstractString, Vector{<:AbstractString}} = nothing,\n http_kwargs::NamedTuple = (retry_non_idempotent = true,\n retries = 5,\n readtimeout = 120), api_kwargs::NamedTuple = (;\n tool_choice = nothing),\n strict::Union{Nothing, Bool} = nothing,\n json_mode::Union{Nothing, Bool} = nothing,\n name_user::Union{Nothing, String} = nothing,\n name_assistant::Union{Nothing, String} = nothing,\n kwargs...)Calls chat completion API with an optional tool call signature. It can receive both tools and standard string-based content. Ideal for agentic workflows with more complex cognitive architectures.
Difference to aigenerate: Response can be a tool call (structured)
Differences to aiextract: Can provide infinitely many tools (including Functions!) and then respond with the tool call's output.
Arguments
prompt_schema: An optional object to specify which prompt template should be applied (Default toPROMPT_SCHEMA = OpenAISchema)prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessageor anAITemplatetools: A vector of tools to be used in the conversation. Can be a vector of types, instances ofAbstractTool, or a mix of both.verbose: A boolean indicating whether to print additional information.api_key: A string representing the API key for accessing the OpenAI API.model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_CHAT.return_all: Iftrue, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run: Iftrue, skips sending the messages to the model (for debugging, often used withreturn_all=true).conversation: An optional vector ofAbstractMessageobjects representing the conversation history.no_system_message::Bool = false: Whether to exclude the system message from the conversation history.image_path: A path to a local image file, or a vector of paths to local image files. Always attaches images to the latest user message.name_user: The name of the user in the conversation history. Defaults to "User".name_assistant: The name of the assistant in the conversation history. Defaults to "Assistant".http_kwargs: A named tuple of HTTP keyword arguments.api_kwargs: A named tuple of API keyword arguments. Several important arguments are highlighted below:tool_choice: The choice of tool mode. Can be "auto", "exact", or can depend on the provided.. Defaults tonothing, which translates to "auto".response_format: The format of the response. Can be "json_schema" for JSON mode, or "text" for standard text output. Defaults to "text".
strict: Whether to enforce strict mode for the schema. Defaults tonothing.json_mode: Whether to enforce JSON mode for the schema. Defaults tonothing.
Example
## Let's define a tool\nget_weather(location, date) = "The weather in $location on $date is 70 degrees."\n\n## JSON mode request\nmsg = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather,\n json_mode = true)\nPT.execute_tool(get_weather, msg.tool_calls[1].args)\n# "The weather in Tokyo on 2023-05-03 is 70 degrees."\n\n# Function calling request\nmsg = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather)\nPT.execute_tool(get_weather, msg.tool_calls[1].args)\n# "The weather in Tokyo on 2023-05-03 is 70 degrees."\n\n# Ignores the tool\nmsg = aitools("What's your name?";\n tools = get_weather)\n# I don't have a personal name, but you can call me your AI assistant!How to have a multi-turn conversation with tools:
conv = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = get_weather, return_all = true)\n\ntool_msg = conv[end].tool_calls[1] # there can be multiple tool calls requested!!\n\n# Execute the output to the tool message content\ntool_msg.content = PT.execute_tool(get_weather, tool_msg.args)\n\n# Add the tool message to the conversation\npush!(conv, tool_msg)\n\n# Call LLM again with the updated conversation\nconv = aitools(\n "And in New York?"; tools = get_weather, return_all = true, conversation = conv)\n# 6-element Vector{AbstractMessage}:\n# SystemMessage("Act as a helpful AI assistant")\n# UserMessage("What's the weather in Tokyo on May 3rd, 2023?")\n# AIToolRequest("-"; Tool Requests: 1)\n# ToolMessage("The weather in Tokyo on 2023-05-03 is 70 degrees.")\n# UserMessage("And in New York?")\n# AIToolRequest("-"; Tool Requests: 1)aitools(tracer_schema::AbstractTracerSchema, prompt::ALLOWED_PROMPT_TYPE;\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Wraps the normal aitools call in a tracing/callback system. Use tracer_kwargs to provide any information necessary to the tracer/callback system only (eg, parent_id, thread_id, run_id).
Logic:
calls
initialize_tracercalls
aiextract(with thetracer_schema.schema)calls
finalize_tracer
Aligns multiple tracers in the vector to have the same Parent and Thread IDs as the first item.
Aligns the tracer message, updating the parent_id, thread_id. Often used to align multiple tracers in the vector to have the same IDs.
annotate!(messages::AbstractVector{<:AbstractMessage}, content; kwargs...)\nannotate!(message::AbstractMessage, content; kwargs...)Add an annotation message to a vector of messages or wrap a single message in a vector with an annotation. The annotation is always inserted after any existing annotation messages.
Arguments
messages: Vector of messages or single message to annotatecontent: Content of the annotationkwargs...: Additional fields for the AnnotationMessage (extras, tags, comment)
Returns
Vector{AbstractMessage} with the annotation message inserted
Example
messages = [SystemMessage("Assistant"), UserMessage("Hello")]\nannotate!(messages, "This is important"; tags=[:important], comment="For review")anthropic_api(\n prompt_schema::AbstractAnthropicSchema,\n messages::Vector{<:AbstractDict{String, <:Any}} = Vector{Dict{String, Any}}();\n api_key::AbstractString = ANTHROPIC_API_KEY,\n system::Union{Nothing, AbstractString, AbstractVector{<:AbstractDict}} = nothing,\n endpoint::String = "messages",\n max_tokens::Int = 2048,\n model::String = "claude-3-haiku-20240307", http_kwargs::NamedTuple = NamedTuple(),\n stream::Bool = false,\n url::String = "https://api.anthropic.com/v1",\n cache::Union{Nothing, Symbol} = nothing,\n betas::Union{Nothing, Vector{Symbol}} = nothing,\n kwargs...)Simple wrapper for a call to Anthropic API.
Keyword Arguments
prompt_schema: Defines which prompt template should be applied.messages: a vector ofAbstractMessageto send to the modelsystem: An optional string representing the system message for the AI conversation. If not provided, a default message will be used.endpoint: The API endpoint to call, only "messages" are currently supported. Defaults to "messages".model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.max_tokens: The maximum number of tokens to generate. Defaults to 2048.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.stream: A boolean indicating whether to stream the response. Defaults tofalse.url: The URL of the Ollama API. Defaults to "localhost".cache: A symbol representing the caching strategy to be used. Currently onlynothing(no caching),:system,:tools,:lastand:allare supported.betas: A vector of symbols representing the beta features to be used. Currently only:toolsand:cacheare supported.kwargs: Prompt variables to be used to fill the prompt/template
anthropic_extra_headers(;\n has_tools = false, has_cache = false, has_long_output = false,\n betas::Union{Nothing, Vector{Symbol}} = nothing)Adds API version and beta headers to the request.
Kwargs / Beta headers
has_tools: Enables tools in the conversation.has_cache: Enables prompt caching.has_long_output: Enables long outputs (up to 8K tokens) with Anthropic's Sonnet 3.5.betas: A vector of symbols representing the beta features to be used. Currently only:computer_use,:long_output,:toolsand:cacheare supported.
Refer to BETA_HEADERS_ANTHROPIC for the allowed beta features.
auth_header(api_key::Union{Nothing, AbstractString};\n bearer::Bool = true,\n x_api_key::Bool = false,\n extra_headers::AbstractVector = Vector{\n Pair{String, String},\n }[],\n kwargs...)Creates the authentication headers for any API request. Assumes that the communication is done in JSON format.
Arguments
api_key::Union{Nothing, AbstractString}: The API key to be used for authentication. IfNothing, no authentication is used.bearer::Bool: Provide the API key in theAuthorization: Bearer ABCformat. Defaults totrue.x_api_key::Bool: Provide the API key in theAuthorization: x-api-key: ABCformat. Defaults tofalse.
batch_start_index(array_length::Integer, n::Integer, batch_size::Integer) -> IntegerCompute the starting index for retrieving the most recent data, adjusting in blocks of batch_size. The function accumulates messages until hitting a batch boundary, then jumps to the next batch.
For example, with n=20 and batch_size=10:
At length 90-99: returns 80 (allowing accumulation of 11-20 messages)
At length 100-109: returns 90 (allowing accumulation of 11-20 messages)
At length 110: returns 100 (resetting to 11 messages)
build_template_metadata(\n template::AbstractVector{<:AbstractMessage}, template_name::Symbol,\n metadata_msgs::AbstractVector{<:MetadataMessage} = MetadataMessage[]; max_length::Int = 100)Builds AITemplateMetadata for a given template based on the messages in template and other information.
AITemplateMetadata is a helper struct for easy searching and reviewing of templates via aitemplates().
Note: Assumes that there is only ever one UserMessage and SystemMessage (concatenates them together)
call_cost(prompt_tokens::Int, completion_tokens::Int, model::String;\n cost_of_token_prompt::Number = get(MODEL_REGISTRY,\n model,\n (; cost_of_token_prompt = 0.0)).cost_of_token_prompt,\n cost_of_token_generation::Number = get(MODEL_REGISTRY, model,\n (; cost_of_token_generation = 0.0)).cost_of_token_generation)\n\ncall_cost(msg, model::String)Calculate the cost of a call based on the number of tokens in the message and the cost per token. If the cost is already calculated (in msg.cost), it will not be re-calculated.
Arguments
prompt_tokens::Int: The number of tokens used in the prompt.completion_tokens::Int: The number of tokens used in the completion.model::String: The name of the model to use for determining token costs. If the model is not found inMODEL_REGISTRY, default costs are used.cost_of_token_prompt::Number: The cost per prompt token. Defaults to the cost inMODEL_REGISTRYfor the given model, or 0.0 if the model is not found.cost_of_token_generation::Number: The cost per generation token. Defaults to the cost inMODEL_REGISTRYfor the given model, or 0.0 if the model is not found.
Returns
Number: The total cost of the call.
Examples
# Assuming MODEL_REGISTRY is set up with appropriate costs\nMODEL_REGISTRY = Dict(\n "model1" => (cost_of_token_prompt = 0.05, cost_of_token_generation = 0.10),\n "model2" => (cost_of_token_prompt = 0.07, cost_of_token_generation = 0.02)\n)\n\ncost1 = call_cost(10, 20, "model1")\n\n# from message\nmsg1 = AIMessage(;tokens=[10, 20]) # 10 prompt tokens, 20 generation tokens\ncost1 = call_cost(msg1, "model1")\n# cost1 = 10 * 0.05 + 20 * 0.10 = 2.5\n\n# Using custom token costs\ncost2 = call_cost(10, 20, "model3"; cost_of_token_prompt = 0.08, cost_of_token_generation = 0.12)\n# cost2 = 10 * 0.08 + 20 * 0.12 = 3.2call_cost_alternative()
Alternative cost calculation. Used to calculate cost of image generation with DALL-E 3 and similar.
configure_callback!(cb::StreamCallback, schema::AbstractPromptSchema;\n api_kwargs...)Configures the callback cb for streaming with a given prompt schema.
If no cb.flavor is provided, adjusts the flavor and the provided api_kwargs as necessary. Eg, for most schemas, we add kwargs like stream = true to the api_kwargs.
If cb.flavor is provided, both callback and api_kwargs are left unchanged! You need to configure them yourself!
', 73)), + createBaseVNode("div", _hoisted_3, [ + _cache[16] || (_cache[16] = createStaticVNode('# PromptingTools.create_template — Method.
create_template(; user::AbstractString, system::AbstractString="Act as a helpful AI assistant.", \n load_as::Union{Nothing, Symbol, AbstractString} = nothing)\n\ncreate_template(system::AbstractString, user::AbstractString, \n load_as::Union{Nothing, Symbol, AbstractString} = nothing)Creates a simple template with a user and system message. Convenience function to prevent writing [PT.UserMessage(...), ...]
Arguments
system::AbstractString: The system message. Usually defines the personality, style, instructions, output format, etc.user::AbstractString: The user message. Usually defines the input, query, request, etc.load_as::Union{Nothing, Symbol, AbstractString}: If provided, loads the template into theTEMPLATE_STOREunder the provided nameload_as. Ifnothing, does not load the template.
Returns a vector of SystemMessage and UserMessage objects. If load_as is provided, it registers the template in the TEMPLATE_STORE and TEMPLATE_METADATA as well.
Examples
Let's generate a quick template for a simple conversation (only one placeholder: name)
# first system message, then user message (or use kwargs)\ntpl=PT.create_template("You must speak like a pirate", "Say hi to {{name}}")\n\n## 2-element Vector{PromptingTools.AbstractChatMessage}:\n## PromptingTools.SystemMessage("You must speak like a pirate")\n## PromptingTools.UserMessage("Say hi to {{name}}")You can immediately use this template in ai* functions:
aigenerate(tpl; name="Jack Sparrow")\n# Output: AIMessage("Arr, me hearty! Best be sending me regards to Captain Jack Sparrow on the salty seas! May his compass always point true to the nearest treasure trove. Yarrr!")If you're interested in saving the template in the template registry, jump to the end of these examples!
If you want to save it in your project folder:
PT.save_template("templates/GreatingPirate.json", tpl; version="1.0") # optionally, add descriptionIt will be saved and accessed under its basename, ie, GreatingPirate.
Now you can load it like all the other templates (provide the template directory):
PT.load_templates!("templates") # it will remember the folder after the first run\n# Note: If you save it again, overwrite it, etc., you need to explicitly reload all templates again!You can verify that your template is loaded with a quick search for "pirate":
aitemplates("pirate")\n\n## 1-element Vector{AITemplateMetadata}:\n## PromptingTools.AITemplateMetadata\n## name: Symbol GreatingPirate\n## description: String ""\n## version: String "1.0"\n## wordcount: Int64 46\n## variables: Array{Symbol}((1,))\n## system_preview: String "You must speak like a pirate"\n## user_preview: String "Say hi to {{name}}"\n## source: String ""Now you can use it like any other template (notice it's a symbol, so :GreatingPirate):
aigenerate(:GreatingPirate; name="Jack Sparrow")\n# Output: AIMessage("Arr, me hearty! Best be sending me regards to Captain Jack Sparrow on the salty seas! May his compass always point true to the nearest treasure trove. Yarrr!")If you do not need to save this template as a file, but you want to make it accessible in the template store for all ai* functions, you can use the load_as (= template name) keyword argument:
# this will not only create the template, but also register it for immediate use\ntpl=PT.create_template("You must speak like a pirate", "Say hi to {{name}}"; load_as="GreatingPirate")\n\n# you can now use it like any other template\naiextract(:GreatingPirate; name="Jack Sparrow")decode_choices(schema::OpenAISchema,\n choices::AbstractVector{<:AbstractString},\n msg::AIMessage; model::AbstractString,\n token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing,\n kwargs...)Decodes the underlying AIMessage against the original choices to lookup what the category name was.
If it fails, it will return msg.content == nothing
detect_base_main_overrides(code_block::AbstractString)Detects if a given code block overrides any Base or Main methods.
Returns a tuple of a boolean and a vector of the overriden methods.
distance_longest_common_subsequence(\n input1::AbstractString, input2::AbstractString)\n\ndistance_longest_common_subsequence(\n input1::AbstractString, input2::AbstractVector{<:AbstractString})Measures distance between two strings using the length of the longest common subsequence (ie, the lower the number, the better the match). Perfect match is distance = 0.0
Convenience wrapper around length_longest_common_subsequence to normalize the distances to 0-1 range. There is a also a dispatch for comparing a string vs an array of strings.
Notes
Use
argminandminimumto find the position of the closest match and the distance, respectively.Matching with an empty string will always return 1.0 (worst match), even if the other string is empty as well (safety mechanism to avoid division by zero).
Arguments
input1::AbstractString: The first string to compare.input2::AbstractString: The second string to compare.
Example
You can also use it to find the closest context for some AI generated summary/story:
context = ["The enigmatic stranger vanished as swiftly as a wisp of smoke, leaving behind a trail of unanswered questions.",\n "Beneath the shimmering moonlight, the ocean whispered secrets only the stars could hear.",\n "The ancient tree stood as a silent guardian, its gnarled branches reaching for the heavens.",\n "The melody danced through the air, painting a vibrant tapestry of emotions.",\n "Time flowed like a relentless river, carrying away memories and leaving imprints in its wake."]\n\nstory = """\n Beneath the shimmering moonlight, the ocean whispered secrets only the stars could hear.\n\n Under the celestial tapestry, the vast ocean whispered its secrets to the indifferent stars. Each ripple, a murmured confidence, each wave, a whispered lament. The glittering celestial bodies listened in silent complicity, their enigmatic gaze reflecting the ocean's unspoken truths. The cosmic dance between the sea and the sky, a symphony of shared secrets, forever echoing in the ethereal expanse.\n """\n\ndist = distance_longest_common_subsequence(story, context)\n@info "The closest context to the query: "$(first(story,20))..." is: "$(context[argmin(dist)])" (distance: $(minimum(dist)))"encode_choices(schema::OpenAISchema, choices::AbstractVector{<:AbstractString};\n model::AbstractString,\n token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing,\n kwargs...)\n\nencode_choices(schema::OpenAISchema, choices::AbstractVector{T};\n model::AbstractString,\n token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing,\n kwargs...) where {T <: Tuple{<:AbstractString, <:AbstractString}}Encode the choices into an enumerated list that can be interpolated into the prompt and creates the corresponding logit biases (to choose only from the selected tokens).
Optionally, can be a vector tuples, where the first element is the choice and the second is the description.
There can be at most 40 choices provided.
Arguments
schema::OpenAISchema: The OpenAISchema object.choices::AbstractVector{<:Union{AbstractString,Tuple{<:AbstractString, <:AbstractString}}}: The choices to be encoded, represented as a vector of the choices directly, or tuples where each tuple contains a choice and its description.model::AbstractString: The model to use for encoding. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.token_ids_map::Union{Nothing, Dict{<:AbstractString, <:Integer}} = nothing: A dictionary mapping custom token IDs to their corresponding integer values. Ifnothing, it will use the default token IDs for the given model.kwargs...: Additional keyword arguments.
Returns
choices_prompt::AbstractString: The encoded choices as a single string, separated by newlines.logit_bias::Dict: The logit bias dictionary, where the keys are the token IDs and the values are the bias values.decode_ids::AbstractVector{<:AbstractString}: The decoded IDs of the choices.
Examples
choices_prompt, logit_bias, _ = PT.encode_choices(PT.OpenAISchema(), ["true", "false"])\nchoices_prompt # Output: "true for "true"\nfalse for "false"\nlogit_bias # Output: Dict(837 => 100, 905 => 100)\n\nchoices_prompt, logit_bias, _ = PT.encode_choices(PT.OpenAISchema(), ["animal", "plant"])\nchoices_prompt # Output: "1. "animal"\n2. "plant""\nlogit_bias # Output: Dict(16 => 100, 17 => 100)Or choices with descriptions:
choices_prompt, logit_bias, _ = PT.encode_choices(PT.OpenAISchema(), [("A", "any animal or creature"), ("P", "for any plant or tree"), ("O", "for everything else")])\nchoices_prompt # Output: "1. "A" for any animal or creature\n2. "P" for any plant or tree\n3. "O" for everything else"\nlogit_bias # Output: Dict(16 => 100, 17 => 100, 18 => 100)eval!(cb::AbstractCodeBlock;\n safe_eval::Bool = true,\n capture_stdout::Bool = true,\n prefix::AbstractString = "",\n suffix::AbstractString = "")Evaluates a code block cb in-place. It runs automatically when AICode is instantiated with a String.
Check the outcome of evaluation with Base.isvalid(cb). If ==true, provide code block has executed successfully.
Steps:
If
cb::AICodehas not been evaluated,cb.success = nothing. After the evaluation it will be eithertrueorfalsedepending on the outcomeParse the text in
cb.codeEvaluate the parsed expression
Capture outputs of the evaluated in
cb.output[OPTIONAL] Capture any stdout outputs (eg, test failures) in
cb.stdoutIf any error exception is raised, it is saved in
cb.errorFinally, if all steps were successful, success is set to
cb.success = true
Keyword Arguments
safe_eval::Bool: Iftrue, we first check for any Pkg operations (eg, installing new packages) and missing imports, then the code will be evaluated inside a bespoke scratch module (not to change any user variables)capture_stdout::Bool: Iftrue, we capture any stdout outputs (eg, test failures) incb.stdoutprefix::AbstractString: A string to be prepended to the code block before parsing and evaluation. Useful to add some additional code definition or necessary imports. Defaults to an empty string.suffix::AbstractString: A string to be appended to the code block before parsing and evaluation. Useful to check that tests pass or that an example executes. Defaults to an empty string.
execute_tool(f::Function, args::AbstractDict{Symbol, <:Any},\n context::AbstractDict{Symbol, <:Any} = Dict{Symbol, Any}();\n throw_on_error::Bool = true, unused_as_kwargs::Bool = false,\n kwargs...)Executes a function with the provided arguments.
Picks the function arguments in the following order:
:contextrefers to the context dictionary passed to the function.Then it looks for the arguments in the
contextdictionary.Then it looks for the arguments in the
argsdictionary.
Dictionary is un-ordered, so we need to sort the arguments first and then pass them to the function.
Arguments
f::Function: The function to execute.args::AbstractDict{Symbol, <:Any}: The arguments to pass to the function.context::AbstractDict{Symbol, <:Any}: Optional context to pass to the function, it will prioritized to get the argument values from.throw_on_error::Bool: Whether to throw an error if the tool execution fails. Defaults totrue.unused_as_kwargs::Bool: Whether to pass unused arguments as keyword arguments. Defaults tofalse. Function must support keyword arguments!kwargs...: Additional keyword arguments to pass to the function.
Example
my_function(x, y) = x + y\nexecute_tool(my_function, Dict(:x => 1, :y => 2))get_weather(date, location) = "The weather in $location on $date is 70 degrees."\ntool_map = PT.tool_call_signature(get_weather)\n\nmsg = aitools("What's the weather in Tokyo on May 3rd, 2023?";\n tools = collect(values(tool_map)))\n\nPT.execute_tool(tool_map, PT.tool_calls(msg)[1])\n# "The weather in Tokyo on 2023-05-03 is 70 degrees."extract_code_blocks(markdown_content::String) -> Vector{String}Extract Julia code blocks from a markdown string.
This function searches through the provided markdown content, identifies blocks of code specifically marked as Julia code (using the julia ... code fence patterns), and extracts the code within these blocks. The extracted code blocks are returned as a vector of strings, with each string representing one block of Julia code.
Note: Only the content within the code fences is extracted, and the code fences themselves are not included in the output.
See also: extract_code_blocks_fallback
Arguments
markdown_content::String: A string containing the markdown content from which Julia code blocks are to be extracted.
Returns
Vector{String}: A vector containing strings of extracted Julia code blocks. If no Julia code blocks are found, an empty vector is returned.
Examples
Example with a single Julia code block
markdown_single = """julia println("Hello, World!")
"""\nextract_code_blocks(markdown_single)\n# Output: ["Hello, World!"]# Example with multiple Julia code blocks\nmarkdown_multiple = """julia x = 5
Some text in betweenjulia y = x + 2
"""\nextract_code_blocks(markdown_multiple)\n# Output: ["x = 5", "y = x + 2"]extract_code_blocks_fallback(markdown_content::String, delim::AbstractString="\\n```\\n")Extract Julia code blocks from a markdown string using a fallback method (splitting by arbitrary delim-iters). Much more simplistic than extract_code_blocks and does not support nested code blocks.
It is often used as a fallback for smaller LLMs that forget to code fence julia ....
Example
code = """println("hello")
\nSome textprintln("world")
"""\n\n# We extract text between triple backticks and check each blob if it looks like a valid Julia code\ncode_parsed = extract_code_blocks_fallback(code) |> x -> filter(is_julia_code, x) |> x -> join(x, "\n")extract_function_name(code_block::String) -> Union{String, Nothing}Extract the name of a function from a given Julia code block. The function searches for two patterns:
The explicit function declaration pattern:
function name(...) ... endThe concise function declaration pattern:
name(...) = ...
If a function name is found, it is returned as a string. If no function name is found, the function returns nothing.
To capture all function names in the block, use extract_function_names.
Arguments
code_block::String: A string containing Julia code.
Returns
Union{String, Nothing}: The extracted function name ornothingif no name is found.
Example
code = """\nfunction myFunction(arg1, arg2)\n # Function body\nend\n"""\nextract_function_name(code)\n# Output: "myFunction"extract_function_names(code_block::AbstractString)Extract one or more names of functions defined in a given Julia code block. The function searches for two patterns: - The explicit function declaration pattern: function name(...) ... end - The concise function declaration pattern: name(...) = ...
It always returns a vector of strings, even if only one function name is found (it will be empty).
For only one function name match, use extract_function_name.
extract_image_attributes(image_url::AbstractString) -> Tuple{String, String}Extracts the data type and base64-encoded data from a data URL.
Arguments
image_url::AbstractString: The data URL to be parsed.
Returns
Tuple{String, String}: A tuple containing the data type (e.g., "image/png") and the base64-encoded data.
Example
image_url = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABQAA"\ndata_type, data = extract_data_type_and_data(image_url)\n# data_type == "image/png"\n# data == "iVBORw0KGgoAAAANSUhEUgAABQAA"extract_julia_imports(input::AbstractString; base_or_main::Bool = false)Detects any using or import statements in a given string and returns the package names as a vector of symbols.
base_or_main is a boolean that determines whether to isolate only Base and Main OR whether to exclude them in the returned vector.
finalize_outputs(prompt::ALLOWED_PROMPT_TYPE, conv_rendered::Any,\n msg::Union{Nothing, AbstractMessage, AbstractVector{<:AbstractMessage}};\n return_all::Bool = false,\n dry_run::Bool = false,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n kwargs...)Finalizes the outputs of the ai* functions by either returning the conversation history or the last message.
Keyword arguments
return_all::Bool=false: If true, returns the entire conversation history, otherwise returns only the last message (theAIMessage).dry_run::Bool=false: If true, does not send the messages to the model, but only renders the prompt with the given schema and replacement variables. Useful for debugging when you want to check the specific schema rendering.conversation::AbstractVector{<:AbstractMessage}=[]: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.kwargs...: Variables to replace in the prompt template.no_system_message::Bool=false: If true, the default system message is not included in the conversation history. Any existing system message is converted to aUserMessage.
finalize_tracer(\n tracer_schema::AbstractTracerSchema, tracer, msg_or_conv::Union{\n AbstractMessage, AbstractVector{<:AbstractMessage}};\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Finalizes the calltracer of whatever is nedeed after the ai* calls. Use tracer_kwargs to provide any information necessary (eg, parent_id, thread_id, run_id).
In the default implementation, we convert all non-tracer messages into TracerMessage.
See also: meta, unwrap, SaverSchema, initialize_tracer
finalize_tracer(\n tracer_schema::SaverSchema, tracer, msg_or_conv::Union{\n AbstractMessage, AbstractVector{<:AbstractMessage}};\n tracer_kwargs = NamedTuple(), model = "", kwargs...)Finalizes the calltracer by saving the provided conversation msg_or_conv to the disk.
Default path is LOG_DIR/conversation__<first_msg_hash>__<time_received_str>.json, where LOG_DIR is set by user preferences or ENV variable (defaults to log/ in current working directory).
If you want to change the logging directory or the exact file name to log with, you can provide the following arguments to tracer_kwargs:
log_dir- used as the directory to save the log into when provided. Defaults toLOG_DIRif not provided.log_file_path- used as the file name to save the log into when provided. This value overrules thelog_dirandLOG_DIRif provided.
It can be composed with TracerSchema to also attach necessary metadata (see below).
Example
wrap_schema = PT.SaverSchema(PT.TracerSchema(PT.OpenAISchema()))\nconv = aigenerate(wrap_schema,:BlankSystemUser; system="You're a French-speaking assistant!",\n user="Say hi!"; model="gpt-4", api_kwargs=(;temperature=0.1), return_all=true)\n\n# conv is a vector of messages that will be saved to a JSON together with metadata about the template and api_kwargsSee also: meta, unwrap, TracerSchema, initialize_tracer
find_subsequence_positions(subseq, seq) -> Vector{Int}Find all positions of a subsequence subseq within a larger sequence seq. Used to lookup positions of code blocks in markdown.
This function scans the sequence seq and identifies all starting positions where the subsequence subseq is found. Both subseq and seq should be vectors of integers, typically obtained using codeunits on strings.
Arguments
subseq: A vector of integers representing the subsequence to search for.seq: A vector of integers representing the larger sequence in which to search.
Returns
Vector{Int}: A vector of starting positions (1-based indices) where the subsequence is found in the sequence.
Examples
find_subsequence_positions(codeunits("ab"), codeunits("cababcab")) # Returns [2, 5]generate_struct(fields::Vector)Generate a struct with the given name and fields. Fields can be specified simply as symbols (with default type String) or pairs of symbol and type. Field descriptions can be provided by adding a pair with the field name suffixed with "**description" (eg, :myfield**description => "My field description").
Returns: A tuple of (struct type, descriptions)
Examples
Weather, descriptions = generate_struct(\n [:location,\n :temperature=>Float64,\n :temperature__description=>"Temperature in degrees Fahrenheit",\n :condition=>String,\n :condition__description=>"Current weather condition (e.g., sunny, rainy, cloudy)"\n ])Get the argument names from a function, ignores keyword arguments!!
Get the argument names from a method, ignores keyword arguments!!
Get the argument types from a function, ignores keyword arguments!!
Get the argument types from a method, ignores keyword arguments!!
get_last(mem::ConversationMemory, n::Integer=20;\n batch_size::Union{Nothing,Integer}=nothing,\n verbose::Bool=false,\n explain::Bool=false)Get the last n messages (but including system message) with intelligent batching to preserve caching.
Arguments:
n::Integer: Maximum number of messages to return (default: 20)
batch_size::Union{Nothing,Integer}: If provided, ensures messages are truncated in fixed batches
verbose::Bool: Print detailed information about truncation
explain::Bool: Add explanation about truncation in the response
Returns: Vector{AbstractMessage} with the selected messages, always including:
The system message (if present)
First user message
Messages up to n, respecting batch_size boundaries
Once you get your full conversation back, you can use append!(mem, conversation) to merge the new messages into the memory.
Examples:
# Basic usage - get last 3 messages\nmem = ConversationMemory()\npush!(mem, SystemMessage("You are helpful"))\npush!(mem, UserMessage("Hello"))\npush!(mem, AIMessage("Hi!"))\npush!(mem, UserMessage("How are you?"))\npush!(mem, AIMessage("I'm good!"))\nmessages = get_last(mem, 3)\n\n# Using batch_size for caching efficiency\nmessages = get_last(mem, 10; batch_size=5) # Aligns to 5-message batches for caching\n\n# Add explanation about truncation\nmessages = get_last(mem, 3; explain=true) # Adds truncation note to first AI message so the model knows it's truncated\n\n# Get verbose output about truncation\nmessages = get_last(mem, 3; verbose=true) # Prints info about truncationget_preferences(key::String)Get preferences for PromptingTools. See ?PREFERENCES for more information.
See also: set_preferences!
Example
PromptingTools.get_preferences("MODEL_CHAT")Stub - to be extended in extension: GoogleGenAIPromptingToolsExt. ggi stands for GoogleGenAI
Checks if a given string has a Julia prompt (julia>) at the beginning of a line.
initialize_tracer(\n tracer_schema::AbstractTracerSchema; model = "", tracer_kwargs = NamedTuple(),\n prompt::ALLOWED_PROMPT_TYPE = "", kwargs...)Initializes tracer/callback (if necessary). Can provide any keyword arguments in tracer_kwargs (eg, parent_id, thread_id, run_id). Is executed prior to the ai* calls.
By default it captures:
time_sent: the time the request was sentmodel: the model to usemeta: a dictionary of additional metadata that is not part of the tracer itselftemplate_name: the template to use if anytemplate_version: the template version to use if anyexpanded
api_kwargs, ie, the keyword arguments to pass to the API call
In the default implementation, we just collect the necessary data to build the tracer object in finalize_tracer.
See also: meta, unwrap, TracerSchema, SaverSchema, finalize_tracer
Check if the object is an instance of AbstractExtractedData
Helpful accessor for the last message in conversation. Returns the last message in the conversation.
last_message(mem::ConversationMemory)Get the last message in the conversation.
Helpful accessor for the last generated output (msg.content) in conversation. Returns the last output in the conversation (eg, the string/data in the last message).
last_output(mem::ConversationMemory)Get the last AI message in the conversation.
length_longest_common_subsequence(itr1::AbstractString, itr2::AbstractString)Compute the length of the longest common subsequence between two string sequences (ie, the higher the number, the better the match).
Arguments
itr1: The first sequence, eg, a String.itr2: The second sequence, eg, a String.
Returns
The length of the longest common subsequence.
Examples
text1 = "abc-abc----"\ntext2 = "___ab_c__abc"\nlongest_common_subsequence(text1, text2)\n# Output: 6 (-> "abcabc")It can be used to fuzzy match strings and find the similarity between them (Tip: normalize the match)
commands = ["product recommendation", "emotions", "specific product advice", "checkout advice"]\nquery = "Which product can you recommend for me?"\nlet pos = argmax(length_longest_common_subsequence.(Ref(query), commands))\n dist = length_longest_common_subsequence(query, commands[pos])\n norm = dist / min(length(query), length(commands[pos]))\n @info "The closest command to the query: "$(query)" is: "$(commands[pos])" (distance: $(dist), normalized: $(norm))"\nendBut it might be easier to use directly the convenience wrapper distance_longest_common_subsequence!
\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/utils.jl#L252-L288)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.list_aliases-Tuple{}' href='#PromptingTools.list_aliases-Tuple{}'>#</a> <b><u>PromptingTools.list_aliases</u></b> — <i>Method</i>.\n\n\n\n\nShows the Dictionary of model aliases in the registry. Add more with `MODEL_ALIASES[alias] = model_name`.\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/user_preferences.jl#L1257)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.list_registry-Tuple{}' href='#PromptingTools.list_registry-Tuple{}'>#</a> <b><u>PromptingTools.list_registry</u></b> — <i>Method</i>.\n\n\n\n\nShows the list of models in the registry. Add more with `register_model!`.\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/user_preferences.jl#L1255)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.load_api_keys!-Tuple{}' href='#PromptingTools.load_api_keys!-Tuple{}'>#</a> <b><u>PromptingTools.load_api_keys!</u></b> — <i>Method</i>.\n\n\n\n\nLoads API keys from environment variables and preferences\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/user_preferences.jl#L178)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.load_conversation-Tuple{Union{AbstractString, IO}}' href='#PromptingTools.load_conversation-Tuple{Union{AbstractString, IO}}'>#</a> <b><u>PromptingTools.load_conversation</u></b> — <i>Method</i>.\n\n\n\n\n```julia\nload_conversation(io_or_file::Union{IO, AbstractString})Loads a conversation (messages) from io_or_file
load_template(io_or_file::Union{IO, AbstractString})Loads messaging template from io_or_file and returns tuple of template messages and metadata.
load_templates!(dir_templates::Union{String, Nothing} = nothing;\n remember_path::Bool = true,\n remove_templates::Bool = isnothing(dir_templates),\n store::Dict{Symbol, <:Any} = TEMPLATE_STORE,\n metadata_store::Vector{<:AITemplateMetadata} = TEMPLATE_METADATA)Loads templates from folder templates/ in the package root and stores them in TEMPLATE_STORE and TEMPLATE_METADATA.
Note: Automatically removes any existing templates and metadata from TEMPLATE_STORE and TEMPLATE_METADATA if remove_templates=true.
Arguments
dir_templates::Union{String, Nothing}: The directory path to load templates from. Ifnothing, uses the default list of paths. It usually used only once "to register" a new template storage.remember_path::Bool=true: If true, remembers the path for future refresh (inTEMPLATE_PATH).remove_templates::Bool=isnothing(dir_templates): If true, removes any existing templates and metadata fromstoreandmetadata_store.store::Dict{Symbol, <:Any}=TEMPLATE_STORE: The store to load the templates into.metadata_store::Vector{<:AITemplateMetadata}=TEMPLATE_METADATA: The metadata store to load the metadata into.
Example
Load the default templates:
PT.load_templates!() # no path neededLoad templates from a new custom path:
PT.load_templates!("path/to/templates") # we will remember this path for future refreshIf you want to now refresh the default templates and the new path, just call load_templates!() without any arguments.
Extracts the metadata dictionary from the tracer message or tracer-like object.
ollama_api(prompt_schema::Union{AbstractOllamaManagedSchema, AbstractOllamaSchema},\n prompt::Union{AbstractString, Nothing} = nothing;\n system::Union{Nothing, AbstractString} = nothing,\n messages::Vector{<:AbstractMessage} = AbstractMessage[],\n endpoint::String = "generate",\n model::String = "llama2", http_kwargs::NamedTuple = NamedTuple(),\n stream::Bool = false,\n url::String = "localhost", port::Int = 11434,\n kwargs...)Simple wrapper for a call to Ollama API.
Keyword Arguments
prompt_schema: Defines which prompt template should be applied.prompt: Can be a string representing the prompt for the AI conversation, aUserMessage, a vector ofAbstractMessagesystem: An optional string representing the system message for the AI conversation. If not provided, a default message will be used.endpoint: The API endpoint to call, only "generate" and "embeddings" are currently supported. Defaults to "generate".model: A string representing the model to use for generating the response. Can be an alias corresponding to a model ID defined inMODEL_ALIASES.http_kwargs::NamedTuple: Additional keyword arguments for the HTTP request. Defaults to emptyNamedTuple.stream: A boolean indicating whether to stream the response. Defaults tofalse.streamcallback::Any: A callback function to handle streaming responses. Can be simplystdoutor aStreamCallbackobject. See?StreamCallbackfor details.url: The URL of the Ollama API. Defaults to "localhost".port: The port of the Ollama API. Defaults to 11434.kwargs: Prompt variables to be used to fill the prompt/template
parse_tool(datatype::Type, blob::AbstractString; kwargs...)Parse the JSON blob into the specified datatype in try-catch mode.
If parsing fails, it tries to return the untyped JSON blob in a dictionary.
pprint(io::IO, conversation::AbstractVector{<:AbstractMessage})Pretty print a vector of AbstractMessage to the given IO stream.
pprint(io::IO, msg::AbstractMessage; text_width::Int = displaysize(io)[2])Pretty print a single AbstractMessage to the given IO stream.
text_width is the width of the text to be displayed. If not provided, it defaults to the width of the given IO stream and add newline separators as needed.
Utility for rendering the conversation (vector of messages) as markdown. REQUIRES the Markdown package to load the extension! See also pprint
push_conversation!(conv_history, conversation::AbstractVector, max_history::Union{Int, Nothing})Add a new conversation to the conversation history and resize the history if necessary.
This function appends a conversation to the conv_history, which is a vector of conversations. Each conversation is represented as a vector of AbstractMessage objects. After adding the new conversation, the history is resized according to the max_history parameter to ensure that the size of the history does not exceed the specified limit.
Arguments
conv_history: A vector that stores the history of conversations. Typically, this isPT.CONV_HISTORY.conversation: The new conversation to be added. It should be a vector ofAbstractMessageobjects.max_history: The maximum number of conversations to retain in the history. IfNothing, the history is not resized.
Returns
The updated conversation history.
Example
new_conversation = aigenerate("Hello World"; return_all = true)\npush_conversation!(PT.CONV_HISTORY, new_conversation, 10)This is done automatically by the ai"" macros.
recursive_splitter(text::AbstractString, separators::Vector{String}; max_length::Int=35000) -> Vector{String}Split a given string text into chunks recursively using a series of separators, with each chunk having a maximum length of max_length (if it's achievable given the separators provided). This function is useful for splitting large documents or texts into smaller segments that are more manageable for processing, particularly for models or systems with limited context windows.
It was previously known as split_by_length.
This is similar to Langchain's RecursiveCharacterTextSplitter. To achieve the same behavior, use separators=["\\n\\n", "\\n", " ", ""].
Arguments
text::AbstractString: The text to be split.separators::Vector{String}: An ordered list of separators used to split the text. The function iteratively applies these separators to split the text. Recommend to use["\\n\\n", ". ", "\\n", " "]max_length::Int: The maximum length of each chunk. Defaults to 35,000 characters. This length is considered after each iteration of splitting, ensuring chunks fit within specified constraints.
Returns
Vector{String}: A vector of strings, where each string is a chunk of the original text that is smaller than or equal to max_length.
Usage Tips
I tend to prefer splitting on sentences (
". ") before splitting on newline characters ("\\n") to preserve the structure of the text.What's the difference between
separators=["\\n"," ",""]andseparators=["\\n"," "]? The former will split down to character level (""), so it will always achieve themax_lengthbut it will split words (bad for context!) I prefer to instead set slightly smallermax_lengthbut not split words.
How It Works
The function processes the text iteratively with each separator in the provided order. It then measures the length of each chunk and splits it further if it exceeds the
max_length. If the chunks is "short enough", the subsequent separators are not applied to it.Each chunk is as close to
max_lengthas possible (unless we cannot split it any further, eg, if the splitters are "too big" / there are not enough of them)If the
textis empty, the function returns an empty array.Separators are re-added to the text chunks after splitting, preserving the original structure of the text as closely as possible. Apply
stripif you do not need them.The function provides
separatorsas the second argument to distinguish itself from its single-separator counterpart dispatch.
Examples
Splitting text using multiple separators:
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n"] # split by paragraphs, sentences, and newlines (not by words)\nchunks = recursive_splitter(text, separators, max_length=20)Splitting text using multiple separators - with splitting on words:
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", ". ", "\\n", " "] # split by paragraphs, sentences, and newlines, words\nchunks = recursive_splitter(text, separators, max_length=10)Using a single separator:
text = "Hello,World," ^ 2900 # length 34900 characters\nchunks = recursive_splitter(text, [","], max_length=10000)To achieve the same behavior as Langchain's RecursiveCharacterTextSplitter, use separators=["\\n\\n", "\\n", " ", ""].
text = "Paragraph 1\\n\\nParagraph 2. Sentence 1. Sentence 2.\\nParagraph 3"\nseparators = ["\\n\\n", "\\n", " ", ""]\nchunks = recursive_splitter(text, separators, max_length=10)recursive_splitter(text::String; separator::String=" ", max_length::Int=35000) -> Vector{String}Split a given string text into chunks of a specified maximum length max_length. This is particularly useful for splitting larger documents or texts into smaller segments, suitable for models or systems with smaller context windows.
There is a method for dispatching on multiple separators, recursive_splitter(text::String, separators::Vector{String}; max_length::Int=35000) -> Vector{String} that mimics the logic of Langchain's RecursiveCharacterTextSplitter.
Arguments
text::String: The text to be split.separator::String=" ": The separator used to split the text into minichunks. Defaults to a space character.max_length::Int=35000: The maximum length of each chunk. Defaults to 35,000 characters, which should fit within 16K context window.
Returns
Vector{String}: A vector of strings, each representing a chunk of the original text that is smaller than or equal to max_length.
Notes
The function ensures that each chunk is as close to
max_lengthas possible without exceeding it.If the
textis empty, the function returns an empty array.The
separatoris re-added to the text chunks after splitting, preserving the original structure of the text as closely as possible.
Examples
Splitting text with the default separator (" "):
text = "Hello world. How are you?"\nchunks = recursive_splitter(text; max_length=13)\nlength(chunks) # Output: 2Using a custom separator and custom max_length
text = "Hello,World," ^ 2900 # length 34900 chars\nrecursive_splitter(text; separator=",", max_length=10000) # for 4K context window\nlength(chunks[1]) # Output: 4register_model!(registry = MODEL_REGISTRY;\n name::String,\n schema::Union{AbstractPromptSchema, Nothing} = nothing,\n cost_of_token_prompt::Float64 = 0.0,\n cost_of_token_generation::Float64 = 0.0,\n description::String = "")Register a new AI model with name and its associated schema.
Registering a model helps with calculating the costs and automatically selecting the right prompt schema.
Arguments
name: The name of the model. This is the name that will be used to refer to the model in theai*functions.schema: The schema of the model. This is the schema that will be used to generate prompts for the model, eg,OpenAISchema().cost_of_token_prompt: The cost of a token in the prompt for this model. This is used to calculate the cost of a prompt. Note: It is often provided online as cost per 1000 tokens, so make sure to convert it correctly!cost_of_token_generation: The cost of a token generated by this model. This is used to calculate the cost of a generation. Note: It is often provided online as cost per 1000 tokens, so make sure to convert it correctly!description: A description of the model. This is used to provide more information about the model when it is queried.
remove_field!(parameters::AbstractDict, field::AbstractString)Utility to remove a specific top-level field from the parameters (and the required list if present) of the JSON schema.
remove_julia_prompt(s::T) where {T<:AbstractString}If it detects a julia prompt, it removes it and all lines that do not have it (except for those that belong to the code block).
remove_templates!()Removes all templates from TEMPLATE_STORE and TEMPLATE_METADATA.
Iterates over the lines of a string and removes those that contain a package operation or a missing import.
Renders provided messaging template (template) under the default schema (PROMPT_SCHEMA).
render(schema::AbstractAnthropicSchema,\n tool::ToolRef;\n kwargs...)Renders the tool reference into the Anthropic format.
Available tools:
:computer: A tool for using the computer.:str_replace_editor: A tool for replacing text in a string.:bash: A tool for running bash commands.
', 107)), + createBaseVNode("div", _hoisted_4, [ + _cache[20] || (_cache[20] = createStaticVNode('# PromptingTools.render — Method.
render(schema::AbstractAnthropicSchema,\n messages::Vector{<:AbstractMessage};\n aiprefill::Union{Nothing, AbstractString} = nothing,\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n cache::Union{Nothing, Symbol} = nothing,\n kwargs...)Keyword Arguments
aiprefill: A string to be used as a prefill for the AI response. This steer the AI response in a certain direction (and potentially save output tokens).conversation: Past conversation to be included in the beginning of the prompt (for continued conversations).no_system_message: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.cache: A symbol representing the caching strategy to be used. Currently onlynothing(no caching),:system,:tools,:lastand:allare supported.
render(schema::AbstractAnthropicSchema,\n tools::Vector{<:AbstractTool};\n kwargs...)Renders the tool signatures into the Anthropic format.
', 3)), + createBaseVNode("div", _hoisted_5, [ + _cache[24] || (_cache[24] = createStaticVNode('# PromptingTools.render — Method.
render(schema::AbstractGoogleSchema,\n messages::Vector{<:AbstractMessage};\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n kwargs...)Keyword Arguments
conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message::Bool=false: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.
render(schema::AbstractOllamaManagedSchema,\n messages::Vector{<:AbstractMessage};\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n kwargs...)render(schema::AbstractOllamaSchema,\n messages::Vector{<:AbstractMessage};\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n kwargs...)Keyword Arguments
conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.
render(schema::AbstractOpenAISchema,\n messages::Vector{<:AbstractMessage};\n image_detail::AbstractString = "auto",\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n name_user::Union{Nothing, String} = nothing,\n kwargs...)Keyword Arguments
image_detail: Only forUserMessageWithImages. It represents the level of detail to include for images. Can be"auto","high", or"low".conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.name_user: No-op for consistency.
render(schema::AbstractOpenAISchema,\n tools::Vector{<:AbstractTool};\n json_mode::Union{Nothing, Bool} = nothing,\n kwargs...)Renders the tool signatures into the OpenAI format.
render(tracer_schema::AbstractTracerSchema,\n conv::AbstractVector{<:AbstractMessage}; kwargs...)Passthrough. No changes.
', 5)), + createBaseVNode("div", _hoisted_9, [ + _cache[45] || (_cache[45] = createStaticVNode('# PromptingTools.render — Method.
render(schema::NoSchema,\n messages::Vector{<:AbstractMessage};\n conversation::AbstractVector{<:AbstractMessage} = AbstractMessage[],\n no_system_message::Bool = false,\n replacement_kwargs...)Renders a conversation history from a vector of messages with all replacement variables specified in replacement_kwargs.
It is the first pass of the prompt rendering system, and is used by all other schemas.
Keyword Arguments
image_detail: Only forUserMessageWithImages. It represents the level of detail to include for images. Can be"auto","high", or"low".conversation: An optional vector ofAbstractMessageobjects representing the conversation history. If not provided, it is initialized as an empty vector.no_system_message: Iftrue, do not include the default system message in the conversation history OR convert any provided system message to a user message.
Notes
', 12)), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + _cache[41] || (_cache[41] = createTextVNode("All unspecified kwargs are passed as replacements such that ")), + createBaseVNode("code", null, toDisplayString(_ctx.key) + "=>value", 1), + _cache[42] || (_cache[42] = createTextVNode(" in the template.")) + ]) + ]), + _cache[43] || (_cache[43] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "If a SystemMessage is missing, we inject a default one at the beginning of the conversation.") + ], -1)), + _cache[44] || (_cache[44] = createBaseVNode("li", null, [ + createBaseVNode("p", null, "Only one SystemMessage is allowed (ie, cannot mix two conversations different system prompts).") + ], -1)) + ]), + _cache[46] || (_cache[46] = createBaseVNode("p", null, [ + createBaseVNode("a", { + href: "https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/llm_shared.jl#L12-L32", + target: "_blank", + rel: "noreferrer" + }, "source") + ], -1)) + ]), + _cache[56] || (_cache[56] = createStaticVNode('replace_words(text::AbstractString, words::Vector{<:AbstractString}; replacement::AbstractString="ABC")Replace all occurrences of words in words with replacement in text. Useful to quickly remove specific names or entities from a text.
Arguments
text::AbstractString: The text to be processed.words::Vector{<:AbstractString}: A vector of words to be replaced.replacement::AbstractString="ABC": The replacement string to be used. Defaults to "ABC".
Example
text = "Disney is a great company"\nreplace_words(text, ["Disney", "Snow White", "Mickey Mouse"])\n# Output: "ABC is a great company"resize_conversation!(conv_history, max_history::Union{Int, Nothing})Resize the conversation history to a specified maximum length.
This function trims the conv_history to ensure that its size does not exceed max_history. It removes the oldest conversations first if the length of conv_history is greater than max_history.
Arguments
conv_history: A vector that stores the history of conversations. Typically, this isPT.CONV_HISTORY.max_history: The maximum number of conversations to retain in the history. IfNothing, the history is not resized.
Returns
The resized conversation history.
Example
resize_conversation!(PT.CONV_HISTORY, PT.MAX_HISTORY_LENGTH)After the function call, conv_history will contain only the 10 most recent conversations.
This is done automatically by the ai"" macros.
response_to_message(schema::AbstractOpenAISchema,\n MSG::Type{AIMessage},\n choice,\n resp;\n model_id::AbstractString = "",\n time::Float64 = 0.0,\n run_id::Int = Int(rand(Int32)),\n sample_id::Union{Nothing, Integer} = nothing,\n name_assistant::Union{Nothing, String} = nothing)Utility to facilitate unwrapping of HTTP response to a message type MSG provided for OpenAI-like responses
Note: Extracts finish_reason and log_prob if available in the response.
Arguments
schema::AbstractOpenAISchema: The schema for the prompt.MSG::Type{AIMessage}: The message type to be returned.choice: The choice from the response (eg, one of the completions).resp: The response from the OpenAI API.model_id::AbstractString: The model ID to use for generating the response. Defaults to an empty string.time::Float64: The elapsed time for the response. Defaults to0.0.run_id::Integer: The run ID for the response. Defaults to a random integer.sample_id::Union{Nothing, Integer}: The sample ID for the response (if there are multiple completions). Defaults tonothing.name_assistant::Union{Nothing, String}: The name to use for the assistant in the conversation history. Defaults tonothing.
Utility to facilitate unwrapping of HTTP response to a message type MSG provided. Designed to handle multi-sample completions.
save_conversation(io_or_file::Union{IO, AbstractString},\n messages::AbstractVector{<:AbstractMessage})Saves provided conversation (messages) to io_or_file. If you need to add some metadata, see save_template.
save_conversations(schema::AbstractPromptSchema, filename::AbstractString,\n conversations::Vector{<:AbstractVector{<:PT.AbstractMessage}})Saves provided conversations (vector of vectors of messages) to filename rendered in the particular schema.
Commonly used for finetuning models with schema = ShareGPTSchema()
The format is JSON Lines, where each line is a JSON object representing one provided conversation.
See also: save_conversation
Examples
You must always provide a VECTOR of conversations
messages = AbstractMessage[SystemMessage("System message 1"),\n UserMessage("User message"),\n AIMessage("AI message")]\nconversation = [messages] # vector of vectors\n\ndir = tempdir()\nfn = joinpath(dir, "conversations.jsonl")\nsave_conversations(fn, conversation)\n\n# Content of the file (one line for each conversation)\n# {"conversations":[{"value":"System message 1","from":"system"},{"value":"User message","from":"human"},{"value":"AI message","from":"gpt"}]}save_template(io_or_file::Union{IO, AbstractString},\n messages::AbstractVector{<:AbstractChatMessage};\n content::AbstractString = "Template Metadata",\n description::AbstractString = "",\n version::AbstractString = "1",\n source::AbstractString = "")Saves provided messaging template (messages) to io_or_file. Automatically adds metadata based on provided keyword arguments.
set_preferences!(pairs::Pair{String, <:Any}...)Set preferences for PromptingTools. See ?PREFERENCES for more information.
See also: get_preferences
Example
Change your API key and default model:
PromptingTools.set_preferences!("OPENAI_API_KEY" => "key1", "MODEL_CHAT" => "chat1")set_properties_strict!(properties::AbstractDict)Sets strict mode for the properties of a JSON schema.
Changes:
Sets
additionalPropertiestofalse.All keys must be included in
required.All optional keys will have
nulladded to their type.
Reference: https://platform.openai.com/docs/guides/structured-outputs/supported-schemas
', 19)), + _cache[57] || (_cache[57] = createBaseVNode("div", { style: { "border-width": "1px", "border-style": "solid", "border-color": "black", "padding": "1em", "border-radius": "25px" } }, [ + createBaseVNode("a", { + id: "PromptingTools.tool_call_signature-Tuple{Union{Method, Type}}", + href: "#PromptingTools.tool_call_signature-Tuple{Union{Method, Type}}" + }, "#"), + createTextVNode(" "), + createBaseVNode("b", null, [ + createBaseVNode("u", null, "PromptingTools.tool_call_signature") + ]), + createTextVNode(" — "), + createBaseVNode("i", null, "Method"), + createTextVNode(". "), + createBaseVNode("div", { class: "language-julia vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }, "julia"), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "tool_call_signature"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, "(") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " type_or_method"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union{Type, Method}"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, "; strict"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union{Nothing, Bool}"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, " ="), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, " nothing"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, ",") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " max_description_length"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Int"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, " ="), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, " 200"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, ", name"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union{Nothing, String}"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, " ="), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, " nothing"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, ",") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " docs"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union{Nothing, String}"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, " ="), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, " nothing"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, ", hidden_fields"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "::"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "AbstractVector"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, "{"), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "<:"), + createBaseVNode("span", { style: { "--shiki-light": "#005CC5", "--shiki-dark": "#79B8FF" } }, "Union"), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, "{") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " AbstractString, Regex}} "), + createBaseVNode("span", { style: { "--shiki-light": "#D73A49", "--shiki-dark": "#F97583" } }, "="), + createBaseVNode("span", { style: { "--shiki-light": "#24292E", "--shiki-dark": "#E1E4E8" } }, " String[])") + ]) + ]) + ]) + ]), + createBaseVNode("p", null, "Extract the argument names, types and docstrings from a struct to create the function call signature in JSON schema."), + createBaseVNode("p", null, "You must provide a Struct type (not an instance of it) with some fields. The types must be CONCRETE, it helps with correct conversion to JSON schema and then conversion back to the struct."), + createBaseVNode("p", null, "Note: Fairly experimental, but works for combination of structs, arrays, strings and singletons."), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Arguments") + ]), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "type_or_method::Union{Type, Method}"), + createTextVNode(": The struct type or method to extract the signature from.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "strict::Union{Nothing, Bool}"), + createTextVNode(": Whether to enforce strict mode for the schema. Defaults to "), + createBaseVNode("code", null, "nothing"), + createTextVNode(".") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "max_description_length::Int"), + createTextVNode(": Maximum length for descriptions. Defaults to 200.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "name::Union{Nothing, String}"), + createTextVNode(": The name of the tool. Defaults to the name of the struct.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "docs::Union{Nothing, String}"), + createTextVNode(": The description of the tool. Defaults to the docstring of the struct/overall function.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createBaseVNode("code", null, "hidden_fields::AbstractVector{<:Union{AbstractString, Regex}}"), + createTextVNode(": A list of fields to hide from the LLM (eg, "), + createBaseVNode("code", null, '["ctx_user_id"]'), + createTextVNode(" or "), + createBaseVNode("code", null, 'r"ctx"'), + createTextVNode(").") + ]) + ]) + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Returns") + ]), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("code", null, "Dict{String, AbstractTool}"), + createTextVNode(": A dictionary representing the function call signature schema.") + ]) + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Tips") + ]), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, "You can improve the quality of the extraction by writing a helpful docstring for your struct (or any nested struct). It will be provided as a description.") + ]), + createBaseVNode("p", null, "You can even include comments/descriptions about the individual fields."), + createBaseVNode("ul", null, [ + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("All fields are assumed to be required, unless you allow null values (eg, "), + createBaseVNode("code", null, "::Union{Nothing, Int}"), + createTextVNode("). Fields with "), + createBaseVNode("code", null, "Nothing"), + createTextVNode(" will be treated as optional.") + ]) + ]), + createBaseVNode("li", null, [ + createBaseVNode("p", null, [ + createTextVNode("Missing values are ignored (eg, "), + createBaseVNode("code", null, "::Union{Missing, Int}"), + createTextVNode(" will be treated as Int). It's for broader compatibility and we cannot deserialize it as easily as "), + createBaseVNode("code", null, "Nothing"), + createTextVNode(".") + ]) + ]) + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Example") + ]), + createBaseVNode("p", null, [ + createTextVNode("Do you want to extract some specific measurements from a text like age, weight and height? You need to define the information you need as a struct ("), + createBaseVNode("code", null, "return_type"), + createTextVNode("):") + ]), + createBaseVNode("div", { class: "language- vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "struct MyMeasurement") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, " age::Int") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, " height::Union{Int,Nothing}") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, " weight::Union{Nothing,Float64}") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "end") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "tool_map = tool_call_signature(MyMeasurement)") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "#") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, '# Dict{String, PromptingTools.AbstractTool}("MyMeasurement" => PromptingTools.Tool') + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, '# name: String "MyMeasurement"') + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "# parameters: Dict{String, Any}") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "# description: Nothing nothing") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "# strict: Nothing nothing") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "# callable: MyMeasurement <: Any") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, '"') + ]) + ]) + ]) + ]), + createBaseVNode("p", null, [ + createTextVNode("You can see that only the field "), + createBaseVNode("code", null, "age"), + createTextVNode(` does not allow null values, hence, it's "required". While `), + createBaseVNode("code", null, "height"), + createTextVNode(" and "), + createBaseVNode("code", null, "weight"), + createTextVNode(" are optional.") + ]), + createBaseVNode("div", { class: "language- vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, 'tool_map["MyMeasurement"].parameters["required"]') + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, '# ["age"]') + ]) + ]) + ]) + ]), + createBaseVNode("p", null, [ + createTextVNode("If there are multiple items you want to extract, define a wrapper struct to get a Vector of "), + createBaseVNode("code", null, "MyMeasurement"), + createTextVNode(":") + ]), + createBaseVNode("div", { class: "language- vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "struct MyMeasurementWrapper") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, " measurements::Vector{MyMeasurement}") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "end") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "Or if you want your extraction to fail gracefully when data isn't found, use `MaybeExtract{T}` wrapper (inspired by Instructor package!):") + ]) + ]) + ]) + ]), + createBaseVNode("p", null, "using PromptingTools: MaybeExtract"), + createBaseVNode("p", { MyMeasurement: "" }, "type = MaybeExtract"), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Effectively the same as:") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "struct MaybeExtract{T}") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "result::Union{T, Nothing}") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "error::Bool // true if a result is found, false otherwise") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "message::Union{Nothing, String} // Only present if no result is found, should be short and concise") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "end") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, [ + createTextVNode("If LLM extraction fails, it will return a Dict with "), + createBaseVNode("code", null, "error"), + createTextVNode(" and "), + createBaseVNode("code", null, "message"), + createTextVNode(" fields instead of the result!") + ]) + ]), + createBaseVNode("p", null, 'msg = aiextract("Extract measurements from the text: I am giraffe", type)'), + createBaseVNode("hr"), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, "Dict{Symbol, Any} with 2 entries:") + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, ':message => "Sorry, this feature is only available for humans."') + ]), + createBaseVNode("p", null, [ + createBaseVNode("strong", null, ":error => true") + ]), + createBaseVNode("div", { class: "language- vp-adaptive-theme" }, [ + createBaseVNode("button", { + title: "Copy Code", + class: "copy" + }), + createBaseVNode("span", { class: "lang" }), + createBaseVNode("pre", { + class: "shiki shiki-themes github-light github-dark vp-code", + tabindex: "0" + }, [ + createBaseVNode("code", null, [ + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, "That way, you can handle the error gracefully and get a reason why extraction failed.") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span") + ]), + createTextVNode("\n"), + createBaseVNode("span", { class: "line" }, [ + createBaseVNode("span", null, 'You can also hide certain fields in your function call signature with Strings or Regex patterns (eg, `r"ctx"`).') + ]) + ]) + ]) + ]), + createBaseVNode("p", null, 'tool_map = tool_call_signature(MyMeasurement; hidden_fields = ["ctx_user_id"]) ```'), + createBaseVNode("p", null, [ + createBaseVNode("a", { + href: "https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/extraction.jl#L463-L555", + target: "_blank", + rel: "noreferrer" + }, "source") + ]) + ], -1)), + _cache[58] || (_cache[58] = createStaticVNode('
tool_call_signature(fields::Vector;\n strict::Union{Nothing, Bool} = nothing, max_description_length::Int = 200, name::Union{\n Nothing, String} = nothing,\n docs::Union{Nothing, String} = nothing)Generate a function call signature schema for a dynamically generated struct based on the provided fields.
Arguments
fields::Vector{Union{Symbol, Pair{Symbol, Type}, Pair{Symbol, String}}}: A vector of field names or pairs of field name and type or string description, eg,[:field1, :field2, :field3]or[:field1 => String, :field2 => Int, :field3 => Float64]or[:field1 => String, :field1__description => "Field 1 has the name"].strict::Union{Nothing, Bool}: Whether to enforce strict mode for the schema. Defaults tonothing.max_description_length::Int: Maximum length for descriptions. Defaults to 200.name::Union{Nothing, String}: The name of the tool. Defaults to the name of the struct.docs::Union{Nothing, String}: The description of the tool. Defaults to the docstring of the struct/overall function.
Returns a tool_map with the tool name as the key and the tool object as the value.
See also generate_struct, aiextract, update_field_descriptions!.
Examples
tool_map = tool_call_signature([:field1, :field2, :field3])With the field types:
tool_map = tool_call_signature([:field1 => String, :field2 => Int, :field3 => Float64])And with the field descriptions:
tool_map = tool_call_signature([:field1 => String, :field1__description => "Field 1 has the name"])Get the vector of tool call requests from an AIToolRequest/message.
unique_permutation(inputs::AbstractVector)Returns indices of unique items in a vector inputs. Access the unique values as inputs[unique_permutation(inputs)].
Unwraps the tracer message or tracer-like object, returning the original object.
update_field_descriptions!(\n parameters::Dict{String, <:Any}, descriptions::Dict{Symbol, <:AbstractString};\n max_description_length::Int = 200)Update the given JSON schema with descriptions from the descriptions dictionary. This function modifies the schema in-place, adding a "description" field to each property that has a corresponding entry in the descriptions dictionary.
Note: It modifies the schema in place. Only the top-level "properties" are updated!
Returns: The modified schema dictionary.
Arguments
parameters: A dictionary representing the JSON schema to be updated.descriptions: A dictionary mapping field names (as symbols) to their descriptions.max_description_length::Int: Maximum length for descriptions. Defaults to 200.
Examples
parameters = Dict{String, Any}(\n "properties" => Dict{String, Any}(\n "location" => Dict{String, Any}("type" => "string"),\n "condition" => Dict{String, Any}("type" => "string"),\n "temperature" => Dict{String, Any}("type" => "number")\n ),\n "required" => ["location", "temperature", "condition"],\n "type" => "object"\n )\n descriptions = Dict{Symbol, String}(\n :temperature => "Temperature in degrees Fahrenheit",\n :condition => "Current weather condition (e.g., sunny, rainy, cloudy)"\n )\n update_field_descriptions!(parameters, descriptions)wrap_string(str::String,\n text_width::Int = 20;\n newline::Union{AbstractString, AbstractChar} = '')
Breaks a string into lines of a given text_width. Optionally, you can specify the newline character or string to use.
Example:
wrap_string("Certainly, here's a function in Julia that will wrap a string according to the specifications:", 10) |> printaai"user_prompt"[model_alias] -> AIMessageAsynchronous version of @ai_str macro, which will log the result once it's ready.
See also aai!"" if you want an asynchronous reply to the provided message / continue the conversation.
Example
Send asynchronous request to GPT-4, so we don't have to wait for the response: Very practical with slow models, so you can keep working in the meantime.
\n**...with some delay...**\n\n**[ Info: Tokens: 29 @ Cost: 0.0011\n in 2.7 seconds**\n\n**[ Info: AIMessage> Hello! How can I assist you today?**\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/macros.jl#L99-L116)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.@ai!_str-Tuple{Any, Vararg{Any}}' href='#PromptingTools.@ai!_str-Tuple{Any, Vararg{Any}}'>#</a> <b><u>PromptingTools.@ai!_str</u></b> — <i>Macro</i>.\n\n\n\n\n```julia\nai!"user_prompt"[model_alias] -> AIMessageThe ai!"" string macro is used to continue a previous conversation with the AI model.
It appends the new user prompt to the last conversation in the tracked history (in PromptingTools.CONV_HISTORY) and generates a response based on the entire conversation context. If you want to see the previous conversation, you can access it via PromptingTools.CONV_HISTORY, which keeps at most last PromptingTools.MAX_HISTORY_LENGTH conversations.
Arguments
user_prompt(String): The new input prompt to be added to the existing conversation.model_alias(optional, any): Specify the model alias of the AI model to be used (seeMODEL_ALIASES). If not provided, the default model is used.
Returns
AIMessage corresponding to the new user prompt, considering the entire conversation history.
Example
To continue a conversation:
# start conversation as normal\nai"Say hi." \n\n# ... wait for reply and then react to it:\n\n# continue the conversation (notice that you can change the model, eg, to more powerful one for better answer)\nai!"What do you think about that?"gpt4t\n# AIMessage("Considering our previous discussion, I think that...")Usage Notes
This macro should be used when you want to maintain the context of an ongoing conversation (ie, the last
ai""message).It automatically accesses and updates the global conversation history.
If no conversation history is found, it raises an assertion error, suggesting to initiate a new conversation using
ai""instead.
Important
Ensure that the conversation history is not too long to maintain relevancy and coherence in the AI's responses. The history length is managed by MAX_HISTORY_LENGTH.
ai"user_prompt"[model_alias] -> AIMessageThe ai"" string macro generates an AI response to a given prompt by using aigenerate under the hood.
See also ai!"" if you want to reply to the provided message / continue the conversation.
Arguments
user_prompt(String): The input prompt for the AI model.model_alias(optional, any): Provide model alias of the AI model (seeMODEL_ALIASES).
Returns
AIMessage corresponding to the input prompt.
Example
result = ai"Hello, how are you?"\n# AIMessage("Hello! I'm an AI assistant, so I don't have feelings, but I'm here to help you. How can I assist you today?")If you want to interpolate some variables or additional context, simply use string interpolation:
a=1\nresult = ai"What is `$a+$a`?"\n# AIMessage("The sum of `1+1` is `2`.")If you want to use a different model, eg, GPT-4, you can provide its alias as a flag:
result = ai"What is `1.23 * 100 + 1`?"gpt4t\n# AIMessage("The answer is 124.")@timeout(seconds, expr_to_run, expr_when_fails)Simple macro to run an expression with a timeout of seconds. If the expr_to_run fails to finish in seconds seconds, expr_when_fails is returned.
Example
x = @timeout 1 begin\n sleep(1.1)\n println("done")\n 1\nend "failed"', 19)) + ]); +} +const reference = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference as default +}; diff --git a/previews/PR252/assets/reference_agenttools.md.BII8hK3X.js b/previews/PR252/assets/reference_agenttools.md.BII8hK3X.js new file mode 100644 index 00000000..28e9e8f4 --- /dev/null +++ b/previews/PR252/assets/reference_agenttools.md.BII8hK3X.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference for AgentTools","description":"","frontmatter":{},"headers":[],"relativePath":"reference_agenttools.md","filePath":"reference_agenttools.md","lastUpdated":null}'); +const _sfc_main = { name: "reference_agenttools.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Reference for AgentTools
PromptingTools.Experimental.AgentTools.AICallPromptingTools.Experimental.AgentTools.AICodeFixerPromptingTools.Experimental.AgentTools.RetryConfigPromptingTools.Experimental.AgentTools.SampleNodePromptingTools.Experimental.AgentTools.ThompsonSamplingPromptingTools.Experimental.AgentTools.UCTPromptingTools.Experimental.AgentTools.AIClassifyPromptingTools.Experimental.AgentTools.AIEmbedPromptingTools.Experimental.AgentTools.AIExtractPromptingTools.Experimental.AgentTools.AIGeneratePromptingTools.Experimental.AgentTools.AIScanPromptingTools.Experimental.AgentTools.add_feedback!PromptingTools.Experimental.AgentTools.aicodefixer_feedbackPromptingTools.Experimental.AgentTools.airetry!PromptingTools.Experimental.AgentTools.backpropagate!PromptingTools.Experimental.AgentTools.beta_samplePromptingTools.Experimental.AgentTools.collect_all_feedbackPromptingTools.Experimental.AgentTools.error_feedbackPromptingTools.Experimental.AgentTools.evaluate_condition!PromptingTools.Experimental.AgentTools.expand!PromptingTools.Experimental.AgentTools.extract_configPromptingTools.Experimental.AgentTools.find_nodePromptingTools.Experimental.AgentTools.gamma_samplePromptingTools.Experimental.AgentTools.print_samplesPromptingTools.Experimental.AgentTools.remove_used_kwargsPromptingTools.Experimental.AgentTools.reset_success!PromptingTools.Experimental.AgentTools.run!PromptingTools.Experimental.AgentTools.run!PromptingTools.Experimental.AgentTools.scorePromptingTools.Experimental.AgentTools.scorePromptingTools.Experimental.AgentTools.select_bestPromptingTools.Experimental.AgentTools.split_multi_samplesPromptingTools.Experimental.AgentTools.truncate_conversationPromptingTools.Experimental.AgentTools.unwrap_aicall_args
AgentToolsProvides Agentic functionality providing lazy calls for building pipelines (eg, AIGenerate) and AICodeFixer.
This module is experimental and may change at any time. It is intended to be moved to a separate package in the future.
AICall(func::F, args...; kwargs...) where {F<:Function}\n\nAIGenerate(args...; kwargs...)\nAIEmbed(args...; kwargs...)\nAIExtract(args...; kwargs...)A lazy call wrapper for AI functions in the PromptingTools module, such as aigenerate.
The AICall struct is designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied. This approach allows for more flexible and efficient handling of AI function calls, especially in interactive environments.
Seel also: run!, AICodeFixer
Fields
func::F: The AI function to be called lazily. This should be a function likeaigenerateor otherai*functions.schema::Union{Nothing, PT.AbstractPromptSchema}: Optional schema to structure the prompt for the AI function.conversation::Vector{PT.AbstractMessage}: A vector of messages that forms the conversation context for the AI call.kwargs::NamedTuple: Keyword arguments to be passed to the AI function.success::Union{Nothing, Bool}: Indicates whether the last call was successful (true) or not (false).Nothingif the call hasn't been made yet.error::Union{Nothing, Exception}: Stores any exception that occurred during the last call.Nothingif no error occurred or if the call hasn't been made yet.
Example
Initiate an AICall like any ai* function, eg, AIGenerate:
aicall = AICall(aigenerate)\n\n# With arguments and kwargs like ai* functions\n# from `aigenerate(schema, conversation; model="abc", api_kwargs=(; temperature=0.1))`\n# to\naicall = AICall(aigenerate, schema, conversation; model="abc", api_kwargs=(; temperature=0.1)\n\n# Or with a template\naicall = AIGenerate(:JuliaExpertAsk; ask="xyz", model="abc", api_kwargs=(; temperature=0.1))Trigger the AICall with run! (it returns the update AICall struct back):
aicall |> run!\n````\n\nYou can also use `AICall` as a functor to trigger the AI call with a `UserMessage` or simply the text to send:julia aicall(UserMessage("Hello, world!")) # Triggers the lazy call result = run!(aicall) # Explicitly runs the AI call ``` This can be used to "reply" to previous message / continue the stored conversation
Notes
The
AICallstruct is a key component in building flexible and efficient Agentic pipelinesThe lazy evaluation model allows for setting up the call parameters in advance and deferring the actual execution until it is explicitly triggered.
This struct is particularly useful in scenarios where the timing of AI function execution needs to be deferred or where multiple potential calls need to be prepared and selectively executed.
AICodeFixer(aicall::AICall, templates::Vector{<:PT.UserMessage}; num_rounds::Int = 3, feedback_func::Function = aicodefixer_feedback; kwargs...)\nAICodeFixer(aicall::AICall, template::Union{AITemplate, Symbol} = :CodeFixerRCI; kwargs...)An AIAgent that iteratively evaluates any received Julia code and provides feedback back to the AI model if num_rounds>0. AICodeFixer manages the lifecycle of a code fixing session, including tracking conversation history, rounds of interaction, and applying user feedback through a specialized feedback function.
It integrates with lazy AI call structures like AIGenerate.
The operation is "lazy", ie, the agent is only executed when needed, eg, when run! is called.
Fields
call::AICall: The AI call that is being used for code generation or processing, eg, AIGenerate (same asaigeneratebut "lazy", ie, called only when neededtemplates::Union{Symbol, AITemplate, Vector{PT.UserMessage}}: A set of user messages or templates that guide the AI's code fixing process. The first UserMessage is used in the first round of code fixing, the second UserMessage is used for every subsequent iteration.num_rounds::Int: The number of rounds for the code fixing session. Defaults to 3.round_counter::Int: Counter to track the current round of interaction.feedback_func::Function: Function to generate feedback based on the AI's proposed code, defaults toaicodefixer_feedback(modular thanks to type dispatch onAbstractOutcomes)kwargs::NamedTuple: Additional keyword arguments for customizing the AI call.
Note: Any kwargs provided to run!() will be passed to the underlying AICall.
Example
Let's create an AIGenerate call and then pipe it to AICodeFixer to run a few rounds of the coding fixing:
# Create an AIGenerate call\nlazy_call = AIGenerate("Write a function to do XYZ...")\n\n# the action starts only when `run!` is called\nresult = lazy_call |> AICodeFixer |> run!\n\n# Access the result of the code fixing session\n# result.call refers to the AIGenerate lazy call above\nconversation = result.call.conversation\nfixed_code = last(conversation) # usually in the last message\n\n# Preview the conversation history\npreview(conversation)You can change the template used to provide user feedback and number of counds via arguments:
# Setup an AIGenerate call\nlazy_call = AIGenerate(aigenerate, "Write code to do XYZ...")\n\n# Custom template and 2 fixing rounds\nresult = AICodeFixer(lazy_call, [PT.UserMessage("Please fix the code.\n\nFeedback: {{feedback}}")]; num_rounds = 2) |> run!\n\n# The result now contains the AI's attempts to fix the code\npreview(result.call.conversation)Notes
AICodeFixeris particularly useful when code is hard to get right in one shot (eg, smaller models, complex syntax)The structure leverages the lazy evaluation model of
AICall(/AIGenerate) to efficiently manage AI interactions and be able to repeatedly call it.The
run!function executes the AI call and applies the feedback loop for the specified number of rounds, enabling an interactive code fixing process.
RetryConfigConfiguration for self-fixing the AI calls. It includes the following fields:
Fields
retries::Int: The number of retries ("fixing rounds") that have been attempted so far.calls::Int: The total number of SUCCESSFULLY generated ai* function calls made so far (across all samples/retry rounds). Ie, if a call fails, because of an API error, it's not counted, because it didn't reach the LLM.max_retries::Int: The maximum number of retries ("fixing rounds") allowed for the AI call. Defaults to 10.max_calls::Int: The maximum number of ai* function calls allowed for the AI call. Defaults to 99.retry_delay::Int: The delay (in seconds) between retry rounds. Defaults to 0s.n_samples::Int: The number of samples to generate in each ai* call round (to increase changes of successful pass). Defaults to 1.scoring::AbstractScoringMethod: The scoring method to use for generating multiple samples. Defaults toUCT(sqrt(2)).ordering::Symbol: The ordering to use for select the best samples. With:PostOrderDFSwe prioritize leaves, with:PreOrderDFSwe prioritize the root. Defaults to:PostOrderDFS.feedback_inplace::Bool: Whether to provide feedback in previous UserMessage (and remove the past AIMessage) or to create a new UserMessage. Defaults tofalse.feedback_template::Symbol: Template to use for feedback in place. Defaults to:FeedbackFromEvaluator.temperature::Float64: The temperature to use for sampling. Relevant only if not defined inapi_kwargsprovided. Defaults to 0.7.catch_errors::Bool: Whether to catch errors duringrun!of AICall. Saves them inaicall.error. Defaults tofalse.
SampleNode{T}A node in the Monte Carlo Tree Search tree.
It's used to hold the data we're trying to optimize/discover (eg, a conversation), the scores from evaluation (wins, visits) and the results of the evaluations upon failure (feedback).
Fields
id::UInt16: Unique identifier for the nodeparent::Union{SampleNode, Nothing}: Parent node that current node was built onchildren::Vector{SampleNode}: Children nodeswins::Int: Number of successful outcomesvisits::Int: Number of condition checks done (eg, losses arechecks - wins)data::T: eg, the conversation or some parameter to be optimizedfeedback::String: Feedback from the evaluation, always a string! Defaults to empty string.success::Union{Nothing, Bool}: Success of the generation and subsequent evaluations, proxy for whether it should be further evaluated. Defaults to nothing.
ThompsonSampling <: AbstractScoringMethodImplements scoring and selection for Thompson Sampling method. See https://en.wikipedia.org/wiki/Thompson_sampling for more details.
UCT <: AbstractScoringMethodImplements scoring and selection for UCT (Upper Confidence Bound for Trees) sampling method. See https://en.wikipedia.org/wiki/Monte_Carlo_tree_search#Exploration_and_exploitation for more details.
AIClassify(args...; kwargs...)Creates a lazy instance of aiclassify. It is an instance of AICall with aiclassify as the function.
Use exactly the same arguments and keyword arguments as aiclassify (see ?aiclassify for details).
AIEmbed(args...; kwargs...)Creates a lazy instance of aiembed. It is an instance of AICall with aiembed as the function.
Use exactly the same arguments and keyword arguments as aiembed (see ?aiembed for details).
AIExtract(args...; kwargs...)Creates a lazy instance of aiextract. It is an instance of AICall with aiextract as the function.
Use exactly the same arguments and keyword arguments as aiextract (see ?aiextract for details).
AIGenerate(args...; kwargs...)Creates a lazy instance of aigenerate. It is an instance of AICall with aigenerate as the function.
Use exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details).
AIScan(args...; kwargs...)Creates a lazy instance of aiscan. It is an instance of AICall with aiscan as the function.
Use exactly the same arguments and keyword arguments as aiscan (see ?aiscan for details).
add_feedback!(\n conversation::AbstractVector{<:PT.AbstractMessage}, sample::SampleNode; feedback_inplace::Bool = false,\n feedback_template::Symbol = :FeedbackFromEvaluator)Adds formatted feedback to the conversation based on the sample node feedback (and its ancestors).
Arguments
conversation::AbstractVector{<:PT.AbstractMessage}: The conversation to add the feedback to.sample::SampleNode: The sample node to extract the feedback from.feedback_inplace::Bool=false: If true, it will add the feedback to the last user message inplace (and pop the last AIMessage). Otherwise, it will append the feedback as a new message.feedback_template::Symbol=:FeedbackFromEvaluator: The template to use for the feedback message. It must be a validAITemplatename.
Example
sample = SampleNode(; data = nothing, feedback = "Feedback X")\nconversation = [PT.UserMessage("I say hi!"), PT.AIMessage(; content = "I say hi!")]\nconversation = AT.add_feedback!(conversation, sample)\nconversation[end].content == "### Feedback from Evaluator\\nFeedback X\\n"\n\nInplace feedback:julia conversation = [PT.UserMessage("I say hi!"), PT.AIMessage(; content = "I say hi!")] conversation = AT.add_feedback!(conversation, sample; feedback_inplace = true) conversation[end].content == "I say hi!\\n\\n### Feedback from Evaluator\\nFeedback X\\n"
\nSample with ancestors with feedback:julia sample_p = SampleNode(; data = nothing, feedback = "\\nFeedback X") sample = expand!(sample_p, nothing) sample.feedback = "\\nFeedback Y" conversation = [PT.UserMessage("I say hi!"), PT.AIMessage(; content = "I say hi!")] conversation = AT.add_feedback!(conversation, sample)
conversation[end].content == "### Feedback from Evaluator\\n\\nFeedback X\\n–––––\\n\\nFeedback Y\\n" ```
aicodefixer_feedback(cb::AICode; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(conversation::AbstractVector{<:PT.AbstractMessage}; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(msg::PT.AIMessage; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(aicall::AICall; max_length::Int = 512) -> NamedTuple(; feedback::String)Generate feedback for an AI code fixing session based on the AICode block /or conversation history (that will be used to extract and evaluate a code block). Function is designed to be extensible for different types of feedback and code evaluation outcomes.
The highlevel wrapper accepts a conversation and returns new kwargs for the AICall.
Individual feedback functions are dispatched on different subtypes of AbstractCodeOutcome and can be extended/overwritten to provide more detailed feedback.
See also: AIGenerate, AICodeFixer
Arguments
cb::AICode: AICode block to evaluate and provide feedback on.max_length::Int=512: An optional argument that specifies the maximum length of the feedback message.
Returns
NamedTuple: A feedback message as a kwarg in NamedTuple based on the analysis of the code provided in the conversation.
Example
cb = AICode(msg; skip_unsafe = true, capture_stdout = true)\nnew_kwargs = aicodefixer_feedback(cb)\n\nnew_kwargs = aicodefixer_feedback(msg)\nnew_kwargs = aicodefixer_feedback(conversation)Notes
This function is part of the AI code fixing system, intended to interact with code in AIMessage and provide feedback on improving it.
The highlevel wrapper accepts a conversation and returns new kwargs for the AICall.
It dispatches for the code feedback based on the subtypes of AbstractCodeOutcome below:
CodeEmpty: No code found in the message.CodeFailedParse: Code parsing error.CodeFailedEval: Runtime evaluation error.CodeFailedTimeout: Code execution timed out.CodeSuccess: Successful code execution.
You can override the individual methods to customize the feedback.
airetry!(\n f_cond::Function, aicall::AICallBlock, feedback::Union{AbstractString, Function} = "";\n verbose::Bool = true, throw::Bool = false, evaluate_all::Bool = true, feedback_expensive::Bool = false,\n max_retries::Union{Nothing, Int} = nothing, retry_delay::Union{Nothing, Int} = nothing)Evaluates the condition f_cond on the aicall object. If the condition is not met, it will return the best sample to retry from and provide feedback (string or function) to aicall. That's why it's mutating. It will retry maximum max_retries times, with throw=true, an error will be thrown if the condition is not met after max_retries retries.
Note: aicall must be run first via run!(aicall) before calling airetry!.
Function signatures
f_cond(aicall::AICallBlock) -> Bool, ie, it must accept the aicall object and return a boolean value.feedbackcan be a string orfeedback(aicall::AICallBlock) -> String, ie, it must accept the aicall object and return a string.
You can leverage the last_message, last_output, and AICode functions to access the last message, last output and execute code blocks in the conversation, respectively. See examples below.
Good Use Cases
Retry with API failures/drops (add
retry_delay=2to wait 2s between retries)Check the output format / type / length / etc
Check the output with
aiclassifycall (LLM Judge) to catch unsafe/NSFW/out-of-scope contentProvide hints to the model to guide it to the correct answer
Gotchas
If controlling keyword arguments are set to nothing, they will fall back to the default values in
aicall.config. You can override them by passing the keyword arguments explicitly.If there multiple
airetry!checks, they are evaluted sequentially. As long asthrow==false, they will be all evaluated even if they failed previous checks.Only samples which passed previous evaluations are evaluated (
sample.successistrue). If there are no successful samples, the function will evaluate only the active sample (aicall.active_sample_id) and nothing else.Feedback from all "ancestor" evaluations is added upon retry, not feedback from the "sibblings" or other branches. To have only ONE long BRANCH (no sibblings), make sure to keep
RetryConfig(; n_samples=1). That way the model will always see ALL previous feedback.We implement a version of Monte Carlo Tree Search (MCTS) to always pick the most promising sample to restart from (you can tweak the options in
RetryConfigto change the behaviour).For large number of parallel branches (ie, "shallow and wide trees"), you might benefit from switching scoring to
scoring=ThompsonSampling()(similar to how Bandit algorithms work).Open-source/local models can struggle with too long conversation, you might want to experiment with
in-place feedback(setRetryConfig(; feedback_inplace=true)).
Arguments
f_cond::Function: A function that accepts theaicallobject and returns a boolean value. Retry will be attempted if the condition is not met (f_cond -> false).aicall::AICallBlock: Theaicallobject to evaluate the condition on.feedback::Union{AbstractString, Function}: Feedback to provide if the condition is not met. If a function is provided, it must accept theaicallobject as the only argument and return a string.verbose::Integer=1: A verbosity level for logging the retry attempts and warnings. A higher value indicates more detailed logging.throw::Bool=false: If true, it will throw an error if the functionf_conddoes not returntrueaftermax_retriesretries.evaluate_all::Bool=false: If true, it will evaluate all the "successful" samples in theaicallobject. Otherwise, it will only evaluate the active sample.feedback_expensive::Bool=false: If false, it will provide feedback to all samples that fail the condition. Iffeedbackfunction is expensive to call (eg, another ai* function), set this totrueand feedback will be provided only to the sample we will retry from.max_retries::Union{Nothing, Int}=nothing: Maximum number of retries. If not provided, it will fall back to themax_retriesinaicall.config.retry_delay::Union{Nothing, Int}=nothing: Delay between retries in seconds. If not provided, it will fall back to theretry_delayinaicall.config.
Returns
- The
aicallobject with the updatedconversation, andsamples(saves the evaluations and their scores/feedback).
Example
You can use airetry! to catch API errors in run! and auto-retry the call. RetryConfig is how you influence all the subsequent retry behaviours - see ?RetryConfig for more details.
# API failure because of a non-existent model\nout = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\n model = "NOTEXIST")\nrun!(out) # fails\n\n# we ask to wait 2s between retries and retry 2 times (can be set in `config` in aicall as well)\nairetry!(isvalid, out; retry_delay = 2, max_retries = 2)If you provide arguments to the aicall, we try to honor them as much as possible in the following calls, eg, set low verbosity
out = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\nmodel = "NOTEXIST", verbose=false)\nrun!(out)\n# No info message, you just see `success = false` in the properties of the AICallLet's show a toy example to demonstrate the runtime checks / guardrails for the model output. We'll play a color guessing game (I'm thinking "yellow"):
# Notice that we ask for two samples (`n_samples=2`) at each attempt (to improve our chances). \n# Both guesses are scored at each time step, and the best one is chosen for the next step.\n# And with OpenAI, we can set `api_kwargs = (;n=2)` to get both samples simultaneously (cheaper and faster)!\nout = AIGenerate(\n "Guess what color I'm thinking. It could be: blue, red, black, white, yellow. Answer with 1 word only";\n verbose = false,\n config = RetryConfig(; n_samples = 2), api_kwargs = (; n = 2))\nrun!(out)\n\n\n## Check that the output is 1 word only, third argument is the feedback that will be provided if the condition fails\n## Notice: functions operate on `aicall` as the only argument. We can use utilities like `last_output` and `last_message` to access the last message and output in the conversation.\nairetry!(x -> length(split(last_output(x), r" |\\.")) == 1, out,\n "You must answer with 1 word only.")\n\n\n## Let's ensure that the output is in lowercase - simple and short\nairetry!(x -> all(islowercase, last_output(x)), out, "You must answer in lowercase.")\n# [ Info: Condition not met. Retrying...\n\n\n## Let's add final hint - it took us 2 retries\nairetry!(x -> startswith(last_output(x), "y"), out, "It starts with "y"")\n# [ Info: Condition not met. Retrying...\n# [ Info: Condition not met. Retrying...\n\n\n## We end up with the correct answer\nlast_output(out)\n# Output: "yellow"Let's explore how we got here. We save the various attempts in a "tree" (SampleNode object) You can access it in out.samples, which is the ROOT of the tree (top level). Currently "active" sample ID is out.active_sample_id -> that's the same as conversation field in your AICall.
# Root node:\nout.samples\n# Output: SampleNode(id: 46839, stats: 6/12, length: 2)\n\n# Active sample (our correct answer):\nout.active_sample_id \n# Output: 50086\n\n# Let's obtain the active sample node with this ID - use getindex notation or function find_node\nout.samples[out.active_sample_id]\n# Output: SampleNode(id: 50086, stats: 1/1, length: 7)\n\n# The SampleNode has two key fields: data and feedback. Data is where the conversation is stored:\nactive_sample = out.samples[out.active_sample_id]\nactive_sample.data == out.conversation # Output: true -> This is the winning guess!We also get a clear view of the tree structure of all samples with print_samples:
julia> print_samples(out.samples)\nSampleNode(id: 46839, stats: 6/12, score: 0.5, length: 2)\n├─ SampleNode(id: 12940, stats: 5/8, score: 1.41, length: 4)\n│ ├─ SampleNode(id: 34315, stats: 3/4, score: 1.77, length: 6)\n│ │ ├─ SampleNode(id: 20493, stats: 1/1, score: 2.67, length: 7)\n│ │ └─ SampleNode(id: 50086, stats: 1/1, score: 2.67, length: 7)\n│ └─ SampleNode(id: 2733, stats: 1/2, score: 1.94, length: 5)\n└─ SampleNode(id: 48343, stats: 1/4, score: 1.36, length: 4)\n ├─ SampleNode(id: 30088, stats: 0/1, score: 1.67, length: 5)\n └─ SampleNode(id: 44816, stats: 0/1, score: 1.67, length: 5)You can use the id to grab and inspect any of these nodes, eg,
out.samples[2733]\n# Output: SampleNode(id: 2733, stats: 1/2, length: 5)We can also iterate through all samples and extract whatever information we want with PostOrderDFS or PreOrderDFS (exported from AbstractTrees.jl)
for sample in PostOrderDFS(out.samples)\n # Data is the universal field for samples, we put `conversation` in there\n # Last item in data is the last message in coversation\n msg = sample.data[end]\n if msg isa PT.AIMessage # skip feedback\n # get only the message content, ie, the guess\n println("ID: $(sample.id), Answer: $(msg.content)")\n end\nend\n\n# ID: 20493, Answer: yellow\n# ID: 50086, Answer: yellow\n# ID: 2733, Answer: red\n# ID: 30088, Answer: blue\n# ID: 44816, Answer: blueNote: airetry! will attempt to fix the model max_retries times. If you set throw=true, it will throw an ErrorException if the condition is not met after max_retries retries.
Let's define a mini program to guess the number and use airetry! to guide the model to the correct answer:
"""\n llm_guesser()\n\nMini program to guess the number provided by the user (betwee 1-100).\n"""\nfunction llm_guesser(user_number::Int)\n @assert 1 <= user_number <= 100\n prompt = """\nI'm thinking a number between 1-100. Guess which one it is. \nYou must respond only with digits and nothing else. \nYour guess:"""\n ## 2 samples at a time, max 5 fixing rounds\n out = AIGenerate(prompt; config = RetryConfig(; n_samples = 2, max_retries = 5),\n api_kwargs = (; n = 2)) |> run!\n ## Check the proper output format - must parse to Int, use do-syntax\n ## We can provide feedback via a function!\n function feedback_f(aicall)\n "Output: $(last_output(aicall))\nFeedback: You must respond only with digits!!"\n end\n airetry!(out, feedback_f) do aicall\n !isnothing(tryparse(Int, last_output(aicall)))\n end\n ## Give a hint on bounds\n lower_bound = (user_number ÷ 10) * 10\n upper_bound = lower_bound + 10\n airetry!(\n out, "The number is between or equal to $lower_bound to $upper_bound.") do aicall\n guess = tryparse(Int, last_output(aicall))\n lower_bound <= guess <= upper_bound\n end\n ## You can make at most 3x guess now -- if there is max_retries in `config.max_retries` left\n max_retries = out.config.retries + 3\n function feedback_f2(aicall)\n guess = tryparse(Int, last_output(aicall))\n "Your guess of $(guess) is wrong, it's $(abs(guess-user_number)) numbers away."\n end\n airetry!(out, feedback_f2; max_retries) do aicall\n tryparse(Int, last_output(aicall)) == user_number\n end\n\n ## Evaluate the best guess\n @info "Results: Guess: $(last_output(out)) vs User: $user_number (Number of calls made: $(out.config.calls))"\n return out\nend\n\n# Let's play the game\nout = llm_guesser(33)\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Results: Guess: 33 vs User: 33 (Number of calls made: 10)Yay! We got it 😃
Now, we could explore different samples (eg, print_samples(out.samples)) or see what the model guessed at each step:
print_samples(out.samples)\n## SampleNode(id: 57694, stats: 6/14, score: 0.43, length: 2)\n## ├─ SampleNode(id: 35603, stats: 5/10, score: 1.23, length: 4)\n## │ ├─ SampleNode(id: 55394, stats: 1/4, score: 1.32, length: 6)\n## │ │ ├─ SampleNode(id: 20737, stats: 0/1, score: 1.67, length: 7)\n## │ │ └─ SampleNode(id: 52910, stats: 0/1, score: 1.67, length: 7)\n## │ └─ SampleNode(id: 43094, stats: 3/4, score: 1.82, length: 6)\n## │ ├─ SampleNode(id: 14966, stats: 1/1, score: 2.67, length: 7)\n## │ └─ SampleNode(id: 32991, stats: 1/1, score: 2.67, length: 7)\n## └─ SampleNode(id: 20506, stats: 1/4, score: 1.4, length: 4)\n## ├─ SampleNode(id: 37581, stats: 0/1, score: 1.67, length: 5)\n## └─ SampleNode(id: 46632, stats: 0/1, score: 1.67, length: 5)\n\n# Lastly, let's check all the guesses AI made across all samples. \n# Our winning guess was ID 32991 (`out.active_sample_id`)\n\nfor sample in PostOrderDFS(out.samples)\n [println("ID: $(sample.id), Guess: $(msg.content)")\n for msg in sample.data if msg isa PT.AIMessage]\nend\n## ID: 20737, Guess: 50\n## ID: 20737, Guess: 35\n## ID: 20737, Guess: 37\n## ID: 52910, Guess: 50\n## ID: 52910, Guess: 35\n## ID: 52910, Guess: 32\n## ID: 14966, Guess: 50\n## ID: 14966, Guess: 35\n## ID: 14966, Guess: 33\n## ID: 32991, Guess: 50\n## ID: 32991, Guess: 35\n## ID: 32991, Guess: 33\n## etc...Note that if there are multiple "branches" the model will see only the feedback of its own and its ancestors not the other "branches". If you wanted to provide ALL feedback, set RetryConfig(; n_samples=1) to remove any "branching". It fixing will be done sequentially in one conversation and the model will see all feedback (less powerful if the model falls into a bad state). Alternatively, you can tweak the feedback function.
See Also
References: airetry is inspired by the Language Agent Tree Search paper and by DSPy Assertions paper.
Provides scores for a given node (and all its ancestors) based on the evaluation (wins, visits).
beta_sample(α::Real, β::Real)Approximates a sample from the Beta distribution by generating two independent Gamma distributed samples and using their ratio.
Collects all feedback from the node and its ancestors (parents). Returns a string separated by separator.
error_feedback(e::Any; max_length::Int = 512)Set of specialized methods to provide feedback on different types of errors (e).
evaluate_condition!(f_cond::Function, aicall::AICallBlock,\n feedback::Union{AbstractString, Function} = "";\n evaluate_all::Bool = true, feedback_expensive::Bool = false)Evalutes the condition f_cond (must return Bool) on the aicall object. If the condition is not met, it will return the best sample to retry from and provide feedback.
Mutating as the results are saved in aicall.samples
If evaluate_all is true, it will evaluate all the "successful" samples in the aicall object. Otherwise, it will only evaluate the active sample..
For f_cond and feedback functions, you can use the last_message and last_output utilities to access the last message and last output in the conversation, respectively.
Arguments
f_cond::Function: A function that accepts theaicallobject and returns a boolean value. Retry will be attempted if the condition is not met (f_cond -> false).aicall::AICallBlock: Theaicallobject to evaluate the condition on.feedback::Union{AbstractString, Function}: Feedback to provide if the condition is not met. If a function is provided, it must accept theaicallobject as the only argument and return a string.evaluate_all::Bool=false: If true, it will evaluate all the "successful" samples in theaicallobject. Otherwise, it will only evaluate the active sample.feedback_expensive::Bool=false: If false, it will provide feedback to all samples that fail the condition. Iffeedbackfunction is expensive to call (eg, another ai* function), set this totrueand feedback will be provided only to the sample we will retry from.
Returns
- a tuple
(condition_passed, sample), wherecondition_passedis a boolean indicating whether the condition was met, andsampleis the best sample to retry from.
Example
# Mimic AIGenerate run!\naicall = AIGenerate("Say hi!"; config = RetryConfig(; n_samples = 2))\nsample = expand!(aicall.samples, aicall.conversation; success = true)\naicall.active_sample_id = sample.id\n\n# Return whether it passed and node to take the next action from\ncond, node = AT.evaluate_condition!(x -> occursin("hi", last_output(x)), aicall)\n\n# Checks:\ncond == true\nnode == sample\nnode.wins == 1With feedback: ```julia
Mimic AIGenerate run with feedback
aicall = AIGenerate( :BlankSystemUser; system = "a", user = "b") sample = expand!(aicall.samples, aicall.conversation; success = true) aicall.active_sample_id = sample.id
Evaluate
cond, node = AT.evaluate_condition!( x -> occursin("NOTFOUND", last_output(x)), aicall, "Feedback X") cond == false # fail sample == node # same node (no other choice) node.wins == 0 node.feedback == " Feedback X"
Expands the tree with a new node from parent using the given data and success.
Extracts config::RetryConfig from kwargs and returns the rest of the kwargs.
Finds a node with a given id in the tree starting from node.
gamma_sample(α::Real, θ::Real)Approximates a sample from the Gamma distribution using the Marsaglia and Tsang method.
Pretty prints the samples tree starting from node. Usually, node is the root of the tree. Example: print_samples(aicall.samples).
Removes the kwargs that have already been used in the conversation. Returns NamedTuple.
Sets the success field of all nodes in the tree to success value.
run!(codefixer::AICodeFixer; verbose::Int = 1, max_conversation_length::Int = 32000, run_kwargs...)Executes the code fixing process encapsulated by the AICodeFixer instance. This method iteratively refines and fixes code by running the AI call in a loop for a specified number of rounds, using feedback from the code evaluation (aicodefixer_feedback) to improve the outcome in each iteration.
Arguments
codefixer::AICodeFixer: An instance ofAICodeFixercontaining the AI call, templates, and settings for the code fixing session.verbose::Int=1: Verbosity level for logging. A higher value indicates more detailed logging.max_conversation_length::Int=32000: Maximum length in characters for the conversation history to keep it within manageable limits, especially for large code fixing sessions.num_rounds::Union{Nothing, Int}=nothing: Number of additional rounds for the code fixing session. Ifnothing, the value from theAICodeFixerinstance is used.run_kwargs...: Additional keyword arguments that are passed to the AI function.
Returns
AICodeFixer: The updatedAICodeFixerinstance with the results of the code fixing session.
Usage
aicall = AICall(aigenerate, schema=mySchema, conversation=myConversation)\ncodefixer = AICodeFixer(aicall, myTemplates; num_rounds=5)\nresult = run!(codefixer, verbose=2)Notes
The
run!method drives the core logic of theAICodeFixer, iterating through rounds of AI interactions to refine and fix code.In each round, it applies feedback based on the current state of the conversation, allowing the AI to respond more effectively.
The conversation history is managed to ensure it stays within the specified
max_conversation_length, keeping the AI's focus on relevant parts of the conversation.This iterative process is essential for complex code fixing tasks where multiple interactions and refinements are required to achieve the desired outcome.
run!(aicall::AICallBlock; verbose::Int = 1, catch_errors::Bool = false, return_all::Bool = true, kwargs...)Executes the AI call wrapped by an AICallBlock instance. This method triggers the actual communication with the AI model and processes the response based on the provided conversation context and parameters.
Note: Currently return_all must always be set to true.
Arguments
aicall::AICallBlock: An instance ofAICallBlockwhich encapsulates the AI function call along with its context and parameters (eg,AICall,AIGenerate)verbose::Integer=1: A verbosity level for logging. A higher value indicates more detailed logging.catch_errors::Union{Nothing, Bool}=nothing: A flag to indicate whether errors should be caught and saved toaicall.error. Ifnothing, it defaults toaicall.config.catch_errors.return_all::Bool=true: A flag to indicate whether the whole conversation from the AI call should be returned. It should always be true.kwargs...: Additional keyword arguments that are passed to the AI function.
Returns
AICallBlock: The sameAICallBlockinstance, updated with the results of the AI call. This includes updated conversation, success status, and potential error information.
Example
aicall = AICall(aigenerate)\nrun!(aicall)Alternatively, you can trigger the run! call by using the AICall as a functor and calling it with a string or a UserMessage:
aicall = AICall(aigenerate)\naicall("Say hi!")Notes
The
run!method is a key component of the lazy evaluation model inAICall. It allows for the deferred execution of AI function calls, providing flexibility in how and when AI interactions are conducted.The method updates the
AICallBlockinstance with the outcome of the AI call, including any generated responses, success or failure status, and error information if an error occurred.This method is essential for scenarios where AI interactions are based on dynamic or evolving contexts, as it allows for real-time updates and responses based on the latest information.
Scores a node using the ThomsonSampling method, similar to Bandit algorithms.
Scores a node using the UCT (Upper Confidence Bound for Trees) method.
select_best(node::SampleNode, scoring::AbstractScoringMethod = UCT();\n ordering::Symbol = :PostOrderDFS)Selects the best node from the tree using the given scoring (UCT or ThompsonSampling). Defaults to UCT. Thompson Sampling is more random with small samples, while UCT stabilizes much quicker thanks to looking at parent nodes as well.
Ordering can be either :PreOrderDFS or :PostOrderDFS. Defaults to :PostOrderDFS, which favors the leaves (end points of the tree).
Example
Compare the different scoring methods:
# Set up mock samples and scores\ndata = PT.AbstractMessage[]\nroot = SampleNode(; data)\nchild1 = expand!(root, data)\nbackpropagate!(child1; wins = 1, visits = 1)\nchild2 = expand!(root, data)\nbackpropagate!(child2; wins = 0, visits = 1)\nchild11 = expand!(child1, data)\nbackpropagate!(child11; wins = 1, visits = 1)\n\n# Select with UCT\nn = select_best(root, UCT())\nSampleNode(id: 29826, stats: 1/1, length: 0)\n\n# Show the tree:\nprint_samples(root; scoring = UCT())\n## SampleNode(id: 13184, stats: 2/3, score: 0.67, length: 0)\n## ├─ SampleNode(id: 26078, stats: 2/2, score: 2.05, length: 0)\n## │ └─ SampleNode(id: 29826, stats: 1/1, score: 2.18, length: 0)\n## └─ SampleNode(id: 39931, stats: 0/1, score: 1.48, length: 0)\n\n# Select with ThompsonSampling - much more random with small samples\nn = select_best(root, ThompsonSampling())\nSampleNode(id: 26078, stats: 2/2, length: 0)\n\n# Show the tree (run it a few times and see how the scores jump around):\nprint_samples(root; scoring = ThompsonSampling())\n## SampleNode(id: 13184, stats: 2/3, score: 0.6, length: 0)\n## ├─ SampleNode(id: 26078, stats: 2/2, score: 0.93, length: 0)\n## │ └─ SampleNode(id: 29826, stats: 1/1, score: 0.22, length: 0)\n## └─ SampleNode(id: 39931, stats: 0/1, score: 0.84, length: 0)If the conversation has multiple AIMessage samples, split them into separate conversations with the common past.
truncate_conversation(conversation::AbstractVector{<:PT.AbstractMessage};\n max_conversation_length::Int = 32000)Truncates a given conversation to a max_conversation_length characters by removing messages "in the middle". It tries to retain the original system+user message and also the most recent messages.
Practically, if a conversation is too long, it will start by removing the most recent message EXCEPT for the last two (assumed to be the last AIMessage with the code and UserMessage with the feedback
Arguments
max_conversation_length is in characters; assume c. 2-3 characters per LLM token, so 32000 should correspond to 16K context window.
Unwraps the arguments for AICall and returns the schema and conversation (if provided). Expands any provided AITemplate.
Helpful accessor for AICall blocks. Returns the last message in the conversation.
Helpful accessor for AICall blocks. Returns the last output in the conversation (eg, the string/data in the last message).
', 76) + ])); +} +const reference_agenttools = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference_agenttools as default +}; diff --git a/previews/PR252/assets/reference_agenttools.md.BII8hK3X.lean.js b/previews/PR252/assets/reference_agenttools.md.BII8hK3X.lean.js new file mode 100644 index 00000000..28e9e8f4 --- /dev/null +++ b/previews/PR252/assets/reference_agenttools.md.BII8hK3X.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference for AgentTools","description":"","frontmatter":{},"headers":[],"relativePath":"reference_agenttools.md","filePath":"reference_agenttools.md","lastUpdated":null}'); +const _sfc_main = { name: "reference_agenttools.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Reference for AgentTools
PromptingTools.Experimental.AgentTools.AICallPromptingTools.Experimental.AgentTools.AICodeFixerPromptingTools.Experimental.AgentTools.RetryConfigPromptingTools.Experimental.AgentTools.SampleNodePromptingTools.Experimental.AgentTools.ThompsonSamplingPromptingTools.Experimental.AgentTools.UCTPromptingTools.Experimental.AgentTools.AIClassifyPromptingTools.Experimental.AgentTools.AIEmbedPromptingTools.Experimental.AgentTools.AIExtractPromptingTools.Experimental.AgentTools.AIGeneratePromptingTools.Experimental.AgentTools.AIScanPromptingTools.Experimental.AgentTools.add_feedback!PromptingTools.Experimental.AgentTools.aicodefixer_feedbackPromptingTools.Experimental.AgentTools.airetry!PromptingTools.Experimental.AgentTools.backpropagate!PromptingTools.Experimental.AgentTools.beta_samplePromptingTools.Experimental.AgentTools.collect_all_feedbackPromptingTools.Experimental.AgentTools.error_feedbackPromptingTools.Experimental.AgentTools.evaluate_condition!PromptingTools.Experimental.AgentTools.expand!PromptingTools.Experimental.AgentTools.extract_configPromptingTools.Experimental.AgentTools.find_nodePromptingTools.Experimental.AgentTools.gamma_samplePromptingTools.Experimental.AgentTools.print_samplesPromptingTools.Experimental.AgentTools.remove_used_kwargsPromptingTools.Experimental.AgentTools.reset_success!PromptingTools.Experimental.AgentTools.run!PromptingTools.Experimental.AgentTools.run!PromptingTools.Experimental.AgentTools.scorePromptingTools.Experimental.AgentTools.scorePromptingTools.Experimental.AgentTools.select_bestPromptingTools.Experimental.AgentTools.split_multi_samplesPromptingTools.Experimental.AgentTools.truncate_conversationPromptingTools.Experimental.AgentTools.unwrap_aicall_args
AgentToolsProvides Agentic functionality providing lazy calls for building pipelines (eg, AIGenerate) and AICodeFixer.
This module is experimental and may change at any time. It is intended to be moved to a separate package in the future.
AICall(func::F, args...; kwargs...) where {F<:Function}\n\nAIGenerate(args...; kwargs...)\nAIEmbed(args...; kwargs...)\nAIExtract(args...; kwargs...)A lazy call wrapper for AI functions in the PromptingTools module, such as aigenerate.
The AICall struct is designed to facilitate a deferred execution model (lazy evaluation) for AI functions that interact with a Language Learning Model (LLM). It stores the necessary information for an AI call and executes the underlying AI function only when supplied with a UserMessage or when the run! method is applied. This approach allows for more flexible and efficient handling of AI function calls, especially in interactive environments.
Seel also: run!, AICodeFixer
Fields
func::F: The AI function to be called lazily. This should be a function likeaigenerateor otherai*functions.schema::Union{Nothing, PT.AbstractPromptSchema}: Optional schema to structure the prompt for the AI function.conversation::Vector{PT.AbstractMessage}: A vector of messages that forms the conversation context for the AI call.kwargs::NamedTuple: Keyword arguments to be passed to the AI function.success::Union{Nothing, Bool}: Indicates whether the last call was successful (true) or not (false).Nothingif the call hasn't been made yet.error::Union{Nothing, Exception}: Stores any exception that occurred during the last call.Nothingif no error occurred or if the call hasn't been made yet.
Example
Initiate an AICall like any ai* function, eg, AIGenerate:
aicall = AICall(aigenerate)\n\n# With arguments and kwargs like ai* functions\n# from `aigenerate(schema, conversation; model="abc", api_kwargs=(; temperature=0.1))`\n# to\naicall = AICall(aigenerate, schema, conversation; model="abc", api_kwargs=(; temperature=0.1)\n\n# Or with a template\naicall = AIGenerate(:JuliaExpertAsk; ask="xyz", model="abc", api_kwargs=(; temperature=0.1))Trigger the AICall with run! (it returns the update AICall struct back):
aicall |> run!\n````\n\nYou can also use `AICall` as a functor to trigger the AI call with a `UserMessage` or simply the text to send:julia aicall(UserMessage("Hello, world!")) # Triggers the lazy call result = run!(aicall) # Explicitly runs the AI call ``` This can be used to "reply" to previous message / continue the stored conversation
Notes
The
AICallstruct is a key component in building flexible and efficient Agentic pipelinesThe lazy evaluation model allows for setting up the call parameters in advance and deferring the actual execution until it is explicitly triggered.
This struct is particularly useful in scenarios where the timing of AI function execution needs to be deferred or where multiple potential calls need to be prepared and selectively executed.
AICodeFixer(aicall::AICall, templates::Vector{<:PT.UserMessage}; num_rounds::Int = 3, feedback_func::Function = aicodefixer_feedback; kwargs...)\nAICodeFixer(aicall::AICall, template::Union{AITemplate, Symbol} = :CodeFixerRCI; kwargs...)An AIAgent that iteratively evaluates any received Julia code and provides feedback back to the AI model if num_rounds>0. AICodeFixer manages the lifecycle of a code fixing session, including tracking conversation history, rounds of interaction, and applying user feedback through a specialized feedback function.
It integrates with lazy AI call structures like AIGenerate.
The operation is "lazy", ie, the agent is only executed when needed, eg, when run! is called.
Fields
call::AICall: The AI call that is being used for code generation or processing, eg, AIGenerate (same asaigeneratebut "lazy", ie, called only when neededtemplates::Union{Symbol, AITemplate, Vector{PT.UserMessage}}: A set of user messages or templates that guide the AI's code fixing process. The first UserMessage is used in the first round of code fixing, the second UserMessage is used for every subsequent iteration.num_rounds::Int: The number of rounds for the code fixing session. Defaults to 3.round_counter::Int: Counter to track the current round of interaction.feedback_func::Function: Function to generate feedback based on the AI's proposed code, defaults toaicodefixer_feedback(modular thanks to type dispatch onAbstractOutcomes)kwargs::NamedTuple: Additional keyword arguments for customizing the AI call.
Note: Any kwargs provided to run!() will be passed to the underlying AICall.
Example
Let's create an AIGenerate call and then pipe it to AICodeFixer to run a few rounds of the coding fixing:
# Create an AIGenerate call\nlazy_call = AIGenerate("Write a function to do XYZ...")\n\n# the action starts only when `run!` is called\nresult = lazy_call |> AICodeFixer |> run!\n\n# Access the result of the code fixing session\n# result.call refers to the AIGenerate lazy call above\nconversation = result.call.conversation\nfixed_code = last(conversation) # usually in the last message\n\n# Preview the conversation history\npreview(conversation)You can change the template used to provide user feedback and number of counds via arguments:
# Setup an AIGenerate call\nlazy_call = AIGenerate(aigenerate, "Write code to do XYZ...")\n\n# Custom template and 2 fixing rounds\nresult = AICodeFixer(lazy_call, [PT.UserMessage("Please fix the code.\n\nFeedback: {{feedback}}")]; num_rounds = 2) |> run!\n\n# The result now contains the AI's attempts to fix the code\npreview(result.call.conversation)Notes
AICodeFixeris particularly useful when code is hard to get right in one shot (eg, smaller models, complex syntax)The structure leverages the lazy evaluation model of
AICall(/AIGenerate) to efficiently manage AI interactions and be able to repeatedly call it.The
run!function executes the AI call and applies the feedback loop for the specified number of rounds, enabling an interactive code fixing process.
RetryConfigConfiguration for self-fixing the AI calls. It includes the following fields:
Fields
retries::Int: The number of retries ("fixing rounds") that have been attempted so far.calls::Int: The total number of SUCCESSFULLY generated ai* function calls made so far (across all samples/retry rounds). Ie, if a call fails, because of an API error, it's not counted, because it didn't reach the LLM.max_retries::Int: The maximum number of retries ("fixing rounds") allowed for the AI call. Defaults to 10.max_calls::Int: The maximum number of ai* function calls allowed for the AI call. Defaults to 99.retry_delay::Int: The delay (in seconds) between retry rounds. Defaults to 0s.n_samples::Int: The number of samples to generate in each ai* call round (to increase changes of successful pass). Defaults to 1.scoring::AbstractScoringMethod: The scoring method to use for generating multiple samples. Defaults toUCT(sqrt(2)).ordering::Symbol: The ordering to use for select the best samples. With:PostOrderDFSwe prioritize leaves, with:PreOrderDFSwe prioritize the root. Defaults to:PostOrderDFS.feedback_inplace::Bool: Whether to provide feedback in previous UserMessage (and remove the past AIMessage) or to create a new UserMessage. Defaults tofalse.feedback_template::Symbol: Template to use for feedback in place. Defaults to:FeedbackFromEvaluator.temperature::Float64: The temperature to use for sampling. Relevant only if not defined inapi_kwargsprovided. Defaults to 0.7.catch_errors::Bool: Whether to catch errors duringrun!of AICall. Saves them inaicall.error. Defaults tofalse.
SampleNode{T}A node in the Monte Carlo Tree Search tree.
It's used to hold the data we're trying to optimize/discover (eg, a conversation), the scores from evaluation (wins, visits) and the results of the evaluations upon failure (feedback).
Fields
id::UInt16: Unique identifier for the nodeparent::Union{SampleNode, Nothing}: Parent node that current node was built onchildren::Vector{SampleNode}: Children nodeswins::Int: Number of successful outcomesvisits::Int: Number of condition checks done (eg, losses arechecks - wins)data::T: eg, the conversation or some parameter to be optimizedfeedback::String: Feedback from the evaluation, always a string! Defaults to empty string.success::Union{Nothing, Bool}: Success of the generation and subsequent evaluations, proxy for whether it should be further evaluated. Defaults to nothing.
ThompsonSampling <: AbstractScoringMethodImplements scoring and selection for Thompson Sampling method. See https://en.wikipedia.org/wiki/Thompson_sampling for more details.
UCT <: AbstractScoringMethodImplements scoring and selection for UCT (Upper Confidence Bound for Trees) sampling method. See https://en.wikipedia.org/wiki/Monte_Carlo_tree_search#Exploration_and_exploitation for more details.
AIClassify(args...; kwargs...)Creates a lazy instance of aiclassify. It is an instance of AICall with aiclassify as the function.
Use exactly the same arguments and keyword arguments as aiclassify (see ?aiclassify for details).
AIEmbed(args...; kwargs...)Creates a lazy instance of aiembed. It is an instance of AICall with aiembed as the function.
Use exactly the same arguments and keyword arguments as aiembed (see ?aiembed for details).
AIExtract(args...; kwargs...)Creates a lazy instance of aiextract. It is an instance of AICall with aiextract as the function.
Use exactly the same arguments and keyword arguments as aiextract (see ?aiextract for details).
AIGenerate(args...; kwargs...)Creates a lazy instance of aigenerate. It is an instance of AICall with aigenerate as the function.
Use exactly the same arguments and keyword arguments as aigenerate (see ?aigenerate for details).
AIScan(args...; kwargs...)Creates a lazy instance of aiscan. It is an instance of AICall with aiscan as the function.
Use exactly the same arguments and keyword arguments as aiscan (see ?aiscan for details).
add_feedback!(\n conversation::AbstractVector{<:PT.AbstractMessage}, sample::SampleNode; feedback_inplace::Bool = false,\n feedback_template::Symbol = :FeedbackFromEvaluator)Adds formatted feedback to the conversation based on the sample node feedback (and its ancestors).
Arguments
conversation::AbstractVector{<:PT.AbstractMessage}: The conversation to add the feedback to.sample::SampleNode: The sample node to extract the feedback from.feedback_inplace::Bool=false: If true, it will add the feedback to the last user message inplace (and pop the last AIMessage). Otherwise, it will append the feedback as a new message.feedback_template::Symbol=:FeedbackFromEvaluator: The template to use for the feedback message. It must be a validAITemplatename.
Example
sample = SampleNode(; data = nothing, feedback = "Feedback X")\nconversation = [PT.UserMessage("I say hi!"), PT.AIMessage(; content = "I say hi!")]\nconversation = AT.add_feedback!(conversation, sample)\nconversation[end].content == "### Feedback from Evaluator\\nFeedback X\\n"\n\nInplace feedback:julia conversation = [PT.UserMessage("I say hi!"), PT.AIMessage(; content = "I say hi!")] conversation = AT.add_feedback!(conversation, sample; feedback_inplace = true) conversation[end].content == "I say hi!\\n\\n### Feedback from Evaluator\\nFeedback X\\n"
\nSample with ancestors with feedback:julia sample_p = SampleNode(; data = nothing, feedback = "\\nFeedback X") sample = expand!(sample_p, nothing) sample.feedback = "\\nFeedback Y" conversation = [PT.UserMessage("I say hi!"), PT.AIMessage(; content = "I say hi!")] conversation = AT.add_feedback!(conversation, sample)
conversation[end].content == "### Feedback from Evaluator\\n\\nFeedback X\\n–––––\\n\\nFeedback Y\\n" ```
aicodefixer_feedback(cb::AICode; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(conversation::AbstractVector{<:PT.AbstractMessage}; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(msg::PT.AIMessage; max_length::Int = 512) -> NamedTuple(; feedback::String)\naicodefixer_feedback(aicall::AICall; max_length::Int = 512) -> NamedTuple(; feedback::String)Generate feedback for an AI code fixing session based on the AICode block /or conversation history (that will be used to extract and evaluate a code block). Function is designed to be extensible for different types of feedback and code evaluation outcomes.
The highlevel wrapper accepts a conversation and returns new kwargs for the AICall.
Individual feedback functions are dispatched on different subtypes of AbstractCodeOutcome and can be extended/overwritten to provide more detailed feedback.
See also: AIGenerate, AICodeFixer
Arguments
cb::AICode: AICode block to evaluate and provide feedback on.max_length::Int=512: An optional argument that specifies the maximum length of the feedback message.
Returns
NamedTuple: A feedback message as a kwarg in NamedTuple based on the analysis of the code provided in the conversation.
Example
cb = AICode(msg; skip_unsafe = true, capture_stdout = true)\nnew_kwargs = aicodefixer_feedback(cb)\n\nnew_kwargs = aicodefixer_feedback(msg)\nnew_kwargs = aicodefixer_feedback(conversation)Notes
This function is part of the AI code fixing system, intended to interact with code in AIMessage and provide feedback on improving it.
The highlevel wrapper accepts a conversation and returns new kwargs for the AICall.
It dispatches for the code feedback based on the subtypes of AbstractCodeOutcome below:
CodeEmpty: No code found in the message.CodeFailedParse: Code parsing error.CodeFailedEval: Runtime evaluation error.CodeFailedTimeout: Code execution timed out.CodeSuccess: Successful code execution.
You can override the individual methods to customize the feedback.
airetry!(\n f_cond::Function, aicall::AICallBlock, feedback::Union{AbstractString, Function} = "";\n verbose::Bool = true, throw::Bool = false, evaluate_all::Bool = true, feedback_expensive::Bool = false,\n max_retries::Union{Nothing, Int} = nothing, retry_delay::Union{Nothing, Int} = nothing)Evaluates the condition f_cond on the aicall object. If the condition is not met, it will return the best sample to retry from and provide feedback (string or function) to aicall. That's why it's mutating. It will retry maximum max_retries times, with throw=true, an error will be thrown if the condition is not met after max_retries retries.
Note: aicall must be run first via run!(aicall) before calling airetry!.
Function signatures
f_cond(aicall::AICallBlock) -> Bool, ie, it must accept the aicall object and return a boolean value.feedbackcan be a string orfeedback(aicall::AICallBlock) -> String, ie, it must accept the aicall object and return a string.
You can leverage the last_message, last_output, and AICode functions to access the last message, last output and execute code blocks in the conversation, respectively. See examples below.
Good Use Cases
Retry with API failures/drops (add
retry_delay=2to wait 2s between retries)Check the output format / type / length / etc
Check the output with
aiclassifycall (LLM Judge) to catch unsafe/NSFW/out-of-scope contentProvide hints to the model to guide it to the correct answer
Gotchas
If controlling keyword arguments are set to nothing, they will fall back to the default values in
aicall.config. You can override them by passing the keyword arguments explicitly.If there multiple
airetry!checks, they are evaluted sequentially. As long asthrow==false, they will be all evaluated even if they failed previous checks.Only samples which passed previous evaluations are evaluated (
sample.successistrue). If there are no successful samples, the function will evaluate only the active sample (aicall.active_sample_id) and nothing else.Feedback from all "ancestor" evaluations is added upon retry, not feedback from the "sibblings" or other branches. To have only ONE long BRANCH (no sibblings), make sure to keep
RetryConfig(; n_samples=1). That way the model will always see ALL previous feedback.We implement a version of Monte Carlo Tree Search (MCTS) to always pick the most promising sample to restart from (you can tweak the options in
RetryConfigto change the behaviour).For large number of parallel branches (ie, "shallow and wide trees"), you might benefit from switching scoring to
scoring=ThompsonSampling()(similar to how Bandit algorithms work).Open-source/local models can struggle with too long conversation, you might want to experiment with
in-place feedback(setRetryConfig(; feedback_inplace=true)).
Arguments
f_cond::Function: A function that accepts theaicallobject and returns a boolean value. Retry will be attempted if the condition is not met (f_cond -> false).aicall::AICallBlock: Theaicallobject to evaluate the condition on.feedback::Union{AbstractString, Function}: Feedback to provide if the condition is not met. If a function is provided, it must accept theaicallobject as the only argument and return a string.verbose::Integer=1: A verbosity level for logging the retry attempts and warnings. A higher value indicates more detailed logging.throw::Bool=false: If true, it will throw an error if the functionf_conddoes not returntrueaftermax_retriesretries.evaluate_all::Bool=false: If true, it will evaluate all the "successful" samples in theaicallobject. Otherwise, it will only evaluate the active sample.feedback_expensive::Bool=false: If false, it will provide feedback to all samples that fail the condition. Iffeedbackfunction is expensive to call (eg, another ai* function), set this totrueand feedback will be provided only to the sample we will retry from.max_retries::Union{Nothing, Int}=nothing: Maximum number of retries. If not provided, it will fall back to themax_retriesinaicall.config.retry_delay::Union{Nothing, Int}=nothing: Delay between retries in seconds. If not provided, it will fall back to theretry_delayinaicall.config.
Returns
- The
aicallobject with the updatedconversation, andsamples(saves the evaluations and their scores/feedback).
Example
You can use airetry! to catch API errors in run! and auto-retry the call. RetryConfig is how you influence all the subsequent retry behaviours - see ?RetryConfig for more details.
# API failure because of a non-existent model\nout = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\n model = "NOTEXIST")\nrun!(out) # fails\n\n# we ask to wait 2s between retries and retry 2 times (can be set in `config` in aicall as well)\nairetry!(isvalid, out; retry_delay = 2, max_retries = 2)If you provide arguments to the aicall, we try to honor them as much as possible in the following calls, eg, set low verbosity
out = AIGenerate("say hi!"; config = RetryConfig(; catch_errors = true),\nmodel = "NOTEXIST", verbose=false)\nrun!(out)\n# No info message, you just see `success = false` in the properties of the AICallLet's show a toy example to demonstrate the runtime checks / guardrails for the model output. We'll play a color guessing game (I'm thinking "yellow"):
# Notice that we ask for two samples (`n_samples=2`) at each attempt (to improve our chances). \n# Both guesses are scored at each time step, and the best one is chosen for the next step.\n# And with OpenAI, we can set `api_kwargs = (;n=2)` to get both samples simultaneously (cheaper and faster)!\nout = AIGenerate(\n "Guess what color I'm thinking. It could be: blue, red, black, white, yellow. Answer with 1 word only";\n verbose = false,\n config = RetryConfig(; n_samples = 2), api_kwargs = (; n = 2))\nrun!(out)\n\n\n## Check that the output is 1 word only, third argument is the feedback that will be provided if the condition fails\n## Notice: functions operate on `aicall` as the only argument. We can use utilities like `last_output` and `last_message` to access the last message and output in the conversation.\nairetry!(x -> length(split(last_output(x), r" |\\.")) == 1, out,\n "You must answer with 1 word only.")\n\n\n## Let's ensure that the output is in lowercase - simple and short\nairetry!(x -> all(islowercase, last_output(x)), out, "You must answer in lowercase.")\n# [ Info: Condition not met. Retrying...\n\n\n## Let's add final hint - it took us 2 retries\nairetry!(x -> startswith(last_output(x), "y"), out, "It starts with "y"")\n# [ Info: Condition not met. Retrying...\n# [ Info: Condition not met. Retrying...\n\n\n## We end up with the correct answer\nlast_output(out)\n# Output: "yellow"Let's explore how we got here. We save the various attempts in a "tree" (SampleNode object) You can access it in out.samples, which is the ROOT of the tree (top level). Currently "active" sample ID is out.active_sample_id -> that's the same as conversation field in your AICall.
# Root node:\nout.samples\n# Output: SampleNode(id: 46839, stats: 6/12, length: 2)\n\n# Active sample (our correct answer):\nout.active_sample_id \n# Output: 50086\n\n# Let's obtain the active sample node with this ID - use getindex notation or function find_node\nout.samples[out.active_sample_id]\n# Output: SampleNode(id: 50086, stats: 1/1, length: 7)\n\n# The SampleNode has two key fields: data and feedback. Data is where the conversation is stored:\nactive_sample = out.samples[out.active_sample_id]\nactive_sample.data == out.conversation # Output: true -> This is the winning guess!We also get a clear view of the tree structure of all samples with print_samples:
julia> print_samples(out.samples)\nSampleNode(id: 46839, stats: 6/12, score: 0.5, length: 2)\n├─ SampleNode(id: 12940, stats: 5/8, score: 1.41, length: 4)\n│ ├─ SampleNode(id: 34315, stats: 3/4, score: 1.77, length: 6)\n│ │ ├─ SampleNode(id: 20493, stats: 1/1, score: 2.67, length: 7)\n│ │ └─ SampleNode(id: 50086, stats: 1/1, score: 2.67, length: 7)\n│ └─ SampleNode(id: 2733, stats: 1/2, score: 1.94, length: 5)\n└─ SampleNode(id: 48343, stats: 1/4, score: 1.36, length: 4)\n ├─ SampleNode(id: 30088, stats: 0/1, score: 1.67, length: 5)\n └─ SampleNode(id: 44816, stats: 0/1, score: 1.67, length: 5)You can use the id to grab and inspect any of these nodes, eg,
out.samples[2733]\n# Output: SampleNode(id: 2733, stats: 1/2, length: 5)We can also iterate through all samples and extract whatever information we want with PostOrderDFS or PreOrderDFS (exported from AbstractTrees.jl)
for sample in PostOrderDFS(out.samples)\n # Data is the universal field for samples, we put `conversation` in there\n # Last item in data is the last message in coversation\n msg = sample.data[end]\n if msg isa PT.AIMessage # skip feedback\n # get only the message content, ie, the guess\n println("ID: $(sample.id), Answer: $(msg.content)")\n end\nend\n\n# ID: 20493, Answer: yellow\n# ID: 50086, Answer: yellow\n# ID: 2733, Answer: red\n# ID: 30088, Answer: blue\n# ID: 44816, Answer: blueNote: airetry! will attempt to fix the model max_retries times. If you set throw=true, it will throw an ErrorException if the condition is not met after max_retries retries.
Let's define a mini program to guess the number and use airetry! to guide the model to the correct answer:
"""\n llm_guesser()\n\nMini program to guess the number provided by the user (betwee 1-100).\n"""\nfunction llm_guesser(user_number::Int)\n @assert 1 <= user_number <= 100\n prompt = """\nI'm thinking a number between 1-100. Guess which one it is. \nYou must respond only with digits and nothing else. \nYour guess:"""\n ## 2 samples at a time, max 5 fixing rounds\n out = AIGenerate(prompt; config = RetryConfig(; n_samples = 2, max_retries = 5),\n api_kwargs = (; n = 2)) |> run!\n ## Check the proper output format - must parse to Int, use do-syntax\n ## We can provide feedback via a function!\n function feedback_f(aicall)\n "Output: $(last_output(aicall))\nFeedback: You must respond only with digits!!"\n end\n airetry!(out, feedback_f) do aicall\n !isnothing(tryparse(Int, last_output(aicall)))\n end\n ## Give a hint on bounds\n lower_bound = (user_number ÷ 10) * 10\n upper_bound = lower_bound + 10\n airetry!(\n out, "The number is between or equal to $lower_bound to $upper_bound.") do aicall\n guess = tryparse(Int, last_output(aicall))\n lower_bound <= guess <= upper_bound\n end\n ## You can make at most 3x guess now -- if there is max_retries in `config.max_retries` left\n max_retries = out.config.retries + 3\n function feedback_f2(aicall)\n guess = tryparse(Int, last_output(aicall))\n "Your guess of $(guess) is wrong, it's $(abs(guess-user_number)) numbers away."\n end\n airetry!(out, feedback_f2; max_retries) do aicall\n tryparse(Int, last_output(aicall)) == user_number\n end\n\n ## Evaluate the best guess\n @info "Results: Guess: $(last_output(out)) vs User: $user_number (Number of calls made: $(out.config.calls))"\n return out\nend\n\n# Let's play the game\nout = llm_guesser(33)\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Condition not met. Retrying...\n[ Info: Results: Guess: 33 vs User: 33 (Number of calls made: 10)Yay! We got it 😃
Now, we could explore different samples (eg, print_samples(out.samples)) or see what the model guessed at each step:
print_samples(out.samples)\n## SampleNode(id: 57694, stats: 6/14, score: 0.43, length: 2)\n## ├─ SampleNode(id: 35603, stats: 5/10, score: 1.23, length: 4)\n## │ ├─ SampleNode(id: 55394, stats: 1/4, score: 1.32, length: 6)\n## │ │ ├─ SampleNode(id: 20737, stats: 0/1, score: 1.67, length: 7)\n## │ │ └─ SampleNode(id: 52910, stats: 0/1, score: 1.67, length: 7)\n## │ └─ SampleNode(id: 43094, stats: 3/4, score: 1.82, length: 6)\n## │ ├─ SampleNode(id: 14966, stats: 1/1, score: 2.67, length: 7)\n## │ └─ SampleNode(id: 32991, stats: 1/1, score: 2.67, length: 7)\n## └─ SampleNode(id: 20506, stats: 1/4, score: 1.4, length: 4)\n## ├─ SampleNode(id: 37581, stats: 0/1, score: 1.67, length: 5)\n## └─ SampleNode(id: 46632, stats: 0/1, score: 1.67, length: 5)\n\n# Lastly, let's check all the guesses AI made across all samples. \n# Our winning guess was ID 32991 (`out.active_sample_id`)\n\nfor sample in PostOrderDFS(out.samples)\n [println("ID: $(sample.id), Guess: $(msg.content)")\n for msg in sample.data if msg isa PT.AIMessage]\nend\n## ID: 20737, Guess: 50\n## ID: 20737, Guess: 35\n## ID: 20737, Guess: 37\n## ID: 52910, Guess: 50\n## ID: 52910, Guess: 35\n## ID: 52910, Guess: 32\n## ID: 14966, Guess: 50\n## ID: 14966, Guess: 35\n## ID: 14966, Guess: 33\n## ID: 32991, Guess: 50\n## ID: 32991, Guess: 35\n## ID: 32991, Guess: 33\n## etc...Note that if there are multiple "branches" the model will see only the feedback of its own and its ancestors not the other "branches". If you wanted to provide ALL feedback, set RetryConfig(; n_samples=1) to remove any "branching". It fixing will be done sequentially in one conversation and the model will see all feedback (less powerful if the model falls into a bad state). Alternatively, you can tweak the feedback function.
See Also
References: airetry is inspired by the Language Agent Tree Search paper and by DSPy Assertions paper.
Provides scores for a given node (and all its ancestors) based on the evaluation (wins, visits).
beta_sample(α::Real, β::Real)Approximates a sample from the Beta distribution by generating two independent Gamma distributed samples and using their ratio.
Collects all feedback from the node and its ancestors (parents). Returns a string separated by separator.
error_feedback(e::Any; max_length::Int = 512)Set of specialized methods to provide feedback on different types of errors (e).
evaluate_condition!(f_cond::Function, aicall::AICallBlock,\n feedback::Union{AbstractString, Function} = "";\n evaluate_all::Bool = true, feedback_expensive::Bool = false)Evalutes the condition f_cond (must return Bool) on the aicall object. If the condition is not met, it will return the best sample to retry from and provide feedback.
Mutating as the results are saved in aicall.samples
If evaluate_all is true, it will evaluate all the "successful" samples in the aicall object. Otherwise, it will only evaluate the active sample..
For f_cond and feedback functions, you can use the last_message and last_output utilities to access the last message and last output in the conversation, respectively.
Arguments
f_cond::Function: A function that accepts theaicallobject and returns a boolean value. Retry will be attempted if the condition is not met (f_cond -> false).aicall::AICallBlock: Theaicallobject to evaluate the condition on.feedback::Union{AbstractString, Function}: Feedback to provide if the condition is not met. If a function is provided, it must accept theaicallobject as the only argument and return a string.evaluate_all::Bool=false: If true, it will evaluate all the "successful" samples in theaicallobject. Otherwise, it will only evaluate the active sample.feedback_expensive::Bool=false: If false, it will provide feedback to all samples that fail the condition. Iffeedbackfunction is expensive to call (eg, another ai* function), set this totrueand feedback will be provided only to the sample we will retry from.
Returns
- a tuple
(condition_passed, sample), wherecondition_passedis a boolean indicating whether the condition was met, andsampleis the best sample to retry from.
Example
# Mimic AIGenerate run!\naicall = AIGenerate("Say hi!"; config = RetryConfig(; n_samples = 2))\nsample = expand!(aicall.samples, aicall.conversation; success = true)\naicall.active_sample_id = sample.id\n\n# Return whether it passed and node to take the next action from\ncond, node = AT.evaluate_condition!(x -> occursin("hi", last_output(x)), aicall)\n\n# Checks:\ncond == true\nnode == sample\nnode.wins == 1With feedback: ```julia
Mimic AIGenerate run with feedback
aicall = AIGenerate( :BlankSystemUser; system = "a", user = "b") sample = expand!(aicall.samples, aicall.conversation; success = true) aicall.active_sample_id = sample.id
Evaluate
cond, node = AT.evaluate_condition!( x -> occursin("NOTFOUND", last_output(x)), aicall, "Feedback X") cond == false # fail sample == node # same node (no other choice) node.wins == 0 node.feedback == " Feedback X"
Expands the tree with a new node from parent using the given data and success.
Extracts config::RetryConfig from kwargs and returns the rest of the kwargs.
Finds a node with a given id in the tree starting from node.
gamma_sample(α::Real, θ::Real)Approximates a sample from the Gamma distribution using the Marsaglia and Tsang method.
Pretty prints the samples tree starting from node. Usually, node is the root of the tree. Example: print_samples(aicall.samples).
Removes the kwargs that have already been used in the conversation. Returns NamedTuple.
Sets the success field of all nodes in the tree to success value.
run!(codefixer::AICodeFixer; verbose::Int = 1, max_conversation_length::Int = 32000, run_kwargs...)Executes the code fixing process encapsulated by the AICodeFixer instance. This method iteratively refines and fixes code by running the AI call in a loop for a specified number of rounds, using feedback from the code evaluation (aicodefixer_feedback) to improve the outcome in each iteration.
Arguments
codefixer::AICodeFixer: An instance ofAICodeFixercontaining the AI call, templates, and settings for the code fixing session.verbose::Int=1: Verbosity level for logging. A higher value indicates more detailed logging.max_conversation_length::Int=32000: Maximum length in characters for the conversation history to keep it within manageable limits, especially for large code fixing sessions.num_rounds::Union{Nothing, Int}=nothing: Number of additional rounds for the code fixing session. Ifnothing, the value from theAICodeFixerinstance is used.run_kwargs...: Additional keyword arguments that are passed to the AI function.
Returns
AICodeFixer: The updatedAICodeFixerinstance with the results of the code fixing session.
Usage
aicall = AICall(aigenerate, schema=mySchema, conversation=myConversation)\ncodefixer = AICodeFixer(aicall, myTemplates; num_rounds=5)\nresult = run!(codefixer, verbose=2)Notes
The
run!method drives the core logic of theAICodeFixer, iterating through rounds of AI interactions to refine and fix code.In each round, it applies feedback based on the current state of the conversation, allowing the AI to respond more effectively.
The conversation history is managed to ensure it stays within the specified
max_conversation_length, keeping the AI's focus on relevant parts of the conversation.This iterative process is essential for complex code fixing tasks where multiple interactions and refinements are required to achieve the desired outcome.
run!(aicall::AICallBlock; verbose::Int = 1, catch_errors::Bool = false, return_all::Bool = true, kwargs...)Executes the AI call wrapped by an AICallBlock instance. This method triggers the actual communication with the AI model and processes the response based on the provided conversation context and parameters.
Note: Currently return_all must always be set to true.
Arguments
aicall::AICallBlock: An instance ofAICallBlockwhich encapsulates the AI function call along with its context and parameters (eg,AICall,AIGenerate)verbose::Integer=1: A verbosity level for logging. A higher value indicates more detailed logging.catch_errors::Union{Nothing, Bool}=nothing: A flag to indicate whether errors should be caught and saved toaicall.error. Ifnothing, it defaults toaicall.config.catch_errors.return_all::Bool=true: A flag to indicate whether the whole conversation from the AI call should be returned. It should always be true.kwargs...: Additional keyword arguments that are passed to the AI function.
Returns
AICallBlock: The sameAICallBlockinstance, updated with the results of the AI call. This includes updated conversation, success status, and potential error information.
Example
aicall = AICall(aigenerate)\nrun!(aicall)Alternatively, you can trigger the run! call by using the AICall as a functor and calling it with a string or a UserMessage:
aicall = AICall(aigenerate)\naicall("Say hi!")Notes
The
run!method is a key component of the lazy evaluation model inAICall. It allows for the deferred execution of AI function calls, providing flexibility in how and when AI interactions are conducted.The method updates the
AICallBlockinstance with the outcome of the AI call, including any generated responses, success or failure status, and error information if an error occurred.This method is essential for scenarios where AI interactions are based on dynamic or evolving contexts, as it allows for real-time updates and responses based on the latest information.
Scores a node using the ThomsonSampling method, similar to Bandit algorithms.
Scores a node using the UCT (Upper Confidence Bound for Trees) method.
select_best(node::SampleNode, scoring::AbstractScoringMethod = UCT();\n ordering::Symbol = :PostOrderDFS)Selects the best node from the tree using the given scoring (UCT or ThompsonSampling). Defaults to UCT. Thompson Sampling is more random with small samples, while UCT stabilizes much quicker thanks to looking at parent nodes as well.
Ordering can be either :PreOrderDFS or :PostOrderDFS. Defaults to :PostOrderDFS, which favors the leaves (end points of the tree).
Example
Compare the different scoring methods:
# Set up mock samples and scores\ndata = PT.AbstractMessage[]\nroot = SampleNode(; data)\nchild1 = expand!(root, data)\nbackpropagate!(child1; wins = 1, visits = 1)\nchild2 = expand!(root, data)\nbackpropagate!(child2; wins = 0, visits = 1)\nchild11 = expand!(child1, data)\nbackpropagate!(child11; wins = 1, visits = 1)\n\n# Select with UCT\nn = select_best(root, UCT())\nSampleNode(id: 29826, stats: 1/1, length: 0)\n\n# Show the tree:\nprint_samples(root; scoring = UCT())\n## SampleNode(id: 13184, stats: 2/3, score: 0.67, length: 0)\n## ├─ SampleNode(id: 26078, stats: 2/2, score: 2.05, length: 0)\n## │ └─ SampleNode(id: 29826, stats: 1/1, score: 2.18, length: 0)\n## └─ SampleNode(id: 39931, stats: 0/1, score: 1.48, length: 0)\n\n# Select with ThompsonSampling - much more random with small samples\nn = select_best(root, ThompsonSampling())\nSampleNode(id: 26078, stats: 2/2, length: 0)\n\n# Show the tree (run it a few times and see how the scores jump around):\nprint_samples(root; scoring = ThompsonSampling())\n## SampleNode(id: 13184, stats: 2/3, score: 0.6, length: 0)\n## ├─ SampleNode(id: 26078, stats: 2/2, score: 0.93, length: 0)\n## │ └─ SampleNode(id: 29826, stats: 1/1, score: 0.22, length: 0)\n## └─ SampleNode(id: 39931, stats: 0/1, score: 0.84, length: 0)If the conversation has multiple AIMessage samples, split them into separate conversations with the common past.
truncate_conversation(conversation::AbstractVector{<:PT.AbstractMessage};\n max_conversation_length::Int = 32000)Truncates a given conversation to a max_conversation_length characters by removing messages "in the middle". It tries to retain the original system+user message and also the most recent messages.
Practically, if a conversation is too long, it will start by removing the most recent message EXCEPT for the last two (assumed to be the last AIMessage with the code and UserMessage with the feedback
Arguments
max_conversation_length is in characters; assume c. 2-3 characters per LLM token, so 32000 should correspond to 16K context window.
Unwraps the arguments for AICall and returns the schema and conversation (if provided). Expands any provided AITemplate.
Helpful accessor for AICall blocks. Returns the last message in the conversation.
Helpful accessor for AICall blocks. Returns the last output in the conversation (eg, the string/data in the last message).
', 76) + ])); +} +const reference_agenttools = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference_agenttools as default +}; diff --git a/previews/PR252/assets/reference_apitools.md.Dsnm-YWy.js b/previews/PR252/assets/reference_apitools.md.Dsnm-YWy.js new file mode 100644 index 00000000..c642d37e --- /dev/null +++ b/previews/PR252/assets/reference_apitools.md.Dsnm-YWy.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference for APITools","description":"","frontmatter":{},"headers":[],"relativePath":"reference_apitools.md","filePath":"reference_apitools.md","lastUpdated":null}'); +const _sfc_main = { name: "reference_apitools.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Reference for APITools
PromptingTools.Experimental.APITools.create_websearchPromptingTools.Experimental.APITools.tavily_api
create_websearch(query::AbstractString;\n api_key::AbstractString,\n search_depth::AbstractString = "basic")Arguments
query::AbstractString: The query to search for.api_key::AbstractString: The API key to use for the search. Get an API key from Tavily.search_depth::AbstractString: The depth of the search. Can be either "basic" or "advanced". Default is "basic". Advanced search calls equal to 2 requests.include_answer::Bool: Whether to include the answer in the search results. Default isfalse.include_raw_content::Bool: Whether to include the raw content in the search results. Default isfalse.max_results::Integer: The maximum number of results to return. Default is 5.include_images::Bool: Whether to include images in the search results. Default isfalse.include_domains::AbstractVector{<:AbstractString}: A list of domains to include in the search results. Default is an empty list.exclude_domains::AbstractVector{<:AbstractString}: A list of domains to exclude from the search results. Default is an empty list.
Example
r = create_websearch("Who is King Charles?")Even better, you can get not just the results but also the answer:
r = create_websearch("Who is King Charles?"; include_answer = true)See Rest API documentation for more information.
tavily_api(;\n api_key::AbstractString,\n endpoint::String = "search",\n url::AbstractString = "https://api.tavily.com",\n http_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Sends API requests to Tavily and returns the response.
', 6) + ])); +} +const reference_apitools = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference_apitools as default +}; diff --git a/previews/PR252/assets/reference_apitools.md.Dsnm-YWy.lean.js b/previews/PR252/assets/reference_apitools.md.Dsnm-YWy.lean.js new file mode 100644 index 00000000..c642d37e --- /dev/null +++ b/previews/PR252/assets/reference_apitools.md.Dsnm-YWy.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference for APITools","description":"","frontmatter":{},"headers":[],"relativePath":"reference_apitools.md","filePath":"reference_apitools.md","lastUpdated":null}'); +const _sfc_main = { name: "reference_apitools.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Reference for APITools
PromptingTools.Experimental.APITools.create_websearchPromptingTools.Experimental.APITools.tavily_api
create_websearch(query::AbstractString;\n api_key::AbstractString,\n search_depth::AbstractString = "basic")Arguments
query::AbstractString: The query to search for.api_key::AbstractString: The API key to use for the search. Get an API key from Tavily.search_depth::AbstractString: The depth of the search. Can be either "basic" or "advanced". Default is "basic". Advanced search calls equal to 2 requests.include_answer::Bool: Whether to include the answer in the search results. Default isfalse.include_raw_content::Bool: Whether to include the raw content in the search results. Default isfalse.max_results::Integer: The maximum number of results to return. Default is 5.include_images::Bool: Whether to include images in the search results. Default isfalse.include_domains::AbstractVector{<:AbstractString}: A list of domains to include in the search results. Default is an empty list.exclude_domains::AbstractVector{<:AbstractString}: A list of domains to exclude from the search results. Default is an empty list.
Example
r = create_websearch("Who is King Charles?")Even better, you can get not just the results but also the answer:
r = create_websearch("Who is King Charles?"; include_answer = true)See Rest API documentation for more information.
tavily_api(;\n api_key::AbstractString,\n endpoint::String = "search",\n url::AbstractString = "https://api.tavily.com",\n http_kwargs::NamedTuple = NamedTuple(),\n kwargs...)Sends API requests to Tavily and returns the response.
', 6) + ])); +} +const reference_apitools = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference_apitools as default +}; diff --git a/previews/PR252/assets/reference_experimental.md.BnIb-nyV.js b/previews/PR252/assets/reference_experimental.md.BnIb-nyV.js new file mode 100644 index 00000000..99256001 --- /dev/null +++ b/previews/PR252/assets/reference_experimental.md.BnIb-nyV.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference for Experimental Module","description":"","frontmatter":{},"headers":[],"relativePath":"reference_experimental.md","filePath":"reference_experimental.md","lastUpdated":null}'); +const _sfc_main = { name: "reference_experimental.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Reference for Experimental Module
Note: This module is experimental and may change in future releases. The intention is for the functionality to be moved to separate packages over time.
ExperimentalThis module is for experimental code that is not yet ready for production. It is not included in the main module, so it must be explicitly imported.
Contains:
RAGTools: Retrieval-Augmented Generation (RAG) functionality.AgentTools: Agentic functionality - lazy calls for building pipelines (eg,AIGenerate) andAICodeFixer.APITools: APIs to complement GenAI workflows (eg, Tavily Search API).
', 5) + ])); +} +const reference_experimental = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference_experimental as default +}; diff --git a/previews/PR252/assets/reference_experimental.md.BnIb-nyV.lean.js b/previews/PR252/assets/reference_experimental.md.BnIb-nyV.lean.js new file mode 100644 index 00000000..99256001 --- /dev/null +++ b/previews/PR252/assets/reference_experimental.md.BnIb-nyV.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference for Experimental Module","description":"","frontmatter":{},"headers":[],"relativePath":"reference_experimental.md","filePath":"reference_experimental.md","lastUpdated":null}'); +const _sfc_main = { name: "reference_experimental.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Reference for Experimental Module
Note: This module is experimental and may change in future releases. The intention is for the functionality to be moved to separate packages over time.
ExperimentalThis module is for experimental code that is not yet ready for production. It is not included in the main module, so it must be explicitly imported.
Contains:
RAGTools: Retrieval-Augmented Generation (RAG) functionality.AgentTools: Agentic functionality - lazy calls for building pipelines (eg,AIGenerate) andAICodeFixer.APITools: APIs to complement GenAI workflows (eg, Tavily Search API).
', 5) + ])); +} +const reference_experimental = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference_experimental as default +}; diff --git a/previews/PR252/assets/reference_ragtools.md.9-ISgMxz.js b/previews/PR252/assets/reference_ragtools.md.9-ISgMxz.js new file mode 100644 index 00000000..d64e1af5 --- /dev/null +++ b/previews/PR252/assets/reference_ragtools.md.9-ISgMxz.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference for RAGTools","description":"","frontmatter":{},"headers":[],"relativePath":"reference_ragtools.md","filePath":"reference_ragtools.md","lastUpdated":null}'); +const _sfc_main = { name: "reference_ragtools.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Reference for RAGTools
PromptingTools.Experimental.RAGTools.AbstractCandidateChunksPromptingTools.Experimental.RAGTools.AbstractChunkIndexPromptingTools.Experimental.RAGTools.AbstractGeneratorPromptingTools.Experimental.RAGTools.AbstractIndexBuilderPromptingTools.Experimental.RAGTools.AbstractMultiIndexPromptingTools.Experimental.RAGTools.AbstractRetrieverPromptingTools.Experimental.RAGTools.AdvancedGeneratorPromptingTools.Experimental.RAGTools.AdvancedRetrieverPromptingTools.Experimental.RAGTools.AllTagFilterPromptingTools.Experimental.RAGTools.AnnotatedNodePromptingTools.Experimental.RAGTools.AnyTagFilterPromptingTools.Experimental.RAGTools.BM25SimilarityPromptingTools.Experimental.RAGTools.BatchEmbedderPromptingTools.Experimental.RAGTools.BinaryBatchEmbedderPromptingTools.Experimental.RAGTools.BinaryCosineSimilarityPromptingTools.Experimental.RAGTools.BitPackedBatchEmbedderPromptingTools.Experimental.RAGTools.BitPackedCosineSimilarityPromptingTools.Experimental.RAGTools.CandidateChunksPromptingTools.Experimental.RAGTools.ChunkEmbeddingsIndexPromptingTools.Experimental.RAGTools.ChunkKeywordsIndexPromptingTools.Experimental.RAGTools.ChunkKeywordsIndexPromptingTools.Experimental.RAGTools.CohereRerankerPromptingTools.Experimental.RAGTools.ContextEnumeratorPromptingTools.Experimental.RAGTools.CosineSimilarityPromptingTools.Experimental.RAGTools.DocumentTermMatrixPromptingTools.Experimental.RAGTools.FileChunkerPromptingTools.Experimental.RAGTools.FlashRankerPromptingTools.Experimental.RAGTools.HTMLStylerPromptingTools.Experimental.RAGTools.HyDERephraserPromptingTools.Experimental.RAGTools.JudgeAllScoresPromptingTools.Experimental.RAGTools.JudgeRatingPromptingTools.Experimental.RAGTools.KeywordsIndexerPromptingTools.Experimental.RAGTools.KeywordsProcessorPromptingTools.Experimental.RAGTools.MultiCandidateChunksPromptingTools.Experimental.RAGTools.MultiFinderPromptingTools.Experimental.RAGTools.MultiIndexPromptingTools.Experimental.RAGTools.NoEmbedderPromptingTools.Experimental.RAGTools.NoPostprocessorPromptingTools.Experimental.RAGTools.NoProcessorPromptingTools.Experimental.RAGTools.NoRefinerPromptingTools.Experimental.RAGTools.NoRephraserPromptingTools.Experimental.RAGTools.NoRerankerPromptingTools.Experimental.RAGTools.NoTagFilterPromptingTools.Experimental.RAGTools.NoTaggerPromptingTools.Experimental.RAGTools.OpenTaggerPromptingTools.Experimental.RAGTools.PassthroughTaggerPromptingTools.Experimental.RAGTools.RAGConfigPromptingTools.Experimental.RAGTools.RAGResultPromptingTools.Experimental.RAGTools.RankGPTRerankerPromptingTools.Experimental.RAGTools.RankGPTResultPromptingTools.Experimental.RAGTools.SimpleAnswererPromptingTools.Experimental.RAGTools.SimpleBM25RetrieverPromptingTools.Experimental.RAGTools.SimpleGeneratorPromptingTools.Experimental.RAGTools.SimpleIndexerPromptingTools.Experimental.RAGTools.SimpleRefinerPromptingTools.Experimental.RAGTools.SimpleRephraserPromptingTools.Experimental.RAGTools.SimpleRetrieverPromptingTools.Experimental.RAGTools.StylerPromptingTools.Experimental.RAGTools.SubChunkIndexPromptingTools.Experimental.RAGTools.SubDocumentTermMatrixPromptingTools.Experimental.RAGTools.TavilySearchRefinerPromptingTools.Experimental.RAGTools.TextChunkerPromptingTools.Experimental.RAGTools.TrigramAnnotaterPromptingTools.Experimental.RAGTools._normalizePromptingTools.Experimental.RAGTools.add_node_metadata!PromptingTools.Experimental.RAGTools.airagPromptingTools.Experimental.RAGTools.align_node_styles!PromptingTools.Experimental.RAGTools.annotate_supportPromptingTools.Experimental.RAGTools.annotate_supportPromptingTools.Experimental.RAGTools.answer!PromptingTools.Experimental.RAGTools.build_contextPromptingTools.Experimental.RAGTools.build_indexPromptingTools.Experimental.RAGTools.build_indexPromptingTools.Experimental.RAGTools.build_qa_evalsPromptingTools.Experimental.RAGTools.build_tagsPromptingTools.Experimental.RAGTools.build_tagsPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.cohere_apiPromptingTools.Experimental.RAGTools.create_permutation_instructionPromptingTools.Experimental.RAGTools.extract_rankingPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.generate!PromptingTools.Experimental.RAGTools.get_chunksPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.getpropertynestedPromptingTools.Experimental.RAGTools.hamming_distancePromptingTools.Experimental.RAGTools.hcat_truncatePromptingTools.Experimental.RAGTools.load_textPromptingTools.Experimental.RAGTools.merge_kwargs_nestedPromptingTools.Experimental.RAGTools.pack_bitsPromptingTools.Experimental.RAGTools.permutation_step!PromptingTools.Experimental.RAGTools.preprocess_tokensPromptingTools.Experimental.RAGTools.print_htmlPromptingTools.Experimental.RAGTools.rank_gptPromptingTools.Experimental.RAGTools.rank_sliding_window!PromptingTools.Experimental.RAGTools.receive_permutation!PromptingTools.Experimental.RAGTools.reciprocal_rank_fusionPromptingTools.Experimental.RAGTools.reciprocal_rank_fusionPromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rerankPromptingTools.Experimental.RAGTools.rerankPromptingTools.Experimental.RAGTools.retrievePromptingTools.Experimental.RAGTools.run_qa_evalsPromptingTools.Experimental.RAGTools.run_qa_evalsPromptingTools.Experimental.RAGTools.score_retrieval_hitPromptingTools.Experimental.RAGTools.score_retrieval_rankPromptingTools.Experimental.RAGTools.score_to_unit_scalePromptingTools.Experimental.RAGTools.set_node_style!PromptingTools.Experimental.RAGTools.setpropertynestedPromptingTools.Experimental.RAGTools.split_into_code_and_sentencesPromptingTools.Experimental.RAGTools.tags_extractPromptingTools.Experimental.RAGTools.token_with_boundariesPromptingTools.Experimental.RAGTools.tokenizePromptingTools.Experimental.RAGTools.translate_positions_to_parentPromptingTools.Experimental.RAGTools.translate_positions_to_parentPromptingTools.Experimental.RAGTools.trigram_support!PromptingTools.Experimental.RAGTools.trigramsPromptingTools.Experimental.RAGTools.trigrams_hashed
RAGToolsProvides Retrieval-Augmented Generation (RAG) functionality.
Requires: LinearAlgebra, SparseArrays, Unicode, PromptingTools for proper functionality.
This module is experimental and may change at any time. It is intended to be moved to a separate package in the future.
AbstractCandidateChunksAbstract type for storing candidate chunks, ie, references to items in a AbstractChunkIndex.
Return type from find_closest and find_tags functions.
Required Fields
index_id::Symbol: the id of the index from which the candidates are drawnpositions::Vector{Int}: the positions of the candidates in the indexscores::Vector{Float32}: the similarity scores of the candidates from the query (higher is better)
AbstractChunkIndex <: AbstractDocumentIndexMain abstract type for storing document chunks and their embeddings. It also stores tags and sources for each chunk.
Required Fields
id::Symbol: unique identifier of each index (to ensure we're using the right index withCandidateChunks)chunks::Vector{<:AbstractString}: underlying document chunks / snippetsembeddings::Union{Nothing, Matrix{<:Real}}: for semantic searchtags::Union{Nothing, AbstractMatrix{<:Bool}}: for exact search, filtering, etc. This is often a sparse matrix indicating which chunks have the giventag(seetag_vocabfor the position lookup)tags_vocab::Union{Nothing, Vector{<:AbstractString}}: vocabulary for thetagsmatrix (each column intagsis one item intags_vocaband rows are the chunks)sources::Vector{<:AbstractString}: sources of the chunksextras::Union{Nothing, AbstractVector}: additional data, eg, metadata, source code, etc.
AbstractGenerator <: AbstractGenerationMethodAbstract type for generating an answer with generate! (use to change the process / return type of generate).
Required Fields
contexter::AbstractContextBuilder: the context building method, dispatching `build_context!answerer::AbstractAnswerer: the answer generation method, dispatchinganswer!refiner::AbstractRefiner: the answer refining method, dispatchingrefine!postprocessor::AbstractPostprocessor: the postprocessing method, dispatchingpostprocess!
AbstractIndexBuilderAbstract type for building an index with build_index (use to change the process / return type of build_index).
Required Fields
chunker::AbstractChunker: the chunking method, dispatchingget_chunksembedder::AbstractEmbedder: the embedding method, dispatchingget_embeddingstagger::AbstractTagger: the tagging method, dispatchingget_tags
AbstractMultiIndex <: AbstractDocumentIndexExperimental abstract type for storing multiple document indexes. Not yet implemented.
AbstractRetriever <: AbstractRetrievalMethodAbstract type for retrieving chunks from an index with retrieve (use to change the process / return type of retrieve).
Required Fields
rephraser::AbstractRephraser: the rephrasing method, dispatchingrephrasefinder::AbstractSimilarityFinder: the similarity search method, dispatchingfind_closestfilter::AbstractTagFilter: the tag matching method, dispatchingfind_tagsreranker::AbstractReranker: the reranking method, dispatchingrerank
AdvancedGenerator <: AbstractGeneratorDefault implementation for generate!. It simply enumerates context snippets and runs aigenerate (no refinement).
It uses ContextEnumerator, SimpleAnswerer, SimpleRefiner, and NoPostprocessor as default contexter, answerer, refiner, and postprocessor.
AdvancedRetriever <: AbstractRetrieverDispatch for retrieve with advanced retrieval methods to improve result quality. Compared to SimpleRetriever, it adds rephrasing the query and reranking the results.
Fields
rephraser::AbstractRephraser: the rephrasing method, dispatchingrephrase- usesHyDERephraserembedder::AbstractEmbedder: the embedding method, dispatchingget_embeddings(see Preparation Stage for more details) - usesBatchEmbedderprocessor::AbstractProcessor: the processor method, dispatchingget_keywords(see Preparation Stage for more details) - usesNoProcessorfinder::AbstractSimilarityFinder: the similarity search method, dispatchingfind_closest- usesCosineSimilaritytagger::AbstractTagger: the tag generating method, dispatchingget_tags(see Preparation Stage for more details) - usesNoTaggerfilter::AbstractTagFilter: the tag matching method, dispatchingfind_tags- usesNoTagFilterreranker::AbstractReranker: the reranking method, dispatchingrerank- usesCohereReranker
AllTagFilter <: AbstractTagFilterFinds the chunks that have ALL OF the specified tag(s). A method for find_tags.
AnnotatedNode{T} <: AbstractAnnotatedNodeA node to add annotations to the generated answer in airag
Annotations can be: sources, scores, whether its supported or not by the context, etc.
Fields
group_id::Int: Unique identifier for the same group of nodes (eg, different lines of the same code block)parent::Union{AnnotatedNode, Nothing}: Parent node that current node was built onchildren::Vector{AnnotatedNode}: Children nodes`score::
AnyTagFilter <: AbstractTagFilterFinds the chunks that have ANY OF the specified tag(s). A method for find_tags.
BM25Similarity <: AbstractSimilarityFinderFinds the closest chunks to a query embedding by measuring the BM25 similarity between the query and the chunks' embeddings in binary form. A method for find_closest.
Reference: Wikipedia: BM25. Implementation follows: The Next Generation of Lucene Relevance.
BatchEmbedder <: AbstractEmbedderDefault embedder for get_embeddings functions. It passes individual documents to be embedded in chunks to aiembed.
BinaryBatchEmbedder <: AbstractEmbedderSame as BatchEmbedder but reduces the embeddings matrix to a binary form (eg, BitMatrix). Defines a method for get_embeddings.
Reference: HuggingFace: Embedding Quantization.
BinaryCosineSimilarity <: AbstractSimilarityFinderFinds the closest chunks to a query embedding by measuring the Hamming distance AND cosine similarity between the query and the chunks' embeddings in binary form. A method for find_closest.
It follows the two-pass approach:
First pass: Hamming distance in binary form to get the
top_k * rescore_multiplier(ie, more than top_k) candidates.Second pass: Rescore the candidates with float embeddings and return the top_k.
Reference: HuggingFace: Embedding Quantization.
BitPackedBatchEmbedder <: AbstractEmbedderSame as BatchEmbedder but reduces the embeddings matrix to a binary form packed in UInt64 (eg, BitMatrix.chunks). Defines a method for get_embeddings.
See also utilities pack_bits and unpack_bits to move between packed/non-packed binary forms.
Reference: HuggingFace: Embedding Quantization.
BitPackedCosineSimilarity <: AbstractSimilarityFinderFinds the closest chunks to a query embedding by measuring the Hamming distance AND cosine similarity between the query and the chunks' embeddings in binary form. A method for find_closest.
The difference to BinaryCosineSimilarity is that the binary values are packed into UInt64, which is more efficient.
Reference: HuggingFace: Embedding Quantization. Implementation of hamming_distance is based on TinyRAG.
CandidateChunksA struct for storing references to chunks in the given index (identified by index_id) called positions and scores holding the strength of similarity (=1 is the highest, most similar). It's the result of the retrieval stage of RAG.
Fields
index_id::Symbol: the id of the index from which the candidates are drawnpositions::Vector{Int}: the positions of the candidates in the index (ie,5refers to the 5th chunk in the index -chunks(index)[5])scores::Vector{Float32}: the similarity scores of the candidates from the query (higher is better)
ChunkEmbeddingsIndexMain struct for storing document chunks and their embeddings. It also stores tags and sources for each chunk.
Previously, this struct was called ChunkIndex.
Fields
id::Symbol: unique identifier of each index (to ensure we're using the right index withCandidateChunks)chunks::Vector{<:AbstractString}: underlying document chunks / snippetsembeddings::Union{Nothing, Matrix{<:Real}}: for semantic searchtags::Union{Nothing, AbstractMatrix{<:Bool}}: for exact search, filtering, etc. This is often a sparse matrix indicating which chunks have the giventag(seetag_vocabfor the position lookup)tags_vocab::Union{Nothing, Vector{<:AbstractString}}: vocabulary for thetagsmatrix (each column intagsis one item intags_vocaband rows are the chunks)sources::Vector{<:AbstractString}: sources of the chunksextras::Union{Nothing, AbstractVector}: additional data, eg, metadata, source code, etc.
ChunkKeywordsIndexStruct for storing chunks of text and associated keywords for BM25 similarity search.
Fields
id::Symbol: unique identifier of each index (to ensure we're using the right index withCandidateChunks)chunks::Vector{<:AbstractString}: underlying document chunks / snippetschunkdata::Union{Nothing, AbstractMatrix{<:Real}}: for similarity search, assumed to beDocumentTermMatrixtags::Union{Nothing, AbstractMatrix{<:Bool}}: for exact search, filtering, etc. This is often a sparse matrix indicating which chunks have the giventag(seetag_vocabfor the position lookup)tags_vocab::Union{Nothing, Vector{<:AbstractString}}: vocabulary for thetagsmatrix (each column intagsis one item intags_vocaband rows are the chunks)sources::Vector{<:AbstractString}: sources of the chunksextras::Union{Nothing, AbstractVector}: additional data, eg, metadata, source code, etc.
Example
We can easily create a keywords-based index from a standard embeddings-based index.
\n# Let's assume we have a standard embeddings-based index\nindex = build_index(SimpleIndexer(), texts; chunker_kwargs = (; max_length=10))\n\n# Creating an additional index for keyword-based search (BM25), is as simple as\nindex_keywords = ChunkKeywordsIndex(index)\n\n# We can immediately create a MultiIndex (a hybrid index holding both indices)\nmulti_index = MultiIndex([index, index_keywords])You can also build the index via build_index
# given some sentences and sources\nindex_keywords = build_index(KeywordsIndexer(), sentences; chunker_kwargs=(; sources))\n\n# Retrive closest chunks with\nretriever = SimpleBM25Retriever()\nresult = retrieve(retriever, index_keywords, "What are the best practices for parallel computing in Julia?")\nresult.contextIf you want to use airag, don't forget to specify the config to make sure keywords are processed (ie, tokenized) and that BM25 is used for searching candidates
cfg = RAGConfig(; retriever = SimpleBM25Retriever());\nairag(cfg, index_keywords;\n question = "What are the best practices for parallel computing in Julia?")ChunkKeywordsIndex(\n [processor::AbstractProcessor=KeywordsProcessor(),] index::ChunkEmbeddingsIndex; verbose::Int = 1,\n index_id = gensym("ChunkKeywordsIndex"), processor_kwargs...)Convenience method to quickly create a ChunkKeywordsIndex from an existing ChunkEmbeddingsIndex.
Example
\n# Let's assume we have a standard embeddings-based index\nindex = build_index(SimpleIndexer(), texts; chunker_kwargs = (; max_length=10))\n\n# Creating an additional index for keyword-based search (BM25), is as simple as\nindex_keywords = ChunkKeywordsIndex(index)\n\n# We can immediately create a MultiIndex (a hybrid index holding both indices)\nmulti_index = MultiIndex([index, index_keywords])CohereReranker <: AbstractRerankerRerank strategy using the Cohere Rerank API. Requires an API key. A method for rerank.
ContextEnumerator <: AbstractContextBuilderDefault method for build_context! method. It simply enumerates the context snippets around each position in candidates. When possibly, it will add surrounding chunks (from the same source).
CosineSimilarity <: AbstractSimilarityFinderFinds the closest chunks to a query embedding by measuring the cosine similarity between the query and the chunks' embeddings. A method for find_closest (see the docstring for more details and usage example).
DocumentTermMatrix{T<:AbstractString}A sparse matrix of term frequencies and document lengths to allow calculation of BM25 similarity scores.
FileChunker <: AbstractChunkerChunker when you provide file paths to get_chunks functions.
Ie, the inputs will be validated first (eg, file exists, etc) and then read into memory.
Set as default chunker in get_chunks functions.
FlashRanker <: AbstractRerankerRerank strategy using the package FlashRank.jl and local models. A method for rerank.
You must first import the FlashRank.jl package. To automatically download any required models, set your ENV["DATADEPS_ALWAYS_ACCEPT"] = true (see DataDeps for more details).
Example
using FlashRank\n\n# Wrap the model to be a valid Ranker recognized by RAGTools\n# It will be provided to the airag/rerank function to avoid instantiating it on every call\nreranker = FlashRank.RankerModel(:mini) |> FlashRanker\n# You can choose :tiny or :mini\n\n## Apply to the pipeline configuration, eg, \ncfg = RAGConfig(; retriever = AdvancedRetriever(; reranker))\n\n# Ask a question (assumes you have some `index`)\nquestion = "What are the best practices for parallel computing in Julia?"\nresult = airag(cfg, index; question, return_all = true)HTMLStylerDefines styling via classes (attribute class) and styles (attribute style) for HTML formatting of AbstractAnnotatedNode
HyDERephraser <: AbstractRephraserRephraser implemented using the provided AI Template (eg, ...) and standard chat model. A method for rephrase.
It uses a prompt-based rephrasing method called HyDE (Hypothetical Document Embedding), where instead of looking for an embedding of the question, we look for the documents most similar to a synthetic passage that would be a good answer to our question.
Reference: Arxiv paper.
final_rating is the average of all scoring criteria. Explain the final_rating in rationale
Provide the final_rating between 1-5. Provide the rationale for it.
KeywordsIndexer <: AbstractIndexBuilderKeyword-based index (BM25) to be returned by build_index.
It uses TextChunker, KeywordsProcessor, and NoTagger as default chunker, processor, and tagger.
KeywordsProcessor <: AbstractProcessorDefault keywords processor for get_keywords functions. It normalizes the documents, tokenizes them and builds a DocumentTermMatrix.
MultiCandidateChunksA struct for storing references to multiple sets of chunks across different indices. Each set of chunks is identified by an index_id in index_ids, with corresponding positions in the index and scores indicating the strength of similarity.
This struct is useful for scenarios where candidates are drawn from multiple indices, and there is a need to keep track of which candidates came from which index.
Fields
index_ids::Vector{Symbol}: the ids of the indices from which the candidates are drawnpositions::Vector{TP}: the positions of the candidates in their respective indicesscores::Vector{TD}: the similarity scores of the candidates from the query
MultiFinder <: AbstractSimilarityFinderComposite finder for MultiIndex where we want to set multiple finders for each index. A method for find_closest. Positions correspond to indexes(::MultiIndex).
MultiIndexComposite index that stores multiple ChunkIndex objects and their embeddings.
Fields
id::Symbol: unique identifier of each index (to ensure we're using the right index withCandidateChunks)indexes::Vector{<:AbstractChunkIndex}: the indexes to be combined
Use accesor indexes to access the individual indexes.
Examples
We can create a MultiIndex from a vector of AbstractChunkIndex objects.
index = build_index(SimpleIndexer(), texts; chunker_kwargs = (; sources))\nindex_keywords = ChunkKeywordsIndex(index) # same chunks as above but adds BM25 instead of embeddings\n\nmulti_index = MultiIndex([index, index_keywords])To use airag with different types of indices, we need to specify how to find the closest items for each index
# Cosine similarity for embeddings and BM25 for keywords, same order as indexes in MultiIndex\nfinder = RT.MultiFinder([RT.CosineSimilarity(), RT.BM25Similarity()])\n\n# Notice that we add `processor` to make sure keywords are processed (ie, tokenized) as well\ncfg = RAGConfig(; retriever = SimpleRetriever(; processor = RT.KeywordsProcessor(), finder))\n\n# Ask questions\nmsg = airag(cfg, multi_index; question = "What are the best practices for parallel computing in Julia?")\npprint(msg) # prettify the answerNoEmbedder <: AbstractEmbedderNo-op embedder for get_embeddings functions. It returns nothing.
NoPostprocessor <: AbstractPostprocessorDefault method for postprocess! method. A passthrough option that returns the result without any changes.
Overload this method to add custom postprocessing steps, eg, logging, saving conversations to disk, etc.
NoProcessor <: AbstractProcessorNo-op processor for get_keywords functions. It returns the inputs as is.
NoRefiner <: AbstractRefinerDefault method for refine! method. A passthrough option that returns the result.answer without any changes.
NoRephraser <: AbstractRephraserNo-op implementation for rephrase, which simply passes the question through.
NoReranker <: AbstractRerankerNo-op implementation for rerank, which simply passes the candidate chunks through.
NoTagFilter <: AbstractTagFilterNo-op implementation for find_tags, which simply returns all chunks.
NoTagger <: AbstractTaggerNo-op tagger for get_tags functions. It returns (nothing, nothing).
OpenTagger <: AbstractTaggerTagger for get_tags functions, which generates possible tags for each chunk via aiextract. You can customize it via prompt template (default: :RAGExtractMetadataShort), but it's quite open-ended (ie, AI decides the possible tags).
PassthroughTagger <: AbstractTaggerTagger for get_tags functions, which passes tags directly as Vector of Vectors of strings (ie, tags[i] is the tags for docs[i]).
RAGConfig <: AbstractRAGConfigDefault configuration for RAG. It uses SimpleIndexer, SimpleRetriever, and SimpleGenerator as default components. Provided as the first argument in airag.
To customize the components, replace corresponding fields for each step of the RAG pipeline (eg, use subtypes(AbstractIndexBuilder) to find the available options).
RAGResultA struct for debugging RAG answers. It contains the question, answer, context, and the candidate chunks at each step of the RAG pipeline.
Think of the flow as question -> rephrased_questions -> answer -> final_answer with the context and candidate chunks helping along the way.
Fields
question::AbstractString: the original questionrephrased_questions::Vector{<:AbstractString}: a vector of rephrased questions (eg, HyDe, Multihop, etc.)answer::AbstractString: the generated answerfinal_answer::AbstractString: the refined final answer (eg, after CorrectiveRAG), also considered the FINAL answer (it must be always available)context::Vector{<:AbstractString}: the context used for retrieval (ie, the vector of chunks and their surrounding window if applicable)sources::Vector{<:AbstractString}: the sources of the context (for the original matched chunks)emb_candidates::CandidateChunks: the candidate chunks from the embedding index (fromfind_closest)tag_candidates::Union{Nothing, CandidateChunks}: the candidate chunks from the tag index (fromfind_tags)filtered_candidates::CandidateChunks: the filtered candidate chunks (intersection ofemb_candidatesandtag_candidates)reranked_candidates::CandidateChunks: the reranked candidate chunks (fromrerank)conversations::Dict{Symbol,Vector{<:AbstractMessage}}: the conversation history for AI steps of the RAG pipeline, use keys that correspond to the function names, eg,:answeror:refine
See also: pprint (pretty printing), annotate_support (for annotating the answer)
RankGPTReranker <: AbstractRerankerRerank strategy using the RankGPT algorithm (calling LLMs). A method for rerank.
Reference
[1] Is ChatGPT Good at Search? Investigating Large Language Models as Re-Ranking Agents by W. Sun et al. [2] RankGPT Github
RankGPTResultResults from the RankGPT algorithm.
Fields
question::String: The question that was asked.chunks::AbstractVector{T}: The chunks that were ranked (=context).positions::Vector{Int}: The ranking of the chunks (referring to thechunks).elapsed::Float64: The time it took to rank the chunks.cost::Float64: The cumulative cost of the ranking.tokens::Int: The cumulative number of tokens used in the ranking.
SimpleAnswerer <: AbstractAnswererDefault method for answer! method. Generates an answer using the aigenerate function with the provided context and question.
SimpleBM25Retriever <: AbstractRetrieverKeyword-based implementation for retrieve. It does a simple similarity search via BM25Similarity and returns the results.
Make sure to use consistent processor and tagger with the Preparation Stage (build_index)!
Fields
rephraser::AbstractRephraser: the rephrasing method, dispatchingrephrase- usesNoRephraserembedder::AbstractEmbedder: the embedding method, dispatchingget_embeddings(see Preparation Stage for more details) - usesNoEmbedderprocessor::AbstractProcessor: the processor method, dispatchingget_keywords(see Preparation Stage for more details) - usesKeywordsProcessorfinder::AbstractSimilarityFinder: the similarity search method, dispatchingfind_closest- usesCosineSimilaritytagger::AbstractTagger: the tag generating method, dispatchingget_tags(see Preparation Stage for more details) - usesNoTaggerfilter::AbstractTagFilter: the tag matching method, dispatchingfind_tags- usesNoTagFilterreranker::AbstractReranker: the reranking method, dispatchingrerank- usesNoReranker
SimpleGenerator <: AbstractGeneratorDefault implementation for generate. It simply enumerates context snippets and runs aigenerate (no refinement).
It uses ContextEnumerator, SimpleAnswerer, NoRefiner, and NoPostprocessor as default contexter, answerer, refiner, and postprocessor.
SimpleIndexer <: AbstractIndexBuilderDefault implementation for build_index.
It uses TextChunker, BatchEmbedder, and NoTagger as default chunker, embedder, and tagger.
SimpleRefiner <: AbstractRefinerRefines the answer using the same context previously provided via the provided prompt template. A method for refine!.
SimpleRephraser <: AbstractRephraserRephraser implemented using the provided AI Template (eg, ...) and standard chat model. A method for rephrase.
SimpleRetriever <: AbstractRetrieverDefault implementation for retrieve function. It does a simple similarity search via CosineSimilarity and returns the results.
Make sure to use consistent embedder and tagger with the Preparation Stage (build_index)!
Fields
rephraser::AbstractRephraser: the rephrasing method, dispatchingrephrase- usesNoRephraserembedder::AbstractEmbedder: the embedding method, dispatchingget_embeddings(see Preparation Stage for more details) - usesBatchEmbedderprocessor::AbstractProcessor: the processor method, dispatchingget_keywords(see Preparation Stage for more details) - usesNoProcessorfinder::AbstractSimilarityFinder: the similarity search method, dispatchingfind_closest- usesCosineSimilaritytagger::AbstractTagger: the tag generating method, dispatchingget_tags(see Preparation Stage for more details) - usesNoTaggerfilter::AbstractTagFilter: the tag matching method, dispatchingfind_tags- usesNoTagFilterreranker::AbstractReranker: the reranking method, dispatchingrerank- usesNoReranker
StylerDefines styling keywords for printstyled for each AbstractAnnotatedNode
SubChunkIndexA view of the parent index with respect to the chunks (and chunk-aligned fields). All methods and accessors working for AbstractChunkIndex also work for SubChunkIndex. It does not yet work for MultiIndex.
Fields
parent::AbstractChunkIndex: the parent index from which the chunks are drawn (always the original index, never a view)positions::Vector{Int}: the positions of the chunks in the parent index (always refers to original PARENT index, even if we create a view of the view)
Example
cc = CandidateChunks(index.id, 1:10)\nsub_index = @view(index[cc])You can use SubChunkIndex to access chunks or sources (and other fields) from a parent index, eg,
RT.chunks(sub_index)\nRT.sources(sub_index)\nRT.chunkdata(sub_index) # slice of embeddings\nRT.embeddings(sub_index) # slice of embeddings\nRT.tags(sub_index) # slice of tags\nRT.tags_vocab(sub_index) # unchanged, identical to parent version\nRT.extras(sub_index) # slice of extrasAccess the parent index that the positions correspond to
parent(sub_index)\nRT.positions(sub_index)A partial view of a DocumentTermMatrix, tf is MATERIALIZED for performance and fewer allocations.
TavilySearchRefiner <: AbstractRefinerRefines the answer by executing a web search using the Tavily API. This method aims to enhance the answer's accuracy and relevance by incorporating information retrieved from the web. A method for refine!.
TextChunker <: AbstractChunkerChunker when you provide text to get_chunks functions. Inputs are directly chunked
TrigramAnnotaterAnnotation method where we score answer versus each context based on word-level trigrams that match.
It's very simple method (and it can loose some semantic meaning in longer sequences like negative), but it works reasonably well for both text and code.
Shortcut to LinearAlgebra.normalize. Provided in the package extension RAGToolsExperimentalExt (Requires SparseArrays, Unicode, and LinearAlgebra)
add_node_metadata!(annotater::TrigramAnnotater,\n root::AnnotatedNode; add_sources::Bool = true, add_scores::Bool = true,\n sources::Union{Nothing, AbstractVector{<:AbstractString}} = nothing)Adds metadata to the children of root. Metadata includes sources and scores, if requested.
Optionally, it can add a list of sources at the end of the printed text.
The metadata is added by inserting new nodes in the root children list (with no children of its own to be printed out).
airag(cfg::AbstractRAGConfig, index::AbstractDocumentIndex;\n question::AbstractString,\n verbose::Integer = 1, return_all::Bool = false,\n api_kwargs::NamedTuple = NamedTuple(),\n retriever::AbstractRetriever = cfg.retriever,\n retriever_kwargs::NamedTuple = NamedTuple(),\n generator::AbstractGenerator = cfg.generator,\n generator_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))High-level wrapper for Retrieval-Augmented Generation (RAG), it combines together the retrieve and generate! steps which you can customize if needed.
The simplest version first finds the relevant chunks in index for the question and then sends these chunks to the AI model to help with generating a response to the question.
To customize the components, replace the types (retriever, generator) of the corresponding step of the RAG pipeline - or go into sub-routines within the steps. Eg, use subtypes(AbstractRetriever) to find the available options.
Arguments
cfg::AbstractRAGConfig: The configuration for the RAG pipeline. Defaults toRAGConfig(), where you can swap sub-types to customize the pipeline.index::AbstractDocumentIndex: The chunk index to search for relevant text.question::AbstractString: The question to be answered.return_all::Bool: Iftrue, returns the details used for RAG along with the response.verbose::Integer: If>0, enables verbose logging. The higher the number, the more nested functions will log.api_kwargs: API parameters that will be forwarded to ALL of the API calls (aiembed,aigenerate, andaiextract).retriever::AbstractRetriever: The retriever to use for finding relevant chunks. Defaults tocfg.retriever, eg,SimpleRetriever(with no question rephrasing).retriever_kwargs::NamedTuple: API parameters that will be forwarded to theretrievercall. Examples of important ones:top_k::Int: Number of top candidates to retrieve based on embedding similarity.top_n::Int: Number of candidates to return after reranking.tagger::AbstractTagger: Tagger to use for tagging the chunks. Defaults toNoTagger().tagger_kwargs::NamedTuple: API parameters that will be forwarded to thetaggercall. You could provide the explicit tags directly withPassthroughTaggerandtagger_kwargs = (; tags = ["tag1", "tag2"]).
generator::AbstractGenerator: The generator to use for generating the answer. Defaults tocfg.generator, eg,SimpleGenerator.generator_kwargs::NamedTuple: API parameters that will be forwarded to thegeneratorcall. Examples of important ones:answerer_kwargs::NamedTuple: API parameters that will be forwarded to theanswerercall. Examples:model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.
refiner::AbstractRefiner: The method to use for refining the answer. Defaults togenerator.refiner, eg,NoRefiner.refiner_kwargs::NamedTuple: API parameters that will be forwarded to therefinercall.model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.
cost_tracker: An atomic counter to track the total cost of the operations (if you want to track the cost of multiple pipeline runs - it passed around in the pipeline).
Returns
If
return_allisfalse, returns the generated message (msg).If
return_allistrue, returns the detail of the full pipeline inRAGResult(see the docs).
See also build_index, retrieve, generate!, RAGResult, getpropertynested, setpropertynested, merge_kwargs_nested, ChunkKeywordsIndex.
Examples
Using airag to get a response for a question:
index = build_index(...) # create an index\nquestion = "How to make a barplot in Makie.jl?"\nmsg = airag(index; question)To understand the details of the RAG process, use return_all=true
msg, details = airag(index; question, return_all = true)\n# details is a RAGDetails object with all the internal steps of the `airag` functionYou can also pretty-print details to highlight generated text vs text that is supported by context. It also includes annotations of which context was used for each part of the response (where available).
PT.pprint(details)Example with advanced retrieval (with question rephrasing and reranking (requires COHERE_API_KEY). We will obtain top 100 chunks from embeddings (top_k) and top 5 chunks from reranking (top_n). In addition, it will be done with a "custom" locally-hosted model.
cfg = RAGConfig(; retriever = AdvancedRetriever())\n\n# kwargs will be big and nested, let's prepare them upfront\n# we specify "custom" model for each component that calls LLM\nkwargs = (\n retriever_kwargs = (;\n top_k = 100,\n top_n = 5,\n rephraser_kwargs = (;\n model = "custom"),\n embedder_kwargs = (;\n model = "custom"),\n tagger_kwargs = (;\n model = "custom")),\n generator_kwargs = (;\n answerer_kwargs = (;\n model = "custom"),\n refiner_kwargs = (;\n model = "custom")),\n api_kwargs = (;\n url = "http://localhost:8080"))\n\nresult = airag(cfg, index, question; kwargs...)If you want to use hybrid retrieval (embeddings + BM25), you can easily create an additional index based on keywords and pass them both into a MultiIndex.
You need to provide an explicit config, so the pipeline knows how to handle each index in the search similarity phase (finder).
index = # your existing index\n\n# create the multi-index with the keywords index\nindex_keywords = ChunkKeywordsIndex(index)\nmulti_index = MultiIndex([index, index_keywords])\n\n# define the similarity measures for the indices that you have (same order)\nfinder = RT.MultiFinder([RT.CosineSimilarity(), RT.BM25Similarity()])\ncfg = RAGConfig(; retriever=AdvancedRetriever(; processor=RT.KeywordsProcessor(), finder))\n\n# Run the pipeline with the new hybrid retrieval (return the `RAGResult` to see the details)\nresult = airag(cfg, multi_index; question, return_all=true)\n\n# Pretty-print the result\nPT.pprint(result)For easier manipulation of nested kwargs, see utilities getpropertynested, setpropertynested, merge_kwargs_nested.
align_node_styles!(annotater::TrigramAnnotater, nodes::AbstractVector{<:AnnotatedNode}; kwargs...)Aligns the styles of the nodes based on the surrounding nodes ("fill-in-the-middle").
If the node has no score, but the surrounding nodes have the same style, the node will inherit the style of the surrounding nodes.
annotate_support(annotater::TrigramAnnotater, answer::AbstractString,\n context::AbstractVector; min_score::Float64 = 0.5,\n skip_trigrams::Bool = true, hashed::Bool = true,\n sources::Union{Nothing, AbstractVector{<:AbstractString}} = nothing,\n min_source_score::Float64 = 0.25,\n add_sources::Bool = true,\n add_scores::Bool = true, kwargs...)Annotates the answer with the overlap/what's supported in context and returns the annotated tree of nodes representing the answer
Returns a "root" node with children nodes representing the sentences/code blocks in the answer. Only the "leaf" nodes are to be printed (to avoid duplication), "leaf" nodes are those with NO children.
Default logic:
Split into sentences/code blocks, then into tokens (~words).
Then match each token (~word) exactly.
If no exact match found, count trigram-based match (include the surrounding tokens for better contextual awareness).
If the match is higher than
min_score, it's recorded in thescoreof the node.
Arguments
annotater::TrigramAnnotater: Annotater to useanswer::AbstractString: Text to annotatecontext::AbstractVector: Context to annotate against, ie, look for "support" in the texts incontextmin_score::Float64: Minimum score to consider a match. Default: 0.5, which means that half of the trigrams of each word should matchskip_trigrams::Bool: Whether to potentially skip trigram matching if exact full match is found. Default: truehashed::Bool: Whether to use hashed trigrams. It's harder to debug, but it's much faster for larger texts (hashed text are held in a Set to deduplicate). Default: truesources::Union{Nothing, AbstractVector{<:AbstractString}}: Sources to add at the end of the context. Default: nothingmin_source_score::Float64: Minimum score to consider/to display a source. Default: 0.25, which means that at least a quarter of the trigrams of each word should match to some context. The threshold is lower thanmin_score, because it's average across ALL words in a block, so it's much harder to match fully with generated text.add_sources::Bool: Whether to add sources at the end of each code block/sentence. Sources are addded in the square brackets like "[1]". Default: trueadd_scores::Bool: Whether to add source-matching scores at the end of each code block/sentence. Scores are added in the square brackets like "[0.75]". Default: truekwargs: Additional keyword arguments to pass to
trigram_support!andset_node_style!. See their documentation for more details (eg, customize the colors of the nodes based on the score)
Example
annotater = TrigramAnnotater()\ncontext = [\n "This is a test context.", "Another context sentence.", "Final piece of context."]\nanswer = "This is a test context. Another context sentence."\n\nannotated_root = annotate_support(annotater, answer, context)\npprint(annotated_root) # pretty print the annotated treeannotate_support(\n annotater::TrigramAnnotater, result::AbstractRAGResult; min_score::Float64 = 0.5,\n skip_trigrams::Bool = true, hashed::Bool = true,\n min_source_score::Float64 = 0.25,\n add_sources::Bool = true,\n add_scores::Bool = true, kwargs...)Dispatch for annotate_support for AbstractRAGResult type. It extracts the final_answer and context from the result and calls annotate_support with them.
See annotate_support for more details.
Example
res = RAGResult(; question = "", final_answer = "This is a test.",\n context = ["Test context.", "Completely different"])\nannotated_root = annotate_support(annotater, res)\nPT.pprint(annotated_root)answer!(\n answerer::SimpleAnswerer, index::AbstractDocumentIndex, result::AbstractRAGResult;\n model::AbstractString = PT.MODEL_CHAT, verbose::Bool = true,\n template::Symbol = :RAGAnswerFromContext,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Generates an answer using the aigenerate function with the provided result.context and result.question.
Returns
- Mutated
resultwithresult.answerand the full conversation saved inresult.conversations[:answer]
Arguments
answerer::SimpleAnswerer: The method to use for generating the answer. Usesaigenerate.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.model::AbstractString: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.verbose::Bool: Iftrue, enables verbose logging.template::Symbol: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.cost_tracker: An atomic counter to track the cost of the operation.
build_context(contexter::ContextEnumerator,\n index::AbstractDocumentIndex, candidates::AbstractCandidateChunks;\n verbose::Bool = true,\n chunks_window_margin::Tuple{Int, Int} = (1, 1), kwargs...)\n\n build_context!(contexter::ContextEnumerator,\n index::AbstractDocumentIndex, result::AbstractRAGResult; kwargs...)Build context strings for each position in candidates considering a window margin around each position. If mutating version is used (build_context!), it will use result.reranked_candidates to update the result.context field.
Arguments
contexter::ContextEnumerator: The method to use for building the context. Enumerates the snippets.index::AbstractDocumentIndex: The index containing chunks and sources.candidates::AbstractCandidateChunks: Candidate chunks which contain positions to extract context from.verbose::Bool: Iftrue, enables verbose logging.chunks_window_margin::Tuple{Int, Int}: A tuple indicating the margin (before, after) around each position to include in the context. Defaults to(1,1), which means 1 preceding and 1 suceeding chunk will be included. With(0,0), only the matching chunks will be included.
Returns
Vector{String}: A vector of context strings, each corresponding to a position inreranked_candidates.
Examples
index = ChunkIndex(...) # Assuming a proper index is defined\ncandidates = CandidateChunks(index.id, [2, 4], [0.1, 0.2])\ncontext = build_context(ContextEnumerator(), index, candidates; chunks_window_margin=(0, 1)) # include only one following chunk for each matching chunkbuild_index(\n indexer::KeywordsIndexer, files_or_docs::Vector{<:AbstractString};\n verbose::Integer = 1,\n extras::Union{Nothing, AbstractVector} = nothing,\n index_id = gensym("ChunkKeywordsIndex"),\n chunker::AbstractChunker = indexer.chunker,\n chunker_kwargs::NamedTuple = NamedTuple(),\n processor::AbstractProcessor = indexer.processor,\n processor_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = indexer.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n api_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))Builds a ChunkKeywordsIndex from the provided files or documents to support keyword-based search (BM25).
build_index(\n indexer::AbstractIndexBuilder, files_or_docs::Vector{<:AbstractString};\n verbose::Integer = 1,\n extras::Union{Nothing, AbstractVector} = nothing,\n index_id = gensym("ChunkEmbeddingsIndex"),\n chunker::AbstractChunker = indexer.chunker,\n chunker_kwargs::NamedTuple = NamedTuple(),\n embedder::AbstractEmbedder = indexer.embedder,\n embedder_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = indexer.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n api_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))Build an INDEX for RAG (Retriever-Augmented Generation) applications from the provided file paths. INDEX is a object storing the document chunks and their embeddings (and potentially other information).
The function processes each file or document (depending on chunker), splits its content into chunks, embeds these chunks, optionally extracts metadata, and then combines this information into a retrievable index.
Define your own methods via indexer and its subcomponents (chunker, embedder, tagger).
Arguments
indexer::AbstractIndexBuilder: The indexing logic to use. Default isSimpleIndexer().files_or_docs: A vector of valid file paths OR string documents to be indexed (chunked and embedded). Specify which mode to use viachunker.verbose: An Integer specifying the verbosity of the logs. Default is1(high-level logging).0is disabled.extras: An optional vector of extra information to be stored with each chunk. Default isnothing.index_id: A unique identifier for the index. Default is a generated symbol.chunker: The chunker logic to use for splitting the documents. Default isTextChunker().chunker_kwargs: Parameters to be provided to theget_chunksfunction. Useful to change theseparatorsormax_length.sources: A vector of strings indicating the source of each chunk. Default is equal tofiles_or_docs.
embedder: The embedder logic to use for embedding the chunks. Default isBatchEmbedder().embedder_kwargs: Parameters to be provided to theget_embeddingsfunction. Useful to change thetarget_batch_size_lengthor reduce asyncmap tasksntasks.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.
tagger: The tagger logic to use for extracting tags from the chunks. Default isNoTagger(), ie, skip tag extraction. There are alsoPassthroughTaggerandOpenTagger.tagger_kwargs: Parameters to be provided to theget_tagsfunction.model: The model to use for tags extraction. Default isPT.MODEL_CHAT.template: A template to be used for tags extraction. Default is:RAGExtractMetadataShort.tags: A vector of vectors of strings directly providing the tags for each chunk. Applicable fortagger::PasstroughTagger.
api_kwargs: Parameters to be provided to the API endpoint. Shared across all API calls if provided.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.
Returns
ChunkEmbeddingsIndex: An object containing the compiled index of chunks, embeddings, tags, vocabulary, and sources.
See also: ChunkEmbeddingsIndex, get_chunks, get_embeddings, get_tags, CandidateChunks, find_closest, find_tags, rerank, retrieve, generate!, airag
Examples
# Default is loading a vector of strings and chunking them (`TextChunker()`)\nindex = build_index(SimpleIndexer(), texts; chunker_kwargs = (; max_length=10))\n\n# Another example with tags extraction, splitting only sentences and verbose output\n# Assuming `test_files` is a vector of file paths\nindexer = SimpleIndexer(chunker=FileChunker(), tagger=OpenTagger())\nindex = build_index(indexer, test_files; \n chunker_kwargs(; separators=[". "]), verbose=true)Notes
- If you get errors about exceeding embedding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try changing theembedding_kwargs. In particular, reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes (eg, Databricks).
build_qa_evals(doc_chunks::Vector{<:AbstractString}, sources::Vector{<:AbstractString};\n model=PT.MODEL_CHAT, instructions="None.", qa_template::Symbol=:RAGCreateQAFromContext, \n verbose::Bool=true, api_kwargs::NamedTuple = NamedTuple(), kwargs...) -> Vector{QAEvalItem}Create a collection of question and answer evaluations (QAEvalItem) from document chunks and sources. This function generates Q&A pairs based on the provided document chunks, using a specified AI model and template.
Arguments
doc_chunks::Vector{<:AbstractString}: A vector of document chunks, each representing a segment of text.sources::Vector{<:AbstractString}: A vector of source identifiers corresponding to each chunk indoc_chunks(eg, filenames or paths).model: The AI model used for generating Q&A pairs. Default isPT.MODEL_CHAT.instructions::String: Additional instructions or context to provide to the model generating QA sets. Defaults to "None.".qa_template::Symbol: A template symbol that dictates the AITemplate that will be used. It must have placeholdercontext. Default is:CreateQAFromContext.api_kwargs::NamedTuple: Parameters that will be forwarded to the API endpoint.verbose::Bool: Iftrue, additional information like costs will be logged. Defaults totrue.
Returns
Vector{QAEvalItem}: A vector of QAEvalItem structs, each containing a source, context, question, and answer. Invalid or empty items are filtered out.
Notes
The function internally uses
aiextractto generate Q&A pairs based on the providedqa_template. So you can use any kwargs that you want.Each
QAEvalItemincludes the context (document chunk), the generated question and answer, and the source.The function tracks and reports the cost of AI calls if
verboseis enabled.Items where the question, answer, or context is empty are considered invalid and are filtered out.
Examples
Creating Q&A evaluations from a set of document chunks:
doc_chunks = ["Text from document 1", "Text from document 2"]\nsources = ["source1", "source2"]\nqa_evals = build_qa_evals(doc_chunks, sources)Builds a matrix of tags and a vocabulary list. REQUIRES SparseArrays, LinearAlgebra, Unicode packages to be loaded!!
build_tags(tagger::AbstractTagger, chunk_tags::Nothing; kwargs...)No-op that skips any tag building, returning nothing, nothing
Otherwise, it would build the sparse matrix and the vocabulary (requires SparseArrays and LinearAlgebra packages to be loaded).
Access chunkdata for a subset of chunks, chunk_idx is a vector of chunk indices in the index
Access chunkdata for a subset of chunks, chunk_idx is a vector of chunk indices in the index
Access chunkdata for a subset of chunks, chunk_idx is a vector of chunk indices in the index
cohere_api(;\napi_key::AbstractString,\nendpoint::String,\nurl::AbstractString="https://api.cohere.ai/v1",\nhttp_kwargs::NamedTuple=NamedTuple(),\nkwargs...)Lightweight wrapper around the Cohere API. See https://cohere.com/docs for more details.
Arguments
api_key: Your Cohere API key. You can get one from https://dashboard.cohere.com/welcome/register (trial access is for free).endpoint: The Cohere endpoint to call.url: The base URL for the Cohere API. Default ishttps://api.cohere.ai/v1.http_kwargs: Any additional keyword arguments to pass toHTTP.post.kwargs: Any additional keyword arguments to pass to the Cohere API.
create_permutation_instruction(\n context::AbstractVector{<:AbstractString}; rank_start::Integer = 1,\n rank_end::Integer = 100, max_length::Integer = 512, template::Symbol = :RAGRankGPT)Creates rendered template with injected context passages.
extract_ranking(str::AbstractString)Extracts the ranking from the response into a sorted array of integers.
find_closest(\n finder::BitPackedCosineSimilarity, emb::AbstractMatrix{<:Bool},\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, rescore_multiplier::Int = 4, minimum_similarity::AbstractFloat = -1.0, kwargs...)Finds the indices of chunks (represented by embeddings in emb) that are closest to query embedding (query_emb) using bit-packed binary embeddings (in the index).
This is a two-pass approach:
First pass: Hamming distance in bit-packed binary form to get the
top_k * rescore_multiplier(i.e., more than top_k) candidates.Second pass: Rescore the candidates with float embeddings and return the top_k.
Returns only top_k closest indices.
Reference: HuggingFace: Embedding Quantization.
Examples
Convert any Float embeddings to bit-packed binary like this:
bitpacked_emb = pack_bits(emb.>0)find_closest(\n finder::BinaryCosineSimilarity, emb::AbstractMatrix{<:Bool},\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, rescore_multiplier::Int = 4, minimum_similarity::AbstractFloat = -1.0, kwargs...)Finds the indices of chunks (represented by embeddings in emb) that are closest to query embedding (query_emb) using binary embeddings (in the index).
This is a two-pass approach:
First pass: Hamming distance in binary form to get the
top_k * rescore_multiplier(ie, more than top_k) candidates.Second pass: Rescore the candidates with float embeddings and return the top_k.
Returns only top_k closest indices.
Reference: HuggingFace: Embedding Quantization.
Examples
Convert any Float embeddings to binary like this:
binary_emb = map(>(0), emb)find_closest(\n finder::CosineSimilarity, emb::AbstractMatrix{<:Real},\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, minimum_similarity::AbstractFloat = -1.0, kwargs...)Finds the indices of chunks (represented by embeddings in emb) that are closest (in cosine similarity for CosineSimilarity()) to query embedding (query_emb).
finder is the logic used for the similarity search. Default is CosineSimilarity.
If minimum_similarity is provided, only indices with similarity greater than or equal to it are returned. Similarity can be between -1 and 1 (-1 = completely opposite, 1 = exactly the same).
Returns only top_k closest indices.
find_closest(\n finder::BM25Similarity, dtm::AbstractDocumentTermMatrix,\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, minimum_similarity::AbstractFloat = -1.0, kwargs...)Finds the indices of chunks (represented by DocumentTermMatrix in dtm) that are closest to query tokens (query_tokens) using BM25.
Reference: Wikipedia: BM25. Implementation follows: The Next Generation of Lucene Relevance.
find_closest(\n finder::AbstractSimilarityFinder, index::AbstractChunkIndex,\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, kwargs...)Finds the indices of chunks (represented by embeddings in index) that are closest to query embedding (query_emb).
Returns only top_k closest indices.
find_tags(method::AnyTagFilter, index::AbstractChunkIndex,\n tag::Union{AbstractString, Regex}; kwargs...)\n\nfind_tags(method::AnyTagFilter, index::AbstractChunkIndex,\n tags::Vector{T}; kwargs...) where {T <: Union{AbstractString, Regex}}Finds the indices of chunks (represented by tags in index) that have ANY OF the specified tag or tags.
find_tags(method::AllTagFilter, index::AbstractChunkIndex,\n tag::Union{AbstractString, Regex}; kwargs...)\n\nfind_tags(method::AllTagFilter, index::AbstractChunkIndex,\n tags::Vector{T}; kwargs...) where {T <: Union{AbstractString, Regex}}Finds the indices of chunks (represented by tags in index) that have ALL OF the specified tag or tags.
find_tags(method::NoTagFilter, index::AbstractChunkIndex,\n tags::Union{T, AbstractVector{<:T}}; kwargs...) where {T <:\n Union{\n AbstractString, Regex, Nothing}}\n tags; kwargs...)Returns all chunks in the index, ie, no filtering, so we simply return nothing (easier for dispatch).
generate!(\n generator::AbstractGenerator, index::AbstractDocumentIndex, result::AbstractRAGResult;\n verbose::Integer = 1,\n api_kwargs::NamedTuple = NamedTuple(),\n contexter::AbstractContextBuilder = generator.contexter,\n contexter_kwargs::NamedTuple = NamedTuple(),\n answerer::AbstractAnswerer = generator.answerer,\n answerer_kwargs::NamedTuple = NamedTuple(),\n refiner::AbstractRefiner = generator.refiner,\n refiner_kwargs::NamedTuple = NamedTuple(),\n postprocessor::AbstractPostprocessor = generator.postprocessor,\n postprocessor_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Generate the response using the provided generator and the index and result. It is the second step in the RAG pipeline (after retrieve)
Returns the mutated result with the result.final_answer and the full conversation saved in result.conversations[:final_answer].
Notes
The default flow is
build_context!->answer!->refine!->postprocess!.contexteris the method to use for building the context, eg, simply enumerate the context chunks withContextEnumerator.answereris the standard answer generation step with LLMs.refinerstep allows the LLM to critique itself and refine its own answer.postprocessorstep allows for additional processing of the answer, eg, logging, saving conversations, etc.All of its sub-routines operate by mutating the
resultobject (and adding their part).Discover available sub-types for each step with
subtypes(AbstractRefiner)and similar for other abstract types.
Arguments
generator::AbstractGenerator: Thegeneratorto use for generating the answer. Can beSimpleGeneratororAdvancedGenerator.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.verbose::Integer: If >0, enables verbose logging.api_kwargs::NamedTuple: API parameters that will be forwarded to ALL of the API calls (aiembed,aigenerate, andaiextract).contexter::AbstractContextBuilder: The method to use for building the context. Defaults togenerator.contexter, eg,ContextEnumerator.contexter_kwargs::NamedTuple: API parameters that will be forwarded to thecontextercall.answerer::AbstractAnswerer: The method to use for generating the answer. Defaults togenerator.answerer, eg,SimpleAnswerer.answerer_kwargs::NamedTuple: API parameters that will be forwarded to theanswerercall. Examples:model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.
refiner::AbstractRefiner: The method to use for refining the answer. Defaults togenerator.refiner, eg,NoRefiner.refiner_kwargs::NamedTuple: API parameters that will be forwarded to therefinercall.model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.
postprocessor::AbstractPostprocessor: The method to use for postprocessing the answer. Defaults togenerator.postprocessor, eg,NoPostprocessor.postprocessor_kwargs::NamedTuple: API parameters that will be forwarded to thepostprocessorcall.cost_tracker: An atomic counter to track the total cost of the operations.
See also: retrieve, build_context!, ContextEnumerator, answer!, SimpleAnswerer, refine!, NoRefiner, SimpleRefiner, postprocess!, NoPostprocessor
Examples
Assume we already have `index`\n\nquestion = "What are the best practices for parallel computing in Julia?"\n\n# Retrieve the relevant chunks - returns RAGResult\nresult = retrieve(index, question)\n\n# Generate the answer using the default generator, mutates the same result\nresult = generate!(index, result)get_chunks(chunker::AbstractChunker,\n files_or_docs::Vector{<:AbstractString};\n sources::AbstractVector{<:AbstractString} = files_or_docs,\n verbose::Bool = true,\n separators = ["\\n\\n", ". ", "\\n", " "], max_length::Int = 256)Chunks the provided files_or_docs into chunks of maximum length max_length (if possible with provided separators).
Supports two modes of operation:
chunker = FileChunker(): The function opens each file infiles_or_docsand reads its contents.chunker = TextChunker(): The function assumes thatfiles_or_docsis a vector of strings to be chunked, you MUST provide correspondingsources.
Arguments
files_or_docs: A vector of valid file paths OR string documents to be chunked.separators: A list of strings used as separators for splitting the text in each file into chunks. Default is[\\n\\n", ". ", "\\n", " "]. Seerecursive_splitterfor more details.max_length: The maximum length of each chunk (if possible with provided separators). Default is 256.sources: A vector of strings indicating the source of each chunk. Default is equal tofiles_or_docs(forreader=:files)
get_embeddings(embedder::BatchEmbedder, docs::AbstractVector{<:AbstractString};\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_EMBEDDING,\n truncate_dimension::Union{Int, Nothing} = nothing,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n target_batch_size_length::Int = 80_000,\n ntasks::Int = 4 * Threads.nthreads(),\n kwargs...)Embeds a vector of docs using the provided model (kwarg model) in a batched manner - BatchEmbedder.
BatchEmbedder tries to batch embedding calls for roughly 80K characters per call (to avoid exceeding the API rate limit) to reduce network latency.
Notes
docsare assumed to be already chunked to the reasonable sizes that fit within the embedding context limit.If you get errors about exceeding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes.
Arguments
docs: A vector of strings to be embedded.verbose: A boolean flag for verbose output. Default istrue.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.truncate_dimension: The dimensionality of the embeddings to truncate to. Default isnothing,0will also do nothing.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.target_batch_size_length: The target length (in characters) of each batch of document chunks sent for embedding. Default is 80_000 characters. Speeds up embedding process.ntasks: The number of tasks to use for asyncmap. Default is 4 * Threads.nthreads().
get_embeddings(embedder::BinaryBatchEmbedder, docs::AbstractVector{<:AbstractString};\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_EMBEDDING,\n truncate_dimension::Union{Int, Nothing} = nothing,\n return_type::Type = Matrix{Bool},\n cost_tracker = Threads.Atomic{Float64}(0.0),\n target_batch_size_length::Int = 80_000,\n ntasks::Int = 4 * Threads.nthreads(),\n kwargs...)Embeds a vector of docs using the provided model (kwarg model) in a batched manner and then returns the binary embeddings matrix - BinaryBatchEmbedder.
BinaryBatchEmbedder tries to batch embedding calls for roughly 80K characters per call (to avoid exceeding the API rate limit) to reduce network latency.
Notes
docsare assumed to be already chunked to the reasonable sizes that fit within the embedding context limit.If you get errors about exceeding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes.
Arguments
docs: A vector of strings to be embedded.verbose: A boolean flag for verbose output. Default istrue.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.truncate_dimension: The dimensionality of the embeddings to truncate to. Default isnothing.return_type: The type of the returned embeddings matrix. Default isMatrix{Bool}. ChooseBitMatrixto minimize storage requirements,Matrix{Bool}to maximize performance in elementwise-ops.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.target_batch_size_length: The target length (in characters) of each batch of document chunks sent for embedding. Default is 80_000 characters. Speeds up embedding process.ntasks: The number of tasks to use for asyncmap. Default is 4 * Threads.nthreads().
get_embeddings(embedder::BitPackedBatchEmbedder, docs::AbstractVector{<:AbstractString};\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_EMBEDDING,\n truncate_dimension::Union{Int, Nothing} = nothing,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n target_batch_size_length::Int = 80_000,\n ntasks::Int = 4 * Threads.nthreads(),\n kwargs...)Embeds a vector of docs using the provided model (kwarg model) in a batched manner and then returns the binary embeddings matrix represented in UInt64 (bit-packed) - BitPackedBatchEmbedder.
BitPackedBatchEmbedder tries to batch embedding calls for roughly 80K characters per call (to avoid exceeding the API rate limit) to reduce network latency.
The best option for FAST and MEMORY-EFFICIENT storage of embeddings, for retrieval use BitPackedCosineSimilarity.
Notes
docsare assumed to be already chunked to the reasonable sizes that fit within the embedding context limit.If you get errors about exceeding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes.
Arguments
docs: A vector of strings to be embedded.verbose: A boolean flag for verbose output. Default istrue.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.truncate_dimension: The dimensionality of the embeddings to truncate to. Default isnothing.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.target_batch_size_length: The target length (in characters) of each batch of document chunks sent for embedding. Default is 80_000 characters. Speeds up embedding process.ntasks: The number of tasks to use for asyncmap. Default is 4 * Threads.nthreads().
See also: unpack_bits, pack_bits, BitPackedCosineSimilarity.
get_tags(tagger::NoTagger, docs::AbstractVector{<:AbstractString};\n kwargs...)Simple no-op that skips any tagging of the documents
get_tags(tagger::OpenTagger, docs::AbstractVector{<:AbstractString};\n verbose::Bool = true,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Extracts "tags" (metadata/keywords) from a vector of docs using the provided model (kwarg model).
Arguments
docs: A vector of strings to be embedded.verbose: A boolean flag for verbose output. Default istrue.model: The model to use for tags extraction. Default isPT.MODEL_CHAT.template: A template to be used for tags extraction. Default is:RAGExtractMetadataShort.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.
get_tags(tagger::PassthroughTagger, docs::AbstractVector{<:AbstractString};\n tags::AbstractVector{<:AbstractVector{<:AbstractString}},\n kwargs...)Pass tags directly as Vector of Vectors of strings (ie, tags[i] is the tags for docs[i]). It then builds the vocabulary from the tags and returns both the tags in matrix form and the vocabulary.
getpropertynested(\n nt::NamedTuple, parent_keys::Vector{Symbol}, key::Symbol, default = nothing)Get a property key from a nested NamedTuple nt, where the property is nested to a key in parent_keys.
Useful for nested kwargs where we want to get some property in parent_keys subset (eg, model in retriever_kwargs).
Examples
kw = (; abc = (; def = "x"))\ngetpropertynested(kw, [:abc], :def)\n# Output: "x"hamming_distance(\n mat::AbstractMatrix{T}, query::AbstractVector{T})::Vector{Int} where {T <: Integer}Calculates the column-wise Hamming distance between a matrix of binary vectors mat and a single binary vector vect.
This is the first-pass ranking for BinaryCosineSimilarity method.
Implementation from domluna's tinyRAG.
hcat_truncate(matrices::AbstractVector{<:AbstractMatrix{T}},\n truncate_dimension::Union{Nothing, Int} = nothing; verbose::Bool = false) where {T <:\n Real}Horizontal concatenation of matrices, with optional truncation of the rows of each matrix to the specified dimension (reducing embedding dimensionality).
More efficient that a simple splatting, as the resulting matrix is pre-allocated in one go.
Returns: a Matrix{Float32}
Arguments
matrices::AbstractVector{<:AbstractMatrix{T}}: Vector of matrices to concatenatetruncate_dimension::Union{Nothing,Int}=nothing: Dimension to truncate to, ornothingor0to skip truncation. If truncated, the columns will be normalized.verbose::Bool=false: Whether to print verbose output.
Examples
a = rand(Float32, 1000, 10)\nb = rand(Float32, 1000, 20)\n\nc = hcat_truncate([a, b])\nsize(c) # (1000, 30)\n\nd = hcat_truncate([a, b], 500)\nsize(d) # (500, 30)load_text(chunker::AbstractChunker, input;\n kwargs...)Load text from input using the provided chunker. Called by get_chunks.
Available chunkers:
FileChunker: The function opens each file ininputand reads its contents.TextChunker: The function assumes thatinputis a vector of strings to be chunked, you MUST provide correspondingsources.
merge_kwargs_nested(nt1::NamedTuple, nt2::NamedTuple)Merges two nested NamedTuples nt1 and nt2 recursively. The nt2 values will overwrite the nt1 values when overlapping.
Example
kw = (; abc = (; def = "x"))\nkw2 = (; abc = (; def = "x", def2 = 2), new = 1)\nmerge_kwargs_nested(kw, kw2)pack_bits(arr::AbstractMatrix{<:Bool}) -> Matrix{UInt64}\npack_bits(vect::AbstractVector{<:Bool}) -> Vector{UInt64}Pack a matrix or vector of boolean values into a more compact representation using UInt64.
Arguments (Input)
arr::AbstractMatrix{<:Bool}: A matrix of boolean values where the number of rows must be divisible by 64.
Returns
- For
arr::AbstractMatrix{<:Bool}: Returns a matrix of UInt64 where each element represents 64 boolean values from the original matrix.
Examples
For vectors:
bin = rand(Bool, 128)\nbinint = pack_bits(bin)\nbinx = unpack_bits(binint)\n@assert bin == binxFor matrices:
bin = rand(Bool, 128, 10)\nbinint = pack_bits(bin)\nbinx = unpack_bits(binint)\n@assert bin == binxpermutation_step!(\n result::RankGPTResult; rank_start::Integer = 1, rank_end::Integer = 100, kwargs...)One sub-step of the RankGPT algorithm permutation ranking within the window of chunks defined by rank_start and rank_end positions.
preprocess_tokens(text::AbstractString, stemmer=nothing; stopwords::Union{Nothing,Set{String}}=nothing, min_length::Int=3)Preprocess provided text by removing numbers, punctuation, and applying stemming for BM25 search index.
Returns a list of preprocessed tokens.
Example
stemmer = Snowball.Stemmer("english")\nstopwords = Set(["a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "some", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"])\ntext = "This is a sample paragraph to test the functionality of your text preprocessor. It contains a mix of uppercase and lowercase letters, as well as punctuation marks such as commas, periods, and exclamation points! Let's see how your preprocessor handles quotes, like "this one", and also apostrophes, like in don't. Will it preserve the formatting of this paragraph, including the indentation and line breaks?"\npreprocess_tokens(text, stemmer; stopwords)print_html([io::IO,] parent_node::AbstractAnnotatedNode)\n\nprint_html([io::IO,] rag::AbstractRAGResult; add_sources::Bool = false,\n add_scores::Bool = false, default_styler = HTMLStyler(),\n low_styler = HTMLStyler(styles = "color:magenta", classes = ""),\n medium_styler = HTMLStyler(styles = "color:blue", classes = ""),\n high_styler = HTMLStyler(styles = "", classes = ""), styler_kwargs...)Pretty-prints the annotation parent_node (or RAGResult) to the io stream (or returns the string) in HTML format (assumes node is styled with styler HTMLStyler).
It wraps each "token" into a span with requested styling (HTMLStyler's properties classes and styles). It also replaces new lines with <br> for better HTML formatting.
For any non-HTML styler, it prints the content as plain text.
Returns
nothingifiois providedor the string with HTML-formatted text (if
iois not provided, we print the result out)
See also HTMLStyler, annotate_support, and set_node_style! for how the styling is applied and what the arguments mean.
Examples
Note: RT is an alias for PromptingTools.Experimental.RAGTools
Simple start directly with the RAGResult:
# set up the text/RAGResult\ncontext = [\n "This is a test context.", "Another context sentence.", "Final piece of context."]\nanswer = "This is a test answer. It has multiple sentences."\nrag = RT.RAGResult(; context, final_answer=answer, question="")\n\n# print the HTML\nprint_html(rag)Low-level control by creating our AnnotatedNode:
# prepare your HTML styling\nstyler_kwargs = (;\n default_styler=RT.HTMLStyler(),\n low_styler=RT.HTMLStyler(styles="color:magenta", classes=""),\n medium_styler=RT.HTMLStyler(styles="color:blue", classes=""),\n high_styler=RT.HTMLStyler(styles="", classes=""))\n\n# annotate the text\ncontext = [\n "This is a test context.", "Another context sentence.", "Final piece of context."]\nanswer = "This is a test answer. It has multiple sentences."\n\nparent_node = RT.annotate_support(\n RT.TrigramAnnotater(), answer, context; add_sources=false, add_scores=false, styler_kwargs...)\n\n# print the HTML\nprint_html(parent_node)\n\n# or to accumulate more nodes\nio = IOBuffer()\nprint_html(io, parent_node)rank_gpt(chunks::AbstractVector{<:AbstractString}, question::AbstractString;\n verbose::Int = 1, rank_start::Integer = 1, rank_end::Integer = 100,\n window_size::Integer = 20, step::Integer = 10,\n num_rounds::Integer = 1, model::String = "gpt4o", kwargs...)Ranks the chunks based on their relevance for question. Returns the ranking permutation of the chunks in the order they are most relevant to the question (the first is the most relevant).
Example
result = rank_gpt(chunks, question; rank_start=1, rank_end=25, window_size=8, step=4, num_rounds=3, model="gpt4o")Reference
[1] Is ChatGPT Good at Search? Investigating Large Language Models as Re-Ranking Agents by W. Sun et al. [2] RankGPT Github
rank_sliding_window!(\n result::RankGPTResult; verbose::Int = 1, rank_start = 1, rank_end = 100,\n window_size = 20, step = 10, model::String = "gpt4o", kwargs...)One single pass of the RankGPT algorithm permutation ranking across all positions between rank_start and rank_end.
receive_permutation!(\n curr_rank::AbstractVector{<:Integer}, response::AbstractString;\n rank_start::Integer = 1, rank_end::Integer = 100)Extracts and heals the permutation to contain all ranking positions.
reciprocal_rank_fusion(args...; k::Int=60)Merges multiple rankings and calculates the reciprocal rank score for each chunk (discounted by the inverse of the rank).
Example
positions1 = [1, 3, 5, 7, 9]\npositions2 = [2, 4, 6, 8, 10]\npositions3 = [2, 4, 6, 11, 12]\n\nmerged_positions, scores = reciprocal_rank_fusion(positions1, positions2, positions3)reciprocal_rank_fusion(\n positions1::AbstractVector{<:Integer}, scores1::AbstractVector{<:T},\n positions2::AbstractVector{<:Integer},\n scores2::AbstractVector{<:T}; k::Int = 60) where {T <: Real}Merges two sets of rankings and their joint scores. Calculates the reciprocal rank score for each chunk (discounted by the inverse of the rank).
Example
positions1 = [1, 3, 5, 7, 9]\nscores1 = [0.9, 0.8, 0.7, 0.6, 0.5]\npositions2 = [2, 4, 6, 8, 10]\nscores2 = [0.5, 0.6, 0.7, 0.8, 0.9]\n\nmerged, scores = reciprocal_rank_fusion(positions1, scores1, positions2, scores2; k = 60)refine!(\n refiner::NoRefiner, index::AbstractChunkIndex, result::AbstractRAGResult;\n kwargs...)Simple no-op function for refine!. It simply copies the result.answer and result.conversations[:answer] without any changes.
refine!(\n refiner::SimpleRefiner, index::AbstractDocumentIndex, result::AbstractRAGResult;\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_CHAT,\n template::Symbol = :RAGAnswerRefiner,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Give model a chance to refine the answer (using the same or different context than previously provided).
This method uses the same context as the original answer, however, it can be modified to do additional retrieval and use a different context.
Returns
- Mutated
resultwithresult.final_answerand the full conversation saved inresult.conversations[:final_answer]
Arguments
refiner::SimpleRefiner: The method to use for refining the answer. Usesaigenerate.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.model::AbstractString: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.verbose::Bool: Iftrue, enables verbose logging.template::Symbol: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.cost_tracker: An atomic counter to track the cost of the operation.
refine!(\n refiner::TavilySearchRefiner, index::AbstractDocumentIndex, result::AbstractRAGResult;\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_CHAT,\n include_answer::Bool = true,\n max_results::Integer = 5,\n include_domains::AbstractVector{<:AbstractString} = String[],\n exclude_domains::AbstractVector{<:AbstractString} = String[],\n template::Symbol = :RAGWebSearchRefiner,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Refines the answer by executing a web search using the Tavily API. This method aims to enhance the answer's accuracy and relevance by incorporating information retrieved from the web.
Note: The web results and web answer (if requested) will be added to the context and sources!
Returns
Mutated
resultwithresult.final_answerand the full conversation saved inresult.conversations[:final_answer].In addition, the web results and web answer (if requested) are appended to the
result.contextandresult.sourcesfor correct highlighting and verification.
Arguments
refiner::TavilySearchRefiner: The method to use for refining the answer. Usesaigeneratewith a web search template.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.model::AbstractString: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.include_answer::Bool: Iftrue, includes the answer from Tavily in the web search.max_results::Integer: The maximum number of results to return.include_domains::AbstractVector{<:AbstractString}: A list of domains to include in the search results. Default is an empty list.exclude_domains::AbstractVector{<:AbstractString}: A list of domains to exclude from the search results. Default is an empty list.verbose::Bool: Iftrue, enables verbose logging.template::Symbol: The template to use for theaigeneratefunction. Defaults to:RAGWebSearchRefiner.cost_tracker: An atomic counter to track the cost of the operation.
Example
refiner!(TavilySearchRefiner(), index, result)\n# See result.final_answer or pprint(result)To enable this refiner in a full RAG pipeline, simply swap the component in the config:
cfg = RT.RAGConfig()\ncfg.generator.refiner = RT.TavilySearchRefiner()\n\nresult = airag(cfg, index; question, return_all = true)\npprint(result)rephrase(rephraser::SimpleRephraser, question::AbstractString;\n verbose::Bool = true,\n model::String = PT.MODEL_CHAT, template::Symbol = :RAGQueryHyDE,\n cost_tracker = Threads.Atomic{Float64}(0.0))Rephrases the question using the provided rephraser template = RAGQueryHyDE.
Special flavor of rephrasing using HyDE (Hypothetical Document Embedding) method, which aims to find the documents most similar to a synthetic passage that would be a good answer to our question.
Returns both the original and the rephrased question.
Arguments
rephraser: Type that dictates the logic of rephrasing step.question: The question to be rephrased.model: The model to use for rephrasing. Default isPT.MODEL_CHAT.template: The rephrasing template to use. Default is:RAGQueryHyDE. Find more withaitemplates("rephrase").verbose: A boolean flag indicating whether to print verbose logging. Default istrue.
rephrase(rephraser::NoRephraser, question::AbstractString; kwargs...)No-op, simple passthrough.
rephrase(rephraser::SimpleRephraser, question::AbstractString;\n verbose::Bool = true,\n model::String = PT.MODEL_CHAT, template::Symbol = :RAGQueryOptimizer,\n cost_tracker = Threads.Atomic{Float64}(0.0), kwargs...)Rephrases the question using the provided rephraser template.
Returns both the original and the rephrased question.
Arguments
rephraser: Type that dictates the logic of rephrasing step.question: The question to be rephrased.model: The model to use for rephrasing. Default isPT.MODEL_CHAT.template: The rephrasing template to use. Default is:RAGQueryOptimizer. Find more withaitemplates("rephrase").verbose: A boolean flag indicating whether to print verbose logging. Default istrue.
rerank(\n reranker::CohereReranker, index::AbstractDocumentIndex, question::AbstractString,\n candidates::AbstractCandidateChunks;\n verbose::Bool = false,\n api_key::AbstractString = PT.COHERE_API_KEY,\n top_n::Integer = length(candidates.scores),\n model::AbstractString = "rerank-english-v3.0",\n return_documents::Bool = false,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Re-ranks a list of candidate chunks using the Cohere Rerank API. See https://cohere.com/rerank for more details.
Arguments
reranker: Using Cohere APIindex: The index that holds the underlying chunks to be re-ranked.question: The query to be used for the search.candidates: The candidate chunks to be re-ranked.top_n: The number of most relevant documents to return. Default islength(documents).model: The model to use for reranking. Default isrerank-english-v3.0.return_documents: A boolean flag indicating whether to return the reranked documents in the response. Default isfalse.verbose: A boolean flag indicating whether to print verbose logging. Default isfalse.cost_tracker: An atomic counter to track the cost of the retrieval. Not implemented /tracked (cost unclear). Provided for consistency.
rerank(\n reranker::RankGPTReranker, index::AbstractDocumentIndex, question::AbstractString,\n candidates::AbstractCandidateChunks;\n api_key::AbstractString = PT.OPENAI_API_KEY,\n model::AbstractString = PT.MODEL_CHAT,\n verbose::Bool = false,\n top_n::Integer = length(candidates.scores),\n unique_chunks::Bool = true,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Re-ranks a list of candidate chunks using the RankGPT algorithm. See https://github.com/sunnweiwei/RankGPT for more details.
It uses LLM calls to rank the candidate chunks.
Arguments
reranker: Using Cohere APIindex: The index that holds the underlying chunks to be re-ranked.question: The query to be used for the search.candidates: The candidate chunks to be re-ranked.top_n: The number of most relevant documents to return. Default islength(documents).model: The model to use for reranking. Default isrerank-english-v3.0.verbose: A boolean flag indicating whether to print verbose logging. Default is1.unique_chunks: A boolean flag indicating whether to remove duplicates from the candidate chunks prior to reranking (saves compute time). Default istrue.
Examples
index = <some index>\nquestion = "What are the best practices for parallel computing in Julia?"\n\ncfg = RAGConfig(; retriever = SimpleRetriever(; reranker = RT.RankGPTReranker()))\nmsg = airag(cfg, index; question, return_all = true)To get full verbosity of logs, set verbose = 5 (anything higher than 3).
msg = airag(cfg, index; question, return_all = true, verbose = 5)Reference
[1] Is ChatGPT Good at Search? Investigating Large Language Models as Re-Ranking Agents by W. Sun et al. [2] RankGPT Github
retrieve(retriever::AbstractRetriever,\n index::AbstractChunkIndex,\n question::AbstractString;\n verbose::Integer = 1,\n top_k::Integer = 100,\n top_n::Integer = 5,\n api_kwargs::NamedTuple = NamedTuple(),\n rephraser::AbstractRephraser = retriever.rephraser,\n rephraser_kwargs::NamedTuple = NamedTuple(),\n embedder::AbstractEmbedder = retriever.embedder,\n embedder_kwargs::NamedTuple = NamedTuple(),\n processor::AbstractProcessor = retriever.processor,\n processor_kwargs::NamedTuple = NamedTuple(),\n finder::AbstractSimilarityFinder = retriever.finder,\n finder_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = retriever.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n filter::AbstractTagFilter = retriever.filter,\n filter_kwargs::NamedTuple = NamedTuple(),\n reranker::AbstractReranker = retriever.reranker,\n reranker_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Retrieves the most relevant chunks from the index for the given question and returns them in the RAGResult object.
This is the main entry point for the retrieval stage of the RAG pipeline. It is often followed by generate! step.
Notes:
- The default flow is
build_context!->answer!->refine!->postprocess!.
The arguments correspond to the steps of the retrieval process (rephrasing, embedding, finding similar docs, tagging, filtering by tags, reranking). You can customize each step by providing a new custom type that dispatches the corresponding function, eg, create your own type struct MyReranker<:AbstractReranker end and define the custom method for it rerank(::MyReranker,...) = ....
Note: Discover available retrieval sub-types for each step with subtypes(AbstractRephraser) and similar for other abstract types.
If you're using locally-hosted models, you can pass the api_kwargs with the url field set to the model's URL and make sure to provide corresponding model kwargs to rephraser, embedder, and tagger to use the custom models (they make AI calls).
Arguments
retriever: The retrieval method to use. Default isSimpleRetrieverbut could beAdvancedRetrieverfor more advanced retrieval.index: The index that holds the chunks and sources to be retrieved from.question: The question to be used for the retrieval.verbose: If>0, it prints out verbose logging. Default is1. If you set it to2, it will print out logs for each sub-function.top_k: The TOTAL number of closest chunks to return fromfind_closest. Default is100. If there are multiple rephrased questions, the number of chunks per each item will betop_k ÷ number_of_rephrased_questions.top_n: The TOTAL number of most relevant chunks to return for the context (fromrerankstep). Default is5.api_kwargs: Additional keyword arguments to be passed to the API calls (shared by allai*calls).rephraser: Transform the question into one or more questions. Default isretriever.rephraser.rephraser_kwargs: Additional keyword arguments to be passed to the rephraser.model: The model to use for rephrasing. Default isPT.MODEL_CHAT.template: The rephrasing template to use. Default is:RAGQueryOptimizeror:RAGQueryHyDE(depending on therephraserselected).
embedder: The embedding method to use. Default isretriever.embedder.embedder_kwargs: Additional keyword arguments to be passed to the embedder.processor: The processor method to use when using Keyword-based index. Default isretriever.processor.processor_kwargs: Additional keyword arguments to be passed to the processor.finder: The similarity search method to use. Default isretriever.finder, oftenCosineSimilarity.finder_kwargs: Additional keyword arguments to be passed to the similarity finder.tagger: The tag generating method to use. Default isretriever.tagger.tagger_kwargs: Additional keyword arguments to be passed to the tagger. Noteworthy arguments:tags: Directly provide the tags to use for filtering (can be String, Regex, or Vector{String}). Useful fortagger = PassthroughTagger.
filter: The tag matching method to use. Default isretriever.filter.filter_kwargs: Additional keyword arguments to be passed to the tag filter.reranker: The reranking method to use. Default isretriever.reranker.reranker_kwargs: Additional keyword arguments to be passed to the reranker.model: The model to use for reranking. Default isrerank-english-v2.0if you usereranker = CohereReranker().
cost_tracker: An atomic counter to track the cost of the retrieval. Default isThreads.Atomic{Float64}(0.0).
See also: SimpleRetriever, AdvancedRetriever, build_index, rephrase, get_embeddings, get_keywords, find_closest, get_tags, find_tags, rerank, RAGResult.
Examples
Find the 5 most relevant chunks from the index for the given question.
# assumes you have an existing index `index`\nretriever = SimpleRetriever()\n\nresult = retrieve(retriever,\n index,\n "What is the capital of France?",\n top_n = 5)\n\n# or use the default retriever (same as above)\nresult = retrieve(retriever,\n index,\n "What is the capital of France?",\n top_n = 5)Apply more advanced retrieval with question rephrasing and reranking (requires COHERE_API_KEY). We will obtain top 100 chunks from embeddings (top_k) and top 5 chunks from reranking (top_n).
retriever = AdvancedRetriever()\n\nresult = retrieve(retriever, index, question; top_k=100, top_n=5)You can use the retriever to customize your retrieval strategy or directly change the strategy types in the retrieve kwargs!
Example of using locally-hosted model hosted on localhost:8080:
retriever = SimpleRetriever()\nresult = retrieve(retriever, index, question;\n rephraser_kwargs = (; model = "custom"),\n embedder_kwargs = (; model = "custom"),\n tagger_kwargs = (; model = "custom"), api_kwargs = (;\n url = "http://localhost:8080"))run_qa_evals(index::AbstractChunkIndex, qa_items::AbstractVector{<:QAEvalItem};\n api_kwargs::NamedTuple = NamedTuple(),\n airag_kwargs::NamedTuple = NamedTuple(),\n qa_evals_kwargs::NamedTuple = NamedTuple(),\n verbose::Bool = true, parameters_dict::Dict{Symbol, <:Any} = Dict{Symbol, Any}())Evaluates a vector of QAEvalItems and returns a vector QAEvalResult. This function assesses the relevance and accuracy of the answers generated in a QA evaluation context.
See ?run_qa_evals for more details.
Arguments
qa_items::AbstractVector{<:QAEvalItem}: The vector of QA evaluation items containing the questions and their answers.verbose::Bool: Iftrue, enables verbose logging. Defaults totrue.api_kwargs::NamedTuple: Parameters that will be forwarded to the API calls. See?aiextractfor details.airag_kwargs::NamedTuple: Parameters that will be forwarded toairagcalls. See?airagfor details.qa_evals_kwargs::NamedTuple: Parameters that will be forwarded torun_qa_evalscalls. See?run_qa_evalsfor details.parameters_dict::Dict{Symbol, Any}: Track any parameters used for later evaluations. Keys must be Symbols.
Returns
Vector{QAEvalResult}: Vector of evaluation results that includes various scores and metadata related to the QA evaluation.
Example
index = "..." # Assuming a proper index is defined\nqa_items = [QAEvalItem(question="What is the capital of France?", answer="Paris", context="France is a country in Europe."),\n QAEvalItem(question="What is the capital of Germany?", answer="Berlin", context="Germany is a country in Europe.")]\n\n# Let's run a test with `top_k=5`\nresults = run_qa_evals(index, qa_items; airag_kwargs=(;top_k=5), parameters_dict=Dict(:top_k => 5))\n\n# Filter out the "failed" calls\nresults = filter(x->!isnothing(x.answer_score), results);\n\n# See average judge score\nmean(x->x.answer_score, results)run_qa_evals(qa_item::QAEvalItem, ctx::RAGResult; verbose::Bool = true,\n parameters_dict::Dict{Symbol, <:Any}, judge_template::Symbol = :RAGJudgeAnswerFromContext,\n model_judge::AbstractString, api_kwargs::NamedTuple = NamedTuple()) -> QAEvalResultEvaluates a single QAEvalItem using RAG details (RAGResult) and returns a QAEvalResult structure. This function assesses the relevance and accuracy of the answers generated in a QA evaluation context.
Arguments
qa_item::QAEvalItem: The QA evaluation item containing the question and its answer.ctx::RAGResult: The RAG result used for generating the QA pair, including the original context and the answers. Comes fromairag(...; return_context=true)verbose::Bool: Iftrue, enables verbose logging. Defaults totrue.parameters_dict::Dict{Symbol, Any}: Track any parameters used for later evaluations. Keys must be Symbols.judge_template::Symbol: The template symbol for the AI model used to judge the answer. Defaults to:RAGJudgeAnswerFromContext.model_judge::AbstractString: The AI model used for judging the answer's quality. Defaults to standard chat model, but it is advisable to use more powerful model GPT-4.api_kwargs::NamedTuple: Parameters that will be forwarded to the API endpoint.
Returns
QAEvalResult: An evaluation result that includes various scores and metadata related to the QA evaluation.
Notes
The function computes a retrieval score and rank based on how well the context matches the QA context.
It then uses the
judge_templateandmodel_judgeto score the answer's accuracy and relevance.In case of errors during evaluation, the function logs a warning (if
verboseistrue) and theanswer_scorewill be set tonothing.
Examples
Evaluating a QA pair using a specific context and model:
qa_item = QAEvalItem(question="What is the capital of France?", answer="Paris", context="France is a country in Europe.")\nctx = RAGResult(source="Wikipedia", context="France is a country in Europe.", answer="Paris")\nparameters_dict = Dict("param1" => "value1", "param2" => "value2")\n\neval_result = run_qa_evals(qa_item, ctx, parameters_dict=parameters_dict, model_judge="MyAIJudgeModel")Returns 1.0 if context overlaps or is contained within any of the candidate_context
Returns Integer rank of the position where context overlaps or is contained within a candidate_context
score_to_unit_scale(x::AbstractVector{T}) where T<:RealShift and scale a vector of scores to the unit scale [0, 1].
Example
x = [1.0, 2.0, 3.0, 4.0, 5.0]\nscaled_x = score_to_unit_scale(x)set_node_style!(::TrigramAnnotater, node::AnnotatedNode;\n low_threshold::Float64 = 0.0, medium_threshold::Float64 = 0.5, high_threshold::Float64 = 1.0,\n default_styler::AbstractAnnotationStyler = Styler(),\n low_styler::AbstractAnnotationStyler = Styler(color = :magenta, bold = false),\n medium_styler::AbstractAnnotationStyler = Styler(color = :blue, bold = false),\n high_styler::AbstractAnnotationStyler = Styler(color = :nothing, bold = false),\n bold_multihits::Bool = false)Sets style of node based on the provided rules
setpropertynested(nt::NamedTuple, parent_keys::Vector{Symbol},\n key::Symbol,\n value)
Setter for a property key in a nested NamedTuple nt, where the property is nested to a key in parent_keys.
Useful for nested kwargs where we want to change some property in parent_keys subset (eg, model in retriever_kwargs).
Examples
kw = (; abc = (; def = "x"))\nsetpropertynested(kw, [:abc], :def, "y")\n# Output: (abc = (def = "y",),)Practical example of changing all model keys in CHAT-based steps in the pipeline:
# changes :model to "gpt4t" whenever the parent key is in the below list (chat-based steps)\nsetpropertynested(kwargs,\n [:rephraser_kwargs, :tagger_kwargs, :answerer_kwargs, :refiner_kwargs],\n :model, "gpt4t")Or changing an embedding model (across both indexer and retriever steps, because it's same step name):
kwargs = setpropertynested(\n kwargs, [:embedder_kwargs],\n :model, "text-embedding-3-large"\n )split_into_code_and_sentences(input::Union{String, SubString{String}})Splits text block into code or text and sub-splits into units.
If code block, it splits by newline but keep the group_id the same (to have the same source) If text block, splits into sentences, bullets, etc., provides different group_id (to have different source)
tags_extract(item::Tag)\ntags_extract(tags::Vector{Tag})Extracts the Tag item into a string of the form category:::value (lowercased and spaces replaced with underscores).
Example
msg = aiextract(:RAGExtractMetadataShort; return_type=MaybeTags, text="I like package DataFrames", instructions="None.")\nmetadata = tags_extract(msg.content.items)token_with_boundaries(\n prev_token::Union{Nothing, AbstractString}, curr_token::AbstractString,\n next_token::Union{Nothing, AbstractString})Joins the three tokens together. Useful to add boundary tokens (like spaces vs brackets) to the curr_token to improve the matched context (ie, separate partial matches from exact match)
tokenize(input::Union{String, SubString{String}})Tokenizes provided input by spaces, special characters or Julia symbols (eg, =>).
Unlike other tokenizers, it aims to lossless - ie, keep both the separated text and the separators.
translate_positions_to_parent(index::AbstractChunkIndex, positions::AbstractVector{<:Integer})Translate positions to the parent index. Useful to convert between positions in a view and the original index.
Used whenever a chunkdata() is used to re-align positions in case index is a view.
translate_positions_to_parent(\n index::SubChunkIndex, pos::AbstractVector{<:Integer})Translate positions to the parent index. Useful to convert between positions in a view and the original index.
Used whenever a chunkdata() or tags() are used to re-align positions to the "parent" index.
trigram_support!(parent_node::AnnotatedNode,\n context_trigrams::AbstractVector, trigram_func::F1 = trigrams, token_transform::F2 = identity;\n skip_trigrams::Bool = false, min_score::Float64 = 0.5,\n min_source_score::Float64 = 0.25,\n stop_words::AbstractVector{<:String} = STOPWORDS,\n styler_kwargs...) where {F1 <: Function, F2 <: Function}Find if the parent_node.content is supported by the provided context_trigrams.
Logic:
Split the
parent_node.contentinto tokensCreate an
AnnotatedNodefor each tokenIf
skip_trigramsis enabled, it looks for an exact match in thecontext_trigramsIf no exact match found, it counts trigram-based match (include the surrounding tokens for better contextual awareness) as a score
Then it sets the style of the node based on the score
Lastly, it aligns the styles of neighboring nodes with
score==nothing(eg, single character tokens)Then, it rolls up the scores and sources to the parent node
For diagnostics, you can use AbstractTrees.print_tree(parent_node) to see the tree structure of each token and its score.
Example
\nnode = AnnotatedNode(content = "xyz") trigram_support!(node, context_trigrams) # updates node.children! ```\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/Experimental/RAGTools/annotation.jl#L215-L244)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.Experimental.RAGTools.trigrams-Tuple{AbstractString}' href='#PromptingTools.Experimental.RAGTools.trigrams-Tuple{AbstractString}'>#</a> <b><u>PromptingTools.Experimental.RAGTools.trigrams</u></b> — <i>Method</i>.\n\n\n\n\n```julia\ntrigrams(input_string::AbstractString; add_word::AbstractString = "")Splits provided input_string into a vector of trigrams (combination of three consecutive characters found in the input_string).
If add_word is provided, it is added to the resulting array. Useful to add the full word itself to the resulting array for exact match.
trigrams_hashed(input_string::AbstractString; add_word::AbstractString = "")Splits provided input_string into a Set of hashed trigrams (combination of three consecutive characters found in the input_string).
It is more efficient for lookups in large strings (eg, >100K characters).
If add_word is provided, it is added to the resulting array to hash. Useful to add the full word itself to the resulting array for exact match.
PT.last_message(result::RAGResult)Extract the last message from the RAGResult. It looks for final_answer first, then answer fields in the conversations dictionary. Returns nothing if not found.
Extracts the last output (generated text answer) from the RAGResult.
PromptingTools.pprint(\n io::IO, node::AbstractAnnotatedNode;\n text_width::Int = displaysize(io)[2], add_newline::Bool = true)Pretty print the node to the io stream, including all its children
Supports only node.style::Styler for now.
PT.pprint(\n io::IO, r::AbstractRAGResult; add_context::Bool = false,\n text_width::Int = displaysize(io)[2], annotater_kwargs...)Pretty print the RAG result r to the given io stream.
If add_context is true, the context will be printed as well. The text_width parameter can be used to control the width of the output.
You can provide additional keyword arguments to the annotater, eg, add_sources, add_scores, min_score, etc. See annotate_support for more details.
', 284) + ])); +} +const reference_ragtools = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference_ragtools as default +}; diff --git a/previews/PR252/assets/reference_ragtools.md.9-ISgMxz.lean.js b/previews/PR252/assets/reference_ragtools.md.9-ISgMxz.lean.js new file mode 100644 index 00000000..d64e1af5 --- /dev/null +++ b/previews/PR252/assets/reference_ragtools.md.9-ISgMxz.lean.js @@ -0,0 +1,13 @@ +import { _ as _export_sfc, c as createElementBlock, a5 as createStaticVNode, o as openBlock } from "./chunks/framework.dGC8pPHm.js"; +const __pageData = JSON.parse('{"title":"Reference for RAGTools","description":"","frontmatter":{},"headers":[],"relativePath":"reference_ragtools.md","filePath":"reference_ragtools.md","lastUpdated":null}'); +const _sfc_main = { name: "reference_ragtools.md" }; +function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { + return openBlock(), createElementBlock("div", null, _cache[0] || (_cache[0] = [ + createStaticVNode('
Reference for RAGTools
PromptingTools.Experimental.RAGTools.AbstractCandidateChunksPromptingTools.Experimental.RAGTools.AbstractChunkIndexPromptingTools.Experimental.RAGTools.AbstractGeneratorPromptingTools.Experimental.RAGTools.AbstractIndexBuilderPromptingTools.Experimental.RAGTools.AbstractMultiIndexPromptingTools.Experimental.RAGTools.AbstractRetrieverPromptingTools.Experimental.RAGTools.AdvancedGeneratorPromptingTools.Experimental.RAGTools.AdvancedRetrieverPromptingTools.Experimental.RAGTools.AllTagFilterPromptingTools.Experimental.RAGTools.AnnotatedNodePromptingTools.Experimental.RAGTools.AnyTagFilterPromptingTools.Experimental.RAGTools.BM25SimilarityPromptingTools.Experimental.RAGTools.BatchEmbedderPromptingTools.Experimental.RAGTools.BinaryBatchEmbedderPromptingTools.Experimental.RAGTools.BinaryCosineSimilarityPromptingTools.Experimental.RAGTools.BitPackedBatchEmbedderPromptingTools.Experimental.RAGTools.BitPackedCosineSimilarityPromptingTools.Experimental.RAGTools.CandidateChunksPromptingTools.Experimental.RAGTools.ChunkEmbeddingsIndexPromptingTools.Experimental.RAGTools.ChunkKeywordsIndexPromptingTools.Experimental.RAGTools.ChunkKeywordsIndexPromptingTools.Experimental.RAGTools.CohereRerankerPromptingTools.Experimental.RAGTools.ContextEnumeratorPromptingTools.Experimental.RAGTools.CosineSimilarityPromptingTools.Experimental.RAGTools.DocumentTermMatrixPromptingTools.Experimental.RAGTools.FileChunkerPromptingTools.Experimental.RAGTools.FlashRankerPromptingTools.Experimental.RAGTools.HTMLStylerPromptingTools.Experimental.RAGTools.HyDERephraserPromptingTools.Experimental.RAGTools.JudgeAllScoresPromptingTools.Experimental.RAGTools.JudgeRatingPromptingTools.Experimental.RAGTools.KeywordsIndexerPromptingTools.Experimental.RAGTools.KeywordsProcessorPromptingTools.Experimental.RAGTools.MultiCandidateChunksPromptingTools.Experimental.RAGTools.MultiFinderPromptingTools.Experimental.RAGTools.MultiIndexPromptingTools.Experimental.RAGTools.NoEmbedderPromptingTools.Experimental.RAGTools.NoPostprocessorPromptingTools.Experimental.RAGTools.NoProcessorPromptingTools.Experimental.RAGTools.NoRefinerPromptingTools.Experimental.RAGTools.NoRephraserPromptingTools.Experimental.RAGTools.NoRerankerPromptingTools.Experimental.RAGTools.NoTagFilterPromptingTools.Experimental.RAGTools.NoTaggerPromptingTools.Experimental.RAGTools.OpenTaggerPromptingTools.Experimental.RAGTools.PassthroughTaggerPromptingTools.Experimental.RAGTools.RAGConfigPromptingTools.Experimental.RAGTools.RAGResultPromptingTools.Experimental.RAGTools.RankGPTRerankerPromptingTools.Experimental.RAGTools.RankGPTResultPromptingTools.Experimental.RAGTools.SimpleAnswererPromptingTools.Experimental.RAGTools.SimpleBM25RetrieverPromptingTools.Experimental.RAGTools.SimpleGeneratorPromptingTools.Experimental.RAGTools.SimpleIndexerPromptingTools.Experimental.RAGTools.SimpleRefinerPromptingTools.Experimental.RAGTools.SimpleRephraserPromptingTools.Experimental.RAGTools.SimpleRetrieverPromptingTools.Experimental.RAGTools.StylerPromptingTools.Experimental.RAGTools.SubChunkIndexPromptingTools.Experimental.RAGTools.SubDocumentTermMatrixPromptingTools.Experimental.RAGTools.TavilySearchRefinerPromptingTools.Experimental.RAGTools.TextChunkerPromptingTools.Experimental.RAGTools.TrigramAnnotaterPromptingTools.Experimental.RAGTools._normalizePromptingTools.Experimental.RAGTools.add_node_metadata!PromptingTools.Experimental.RAGTools.airagPromptingTools.Experimental.RAGTools.align_node_styles!PromptingTools.Experimental.RAGTools.annotate_supportPromptingTools.Experimental.RAGTools.annotate_supportPromptingTools.Experimental.RAGTools.answer!PromptingTools.Experimental.RAGTools.build_contextPromptingTools.Experimental.RAGTools.build_indexPromptingTools.Experimental.RAGTools.build_indexPromptingTools.Experimental.RAGTools.build_qa_evalsPromptingTools.Experimental.RAGTools.build_tagsPromptingTools.Experimental.RAGTools.build_tagsPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.chunkdataPromptingTools.Experimental.RAGTools.cohere_apiPromptingTools.Experimental.RAGTools.create_permutation_instructionPromptingTools.Experimental.RAGTools.extract_rankingPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_closestPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.find_tagsPromptingTools.Experimental.RAGTools.generate!PromptingTools.Experimental.RAGTools.get_chunksPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_embeddingsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.get_tagsPromptingTools.Experimental.RAGTools.getpropertynestedPromptingTools.Experimental.RAGTools.hamming_distancePromptingTools.Experimental.RAGTools.hcat_truncatePromptingTools.Experimental.RAGTools.load_textPromptingTools.Experimental.RAGTools.merge_kwargs_nestedPromptingTools.Experimental.RAGTools.pack_bitsPromptingTools.Experimental.RAGTools.permutation_step!PromptingTools.Experimental.RAGTools.preprocess_tokensPromptingTools.Experimental.RAGTools.print_htmlPromptingTools.Experimental.RAGTools.rank_gptPromptingTools.Experimental.RAGTools.rank_sliding_window!PromptingTools.Experimental.RAGTools.receive_permutation!PromptingTools.Experimental.RAGTools.reciprocal_rank_fusionPromptingTools.Experimental.RAGTools.reciprocal_rank_fusionPromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.refine!PromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rephrasePromptingTools.Experimental.RAGTools.rerankPromptingTools.Experimental.RAGTools.rerankPromptingTools.Experimental.RAGTools.retrievePromptingTools.Experimental.RAGTools.run_qa_evalsPromptingTools.Experimental.RAGTools.run_qa_evalsPromptingTools.Experimental.RAGTools.score_retrieval_hitPromptingTools.Experimental.RAGTools.score_retrieval_rankPromptingTools.Experimental.RAGTools.score_to_unit_scalePromptingTools.Experimental.RAGTools.set_node_style!PromptingTools.Experimental.RAGTools.setpropertynestedPromptingTools.Experimental.RAGTools.split_into_code_and_sentencesPromptingTools.Experimental.RAGTools.tags_extractPromptingTools.Experimental.RAGTools.token_with_boundariesPromptingTools.Experimental.RAGTools.tokenizePromptingTools.Experimental.RAGTools.translate_positions_to_parentPromptingTools.Experimental.RAGTools.translate_positions_to_parentPromptingTools.Experimental.RAGTools.trigram_support!PromptingTools.Experimental.RAGTools.trigramsPromptingTools.Experimental.RAGTools.trigrams_hashed
RAGToolsProvides Retrieval-Augmented Generation (RAG) functionality.
Requires: LinearAlgebra, SparseArrays, Unicode, PromptingTools for proper functionality.
This module is experimental and may change at any time. It is intended to be moved to a separate package in the future.
AbstractCandidateChunksAbstract type for storing candidate chunks, ie, references to items in a AbstractChunkIndex.
Return type from find_closest and find_tags functions.
Required Fields
index_id::Symbol: the id of the index from which the candidates are drawnpositions::Vector{Int}: the positions of the candidates in the indexscores::Vector{Float32}: the similarity scores of the candidates from the query (higher is better)
AbstractChunkIndex <: AbstractDocumentIndexMain abstract type for storing document chunks and their embeddings. It also stores tags and sources for each chunk.
Required Fields
id::Symbol: unique identifier of each index (to ensure we're using the right index withCandidateChunks)chunks::Vector{<:AbstractString}: underlying document chunks / snippetsembeddings::Union{Nothing, Matrix{<:Real}}: for semantic searchtags::Union{Nothing, AbstractMatrix{<:Bool}}: for exact search, filtering, etc. This is often a sparse matrix indicating which chunks have the giventag(seetag_vocabfor the position lookup)tags_vocab::Union{Nothing, Vector{<:AbstractString}}: vocabulary for thetagsmatrix (each column intagsis one item intags_vocaband rows are the chunks)sources::Vector{<:AbstractString}: sources of the chunksextras::Union{Nothing, AbstractVector}: additional data, eg, metadata, source code, etc.
AbstractGenerator <: AbstractGenerationMethodAbstract type for generating an answer with generate! (use to change the process / return type of generate).
Required Fields
contexter::AbstractContextBuilder: the context building method, dispatching `build_context!answerer::AbstractAnswerer: the answer generation method, dispatchinganswer!refiner::AbstractRefiner: the answer refining method, dispatchingrefine!postprocessor::AbstractPostprocessor: the postprocessing method, dispatchingpostprocess!
AbstractIndexBuilderAbstract type for building an index with build_index (use to change the process / return type of build_index).
Required Fields
chunker::AbstractChunker: the chunking method, dispatchingget_chunksembedder::AbstractEmbedder: the embedding method, dispatchingget_embeddingstagger::AbstractTagger: the tagging method, dispatchingget_tags
AbstractMultiIndex <: AbstractDocumentIndexExperimental abstract type for storing multiple document indexes. Not yet implemented.
AbstractRetriever <: AbstractRetrievalMethodAbstract type for retrieving chunks from an index with retrieve (use to change the process / return type of retrieve).
Required Fields
rephraser::AbstractRephraser: the rephrasing method, dispatchingrephrasefinder::AbstractSimilarityFinder: the similarity search method, dispatchingfind_closestfilter::AbstractTagFilter: the tag matching method, dispatchingfind_tagsreranker::AbstractReranker: the reranking method, dispatchingrerank
AdvancedGenerator <: AbstractGeneratorDefault implementation for generate!. It simply enumerates context snippets and runs aigenerate (no refinement).
It uses ContextEnumerator, SimpleAnswerer, SimpleRefiner, and NoPostprocessor as default contexter, answerer, refiner, and postprocessor.
AdvancedRetriever <: AbstractRetrieverDispatch for retrieve with advanced retrieval methods to improve result quality. Compared to SimpleRetriever, it adds rephrasing the query and reranking the results.
Fields
rephraser::AbstractRephraser: the rephrasing method, dispatchingrephrase- usesHyDERephraserembedder::AbstractEmbedder: the embedding method, dispatchingget_embeddings(see Preparation Stage for more details) - usesBatchEmbedderprocessor::AbstractProcessor: the processor method, dispatchingget_keywords(see Preparation Stage for more details) - usesNoProcessorfinder::AbstractSimilarityFinder: the similarity search method, dispatchingfind_closest- usesCosineSimilaritytagger::AbstractTagger: the tag generating method, dispatchingget_tags(see Preparation Stage for more details) - usesNoTaggerfilter::AbstractTagFilter: the tag matching method, dispatchingfind_tags- usesNoTagFilterreranker::AbstractReranker: the reranking method, dispatchingrerank- usesCohereReranker
AllTagFilter <: AbstractTagFilterFinds the chunks that have ALL OF the specified tag(s). A method for find_tags.
AnnotatedNode{T} <: AbstractAnnotatedNodeA node to add annotations to the generated answer in airag
Annotations can be: sources, scores, whether its supported or not by the context, etc.
Fields
group_id::Int: Unique identifier for the same group of nodes (eg, different lines of the same code block)parent::Union{AnnotatedNode, Nothing}: Parent node that current node was built onchildren::Vector{AnnotatedNode}: Children nodes`score::
AnyTagFilter <: AbstractTagFilterFinds the chunks that have ANY OF the specified tag(s). A method for find_tags.
BM25Similarity <: AbstractSimilarityFinderFinds the closest chunks to a query embedding by measuring the BM25 similarity between the query and the chunks' embeddings in binary form. A method for find_closest.
Reference: Wikipedia: BM25. Implementation follows: The Next Generation of Lucene Relevance.
BatchEmbedder <: AbstractEmbedderDefault embedder for get_embeddings functions. It passes individual documents to be embedded in chunks to aiembed.
BinaryBatchEmbedder <: AbstractEmbedderSame as BatchEmbedder but reduces the embeddings matrix to a binary form (eg, BitMatrix). Defines a method for get_embeddings.
Reference: HuggingFace: Embedding Quantization.
BinaryCosineSimilarity <: AbstractSimilarityFinderFinds the closest chunks to a query embedding by measuring the Hamming distance AND cosine similarity between the query and the chunks' embeddings in binary form. A method for find_closest.
It follows the two-pass approach:
First pass: Hamming distance in binary form to get the
top_k * rescore_multiplier(ie, more than top_k) candidates.Second pass: Rescore the candidates with float embeddings and return the top_k.
Reference: HuggingFace: Embedding Quantization.
BitPackedBatchEmbedder <: AbstractEmbedderSame as BatchEmbedder but reduces the embeddings matrix to a binary form packed in UInt64 (eg, BitMatrix.chunks). Defines a method for get_embeddings.
See also utilities pack_bits and unpack_bits to move between packed/non-packed binary forms.
Reference: HuggingFace: Embedding Quantization.
BitPackedCosineSimilarity <: AbstractSimilarityFinderFinds the closest chunks to a query embedding by measuring the Hamming distance AND cosine similarity between the query and the chunks' embeddings in binary form. A method for find_closest.
The difference to BinaryCosineSimilarity is that the binary values are packed into UInt64, which is more efficient.
Reference: HuggingFace: Embedding Quantization. Implementation of hamming_distance is based on TinyRAG.
CandidateChunksA struct for storing references to chunks in the given index (identified by index_id) called positions and scores holding the strength of similarity (=1 is the highest, most similar). It's the result of the retrieval stage of RAG.
Fields
index_id::Symbol: the id of the index from which the candidates are drawnpositions::Vector{Int}: the positions of the candidates in the index (ie,5refers to the 5th chunk in the index -chunks(index)[5])scores::Vector{Float32}: the similarity scores of the candidates from the query (higher is better)
ChunkEmbeddingsIndexMain struct for storing document chunks and their embeddings. It also stores tags and sources for each chunk.
Previously, this struct was called ChunkIndex.
Fields
id::Symbol: unique identifier of each index (to ensure we're using the right index withCandidateChunks)chunks::Vector{<:AbstractString}: underlying document chunks / snippetsembeddings::Union{Nothing, Matrix{<:Real}}: for semantic searchtags::Union{Nothing, AbstractMatrix{<:Bool}}: for exact search, filtering, etc. This is often a sparse matrix indicating which chunks have the giventag(seetag_vocabfor the position lookup)tags_vocab::Union{Nothing, Vector{<:AbstractString}}: vocabulary for thetagsmatrix (each column intagsis one item intags_vocaband rows are the chunks)sources::Vector{<:AbstractString}: sources of the chunksextras::Union{Nothing, AbstractVector}: additional data, eg, metadata, source code, etc.
ChunkKeywordsIndexStruct for storing chunks of text and associated keywords for BM25 similarity search.
Fields
id::Symbol: unique identifier of each index (to ensure we're using the right index withCandidateChunks)chunks::Vector{<:AbstractString}: underlying document chunks / snippetschunkdata::Union{Nothing, AbstractMatrix{<:Real}}: for similarity search, assumed to beDocumentTermMatrixtags::Union{Nothing, AbstractMatrix{<:Bool}}: for exact search, filtering, etc. This is often a sparse matrix indicating which chunks have the giventag(seetag_vocabfor the position lookup)tags_vocab::Union{Nothing, Vector{<:AbstractString}}: vocabulary for thetagsmatrix (each column intagsis one item intags_vocaband rows are the chunks)sources::Vector{<:AbstractString}: sources of the chunksextras::Union{Nothing, AbstractVector}: additional data, eg, metadata, source code, etc.
Example
We can easily create a keywords-based index from a standard embeddings-based index.
\n# Let's assume we have a standard embeddings-based index\nindex = build_index(SimpleIndexer(), texts; chunker_kwargs = (; max_length=10))\n\n# Creating an additional index for keyword-based search (BM25), is as simple as\nindex_keywords = ChunkKeywordsIndex(index)\n\n# We can immediately create a MultiIndex (a hybrid index holding both indices)\nmulti_index = MultiIndex([index, index_keywords])You can also build the index via build_index
# given some sentences and sources\nindex_keywords = build_index(KeywordsIndexer(), sentences; chunker_kwargs=(; sources))\n\n# Retrive closest chunks with\nretriever = SimpleBM25Retriever()\nresult = retrieve(retriever, index_keywords, "What are the best practices for parallel computing in Julia?")\nresult.contextIf you want to use airag, don't forget to specify the config to make sure keywords are processed (ie, tokenized) and that BM25 is used for searching candidates
cfg = RAGConfig(; retriever = SimpleBM25Retriever());\nairag(cfg, index_keywords;\n question = "What are the best practices for parallel computing in Julia?")ChunkKeywordsIndex(\n [processor::AbstractProcessor=KeywordsProcessor(),] index::ChunkEmbeddingsIndex; verbose::Int = 1,\n index_id = gensym("ChunkKeywordsIndex"), processor_kwargs...)Convenience method to quickly create a ChunkKeywordsIndex from an existing ChunkEmbeddingsIndex.
Example
\n# Let's assume we have a standard embeddings-based index\nindex = build_index(SimpleIndexer(), texts; chunker_kwargs = (; max_length=10))\n\n# Creating an additional index for keyword-based search (BM25), is as simple as\nindex_keywords = ChunkKeywordsIndex(index)\n\n# We can immediately create a MultiIndex (a hybrid index holding both indices)\nmulti_index = MultiIndex([index, index_keywords])CohereReranker <: AbstractRerankerRerank strategy using the Cohere Rerank API. Requires an API key. A method for rerank.
ContextEnumerator <: AbstractContextBuilderDefault method for build_context! method. It simply enumerates the context snippets around each position in candidates. When possibly, it will add surrounding chunks (from the same source).
CosineSimilarity <: AbstractSimilarityFinderFinds the closest chunks to a query embedding by measuring the cosine similarity between the query and the chunks' embeddings. A method for find_closest (see the docstring for more details and usage example).
DocumentTermMatrix{T<:AbstractString}A sparse matrix of term frequencies and document lengths to allow calculation of BM25 similarity scores.
FileChunker <: AbstractChunkerChunker when you provide file paths to get_chunks functions.
Ie, the inputs will be validated first (eg, file exists, etc) and then read into memory.
Set as default chunker in get_chunks functions.
FlashRanker <: AbstractRerankerRerank strategy using the package FlashRank.jl and local models. A method for rerank.
You must first import the FlashRank.jl package. To automatically download any required models, set your ENV["DATADEPS_ALWAYS_ACCEPT"] = true (see DataDeps for more details).
Example
using FlashRank\n\n# Wrap the model to be a valid Ranker recognized by RAGTools\n# It will be provided to the airag/rerank function to avoid instantiating it on every call\nreranker = FlashRank.RankerModel(:mini) |> FlashRanker\n# You can choose :tiny or :mini\n\n## Apply to the pipeline configuration, eg, \ncfg = RAGConfig(; retriever = AdvancedRetriever(; reranker))\n\n# Ask a question (assumes you have some `index`)\nquestion = "What are the best practices for parallel computing in Julia?"\nresult = airag(cfg, index; question, return_all = true)HTMLStylerDefines styling via classes (attribute class) and styles (attribute style) for HTML formatting of AbstractAnnotatedNode
HyDERephraser <: AbstractRephraserRephraser implemented using the provided AI Template (eg, ...) and standard chat model. A method for rephrase.
It uses a prompt-based rephrasing method called HyDE (Hypothetical Document Embedding), where instead of looking for an embedding of the question, we look for the documents most similar to a synthetic passage that would be a good answer to our question.
Reference: Arxiv paper.
final_rating is the average of all scoring criteria. Explain the final_rating in rationale
Provide the final_rating between 1-5. Provide the rationale for it.
KeywordsIndexer <: AbstractIndexBuilderKeyword-based index (BM25) to be returned by build_index.
It uses TextChunker, KeywordsProcessor, and NoTagger as default chunker, processor, and tagger.
KeywordsProcessor <: AbstractProcessorDefault keywords processor for get_keywords functions. It normalizes the documents, tokenizes them and builds a DocumentTermMatrix.
MultiCandidateChunksA struct for storing references to multiple sets of chunks across different indices. Each set of chunks is identified by an index_id in index_ids, with corresponding positions in the index and scores indicating the strength of similarity.
This struct is useful for scenarios where candidates are drawn from multiple indices, and there is a need to keep track of which candidates came from which index.
Fields
index_ids::Vector{Symbol}: the ids of the indices from which the candidates are drawnpositions::Vector{TP}: the positions of the candidates in their respective indicesscores::Vector{TD}: the similarity scores of the candidates from the query
MultiFinder <: AbstractSimilarityFinderComposite finder for MultiIndex where we want to set multiple finders for each index. A method for find_closest. Positions correspond to indexes(::MultiIndex).
MultiIndexComposite index that stores multiple ChunkIndex objects and their embeddings.
Fields
id::Symbol: unique identifier of each index (to ensure we're using the right index withCandidateChunks)indexes::Vector{<:AbstractChunkIndex}: the indexes to be combined
Use accesor indexes to access the individual indexes.
Examples
We can create a MultiIndex from a vector of AbstractChunkIndex objects.
index = build_index(SimpleIndexer(), texts; chunker_kwargs = (; sources))\nindex_keywords = ChunkKeywordsIndex(index) # same chunks as above but adds BM25 instead of embeddings\n\nmulti_index = MultiIndex([index, index_keywords])To use airag with different types of indices, we need to specify how to find the closest items for each index
# Cosine similarity for embeddings and BM25 for keywords, same order as indexes in MultiIndex\nfinder = RT.MultiFinder([RT.CosineSimilarity(), RT.BM25Similarity()])\n\n# Notice that we add `processor` to make sure keywords are processed (ie, tokenized) as well\ncfg = RAGConfig(; retriever = SimpleRetriever(; processor = RT.KeywordsProcessor(), finder))\n\n# Ask questions\nmsg = airag(cfg, multi_index; question = "What are the best practices for parallel computing in Julia?")\npprint(msg) # prettify the answerNoEmbedder <: AbstractEmbedderNo-op embedder for get_embeddings functions. It returns nothing.
NoPostprocessor <: AbstractPostprocessorDefault method for postprocess! method. A passthrough option that returns the result without any changes.
Overload this method to add custom postprocessing steps, eg, logging, saving conversations to disk, etc.
NoProcessor <: AbstractProcessorNo-op processor for get_keywords functions. It returns the inputs as is.
NoRefiner <: AbstractRefinerDefault method for refine! method. A passthrough option that returns the result.answer without any changes.
NoRephraser <: AbstractRephraserNo-op implementation for rephrase, which simply passes the question through.
NoReranker <: AbstractRerankerNo-op implementation for rerank, which simply passes the candidate chunks through.
NoTagFilter <: AbstractTagFilterNo-op implementation for find_tags, which simply returns all chunks.
NoTagger <: AbstractTaggerNo-op tagger for get_tags functions. It returns (nothing, nothing).
OpenTagger <: AbstractTaggerTagger for get_tags functions, which generates possible tags for each chunk via aiextract. You can customize it via prompt template (default: :RAGExtractMetadataShort), but it's quite open-ended (ie, AI decides the possible tags).
PassthroughTagger <: AbstractTaggerTagger for get_tags functions, which passes tags directly as Vector of Vectors of strings (ie, tags[i] is the tags for docs[i]).
RAGConfig <: AbstractRAGConfigDefault configuration for RAG. It uses SimpleIndexer, SimpleRetriever, and SimpleGenerator as default components. Provided as the first argument in airag.
To customize the components, replace corresponding fields for each step of the RAG pipeline (eg, use subtypes(AbstractIndexBuilder) to find the available options).
RAGResultA struct for debugging RAG answers. It contains the question, answer, context, and the candidate chunks at each step of the RAG pipeline.
Think of the flow as question -> rephrased_questions -> answer -> final_answer with the context and candidate chunks helping along the way.
Fields
question::AbstractString: the original questionrephrased_questions::Vector{<:AbstractString}: a vector of rephrased questions (eg, HyDe, Multihop, etc.)answer::AbstractString: the generated answerfinal_answer::AbstractString: the refined final answer (eg, after CorrectiveRAG), also considered the FINAL answer (it must be always available)context::Vector{<:AbstractString}: the context used for retrieval (ie, the vector of chunks and their surrounding window if applicable)sources::Vector{<:AbstractString}: the sources of the context (for the original matched chunks)emb_candidates::CandidateChunks: the candidate chunks from the embedding index (fromfind_closest)tag_candidates::Union{Nothing, CandidateChunks}: the candidate chunks from the tag index (fromfind_tags)filtered_candidates::CandidateChunks: the filtered candidate chunks (intersection ofemb_candidatesandtag_candidates)reranked_candidates::CandidateChunks: the reranked candidate chunks (fromrerank)conversations::Dict{Symbol,Vector{<:AbstractMessage}}: the conversation history for AI steps of the RAG pipeline, use keys that correspond to the function names, eg,:answeror:refine
See also: pprint (pretty printing), annotate_support (for annotating the answer)
RankGPTReranker <: AbstractRerankerRerank strategy using the RankGPT algorithm (calling LLMs). A method for rerank.
Reference
[1] Is ChatGPT Good at Search? Investigating Large Language Models as Re-Ranking Agents by W. Sun et al. [2] RankGPT Github
RankGPTResultResults from the RankGPT algorithm.
Fields
question::String: The question that was asked.chunks::AbstractVector{T}: The chunks that were ranked (=context).positions::Vector{Int}: The ranking of the chunks (referring to thechunks).elapsed::Float64: The time it took to rank the chunks.cost::Float64: The cumulative cost of the ranking.tokens::Int: The cumulative number of tokens used in the ranking.
SimpleAnswerer <: AbstractAnswererDefault method for answer! method. Generates an answer using the aigenerate function with the provided context and question.
SimpleBM25Retriever <: AbstractRetrieverKeyword-based implementation for retrieve. It does a simple similarity search via BM25Similarity and returns the results.
Make sure to use consistent processor and tagger with the Preparation Stage (build_index)!
Fields
rephraser::AbstractRephraser: the rephrasing method, dispatchingrephrase- usesNoRephraserembedder::AbstractEmbedder: the embedding method, dispatchingget_embeddings(see Preparation Stage for more details) - usesNoEmbedderprocessor::AbstractProcessor: the processor method, dispatchingget_keywords(see Preparation Stage for more details) - usesKeywordsProcessorfinder::AbstractSimilarityFinder: the similarity search method, dispatchingfind_closest- usesCosineSimilaritytagger::AbstractTagger: the tag generating method, dispatchingget_tags(see Preparation Stage for more details) - usesNoTaggerfilter::AbstractTagFilter: the tag matching method, dispatchingfind_tags- usesNoTagFilterreranker::AbstractReranker: the reranking method, dispatchingrerank- usesNoReranker
SimpleGenerator <: AbstractGeneratorDefault implementation for generate. It simply enumerates context snippets and runs aigenerate (no refinement).
It uses ContextEnumerator, SimpleAnswerer, NoRefiner, and NoPostprocessor as default contexter, answerer, refiner, and postprocessor.
SimpleIndexer <: AbstractIndexBuilderDefault implementation for build_index.
It uses TextChunker, BatchEmbedder, and NoTagger as default chunker, embedder, and tagger.
SimpleRefiner <: AbstractRefinerRefines the answer using the same context previously provided via the provided prompt template. A method for refine!.
SimpleRephraser <: AbstractRephraserRephraser implemented using the provided AI Template (eg, ...) and standard chat model. A method for rephrase.
SimpleRetriever <: AbstractRetrieverDefault implementation for retrieve function. It does a simple similarity search via CosineSimilarity and returns the results.
Make sure to use consistent embedder and tagger with the Preparation Stage (build_index)!
Fields
rephraser::AbstractRephraser: the rephrasing method, dispatchingrephrase- usesNoRephraserembedder::AbstractEmbedder: the embedding method, dispatchingget_embeddings(see Preparation Stage for more details) - usesBatchEmbedderprocessor::AbstractProcessor: the processor method, dispatchingget_keywords(see Preparation Stage for more details) - usesNoProcessorfinder::AbstractSimilarityFinder: the similarity search method, dispatchingfind_closest- usesCosineSimilaritytagger::AbstractTagger: the tag generating method, dispatchingget_tags(see Preparation Stage for more details) - usesNoTaggerfilter::AbstractTagFilter: the tag matching method, dispatchingfind_tags- usesNoTagFilterreranker::AbstractReranker: the reranking method, dispatchingrerank- usesNoReranker
StylerDefines styling keywords for printstyled for each AbstractAnnotatedNode
SubChunkIndexA view of the parent index with respect to the chunks (and chunk-aligned fields). All methods and accessors working for AbstractChunkIndex also work for SubChunkIndex. It does not yet work for MultiIndex.
Fields
parent::AbstractChunkIndex: the parent index from which the chunks are drawn (always the original index, never a view)positions::Vector{Int}: the positions of the chunks in the parent index (always refers to original PARENT index, even if we create a view of the view)
Example
cc = CandidateChunks(index.id, 1:10)\nsub_index = @view(index[cc])You can use SubChunkIndex to access chunks or sources (and other fields) from a parent index, eg,
RT.chunks(sub_index)\nRT.sources(sub_index)\nRT.chunkdata(sub_index) # slice of embeddings\nRT.embeddings(sub_index) # slice of embeddings\nRT.tags(sub_index) # slice of tags\nRT.tags_vocab(sub_index) # unchanged, identical to parent version\nRT.extras(sub_index) # slice of extrasAccess the parent index that the positions correspond to
parent(sub_index)\nRT.positions(sub_index)A partial view of a DocumentTermMatrix, tf is MATERIALIZED for performance and fewer allocations.
TavilySearchRefiner <: AbstractRefinerRefines the answer by executing a web search using the Tavily API. This method aims to enhance the answer's accuracy and relevance by incorporating information retrieved from the web. A method for refine!.
TextChunker <: AbstractChunkerChunker when you provide text to get_chunks functions. Inputs are directly chunked
TrigramAnnotaterAnnotation method where we score answer versus each context based on word-level trigrams that match.
It's very simple method (and it can loose some semantic meaning in longer sequences like negative), but it works reasonably well for both text and code.
Shortcut to LinearAlgebra.normalize. Provided in the package extension RAGToolsExperimentalExt (Requires SparseArrays, Unicode, and LinearAlgebra)
add_node_metadata!(annotater::TrigramAnnotater,\n root::AnnotatedNode; add_sources::Bool = true, add_scores::Bool = true,\n sources::Union{Nothing, AbstractVector{<:AbstractString}} = nothing)Adds metadata to the children of root. Metadata includes sources and scores, if requested.
Optionally, it can add a list of sources at the end of the printed text.
The metadata is added by inserting new nodes in the root children list (with no children of its own to be printed out).
airag(cfg::AbstractRAGConfig, index::AbstractDocumentIndex;\n question::AbstractString,\n verbose::Integer = 1, return_all::Bool = false,\n api_kwargs::NamedTuple = NamedTuple(),\n retriever::AbstractRetriever = cfg.retriever,\n retriever_kwargs::NamedTuple = NamedTuple(),\n generator::AbstractGenerator = cfg.generator,\n generator_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))High-level wrapper for Retrieval-Augmented Generation (RAG), it combines together the retrieve and generate! steps which you can customize if needed.
The simplest version first finds the relevant chunks in index for the question and then sends these chunks to the AI model to help with generating a response to the question.
To customize the components, replace the types (retriever, generator) of the corresponding step of the RAG pipeline - or go into sub-routines within the steps. Eg, use subtypes(AbstractRetriever) to find the available options.
Arguments
cfg::AbstractRAGConfig: The configuration for the RAG pipeline. Defaults toRAGConfig(), where you can swap sub-types to customize the pipeline.index::AbstractDocumentIndex: The chunk index to search for relevant text.question::AbstractString: The question to be answered.return_all::Bool: Iftrue, returns the details used for RAG along with the response.verbose::Integer: If>0, enables verbose logging. The higher the number, the more nested functions will log.api_kwargs: API parameters that will be forwarded to ALL of the API calls (aiembed,aigenerate, andaiextract).retriever::AbstractRetriever: The retriever to use for finding relevant chunks. Defaults tocfg.retriever, eg,SimpleRetriever(with no question rephrasing).retriever_kwargs::NamedTuple: API parameters that will be forwarded to theretrievercall. Examples of important ones:top_k::Int: Number of top candidates to retrieve based on embedding similarity.top_n::Int: Number of candidates to return after reranking.tagger::AbstractTagger: Tagger to use for tagging the chunks. Defaults toNoTagger().tagger_kwargs::NamedTuple: API parameters that will be forwarded to thetaggercall. You could provide the explicit tags directly withPassthroughTaggerandtagger_kwargs = (; tags = ["tag1", "tag2"]).
generator::AbstractGenerator: The generator to use for generating the answer. Defaults tocfg.generator, eg,SimpleGenerator.generator_kwargs::NamedTuple: API parameters that will be forwarded to thegeneratorcall. Examples of important ones:answerer_kwargs::NamedTuple: API parameters that will be forwarded to theanswerercall. Examples:model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.
refiner::AbstractRefiner: The method to use for refining the answer. Defaults togenerator.refiner, eg,NoRefiner.refiner_kwargs::NamedTuple: API parameters that will be forwarded to therefinercall.model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.
cost_tracker: An atomic counter to track the total cost of the operations (if you want to track the cost of multiple pipeline runs - it passed around in the pipeline).
Returns
If
return_allisfalse, returns the generated message (msg).If
return_allistrue, returns the detail of the full pipeline inRAGResult(see the docs).
See also build_index, retrieve, generate!, RAGResult, getpropertynested, setpropertynested, merge_kwargs_nested, ChunkKeywordsIndex.
Examples
Using airag to get a response for a question:
index = build_index(...) # create an index\nquestion = "How to make a barplot in Makie.jl?"\nmsg = airag(index; question)To understand the details of the RAG process, use return_all=true
msg, details = airag(index; question, return_all = true)\n# details is a RAGDetails object with all the internal steps of the `airag` functionYou can also pretty-print details to highlight generated text vs text that is supported by context. It also includes annotations of which context was used for each part of the response (where available).
PT.pprint(details)Example with advanced retrieval (with question rephrasing and reranking (requires COHERE_API_KEY). We will obtain top 100 chunks from embeddings (top_k) and top 5 chunks from reranking (top_n). In addition, it will be done with a "custom" locally-hosted model.
cfg = RAGConfig(; retriever = AdvancedRetriever())\n\n# kwargs will be big and nested, let's prepare them upfront\n# we specify "custom" model for each component that calls LLM\nkwargs = (\n retriever_kwargs = (;\n top_k = 100,\n top_n = 5,\n rephraser_kwargs = (;\n model = "custom"),\n embedder_kwargs = (;\n model = "custom"),\n tagger_kwargs = (;\n model = "custom")),\n generator_kwargs = (;\n answerer_kwargs = (;\n model = "custom"),\n refiner_kwargs = (;\n model = "custom")),\n api_kwargs = (;\n url = "http://localhost:8080"))\n\nresult = airag(cfg, index, question; kwargs...)If you want to use hybrid retrieval (embeddings + BM25), you can easily create an additional index based on keywords and pass them both into a MultiIndex.
You need to provide an explicit config, so the pipeline knows how to handle each index in the search similarity phase (finder).
index = # your existing index\n\n# create the multi-index with the keywords index\nindex_keywords = ChunkKeywordsIndex(index)\nmulti_index = MultiIndex([index, index_keywords])\n\n# define the similarity measures for the indices that you have (same order)\nfinder = RT.MultiFinder([RT.CosineSimilarity(), RT.BM25Similarity()])\ncfg = RAGConfig(; retriever=AdvancedRetriever(; processor=RT.KeywordsProcessor(), finder))\n\n# Run the pipeline with the new hybrid retrieval (return the `RAGResult` to see the details)\nresult = airag(cfg, multi_index; question, return_all=true)\n\n# Pretty-print the result\nPT.pprint(result)For easier manipulation of nested kwargs, see utilities getpropertynested, setpropertynested, merge_kwargs_nested.
align_node_styles!(annotater::TrigramAnnotater, nodes::AbstractVector{<:AnnotatedNode}; kwargs...)Aligns the styles of the nodes based on the surrounding nodes ("fill-in-the-middle").
If the node has no score, but the surrounding nodes have the same style, the node will inherit the style of the surrounding nodes.
annotate_support(annotater::TrigramAnnotater, answer::AbstractString,\n context::AbstractVector; min_score::Float64 = 0.5,\n skip_trigrams::Bool = true, hashed::Bool = true,\n sources::Union{Nothing, AbstractVector{<:AbstractString}} = nothing,\n min_source_score::Float64 = 0.25,\n add_sources::Bool = true,\n add_scores::Bool = true, kwargs...)Annotates the answer with the overlap/what's supported in context and returns the annotated tree of nodes representing the answer
Returns a "root" node with children nodes representing the sentences/code blocks in the answer. Only the "leaf" nodes are to be printed (to avoid duplication), "leaf" nodes are those with NO children.
Default logic:
Split into sentences/code blocks, then into tokens (~words).
Then match each token (~word) exactly.
If no exact match found, count trigram-based match (include the surrounding tokens for better contextual awareness).
If the match is higher than
min_score, it's recorded in thescoreof the node.
Arguments
annotater::TrigramAnnotater: Annotater to useanswer::AbstractString: Text to annotatecontext::AbstractVector: Context to annotate against, ie, look for "support" in the texts incontextmin_score::Float64: Minimum score to consider a match. Default: 0.5, which means that half of the trigrams of each word should matchskip_trigrams::Bool: Whether to potentially skip trigram matching if exact full match is found. Default: truehashed::Bool: Whether to use hashed trigrams. It's harder to debug, but it's much faster for larger texts (hashed text are held in a Set to deduplicate). Default: truesources::Union{Nothing, AbstractVector{<:AbstractString}}: Sources to add at the end of the context. Default: nothingmin_source_score::Float64: Minimum score to consider/to display a source. Default: 0.25, which means that at least a quarter of the trigrams of each word should match to some context. The threshold is lower thanmin_score, because it's average across ALL words in a block, so it's much harder to match fully with generated text.add_sources::Bool: Whether to add sources at the end of each code block/sentence. Sources are addded in the square brackets like "[1]". Default: trueadd_scores::Bool: Whether to add source-matching scores at the end of each code block/sentence. Scores are added in the square brackets like "[0.75]". Default: truekwargs: Additional keyword arguments to pass to
trigram_support!andset_node_style!. See their documentation for more details (eg, customize the colors of the nodes based on the score)
Example
annotater = TrigramAnnotater()\ncontext = [\n "This is a test context.", "Another context sentence.", "Final piece of context."]\nanswer = "This is a test context. Another context sentence."\n\nannotated_root = annotate_support(annotater, answer, context)\npprint(annotated_root) # pretty print the annotated treeannotate_support(\n annotater::TrigramAnnotater, result::AbstractRAGResult; min_score::Float64 = 0.5,\n skip_trigrams::Bool = true, hashed::Bool = true,\n min_source_score::Float64 = 0.25,\n add_sources::Bool = true,\n add_scores::Bool = true, kwargs...)Dispatch for annotate_support for AbstractRAGResult type. It extracts the final_answer and context from the result and calls annotate_support with them.
See annotate_support for more details.
Example
res = RAGResult(; question = "", final_answer = "This is a test.",\n context = ["Test context.", "Completely different"])\nannotated_root = annotate_support(annotater, res)\nPT.pprint(annotated_root)answer!(\n answerer::SimpleAnswerer, index::AbstractDocumentIndex, result::AbstractRAGResult;\n model::AbstractString = PT.MODEL_CHAT, verbose::Bool = true,\n template::Symbol = :RAGAnswerFromContext,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Generates an answer using the aigenerate function with the provided result.context and result.question.
Returns
- Mutated
resultwithresult.answerand the full conversation saved inresult.conversations[:answer]
Arguments
answerer::SimpleAnswerer: The method to use for generating the answer. Usesaigenerate.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.model::AbstractString: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.verbose::Bool: Iftrue, enables verbose logging.template::Symbol: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.cost_tracker: An atomic counter to track the cost of the operation.
build_context(contexter::ContextEnumerator,\n index::AbstractDocumentIndex, candidates::AbstractCandidateChunks;\n verbose::Bool = true,\n chunks_window_margin::Tuple{Int, Int} = (1, 1), kwargs...)\n\n build_context!(contexter::ContextEnumerator,\n index::AbstractDocumentIndex, result::AbstractRAGResult; kwargs...)Build context strings for each position in candidates considering a window margin around each position. If mutating version is used (build_context!), it will use result.reranked_candidates to update the result.context field.
Arguments
contexter::ContextEnumerator: The method to use for building the context. Enumerates the snippets.index::AbstractDocumentIndex: The index containing chunks and sources.candidates::AbstractCandidateChunks: Candidate chunks which contain positions to extract context from.verbose::Bool: Iftrue, enables verbose logging.chunks_window_margin::Tuple{Int, Int}: A tuple indicating the margin (before, after) around each position to include in the context. Defaults to(1,1), which means 1 preceding and 1 suceeding chunk will be included. With(0,0), only the matching chunks will be included.
Returns
Vector{String}: A vector of context strings, each corresponding to a position inreranked_candidates.
Examples
index = ChunkIndex(...) # Assuming a proper index is defined\ncandidates = CandidateChunks(index.id, [2, 4], [0.1, 0.2])\ncontext = build_context(ContextEnumerator(), index, candidates; chunks_window_margin=(0, 1)) # include only one following chunk for each matching chunkbuild_index(\n indexer::KeywordsIndexer, files_or_docs::Vector{<:AbstractString};\n verbose::Integer = 1,\n extras::Union{Nothing, AbstractVector} = nothing,\n index_id = gensym("ChunkKeywordsIndex"),\n chunker::AbstractChunker = indexer.chunker,\n chunker_kwargs::NamedTuple = NamedTuple(),\n processor::AbstractProcessor = indexer.processor,\n processor_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = indexer.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n api_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))Builds a ChunkKeywordsIndex from the provided files or documents to support keyword-based search (BM25).
build_index(\n indexer::AbstractIndexBuilder, files_or_docs::Vector{<:AbstractString};\n verbose::Integer = 1,\n extras::Union{Nothing, AbstractVector} = nothing,\n index_id = gensym("ChunkEmbeddingsIndex"),\n chunker::AbstractChunker = indexer.chunker,\n chunker_kwargs::NamedTuple = NamedTuple(),\n embedder::AbstractEmbedder = indexer.embedder,\n embedder_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = indexer.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n api_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0))Build an INDEX for RAG (Retriever-Augmented Generation) applications from the provided file paths. INDEX is a object storing the document chunks and their embeddings (and potentially other information).
The function processes each file or document (depending on chunker), splits its content into chunks, embeds these chunks, optionally extracts metadata, and then combines this information into a retrievable index.
Define your own methods via indexer and its subcomponents (chunker, embedder, tagger).
Arguments
indexer::AbstractIndexBuilder: The indexing logic to use. Default isSimpleIndexer().files_or_docs: A vector of valid file paths OR string documents to be indexed (chunked and embedded). Specify which mode to use viachunker.verbose: An Integer specifying the verbosity of the logs. Default is1(high-level logging).0is disabled.extras: An optional vector of extra information to be stored with each chunk. Default isnothing.index_id: A unique identifier for the index. Default is a generated symbol.chunker: The chunker logic to use for splitting the documents. Default isTextChunker().chunker_kwargs: Parameters to be provided to theget_chunksfunction. Useful to change theseparatorsormax_length.sources: A vector of strings indicating the source of each chunk. Default is equal tofiles_or_docs.
embedder: The embedder logic to use for embedding the chunks. Default isBatchEmbedder().embedder_kwargs: Parameters to be provided to theget_embeddingsfunction. Useful to change thetarget_batch_size_lengthor reduce asyncmap tasksntasks.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.
tagger: The tagger logic to use for extracting tags from the chunks. Default isNoTagger(), ie, skip tag extraction. There are alsoPassthroughTaggerandOpenTagger.tagger_kwargs: Parameters to be provided to theget_tagsfunction.model: The model to use for tags extraction. Default isPT.MODEL_CHAT.template: A template to be used for tags extraction. Default is:RAGExtractMetadataShort.tags: A vector of vectors of strings directly providing the tags for each chunk. Applicable fortagger::PasstroughTagger.
api_kwargs: Parameters to be provided to the API endpoint. Shared across all API calls if provided.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.
Returns
ChunkEmbeddingsIndex: An object containing the compiled index of chunks, embeddings, tags, vocabulary, and sources.
See also: ChunkEmbeddingsIndex, get_chunks, get_embeddings, get_tags, CandidateChunks, find_closest, find_tags, rerank, retrieve, generate!, airag
Examples
# Default is loading a vector of strings and chunking them (`TextChunker()`)\nindex = build_index(SimpleIndexer(), texts; chunker_kwargs = (; max_length=10))\n\n# Another example with tags extraction, splitting only sentences and verbose output\n# Assuming `test_files` is a vector of file paths\nindexer = SimpleIndexer(chunker=FileChunker(), tagger=OpenTagger())\nindex = build_index(indexer, test_files; \n chunker_kwargs(; separators=[". "]), verbose=true)Notes
- If you get errors about exceeding embedding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try changing theembedding_kwargs. In particular, reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes (eg, Databricks).
build_qa_evals(doc_chunks::Vector{<:AbstractString}, sources::Vector{<:AbstractString};\n model=PT.MODEL_CHAT, instructions="None.", qa_template::Symbol=:RAGCreateQAFromContext, \n verbose::Bool=true, api_kwargs::NamedTuple = NamedTuple(), kwargs...) -> Vector{QAEvalItem}Create a collection of question and answer evaluations (QAEvalItem) from document chunks and sources. This function generates Q&A pairs based on the provided document chunks, using a specified AI model and template.
Arguments
doc_chunks::Vector{<:AbstractString}: A vector of document chunks, each representing a segment of text.sources::Vector{<:AbstractString}: A vector of source identifiers corresponding to each chunk indoc_chunks(eg, filenames or paths).model: The AI model used for generating Q&A pairs. Default isPT.MODEL_CHAT.instructions::String: Additional instructions or context to provide to the model generating QA sets. Defaults to "None.".qa_template::Symbol: A template symbol that dictates the AITemplate that will be used. It must have placeholdercontext. Default is:CreateQAFromContext.api_kwargs::NamedTuple: Parameters that will be forwarded to the API endpoint.verbose::Bool: Iftrue, additional information like costs will be logged. Defaults totrue.
Returns
Vector{QAEvalItem}: A vector of QAEvalItem structs, each containing a source, context, question, and answer. Invalid or empty items are filtered out.
Notes
The function internally uses
aiextractto generate Q&A pairs based on the providedqa_template. So you can use any kwargs that you want.Each
QAEvalItemincludes the context (document chunk), the generated question and answer, and the source.The function tracks and reports the cost of AI calls if
verboseis enabled.Items where the question, answer, or context is empty are considered invalid and are filtered out.
Examples
Creating Q&A evaluations from a set of document chunks:
doc_chunks = ["Text from document 1", "Text from document 2"]\nsources = ["source1", "source2"]\nqa_evals = build_qa_evals(doc_chunks, sources)Builds a matrix of tags and a vocabulary list. REQUIRES SparseArrays, LinearAlgebra, Unicode packages to be loaded!!
build_tags(tagger::AbstractTagger, chunk_tags::Nothing; kwargs...)No-op that skips any tag building, returning nothing, nothing
Otherwise, it would build the sparse matrix and the vocabulary (requires SparseArrays and LinearAlgebra packages to be loaded).
Access chunkdata for a subset of chunks, chunk_idx is a vector of chunk indices in the index
Access chunkdata for a subset of chunks, chunk_idx is a vector of chunk indices in the index
Access chunkdata for a subset of chunks, chunk_idx is a vector of chunk indices in the index
cohere_api(;\napi_key::AbstractString,\nendpoint::String,\nurl::AbstractString="https://api.cohere.ai/v1",\nhttp_kwargs::NamedTuple=NamedTuple(),\nkwargs...)Lightweight wrapper around the Cohere API. See https://cohere.com/docs for more details.
Arguments
api_key: Your Cohere API key. You can get one from https://dashboard.cohere.com/welcome/register (trial access is for free).endpoint: The Cohere endpoint to call.url: The base URL for the Cohere API. Default ishttps://api.cohere.ai/v1.http_kwargs: Any additional keyword arguments to pass toHTTP.post.kwargs: Any additional keyword arguments to pass to the Cohere API.
create_permutation_instruction(\n context::AbstractVector{<:AbstractString}; rank_start::Integer = 1,\n rank_end::Integer = 100, max_length::Integer = 512, template::Symbol = :RAGRankGPT)Creates rendered template with injected context passages.
extract_ranking(str::AbstractString)Extracts the ranking from the response into a sorted array of integers.
find_closest(\n finder::BitPackedCosineSimilarity, emb::AbstractMatrix{<:Bool},\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, rescore_multiplier::Int = 4, minimum_similarity::AbstractFloat = -1.0, kwargs...)Finds the indices of chunks (represented by embeddings in emb) that are closest to query embedding (query_emb) using bit-packed binary embeddings (in the index).
This is a two-pass approach:
First pass: Hamming distance in bit-packed binary form to get the
top_k * rescore_multiplier(i.e., more than top_k) candidates.Second pass: Rescore the candidates with float embeddings and return the top_k.
Returns only top_k closest indices.
Reference: HuggingFace: Embedding Quantization.
Examples
Convert any Float embeddings to bit-packed binary like this:
bitpacked_emb = pack_bits(emb.>0)find_closest(\n finder::BinaryCosineSimilarity, emb::AbstractMatrix{<:Bool},\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, rescore_multiplier::Int = 4, minimum_similarity::AbstractFloat = -1.0, kwargs...)Finds the indices of chunks (represented by embeddings in emb) that are closest to query embedding (query_emb) using binary embeddings (in the index).
This is a two-pass approach:
First pass: Hamming distance in binary form to get the
top_k * rescore_multiplier(ie, more than top_k) candidates.Second pass: Rescore the candidates with float embeddings and return the top_k.
Returns only top_k closest indices.
Reference: HuggingFace: Embedding Quantization.
Examples
Convert any Float embeddings to binary like this:
binary_emb = map(>(0), emb)find_closest(\n finder::CosineSimilarity, emb::AbstractMatrix{<:Real},\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, minimum_similarity::AbstractFloat = -1.0, kwargs...)Finds the indices of chunks (represented by embeddings in emb) that are closest (in cosine similarity for CosineSimilarity()) to query embedding (query_emb).
finder is the logic used for the similarity search. Default is CosineSimilarity.
If minimum_similarity is provided, only indices with similarity greater than or equal to it are returned. Similarity can be between -1 and 1 (-1 = completely opposite, 1 = exactly the same).
Returns only top_k closest indices.
find_closest(\n finder::BM25Similarity, dtm::AbstractDocumentTermMatrix,\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, minimum_similarity::AbstractFloat = -1.0, kwargs...)Finds the indices of chunks (represented by DocumentTermMatrix in dtm) that are closest to query tokens (query_tokens) using BM25.
Reference: Wikipedia: BM25. Implementation follows: The Next Generation of Lucene Relevance.
find_closest(\n finder::AbstractSimilarityFinder, index::AbstractChunkIndex,\n query_emb::AbstractVector{<:Real}, query_tokens::AbstractVector{<:AbstractString} = String[];\n top_k::Int = 100, kwargs...)Finds the indices of chunks (represented by embeddings in index) that are closest to query embedding (query_emb).
Returns only top_k closest indices.
find_tags(method::AnyTagFilter, index::AbstractChunkIndex,\n tag::Union{AbstractString, Regex}; kwargs...)\n\nfind_tags(method::AnyTagFilter, index::AbstractChunkIndex,\n tags::Vector{T}; kwargs...) where {T <: Union{AbstractString, Regex}}Finds the indices of chunks (represented by tags in index) that have ANY OF the specified tag or tags.
find_tags(method::AllTagFilter, index::AbstractChunkIndex,\n tag::Union{AbstractString, Regex}; kwargs...)\n\nfind_tags(method::AllTagFilter, index::AbstractChunkIndex,\n tags::Vector{T}; kwargs...) where {T <: Union{AbstractString, Regex}}Finds the indices of chunks (represented by tags in index) that have ALL OF the specified tag or tags.
find_tags(method::NoTagFilter, index::AbstractChunkIndex,\n tags::Union{T, AbstractVector{<:T}}; kwargs...) where {T <:\n Union{\n AbstractString, Regex, Nothing}}\n tags; kwargs...)Returns all chunks in the index, ie, no filtering, so we simply return nothing (easier for dispatch).
generate!(\n generator::AbstractGenerator, index::AbstractDocumentIndex, result::AbstractRAGResult;\n verbose::Integer = 1,\n api_kwargs::NamedTuple = NamedTuple(),\n contexter::AbstractContextBuilder = generator.contexter,\n contexter_kwargs::NamedTuple = NamedTuple(),\n answerer::AbstractAnswerer = generator.answerer,\n answerer_kwargs::NamedTuple = NamedTuple(),\n refiner::AbstractRefiner = generator.refiner,\n refiner_kwargs::NamedTuple = NamedTuple(),\n postprocessor::AbstractPostprocessor = generator.postprocessor,\n postprocessor_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Generate the response using the provided generator and the index and result. It is the second step in the RAG pipeline (after retrieve)
Returns the mutated result with the result.final_answer and the full conversation saved in result.conversations[:final_answer].
Notes
The default flow is
build_context!->answer!->refine!->postprocess!.contexteris the method to use for building the context, eg, simply enumerate the context chunks withContextEnumerator.answereris the standard answer generation step with LLMs.refinerstep allows the LLM to critique itself and refine its own answer.postprocessorstep allows for additional processing of the answer, eg, logging, saving conversations, etc.All of its sub-routines operate by mutating the
resultobject (and adding their part).Discover available sub-types for each step with
subtypes(AbstractRefiner)and similar for other abstract types.
Arguments
generator::AbstractGenerator: Thegeneratorto use for generating the answer. Can beSimpleGeneratororAdvancedGenerator.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.verbose::Integer: If >0, enables verbose logging.api_kwargs::NamedTuple: API parameters that will be forwarded to ALL of the API calls (aiembed,aigenerate, andaiextract).contexter::AbstractContextBuilder: The method to use for building the context. Defaults togenerator.contexter, eg,ContextEnumerator.contexter_kwargs::NamedTuple: API parameters that will be forwarded to thecontextercall.answerer::AbstractAnswerer: The method to use for generating the answer. Defaults togenerator.answerer, eg,SimpleAnswerer.answerer_kwargs::NamedTuple: API parameters that will be forwarded to theanswerercall. Examples:model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerFromContext.
refiner::AbstractRefiner: The method to use for refining the answer. Defaults togenerator.refiner, eg,NoRefiner.refiner_kwargs::NamedTuple: API parameters that will be forwarded to therefinercall.model: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.template: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.
postprocessor::AbstractPostprocessor: The method to use for postprocessing the answer. Defaults togenerator.postprocessor, eg,NoPostprocessor.postprocessor_kwargs::NamedTuple: API parameters that will be forwarded to thepostprocessorcall.cost_tracker: An atomic counter to track the total cost of the operations.
See also: retrieve, build_context!, ContextEnumerator, answer!, SimpleAnswerer, refine!, NoRefiner, SimpleRefiner, postprocess!, NoPostprocessor
Examples
Assume we already have `index`\n\nquestion = "What are the best practices for parallel computing in Julia?"\n\n# Retrieve the relevant chunks - returns RAGResult\nresult = retrieve(index, question)\n\n# Generate the answer using the default generator, mutates the same result\nresult = generate!(index, result)get_chunks(chunker::AbstractChunker,\n files_or_docs::Vector{<:AbstractString};\n sources::AbstractVector{<:AbstractString} = files_or_docs,\n verbose::Bool = true,\n separators = ["\\n\\n", ". ", "\\n", " "], max_length::Int = 256)Chunks the provided files_or_docs into chunks of maximum length max_length (if possible with provided separators).
Supports two modes of operation:
chunker = FileChunker(): The function opens each file infiles_or_docsand reads its contents.chunker = TextChunker(): The function assumes thatfiles_or_docsis a vector of strings to be chunked, you MUST provide correspondingsources.
Arguments
files_or_docs: A vector of valid file paths OR string documents to be chunked.separators: A list of strings used as separators for splitting the text in each file into chunks. Default is[\\n\\n", ". ", "\\n", " "]. Seerecursive_splitterfor more details.max_length: The maximum length of each chunk (if possible with provided separators). Default is 256.sources: A vector of strings indicating the source of each chunk. Default is equal tofiles_or_docs(forreader=:files)
get_embeddings(embedder::BatchEmbedder, docs::AbstractVector{<:AbstractString};\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_EMBEDDING,\n truncate_dimension::Union{Int, Nothing} = nothing,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n target_batch_size_length::Int = 80_000,\n ntasks::Int = 4 * Threads.nthreads(),\n kwargs...)Embeds a vector of docs using the provided model (kwarg model) in a batched manner - BatchEmbedder.
BatchEmbedder tries to batch embedding calls for roughly 80K characters per call (to avoid exceeding the API rate limit) to reduce network latency.
Notes
docsare assumed to be already chunked to the reasonable sizes that fit within the embedding context limit.If you get errors about exceeding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes.
Arguments
docs: A vector of strings to be embedded.verbose: A boolean flag for verbose output. Default istrue.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.truncate_dimension: The dimensionality of the embeddings to truncate to. Default isnothing,0will also do nothing.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.target_batch_size_length: The target length (in characters) of each batch of document chunks sent for embedding. Default is 80_000 characters. Speeds up embedding process.ntasks: The number of tasks to use for asyncmap. Default is 4 * Threads.nthreads().
get_embeddings(embedder::BinaryBatchEmbedder, docs::AbstractVector{<:AbstractString};\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_EMBEDDING,\n truncate_dimension::Union{Int, Nothing} = nothing,\n return_type::Type = Matrix{Bool},\n cost_tracker = Threads.Atomic{Float64}(0.0),\n target_batch_size_length::Int = 80_000,\n ntasks::Int = 4 * Threads.nthreads(),\n kwargs...)Embeds a vector of docs using the provided model (kwarg model) in a batched manner and then returns the binary embeddings matrix - BinaryBatchEmbedder.
BinaryBatchEmbedder tries to batch embedding calls for roughly 80K characters per call (to avoid exceeding the API rate limit) to reduce network latency.
Notes
docsare assumed to be already chunked to the reasonable sizes that fit within the embedding context limit.If you get errors about exceeding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes.
Arguments
docs: A vector of strings to be embedded.verbose: A boolean flag for verbose output. Default istrue.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.truncate_dimension: The dimensionality of the embeddings to truncate to. Default isnothing.return_type: The type of the returned embeddings matrix. Default isMatrix{Bool}. ChooseBitMatrixto minimize storage requirements,Matrix{Bool}to maximize performance in elementwise-ops.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.target_batch_size_length: The target length (in characters) of each batch of document chunks sent for embedding. Default is 80_000 characters. Speeds up embedding process.ntasks: The number of tasks to use for asyncmap. Default is 4 * Threads.nthreads().
get_embeddings(embedder::BitPackedBatchEmbedder, docs::AbstractVector{<:AbstractString};\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_EMBEDDING,\n truncate_dimension::Union{Int, Nothing} = nothing,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n target_batch_size_length::Int = 80_000,\n ntasks::Int = 4 * Threads.nthreads(),\n kwargs...)Embeds a vector of docs using the provided model (kwarg model) in a batched manner and then returns the binary embeddings matrix represented in UInt64 (bit-packed) - BitPackedBatchEmbedder.
BitPackedBatchEmbedder tries to batch embedding calls for roughly 80K characters per call (to avoid exceeding the API rate limit) to reduce network latency.
The best option for FAST and MEMORY-EFFICIENT storage of embeddings, for retrieval use BitPackedCosineSimilarity.
Notes
docsare assumed to be already chunked to the reasonable sizes that fit within the embedding context limit.If you get errors about exceeding input sizes, first check the
max_lengthin your chunks. If that does NOT resolve the issue, try reducing thetarget_batch_size_lengthparameter (eg, 10_000) and number of tasksntasks=1. Some providers cannot handle large batch sizes.
Arguments
docs: A vector of strings to be embedded.verbose: A boolean flag for verbose output. Default istrue.model: The model to use for embedding. Default isPT.MODEL_EMBEDDING.truncate_dimension: The dimensionality of the embeddings to truncate to. Default isnothing.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.target_batch_size_length: The target length (in characters) of each batch of document chunks sent for embedding. Default is 80_000 characters. Speeds up embedding process.ntasks: The number of tasks to use for asyncmap. Default is 4 * Threads.nthreads().
See also: unpack_bits, pack_bits, BitPackedCosineSimilarity.
get_tags(tagger::NoTagger, docs::AbstractVector{<:AbstractString};\n kwargs...)Simple no-op that skips any tagging of the documents
get_tags(tagger::OpenTagger, docs::AbstractVector{<:AbstractString};\n verbose::Bool = true,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Extracts "tags" (metadata/keywords) from a vector of docs using the provided model (kwarg model).
Arguments
docs: A vector of strings to be embedded.verbose: A boolean flag for verbose output. Default istrue.model: The model to use for tags extraction. Default isPT.MODEL_CHAT.template: A template to be used for tags extraction. Default is:RAGExtractMetadataShort.cost_tracker: AThreads.Atomic{Float64}object to track the total cost of the API calls. Useful to pass the total cost to the parent call.
get_tags(tagger::PassthroughTagger, docs::AbstractVector{<:AbstractString};\n tags::AbstractVector{<:AbstractVector{<:AbstractString}},\n kwargs...)Pass tags directly as Vector of Vectors of strings (ie, tags[i] is the tags for docs[i]). It then builds the vocabulary from the tags and returns both the tags in matrix form and the vocabulary.
getpropertynested(\n nt::NamedTuple, parent_keys::Vector{Symbol}, key::Symbol, default = nothing)Get a property key from a nested NamedTuple nt, where the property is nested to a key in parent_keys.
Useful for nested kwargs where we want to get some property in parent_keys subset (eg, model in retriever_kwargs).
Examples
kw = (; abc = (; def = "x"))\ngetpropertynested(kw, [:abc], :def)\n# Output: "x"hamming_distance(\n mat::AbstractMatrix{T}, query::AbstractVector{T})::Vector{Int} where {T <: Integer}Calculates the column-wise Hamming distance between a matrix of binary vectors mat and a single binary vector vect.
This is the first-pass ranking for BinaryCosineSimilarity method.
Implementation from domluna's tinyRAG.
hcat_truncate(matrices::AbstractVector{<:AbstractMatrix{T}},\n truncate_dimension::Union{Nothing, Int} = nothing; verbose::Bool = false) where {T <:\n Real}Horizontal concatenation of matrices, with optional truncation of the rows of each matrix to the specified dimension (reducing embedding dimensionality).
More efficient that a simple splatting, as the resulting matrix is pre-allocated in one go.
Returns: a Matrix{Float32}
Arguments
matrices::AbstractVector{<:AbstractMatrix{T}}: Vector of matrices to concatenatetruncate_dimension::Union{Nothing,Int}=nothing: Dimension to truncate to, ornothingor0to skip truncation. If truncated, the columns will be normalized.verbose::Bool=false: Whether to print verbose output.
Examples
a = rand(Float32, 1000, 10)\nb = rand(Float32, 1000, 20)\n\nc = hcat_truncate([a, b])\nsize(c) # (1000, 30)\n\nd = hcat_truncate([a, b], 500)\nsize(d) # (500, 30)load_text(chunker::AbstractChunker, input;\n kwargs...)Load text from input using the provided chunker. Called by get_chunks.
Available chunkers:
FileChunker: The function opens each file ininputand reads its contents.TextChunker: The function assumes thatinputis a vector of strings to be chunked, you MUST provide correspondingsources.
merge_kwargs_nested(nt1::NamedTuple, nt2::NamedTuple)Merges two nested NamedTuples nt1 and nt2 recursively. The nt2 values will overwrite the nt1 values when overlapping.
Example
kw = (; abc = (; def = "x"))\nkw2 = (; abc = (; def = "x", def2 = 2), new = 1)\nmerge_kwargs_nested(kw, kw2)pack_bits(arr::AbstractMatrix{<:Bool}) -> Matrix{UInt64}\npack_bits(vect::AbstractVector{<:Bool}) -> Vector{UInt64}Pack a matrix or vector of boolean values into a more compact representation using UInt64.
Arguments (Input)
arr::AbstractMatrix{<:Bool}: A matrix of boolean values where the number of rows must be divisible by 64.
Returns
- For
arr::AbstractMatrix{<:Bool}: Returns a matrix of UInt64 where each element represents 64 boolean values from the original matrix.
Examples
For vectors:
bin = rand(Bool, 128)\nbinint = pack_bits(bin)\nbinx = unpack_bits(binint)\n@assert bin == binxFor matrices:
bin = rand(Bool, 128, 10)\nbinint = pack_bits(bin)\nbinx = unpack_bits(binint)\n@assert bin == binxpermutation_step!(\n result::RankGPTResult; rank_start::Integer = 1, rank_end::Integer = 100, kwargs...)One sub-step of the RankGPT algorithm permutation ranking within the window of chunks defined by rank_start and rank_end positions.
preprocess_tokens(text::AbstractString, stemmer=nothing; stopwords::Union{Nothing,Set{String}}=nothing, min_length::Int=3)Preprocess provided text by removing numbers, punctuation, and applying stemming for BM25 search index.
Returns a list of preprocessed tokens.
Example
stemmer = Snowball.Stemmer("english")\nstopwords = Set(["a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "some", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"])\ntext = "This is a sample paragraph to test the functionality of your text preprocessor. It contains a mix of uppercase and lowercase letters, as well as punctuation marks such as commas, periods, and exclamation points! Let's see how your preprocessor handles quotes, like "this one", and also apostrophes, like in don't. Will it preserve the formatting of this paragraph, including the indentation and line breaks?"\npreprocess_tokens(text, stemmer; stopwords)print_html([io::IO,] parent_node::AbstractAnnotatedNode)\n\nprint_html([io::IO,] rag::AbstractRAGResult; add_sources::Bool = false,\n add_scores::Bool = false, default_styler = HTMLStyler(),\n low_styler = HTMLStyler(styles = "color:magenta", classes = ""),\n medium_styler = HTMLStyler(styles = "color:blue", classes = ""),\n high_styler = HTMLStyler(styles = "", classes = ""), styler_kwargs...)Pretty-prints the annotation parent_node (or RAGResult) to the io stream (or returns the string) in HTML format (assumes node is styled with styler HTMLStyler).
It wraps each "token" into a span with requested styling (HTMLStyler's properties classes and styles). It also replaces new lines with <br> for better HTML formatting.
For any non-HTML styler, it prints the content as plain text.
Returns
nothingifiois providedor the string with HTML-formatted text (if
iois not provided, we print the result out)
See also HTMLStyler, annotate_support, and set_node_style! for how the styling is applied and what the arguments mean.
Examples
Note: RT is an alias for PromptingTools.Experimental.RAGTools
Simple start directly with the RAGResult:
# set up the text/RAGResult\ncontext = [\n "This is a test context.", "Another context sentence.", "Final piece of context."]\nanswer = "This is a test answer. It has multiple sentences."\nrag = RT.RAGResult(; context, final_answer=answer, question="")\n\n# print the HTML\nprint_html(rag)Low-level control by creating our AnnotatedNode:
# prepare your HTML styling\nstyler_kwargs = (;\n default_styler=RT.HTMLStyler(),\n low_styler=RT.HTMLStyler(styles="color:magenta", classes=""),\n medium_styler=RT.HTMLStyler(styles="color:blue", classes=""),\n high_styler=RT.HTMLStyler(styles="", classes=""))\n\n# annotate the text\ncontext = [\n "This is a test context.", "Another context sentence.", "Final piece of context."]\nanswer = "This is a test answer. It has multiple sentences."\n\nparent_node = RT.annotate_support(\n RT.TrigramAnnotater(), answer, context; add_sources=false, add_scores=false, styler_kwargs...)\n\n# print the HTML\nprint_html(parent_node)\n\n# or to accumulate more nodes\nio = IOBuffer()\nprint_html(io, parent_node)rank_gpt(chunks::AbstractVector{<:AbstractString}, question::AbstractString;\n verbose::Int = 1, rank_start::Integer = 1, rank_end::Integer = 100,\n window_size::Integer = 20, step::Integer = 10,\n num_rounds::Integer = 1, model::String = "gpt4o", kwargs...)Ranks the chunks based on their relevance for question. Returns the ranking permutation of the chunks in the order they are most relevant to the question (the first is the most relevant).
Example
result = rank_gpt(chunks, question; rank_start=1, rank_end=25, window_size=8, step=4, num_rounds=3, model="gpt4o")Reference
[1] Is ChatGPT Good at Search? Investigating Large Language Models as Re-Ranking Agents by W. Sun et al. [2] RankGPT Github
rank_sliding_window!(\n result::RankGPTResult; verbose::Int = 1, rank_start = 1, rank_end = 100,\n window_size = 20, step = 10, model::String = "gpt4o", kwargs...)One single pass of the RankGPT algorithm permutation ranking across all positions between rank_start and rank_end.
receive_permutation!(\n curr_rank::AbstractVector{<:Integer}, response::AbstractString;\n rank_start::Integer = 1, rank_end::Integer = 100)Extracts and heals the permutation to contain all ranking positions.
reciprocal_rank_fusion(args...; k::Int=60)Merges multiple rankings and calculates the reciprocal rank score for each chunk (discounted by the inverse of the rank).
Example
positions1 = [1, 3, 5, 7, 9]\npositions2 = [2, 4, 6, 8, 10]\npositions3 = [2, 4, 6, 11, 12]\n\nmerged_positions, scores = reciprocal_rank_fusion(positions1, positions2, positions3)reciprocal_rank_fusion(\n positions1::AbstractVector{<:Integer}, scores1::AbstractVector{<:T},\n positions2::AbstractVector{<:Integer},\n scores2::AbstractVector{<:T}; k::Int = 60) where {T <: Real}Merges two sets of rankings and their joint scores. Calculates the reciprocal rank score for each chunk (discounted by the inverse of the rank).
Example
positions1 = [1, 3, 5, 7, 9]\nscores1 = [0.9, 0.8, 0.7, 0.6, 0.5]\npositions2 = [2, 4, 6, 8, 10]\nscores2 = [0.5, 0.6, 0.7, 0.8, 0.9]\n\nmerged, scores = reciprocal_rank_fusion(positions1, scores1, positions2, scores2; k = 60)refine!(\n refiner::NoRefiner, index::AbstractChunkIndex, result::AbstractRAGResult;\n kwargs...)Simple no-op function for refine!. It simply copies the result.answer and result.conversations[:answer] without any changes.
refine!(\n refiner::SimpleRefiner, index::AbstractDocumentIndex, result::AbstractRAGResult;\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_CHAT,\n template::Symbol = :RAGAnswerRefiner,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Give model a chance to refine the answer (using the same or different context than previously provided).
This method uses the same context as the original answer, however, it can be modified to do additional retrieval and use a different context.
Returns
- Mutated
resultwithresult.final_answerand the full conversation saved inresult.conversations[:final_answer]
Arguments
refiner::SimpleRefiner: The method to use for refining the answer. Usesaigenerate.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.model::AbstractString: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.verbose::Bool: Iftrue, enables verbose logging.template::Symbol: The template to use for theaigeneratefunction. Defaults to:RAGAnswerRefiner.cost_tracker: An atomic counter to track the cost of the operation.
refine!(\n refiner::TavilySearchRefiner, index::AbstractDocumentIndex, result::AbstractRAGResult;\n verbose::Bool = true,\n model::AbstractString = PT.MODEL_CHAT,\n include_answer::Bool = true,\n max_results::Integer = 5,\n include_domains::AbstractVector{<:AbstractString} = String[],\n exclude_domains::AbstractVector{<:AbstractString} = String[],\n template::Symbol = :RAGWebSearchRefiner,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Refines the answer by executing a web search using the Tavily API. This method aims to enhance the answer's accuracy and relevance by incorporating information retrieved from the web.
Note: The web results and web answer (if requested) will be added to the context and sources!
Returns
Mutated
resultwithresult.final_answerand the full conversation saved inresult.conversations[:final_answer].In addition, the web results and web answer (if requested) are appended to the
result.contextandresult.sourcesfor correct highlighting and verification.
Arguments
refiner::TavilySearchRefiner: The method to use for refining the answer. Usesaigeneratewith a web search template.index::AbstractDocumentIndex: The index containing chunks and sources.result::AbstractRAGResult: The result containing the context and question to generate the answer for.model::AbstractString: The model to use for generating the answer. Defaults toPT.MODEL_CHAT.include_answer::Bool: Iftrue, includes the answer from Tavily in the web search.max_results::Integer: The maximum number of results to return.include_domains::AbstractVector{<:AbstractString}: A list of domains to include in the search results. Default is an empty list.exclude_domains::AbstractVector{<:AbstractString}: A list of domains to exclude from the search results. Default is an empty list.verbose::Bool: Iftrue, enables verbose logging.template::Symbol: The template to use for theaigeneratefunction. Defaults to:RAGWebSearchRefiner.cost_tracker: An atomic counter to track the cost of the operation.
Example
refiner!(TavilySearchRefiner(), index, result)\n# See result.final_answer or pprint(result)To enable this refiner in a full RAG pipeline, simply swap the component in the config:
cfg = RT.RAGConfig()\ncfg.generator.refiner = RT.TavilySearchRefiner()\n\nresult = airag(cfg, index; question, return_all = true)\npprint(result)rephrase(rephraser::SimpleRephraser, question::AbstractString;\n verbose::Bool = true,\n model::String = PT.MODEL_CHAT, template::Symbol = :RAGQueryHyDE,\n cost_tracker = Threads.Atomic{Float64}(0.0))Rephrases the question using the provided rephraser template = RAGQueryHyDE.
Special flavor of rephrasing using HyDE (Hypothetical Document Embedding) method, which aims to find the documents most similar to a synthetic passage that would be a good answer to our question.
Returns both the original and the rephrased question.
Arguments
rephraser: Type that dictates the logic of rephrasing step.question: The question to be rephrased.model: The model to use for rephrasing. Default isPT.MODEL_CHAT.template: The rephrasing template to use. Default is:RAGQueryHyDE. Find more withaitemplates("rephrase").verbose: A boolean flag indicating whether to print verbose logging. Default istrue.
rephrase(rephraser::NoRephraser, question::AbstractString; kwargs...)No-op, simple passthrough.
rephrase(rephraser::SimpleRephraser, question::AbstractString;\n verbose::Bool = true,\n model::String = PT.MODEL_CHAT, template::Symbol = :RAGQueryOptimizer,\n cost_tracker = Threads.Atomic{Float64}(0.0), kwargs...)Rephrases the question using the provided rephraser template.
Returns both the original and the rephrased question.
Arguments
rephraser: Type that dictates the logic of rephrasing step.question: The question to be rephrased.model: The model to use for rephrasing. Default isPT.MODEL_CHAT.template: The rephrasing template to use. Default is:RAGQueryOptimizer. Find more withaitemplates("rephrase").verbose: A boolean flag indicating whether to print verbose logging. Default istrue.
rerank(\n reranker::CohereReranker, index::AbstractDocumentIndex, question::AbstractString,\n candidates::AbstractCandidateChunks;\n verbose::Bool = false,\n api_key::AbstractString = PT.COHERE_API_KEY,\n top_n::Integer = length(candidates.scores),\n model::AbstractString = "rerank-english-v3.0",\n return_documents::Bool = false,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Re-ranks a list of candidate chunks using the Cohere Rerank API. See https://cohere.com/rerank for more details.
Arguments
reranker: Using Cohere APIindex: The index that holds the underlying chunks to be re-ranked.question: The query to be used for the search.candidates: The candidate chunks to be re-ranked.top_n: The number of most relevant documents to return. Default islength(documents).model: The model to use for reranking. Default isrerank-english-v3.0.return_documents: A boolean flag indicating whether to return the reranked documents in the response. Default isfalse.verbose: A boolean flag indicating whether to print verbose logging. Default isfalse.cost_tracker: An atomic counter to track the cost of the retrieval. Not implemented /tracked (cost unclear). Provided for consistency.
rerank(\n reranker::RankGPTReranker, index::AbstractDocumentIndex, question::AbstractString,\n candidates::AbstractCandidateChunks;\n api_key::AbstractString = PT.OPENAI_API_KEY,\n model::AbstractString = PT.MODEL_CHAT,\n verbose::Bool = false,\n top_n::Integer = length(candidates.scores),\n unique_chunks::Bool = true,\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Re-ranks a list of candidate chunks using the RankGPT algorithm. See https://github.com/sunnweiwei/RankGPT for more details.
It uses LLM calls to rank the candidate chunks.
Arguments
reranker: Using Cohere APIindex: The index that holds the underlying chunks to be re-ranked.question: The query to be used for the search.candidates: The candidate chunks to be re-ranked.top_n: The number of most relevant documents to return. Default islength(documents).model: The model to use for reranking. Default isrerank-english-v3.0.verbose: A boolean flag indicating whether to print verbose logging. Default is1.unique_chunks: A boolean flag indicating whether to remove duplicates from the candidate chunks prior to reranking (saves compute time). Default istrue.
Examples
index = <some index>\nquestion = "What are the best practices for parallel computing in Julia?"\n\ncfg = RAGConfig(; retriever = SimpleRetriever(; reranker = RT.RankGPTReranker()))\nmsg = airag(cfg, index; question, return_all = true)To get full verbosity of logs, set verbose = 5 (anything higher than 3).
msg = airag(cfg, index; question, return_all = true, verbose = 5)Reference
[1] Is ChatGPT Good at Search? Investigating Large Language Models as Re-Ranking Agents by W. Sun et al. [2] RankGPT Github
retrieve(retriever::AbstractRetriever,\n index::AbstractChunkIndex,\n question::AbstractString;\n verbose::Integer = 1,\n top_k::Integer = 100,\n top_n::Integer = 5,\n api_kwargs::NamedTuple = NamedTuple(),\n rephraser::AbstractRephraser = retriever.rephraser,\n rephraser_kwargs::NamedTuple = NamedTuple(),\n embedder::AbstractEmbedder = retriever.embedder,\n embedder_kwargs::NamedTuple = NamedTuple(),\n processor::AbstractProcessor = retriever.processor,\n processor_kwargs::NamedTuple = NamedTuple(),\n finder::AbstractSimilarityFinder = retriever.finder,\n finder_kwargs::NamedTuple = NamedTuple(),\n tagger::AbstractTagger = retriever.tagger,\n tagger_kwargs::NamedTuple = NamedTuple(),\n filter::AbstractTagFilter = retriever.filter,\n filter_kwargs::NamedTuple = NamedTuple(),\n reranker::AbstractReranker = retriever.reranker,\n reranker_kwargs::NamedTuple = NamedTuple(),\n cost_tracker = Threads.Atomic{Float64}(0.0),\n kwargs...)Retrieves the most relevant chunks from the index for the given question and returns them in the RAGResult object.
This is the main entry point for the retrieval stage of the RAG pipeline. It is often followed by generate! step.
Notes:
- The default flow is
build_context!->answer!->refine!->postprocess!.
The arguments correspond to the steps of the retrieval process (rephrasing, embedding, finding similar docs, tagging, filtering by tags, reranking). You can customize each step by providing a new custom type that dispatches the corresponding function, eg, create your own type struct MyReranker<:AbstractReranker end and define the custom method for it rerank(::MyReranker,...) = ....
Note: Discover available retrieval sub-types for each step with subtypes(AbstractRephraser) and similar for other abstract types.
If you're using locally-hosted models, you can pass the api_kwargs with the url field set to the model's URL and make sure to provide corresponding model kwargs to rephraser, embedder, and tagger to use the custom models (they make AI calls).
Arguments
retriever: The retrieval method to use. Default isSimpleRetrieverbut could beAdvancedRetrieverfor more advanced retrieval.index: The index that holds the chunks and sources to be retrieved from.question: The question to be used for the retrieval.verbose: If>0, it prints out verbose logging. Default is1. If you set it to2, it will print out logs for each sub-function.top_k: The TOTAL number of closest chunks to return fromfind_closest. Default is100. If there are multiple rephrased questions, the number of chunks per each item will betop_k ÷ number_of_rephrased_questions.top_n: The TOTAL number of most relevant chunks to return for the context (fromrerankstep). Default is5.api_kwargs: Additional keyword arguments to be passed to the API calls (shared by allai*calls).rephraser: Transform the question into one or more questions. Default isretriever.rephraser.rephraser_kwargs: Additional keyword arguments to be passed to the rephraser.model: The model to use for rephrasing. Default isPT.MODEL_CHAT.template: The rephrasing template to use. Default is:RAGQueryOptimizeror:RAGQueryHyDE(depending on therephraserselected).
embedder: The embedding method to use. Default isretriever.embedder.embedder_kwargs: Additional keyword arguments to be passed to the embedder.processor: The processor method to use when using Keyword-based index. Default isretriever.processor.processor_kwargs: Additional keyword arguments to be passed to the processor.finder: The similarity search method to use. Default isretriever.finder, oftenCosineSimilarity.finder_kwargs: Additional keyword arguments to be passed to the similarity finder.tagger: The tag generating method to use. Default isretriever.tagger.tagger_kwargs: Additional keyword arguments to be passed to the tagger. Noteworthy arguments:tags: Directly provide the tags to use for filtering (can be String, Regex, or Vector{String}). Useful fortagger = PassthroughTagger.
filter: The tag matching method to use. Default isretriever.filter.filter_kwargs: Additional keyword arguments to be passed to the tag filter.reranker: The reranking method to use. Default isretriever.reranker.reranker_kwargs: Additional keyword arguments to be passed to the reranker.model: The model to use for reranking. Default isrerank-english-v2.0if you usereranker = CohereReranker().
cost_tracker: An atomic counter to track the cost of the retrieval. Default isThreads.Atomic{Float64}(0.0).
See also: SimpleRetriever, AdvancedRetriever, build_index, rephrase, get_embeddings, get_keywords, find_closest, get_tags, find_tags, rerank, RAGResult.
Examples
Find the 5 most relevant chunks from the index for the given question.
# assumes you have an existing index `index`\nretriever = SimpleRetriever()\n\nresult = retrieve(retriever,\n index,\n "What is the capital of France?",\n top_n = 5)\n\n# or use the default retriever (same as above)\nresult = retrieve(retriever,\n index,\n "What is the capital of France?",\n top_n = 5)Apply more advanced retrieval with question rephrasing and reranking (requires COHERE_API_KEY). We will obtain top 100 chunks from embeddings (top_k) and top 5 chunks from reranking (top_n).
retriever = AdvancedRetriever()\n\nresult = retrieve(retriever, index, question; top_k=100, top_n=5)You can use the retriever to customize your retrieval strategy or directly change the strategy types in the retrieve kwargs!
Example of using locally-hosted model hosted on localhost:8080:
retriever = SimpleRetriever()\nresult = retrieve(retriever, index, question;\n rephraser_kwargs = (; model = "custom"),\n embedder_kwargs = (; model = "custom"),\n tagger_kwargs = (; model = "custom"), api_kwargs = (;\n url = "http://localhost:8080"))run_qa_evals(index::AbstractChunkIndex, qa_items::AbstractVector{<:QAEvalItem};\n api_kwargs::NamedTuple = NamedTuple(),\n airag_kwargs::NamedTuple = NamedTuple(),\n qa_evals_kwargs::NamedTuple = NamedTuple(),\n verbose::Bool = true, parameters_dict::Dict{Symbol, <:Any} = Dict{Symbol, Any}())Evaluates a vector of QAEvalItems and returns a vector QAEvalResult. This function assesses the relevance and accuracy of the answers generated in a QA evaluation context.
See ?run_qa_evals for more details.
Arguments
qa_items::AbstractVector{<:QAEvalItem}: The vector of QA evaluation items containing the questions and their answers.verbose::Bool: Iftrue, enables verbose logging. Defaults totrue.api_kwargs::NamedTuple: Parameters that will be forwarded to the API calls. See?aiextractfor details.airag_kwargs::NamedTuple: Parameters that will be forwarded toairagcalls. See?airagfor details.qa_evals_kwargs::NamedTuple: Parameters that will be forwarded torun_qa_evalscalls. See?run_qa_evalsfor details.parameters_dict::Dict{Symbol, Any}: Track any parameters used for later evaluations. Keys must be Symbols.
Returns
Vector{QAEvalResult}: Vector of evaluation results that includes various scores and metadata related to the QA evaluation.
Example
index = "..." # Assuming a proper index is defined\nqa_items = [QAEvalItem(question="What is the capital of France?", answer="Paris", context="France is a country in Europe."),\n QAEvalItem(question="What is the capital of Germany?", answer="Berlin", context="Germany is a country in Europe.")]\n\n# Let's run a test with `top_k=5`\nresults = run_qa_evals(index, qa_items; airag_kwargs=(;top_k=5), parameters_dict=Dict(:top_k => 5))\n\n# Filter out the "failed" calls\nresults = filter(x->!isnothing(x.answer_score), results);\n\n# See average judge score\nmean(x->x.answer_score, results)run_qa_evals(qa_item::QAEvalItem, ctx::RAGResult; verbose::Bool = true,\n parameters_dict::Dict{Symbol, <:Any}, judge_template::Symbol = :RAGJudgeAnswerFromContext,\n model_judge::AbstractString, api_kwargs::NamedTuple = NamedTuple()) -> QAEvalResultEvaluates a single QAEvalItem using RAG details (RAGResult) and returns a QAEvalResult structure. This function assesses the relevance and accuracy of the answers generated in a QA evaluation context.
Arguments
qa_item::QAEvalItem: The QA evaluation item containing the question and its answer.ctx::RAGResult: The RAG result used for generating the QA pair, including the original context and the answers. Comes fromairag(...; return_context=true)verbose::Bool: Iftrue, enables verbose logging. Defaults totrue.parameters_dict::Dict{Symbol, Any}: Track any parameters used for later evaluations. Keys must be Symbols.judge_template::Symbol: The template symbol for the AI model used to judge the answer. Defaults to:RAGJudgeAnswerFromContext.model_judge::AbstractString: The AI model used for judging the answer's quality. Defaults to standard chat model, but it is advisable to use more powerful model GPT-4.api_kwargs::NamedTuple: Parameters that will be forwarded to the API endpoint.
Returns
QAEvalResult: An evaluation result that includes various scores and metadata related to the QA evaluation.
Notes
The function computes a retrieval score and rank based on how well the context matches the QA context.
It then uses the
judge_templateandmodel_judgeto score the answer's accuracy and relevance.In case of errors during evaluation, the function logs a warning (if
verboseistrue) and theanswer_scorewill be set tonothing.
Examples
Evaluating a QA pair using a specific context and model:
qa_item = QAEvalItem(question="What is the capital of France?", answer="Paris", context="France is a country in Europe.")\nctx = RAGResult(source="Wikipedia", context="France is a country in Europe.", answer="Paris")\nparameters_dict = Dict("param1" => "value1", "param2" => "value2")\n\neval_result = run_qa_evals(qa_item, ctx, parameters_dict=parameters_dict, model_judge="MyAIJudgeModel")Returns 1.0 if context overlaps or is contained within any of the candidate_context
Returns Integer rank of the position where context overlaps or is contained within a candidate_context
score_to_unit_scale(x::AbstractVector{T}) where T<:RealShift and scale a vector of scores to the unit scale [0, 1].
Example
x = [1.0, 2.0, 3.0, 4.0, 5.0]\nscaled_x = score_to_unit_scale(x)set_node_style!(::TrigramAnnotater, node::AnnotatedNode;\n low_threshold::Float64 = 0.0, medium_threshold::Float64 = 0.5, high_threshold::Float64 = 1.0,\n default_styler::AbstractAnnotationStyler = Styler(),\n low_styler::AbstractAnnotationStyler = Styler(color = :magenta, bold = false),\n medium_styler::AbstractAnnotationStyler = Styler(color = :blue, bold = false),\n high_styler::AbstractAnnotationStyler = Styler(color = :nothing, bold = false),\n bold_multihits::Bool = false)Sets style of node based on the provided rules
setpropertynested(nt::NamedTuple, parent_keys::Vector{Symbol},\n key::Symbol,\n value)
Setter for a property key in a nested NamedTuple nt, where the property is nested to a key in parent_keys.
Useful for nested kwargs where we want to change some property in parent_keys subset (eg, model in retriever_kwargs).
Examples
kw = (; abc = (; def = "x"))\nsetpropertynested(kw, [:abc], :def, "y")\n# Output: (abc = (def = "y",),)Practical example of changing all model keys in CHAT-based steps in the pipeline:
# changes :model to "gpt4t" whenever the parent key is in the below list (chat-based steps)\nsetpropertynested(kwargs,\n [:rephraser_kwargs, :tagger_kwargs, :answerer_kwargs, :refiner_kwargs],\n :model, "gpt4t")Or changing an embedding model (across both indexer and retriever steps, because it's same step name):
kwargs = setpropertynested(\n kwargs, [:embedder_kwargs],\n :model, "text-embedding-3-large"\n )split_into_code_and_sentences(input::Union{String, SubString{String}})Splits text block into code or text and sub-splits into units.
If code block, it splits by newline but keep the group_id the same (to have the same source) If text block, splits into sentences, bullets, etc., provides different group_id (to have different source)
tags_extract(item::Tag)\ntags_extract(tags::Vector{Tag})Extracts the Tag item into a string of the form category:::value (lowercased and spaces replaced with underscores).
Example
msg = aiextract(:RAGExtractMetadataShort; return_type=MaybeTags, text="I like package DataFrames", instructions="None.")\nmetadata = tags_extract(msg.content.items)token_with_boundaries(\n prev_token::Union{Nothing, AbstractString}, curr_token::AbstractString,\n next_token::Union{Nothing, AbstractString})Joins the three tokens together. Useful to add boundary tokens (like spaces vs brackets) to the curr_token to improve the matched context (ie, separate partial matches from exact match)
tokenize(input::Union{String, SubString{String}})Tokenizes provided input by spaces, special characters or Julia symbols (eg, =>).
Unlike other tokenizers, it aims to lossless - ie, keep both the separated text and the separators.
translate_positions_to_parent(index::AbstractChunkIndex, positions::AbstractVector{<:Integer})Translate positions to the parent index. Useful to convert between positions in a view and the original index.
Used whenever a chunkdata() is used to re-align positions in case index is a view.
translate_positions_to_parent(\n index::SubChunkIndex, pos::AbstractVector{<:Integer})Translate positions to the parent index. Useful to convert between positions in a view and the original index.
Used whenever a chunkdata() or tags() are used to re-align positions to the "parent" index.
trigram_support!(parent_node::AnnotatedNode,\n context_trigrams::AbstractVector, trigram_func::F1 = trigrams, token_transform::F2 = identity;\n skip_trigrams::Bool = false, min_score::Float64 = 0.5,\n min_source_score::Float64 = 0.25,\n stop_words::AbstractVector{<:String} = STOPWORDS,\n styler_kwargs...) where {F1 <: Function, F2 <: Function}Find if the parent_node.content is supported by the provided context_trigrams.
Logic:
Split the
parent_node.contentinto tokensCreate an
AnnotatedNodefor each tokenIf
skip_trigramsis enabled, it looks for an exact match in thecontext_trigramsIf no exact match found, it counts trigram-based match (include the surrounding tokens for better contextual awareness) as a score
Then it sets the style of the node based on the score
Lastly, it aligns the styles of neighboring nodes with
score==nothing(eg, single character tokens)Then, it rolls up the scores and sources to the parent node
For diagnostics, you can use AbstractTrees.print_tree(parent_node) to see the tree structure of each token and its score.
Example
\nnode = AnnotatedNode(content = "xyz") trigram_support!(node, context_trigrams) # updates node.children! ```\n\n\n[source](https://github.com/svilupp/PromptingTools.jl/blob/5d2f7e033125a9e00d4dd58b1553cd8653567938/src/Experimental/RAGTools/annotation.jl#L215-L244)\n\n</div>\n<br>\n<div style='border-width:1px; border-style:solid; border-color:black; padding: 1em; border-radius: 25px;'>\n<a id='PromptingTools.Experimental.RAGTools.trigrams-Tuple{AbstractString}' href='#PromptingTools.Experimental.RAGTools.trigrams-Tuple{AbstractString}'>#</a> <b><u>PromptingTools.Experimental.RAGTools.trigrams</u></b> — <i>Method</i>.\n\n\n\n\n```julia\ntrigrams(input_string::AbstractString; add_word::AbstractString = "")Splits provided input_string into a vector of trigrams (combination of three consecutive characters found in the input_string).
If add_word is provided, it is added to the resulting array. Useful to add the full word itself to the resulting array for exact match.
trigrams_hashed(input_string::AbstractString; add_word::AbstractString = "")Splits provided input_string into a Set of hashed trigrams (combination of three consecutive characters found in the input_string).
It is more efficient for lookups in large strings (eg, >100K characters).
If add_word is provided, it is added to the resulting array to hash. Useful to add the full word itself to the resulting array for exact match.
PT.last_message(result::RAGResult)Extract the last message from the RAGResult. It looks for final_answer first, then answer fields in the conversations dictionary. Returns nothing if not found.
Extracts the last output (generated text answer) from the RAGResult.
PromptingTools.pprint(\n io::IO, node::AbstractAnnotatedNode;\n text_width::Int = displaysize(io)[2], add_newline::Bool = true)Pretty print the node to the io stream, including all its children
Supports only node.style::Styler for now.
PT.pprint(\n io::IO, r::AbstractRAGResult; add_context::Bool = false,\n text_width::Int = displaysize(io)[2], annotater_kwargs...)Pretty print the RAG result r to the given io stream.
If add_context is true, the context will be printed as well. The text_width parameter can be used to control the width of the output.
You can provide additional keyword arguments to the annotater, eg, add_sources, add_scores, min_score, etc. See annotate_support for more details.
', 284) + ])); +} +const reference_ragtools = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); +export { + __pageData, + reference_ragtools as default +}; diff --git a/previews/PR252/assets/style.BdjkExOa.css b/previews/PR252/assets/style.BdjkExOa.css new file mode 100644 index 00000000..e3c550a6 --- /dev/null +++ b/previews/PR252/assets/style.BdjkExOa.css @@ -0,0 +1,5286 @@ +@import url(https://fonts.googleapis.com/css?family=Space+Mono:regular,italic,700,700italic);@import url(https://fonts.googleapis.com/css?family=Space+Grotesk:regular,italic,700,700italic); + +@font-face { + font-family: Inter; + font-style: normal; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2') format('woff2'); + unicode-range: U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, + U+FE2E-FE2F; +} + +@font-face { + font-family: Inter; + font-style: normal; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-roman-cyrillic.C5lxZ8CY.woff2') format('woff2'); + unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116; +} + +@font-face { + font-family: Inter; + font-style: normal; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-roman-greek-ext.CqjqNYQ-.woff2') format('woff2'); + unicode-range: U+1F00-1FFF; +} + +@font-face { + font-family: Inter; + font-style: normal; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-roman-greek.BBVDIX6e.woff2') format('woff2'); + unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, + U+03A3-03FF; +} + +@font-face { + font-family: Inter; + font-style: normal; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-roman-vietnamese.BjW4sHH5.woff2') format('woff2'); + unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, + U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, + U+1EA0-1EF9, U+20AB; +} + +@font-face { + font-family: Inter; + font-style: normal; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-roman-latin-ext.4ZJIpNVo.woff2') format('woff2'); + unicode-range: U+0100-02AF, U+0304, U+0308, U+0329, U+1E00-1E9F, U+1EF2-1EFF, + U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; +} + +@font-face { + font-family: Inter; + font-style: normal; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-roman-latin.Di8DUHzh.woff2') format('woff2'); + unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, + U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, + U+2193, U+2212, U+2215, U+FEFF, U+FFFD; +} + +@font-face { + font-family: Inter; + font-style: italic; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-italic-cyrillic-ext.r48I6akx.woff2') format('woff2'); + unicode-range: U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, + U+FE2E-FE2F; +} + +@font-face { + font-family: Inter; + font-style: italic; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-italic-cyrillic.By2_1cv3.woff2') format('woff2'); + unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116; +} + +@font-face { + font-family: Inter; + font-style: italic; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-italic-greek-ext.1u6EdAuj.woff2') format('woff2'); + unicode-range: U+1F00-1FFF; +} + +@font-face { + font-family: Inter; + font-style: italic; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-italic-greek.DJ8dCoTZ.woff2') format('woff2'); + unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, + U+03A3-03FF; +} + +@font-face { + font-family: Inter; + font-style: italic; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-italic-vietnamese.BSbpV94h.woff2') format('woff2'); + unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, + U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, + U+1EA0-1EF9, U+20AB; +} + +@font-face { + font-family: Inter; + font-style: italic; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-italic-latin-ext.CN1xVJS-.woff2') format('woff2'); + unicode-range: U+0100-02AF, U+0304, U+0308, U+0329, U+1E00-1E9F, U+1EF2-1EFF, + U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF; +} + +@font-face { + font-family: Inter; + font-style: italic; + font-weight: 100 900; + font-display: swap; + src: url('/PromptingTools.jl/previews/PR252/assets/inter-italic-latin.C2AdPX0b.woff2') format('woff2'); + unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, + U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, + U+2193, U+2212, U+2215, U+FEFF, U+FFFD; +} + +@font-face { + font-family: 'Punctuation SC'; + font-weight: 400; + src: local('PingFang SC Regular'), local('Noto Sans CJK SC'), + local('Microsoft YaHei'); + unicode-range: U+201C, U+201D, U+2018, U+2019, U+2E3A, U+2014, U+2013, U+2026, + U+00B7, U+007E, U+002F; +} + +@font-face { + font-family: 'Punctuation SC'; + font-weight: 500; + src: local('PingFang SC Medium'), local('Noto Sans CJK SC'), + local('Microsoft YaHei'); + unicode-range: U+201C, U+201D, U+2018, U+2019, U+2E3A, U+2014, U+2013, U+2026, + U+00B7, U+007E, U+002F; +} + +@font-face { + font-family: 'Punctuation SC'; + font-weight: 600; + src: local('PingFang SC Semibold'), local('Noto Sans CJK SC Bold'), + local('Microsoft YaHei Bold'); + unicode-range: U+201C, U+201D, U+2018, U+2019, U+2E3A, U+2014, U+2013, U+2026, + U+00B7, U+007E, U+002F; +} + +@font-face { + font-family: 'Punctuation SC'; + font-weight: 700; + src: local('PingFang SC Semibold'), local('Noto Sans CJK SC Bold'), + local('Microsoft YaHei Bold'); + unicode-range: U+201C, U+201D, U+2018, U+2019, U+2E3A, U+2014, U+2013, U+2026, + U+00B7, U+007E, U+002F; +} + +/* Generate the subsetted fonts using: `pyftsubset