refactored debug log for ai-collab

packages/framework/ai-collab/README.md

@@ -85,7 +85,7 @@ 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"
@@ -145,7 +145,7 @@ const response = await aiCollab({
 		},
 		planningStep: true,
 		finalReviewStep: true,
-		dumpDebugLog: true,
+		debugEventLogHandler: (event: DebugEvent) => {console.log(event);}
 	});
 
 if (response.status === 'sucess') {

packages/framework/ai-collab/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;
+    tokensUsed: TokenUsage;
 }
 
 // @alpha
 export interface AiCollabOptions {
-    readonly dumpDebugLog?: boolean;
+    readonly debugEventLogHandler?: DebugEventLogHandler;
     readonly finalReviewStep?: boolean;
     readonly limiters?: {
         readonly abortController?: AbortController;
@@ -46,6 +46,17 @@ 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;
 

packages/framework/ai-collab/package.json

@@ -114,8 +114,10 @@
 		"@fluidframework/runtime-utils": "workspace:~",
 		"@fluidframework/telemetry-utils": "workspace:~",
 		"@fluidframework/tree": "workspace:~",
+		"@types/uuid": "^9.0.2",
 		"openai": "^4.67.3",
 		"typechat": "^0.1.1",
+		"uuid": "^9.0.0",
 		"zod": "^3.23.8"
 	},
 	"devDependencies": {
@@ -142,7 +144,8 @@
 		"mocha-multi-reporters": "^1.5.1",
 		"prettier": "~3.0.3",
 		"rimraf": "^4.4.0",
-		"typescript": "~5.4.5"
+		"typescript": "~5.4.5",
+		"uuid": "^9.0.0"
 	},
 	"fluidBuild": {
 		"tasks": {

packages/framework/ai-collab/src/aiCollab.ts

@@ -53,7 +53,6 @@ import { generateTreeEdits } from "./explicit-strategy/index.js";
  * 		},
  * 		planningStep: true,
  * 		finalReviewStep: true,
- * 		dumpDebugLog: true,
  * 	});
  * ```
  *
@@ -77,9 +76,9 @@ export async function aiCollab(
 		openAI: options.openAI,
 		prompt: options.prompt,
 		limiters: options.limiters,
-		dumpDebugLog: options.dumpDebugLog,
 		planningStep: options.planningStep,
 		finalReviewStep: options.finalReviewStep,
+		debugEventLogHandler: options.debugEventLogHandler,
 	});
 
 	return response;

packages/framework/ai-collab/src/aiCollabApi.ts

@@ -7,6 +7,55 @@ import type { TreeNode } from "@fluidframework/tree";
 // eslint-disable-next-line import/no-named-as-default
 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";
+	/**
+	 * 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.
  *
@@ -99,9 +148,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;
 }
 
 /**
@@ -139,16 +188,18 @@ 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";
+		| "aborted"
+		| "unexpectedError";
 	/**
 	 * {@inheritDoc TokenUsage}
 	 */
-	readonly tokensUsed: TokenUsage;
+	tokensUsed: TokenUsage;
 }
 
 /**