@fluidframework/ai-collab 2.22.1 → 2.23.0

package/lib/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/lib/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/lib/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, 

package/lib/explicit-strategy/debugEvents.d.ts

@@ -0,0 +1,248 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { DebugEvent, EventFlowDebugEvent } from "../aiCollabApi.js";
+/**
+ * This file contains the types for the debug events that are emitted by the explicit strategy
+ * as well as a helper functions to help create a consistent method for producing a base {@link DebugEvent}.
+ */
+/**
+ * The possible values for the `eventFlowName` field in an {@link EventFlowDebugEvent}.
+ * @alpha
+ */
+export declare 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";
+};
+/**
+ * The type for possible values for the `eventFlowName` field in an {@link EventFlowDebugEvent}.
+ * @alpha
+ */
+export type EventFlowDebugName = (typeof EventFlowDebugNames)[keyof typeof EventFlowDebugNames];
+/**
+ * An edit generated by an LLM that can be applied to a given SharedTree.
+ * @privateremarks TODO: We need a better solution here because don't want to expose the internal TreeEdit type here, but we need to be able to type it.
+ * @alpha
+ */
+export type LlmTreeEdit = Record<string, unknown>;
+/**
+ * An {@link EventFlowDebugEvent} for signaling the start of the ai-collab's core event loop.
+ * Which makes various calls to the LLM to eventually apply edits to the users SharedTree which
+ * accomplish the user's provided goal. There will be exactly 1 of these events per ai-collab function execution.
+ * @alpha
+ */
+export interface CoreEventLoopStarted extends EventFlowDebugEvent {
+    eventName: "CORE_EVENT_LOOP_STARTED";
+    eventFlowName: typeof EventFlowDebugNames.CORE_EVENT_LOOP;
+    eventFlowStatus: "STARTED";
+}
+/**
+ * An {@link EventFlowDebugEvent} for signaling the end of the ai-collab's core event loop.
+ * There could be various reasons for the event loop to end, early exits and failures
+ * which should be captured in the status and failureReason fields. There will be exactly 1
+ * of these events per ai-collab function execution.
+ * @alpha
+ */
+export interface CoreEventLoopCompleted extends EventFlowDebugEvent {
+    eventName: "CORE_EVENT_LOOP_COMPLETED";
+    eventFlowName: typeof EventFlowDebugNames.CORE_EVENT_LOOP;
+    eventFlowStatus: "COMPLETED";
+    status: "success" | "failure";
+    failureReason?: string;
+    errorMessage?: string;
+}
+/**
+ * An {@link EventFlowDebugEvent} marking the initiation of the flow for prompting an LLM to generate a plan for accomplishing the user's goal.
+ * There will be exactly 1 of these events per ai-collab function execution.
+ * @alpha
+ */
+export interface PlanningPromptStarted extends EventFlowDebugEvent {
+    eventName: "GENERATE_PLANNING_PROMPT_STARTED";
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_PLANNING_PROMPT;
+    eventFlowStatus: "STARTED";
+}
+/**
+ * An {@link EventFlowDebugEvent} marking the completion of the flow for prompting an LLM to generate a plan for accomplishing the user's goal.
+ * There will be exactly 1 of these events per ai-collab function execution.
+ * @alpha
+ */
+export interface PlanningPromptCompleted<TIsLlmResponseValid = boolean, TPlan = TIsLlmResponseValid extends true ? string : undefined> extends EventFlowDebugEvent {
+    eventName: "GENERATE_PLANNING_PROMPT_COMPLETED";
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_PLANNING_PROMPT;
+    eventFlowStatus: "COMPLETED";
+    /**
+     * Whether the response produced by the LLM is an expected response.
+     * In the event that the LLM fails to respond in an expected way, despite the API call to the LLM itself being successful, then this fields value will be `false`.
+     *
+     * For now, this case is limited to the LLM returning undefined as a response when it should have returned something. But in the future this could expand
+     * to things such as invalid json.
+     */
+    isLlmResponseValid: TIsLlmResponseValid;
+    /**
+     * The plan generated by the LLM. If the `wasLlmResponseValid` field is `false` then this will be undefined, otherwise it will be a string.
+     */
+    llmGeneratedPlan: TPlan;
+}
+/**
+ * An {@link EventFlowDebugEvent} marking the initiation of the flow for prompting an LLM to
+ * generate an {@link LlmTreeEdit} to the users Shared Tree based on the users initial ask.
+ * It is expected that the LLM will generate multiple of these events when it must generate multiple tree edits to satisfy the user request
+ * @alpha
+ */
+export interface GenerateTreeEditStarted extends EventFlowDebugEvent {
+    eventName: "GENERATE_TREE_EDIT_STARTED";
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;
+    eventFlowStatus: "STARTED";
+    llmPrompt: string;
+}
+/**
+ * An {@link EventFlowDebugEvent} marking the completion of the flow for prompting an LLM to
+ * generate an {@link LlmTreeEdit} to the users Shared Tree based on the users initial ask.
+ * It is expected that the LLM will generate multiple of these events when it must generate multiple tree edits to satisfy the user request
+ * @alpha
+ */
+export interface GenerateTreeEditCompleted<TIsLlmResponseValid = boolean, TEdit = TIsLlmResponseValid extends true ? LlmTreeEdit | null : undefined> extends EventFlowDebugEvent {
+    eventName: "GENERATE_TREE_EDIT_COMPLETED";
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;
+    eventFlowStatus: "COMPLETED";
+    /**
+     * Whether the response produced by the LLM is an expected response.
+     * In the event that the LLM fails to respond in an expected way, despite the API call to the LLM itself being successful, then this fields value will be `false`.
+     *
+     * For now, this case is limited to the LLM returning undefined as a response when it should have returned something. But in the future this could expand
+     * to things such as invalid json.
+     */
+    isLlmResponseValid: TIsLlmResponseValid;
+    /**
+     * If the `isLlmResponseValid` field value is `true` then this be one of two following values returned by the LLM:
+     * 1. An edit that can be applied to a SharedTree to further accomplish the user's goal.
+     * 2. `null` if the LLM decides no more edits are necessary.
+     *
+     * If the `isLlmResponseValid` field is `false` then this field will be `undefined`.
+     */
+    llmGeneratedEdit: TEdit;
+}
+/**
+ * An {@link EventFlowDebugEvent} marking the successful application of an edit generated by the LLM to a SharedTree.
+ * @alpha
+ */
+export interface ApplyEditSuccess extends EventFlowDebugEvent {
+    eventName: "APPLIED_EDIT_SUCCESS";
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;
+    eventFlowStatus: "IN_PROGRESS";
+    /**
+     * A unique id that will be shared across all debug events that are part of the same event flow.
+     */
+    eventFlowTraceId: string;
+    /**
+     * The {@link LlmTreeEdit} generated by the LLM.
+     */
+    edit: LlmTreeEdit;
+}
+/**
+ * An {@link EventFlowDebugEvent} marking the failure of applying an edit generated by the LLM to a SharedTree.
+ * @alpha
+ */
+export interface ApplyEditFailure extends EventFlowDebugEvent {
+    eventName: "APPLIED_EDIT_FAILURE";
+    eventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;
+    eventFlowStatus: "IN_PROGRESS";
+    /**
+     * A unique id that will be shared across all debug events that are part of the same event flow.
+     */
+    eventFlowTraceId: string;
+    /**
+     * The {@link LlmTreeEdit} generated by the LLM.
+     */
+    edit: LlmTreeEdit;
+    /**
+     * The error message that was thrown when attempting to apply the edit.
+     */
+    errorMessage: string;
+    /**
+     * The total number of errors that have occurred up until this point, not including this error.
+     */
+    sequentialErrorCount: number;
+}
+/**
+ * An {@link EventFlowDebugEvent} marking the initiation of the flow for prompting an LLM to complete a final review of its edits
+ * and determine whether the user's goal was accomplished.
+ * @alpha
+ */
+export interface FinalReviewStarted extends EventFlowDebugEvent {
+    eventName: "FINAL_REVIEW_STARTED";
+    eventFlowName: typeof EventFlowDebugNames.FINAL_REVIEW;
+    eventFlowStatus: "STARTED";
+    /**
+     * The prompt sent to the LLM to complete its final review of the edits its made.
+     */
+    llmPrompt: string;
+}
+/**
+ * An {@link EventFlowDebugEvent} marking the end of the flow for prompting an LLM to complete a final review of its edits
+ * and determine whether the user's goal was accomplished.
+ * @alpha
+ */
+export interface FinalReviewCompleted<TIsLlmResponseValid = boolean, TReviewResponse = TIsLlmResponseValid extends true ? "yes" | "no" : undefined> extends EventFlowDebugEvent {
+    eventName: "FINAL_REVIEW_COMPLETED";
+    eventFlowName: typeof EventFlowDebugNames.FINAL_REVIEW;
+    eventFlowStatus: "COMPLETED";
+    /**
+     * Whether the response produced by the LLM is an expected response.
+     * In the event that the LLM fails to respond in an expected way, despite the API call to the LLM itself being successful, then this fields value will be `false`.
+     *
+     * For now, this case is limited to the LLM returning undefined as a response when it should have returned something. But in the future this could expand
+     * to things such as invalid json.
+     */
+    isLlmResponseValid: TIsLlmResponseValid;
+    /**
+     * Whether the Llm believes the user's ask was accomplished, based on the Edits is has already generated and applied.
+     * If the `status` field is `false` then this field value will be `undefined`, otherwise it will be either "yes" or "no"
+     */
+    didLlmAccomplishGoal: TReviewResponse;
+}
+/**
+ * An {@link DebugEvent} for an API call directly to a LLM.
+ * @alpha
+ */
+export interface LlmApiCallDebugEvent extends DebugEvent {
+    eventName: "LLM_API_CALL";
+    /**
+     * The event flow name that made this LLM API call.
+     */
+    triggeringEventFlowName: EventFlowDebugName;
+    /**
+     * The unique id that will be shared across all debug events that are part of the same event flow.
+     * @remarks This can be used to correlate all debug events that are part of the same event flow.
+     */
+    eventFlowTraceId: string;
+    /**
+     * The LLM model name that was used for the API call.
+     */
+    modelName: string;
+    /**
+     * The request parameters sent in the API call to the LLM. (Not the HTTP request parameters such as headers, etc.)
+     */
+    requestParams: unknown;
+    /**
+     * The raw response from the LLM.
+     */
+    response: unknown;
+    /**
+     * The total number of tokens used in the API call to the LLM.
+     */
+    tokenUsage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+}
+/**
+ * Creates a base {@link DebugEvent}.
+ */
+export declare function generateDebugEvent<Tevent extends string>(eventName: Tevent, traceId: string): DebugEvent & {
+    eventName: Tevent;
+};
+//# sourceMappingURL=debugEvents.d.ts.map

