@fluidframework/ai-collab 2.22.1 → 2.23.0

package/dist/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/dist/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/dist/explicit-strategy/debugEvents.js

@@ -0,0 +1,36 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDebugEvent = exports.EventFlowDebugNames = void 0;
+const uuid_1 = require("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
+ */
+exports.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}.
+ */
+function generateDebugEvent(eventName, traceId) {
+    const event = {
+        eventName,
+        id: (0, uuid_1.v4)(),
+        traceId,
+        timestamp: new Date().toISOString(),
+    };
+    return event;
+}
+exports.generateDebugEvent = generateDebugEvent;
+//# sourceMappingURL=debugEvents.js.map

package/dist/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,+BAAoC;AAIpC;;;GAGG;AAEH;;;GAGG;AACU,QAAA,mBAAmB,GAAG;IAClC,eAAe,EAAE,iBAAiB;IAClC,wBAAwB,EAAE,0BAA0B;IACpD,4BAA4B,EAAE,8BAA8B;IAC5D,YAAY,EAAE,cAAc;CACnB,CAAC;AAmQX;;GAEG;AACH,SAAgB,kBAAkB,CACjC,SAAiB,EACjB,OAAe;IAEf,MAAM,KAAK,GAAG;QACb,SAAS;QACT,EAAE,EAAE,IAAA,SAAM,GAAE;QACZ,OAAO;QACP,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACnC,CAAC;IACF,OAAO,KAAK,CAAC;AACd,CAAC;AAXD,gDAWC","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/dist/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/dist/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"}