aimyapi 0.1.0

package/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "useTabs": true
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 WhiteNoise
+
+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.

package/README.md

@@ -0,0 +1,197 @@
+# AI My API
+
+Build AI assistants that use your API's and respond to natural language queries by writing small programs that are executed in a [QuickJS](https://github.com/justjake/quickjs-emscripten) sandbox.
+AIMyAPI writes the glue between your various API functions unlocking new functionality without having to write any code. With the right building blocks, AIMyAPI can even invent new functionality you didn't originally plan for - 
+for example, being able to sort or filter your data in new ways, email or text yourself results, or combine the results of different operations and API's.
+
+Uses the OpenAI API and requires an API key.
+
+## Quickstart
+Simply define your strongly-typed typescript API:
+
+`sales_api.ts`
+```
+// Sales data for each month, per business unit
+export interface SalesData {
+    sales: number;
+    month: number;  // 1...12
+    year: number;
+    businessUnit: "Advertising" | "Hardware" | "Software";
+}
+
+export interface APIInterface {
+    sendEmail(to: string, subject: string, body: string): Promise<void>;
+
+    getSalesData(): SalesData[];
+    // Returns an array of sales data.
+
+    print(text: string): void;
+    // Prints the specified text to the user.
+
+    delay(milliseconds: number): Promise<void>;
+    // waits for the specified number of milliseconds before resolving the promise.
+};
+
+// Global object you will use for accessing the APIInterface
+declare global {
+    var api: APIInterface;
+}
+
+```
+
+Implement it:
+```
+export class API implements APIInterface {
+
+    sendEmail(to: string, subject: string, body: string): Promise<void> {
+    ...
+```
+
+Instantiate your api and AIMyAPI. AIMyAPI will wrap your API so that it can be called from within the QuickJS sandbox.
+
+```
+const api = new API();
+
+const aimyapi = await AIMyAPI.createWithAPI({
+    apiObject: api,
+    apiExports: APIExports,
+    apiDefFilePath: path.join(__dirname, "./sales_api.ts"),
+    apiDocsPath: path.join(__dirname, "./sales_api.md"),
+})
+```
+
+And now you can make requests against the API in natural language.
+Any code generated by the LLM will be run within the sandbox. The LLM will ONLY have access to functions provided within your API and cannot use javascript to make http requests etc.
+
+```
+await aimyapi.processRequest("Which business unit had the highest sales in 2020?");
+```
+
+This would produce the following code generated by the LLM prompt, which is run in the sandbox and makes calls on your API object:
+
+```
+import * as ApiDefs from './api.ts'
+(async() => {
+    try {
+        let salesData = api.getSalesData();
+        let maxSales = 0;
+        let businessUnitWithMaxSales = "";
+        for (let i = 0; i < salesData.length; i++) {
+            if (salesData[i].year === 2020 && salesData[i].sales > maxSales) {
+                maxSales = salesData[i].sales;
+                businessUnitWithMaxSales = salesData[i].businessUnit;
+            }
+        }
+        api.print(\`The business unit with the highest sales in 2020 was ${businessUnitWithMaxSales}.\`);
+    } catch(e) {
+        console.error(e);
+    }
+})();
+```
+
+This example does not take advantage of the chat history and treats every request as a fresh chat. See `example2` for a more complex example that uses the chat history.
+
+APIs should be kept simple and understandable. If you have a complicated API you may want to write a facade for it.
+
+## Advantages and disadvantages of generating code
+
+Currently there is a lot of hype around "agents" - while agents are extremely cool they have a couple drawbacks vs. the code generation approach that AIMyAPI uses to do some of the same things.
+
+**Advantages of AIMyAPI over the Agent (haystack) approach:**
+
+- Open AI's LLMs today are already really good at writing code, but not necessarily trained on the 'haystack' approach.
+- Data from your API can be kept private as long as you don't add it to the chat history or the prompt. The LLM is writing the operations to manipulate the data but doesn't need to see the data itself to do that.
+- Writing code means that AIMyAPI can do math and algorithms out of the box - something LLMs by themselves struggle at. For instance, asking it to do a simple calculation will result in it writing code to do the calculation. Agents can do this using 'tools', but that means you need to do the work to implement and explain these tools wheras they come built-in in a programming language.
+- Agents typically only do one thing at a time and require several OpenAI API calls to do a single loop. AIMyAPI can write an entire program that does several things in one shot.
+
+
+**Disadvantages:**
+
+- This is not an iterative approach: AIMyAPI must have a full understanding of the problem and the API in order write code against it. 
+- It is not currently set up to be able to troubleshoot or fix it's own code (this may be possible)
+- Limits on the context for OpenAI's LLMs mean you can't have a super big API (maybe GPT4 will make this a non-issue). 
+
+## installation
+
+```
+npm install
+```
+
+create a .env file in the root of your project
+add your open ai key:
+```
+OPENAI_API_KEY=XXXXXXXX
+```
+
+## Examples
+
+A simple api example where the LLM allows you to ask questions and compute things about a dataset
+```
+npm run example1
+```
+
+A more complex food ordering example which incorporates chat history
+
+```
+npm run example2
+```
+
+Interactive ordering example (same api as example2)
+
+```
+npm run example3
+```
+
+## Providing examples
+
+Providing examples is super important.
+We recommend that you instruct the LLM to return a self executing async function enclosed in \`\`\` with no other commentary. See the `example/ordering_api.md` for reference.
+It's recommended that you provide at least one example and no other commentary from the assistant, otherwise the LLM's responses will vary pretty widely and probably be unusable.
+GPT3.5-turbo also has tendency to respond in words even after being instructed to respond only with code. Examples help alleviate this problem.
+
+**Sample example**:
+
+```
+Examples of how you should respond:
+
+user: How are you today?
+
+assistant:
+\`\`\`
+import * as ApiDefs from './api.ts'
+(async() {
+    try {
+        api.print("I'm great, thanks for asking!");
+    } catch(e) {
+        console.error(e);
+    }
+})();
+\`\`\`
+```
+
+Aside from the code generation piece, documenting your API with clearly named functions and comments is important so that the LLM understands how it can be used. A big part of using AIMyAPI is testing out usecases and looking at the code that is generated. Problems can be solved by how you name your api, comments in the api, and examples.
+
+## A note about history
+
+If you plan to use history, it is vital that you include the generated code in the history. Otherwise, the LLM will start to think that it doesn't need to generate code.
+
+In example2, note that responses to the user and relevant information is also added to the history so that the LLM can reference it for future queries.
+
+## Safety notes:
+
+- If the user is giving sensitive information in a query, that information isn't private. Refer to the OpenAI policies and plan accordingly.
+- The LLM will do stupid things with your API. You should idiot proof your functions, make sure you sanity check any inputs, etc.
+- Even though we are running the code in sandbox, you should still treat anything coming back from the LLM as untrusted code.
+- You should never give the LLM access to anything mission critical through your API such as live production data or services. 
+- Give as few permissions as is necessary - read only access would be preferred. 
+- Users can trick the LLM to do things that you may not want or intend. Again, access controls are critical. You shouldn't let users access anything they wouldn't normally be able to access via your API.
+- Any 'dangerous' operations should involve some kind of human oversight and approval.
+- A way to audit and rollback anything the LLM does would be wise. The LLM can misunderstand requests due to false assumptions or incomplete information (or trickery). If you allow it to modify your data it could mess things up.
+- By using this library you acknowledge that you take full responsibility for anything that happens as a result of it's use. We cannot gaurantee what will happen based on your instructions to the LLM or how the LLM interprets them etc.
+
+## Thoughts:
+
+Could fine tuning on our API and examples allow us to make the prompt smaller? We can only fine tune on the base models though, so we can't use the cheaper gpt3.5-turbo model.
+Could a smaller / more efficient LLM focused on coding tasks work for this usecase?
+
+