package/lib/explicit-strategy/debugEvents.d.ts.map

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

package/lib/explicit-strategy/debugEvents.js

@@ -0,0 +1,32 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { v4 as uuidv4 } from "uuid";
+/**
+ * This file contains the types for the debug events that are emitted by the explicit strategy
+ * as well as a helper functions to help create a consistent method for producing a base {@link DebugEvent}.
+ */
+/**
+ * The possible values for the `eventFlowName` field in an {@link EventFlowDebugEvent}.
+ * @alpha
+ */
+export const EventFlowDebugNames = {
+    CORE_EVENT_LOOP: "CORE_EVENT_LOOP",
+    GENERATE_PLANNING_PROMPT: "GENERATE_PLANNING_PROMPT",
+    GENERATE_AND_APPLY_TREE_EDIT: "GENERATE_AND_APPLY_TREE_EDIT",
+    FINAL_REVIEW: "FINAL_REVIEW",
+};
+/**
+ * Creates a base {@link DebugEvent}.
+ */
+export function generateDebugEvent(eventName, traceId) {
+    const event = {
+        eventName,
+        id: uuidv4(),
+        traceId,
+        timestamp: new Date().toISOString(),
+    };
+    return event;
+}
+//# sourceMappingURL=debugEvents.js.map

package/lib/explicit-strategy/debugEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugEvents.js","sourceRoot":"","sources":["../../src/explicit-strategy/debugEvents.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAIpC;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAClC,eAAe,EAAE,iBAAiB;IAClC,wBAAwB,EAAE,0BAA0B;IACpD,4BAA4B,EAAE,8BAA8B;IAC5D,YAAY,EAAE,cAAc;CACnB,CAAC;AAmQX;;GAEG;AACH,MAAM,UAAU,kBAAkB,CACjC,SAAiB,EACjB,OAAe;IAEf,MAAM,KAAK,GAAG;QACb,SAAS;QACT,EAAE,EAAE,MAAM,EAAE;QACZ,OAAO;QACP,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACnC,CAAC;IACF,OAAO,KAAK,CAAC;AACd,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { v4 as uuidv4 } from \"uuid\";\n\nimport type { DebugEvent, EventFlowDebugEvent } from \"../aiCollabApi.js\";\n\n/**\n * This file contains the types for the debug events that are emitted by the explicit strategy\n * as well as a helper functions to help create a consistent method for producing a base {@link DebugEvent}.\n */\n\n/**\n * The possible values for the `eventFlowName` field in an {@link EventFlowDebugEvent}.\n * @alpha\n */\nexport const EventFlowDebugNames = {\n\tCORE_EVENT_LOOP: \"CORE_EVENT_LOOP\",\n\tGENERATE_PLANNING_PROMPT: \"GENERATE_PLANNING_PROMPT\",\n\tGENERATE_AND_APPLY_TREE_EDIT: \"GENERATE_AND_APPLY_TREE_EDIT\",\n\tFINAL_REVIEW: \"FINAL_REVIEW\",\n} as const;\n\n/**\n * The type for possible values for the `eventFlowName` field in an {@link EventFlowDebugEvent}.\n * @alpha\n */\nexport type EventFlowDebugName =\n\t(typeof EventFlowDebugNames)[keyof typeof EventFlowDebugNames];\n\n/**\n * An edit generated by an LLM that can be applied to a given SharedTree.\n * @privateremarks TODO: We need a better solution here because don't want to expose the internal TreeEdit type here, but we need to be able to type it.\n * @alpha\n */\nexport type LlmTreeEdit = Record<string, unknown>;\n\n/**\n * An {@link EventFlowDebugEvent} for signaling the start of the ai-collab's core event loop.\n * Which makes various calls to the LLM to eventually apply edits to the users SharedTree which\n * accomplish the user's provided goal. There will be exactly 1 of these events per ai-collab function execution.\n * @alpha\n */\nexport interface CoreEventLoopStarted extends EventFlowDebugEvent {\n\teventName: \"CORE_EVENT_LOOP_STARTED\";\n\teventFlowName: typeof EventFlowDebugNames.CORE_EVENT_LOOP;\n\teventFlowStatus: \"STARTED\";\n}\n\n/**\n * An {@link EventFlowDebugEvent} for signaling the end of the ai-collab's core event loop.\n * There could be various reasons for the event loop to end, early exits and failures\n * which should be captured in the status and failureReason fields. There will be exactly 1\n * of these events per ai-collab function execution.\n * @alpha\n */\nexport interface CoreEventLoopCompleted extends EventFlowDebugEvent {\n\teventName: \"CORE_EVENT_LOOP_COMPLETED\";\n\teventFlowName: typeof EventFlowDebugNames.CORE_EVENT_LOOP;\n\teventFlowStatus: \"COMPLETED\";\n\tstatus: \"success\" | \"failure\";\n\tfailureReason?: string;\n\terrorMessage?: string;\n}\n\n// #region Planning Prompt Debug events -------------------------------\n\n/**\n * An {@link EventFlowDebugEvent} marking the initiation of the flow for prompting an LLM to generate a plan for accomplishing the user's goal.\n * There will be exactly 1 of these events per ai-collab function execution.\n * @alpha\n */\nexport interface PlanningPromptStarted extends EventFlowDebugEvent {\n\teventName: \"GENERATE_PLANNING_PROMPT_STARTED\";\n\teventFlowName: typeof EventFlowDebugNames.GENERATE_PLANNING_PROMPT;\n\teventFlowStatus: \"STARTED\";\n}\n\n/**\n * An {@link EventFlowDebugEvent} marking the completion of the flow for prompting an LLM to generate a plan for accomplishing the user's goal.\n * There will be exactly 1 of these events per ai-collab function execution.\n * @alpha\n */\nexport interface PlanningPromptCompleted<\n\tTIsLlmResponseValid = boolean,\n\tTPlan = TIsLlmResponseValid extends true ? string : undefined,\n> extends EventFlowDebugEvent {\n\teventName: \"GENERATE_PLANNING_PROMPT_COMPLETED\";\n\teventFlowName: typeof EventFlowDebugNames.GENERATE_PLANNING_PROMPT;\n\teventFlowStatus: \"COMPLETED\";\n\t/**\n\t * Whether the response produced by the LLM is an expected response.\n\t * In the event that the LLM fails to respond in an expected way, despite the API call to the LLM itself being successful, then this fields value will be `false`.\n\t *\n\t * For now, this case is limited to the LLM returning undefined as a response when it should have returned something. But in the future this could expand\n\t * to things such as invalid json.\n\t */\n\tisLlmResponseValid: TIsLlmResponseValid;\n\t/**\n\t * The plan generated by the LLM. If the `wasLlmResponseValid` field is `false` then this will be undefined, otherwise it will be a string.\n\t */\n\tllmGeneratedPlan: TPlan;\n}\n\n// #endregion Planning Prompt Debug events ----------------------------------------------------------\n\n// #region Generate And Apply Tree Edit Debug events ------------------\n\n/**\n * An {@link EventFlowDebugEvent} marking the initiation of the flow for prompting an LLM to\n * generate an {@link LlmTreeEdit} to the users Shared Tree based on the users initial ask.\n * It is expected that the LLM will generate multiple of these events when it must generate multiple tree edits to satisfy the user request\n * @alpha\n */\nexport interface GenerateTreeEditStarted extends EventFlowDebugEvent {\n\teventName: \"GENERATE_TREE_EDIT_STARTED\";\n\teventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;\n\teventFlowStatus: \"STARTED\";\n\tllmPrompt: string;\n}\n\n/**\n * An {@link EventFlowDebugEvent} marking the completion of the flow for prompting an LLM to\n * generate an {@link LlmTreeEdit} to the users Shared Tree based on the users initial ask.\n * It is expected that the LLM will generate multiple of these events when it must generate multiple tree edits to satisfy the user request\n * @alpha\n */\nexport interface GenerateTreeEditCompleted<\n\tTIsLlmResponseValid = boolean,\n\tTEdit = TIsLlmResponseValid extends true ? LlmTreeEdit | null : undefined,\n> extends EventFlowDebugEvent {\n\teventName: \"GENERATE_TREE_EDIT_COMPLETED\";\n\teventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;\n\teventFlowStatus: \"COMPLETED\";\n\t/**\n\t * Whether the response produced by the LLM is an expected response.\n\t * In the event that the LLM fails to respond in an expected way, despite the API call to the LLM itself being successful, then this fields value will be `false`.\n\t *\n\t * For now, this case is limited to the LLM returning undefined as a response when it should have returned something. But in the future this could expand\n\t * to things such as invalid json.\n\t */\n\tisLlmResponseValid: TIsLlmResponseValid;\n\t/**\n\t * If the `isLlmResponseValid` field value is `true` then this be one of two following values returned by the LLM:\n\t * 1. An edit that can be applied to a SharedTree to further accomplish the user's goal.\n\t * 2. `null` if the LLM decides no more edits are necessary.\n\t *\n\t * If the `isLlmResponseValid` field is `false` then this field will be `undefined`.\n\t */\n\tllmGeneratedEdit: TEdit;\n}\n\n/**\n * An {@link EventFlowDebugEvent} marking the successful application of an edit generated by the LLM to a SharedTree.\n * @alpha\n */\nexport interface ApplyEditSuccess extends EventFlowDebugEvent {\n\teventName: \"APPLIED_EDIT_SUCCESS\";\n\teventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;\n\teventFlowStatus: \"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\t/**\n\t * The {@link LlmTreeEdit} generated by the LLM.\n\t */\n\tedit: LlmTreeEdit;\n}\n\n/**\n * An {@link EventFlowDebugEvent} marking the failure of applying an edit generated by the LLM to a SharedTree.\n * @alpha\n */\nexport interface ApplyEditFailure extends EventFlowDebugEvent {\n\teventName: \"APPLIED_EDIT_FAILURE\";\n\teventFlowName: typeof EventFlowDebugNames.GENERATE_AND_APPLY_TREE_EDIT;\n\teventFlowStatus: \"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\t/**\n\t * The {@link LlmTreeEdit} generated by the LLM.\n\t */\n\tedit: LlmTreeEdit;\n\t/**\n\t * The error message that was thrown when attempting to apply the edit.\n\t */\n\terrorMessage: string;\n\t/**\n\t * The total number of errors that have occurred up until this point, not including this error.\n\t */\n\tsequentialErrorCount: number;\n}\n\n// #endregion Generate And Apply Tree Edit Debug events ----------------------\n\n// #region Generate Final Review Debug events -------------------------\n\n/**\n * An {@link EventFlowDebugEvent} marking the initiation of the flow for prompting an LLM to complete a final review of its edits\n * and determine whether the user's goal was accomplished.\n * @alpha\n */\nexport interface FinalReviewStarted extends EventFlowDebugEvent {\n\teventName: \"FINAL_REVIEW_STARTED\";\n\teventFlowName: typeof EventFlowDebugNames.FINAL_REVIEW;\n\teventFlowStatus: \"STARTED\";\n\t/**\n\t * The prompt sent to the LLM to complete its final review of the edits its made.\n\t */\n\tllmPrompt: string;\n}\n\n/**\n * An {@link EventFlowDebugEvent} marking the end of the flow for prompting an LLM to complete a final review of its edits\n * and determine whether the user's goal was accomplished.\n * @alpha\n */\nexport interface FinalReviewCompleted<\n\tTIsLlmResponseValid = boolean,\n\tTReviewResponse = TIsLlmResponseValid extends true ? \"yes\" | \"no\" : undefined,\n> extends EventFlowDebugEvent {\n\teventName: \"FINAL_REVIEW_COMPLETED\";\n\teventFlowName: typeof EventFlowDebugNames.FINAL_REVIEW;\n\teventFlowStatus: \"COMPLETED\";\n\t/**\n\t * Whether the response produced by the LLM is an expected response.\n\t * In the event that the LLM fails to respond in an expected way, despite the API call to the LLM itself being successful, then this fields value will be `false`.\n\t *\n\t * For now, this case is limited to the LLM returning undefined as a response when it should have returned something. But in the future this could expand\n\t * to things such as invalid json.\n\t */\n\tisLlmResponseValid: TIsLlmResponseValid;\n\t/**\n\t * Whether the Llm believes the user's ask was accomplished, based on the Edits is has already generated and applied.\n\t * If the `status` field is `false` then this field value will be `undefined`, otherwise it will be either \"yes\" or \"no\"\n\t */\n\tdidLlmAccomplishGoal: TReviewResponse;\n}\n\n// #endregion Generate Final Review Debug events ----------------------\n\n/**\n * An {@link DebugEvent} for an API call directly to a LLM.\n * @alpha\n */\nexport interface LlmApiCallDebugEvent extends DebugEvent {\n\teventName: \"LLM_API_CALL\";\n\t/**\n\t * The event flow name that made this LLM API call.\n\t */\n\ttriggeringEventFlowName: EventFlowDebugName;\n\t/**\n\t * The unique id that will be shared across all debug events that are part of the same event flow.\n\t * @remarks This can be used to correlate all debug events that are part of the same event flow.\n\t */\n\teventFlowTraceId: string;\n\t/**\n\t * The LLM model name that was used for the API call.\n\t */\n\tmodelName: string;\n\t/**\n\t * The request parameters sent in the API call to the LLM. (Not the HTTP request parameters such as headers, etc.)\n\t */\n\trequestParams: unknown;\n\t/**\n\t * The raw response from the LLM.\n\t */\n\tresponse: unknown;\n\t/**\n\t * The total number of tokens used in the API call to the LLM.\n\t */\n\ttokenUsage?: {\n\t\tpromptTokens: number;\n\t\tcompletionTokens: number;\n\t};\n}\n\n/**\n * Creates a base {@link DebugEvent}.\n */\nexport function generateDebugEvent<Tevent extends string>(\n\teventName: Tevent,\n\ttraceId: string,\n): DebugEvent & { eventName: Tevent } {\n\tconst event = {\n\t\teventName,\n\t\tid: uuidv4(),\n\t\ttraceId,\n\t\ttimestamp: new Date().toISOString(),\n\t};\n\treturn event;\n}\n"]}

