@fluidframework/ai-collab 2.10.0-306579

package/lib/implicit-strategy/utils.js

@@ -0,0 +1,43 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { NodeKind } from "@fluidframework/tree";
+/**
+ * Checks if the given object is an {@link TreeMapNode}.
+ */
+export function isTreeMapNode(obj) {
+    if (typeof obj === "object" && obj !== null) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        const maybeNodeKind = Object.getPrototypeOf(obj)?.constructor?.kind;
+        return maybeNodeKind === NodeKind.Map;
+    }
+    return false;
+}
+/**
+ * Checks if the given object is an {@link TreeArrayNode}.
+ */
+export function isTreeArrayNode(obj) {
+    if (typeof obj === "object" && obj !== null) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        const maybeNodeKind = Object.getPrototypeOf(obj)?.constructor?.kind;
+        return maybeNodeKind === NodeKind.Array;
+    }
+    return false;
+}
+/**
+ * Traverses the provided {@link ObjectPath} on the provided Shared Tree or JSON object and returns the value at the end of the path.
+ *
+ * @alpha
+ */
+export function sharedTreeTraverse(jsonObject, path) {
+    let current = jsonObject;
+    for (const key of path) {
+        if (current === undefined || current === null) {
+            return undefined;
+        }
+        current = isTreeMapNode(current) ? current.get(key) : current[key];
+    }
+    return current;
+}
+//# sourceMappingURL=utils.js.map

package/lib/implicit-strategy/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/implicit-strategy/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAwC,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAItF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC7C,sEAAsE;QACtE,MAAM,aAAa,GAAY,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC;QAC7E,OAAO,aAAa,KAAK,QAAQ,CAAC,GAAG,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC3C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC7C,sEAAsE;QACtE,MAAM,aAAa,GAAY,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC;QAC7E,OAAO,aAAa,KAAK,QAAQ,CAAC,KAAK,CAAC;IACzC,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CACjC,UAAiE,EACjE,IAAgB;IAEhB,IAAI,OAAO,GAAY,UAAU,CAAC;IAElC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC/C,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAa,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO,OAAY,CAAC;AACrB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { type TreeMapNode, type TreeArrayNode, NodeKind } from \"@fluidframework/tree\";\n\nimport type { ObjectPath } from \"./sharedTreeDiff.js\";\n\n/**\n * Checks if the given object is an {@link TreeMapNode}.\n */\nexport function isTreeMapNode(obj: unknown): obj is TreeMapNode {\n\tif (typeof obj === \"object\" && obj !== null) {\n\t\t// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access\n\t\tconst maybeNodeKind: unknown = Object.getPrototypeOf(obj)?.constructor?.kind;\n\t\treturn maybeNodeKind === NodeKind.Map;\n\t}\n\treturn false;\n}\n\n/**\n * Checks if the given object is an {@link TreeArrayNode}.\n */\nexport function isTreeArrayNode(obj: unknown): obj is TreeArrayNode {\n\tif (typeof obj === \"object\" && obj !== null) {\n\t\t// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access\n\t\tconst maybeNodeKind: unknown = Object.getPrototypeOf(obj)?.constructor?.kind;\n\t\treturn maybeNodeKind === NodeKind.Array;\n\t}\n\treturn false;\n}\n\n/**\n * Traverses the provided {@link ObjectPath} on the provided Shared Tree or JSON object and returns the value at the end of the path.\n *\n * @alpha\n */\nexport function sharedTreeTraverse<T = unknown>(\n\tjsonObject: TreeMapNode | TreeArrayNode | Record<string, unknown>,\n\tpath: ObjectPath,\n): T | undefined {\n\tlet current: unknown = jsonObject;\n\n\tfor (const key of path) {\n\t\tif (current === undefined || current === null) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tcurrent = isTreeMapNode(current) ? current.get(key as string) : current[key];\n\t}\n\n\treturn current as T;\n}\n"]}

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Experimental package for utilities that enable/simplify interaction with LLMs for apps based on SharedTree.
+ *
+ * See {@link https://github.com/microsoft/FluidFramework/tree/main/packages/framework/ai-collab#readme | README.md }
+ * for an overview of the package.
+ *
+ * @packageDocumentation
+ */
+export { type DifferenceCreate, type DifferenceChange, type DifferenceMove, type DifferenceRemove, type Difference, type ObjectPath, type Options, sharedTreeDiff, createMergableIdDiffSeries, createMergableDiffSeries, SharedTreeBranchManager, sharedTreeTraverse, } from "./implicit-strategy/index.js";
+export { type AiCollabOptions, type AiCollabSuccessResponse, type AiCollabErrorResponse, type TokenUsage, type TokenLimits, type OpenAiClientOptions, } from "./aiCollabApi.js";
+export { aiCollab } from "./aiCollab.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,cAAc,EACd,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,GACxB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/lib/index.js

@@ -0,0 +1,15 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Experimental package for utilities that enable/simplify interaction with LLMs for apps based on SharedTree.
+ *
+ * See {@link https://github.com/microsoft/FluidFramework/tree/main/packages/framework/ai-collab#readme | README.md }
+ * for an overview of the package.
+ *
+ * @packageDocumentation
+ */
+export { sharedTreeDiff, createMergableIdDiffSeries, createMergableDiffSeries, SharedTreeBranchManager, sharedTreeTraverse, } from "./implicit-strategy/index.js";
+export { aiCollab } from "./aiCollab.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAQN,cAAc,EACd,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AAWtC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Experimental package for utilities that enable/simplify interaction with LLMs for apps based on SharedTree.\n *\n * See {@link https://github.com/microsoft/FluidFramework/tree/main/packages/framework/ai-collab#readme | README.md }\n * for an overview of the package.\n *\n * @packageDocumentation\n */\n\nexport {\n\ttype DifferenceCreate,\n\ttype DifferenceChange,\n\ttype DifferenceMove,\n\ttype DifferenceRemove,\n\ttype Difference,\n\ttype ObjectPath,\n\ttype Options,\n\tsharedTreeDiff,\n\tcreateMergableIdDiffSeries,\n\tcreateMergableDiffSeries,\n\tSharedTreeBranchManager,\n\tsharedTreeTraverse,\n} from \"./implicit-strategy/index.js\";\n\nexport {\n\ttype AiCollabOptions,\n\ttype AiCollabSuccessResponse,\n\ttype AiCollabErrorResponse,\n\ttype TokenUsage,\n\ttype TokenLimits,\n\ttype OpenAiClientOptions,\n} from \"./aiCollabApi.js\";\n\nexport { aiCollab } from \"./aiCollab.js\";\n"]}