package/dist/example/example1.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example/example1.js

@@ -0,0 +1,52 @@
+"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;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const lib_1 = __importDefault(require("../lib"));
+const sales_api_impl_1 = require("./sales_api_impl");
+const APIExports = __importStar(require("./sales_api"));
+const path_1 = __importDefault(require("path"));
+// Simpler example using no support for chat history; 
+(async () => {
+    const api = new sales_api_impl_1.API();
+    const aimyapi = await lib_1.default.createWithAPI({
+        apiObject: api,
+        apiGlobalName: "api",
+        apiExports: APIExports,
+        apiDefFilePath: path_1.default.join(__dirname, "./sales_api.ts"),
+        apiDocsPath: path_1.default.join(__dirname, "./sales_api.md"),
+        debug: false,
+    });
+    console.log("Print 'hello' three times.");
+    await aimyapi.processRequest("Print 'hello' three times.");
+    console.log("What was our best month in 2020");
+    await aimyapi.processRequest("What was our best month in 2020");
+    console.log("Which business unit had the highest sales in 2020?");
+    await aimyapi.processRequest("Which business unit had the highest sales in 2020?");
+    console.log("Compute the total sales for each month in 2020 then email the top 3 to test@email.com");
+    await aimyapi.processRequest("Compute the total sales for each month in 2020 then email the top 3 to test@email.com");
+})();

package/dist/example/example2.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example/example2.js

