@fluidframework/ai-collab 2.22.1 → 2.23.0

package/CHANGELOG.md

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

package/README.md

@@ -85,14 +85,14 @@ export class PlannerAppState extends sf.object("PlannerAppState", {
 ### Example 1: Collaborate with AI
 
 ```ts
-import { aiCollab } from "@fluidframework/ai-collab/alpha";
+import { aiCollab, DebugEvent } from "@fluidframework/ai-collab/alpha";
 import { PlannerAppState } from "./types.ts"
 // This is not a real file, this is meant to represent how you initialize your app data.
 import { initializeAppState } from "./yourAppInitializationFile.ts"
 
 //  --------- File name: "app.ts" ---------
 
-// Initialize your app state somehow
+// Initialize your Fluid app state somehow
 const appState: PlannerAppState = initializeAppState({
 		taskGroups: [
 		{
@@ -143,9 +143,12 @@ const response = await aiCollab({
 				"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,
-		dumpDebugLog: true,
+		debugEventLogHandler: (event: DebugEvent) => {console.log(event);}
 	});
 
 if (response.status === 'sucess') {
@@ -174,12 +177,75 @@ Once the `aiCollab` function call is initiated, an LLM will immediately begin at
      - `promptGeneration.ts`: Logic for producing the different types of prompts sent to an LLM in order to edit a SharedTree.
      - `typeGeneration.ts`: Generates serialized(/able) representations of a SharedTree Schema which is used within prompts and the generated of the structured output JSON schema
      - `utils.ts`: Utilities for interacting with a SharedTree
+	 - `debugEvents.ts`: Types and helper functions for `DebugEvent`'s emitted to the callback provided to the aiCollab's `debugEventLogHandler`
 - `/implicit-strategy`: The original implicit strategy, currently not used under the exported aiCollab API surface.
 
+## Debug Events
+This package allows users to consume `DebugEvents` that can be very helpful in understanding what's going on internally and debugging potential issues.
+Users can consume these events by passing in a `debugEventLogHandler` when calling the `aiCollab()` function:
+```ts
+aiCollab({
+	openAI: {
+		client: new OpenAI({
+			apiKey: OPENAI_API_KEY,
+		}),
+		modelName: "gpt-4o",
+	},
+	treeNode: view.root.taskGroups[0],
+	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);} // This should be your debug event log handler
+});
+
+```
+
+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.
+	- Events:
+		1. **Core Event Loop Started**
+		1. **Core Event Loop Completed**
+2. **Generate Planning Prompt** - The event flow for producing an initial LLM generated plan to assist the LLM with creating edits to the users Shared Tree.
+	- Events
+		1. **Generate Planning Prompt Started**
+			- Child `DebugEvent`'s triggered:
+				1. **Llm Api Call** - An event detailing the raw api request to the LLM client.
+		1. **Generate Planning Prompt Completed**
+3. **Generate Tree Edit** - The event flow for generating an edit to the users Shared Tree to further complete the users request.
+	- Events:
+		1. **Generate Tree Edit Started**
+			- Child `DebugEvent`'s triggered:
+				1. **Llm Api Call** - An event detailing the raw api request to the LLM client.
+		1. **Generate Tree Edit Completed**
+		1. **Apply Edit Success** OR **Apply Edit Failure** - The outcome of applying the LLM generated tree edit.
+4. **Final Review** - The event flow for asking the LLM to complete a final review of work it has completed and confirming if the users request has been completed. If the LLM is not satisfied, the **Generate Tree Edit** loop will start again.
+	- Events:
+		- **Final Review Started**
+			- Child `DebugEvent`'s triggered:
+				1. **Llm Api Call** - An event detailing the raw api request to the LLM client.
+		- **Final Review Completed**
+
+
+### 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.
+
+
 ## Known Issues & limitations
 
 1. Union types for a TreeNode are not present when generating App Schema. This will require extracting a field schema instead of TreeNodeSchema when passed a non root node.
-1. The Editing System prompt & structured out schema currently provide array related edits even when there are no arrays. This forces you to have an array in your schema to produce a valid json schema
 1. Optional roots are not allowed, This is because if you pass undefined as your treeNode to the API, we cannot disambiguate whether you passed the root or not.
 1. Primitive root nodes are not allowed to be passed to the API. You must use an object or array as your root.
 1. Optional nodes are not supported -- when we use optional nodes, the OpenAI API returns an error complaining that the structured output JSON schema is invalid. I have introduced a fix that should work upon manual validation of the json schema, but there looks to be an issue with their API. I have filed a ticket with OpenAI to address this

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

@@ -9,14 +9,14 @@ export function aiCollab(options: AiCollabOptions): Promise<AiCollabSuccessRespo
 
 // @alpha
 export interface AiCollabErrorResponse {
-    readonly errorMessage: "tokenLimitExceeded" | "tooManyErrors" | "tooManyModelCalls" | "aborted";
+    readonly errorMessage: "tokenLimitExceeded" | "tooManyErrors" | "tooManyModelCalls" | "aborted" | "unexpectedError";
     readonly status: "failure" | "partial-failure";
     readonly tokensUsed: TokenUsage;
 }
 
 // @alpha
 export interface AiCollabOptions {
-    readonly dumpDebugLog?: boolean;
+    readonly debugEventLogHandler?: DebugEventLogHandler;
     readonly finalReviewStep?: boolean;
     readonly limiters?: {
         readonly abortController?: AbortController;
@@ -40,12 +40,75 @@ export interface AiCollabSuccessResponse {
     readonly tokensUsed: TokenUsage;
 }
 
+// @alpha
+export interface ApplyEditFailure extends EventFlowDebugEvent {
+    edit: LlmTreeEdit;
+    errorMessage: string;
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;
+    // (undocumented)
+    eventFlowStatus: "IN_PROGRESS";
+    eventFlowTraceId: string;
+    // (undocumented)
+    eventName: "APPLIED_EDIT_FAILURE";
+    sequentialErrorCount: number;
+}
+
+// @alpha
+export interface ApplyEditSuccess extends EventFlowDebugEvent {
+    edit: LlmTreeEdit;
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;
+    // (undocumented)
+    eventFlowStatus: "IN_PROGRESS";
+    eventFlowTraceId: string;
+    // (undocumented)
+    eventName: "APPLIED_EDIT_SUCCESS";
+}
+
+// @alpha
+export interface CoreEventLoopCompleted extends EventFlowDebugEvent {
+    // (undocumented)
+    errorMessage?: string;
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.CORE_EVENT_LOOP;
+    // (undocumented)
+    eventFlowStatus: "COMPLETED";
+    // (undocumented)
+    eventName: "CORE_EVENT_LOOP_COMPLETED";
+    // (undocumented)
+    failureReason?: string;
+    // (undocumented)
+    status: "success" | "failure";
+}
+
+// @alpha
+export interface CoreEventLoopStarted extends EventFlowDebugEvent {
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.CORE_EVENT_LOOP;
+    // (undocumented)
+    eventFlowStatus: "STARTED";
+    // (undocumented)
+    eventName: "CORE_EVENT_LOOP_STARTED";
+}
+
 // @alpha
 export function createMergableDiffSeries(diffs: Difference[]): Difference[];
 
 // @alpha
 export function createMergableIdDiffSeries(oldObject: unknown, diffs: Difference[], idAttributeName: string | number): Difference[];
 
+// @alpha
+export interface DebugEvent {
+    eventName: string;
+    id: string;
+    timestamp: string;
+    traceId: string;
+}
+
+// @alpha
+export type DebugEventLogHandler = <T extends DebugEvent>(event: T) => unknown;
+
 // @alpha
 export type Difference = DifferenceCreate | DifferenceRemove | DifferenceChange | DifferenceMove;
 
@@ -99,6 +162,89 @@ export interface DifferenceRemove {
     type: "REMOVE";
 }
 
+// @alpha
+export interface EventFlowDebugEvent extends DebugEvent {
+    eventFlowName: string;
+    eventFlowStatus: "STARTED" | "COMPLETED" | "IN_PROGRESS";
+    eventFlowTraceId: string;
+}
+
+// @alpha
+export type EventFlowDebugName = (typeof EventFlowDebugNames)[keyof typeof EventFlowDebugNames];
+
+// @alpha
+export const EventFlowDebugNames: {
+    readonly CORE_EVENT_LOOP: "CORE_EVENT_LOOP";
+    readonly GENERATE_PLANNING_PROMPT: "GENERATE_PLANNING_PROMPT";
+    readonly GENERATE_AND_APPLY_TREE_EDIT: "GENERATE_AND_APPLY_TREE_EDIT";
+    readonly FINAL_REVIEW: "FINAL_REVIEW";
+};
+
+// @alpha
+export interface FinalReviewCompleted<TIsLlmResponseValid = boolean, TReviewResponse = TIsLlmResponseValid extends true ? "yes" | "no" : undefined> extends EventFlowDebugEvent {
+    didLlmAccomplishGoal: TReviewResponse;
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.FINAL_REVIEW;
+    // (undocumented)
+    eventFlowStatus: "COMPLETED";
+    // (undocumented)
+    eventName: "FINAL_REVIEW_COMPLETED";
+    isLlmResponseValid: TIsLlmResponseValid;
+}
+
+// @alpha
+export interface FinalReviewStarted extends EventFlowDebugEvent {
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.FINAL_REVIEW;
+    // (undocumented)
+    eventFlowStatus: "STARTED";
+    // (undocumented)
+    eventName: "FINAL_REVIEW_STARTED";
+    llmPrompt: string;
+}
+
+// @alpha
+export interface GenerateTreeEditCompleted<TIsLlmResponseValid = boolean, TEdit = TIsLlmResponseValid extends true ? LlmTreeEdit | null : undefined> extends EventFlowDebugEvent {
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;
+    // (undocumented)
+    eventFlowStatus: "COMPLETED";
+    // (undocumented)
+    eventName: "GENERATE_TREE_EDIT_COMPLETED";
+    isLlmResponseValid: TIsLlmResponseValid;
+    llmGeneratedEdit: TEdit;
+}
+
+// @alpha
+export interface GenerateTreeEditStarted extends EventFlowDebugEvent {
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;
+    // (undocumented)
+    eventFlowStatus: "STARTED";
+    // (undocumented)
+    eventName: "GENERATE_TREE_EDIT_STARTED";
+    // (undocumented)
+    llmPrompt: string;
+}
+
+// @alpha
+export interface LlmApiCallDebugEvent extends DebugEvent {
+    eventFlowTraceId: string;
+    // (undocumented)
+    eventName: "LLM_API_CALL";
+    modelName: string;
+    requestParams: unknown;
+    response: unknown;
+    tokenUsage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    triggeringEventFlowName: EventFlowDebugName;
+}
+
+// @alpha
+export type LlmTreeEdit = Record<string, unknown>;
+
 // @alpha
 export type ObjectPath = (string | number)[];
 
@@ -118,6 +264,28 @@ export interface Options {
     } | undefined;
 }
 
+// @alpha
+export interface PlanningPromptCompleted<TIsLlmResponseValid = boolean, TPlan = TIsLlmResponseValid extends true ? string : undefined> extends EventFlowDebugEvent {
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_PLANNING_PROMPT;
+    // (undocumented)
+    eventFlowStatus: "COMPLETED";
+    // (undocumented)
+    eventName: "GENERATE_PLANNING_PROMPT_COMPLETED";
+    isLlmResponseValid: TIsLlmResponseValid;
+    llmGeneratedPlan: TPlan;
+}
+
+// @alpha
+export interface PlanningPromptStarted extends EventFlowDebugEvent {
+    // (undocumented)
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_PLANNING_PROMPT;
+    // (undocumented)
+    eventFlowStatus: "STARTED";
+    // (undocumented)
+    eventName: "GENERATE_PLANNING_PROMPT_STARTED";
+}
+
 // @alpha
 export class SharedTreeBranchManager {
     constructor(params?: {

package/dist/aiCollab.d.ts

@@ -46,7 +46,6 @@ import type { AiCollabErrorResponse, AiCollabOptions, AiCollabSuccessResponse }
  * 		},
  * 		planningStep: true,
  * 		finalReviewStep: true,
- * 		dumpDebugLog: true,
  * 	});
  * ```
  *