package/lib/public.d.ts

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluid-tools/build-cli.
+ */
+
+/**
+ * Experimental package for utilities that enable/simplify interaction with LLMs for apps based on SharedTree.
+ *
+ * See {@link https://github.com/microsoft/FluidFramework/tree/main/packages/framework/ai-collab#readme | README.md }
+ * for an overview of the package.
+ *
+ * @packageDocumentation
+ */export {}
+

package/lib/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.47.8"
+    }
+  ]
+}

package/mocharc.cjs

@@ -0,0 +1,14 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+"use strict";
+
+const getFluidTestMochaConfig = require("@fluid-internal/mocha-test-setup/mocharc-common");
+
+const packageDir = __dirname;
+const config = getFluidTestMochaConfig(packageDir);
+config.spec = process.env.MOCHA_SPEC ?? "lib/test/**/*.spec.js";
+
+module.exports = config;

package/package.json

@@ -0,0 +1,165 @@
+{
+  "name": "@fluidframework/ai-collab",
+  "version": "2.10.0-306579",
+  "description": "Experimental package to simplify integrating AI into Fluid-based applications",
+  "homepage": "https://fluidframework.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/FluidFramework.git",
+    "directory": "packages/framework/ai-collab"
+  },
+  "license": "MIT",
+  "author": "Microsoft and contributors",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/public.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/public.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./alpha": {
+      "import": {
+        "types": "./lib/alpha.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/alpha.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/public.d.ts",
+  "c8": {
+    "all": true,
+    "cache-dir": "nyc/.cache",
+    "exclude": [
+      "src/test/**/*.*ts",
+      "dist/test/**/*.*js",
+      "lib/test/**/*.*js"
+    ],
+    "exclude-after-remap": false,
+    "include": [
+      "src/**/*.*ts",
+      "dist/**/*.*js",
+      "lib/**/*.*js"
+    ],
+    "report-dir": "nyc/report",
+    "reporter": [
+      "cobertura",
+      "html",
+      "text"
+    ],
+    "temp-directory": "nyc/.nyc_output"
+  },
+  "dependencies": {
+    "@fluidframework/core-utils": "2.10.0-306579",
+    "@fluidframework/runtime-utils": "2.10.0-306579",
+    "@fluidframework/telemetry-utils": "2.10.0-306579",
+    "@fluidframework/tree": "2.10.0-306579",
+    "openai": "^4.67.3",
+    "typechat": "^0.1.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.16.4",
+    "@biomejs/biome": "~1.9.3",
+    "@fluid-internal/mocha-test-setup": "2.10.0-306579",
+    "@fluid-tools/build-cli": "^0.50.0",
+    "@fluidframework/build-common": "^2.0.3",
+    "@fluidframework/build-tools": "^0.50.0",
+    "@fluidframework/eslint-config-fluid": "^5.4.0",
+    "@fluidframework/id-compressor": "2.10.0-306579",
+    "@fluidframework/runtime-utils": "2.10.0-306579",
+    "@fluidframework/test-runtime-utils": "2.10.0-306579",
+    "@microsoft/api-extractor": "7.47.8",
+    "@types/mocha": "^9.1.1",
+    "@types/node": "^18.19.0",
+    "c8": "^8.0.1",
+    "concurrently": "^8.2.1",
+    "copyfiles": "^2.4.1",
+    "cross-env": "^7.0.3",
+    "eslint": "~8.55.0",
+    "eslint-config-prettier": "~9.0.0",
+    "mocha": "^10.2.0",
+    "mocha-json-output-reporter": "^2.0.1",
+    "mocha-multi-reporters": "^1.5.1",
+    "prettier": "~3.0.3",
+    "rimraf": "^4.4.0",
+    "typescript": "~5.4.5"
+  },
+  "fluidBuild": {
+    "tasks": {
+      "build:esnext": [
+        "...",
+        "typetests:gen"
+      ],
+      "tsc": [
+        "...",
+        "typetests:gen"
+      ]
+    }
+  },
+  "typeValidation": {
+    "disabled": true,
+    "broken": {},
+    "entrypoint": "internal"
+  },
+  "scripts": {
+    "api": "fluid-build . --task api",
+    "api-extractor:commonjs": "flub generate entrypoints --outDir ./dist",
+    "api-extractor:esnext": "flub generate entrypoints --outDir ./lib --node10TypeCompat",
+    "build": "fluid-build . --task build",
+    "build:commonjs": "fluid-build . --task commonjs",
+    "build:compile": "fluid-build . --task compile",
+    "build:docs": "api-extractor run --local",
+    "build:esnext": "tsc --project ./tsconfig.json",
+    "build:test": "npm run build:test:esm && npm run build:test:cjs",
+    "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json",
+    "build:test:esm": "tsc --project ./src/test/tsconfig.json",
+    "check:are-the-types-wrong": "echo skip per issue #112 - node10 requirement: attw --pack .",
+    "check:biome": "biome check .",
+    "check:exports": "concurrently \"npm:check:exports:*\"",
+    "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
+    "check:exports:cjs:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.cjs.json",
+    "check:exports:cjs:index": "api-extractor run --config api-extractor/api-extractor-lint-index.cjs.json",
+    "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json",
+    "check:exports:esm:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.esm.json",
+    "check:exports:esm:index": "api-extractor run --config api-extractor/api-extractor-lint-index.esm.json",
+    "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
+    "check:format": "npm run check:biome",
+    "ci:build:docs": "api-extractor run",
+    "clean": "rimraf --glob dist lib \"*.d.ts\" \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
+    "eslint": "eslint --format stylish src",
+    "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
+    "format": "npm run format:biome",
+    "format:biome": "biome check . --write",
+    "lint": "fluid-build . --task lint",
+    "lint:fix": "fluid-build . --task eslint:fix --task format",
+    "test": "npm run test:mocha",
+    "test:coverage": "c8 npm test",
+    "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead - npm run test:mocha:cjs",
+    "test:mocha:cjs": "mocha --recursive \"dist/test/**/*.spec.js\"",
+    "test:mocha:esm": "mocha --recursive \"lib/test/**/*.spec.js\"",
+    "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
+    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
+    "typetests:gen": "flub generate typetests --dir . -v",
+    "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"
+  }
+}

