@fluidframework/ai-collab 2.33.2 → 2.40.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @fluidframework/ai-collab
 
+## 2.40.0
+
+Dependency updates only.
+
 ## 2.33.0
 
 Dependency updates only.

package/README.md

@@ -210,6 +210,7 @@ aiCollab({
 All debug events implement the `DebugEvent` interface. Some also implement `EventFlowDebugEvent`, which lets them mark a progress point in a specific logic flow within a given execution of `aiCollab()`.
 
 ### Event flow Overview
+
 To see detailed information about each event, please read their cooresponding [tsdoc](./src/explicit-strategy/debugEvents.ts#L46)
 
 1. **Core Event Loop** - The start and end of a single execution of aiCollab.
@@ -238,10 +239,165 @@ To see detailed information about each event, please read their cooresponding [t
 
 
 ### Using Trace Id's
+
 Debug Events in ai-collab have two different types of trace id's:
 - `traceId`: This field exists on all debug events and can be used to correlate all debug events that happened in a single execution of `aiCollab()`. Sorting the events by timestamp will show the proper chronological order of the events. Note that the events should already be emitted in chronological order.
 - `eventFlowTraceId`: this field exists on all `EventFlowDebugEvents` and can be used to correlate all events from a particular event flow. Additionally all LLM api call events will contain the `eventFlowTraceId` field as well as a `triggeringEventFlowName` so you can link LLM API calls to a particular event flow.
 
+## Edit Differences
+
+`ai-collab` provides an array of `Diff` objects with its response. Each of these objects allows developers to identify tree nodes that have been modified as a result of AI collaboration and visualize them according to their needs.
+
+Every `Diff` will include one or more `NodePaths` representing the nodes affected by a single edit created by the ai agent. A `NodePath` is an array whose items represent segment paths, beginning from the node targeted for modification (at the start of the array) all the way back to the root node passed to the ai-collab function call (at the end of the array), along with an explanation directly from the AI agent as to why it performed an edit.
+
+Let's take a look at some examples for the following SharedTree application schema.
+
+```ts
+import { aiCollab, DebugEvent, Diff } from "@fluidframework/ai-collab/alpha";
+
+const sf = new SchemaFactory("testApp");
+
+class Todo extends sf.object("Todo", {
+	id: sf.identifier,
+	title: string
+	description: string
+}) {}
+
+class TestAppRootObject extends sf.object("TestAppRootObject", {
+	id: sf.identifier,
+	todos: sf.array([Todo]),
+	innerObject: sf.object("InnerObject", {
+		nestedTodos: sf.array([Todo]),
+	}),
+}) {}
+
+const response = aiCollab({
+	openAI: {
+		client: new OpenAI({
+			apiKey: OPENAI_API_KEY,
+		}),
+		modelName: "gpt-4o",
+	},
+	prompt: {
+		systemRoleContext:
+			"You are a manager that is helping out with a project management tool. You have been asked to edit a group of tasks.",
+		userAsk: userAsk,
+	},
+	limiters: {
+		maxModelCalls: 25
+	}
+	planningStep: true,
+	finalReviewStep: true,
+	debugEventLogHandler: (event: DebugEvent) => {console.log(event);}
+});
+
+const diffs: Diff[] = response.diffs;
+```
+
+Each `Diff` will contain one or more `NodePath`s. Each `NodePath` is an array of objects that detail the path from the root node passed to ai-collab, down to the node targeted for editing. The first index in the `NodePath` points to the target node and the last index is always the root node.
+
+Let's look at an example of the Insert Diff.
+
+### Example Insert Diff
+
+The following `InsertDiff` is an example of a `Diff` that would result from an AI agent inserting an object into index 1 of `TestAppRootObject.rootVectors`.
+
+```json
+type: "insert",
+nodePath: [
+		{
+			shortId: -14,
+			schemaIdentifier: "testApp.Todo",
+			parentField: 1,
+		},
+		{
+			shortId: undefined,
+			schemaIdentifier: "testApp.Array<[\"testApp.Todo\"]>",
+			parentField: "todos",
+		},
+		{
+			shortId: -1,
+			schemaIdentifier: "testApp.TestAppRootObject",
+			parentField: "rootFieldKey",
+		},
+	],
+  	aiExplanation: "I need to insert a todo within the todos array",
+  	nodeContent: {
+Using a `Diff`, you can identify the modified node in a number of different ways.
+```
+
+As you can see, the object at the beginning of the `nodePath` array directly points to the newly inserted node, while each subsequent object is the parent of the preceding node, terminating in the root node that was passed to the `ai-collab` function call.
+
+The simplest way is to use the `shortId`, where you can use the following code to identify the newly inserted node within the SharedTree.
+
+> [!NOTE]
+> The `shortId` field will only exist for objects that have a field defined as the `SchemaFactory.identifier` field.
+
+See the above example app schema in this section to see the schema field defined as `sf.identifier`
+
+Let's take a look at another UI example of using an array of Diffs to render changes.
+
+```ts
+import { Tree } from "@fluidframework/tree"
+
+function renderTodoWithDiffs(todo: Todo, Diffs: diff[]) {
+	const modifyDiffs = Diffs.filter((diff): diff is ModifyDiff => diff.type === "modify") ?? [];
+	const matchingModifyDiffs = modifyDiffs.filter(
+		(diff: ModifyDiff) =>
+			// Modify diffs are a field level edit, so the first path will be the field on the target node and the second will be the node itself.diff.nodePath.length > 1 && diff.nodePath[1]?.shortId === Tree.shortId(task),
+		);
+
+	const insertDiffs = Diffs.filter((diff): diff is InsertDiff => diff.type === "insert") ?? [];
+	const matchingInsertDiffs = insertDiffs.filter(
+		(diff: InsertDiff) =>
+			// Insert diffs are a node level edit, so the first path will be the node.
+			diff.nodePath[0]?.shortId === Tree.shortId(task),
+	);
+}
+
+if (insertDiffs.length > 0) {
+	renderNewlyInsertedTodo(todo)
+} else if (modifyDiffs.length > 0) {
+	renderModifiedTodo(todo, modifiedFields)
+} else {
+	renderTodo(todo)
+}
+```
+
+You can also use the `type` and `schemaIdentifier` fields to group related `diff`s.
+
+```ts
+const userAsk: "user-defined prompt for what they're asking the LLM to accomplish",
+const result = aiCollab({
+	openAI: {
+		client: new OpenAI({
+			apiKey: OPENAI_API_KEY,
+		}),
+		modelName: "gpt-4o",
+	},
+	treeNode: view.root,
+	prompt: {
+		systemRoleContext:
+			"You are a manager that is helping out with a project management tool. You have been asked to edit a group of tasks.",
+		userAsk: userAsk,
+	},
+	limiters: {
+		maxModelCalls: 25
+	}
+	planningStep: true,
+	finalReviewStep: true,
+});
+
+const Diffs: diff[] = result.diffs;
+
+const insertDiffs = result.diffs.filter(diff => diff.type === 'insert');
+
+const insertedVectorsDiffs = insertDiffs.filter(diff => diff.path[0]?.schemaIdentifier === TestVector.identifier)
+```
+
+Other `Diff` types follow the same basic structure.
+Read the tsdoc [here](./src/diffTypes.ts) for more info.
+
 
 ## Known Issues & limitations
 

package/api-report/ai-collab.alpha.api.md

@@ -9,6 +9,7 @@ export function aiCollab(options: AiCollabOptions): Promise<AiCollabSuccessRespo
 
 // @alpha
 export interface AiCollabErrorResponse {
+    readonly diffs: readonly Diff[];
     readonly errorMessage: "tokenLimitExceeded" | "tooManyErrors" | "tooManyModelCalls" | "aborted" | "unexpectedError";
     readonly status: "failure" | "partial-failure";
     readonly tokensUsed: TokenUsage;
@@ -36,6 +37,7 @@ export interface AiCollabOptions {
 
 // @alpha
 export interface AiCollabSuccessResponse {
+    readonly diffs: readonly Diff[];
     readonly status: "success";
     readonly tokensUsed: TokenUsage;
 }
@@ -66,6 +68,24 @@ export interface ApplyEditSuccess extends EventFlowDebugEvent {
     eventName: "APPLIED_EDIT_SUCCESS";
 }
 
+// @alpha
+export interface ArrayRangeRemoveDiff extends DiffBase {
+    readonly nodeContents: unknown[];
+    readonly nodePaths: NodePath[];
+    readonly removalType: "remove-array-range";
+    // (undocumented)
+    readonly type: "remove";
+}
+
+// @alpha
+export interface ArraySingleRemoveDiff extends DiffBase {
+    readonly nodeContent: unknown;
+    readonly nodePath: NodePath;
+    readonly removalType: "remove-array-single";
+    // (undocumented)
+    readonly type: "remove";
+}
+
 // @alpha
 export interface CoreEventLoopCompleted extends EventFlowDebugEvent {
     // (undocumented)
@@ -109,6 +129,15 @@ export interface DebugEvent {
 // @alpha
 export type DebugEventLogHandler = <T extends DebugEvent>(event: T) => unknown;
 
+// @alpha
+export type Diff = InsertDiff | ModifyDiff | RemoveDiff | MoveDiff;
+
+// @alpha
+export interface DiffBase {
+    readonly aiExplanation: string;
+    readonly type: string;
+}
+
 // @alpha
 export type Difference = DifferenceCreate | DifferenceRemove | DifferenceChange | DifferenceMove;
 
@@ -227,6 +256,14 @@ export interface GenerateTreeEditStarted extends EventFlowDebugEvent {
     llmPrompt: string;
 }
 
+// @alpha
+export interface InsertDiff extends DiffBase {
+    readonly nodeContent: unknown;
+    readonly nodePath: NodePath;
+    // (undocumented)
+    readonly type: "insert";
+}
+
 // @alpha
 export interface LlmApiCallDebugEvent extends DebugEvent {
     eventFlowTraceId: string;
@@ -245,6 +282,45 @@ export interface LlmApiCallDebugEvent extends DebugEvent {
 // @alpha
 export type LlmTreeEdit = Record<string, unknown>;
 
+// @alpha
+export interface ModifyDiff extends DiffBase {
+    readonly newValue: unknown;
+    readonly nodePath: NodePath;
+    readonly oldValue: unknown;
+    // (undocumented)
+    readonly type: "modify";
+}
+
+// @alpha
+export type MoveDiff = MoveSingleDiff | MoveRangeDiff;
+
+// @alpha
+export interface MoveRangeDiff extends DiffBase {
+    readonly destinationNodePath: NodePath;
+    readonly moveType: "move-range";
+    readonly nodeContents: unknown[];
+    readonly sourceNodePaths: NodePath[];
+    // (undocumented)
+    readonly type: "move";
+}
+
+// @alpha
+export interface MoveSingleDiff extends DiffBase {
+    readonly destinationNodePath: NodePath;
+    readonly moveType: "move-single";
+    readonly nodeContent: unknown;
+    readonly sourceNodePath: NodePath;
+    // (undocumented)
+    readonly type: "move";
+}
+
+// @alpha
+export type NodePath = {
+    readonly shortId: string | number | undefined;
+    readonly schemaIdentifier: string;
+    readonly parentField: string | number;
+}[];
+
 // @alpha
 export type ObjectPath = (string | number)[];
 
@@ -286,6 +362,18 @@ export interface PlanningPromptStarted extends EventFlowDebugEvent {
     eventName: "GENERATE_PLANNING_PROMPT_STARTED";
 }
 
+// @alpha
+export type RemoveDiff = RemoveNodeDiff | ArraySingleRemoveDiff | ArrayRangeRemoveDiff;
+
+// @alpha
+export interface RemoveNodeDiff extends DiffBase {
+    readonly nodeContent: unknown;
+    readonly nodePath: NodePath;
+    readonly removalType: "remove-node";
+    // (undocumented)
+    readonly type: "remove";
+}
+
 // @alpha
 export class SharedTreeBranchManager {
     constructor(params?: {

package/dist/aiCollabApi.d.ts

@@ -4,6 +4,7 @@
  */
 import type { TreeNode } from "@fluidframework/tree";
 import type OpenAI from "openai";
+import type { Diff } from "./diffTypes.js";
 /**
  * Core Debug event type for the ai-collab
  * @alpha
@@ -160,6 +161,10 @@ export interface AiCollabSuccessResponse {
      * {@inheritDoc TokenUsage}
      */
     readonly tokensUsed: TokenUsage;
+    /**
+     * A list of diffs that represent the changes made by the AI collaboration.
+     */
+    readonly diffs: readonly Diff[];
 }
 /**
  * An error response from the AI collaboration.
@@ -186,6 +191,10 @@ export interface AiCollabErrorResponse {
      * {@inheritDoc TokenUsage}
      */
     readonly tokensUsed: TokenUsage;
+    /**
+     * A list of diffs that represent the changes made by the AI collaboration.
+     */
+    readonly diffs: readonly Diff[];
 }
 /**
  * Total usage of tokens by an LLM.

package/dist/aiCollabApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiCollabApi.d.ts","sourceRoot":"","sources":["../src/aiCollabApi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"aiCollabApi.d.ts","sourceRoot":"","sources":["../src/aiCollabApi.ts"],"names":[],"mappings":"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"}

package/dist/aiCollabApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"aiCollabApi.js","sourceRoot":"","sources":["../src/aiCollabApi.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { TreeNode } from \"@fluidframework/tree\";\n// eslint-disable-next-line import/no-named-as-default\nimport type OpenAI from \"openai\";\n\n/**\n * Core Debug event type for the ai-collab\n * @alpha\n */\nexport interface DebugEvent {\n\t/**\n\t * The unique id of the debug event.\n\t */\n\tid: string;\n\t/**\n\t * An id that will be shared across all debug events that originate from the same single execution of ai-collab.\n\t * @remarks This is intended to be used to correlate all debug events that originate from the same execution\n\t */\n\ttraceId: string;\n\t/**\n\t * The name of the debug event.\n\t */\n\teventName: string;\n\t/**\n\t * The date and time at which the debug event was created.\n\t */\n\ttimestamp: string;\n}\n\n/**\n * A Debug event that marks the start or end of a single core logic flow, such as generated tree edits, planning prompt, etc.\n * @alpha\n */\nexport interface EventFlowDebugEvent extends DebugEvent {\n\t/**\n\t * The name of the particular event flow.\n\t */\n\teventFlowName: string;\n\t/**\n\t * The status of the particular event flow.\n\t */\n\teventFlowStatus: \"STARTED\" | \"COMPLETED\" | \"IN_PROGRESS\";\n\t/**\n\t * A unique id that will be shared across all debug events that are part of the same event flow.\n\t */\n\teventFlowTraceId: string;\n}\n\n/**\n * A callback function that can be used to handle debug events that occur during the AI collaboration process.\n * @alpha\n */\nexport type DebugEventLogHandler = <T extends DebugEvent>(event: T) => unknown;\n\n/**\n * OpenAI client options for the {@link AiCollabOptions} interface.\n *\n * @alpha\n */\nexport interface OpenAiClientOptions {\n\t/**\n\t * The OpenAI client to use for the AI collaboration.\n\t */\n\tclient: OpenAI;\n\t/**\n\t * The name of the target OpenAI model to use for the AI collaboration.\n\t */\n\tmodelName?: string;\n}\n\n/**\n * Options for the AI collaboration.\n *\n * @alpha\n */\nexport interface AiCollabOptions {\n\t/**\n\t * The OpenAI client options to use for the LLM based AI collaboration.\n\t */\n\treadonly openAI: OpenAiClientOptions;\n\t/**\n\t * The specific tree node you want the AI to collaborate on. Pass the root node of your tree if you intend\n\t * for the AI to work on the entire tree.\n\t * @remarks\n\t * - Optional root nodes are not supported\n\t * - Primitive root nodes are not supported\n\t */\n\treadonly treeNode: TreeNode;\n\t/**\n\t * The prompt context to give the LLM in order to collaborate with your applications data.\n\t */\n\treadonly prompt: {\n\t\t/**\n\t\t * The context to give the LLM about its role in the collaboration.\n\t\t * @remarks It's highly recommended to give context about your applications data model and the LLM's role in the collaboration.\n\t\t */\n\t\treadonly systemRoleContext: string;\n\t\t/**\n\t\t * The request from the users to the LLM.\n\t\t */\n\t\treadonly userAsk: string;\n\t};\n\t/**\n\t * Limiters are various optional ways to limit this library's usage of the LLM.\n\t */\n\treadonly limiters?: {\n\t\t/**\n\t\t * An optional AbortController that can be used to abort the AI collaboration while it is still in progress.\n\t\t */\n\t\treadonly abortController?: AbortController;\n\t\t/**\n\t\t * The maximum number of sequential errors the LLM can make before aborting the collaboration.\n\t\t * If the maximum number of sequential errors is reached, the AI collaboration will be aborted and return with the errorMessage 'tooManyErrors'.\n\t\t * Leaving this undefined will disable this limiter.\n\t\t */\n\t\treadonly maxSequentialErrors?: number;\n\t\t/**\n\t\t * The maximum number of model calls the LLM can make before aborting the collaboration.\n\t\t * If the maximum number of model calls is reached, the AI collaboration will be aborted and return with the errorMessage 'tooManyModelCalls'.\n\t\t * Leaving this undefined will disable this limiter.\n\t\t */\n\t\treadonly maxModelCalls?: number;\n\t\t/**\n\t\t * The maximum token usage limits for the LLM.\n\t\t * If the LLM exceeds the token limits, the AI collaboration will be aborted and return with the errorMessage 'tokenLimitExceeded'.\n\t\t * This happens after the first model call's token usage is calculated, meaning that the limits set may be exceeded by a certain amount.\n\t\t * Leaving this undefined will disable this limiter.\n\t\t */\n\t\treadonly tokenLimits?: TokenLimits;\n\t};\n\t/**\n\t * 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.\n\t * This can help the LLM produce better results.\n\t * When set to false, the LLM will not be asked to produce a plan.\n\t */\n\treadonly planningStep?: boolean;\n\t/**\n\t * 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.\n\t * When set to false, the LLM will not be asked to complete a final review.\n\t */\n\treadonly finalReviewStep?: boolean;\n\t/**\n\t * An optional validator function that can be used to validate the new content produced by the LLM.\n\t */\n\treadonly validator?: (newContent: TreeNode) => void;\n\t/**\n\t * An optional handler for debug events that occur during the AI collaboration.\n\t */\n\treadonly debugEventLogHandler?: DebugEventLogHandler;\n}\n\n/**\n * A successful response from the AI collaboration.\n *\n * @alpha\n */\nexport interface AiCollabSuccessResponse {\n\t/**\n\t * The status of the Ai Collaboration.\n\t * A 'success' status indicates that the AI collaboration was successful at creating changes.\n\t */\n\treadonly status: \"success\";\n\t/**\n\t * {@inheritDoc TokenUsage}\n\t */\n\treadonly tokensUsed: TokenUsage;\n}\n\n/**\n * An error response from the AI collaboration.\n *\n * @alpha\n */\nexport interface AiCollabErrorResponse {\n\t/**\n\t * The status of the Ai Collaboration.\n\t * - A 'partial-failure' status indicates that the AI collaboration was partially successful, but was aborted due to a limiter or other error\n\t * - A \"failure\" status indicates that the AI collaboration was not successful at creating any changes.\n\t */\n\treadonly status: \"failure\" | \"partial-failure\";\n\t/**\n\t * The type of known error that occured\n\t * - 'tokenLimitExceeded' indicates that the LLM exceeded the token limits set by the user\n\t * - 'tooManyErrors' indicates that the LLM made too many errors in a row\n\t * - 'tooManyModelCalls' indicates that the LLM made too many model calls\n\t * - 'aborted' indicates that the AI collaboration was aborted by the user or a limiter\n\t * - 'unexpectedError' indicates that an unexpected error occured\n\t */\n\treadonly errorMessage:\n\t\t| \"tokenLimitExceeded\"\n\t\t| \"tooManyErrors\"\n\t\t| \"tooManyModelCalls\"\n\t\t| \"aborted\"\n\t\t| \"unexpectedError\";\n\t/**\n\t * {@inheritDoc TokenUsage}\n\t */\n\treadonly tokensUsed: TokenUsage;\n}\n\n/**\n * Total usage of tokens by an LLM.\n *\n * @alpha\n */\nexport interface TokenUsage {\n\t/**\n\t * The total number of tokens used by the LLM for input.\n\t */\n\tinputTokens: number;\n\t/**\n\t * The total number of tokens used by the LLM for output.\n\t */\n\toutputTokens: number;\n}\n\n/**\n * Maximum limits for the total tokens that can be used by an llm\n *\n * @alpha\n */\nexport interface TokenLimits {\n\t/**\n\t * The maximum number of tokens that can be used by the LLM for input.\n\t */\n\treadonly inputTokens?: number;\n\t/**\n\t * The maximum number of tokens that can be used by the LLM for output.\n\t */\n\treadonly outputTokens?: number;\n}\n"]}
+{"version":3,"file":"aiCollabApi.js","sourceRoot":"","sources":["../src/aiCollabApi.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { TreeNode } from \"@fluidframework/tree\";\n// eslint-disable-next-line import/no-named-as-default\nimport type OpenAI from \"openai\";\n\nimport type { Diff } from \"./diffTypes.js\";\n\n/**\n * Core Debug event type for the ai-collab\n * @alpha\n */\nexport interface DebugEvent {\n\t/**\n\t * The unique id of the debug event.\n\t */\n\tid: string;\n\t/**\n\t * An id that will be shared across all debug events that originate from the same single execution of ai-collab.\n\t * @remarks This is intended to be used to correlate all debug events that originate from the same execution\n\t */\n\ttraceId: string;\n\t/**\n\t * The name of the debug event.\n\t */\n\teventName: string;\n\t/**\n\t * The date and time at which the debug event was created.\n\t */\n\ttimestamp: string;\n}\n\n/**\n * A Debug event that marks the start or end of a single core logic flow, such as generated tree edits, planning prompt, etc.\n * @alpha\n */\nexport interface EventFlowDebugEvent extends DebugEvent {\n\t/**\n\t * The name of the particular event flow.\n\t */\n\teventFlowName: string;\n\t/**\n\t * The status of the particular event flow.\n\t */\n\teventFlowStatus: \"STARTED\" | \"COMPLETED\" | \"IN_PROGRESS\";\n\t/**\n\t * A unique id that will be shared across all debug events that are part of the same event flow.\n\t */\n\teventFlowTraceId: string;\n}\n\n/**\n * A callback function that can be used to handle debug events that occur during the AI collaboration process.\n * @alpha\n */\nexport type DebugEventLogHandler = <T extends DebugEvent>(event: T) => unknown;\n\n/**\n * OpenAI client options for the {@link AiCollabOptions} interface.\n *\n * @alpha\n */\nexport interface OpenAiClientOptions {\n\t/**\n\t * The OpenAI client to use for the AI collaboration.\n\t */\n\tclient: OpenAI;\n\t/**\n\t * The name of the target OpenAI model to use for the AI collaboration.\n\t */\n\tmodelName?: string;\n}\n\n/**\n * Options for the AI collaboration.\n *\n * @alpha\n */\nexport interface AiCollabOptions {\n\t/**\n\t * The OpenAI client options to use for the LLM based AI collaboration.\n\t */\n\treadonly openAI: OpenAiClientOptions;\n\t/**\n\t * The specific tree node you want the AI to collaborate on. Pass the root node of your tree if you intend\n\t * for the AI to work on the entire tree.\n\t * @remarks\n\t * - Optional root nodes are not supported\n\t * - Primitive root nodes are not supported\n\t */\n\treadonly treeNode: TreeNode;\n\t/**\n\t * The prompt context to give the LLM in order to collaborate with your applications data.\n\t */\n\treadonly prompt: {\n\t\t/**\n\t\t * The context to give the LLM about its role in the collaboration.\n\t\t * @remarks It's highly recommended to give context about your applications data model and the LLM's role in the collaboration.\n\t\t */\n\t\treadonly systemRoleContext: string;\n\t\t/**\n\t\t * The request from the users to the LLM.\n\t\t */\n\t\treadonly userAsk: string;\n\t};\n\t/**\n\t * Limiters are various optional ways to limit this library's usage of the LLM.\n\t */\n\treadonly limiters?: {\n\t\t/**\n\t\t * An optional AbortController that can be used to abort the AI collaboration while it is still in progress.\n\t\t */\n\t\treadonly abortController?: AbortController;\n\t\t/**\n\t\t * The maximum number of sequential errors the LLM can make before aborting the collaboration.\n\t\t * If the maximum number of sequential errors is reached, the AI collaboration will be aborted and return with the errorMessage 'tooManyErrors'.\n\t\t * Leaving this undefined will disable this limiter.\n\t\t */\n\t\treadonly maxSequentialErrors?: number;\n\t\t/**\n\t\t * The maximum number of model calls the LLM can make before aborting the collaboration.\n\t\t * If the maximum number of model calls is reached, the AI collaboration will be aborted and return with the errorMessage 'tooManyModelCalls'.\n\t\t * Leaving this undefined will disable this limiter.\n\t\t */\n\t\treadonly maxModelCalls?: number;\n\t\t/**\n\t\t * The maximum token usage limits for the LLM.\n\t\t * If the LLM exceeds the token limits, the AI collaboration will be aborted and return with the errorMessage 'tokenLimitExceeded'.\n\t\t * This happens after the first model call's token usage is calculated, meaning that the limits set may be exceeded by a certain amount.\n\t\t * Leaving this undefined will disable this limiter.\n\t\t */\n\t\treadonly tokenLimits?: TokenLimits;\n\t};\n\t/**\n\t * 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.\n\t * This can help the LLM produce better results.\n\t * When set to false, the LLM will not be asked to produce a plan.\n\t */\n\treadonly planningStep?: boolean;\n\t/**\n\t * 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.\n\t * When set to false, the LLM will not be asked to complete a final review.\n\t */\n\treadonly finalReviewStep?: boolean;\n\t/**\n\t * An optional validator function that can be used to validate the new content produced by the LLM.\n\t */\n\treadonly validator?: (newContent: TreeNode) => void;\n\t/**\n\t * An optional handler for debug events that occur during the AI collaboration.\n\t */\n\treadonly debugEventLogHandler?: DebugEventLogHandler;\n}\n\n/**\n * A successful response from the AI collaboration.\n *\n * @alpha\n */\nexport interface AiCollabSuccessResponse {\n\t/**\n\t * The status of the Ai Collaboration.\n\t * A 'success' status indicates that the AI collaboration was successful at creating changes.\n\t */\n\treadonly status: \"success\";\n\t/**\n\t * {@inheritDoc TokenUsage}\n\t */\n\treadonly tokensUsed: TokenUsage;\n\t/**\n\t * A list of diffs that represent the changes made by the AI collaboration.\n\t */\n\treadonly diffs: readonly Diff[];\n}\n\n/**\n * An error response from the AI collaboration.\n *\n * @alpha\n */\nexport interface AiCollabErrorResponse {\n\t/**\n\t * The status of the Ai Collaboration.\n\t * - A 'partial-failure' status indicates that the AI collaboration was partially successful, but was aborted due to a limiter or other error\n\t * - A \"failure\" status indicates that the AI collaboration was not successful at creating any changes.\n\t */\n\treadonly status: \"failure\" | \"partial-failure\";\n\t/**\n\t * The type of known error that occured\n\t * - 'tokenLimitExceeded' indicates that the LLM exceeded the token limits set by the user\n\t * - 'tooManyErrors' indicates that the LLM made too many errors in a row\n\t * - 'tooManyModelCalls' indicates that the LLM made too many model calls\n\t * - 'aborted' indicates that the AI collaboration was aborted by the user or a limiter\n\t * - 'unexpectedError' indicates that an unexpected error occured\n\t */\n\treadonly errorMessage:\n\t\t| \"tokenLimitExceeded\"\n\t\t| \"tooManyErrors\"\n\t\t| \"tooManyModelCalls\"\n\t\t| \"aborted\"\n\t\t| \"unexpectedError\";\n\t/**\n\t * {@inheritDoc TokenUsage}\n\t */\n\treadonly tokensUsed: TokenUsage;\n\t/**\n\t * A list of diffs that represent the changes made by the AI collaboration.\n\t */\n\treadonly diffs: readonly Diff[];\n}\n\n/**\n * Total usage of tokens by an LLM.\n *\n * @alpha\n */\nexport interface TokenUsage {\n\t/**\n\t * The total number of tokens used by the LLM for input.\n\t */\n\tinputTokens: number;\n\t/**\n\t * The total number of tokens used by the LLM for output.\n\t */\n\toutputTokens: number;\n}\n\n/**\n * Maximum limits for the total tokens that can be used by an llm\n *\n * @alpha\n */\nexport interface TokenLimits {\n\t/**\n\t * The maximum number of tokens that can be used by the LLM for input.\n\t */\n\treadonly inputTokens?: number;\n\t/**\n\t * The maximum number of tokens that can be used by the LLM for output.\n\t */\n\treadonly outputTokens?: number;\n}\n"]}

package/dist/alpha.d.ts

@@ -24,10 +24,14 @@ export {
 	AiCollabSuccessResponse, 
 	ApplyEditFailure, 
 	ApplyEditSuccess, 
+	ArrayRangeRemoveDiff, 
+	ArraySingleRemoveDiff, 
 	CoreEventLoopCompleted, 
 	CoreEventLoopStarted, 
 	DebugEvent, 
 	DebugEventLogHandler, 
+	Diff, 
+	DiffBase, 
 	Difference, 
 	DifferenceChange, 
 	DifferenceCreate, 
@@ -40,13 +44,21 @@ export {
 	FinalReviewStarted, 
 	GenerateTreeEditCompleted, 
 	GenerateTreeEditStarted, 
+	InsertDiff, 
 	LlmApiCallDebugEvent, 
 	LlmTreeEdit, 
+	ModifyDiff, 
+	MoveDiff, 
+	MoveRangeDiff, 
+	MoveSingleDiff, 
+	NodePath, 
 	ObjectPath, 
 	OpenAiClientOptions, 
 	Options, 
 	PlanningPromptCompleted, 
 	PlanningPromptStarted, 
+	RemoveDiff, 
+	RemoveNodeDiff, 
 	SharedTreeBranchManager, 
 	TokenLimits, 
 	TokenUsage, 

package/dist/diffTypes.d.ts

@@ -0,0 +1,200 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * A base interface to enforce consistency between all Diff objects.
+ * @remarks This object is not intended to be used directly.
+ * The union type Diff provides a better typescript experience
+ *
+ * @alpha
+ */
+export interface DiffBase {
+    /**
+     * The operation type performed by an ai agent on a SharedTree
+     * @remarks This is intended to be used to correlate the diff with the operation that generated it.
+     */
+    readonly type: string;
+    /**
+     * An explanation from the ai as to why the edit is being made.
+     */
+    readonly aiExplanation: string;
+}
+/**
+ * An object that provides relevant information to visualize a single edit performed by an ai agent on a SharedTree
+ * @alpha
+ */
+export type Diff = InsertDiff | ModifyDiff | RemoveDiff | MoveDiff;
+/**
+ * A path from the root of the tree node passed to ai-collab to a specific node within the tree.
+ * @alpha
+ */
+export type NodePath = {
+    /**
+     * The short id of the node.
+     * @remarks the root tree node and nodes without a defined SchemaFactory.identifier field will not have a short id.
+     */
+    readonly shortId: string | number | undefined;
+    /**
+     * The schema of the node.
+     */
+    readonly schemaIdentifier: string;
+    /**
+     * The field within the parent node that the node is located at.
+     * @remarks
+     * The root node will have a parentField name of 'rootFieldKey'.
+     * Nodes in an array use numbers to represent their index within the array.
+     */
+    readonly parentField: string | number;
+}[];
+/**
+ * An object that describes the insertion of a new node into a tree.
+ * @alpha
+ */
+export interface InsertDiff extends DiffBase {
+    readonly type: "insert";
+    /**
+     * The path from the root node to the newly inserted node.
+     * The last value in the path will be the newly inserted node.
+     * If the newly inserted node is a primitive value, the last value in the path will be the parent array node.
+     */
+    readonly nodePath: NodePath;
+    /**
+     * The content of the newly inserted node.
+     */
+    readonly nodeContent: unknown;
+}
+/**
+ * An object that describes the modification of an existing node on a tree.
+ * @alpha
+ */
+export interface ModifyDiff extends DiffBase {
+    readonly type: "modify";
+    /**
+     * The path from the root node to the ndoe being modified.
+     */
+    readonly nodePath: NodePath;
+    /**
+     * The new value of the node.
+     */
+    readonly newValue: unknown;
+    /**
+     * The old value of the node.
+     */
+    readonly oldValue: unknown;
+}
+/**
+ * An object that describes the removal of one or more nodes from a tree.
+ * @alpha
+ */
+export type RemoveDiff = RemoveNodeDiff | ArraySingleRemoveDiff | ArrayRangeRemoveDiff;
+/**
+ * Details about a node being removed from a field in an object node.
+ * @alpha
+ */
+export interface RemoveNodeDiff extends DiffBase {
+    readonly type: "remove";
+    /**
+     * The type of removal being performed.
+     */
+    readonly removalType: "remove-node";
+    /**
+     * The path from the root of the tree to the node being removed.
+     */
+    readonly nodePath: NodePath;
+    /**
+     * The content of the node being removed.
+     */
+    readonly nodeContent: unknown;
+}
+/**
+ * An object that describes the removal of a single node from an array node.
+ * @alpha
+ */
+export interface ArraySingleRemoveDiff extends DiffBase {
+    readonly type: "remove";
+    /**
+     * The type of removal being performed.
+     */
+    readonly removalType: "remove-array-single";
+    /**
+     * The path from the root of the tree to the node being removed from the array node.
+     */
+    readonly nodePath: NodePath;
+    /**
+     * The content of the node being removed from the array node.
+     */
+    readonly nodeContent: unknown;
+}
+/**
+ * An object that describes the removal of a range of nodes from an array node.
+ * @alpha
+ */
+export interface ArrayRangeRemoveDiff extends DiffBase {
+    readonly type: "remove";
+    /**
+     * The type of removal being performed.
+     */
+    readonly removalType: "remove-array-range";
+    /**
+     * The paths to each node being removed from the array node.
+     */
+    readonly nodePaths: NodePath[];
+    /**
+     * The content of each of the nodes being removed from the array node.
+     */
+    readonly nodeContents: unknown[];
+}
+/**
+ * An object that describes the movement of nodes from one array node to another array node.
+ * @alpha
+ */
+export type MoveDiff = MoveSingleDiff | MoveRangeDiff;
+/**
+ * An object that describes the movement of a single node from one array node to another array node.
+ * @alpha
+ */
+export interface MoveSingleDiff extends DiffBase {
+    readonly type: "move";
+    /**
+     * The type of movement being performed.
+     */
+    readonly moveType: "move-single";
+    /**
+     * The path from the root of the tree to the source node.
+     * The last value in the path will be the node being moved
+     */
+    readonly sourceNodePath: NodePath;
+    /**
+     * The path from the root of the tree to the destination array node.
+     */
+    readonly destinationNodePath: NodePath;
+    /**
+     * The content of the node being moved from the source array node to the destination array node.
+     */
+    readonly nodeContent: unknown;
+}
+/**
+ * An object that describes the movement of a range of nodes from one array node to another array node.
+ * @alpha
+ */
+export interface MoveRangeDiff extends DiffBase {
+    readonly type: "move";
+    /**
+     * The type of movement being performed.
+     */
+    readonly moveType: "move-range";
+    /**
+     * The paths to each node being moved from the source array node.
+     */
+    readonly sourceNodePaths: NodePath[];
+    /**
+     * The path from the root of the tree to the destination array node.
+     */
+    readonly destinationNodePath: NodePath;
+    /**
+     * The content of each of the nodes being moved from the source array node to the destination array node.
+     */
+    readonly nodeContents: unknown[];
+}
+//# sourceMappingURL=diffTypes.d.ts.map

package/dist/diffTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffTypes.d.ts","sourceRoot":"","sources":["../src/diffTypes.ts"],"names":[],"mappings":"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"}

package/dist/diffTypes.js

@@ -0,0 +1,7 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=diffTypes.js.map

package/dist/diffTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffTypes.js","sourceRoot":"","sources":["../src/diffTypes.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A base interface to enforce consistency between all Diff objects.\n * @remarks This object is not intended to be used directly.\n * The union type Diff provides a better typescript experience\n *\n * @alpha\n */\nexport interface DiffBase {\n\t/**\n\t * The operation type performed by an ai agent on a SharedTree\n\t * @remarks This is intended to be used to correlate the diff with the operation that generated it.\n\t */\n\treadonly type: string;\n\t/**\n\t * An explanation from the ai as to why the edit is being made.\n\t */\n\treadonly aiExplanation: string;\n}\n\n/**\n * An object that provides relevant information to visualize a single edit performed by an ai agent on a SharedTree\n * @alpha\n */\nexport type Diff = InsertDiff | ModifyDiff | RemoveDiff | MoveDiff;\n\n/**\n * A path from the root of the tree node passed to ai-collab to a specific node within the tree.\n * @alpha\n */\nexport type NodePath = {\n\t/**\n\t * The short id of the node.\n\t * @remarks the root tree node and nodes without a defined SchemaFactory.identifier field will not have a short id.\n\t */\n\treadonly shortId: string | number | undefined;\n\t/**\n\t * The schema of the node.\n\t */\n\treadonly schemaIdentifier: string;\n\t/**\n\t * The field within the parent node that the node is located at.\n\t * @remarks\n\t * The root node will have a parentField name of 'rootFieldKey'.\n\t * Nodes in an array use numbers to represent their index within the array.\n\t */\n\treadonly parentField: string | number;\n}[];\n\n/**\n * An object that describes the insertion of a new node into a tree.\n * @alpha\n */\nexport interface InsertDiff extends DiffBase {\n\treadonly type: \"insert\";\n\t/**\n\t * The path from the root node to the newly inserted node.\n\t * The last value in the path will be the newly inserted node.\n\t * If the newly inserted node is a primitive value, the last value in the path will be the parent array node.\n\t */\n\treadonly nodePath: NodePath;\n\t/**\n\t * The content of the newly inserted node.\n\t */\n\treadonly nodeContent: unknown;\n}\n\n/**\n * An object that describes the modification of an existing node on a tree.\n * @alpha\n */\nexport interface ModifyDiff extends DiffBase {\n\treadonly type: \"modify\";\n\t/**\n\t * The path from the root node to the ndoe being modified.\n\t */\n\treadonly nodePath: NodePath;\n\t/**\n\t * The new value of the node.\n\t */\n\treadonly newValue: unknown;\n\t/**\n\t * The old value of the node.\n\t */\n\treadonly oldValue: unknown;\n}\n\n/**\n * An object that describes the removal of one or more nodes from a tree.\n * @alpha\n */\nexport type RemoveDiff = RemoveNodeDiff | ArraySingleRemoveDiff | ArrayRangeRemoveDiff;\n\n/**\n * Details about a node being removed from a field in an object node.\n * @alpha\n */\nexport interface RemoveNodeDiff extends DiffBase {\n\treadonly type: \"remove\";\n\t/**\n\t * The type of removal being performed.\n\t */\n\treadonly removalType: \"remove-node\";\n\t/**\n\t * The path from the root of the tree to the node being removed.\n\t */\n\treadonly nodePath: NodePath;\n\t/**\n\t * The content of the node being removed.\n\t */\n\treadonly nodeContent: unknown;\n}\n\n/**\n * An object that describes the removal of a single node from an array node.\n * @alpha\n */\nexport interface ArraySingleRemoveDiff extends DiffBase {\n\treadonly type: \"remove\";\n\t/**\n\t * The type of removal being performed.\n\t */\n\treadonly removalType: \"remove-array-single\";\n\t/**\n\t * The path from the root of the tree to the node being removed from the array node.\n\t */\n\treadonly nodePath: NodePath;\n\t/**\n\t * The content of the node being removed from the array node.\n\t */\n\treadonly nodeContent: unknown;\n}\n\n/**\n * An object that describes the removal of a range of nodes from an array node.\n * @alpha\n */\nexport interface ArrayRangeRemoveDiff extends DiffBase {\n\treadonly type: \"remove\";\n\t/**\n\t * The type of removal being performed.\n\t */\n\treadonly removalType: \"remove-array-range\";\n\t/**\n\t * The paths to each node being removed from the array node.\n\t */\n\treadonly nodePaths: NodePath[];\n\t/**\n\t * The content of each of the nodes being removed from the array node.\n\t */\n\treadonly nodeContents: unknown[];\n}\n\n/**\n * An object that describes the movement of nodes from one array node to another array node.\n * @alpha\n */\nexport type MoveDiff = MoveSingleDiff | MoveRangeDiff;\n\n/**\n * An object that describes the movement of a single node from one array node to another array node.\n * @alpha\n */\nexport interface MoveSingleDiff extends DiffBase {\n\treadonly type: \"move\";\n\t/**\n\t * The type of movement being performed.\n\t */\n\treadonly moveType: \"move-single\";\n\t/**\n\t * The path from the root of the tree to the source node.\n\t * The last value in the path will be the node being moved\n\t */\n\treadonly sourceNodePath: NodePath;\n\t/**\n\t * The path from the root of the tree to the destination array node.\n\t */\n\treadonly destinationNodePath: NodePath;\n\t/**\n\t * The content of the node being moved from the source array node to the destination array node.\n\t */\n\treadonly nodeContent: unknown;\n}\n\n/**\n * An object that describes the movement of a range of nodes from one array node to another array node.\n * @alpha\n */\nexport interface MoveRangeDiff extends DiffBase {\n\treadonly type: \"move\";\n\t/**\n\t * The type of movement being performed.\n\t */\n\treadonly moveType: \"move-range\";\n\t/**\n\t * The paths to each node being moved from the source array node.\n\t */\n\treadonly sourceNodePaths: NodePath[];\n\t/**\n\t * The path from the root of the tree to the destination array node.\n\t */\n\treadonly destinationNodePath: NodePath;\n\t/**\n\t * The content of each of the nodes being moved from the source array node to the destination array node.\n\t */\n\treadonly nodeContents: unknown[];\n}\n"]}