@@ -0,0 +1,66 @@
+"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;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const lib_1 = __importDefault(require("../lib"));
+const ordering_api_impl_1 = require("./ordering_api_impl");
+const APIExports = __importStar(require("./ordering_api"));
+const path_1 = __importDefault(require("path"));
+// More complex fast food ordering example that uses chat history.
+// Fast food ordering example.
+(async () => {
+    const api = new ordering_api_impl_1.OrderingAPI();
+    const aimyapi = await lib_1.default.createWithAPI({
+        apiObject: api,
+        apiGlobalName: "orderingApi",
+        apiExports: APIExports,
+        apiDefFilePath: path_1.default.join(__dirname, "./ordering_api.ts"),
+        apiDocsPath: path_1.default.join(__dirname, "./ordering_api.md"),
+        debug: false,
+    });
+    async function runQuery(query) {
+        console.log(`Query: ${query}`);
+        // generate the code for this query
+        const code = await aimyapi.generateCode(query, api._getHistory());
+        api._addMessageToHistory({
+            content: query,
+            role: "user",
+            name: "user",
+        });
+        api._addMessageToHistory({
+            content: '```\n' + code + '\n```',
+            role: "assistant",
+            name: "assistant",
+        });
+        // run the code in the sandbox
+        await aimyapi.runCode(code);
+    }
+    await runQuery("How's the burger here?");
+    await runQuery("I'd like a plain hamburger and a large fries, a pizza with anchovies and a cola. I'd also like a cheese burger with bacon and avocado.");
+    await runQuery("I changed my mind, instead of anchovies, can I get a large gluten free pizza with pineapple instead.");
+    await runQuery("email me the total at myemail@test.com and complete the order");
+})();

package/dist/example/example3.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example/example3.js

@@ -0,0 +1,79 @@
+"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;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const lib_1 = __importDefault(require("../lib"));
+const ordering_api_impl_1 = require("./ordering_api_impl");
+const APIExports = __importStar(require("./ordering_api"));
+const path_1 = __importDefault(require("path"));
+const readline_1 = __importDefault(require("readline"));
+function getInput(query) {
+    const rl = readline_1.default.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise(resolve => rl.question(query, ans => {
+        rl.close();
+        resolve(ans);
+    }));
+}
+// More complex fast food ordering example that uses chat history.
+// Fast food ordering example.
+// Interactive version
+(async () => {
+    const api = new ordering_api_impl_1.OrderingAPI();
+    const aimyapi = await lib_1.default.createWithAPI({
+        apiObject: api,
+        apiGlobalName: "orderingApi",
+        apiExports: APIExports,
+        apiDefFilePath: path_1.default.join(__dirname, "./ordering_api.ts"),
+        apiDocsPath: path_1.default.join(__dirname, "./ordering_api.md"),
+        debug: false,
+    });
+    async function runQuery(query) {
+        console.log(`Query: ${query}`);
+        // generate the code for this query
+        const code = await aimyapi.generateCode(query, api._getHistory());
+        api._addMessageToHistory({
+            content: query,
+            role: "user",
+            name: "user",
+        });
+        api._addMessageToHistory({
+            content: '```\n' + code + '\n```',
+            role: "assistant",
+            name: "assistant",
+        });
+        // run the code in the sandbox
+        await aimyapi.runCode(code);
+    }
+    console.log("Welcome to the restaurant. You can ask to hear the menu or order something. What would you like to do?");
+    while (!api._isCompleted) {
+        const query = await getInput("Your query: ");
+        await runQuery(query);
+    }
+})();

package/dist/example/ordering_api.d.ts

@@ -0,0 +1,36 @@
+export declare const API_VERSION = "1.0.1";
+export interface Customization {
+    name: string;
+    priceAdjustment: number;
+}
+export interface MenuItemBase {
+    orderId?: string;
+    name: string;
+    price: number;
+    description: string;
+    category: string;
+    tags: string[];
+    customizations: Customization[];
+    readonly allowedCustomizations: Customization[];
+    toppings: string[];
+    readonly allowedToppings: string[];
+}
+export declare const Menu: MenuItemBase[];
+export interface OrderingAPIInterface {
+    sendEmail(to: string, subject: string, body: string): Promise<void>;
+    getCurrentOrder(): MenuItemBase[];
+    getItemInOrder(itemOrderId: string): MenuItemBase | undefined;
+    getCustomizationByName(itemName: string, name: string): Customization | undefined;
+    addItemToOrder(itemName: string, customizationNames: string[], toppings: string[]): void;
+    removeItemFromOrder(itemOrderId: string): void;
+    modifyItemInOrder(itemOrderId: string, customizationNames: string[], toppings: string[]): void;
+    getOrderTotal(): number;
+    completeOrder(): void;
+    respondToUser(text: string): void;
+    delay(milliseconds: number): Promise<void>;
+    displayItem(item: MenuItemBase): void;
+    displayOrder(): void;
+}
+declare global {
+    var orderingApi: OrderingAPIInterface;
+}