package/dist/aiCollab.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiCollab.d.ts","sourceRoot":"","sources":["../src/aiCollab.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACX,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAsB,QAAQ,CAC7B,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,uBAAuB,GAAG,qBAAqB,CAAC,CAa1D"}
+{"version":3,"file":"aiCollab.d.ts","sourceRoot":"","sources":["../src/aiCollab.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACX,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAsB,QAAQ,CAC7B,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,uBAAuB,GAAG,qBAAqB,CAAC,CAa1D"}

package/dist/aiCollab.js

@@ -49,7 +49,6 @@ const index_js_1 = require("./explicit-strategy/index.js");
  * 		},
  * 		planningStep: true,
  * 		finalReviewStep: true,
- * 		dumpDebugLog: true,
  * 	});
  * ```
  *
@@ -71,9 +70,9 @@ async function aiCollab(options) {
         openAI: options.openAI,
         prompt: options.prompt,
         limiters: options.limiters,
-        dumpDebugLog: options.dumpDebugLog,
         planningStep: options.planningStep,
         finalReviewStep: options.finalReviewStep,
+        debugEventLogHandler: options.debugEventLogHandler,
     });
     return response;
 }

package/dist/aiCollab.js.map

@@ -1 +1 @@
-{"version":3,"file":"aiCollab.js","sourceRoot":"","sources":["../src/aiCollab.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAOH,2DAAiE;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACI,KAAK,UAAU,QAAQ,CAC7B,OAAwB;IAExB,MAAM,QAAQ,GAAG,MAAM,IAAA,4BAAiB,EAAC;QACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,eAAe,EAAE,OAAO,CAAC,eAAe;KACxC,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AACjB,CAAC;AAfD,4BAeC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tAiCollabErrorResponse,\n\tAiCollabOptions,\n\tAiCollabSuccessResponse,\n} from \"./aiCollabApi.js\";\nimport { generateTreeEdits } from \"./explicit-strategy/index.js\";\n\n/**\n * Calls an LLM to modify the provided SharedTree in a series of real time edits based on the provided users prompt input.\n * @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.\n *\n * @example\n * ```typescript\n * import {\n * \tSchemaFactory,\n * \tTreeViewConfiguration,\n * \ttype TreeView\n * } from \"@fluidframework/tree\";\n *\n * const sf = new SchemaFactory(\"todo-app\");\n *\n * class TodoTask extends sf.object(\"TodoTask\", {\n * \ttitle: sf.string,\n * \tdescription: sf.string,\n * }) {}\n *\n * class TodoAppState extends sf.object(\"TodoAppState\", {\n * \ttasks: sf.array(TodoTask),\n * }) {}\n *\n * // Initialize your SharedTree\n * const treeView: TreeView = tree.viewWith(new TreeViewConfiguration({ schema: TodoAppState }));\n * treeView.initialize({ tasks: [] });\n *\n * // Collaborate with AI in realtime in just one function call.\n * const response = await aiCollab({\n * \t\topenAI: {\n * \t\t\tclient: new OpenAI({\n * \t\t\t\tapiKey: OPENAI_API_KEY,\n * \t\t\t}),\n * \t\t\tmodelName: \"gpt-4o\",\n * \t\t},\n * \t\ttreeNode: view.root,\n * \t\tprompt: {\n * \t\t\tsystemRoleContext:\n * \t\t\t\t\"You are an helpful assistant managing a todo list for a user.\",\n * \t\t\tuserAsk: \"Create a set of new todos to plan a vacation to Cancun.\",\n * \t\t},\n * \t\tplanningStep: true,\n * \t\tfinalReviewStep: true,\n * \t\tdumpDebugLog: true,\n * \t});\n * ```\n *\n * @remarks Known Limitiations:\n * - Root level array nodes are not supported\n * - Nested arrays are not supported\n * - Primitive nodes are not supported, e.g. 'string', 'number', 'boolean'\n * - Your application's Shared Tree schema must have no more than 4 levels of nesting\n * - Optional nodes are not supported in the Shared Tree schema\n * - Union types are not supported in the Shared Tree schema\n * - See README for more details.\n *\n * @alpha\n */\nexport async function aiCollab(\n\toptions: AiCollabOptions,\n): Promise<AiCollabSuccessResponse | AiCollabErrorResponse> {\n\tconst response = await generateTreeEdits({\n\t\ttreeNode: options.treeNode,\n\t\tvalidator: options.validator,\n\t\topenAI: options.openAI,\n\t\tprompt: options.prompt,\n\t\tlimiters: options.limiters,\n\t\tdumpDebugLog: options.dumpDebugLog,\n\t\tplanningStep: options.planningStep,\n\t\tfinalReviewStep: options.finalReviewStep,\n\t});\n\n\treturn response;\n}\n"]}
+{"version":3,"file":"aiCollab.js","sourceRoot":"","sources":["../src/aiCollab.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAOH,2DAAiE;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACI,KAAK,UAAU,QAAQ,CAC7B,OAAwB;IAExB,MAAM,QAAQ,GAAG,MAAM,IAAA,4BAAiB,EAAC;QACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;KAClD,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AACjB,CAAC;AAfD,4BAeC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tAiCollabErrorResponse,\n\tAiCollabOptions,\n\tAiCollabSuccessResponse,\n} from \"./aiCollabApi.js\";\nimport { generateTreeEdits } from \"./explicit-strategy/index.js\";\n\n/**\n * Calls an LLM to modify the provided SharedTree in a series of real time edits based on the provided users prompt input.\n * @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.\n *\n * @example\n * ```typescript\n * import {\n * \tSchemaFactory,\n * \tTreeViewConfiguration,\n * \ttype TreeView\n * } from \"@fluidframework/tree\";\n *\n * const sf = new SchemaFactory(\"todo-app\");\n *\n * class TodoTask extends sf.object(\"TodoTask\", {\n * \ttitle: sf.string,\n * \tdescription: sf.string,\n * }) {}\n *\n * class TodoAppState extends sf.object(\"TodoAppState\", {\n * \ttasks: sf.array(TodoTask),\n * }) {}\n *\n * // Initialize your SharedTree\n * const treeView: TreeView = tree.viewWith(new TreeViewConfiguration({ schema: TodoAppState }));\n * treeView.initialize({ tasks: [] });\n *\n * // Collaborate with AI in realtime in just one function call.\n * const response = await aiCollab({\n * \t\topenAI: {\n * \t\t\tclient: new OpenAI({\n * \t\t\t\tapiKey: OPENAI_API_KEY,\n * \t\t\t}),\n * \t\t\tmodelName: \"gpt-4o\",\n * \t\t},\n * \t\ttreeNode: view.root,\n * \t\tprompt: {\n * \t\t\tsystemRoleContext:\n * \t\t\t\t\"You are an helpful assistant managing a todo list for a user.\",\n * \t\t\tuserAsk: \"Create a set of new todos to plan a vacation to Cancun.\",\n * \t\t},\n * \t\tplanningStep: true,\n * \t\tfinalReviewStep: true,\n * \t});\n * ```\n *\n * @remarks Known Limitiations:\n * - Root level array nodes are not supported\n * - Nested arrays are not supported\n * - Primitive nodes are not supported, e.g. 'string', 'number', 'boolean'\n * - Your application's Shared Tree schema must have no more than 4 levels of nesting\n * - Optional nodes are not supported in the Shared Tree schema\n * - Union types are not supported in the Shared Tree schema\n * - See README for more details.\n *\n * @alpha\n */\nexport async function aiCollab(\n\toptions: AiCollabOptions,\n): Promise<AiCollabSuccessResponse | AiCollabErrorResponse> {\n\tconst response = await generateTreeEdits({\n\t\ttreeNode: options.treeNode,\n\t\tvalidator: options.validator,\n\t\topenAI: options.openAI,\n\t\tprompt: options.prompt,\n\t\tlimiters: options.limiters,\n\t\tplanningStep: options.planningStep,\n\t\tfinalReviewStep: options.finalReviewStep,\n\t\tdebugEventLogHandler: options.debugEventLogHandler,\n\t});\n\n\treturn response;\n}\n"]}