package/prettier.config.cjs

@@ -0,0 +1,8 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+module.exports = {
+	...require("@fluidframework/build-common/prettier.config.cjs"),
+};

package/src/aiCollab.ts

@@ -0,0 +1,86 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	AiCollabErrorResponse,
+	AiCollabOptions,
+	AiCollabSuccessResponse,
+} from "./aiCollabApi.js";
+import { generateTreeEdits } from "./explicit-strategy/index.js";
+
+/**
+ * Calls an LLM to modify the provided SharedTree in a series of real time edits based on the provided users prompt input.
+ * @remarks This function is designed to be a controlled "all-in-one" function that handles the entire process of calling an LLM to collaborative edit a SharedTree.
+ *
+ * @example
+ * ```typescript
+ * import {
+ * 	SchemaFactory,
+ * 	TreeViewConfiguration,
+ * 	type TreeView
+ * } from "@fluidframework/tree";
+ *
+ * const sf = new SchemaFactory("todo-app");
+ *
+ * class TodoTask extends sf.object("TodoTask", {
+ * 	title: sf.string,
+ * 	description: sf.string,
+ * }) {}
+ *
+ * class TodoAppState extends sf.object("TodoAppState", {
+ * 	tasks: sf.array(TodoTask),
+ * }) {}
+ *
+ * // Initialize your SharedTree
+ * const treeView: TreeView = tree.viewWith(new TreeViewConfiguration({ schema: TodoAppState }));
+ * treeView.initialize({ tasks: [] });
+ *
+ * // Collaborate with AI in realtime in just one function call.
+ * const response = await aiCollab({
+ * 		openAI: {
+ * 			client: new OpenAI({
+ * 				apiKey: OPENAI_API_KEY,
+ * 			}),
+ * 			modelName: "gpt-4o",
+ * 		},
+ * 		treeNode: view.root,
+ * 		prompt: {
+ * 			systemRoleContext:
+ * 				"You are an helpful assistant managing a todo list for a user.",
+ * 			userAsk: "Create a set of new todos to plan a vacation to Cancun.",
+ * 		},
+ * 		planningStep: true,
+ * 		finalReviewStep: true,
+ * 		dumpDebugLog: true,
+ * 	});
+ * ```
+ *
+ * @remarks Known Limitiations:
+ * - Root level array nodes are not supported
+ * - Nested arrays are not supported
+ * - Primitive nodes are not supported, e.g. 'string', 'number', 'boolean'
+ * - Your application's Shared Tree schema must have no more than 4 levels of nesting
+ * - Optional nodes are not supported in the Shared Tree schema
+ * - Union types are not supported in the Shared Tree schema
+ * - See README for more details.
+ *
+ * @alpha
+ */
+export async function aiCollab(
+	options: AiCollabOptions,
+): Promise<AiCollabSuccessResponse | AiCollabErrorResponse> {
+	const response = await generateTreeEdits({
+		treeNode: options.treeNode,
+		validator: options.validator,
+		openAI: options.openAI,
+		prompt: options.prompt,
+		limiters: options.limiters,
+		dumpDebugLog: options.dumpDebugLog,
+		planningStep: options.planningStep,
+		finalReviewStep: options.finalReviewStep,
+	});
+
+	return response;
+}

