From b0b159a3222152a7b88a4ff386be61ac90a07d1d Mon Sep 17 00:00:00 2001 From: Philipp Burckhardt Date: Mon, 10 Jul 2023 11:23:05 -0400 Subject: [PATCH] docs: add TSDoc comments --- legacy/packages/core/src/agentic.ts | 36 ++++++++++++++++++ legacy/packages/core/src/errors.ts | 14 ++++++- legacy/packages/core/src/events/event.ts | 18 +++++++++ legacy/packages/core/src/events/tracker.ts | 23 ++++++++++-- .../core/src/human-feedback/feedback.ts | 15 ++++++-- legacy/packages/core/src/logger.ts | 37 +++++++++++++++++++ 6 files changed, 135 insertions(+), 8 deletions(-) diff --git a/legacy/packages/core/src/agentic.ts b/legacy/packages/core/src/agentic.ts index 243a9237..c81c1ab2 100644 --- a/legacy/packages/core/src/agentic.ts +++ b/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( promptOrChatCompletionParams: | types.ChatMessageContent diff --git a/legacy/packages/core/src/errors.ts b/legacy/packages/core/src/errors.ts index 6912c1b8..dfbd8a80 100644 --- a/legacy/packages/core/src/errors.ts +++ b/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) diff --git a/legacy/packages/core/src/events/event.ts b/legacy/packages/core/src/events/event.ts index 37a3eeb5..0643e848 100644 --- a/legacy/packages/core/src/events/event.ts +++ b/legacy/packages/core/src/events/event.ts @@ -132,26 +132,44 @@ export enum TaskStatus { export class TaskEvent extends Event< TaskEventPayload > { + /** + * 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' } diff --git a/legacy/packages/core/src/events/tracker.ts b/legacy/packages/core/src/events/tracker.ts index 081cb839..e902e92f 100644 --- a/legacy/packages/core/src/events/tracker.ts +++ b/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(event: TaskEvent): 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 { diff --git a/legacy/packages/core/src/human-feedback/feedback.ts b/legacy/packages/core/src/human-feedback/feedback.ts index e2bf3ca3..d53b0eed 100644 --- a/legacy/packages/core/src/human-feedback/feedback.ts +++ b/legacy/packages/core/src/human-feedback/feedback.ts @@ -46,9 +46,9 @@ export type HumanFeedbackOptions = { * * 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 = { /** * 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 diff --git a/legacy/packages/core/src/logger.ts b/legacy/packages/core/src/logger.ts index 546e171a..8ca15bae 100644 --- a/legacy/packages/core/src/logger.ts +++ b/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