package/dist/aiCollabApi.d.ts

@@ -4,6 +4,52 @@
  */
 import type { TreeNode } from "@fluidframework/tree";
 import type OpenAI from "openai";
+/**
+ * Core Debug event type for the ai-collab
+ * @alpha
+ */
+export interface DebugEvent {
+    /**
+     * The unique id of the debug event.
+     */
+    id: string;
+    /**
+     * An id that will be shared across all debug events that originate from the same single execution of ai-collab.
+     * @remarks This is intended to be used to correlate all debug events that originate from the same execution
+     */
+    traceId: string;
+    /**
+     * The name of the debug event.
+     */
+    eventName: string;
+    /**
+     * The date and time at which the debug event was created.
+     */
+    timestamp: string;
+}
+/**
+ * A Debug event that marks the start or end of a single core logic flow, such as generated tree edits, planning prompt, etc.
+ * @alpha
+ */
+export interface EventFlowDebugEvent extends DebugEvent {
+    /**
+     * The name of the particular event flow.
+     */
+    eventFlowName: string;
+    /**
+     * The status of the particular event flow.
+     */
+    eventFlowStatus: "STARTED" | "COMPLETED" | "IN_PROGRESS";
+    /**
+     * A unique id that will be shared across all debug events that are part of the same event flow.
+     */
+    eventFlowTraceId: string;
+}
+/**
+ * A callback function that can be used to handle debug events that occur during the AI collaboration process.
+ * @alpha
+ */
+export type DebugEventLogHandler = <T extends DebugEvent>(event: T) => unknown;
 /**
  * OpenAI client options for the {@link AiCollabOptions} interface.
  *
@@ -95,9 +141,9 @@ export interface AiCollabOptions {
      */
     readonly validator?: (newContent: TreeNode) => void;
     /**
-     * When enabled, the library will console.log information useful for debugging the AI collaboration.
+     * An optional handler for debug events that occur during the AI collaboration.
      */