package/dist/example/ordering_api.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Menu = exports.API_VERSION = void 0;
+exports.API_VERSION = "1.0.1";
+exports.Menu = [
+    {
+        "name": "Pizza",
+        "price": 10.99,
+        "description": "A classic pizza with your choice of toppings.",
+        "category": "Pizza",
+        "tags": [
+            "cheese",
+            "pizza"
+        ],
+        "customizations": [],
+        "allowedCustomizations": [
+            {
+                "name": "Extra Cheese",
+                "priceAdjustment": 1.99
+            },
+            {
+                "name": "Extra Sauce",
+                "priceAdjustment": 0.99
+            },
+            {
+                "name": "Gluten Free Crust",
+                "priceAdjustment": 2.99
+            },
+            {
+                "name": "Large",
+                "priceAdjustment": 3.99
+            }
+        ],
+        "toppings": [],
+        "allowedToppings": [
+            "pepperoni",
+            "sausage",
+            "mushrooms",
+            "onions",
+            "green peppers",
+            "black olives",
+            "green olives",
+            "anchovies",
+            "pineapple",
+            "ham",
+            "bacon",
+            "chicken",
+        ]
+    },
+    {
+        "name": "Hamburger",
+        "price": 8.99,
+        "description": "A classic american hamburger with your choice of toppings. Cheese, lettuce, tomato, and onion are included by default. Other toppings available on request.",
+        "category": "Burgers",
+        "tags": [
+            "hamburger",
+            "burger"
+        ],
+        "customizations": [],
+        "allowedCustomizations": [
+            {
+                "name": "Special sauce",
+                "priceAdjustment": 1.99
+            }
+        ],
+        "toppings": [],
+        "allowedToppings": [
+            "cheese",
+            "lettuce",
+            "tomato",
+            "onion",
+            "pickles",
+            "bacon",
+            "mushrooms",
+            "avocado",
+            "jalapenos",
+        ],
+    },
+    {
+        "name": "Fries",
+        "price": 2.99,
+        "description": "A classic side of fries.",
+        "category": "Sides",
+        "tags": [
+            "fries",
+            "french fries"
+        ],
+        "customizations": [],
+        "allowedCustomizations": [
+            {
+                "name": "Large",
+                "priceAdjustment": 1.99
+            },
+        ],
+        "toppings": [],
+        "allowedToppings": [
+            "old bay",
+        ]
+    },
+    {
+        "name": "Fountain Drink",
+        "price": 1.99,
+        "description": "A classic fountain drink. Choose from Cola, Diet Cola, Dr. Dazzle, or Mountain Rush.",
+        "category": "Drinks",
+        "tags": [
+            "drink",
+            "soda",
+            "fountain drink"
+        ],
+        "customizations": [],
+        "allowedCustomizations": [
+            {
+                "name": "Large",
+                "priceAdjustment": 0.99
+            },
+            {
+                "name": "Extra Ice",
+                "priceAdjustment": 0.99
+            },
+        ],
+        "toppings": [],
+        "allowedToppings": []
+    }
+];
+;

package/dist/example/ordering_api_impl.d.ts

@@ -0,0 +1,23 @@
+import { ChatCompletionRequestMessage } from "openai";
+import { Customization, MenuItemBase, OrderingAPIInterface } from "./ordering_api";
+export declare class OrderingAPI implements OrderingAPIInterface {
+    private _order;
+    private _lastOrderIdNumber;
+    _isCompleted: boolean;
+    private _history;
+    sendEmail(to: string, subject: string, body: string): Promise<void>;
+    respondToUser(text: string): void;
+    delay(milliseconds: number): Promise<void>;
+    getCurrentOrder(): MenuItemBase[];
+    getCustomizationByName(itemName: string, name: string): Customization | undefined;
+    addItemToOrder(itemName: string, customizationNames: string[], toppings: string[]): void;
+    getItemInOrder(itemOrderId: string): MenuItemBase;
+    removeItemFromOrder(itemOrderId: string): void;
+    modifyItemInOrder(itemOrderId: string, customizationNames: string[], toppings: string[]): void;
+    getOrderTotal(): number;
+    completeOrder(): void;
+    displayItem(item: MenuItemBase): void;
+    displayOrder(): void;
+    _addMessageToHistory(message: ChatCompletionRequestMessage): void;
+    _getHistory(): ChatCompletionRequestMessage[];
+}