package/src/aiCollabApi.ts

@@ -0,0 +1,184 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { TreeNode } from "@fluidframework/tree";
+// eslint-disable-next-line import/no-named-as-default
+import type OpenAI from "openai";
+
+/**
+ * OpenAI client options for the {@link AiCollabOptions} interface.
+ *
+ * @alpha
+ */
+export interface OpenAiClientOptions {
+	/**
+	 * The OpenAI client to use for the AI collaboration.
+	 */
+	client: OpenAI;
+	/**
+	 * The name of the target OpenAI model to use for the AI collaboration.
+	 */
+	modelName?: string;
+}
+
+/**
+ * Options for the AI collaboration.
+ *
+ * @alpha
+ */
+export interface AiCollabOptions {
+	/**
+	 * The OpenAI client options to use for the LLM based AI collaboration.
+	 */
+	readonly openAI: OpenAiClientOptions;
+	/**
+	 * The specific tree node you want the AI to collaborate on. Pass the root node of your tree if you intend
+	 * for the AI to work on the entire tree.
+	 * @remarks
+	 * - Optional root nodes are not supported
+	 * - Primitive root nodes are not supported
+	 */
+	readonly treeNode: TreeNode;
+	/**
+	 * The prompt context to give the LLM in order to collaborate with your applications data.
+	 */
+	readonly prompt: {
+		/**
+		 * The context to give the LLM about its role in the collaboration.
+		 * @remarks It's highly recommended to give context about your applications data model and the LLM's role in the collaboration.
+		 */
+		readonly systemRoleContext: string;
+		/**
+		 * The request from the users to the LLM.
+		 */
+		readonly userAsk: string;
+	};
+	/**
+	 * Limiters are various optional ways to limit this library's usage of the LLM.
+	 */
+	readonly limiters?: {
+		/**
+		 * An optional AbortController that can be used to abort the AI collaboration while it is still in progress.
+		 */
+		readonly abortController?: AbortController;
+		/**
+		 * The maximum number of sequential errors the LLM can make before aborting the collaboration.
+		 * If the maximum number of sequential errors is reached, the AI collaboration will be aborted and return with the errorMessage 'tooManyErrors'.
+		 * Leaving this undefined will disable this limiter.
+		 */
+		readonly maxSequentialErrors?: number;
+		/**
+		 * The maximum number of model calls the LLM can make before aborting the collaboration.
+		 * If the maximum number of model calls is reached, the AI collaboration will be aborted and return with the errorMessage 'tooManyModelCalls'.
+		 * Leaving this undefined will disable this limiter.
+		 */
+		readonly maxModelCalls?: number;
+		/**
+		 * The maximum token usage limits for the LLM.
+		 * If the LLM exceeds the token limits, the AI collaboration will be aborted and return with the errorMessage 'tokenLimitExceeded'.
+		 * This happens after the first model call's token usage is calculated, meaning that the limits set may be exceeded by a certain amount.
+		 * Leaving this undefined will disable this limiter.
+		 */
+		readonly tokenLimits?: TokenLimits;
+	};
+	/**
+	 * When set to true, the LLM will be asked to first produce a plan, based on the user's ask, before generating any changes to your applications data.
+	 * This can help the LLM produce better results.
+	 * When set to false, the LLM will not be asked to produce a plan.
+	 */
+	readonly planningStep?: boolean;
+	/**
+	 * When set to true, the LLM will be asked to complete a final review of the changes and determine if any additional changes need to be made.
+	 * When set to false, the LLM will not be asked to complete a final review.
+	 */
+	readonly finalReviewStep?: boolean;
+	/**
+	 * An optional validator function that can be used to validate the new content produced by the LLM.
+	 */
+	readonly validator?: (newContent: TreeNode) => void;
+	/**
+	 * When enabled, the library will console.log information useful for debugging the AI collaboration.
+	 */
+	readonly dumpDebugLog?: boolean;
+}
+
+/**
+ * A successful response from the AI collaboration.
+ *
+ * @alpha
+ */
+export interface AiCollabSuccessResponse {
+	/**
+	 * The status of the Ai Collaboration.
+	 * A 'success' status indicates that the AI collaboration was successful at creating changes.
+	 */
+	readonly status: "success";
+	/**
+	 * {@inheritDoc TokenUsage}
+	 */
+	readonly tokensUsed: TokenUsage;
+}
+
+/**
+ * An error response from the AI collaboration.
+ *
+ * @alpha
+ */
+export interface AiCollabErrorResponse {
+	/**
+	 * The status of the Ai Collaboration.
+	 * - A 'partial-failure' status indicates that the AI collaboration was partially successful, but was aborted due to a limiter or other error
+	 * - A "failure" status indicates that the AI collaboration was not successful at creating any changes.
+	 */
+	readonly status: "failure" | "partial-failure";
+	/**
+	 * The type of known error that occured
+	 * - 'tokenLimitExceeded' indicates that the LLM exceeded the token limits set by the user
+	 * - 'tooManyErrors' indicates that the LLM made too many errors in a row
+	 * - 'tooManyModelCalls' indicates that the LLM made too many model calls
+	 * - 'aborted' indicates that the AI collaboration was aborted by the user or a limiter
+	 */
+	readonly errorMessage:
+		| "tokenLimitExceeded"
+		| "tooManyErrors"
+		| "tooManyModelCalls"
+		| "aborted";
+	/**
+	 * {@inheritDoc TokenUsage}
+	 */
+	readonly tokensUsed: TokenUsage;
+}
+
+/**
+ * Total usage of tokens by an LLM.
+ *
+ * @alpha
+ */
+export interface TokenUsage {
+	/**
+	 * The total number of tokens used by the LLM for input.
+	 */
+	inputTokens: number;
+	/**
+	 * The total number of tokens used by the LLM for output.
+	 */
+	outputTokens: number;
+}
+
+/**
+ * Maximum limits for the total tokens that can be used by an llm
+ *
+ * @alpha
+ */
+export interface TokenLimits {
+	/**
+	 * The maximum number of tokens that can be used by the LLM for input.
+	 */
+	readonly inputTokens?: number;
+	/**
+	 * The maximum number of tokens that can be used by the LLM for output.
+	 */
+	readonly outputTokens?: number;
+}