-    readonly dumpDebugLog?: boolean;
+    readonly debugEventLogHandler?: DebugEventLogHandler;
 }
 /**
  * A successful response from the AI collaboration.
@@ -133,8 +179,9 @@ export interface AiCollabErrorResponse {
      * - '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
+     * - 'unexpectedError' indicates that an unexpected error occured
      */
-    readonly errorMessage: "tokenLimitExceeded" | "tooManyErrors" | "tooManyModelCalls" | "aborted";
+    readonly errorMessage: "tokenLimitExceeded" | "tooManyErrors" | "tooManyModelCalls" | "aborted" | "unexpectedError";
     /**
      * {@inheritDoc TokenUsage}
      */

package/dist/aiCollabApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiCollabApi.d.ts","sourceRoot":"","sources":["../src/aiCollabApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE;QAChB;;;WAGG;QACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;QACnC;;WAEG;QACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QACnB;;WAEG;QACH,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;QAC3C;;;;WAIG;QACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QACtC;;;;WAIG;QACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAChC;;;;;WAKG;QACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;KACnC,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpD;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACvC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAClB,oBAAoB,GACpB,eAAe,GACf,mBAAmB,GACnB,SAAS,CAAC;IACb;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAC/B"}
+{"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 * 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 * When enabled, the library will console.log information useful for debugging the AI collaboration.\n\t */\n\treadonly dumpDebugLog?: boolean;\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 */\n\treadonly errorMessage:\n\t\t| \"tokenLimitExceeded\"\n\t\t| \"tooManyErrors\"\n\t\t| \"tooManyModelCalls\"\n\t\t| \"aborted\";\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\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"]}

package/dist/alpha.d.ts

@@ -22,14 +22,31 @@ export {
 	AiCollabErrorResponse, 
 	AiCollabOptions, 
 	AiCollabSuccessResponse, 
+	ApplyEditFailure, 
+	ApplyEditSuccess, 
+	CoreEventLoopCompleted, 
+	CoreEventLoopStarted, 
+	DebugEvent, 
+	DebugEventLogHandler, 
 	Difference, 
 	DifferenceChange, 
 	DifferenceCreate, 
 	DifferenceMove, 
 	DifferenceRemove, 
+	EventFlowDebugEvent, 
+	EventFlowDebugName, 
+	EventFlowDebugNames, 
+	FinalReviewCompleted, 
+	FinalReviewStarted, 
+	GenerateTreeEditCompleted, 
+	GenerateTreeEditStarted, 
+	LlmApiCallDebugEvent, 
+	LlmTreeEdit, 
 	ObjectPath, 
 	OpenAiClientOptions, 
 	Options, 
+	PlanningPromptCompleted, 
+	PlanningPromptStarted, 
 	SharedTreeBranchManager, 
 	TokenLimits, 
 	TokenUsage,