package/lib/explicit-strategy/index.d.ts

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 import { type TreeNode } from "@fluidframework/tree/internal";
-import type { OpenAiClientOptions, TokenLimits, TokenUsage } from "../aiCollabApi.js";
+import type { DebugEventLogHandler, OpenAiClientOptions, TokenLimits, TokenUsage } from "../aiCollabApi.js";
+export type { ApplyEditFailure, ApplyEditSuccess, CoreEventLoopCompleted, CoreEventLoopStarted, FinalReviewCompleted, FinalReviewStarted, GenerateTreeEditCompleted, GenerateTreeEditStarted, LlmApiCallDebugEvent, PlanningPromptCompleted, PlanningPromptStarted, LlmTreeEdit, EventFlowDebugName, EventFlowDebugNames, } from "./debugEvents.js";
 /**
  * {@link generateTreeEdits} options.
  *
@@ -24,7 +25,7 @@ export interface GenerateTreeEditsOptions {
     };
     finalReviewStep?: boolean;
     validator?: (newContent: TreeNode) => void;
-    dumpDebugLog?: boolean;
+    debugEventLogHandler?: DebugEventLogHandler;
     planningStep?: boolean;
 }
 interface GenerateTreeEditsSuccessResponse {
@@ -33,7 +34,7 @@ interface GenerateTreeEditsSuccessResponse {
 }
 interface GenerateTreeEditsErrorResponse {
     status: "failure" | "partial-failure";
-    errorMessage: "tokenLimitExceeded" | "tooManyErrors" | "tooManyModelCalls" | "aborted";
+    errorMessage: "tokenLimitExceeded" | "tooManyErrors" | "tooManyModelCalls" | "aborted" | "unexpectedError";
     tokensUsed: TokenUsage;
 }
 /**
@@ -47,5 +48,4 @@ interface GenerateTreeEditsErrorResponse {
  * @internal
  */
 export declare function generateTreeEdits(options: GenerateTreeEditsOptions): Promise<GenerateTreeEditsSuccessResponse | GenerateTreeEditsErrorResponse>;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/lib/explicit-strategy/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/explicit-strategy/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAIN,KAAK,QAAQ,EACb,MAAM,+BAA+B,CAAC;AASvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAiBtF;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACxC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE;QACP,iBAAiB,EAAE,MAAM,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,CAAC,EAAE;QACV,eAAe,CAAC,EAAE,eAAe,CAAC;QAClC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,WAAW,CAAC;KAC1B,CAAC;IACF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,KAAK,IAAI,CAAC;IAC3C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,gCAAgC;IACzC,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;CACvB;AAED,UAAU,8BAA8B;IACvC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAAC;IACtC,YAAY,EAAE,oBAAoB,GAAG,eAAe,GAAG,mBAAmB,GAAG,SAAS,CAAC;IACvF,UAAU,EAAE,UAAU,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACtC,OAAO,EAAE,wBAAwB,GAC/B,OAAO,CAAC,gCAAgC,GAAG,8BAA8B,CAAC,CAmG5E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/explicit-strategy/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAIN,KAAK,QAAQ,EACb,MAAM,+BAA+B,CAAC;AAUvC,OAAO,KAAK,EACX,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,MAAM,mBAAmB,CAAC;AAgC3B,YAAY,EACX,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,GACnB,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACxC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE;QACP,iBAAiB,EAAE,MAAM,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,CAAC,EAAE;QACV,eAAe,CAAC,EAAE,eAAe,CAAC;QAClC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,WAAW,CAAC;KAC1B,CAAC;IACF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,KAAK,IAAI,CAAC;IAC3C,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,gCAAgC;IACzC,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;CACvB;AAED,UAAU,8BAA8B;IACvC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAAC;IACtC,YAAY,EACT,oBAAoB,GACpB,eAAe,GACf,mBAAmB,GACnB,SAAS,GACT,iBAAiB,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACtC,OAAO,EAAE,wBAAwB,GAC/B,OAAO,CAAC,gCAAgC,GAAG,8BAA8B,CAAC,CA8I5E"}