From a102e210a1c93406ba575f65cd57036eeb174c0e Mon Sep 17 00:00:00 2001
From: Travis Fischer <fisch0920@gmail.com>
Date: Sun, 16 Jun 2024 19:39:41 -0500
Subject: [PATCH] =?UTF-8?q?=F0=9F=8D=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/types.ts | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/src/types.ts b/src/types.ts
index f4e0b04cd..50bde4aba 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -20,8 +20,13 @@ export type MaybePromise<T> = T | Promise<T>
 export type RelaxedJsonifiable = Jsonifiable | Record<string, Jsonifiable>
 
 export interface AIFunctionSpec {
+  /** AI Function name. */
   name: string
+
+  /** Description of what the function does. */
   description: string
+
+  /** JSON schema spec of the function's input parameters */
   parameters: Record<string, unknown>
 }
 
@@ -36,6 +41,13 @@ export type AIFunctionImpl<Return> = Omit<
   'name' | 'toString' | 'arguments' | 'caller' | 'prototype' | 'length'
 >
 
+/**
+ * Flexible type which accepts any AI-function-like object, including:
+ *   - `AIFunctionSet` - Sets of AI functions
+ *   - `AIFunctionsProvider` - Client classes which expose an `AIFunctionSet`
+ *      via the `.functions` property
+ *   - `AIFunction` - Individual functions
+ */
 export type AIFunctionLike = AIFunctionsProvider | AIFunction | AIFunctionSet
 
 /**
@@ -45,6 +57,11 @@ export interface AIFunction<
   InputSchema extends z.ZodObject<any> = z.ZodObject<any>,
   Return = any
 > {
+  /**
+   * Invokes the underlying AI function `impl` but first validates the input
+   * against this function's `inputSchema`. This method is callable and is
+   * meant to be passed the raw LLM JSON string or an OpenAI-compatible Message.
+   */
   (input: string | Msg): MaybePromise<Return>
 
   /** The Zod schema for the input object. */
@@ -53,10 +70,12 @@ export interface AIFunction<
   /** Parse the function arguments from a message. */
   parseInput(input: string | Msg): z.infer<InputSchema>
 
-  /** The function spec for the OpenAI API `functions` property. */
+  /** The JSON schema function spec for the OpenAI API `functions` property. */
   spec: AIFunctionSpec
 
-  /** The underlying function implementation without any arg parsing or validation. */
+  /**
+   * The underlying function implementation without any arg parsing or validation.
+   */
   // TODO: this `any` shouldn't be necessary, but it is for `createAIFunction` results to be assignable to `AIFunctionLike`
   impl: (params: z.infer<InputSchema> | any) => MaybePromise<Return>
 }