docs: add TSDoc comments

legacy/packages/core/src/agentic.ts

@@ -13,6 +13,12 @@ import { defaultLogger } from './logger'
 import { openaiModelDefaults } from './model_defaults'
 import { defaultIDGeneratorFn, isFunction, isString } from './utils'
 
+/**
+ * Main entrypoint for using Agentic to build AI-powered applications.
+ *
+ * -   It provides a set of common functionality and configuration defaults, which are shared across all tools and tasks.
+ * -   You will usually want to create a single Agentic instance and use it throughout your application.
+ */
 export class Agentic extends EventEmitter {
   protected _ky: types.KyInstance
   protected _logger: types.Logger
@@ -71,6 +77,8 @@ export class Agentic extends EventEmitter {
 
       /**
        * A task tracker or `false` to disable. By default, tasks will be tracked via the terminal (assuming `stderr` is a TTY).
+       *
+       * You can also pass in a custom tracker to track tasks in a different way (e.g. via a database or web UI) by extending the `TaskTracker` class.
        */
       taskTracker?: TaskTracker | false
     } = {}
@@ -115,34 +123,62 @@ export class Agentic extends EventEmitter {
     this._id = this._idGeneratorFn()
   }
 
+  /**
+   * OpenAI client used for making requests to the OpenAI API.
+   */
   public get openai(): types.openai.OpenAIClient | undefined {
     return this._openai
   }
 
+  /**
+   * Anthropic client used for making requests to the Anthropic API.
+   */
   public get anthropic(): types.anthropic.Anthropic | undefined {
     return this._anthropic
   }
 
+  /**
+   * Ky instance used for making HTTP requests.
+   */
   public get ky(): types.KyInstance {
     return this._ky
   }
 
+  /**
+   * Logger used for logging events of various severities.
+   */
   public get logger(): types.Logger {
     return this._logger
   }
 
+  /**
+   * Default option values when requesting human feedback in tasks.
+   */
   public get humanFeedbackDefaults() {
     return this._humanFeedbackDefaults
   }
 
+  /**
+   * Task tracker used for tracking tasks.
+   */
   public get taskTracker(): TaskTracker {
     return this._taskTracker
   }
 
+  /**
+   * Function used to generate a unique identifier for each task.
+   */
   public get idGeneratorFn(): types.IDGeneratorFunction {
     return this._idGeneratorFn
   }
 
+  /**
+   * Creates an OpenAI chat completion.
+   *
+   * @param promptOrChatCompletionParams - prompt to send to the OpenAI API or an object containing the chat completion parameters
+   * @param modelParams - additional parameters to pass to the OpenAI API
+   * @returns chat completion
+   */
   openaiChatCompletion<TInput extends types.TaskInput = void>(
     promptOrChatCompletionParams:
       | types.ChatMessageContent<TInput>

legacy/packages/core/src/errors.ts

@@ -4,8 +4,11 @@ import type { Jsonifiable } from 'type-fest'
 import type { ZodError } from 'zod'
 import { ValidationError, fromZodError } from 'zod-validation-error'
 
-export { TimeoutError, KyTimeoutError }
+export { KyTimeoutError, TimeoutError }
 
+/**
+ * Options for creating an error.
+ */
 export type ErrorOptions = {
   /** HTTP status code for the error. */
   status?: number
@@ -58,6 +61,9 @@ export class OpenAIApiError extends BaseError {
   }
 }
 
+/**
+ * An error thrown when an output fails to validate against its Zod schema.
+ */
 export class ZodOutputValidationError extends BaseError {
   validationError: ValidationError
 
@@ -71,6 +77,9 @@ export class ZodOutputValidationError extends BaseError {
   }
 }
 
+/**
+ * An error thrown when an output fails validation (e.g., by not being valid JSON).
+ */
 export class OutputValidationError extends BaseError {
   constructor(message: string, opts: ErrorOptions = {}) {
     super(message, opts)
@@ -79,6 +88,9 @@ export class OutputValidationError extends BaseError {
   }
 }
 
+/**
+ * An error thrown when a handlebars template fails to compile.
+ */
 export class TemplateValidationError extends BaseError {
   constructor(message: string, opts: ErrorOptions = {}) {
     super(message, opts)

legacy/packages/core/src/events/event.ts

@@ -132,26 +132,44 @@ export enum TaskStatus {
 export class TaskEvent<TInput, TOutput> extends Event<
   TaskEventPayload<TInput, TOutput>
 > {
+  /**
+   * Task name.
+   */
   get name(): string {
     return this.payload?.taskName ?? ''
   }
 
+  /**
+   * Unique task identifier.
+   */
   get taskId(): string {
     return this.payload?.taskId ?? ''
   }
 
+  /**
+   * Task status.
+   */
   get status(): TaskStatus {
     return this.payload?.taskStatus ?? TaskStatus.RUNNING
   }
 
+  /**
+   * Task inputs.
+   */
   get inputs(): any {
     return this.payload?.taskInputs ?? ''
   }
 
+  /**
+   * Task output.
+   */
   get output(): any {
     return this.payload?.taskOutput ?? ''
   }
 
+  /**
+   * Unique identifier of the parent task (or `'root'` if it is a top-level task).
+   */
   get parentTaskId(): string {
     return this.payload?.parentTaskId ?? 'root'
   }

legacy/packages/core/src/events/tracker.ts

@@ -21,12 +21,30 @@ const originalStdoutWrite = process.stdout.write
 const originalStderrWrite = process.stderr.write
 
 export abstract class TaskTracker {
+  /**
+   * Starts the task tracker.
+   */
   abstract start(): void
+
+  /**
+   * Closes the task tracker and cleans up any resources.
+   */
   abstract close(): void
+
+  /**
+   * Pauses the task tracker temporarily.
+   */
   abstract pause(message?: string): void
+
+  /**
+   * Resumes the task tracker after it has been paused.
+   */
   abstract resume(): void
+
+  /**
+   * Registers a new task event with the tracker.
+   */
   abstract addEvent<TInput, TOutput>(event: TaskEvent<TInput, TOutput>): void
-  abstract render(): void
 }
 
 export class DummyTaskTracker extends TaskTracker {
@@ -45,9 +63,6 @@ export class DummyTaskTracker extends TaskTracker {
   addEvent(): void {
     // Does nothing
   }
-  render(): void {
-    // Does nothing
-  }
 }
 
 export interface TerminalTaskTrackerOptions {

legacy/packages/core/src/human-feedback/feedback.ts

@@ -46,9 +46,9 @@ export type HumanFeedbackOptions<T extends HumanFeedbackType, TOutput> = {
    *
    * Possible values:
    *
-   * - `'confirm'`: The user is asked to confirm the generated output of the task.
-   * - `'select'`: The user is asked to select exactly one of the outputs to keep (assumes output is an array).
-   * - `'multiselect'`: The user is asked to select any number of outputs to keep (assumes output is an array).
+   * -   `'confirm'`: The user is asked to confirm the generated output of the task.
+   * -   `'select'`: The user is asked to select exactly one of the outputs to keep (assumes output is an array).
+   * -   `'multiselect'`: The user is asked to select any number of outputs to keep (assumes output is an array).
    */
   type?: T
 
@@ -69,6 +69,15 @@ export type HumanFeedbackOptions<T extends HumanFeedbackType, TOutput> = {
 
   /**
    * The human feedback mechanism to use for this task. By default, human feedback is requested via the CLI.
+   *
+   * Possible feedback mechanisms to provide include:
+   *
+   * -   `HumanFeedbackMechanismCLI`: Requests feedback via the CLI.
+   * -   `HumanFeedbackMechanismSlack`: Requests feedback via Slack.
+   * -   `HumanFeedbackMechanismTwilio`: Requests feedback via SMS.
+   * -   `HumanFeedbackMechanismDummy`: Requests feedback via a dummy mechanism that does nothing.
+   *
+   * You can also provide your own custom feedback mechanism by extending the `HumanFeedbackMechanism` class and implementing the required methods.
    */
   mechanism?: HumanFeedbackMechanismConstructor<T, TOutput>
 

legacy/packages/core/src/logger.ts

@@ -78,26 +78,63 @@ logger.formatArgs = function formatArgs(args) {
  * Default `debug` logger with methods that log to the console with the respective severity level.
  */
 export const defaultLogger = {
+  /**
+   * Debug-level logs, providing detailed information for development and debugging.
+   *
+   * @param formatter - formatter to structure the log message
+   * @param args - arguments to be logged
+   */
   debug: (formatter: any, ...args: any[]) => {
     if (LOG_LEVEL > Severity.DEBUG) return
     debug(formatter, ...args, Severity.DEBUG)
   },
+
+  /**
+   * Info-level logs, indicating that the system is functioning normally.
+   *
+   * @param formatter - formatter to structure the log message
+   * @param args - arguments to be logged
+   */
   info: (formatter: any, ...args: any[]) => {
     if (LOG_LEVEL > Severity.INFO) return
     debug(formatter, ...args, Severity.INFO)
   },
+
+  /**
+   * Warning-level logs, indicating that the system encountered unexpected events or behavior.
+   *
+   * @param formatter - formatter to structure the log message
+   * @param args - arguments to be logged
+   */
   warn: (formatter: any, ...args: any[]) => {
     if (LOG_LEVEL > Severity.WARNING) return
     debug(formatter, ...args, Severity.WARNING)
   },
+
+  /**
+   * Error-level logs, indicating that the system encountered errors.
+   *
+   * @param formatter - formatter to structure the log message
+   * @param args - arguments to be logged
+   */
   error: (formatter: any, ...args: any[]) => {
     if (LOG_LEVEL > Severity.ERROR) return
     debug(formatter, ...args, Severity.ERROR)
   },
+
+  /**
+   * Critical-level logs, indicating that the system encountered errors and might not be able to function properly.
+   *
+   * @param formatter - formatter to structure the log message
+   * @param args - arguments to be logged
+   */
   critical: (formatter: any, ...args: any[]) => {
     if (LOG_LEVEL > Severity.CRITICAL) return
     debug(formatter, ...args, Severity.CRITICAL)
   }
 }
 
+/**
+ * Logger type with methods for logging at various levels of severity.
+ */
 export type Logger = typeof defaultLogger