@fluidframework/ai-collab Package

Experimental package for utilities that enable/simplify interaction with LLMs for apps based on SharedTree.

See README.md for an overview of the package.

Interfaces

Interface	Alerts	Description
AiCollabErrorResponse	Alpha	An error response from the AI collaboration.
AiCollabOptions	Alpha	Options for the AI collaboration.
AiCollabSuccessResponse	Alpha	A successful response from the AI collaboration.
DifferenceChange	Alpha	Represents a change operation between two branches of a tree. Meaning that an attribute (a shared tree node) was identified as being changed from one value to another.
DifferenceCreate	Alpha	Represents a create operation between two branches of a tree. Meaning that an attribute (a shared tree node) was identified as being created.
DifferenceMove	Alpha	Represents a move operation between two branches of a tree. Meaning that an object (shared tree node) was identified as being moved from one index to another based on its unique id.
DifferenceRemove	Alpha	Represents a remove operation between two branches of a tree. Meaning that an attribute (a shared tree node) was identified as being deleted. When using object ids, removes are idenitified by an object with a given id no longer existing.
OpenAiClientOptions	Alpha	OpenAI client options for the AiCollabOptions interface.
Options	Alpha	Options for tree diffing.
TokenLimits	Alpha	Maximum limits for the total tokens that can be used by an llm
TokenUsage	Alpha	Total usage of tokens by an LLM.

Classes

Class	Alerts	Description
SharedTreeBranchManager	Alpha	Manages determining the differences between two branches of a SharedTree represented as an actual tree node or a plain javascript object and applies said differences to the original SharedTree branch.

Types

TypeAlias	Alerts	Description
Difference	Alpha	Union for all possible difference types.
ObjectPath	Alpha	Represents a path through a tree of objects. number values represent array indices whereas string values represent object keys.

Functions

Function	Alerts	Return Type	Description
aiCollab(options)	Alpha	Promise<AiCollabSuccessResponse | AiCollabErrorResponse>	Calls an LLM to modify the provided SharedTree in a series of real time edits based on the provided users prompt input.
createMergableDiffSeries(diffs)	Alpha	Difference[]	Creates a set of mergeable diffs from a series of diffs produced by sharedTreeDiff(obj, newObj, options, _stack) that AREN'T using the object ID strategy. These diffs don't need any modifications to be applied to the old object.
createMergableIdDiffSeries(oldObject, diffs, idAttributeName)	Alpha	Difference[]	Creates a set of mergeable diffs from a series of diffs produced by sharedTreeDiff(obj, newObj, options, _stack) that are using the object ID strategy. These diffs don't need any modifications to be applied to the old object.
sharedTreeDiff(obj, newObj, options, _stack)	Alpha	Difference[]	Compares two objects and returns an array of differences between them.
sharedTreeTraverse(jsonObject, path)	Alpha	T | undefined	Traverses the provided ObjectPath on the provided Shared Tree or JSON object and returns the value at the end of the path.

Function Details

aiCollab

Calls an LLM to modify the provided SharedTree in a series of real time edits based on the provided users prompt input.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/ai-collab/alpha.

For more information about our API support guarantees, see here.

Signature

export declare function aiCollab(options: AiCollabOptions): Promise<AiCollabSuccessResponse | AiCollabErrorResponse>;

Remarks

Known Limitiations: - Root level array nodes are not supported - Nested arrays are not supported - Primitive nodes are not supported, e.g. 'string', 'number', 'boolean' - Your application's Shared Tree schema must have no more than 4 levels of nesting - Optional nodes are not supported in the Shared Tree schema - Union types are not supported in the Shared Tree schema - See README for more details.

Example

import {
	SchemaFactory,
	TreeViewConfiguration,
	type TreeView
} from "@fluidframework/tree";
const sf = new SchemaFactory("todo-app");
class TodoTask extends sf.object("TodoTask", {
	title: sf.string,
	description: sf.string,
}) {}
class TodoAppState extends sf.object("TodoAppState", {
	tasks: sf.array(TodoTask),
}) {}
// Initialize your SharedTree
const treeView: TreeView = tree.viewWith(new TreeViewConfiguration({ schema: TodoAppState }));
treeView.initialize({ tasks: [] });
// Collaborate with AI in realtime in just one function call.
const response = await aiCollab({
		openAI: {
			client: new OpenAI({
				apiKey: OPENAI_API_KEY,
			}),
			modelName: "gpt-4o",
		},
		treeNode: view.root,
		prompt: {
			systemRoleContext:
				"You are an helpful assistant managing a todo list for a user.",
			userAsk: "Create a set of new todos to plan a vacation to Cancun.",
		},
		planningStep: true,
		finalReviewStep: true,
		dumpDebugLog: true,
	});

Parameters

Parameter	Type	Description
options	AiCollabOptions

Returns

Return type: Promise<AiCollabSuccessResponse | AiCollabErrorResponse>

createMergableDiffSeries

Creates a set of mergeable diffs from a series of diffs produced by sharedTreeDiff(obj, newObj, options, _stack) that AREN'T using the object ID strategy. These diffs don't need any modifications to be applied to the old object.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/ai-collab/alpha.

For more information about our API support guarantees, see here.

Signature

export declare function createMergableDiffSeries(diffs: Difference[]): Difference[];

Parameters

Parameter	Type	Description
diffs	Difference[]

Returns

Return type: Difference[]

createMergableIdDiffSeries

Creates a set of mergeable diffs from a series of diffs produced by sharedTreeDiff(obj, newObj, options, _stack) that are using the object ID strategy. These diffs don't need any modifications to be applied to the old object.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/ai-collab/alpha.

For more information about our API support guarantees, see here.

Signature

export declare function createMergableIdDiffSeries(oldObject: unknown, diffs: Difference[], idAttributeName: string | number): Difference[];

Parameters

Parameter	Type	Description
oldObject	unknown
diffs	Difference[]
idAttributeName	string | number

Returns

Return type: Difference[]

sharedTreeDiff

Compares two objects and returns an array of differences between them.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/ai-collab/alpha.

For more information about our API support guarantees, see here.

Signature

export declare function sharedTreeDiff(obj: Record<string, unknown> | unknown[], newObj: Record<string, unknown> | unknown[], options?: Options, _stack?: (Record<string, unknown> | unknown[])[]): Difference[];

Parameters

Parameter	Modifiers	Type	Description
obj		Record<string, unknown> | unknown[]
newObj		Record<string, unknown> | unknown[]
options	optional	Options
_stack	optional	(Record<string, unknown> | unknown[])[]

Returns

Return type: Difference[]

sharedTreeTraverse

Traverses the provided ObjectPath on the provided Shared Tree or JSON object and returns the value at the end of the path.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/ai-collab/alpha.

For more information about our API support guarantees, see here.

Signature

export declare function sharedTreeTraverse<T = unknown>(jsonObject: TreeMapNode | TreeArrayNode | Record<string, unknown>, path: ObjectPath): T | undefined;

Type Parameters

Parameter	Default	Description
T	unknown

Parameters

Parameter	Type	Description
jsonObject	TreeMapNode | TreeArrayNode | Record<string, unknown>
path	ObjectPath

Returns

Return type: T | undefined