@mikugg/guidance 0.8.0

package/README.md

@@ -0,0 +1,73 @@
+# Guidance-like library for Node.js
+This library is a port of the [Guidance](https://github.com/guidance-ai/guidance) library for Node.js. It allows you to generate text from templates using a Language Model (LLM) and an endpoint that can generate text from a prompt.
+
+## Installation
+```bash
+npm install @mikugg/guidance
+```
+
+## Usage
+You can use end OpenAI endpoint to generate text from templates. The template processor will generate text from the template and then use the generated text as a prompt to the OpenAI endpoint. The generated text will be appended to the template and the process will repeat until the stop condition is met.
+
+For serving LLaMA or Mistral models, I recommend using [Aphrodite Engine](https://github.com/PygmalionAI/aphrodite-engine), since it has `logit_bias` support.
+
+```javascript
+import * as Guidance from '@mikugg/guidance';
+
+const tokenizer = new Guidance.Tokenizer.LLaMATokenizer();
+const generator = new Guidance.TokenGenerator.OpenAITokenGenerator({
+  apiKey: 'sk-EMPTY',
+  baseURL: 'http://localhost:2242/v1',
+  model: 'mistralai/Mistral-7B-v0.1',
+});
+const templateProcessor = new Guidance.Template.TemplateProcessor(tokenizer, generator);
+
+let result = await templateProcessor.processTemplate(
+  `Common sense question and answer, with short answers
+  Question: What is your favorite food?
+  Answer: "Sushi."
+  Question: What is your favorite color?
+  Answer: "Blue."
+  Question: What is your favorite animal?
+  Answer: "{{GEN response stop=" }}"`,
+  new Map([])
+).then((result) => {
+  console.log(result.entries()); // {"response": "Elephant."}
+});
+```
+
+### Select from a list of options
+You can provide an array of options to select the next text. The TemplateProcessor will increase the probability of one of those options being selected by the LLM.
+
+```javascript
+import * as Guidance from '@mikugg/guidance';
+
+const tokenizer = new Guidance.Tokenizer.LLaMATokenizer();
+const generator = new Guidance.TokenGenerator.OpenAITokenGenerator({
+  apiKey: 'sk-EMPTY',
+  baseURL: 'http://localhost:2242/v1',
+  model: 'mistralai/Mistral-7B-v0.1',
+});
+const templateProcessor = new Guidance.Template.TemplateProcessor(tokenizer, generator);
+
+let result = await templateProcessor.processTemplate(
+  `RPG Game Character specification
+  {
+    "name": "{{name}}",
+    "job": "{{GEN job stop=",}}",
+    "armor": "{{SEL armor options=valid_armors}}",
+    "weapon": "{{SEL weapon options=valid_weapons}}",
+    "pants": "{{SEL pants options=valid_pants}}"
+  }`,
+  new Map<string, string[] | string>([
+    ['name', 'Rudeus'],
+    ['valid_armors', ['plate', 'leather']],
+    ['valid_weapons', ["axe", "mace", "spear", "sword", "bow", "crossbow"]],
+    ['valid_pants', ['leather_jacket', 'leather_shorts', 'hat']], // Should select leather_shorts
+  ])
+).then((result) => {
+  console.log(result.entries());
+});
+```
+
+You can check more examples in the [this file](./demo/index.ts).

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import * as Tokenizer from './lib/tokenizer';
+import * as TokenGenerator from './lib/token-generator';
+import * as Template from './lib/template';
+export { Tokenizer, TokenGenerator, Template };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAM,SAAS,MAAM,iBAAiB,CAAC;AAC9C,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Template = exports.TokenGenerator = exports.Tokenizer = void 0;
+const Tokenizer = __importStar(require("./lib/tokenizer"));
+exports.Tokenizer = Tokenizer;
+const TokenGenerator = __importStar(require("./lib/token-generator"));
+exports.TokenGenerator = TokenGenerator;
+const Template = __importStar(require("./lib/template"));
+exports.Template = Template;

package/dist/lib/__test__/_trie.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=_trie.test.d.ts.map

package/dist/lib/__test__/_trie.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_trie.test.d.ts","sourceRoot":"","sources":["../../../src/lib/__test__/_trie.test.ts"],"names":[],"mappings":""}

package/dist/lib/__test__/_trie.test.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const _trie_1 = __importDefault(require("../_trie")); // replace './Trie' with the actual path of your Trie class
+describe('Trie', () => {
+    let trie;
+    beforeEach(() => {
+        trie = new _trie_1.default();
+    });
+    test('addPrefix should add numbers to the trie', () => {
+        var _a, _b, _c;
+        trie.addPrefix([1, 2, 3]);
+        expect(trie.root.children.has(1)).toBeTruthy();
+        expect((_a = trie.root.children.get(1)) === null || _a === void 0 ? void 0 : _a.children.has(2)).toBeTruthy();
+        expect((_c = (_b = trie.root.children.get(1)) === null || _b === void 0 ? void 0 : _b.children.get(2)) === null || _c === void 0 ? void 0 : _c.children.has(3)).toBeTruthy();
+    });
+    test('getNextChildren should return correct next children', () => {
+        trie.addPrefix([1, 2, 3]);
+        trie.addPrefix([1, 2, 4]);
+        expect(trie.getNextChildren([1, 2])).toEqual([3, 4]);
+    });
+    test('getNextPrefix should return correct next prefix', () => {
+        trie.addPrefix([1, 2, 3]);
+        trie.addPrefix([1, 2, 3, 4]);
+        expect(trie.getNextPrefix([1, 2])).toEqual([1, 2, 3]);
+    });
+    test('getNextPrefix should return correct next prefix', () => {
+        trie.addPrefix([1, 2, 3, 4, 5]);
+        trie.addPrefix([1, 2, 3, 4, 7]);
+        expect(trie.getNextPrefix([1, 2])).toEqual([1, 2, 3, 4]);
+    });
+    test('getWord should return correct word until the end of the prefix', () => {
+        trie.addPrefix([1, 2, 3]);
+        trie.addPrefix([1, 2, 3, 4]);
+        expect(trie.getWord([1, 2])).toEqual([1, 2, 3]);
+    });
+    test('getWord should return empty array if prefix not found', () => {
+        trie.addPrefix([1, 2, 3]);
+        expect(trie.getWord([4])).toEqual([]);
+    });
+});

package/dist/lib/__test__/template.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=template.test.d.ts.map

package/dist/lib/__test__/template.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.test.d.ts","sourceRoot":"","sources":["../../../src/lib/__test__/template.test.ts"],"names":[],"mappings":""}

package/dist/lib/__test__/template.test.js

@@ -0,0 +1,96 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const template_1 = require("../template");
+const tokenizer_1 = require("../tokenizer"); // import paths as required
+const token_generator_1 = require("../token-generator");
+class MockTokenGenerator extends token_generator_1.AbstractTokenGenerator {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    generateToken(prompt, logit_bias) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return '<TOK>';
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    generateString(prompt, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return 'generated';
+        });
+    }
+}
+describe('TemplateProcessor', () => {
+    let tokenizer;
+    let generator;
+    let templateProcessor;
+    beforeEach(() => {
+        tokenizer = new tokenizer_1.LLaMATokenizer();
+        generator = new MockTokenGenerator();
+        templateProcessor = new template_1.TemplateProcessor(tokenizer, generator);
+    });
+    describe('processTemplate', () => {
+        it('should process template with GEN method correctly', () => __awaiter(void 0, void 0, void 0, function* () {
+            const spyGenerateString = jest.spyOn(generator, 'generateString');
+            const result = yield templateProcessor.processTemplate('Hello, {{user}}. The weather is {{GEN weather}}', new Map([['user', 'Hina']]));
+            expect(spyGenerateString).toHaveBeenCalledWith('Hello, Hina. The weather is ', {});
+            expect(result.get('weather')).toEqual('generated');
+        }));
+        it('should process template with GEN method and stop correctly', () => __awaiter(void 0, void 0, void 0, function* () {
+            const spyGenerateString = jest.spyOn(generator, 'generateString');
+            const result = yield templateProcessor.processTemplate('Hello, {{user}}. The weather is {{GEN weather stop=.}}', new Map([['user', 'Hina']]));
+            expect(spyGenerateString).toHaveBeenCalledWith('Hello, Hina. The weather is ', { stop: '.' });
+            expect(result.get('weather')).toEqual('generated');
+        }));
+        it('should process template with GEN method and temperature and repetition_penalty and stop correctly', () => __awaiter(void 0, void 0, void 0, function* () {
+            const spyGenerateString = jest.spyOn(generator, 'generateString');
+            const result = yield templateProcessor.processTemplate('Hello, {{user}}. The weather is {{GEN weather temperature=0.5 repetition_penalty=1 stop=.}}', new Map([['user', 'Hina']]));
+            expect(spyGenerateString).toHaveBeenCalledWith('Hello, Hina. The weather is ', { temperature: '0.5', repetition_penalty: '1', stop: '.' });
+            expect(result.get('weather')).toEqual('generated');
+        }));
+        it('should process template with SEL method correctly', () => __awaiter(void 0, void 0, void 0, function* () {
+            // 1153 = " ra"
+            const spyGenerateToken = jest.spyOn(generator, 'generateToken').mockReturnValue(new Promise((resolve) => resolve(" ra")));
+            const result = yield templateProcessor.processTemplate('Hello, {{user}}. The weather is{{SEL weather options=weatherOptions}}', new Map([
+                ['user', 'Hina'],
+                ['weatherOptions', [' sunny', ' rainy', ' cloudy']]
+            ]));
+            expect(spyGenerateToken).toHaveBeenCalledWith('Hello, Hina. The weather is', {
+                '6575': 100,
+                '1153': 100,
+                '9570': 100
+            });
+            expect(result.get('weather')).toEqual(' rainy');
+        }));
+        it('should process template with SEL method in a JSON correctly', () => __awaiter(void 0, void 0, void 0, function* () {
+            // 29879 = "s"
+            const spyGenerateToken = jest.spyOn(generator, 'generateToken').mockReturnValue(new Promise((resolve) => resolve("s")));
+            const spyGenerateString = jest.spyOn(generator, 'generateString').mockReturnValue(new Promise((resolve) => resolve("wizard")));
+            const result = yield templateProcessor.processTemplate(`RPG Game Character specification
+        {
+          "name": "{{name}}",
+          "job": "{{GEN job stop=",}}",
+          "weapon": "{{SEL weapon options=valid_weapons}}",
+        }`, new Map([
+                ['name', 'Rudeus'],
+                ['valid_weapons', ["axe", "mace", "sword", "bow", "crossbow"]],
+            ]));
+            expect(spyGenerateString).toHaveBeenCalledWith('RPG Game Character specification\n        {\n          "name": "Rudeus",\n          "job": "', { stop: '",' });
+            expect(spyGenerateToken).toHaveBeenCalledWith('RPG Game Character specification\n        {\n          "name": "Rudeus",\n          "job": "wizard",\n          "weapon": "', {
+                '29879': 100,
+                '1165': 100,
+                '655': 100,
+                '17729': 100,
+                '19128': 100,
+            });
+            expect(result.get('weapon')).toEqual('sword');
+            expect(result.get('job')).toEqual('wizard');
+        }));
+    });
+});

package/dist/lib/_llama-tokenizer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MIT LICENSE
+ *
+ * Copyright 2023 belladore.ai
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ */
+export interface LLaMATokenizer {
+    encode: (text: string, add_bos_token?: boolean, add_preceding_space?: boolean, log_performance?: boolean) => number[];
+    decode: (tokenIds: number[], add_bos_token?: boolean, add_preceding_space?: boolean) => string;
+}
+declare const llamaTokenizer: LLaMATokenizer;
+export default llamaTokenizer;
+//# sourceMappingURL=_llama-tokenizer.d.ts.map

package/dist/lib/_llama-tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_llama-tokenizer.d.ts","sourceRoot":"","sources":["../../src/lib/_llama-tokenizer.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,CACJ,IAAI,EAAE,MAAM,EACZ,aAAa,CAAC,EAAE,OAAO,EACvB,mBAAmB,CAAC,EAAE,OAAO,EAC7B,eAAe,CAAC,EAAE,OAAO,KACxB,MAAM,EAAE,CAAC;IACd,MAAM,EAAE,CACJ,QAAQ,EAAE,MAAM,EAAE,EAClB,aAAa,CAAC,EAAE,OAAO,EACvB,mBAAmB,CAAC,EAAE,OAAO,KAC5B,MAAM,CAAA;CACZ;AAED,QAAA,MAAM,cAAc,EAAE,cAAmB,CAAA;AA6czC,eAAe,cAAc,CAAA"}