diff --git a/genaisrc/genaiscript.d.ts b/genaisrc/genaiscript.d.ts index 497ae27aa..f21ea5fbf 100644 --- a/genaisrc/genaiscript.d.ts +++ b/genaisrc/genaiscript.d.ts @@ -1,4 +1,4 @@ -interface PromptConsole { +interface PromptGenerationConsole { log(...data: any[]): void warn(...data: any[]): void debug(...data: any[]): void @@ -12,6 +12,10 @@ interface Diagnostic { range: CharRange severity: DiagnosticSeverity message: string + /** + * error or warning code + */ + code?: string } type Awaitable = T | PromiseLike @@ -61,9 +65,37 @@ interface PromptLike extends PromptDefinition { text?: string } -type SystemPromptId = "system" | "system.annotations" | "system.changelog" | "system.diff" | "system.explanations" | "system.files" | "system.files_schema" | "system.fs_find_files" | "system.fs_read_file" | "system.fs_read_summary" | "system.functions" | "system.json" | "system.math" | "system.python" | "system.retrieval_fuzz_search" | "system.retrieval_vector_search" | "system.retrieval_web_search" | "system.schema" | "system.tasks" | "system.technical" | "system.typescript" | "system.zero_shot_cot" - -type SystemToolId = "fs_find_files" | "fs_read_file" | "fs_read_summary" | "math_eval" | "retrieval_fuzz_search" | "retrieval_vector_search" | "retrieval_web_search" +type SystemPromptId = + | "system" + | "system.annotations" + | "system.changelog" + | "system.diff" + | "system.explanations" + | "system.files" + | "system.files_schema" + | "system.fs_find_files" + | "system.fs_read_file" + | "system.fs_read_summary" + | "system.functions" + | "system.math" + | "system.python" + | "system.retrieval_fuzz_search" + | "system.retrieval_vector_search" + | "system.retrieval_web_search" + | "system.schema" + | "system.tasks" + | "system.technical" + | "system.typescript" + | "system.zero_shot_cot" + +type SystemToolId = + | "fs_find_files" + | "fs_read_file" + | "fs_read_summary" + | "math_eval" + | "retrieval_fuzz_search" + | "retrieval_vector_search" + | "retrieval_web_search" type FileMergeHandler = ( filename: string, @@ -106,13 +138,12 @@ interface ModelConnectionOptions { * @example gpt-4 gpt-4-32k gpt-3.5-turbo ollama:phi3 ollama:llama3 ollama:mixtral aici:mixtral */ model?: - | "gpt-4" - | "gpt-4-32k" - | "gpt-3.5-turbo" + | "openai:gpt-4" + | "openai:gpt-4-32k" + | "openai:gpt-3.5-turbo" | "ollama:phi3" | "ollama:llama3" | "ollama:mixtral" - | "aici:mixtral" | string } @@ -125,6 +156,17 @@ interface ModelOptions extends ModelConnectionOptions { */ temperature?: number + /** + * Specifies the type of output. Default is `markdown`. Use `responseSchema` to + * specify an output schema. + */ + responseType?: PromptTemplateResponseType + + /** + * JSON object schema for the output. Enables the `JSON` output mode. + */ + responseSchema?: JSONSchemaObject + /** * “Top_p” or nucleus sampling is a setting that decides how many possible words to consider. * A high “top_p” value means the model looks at more possible words, even the less likely ones, @@ -143,6 +185,11 @@ interface ModelOptions extends ModelConnectionOptions { */ maxToolCalls?: number + /** + * Maximum number of data repairs to attempt. + */ + maxDataRepairs?: number + /** * A deterministic integer seed to use for the model. */ @@ -160,56 +207,59 @@ interface ModelOptions extends ModelConnectionOptions { cacheName?: string } -interface ScriptRuntimeOptions { -/** -* System prompt identifiers ([reference](https://microsoft.github.io/genaiscript/reference/scripts/system/)) -* - `system`: Base system prompt -* - `system.annotations`: Emits annotations compatible with GitHub Actions -* - `system.changelog`: Generate changelog formatter edits -* - `system.diff`: Generates concise file diffs. -* - `system.explanations`: Explain your answers -* - `system.files`: File generation -* - `system.files_schema`: Apply JSON schemas to generated data. -* - `system.fs_find_files`: File Find Files -* - `system.fs_read_file`: File Read File -* - `system.fs_read_summary`: File Read Summary -* - `system.functions`: use functions -* - `system.json`: JSON system prompt -* - `system.math`: Math expression evaluator -* - `system.python`: Expert at generating and understanding Python code. -* - `system.retrieval_fuzz_search`: Full Text Fuzzy Search -* - `system.retrieval_vector_search`: Embeddings Vector Search -* - `system.retrieval_web_search`: Web Search -* - `system.schema`: JSON Schema support -* - `system.tasks`: Generates tasks -* - `system.technical`: Technical Writer -* - `system.typescript`: Export TypeScript Developer -* - `system.zero_shot_cot`: Zero-shot Chain Of Though -**/ - system?: SystemPromptId[] +interface EmbeddingsModelConnectionOptions { + /** + * LLM model to use for embeddings. + */ + embeddingsModel?: "openai:text-embedding-ada-002" | string +} -/** -* System tool identifiers ([reference](https://microsoft.github.io/genaiscript/reference/scripts/tools/)) -* - `fs_find_files`: Finds file matching a glob pattern. -* - `fs_read_file`: Reads a file as text from the file system. -* - `fs_read_summary`: Reads a summary of a file from the file system. -* - `math_eval`: Evaluates a math expression -* - `retrieval_fuzz_search`: Search for keywords using the full text of files and a fuzzy distance. -* - `retrieval_vector_search`: Search files using embeddings and similarity distance. -* - `retrieval_web_search`: Search the web for a user query using Bing Search. -**/ - tools?: SystemToolId[] +interface EmbeddingsModelOptions extends EmbeddingsModelConnectionOptions {} +interface ScriptRuntimeOptions { /** - * Specifies the type of output. Default is `markdown`. Use `responseSchema` to - * specify an output schema. - */ - responseType?: PromptTemplateResponseType + * List of system script ids used by the prompt. + */ + /** + * System prompt identifiers ([reference](https://microsoft.github.io/genaiscript/reference/scripts/system/)) + * - `system`: Base system prompt + * - `system.annotations`: Emits annotations compatible with GitHub Actions + * - `system.changelog`: Generate changelog formatter edits + * - `system.diff`: Generates concise file diffs. + * - `system.explanations`: Explain your answers + * - `system.files`: File generation + * - `system.files_schema`: Apply JSON schemas to generated data. + * - `system.fs_find_files`: File Find Files + * - `system.fs_read_file`: File Read File + * - `system.fs_read_summary`: File Read Summary + * - `system.functions`: use functions + * - `system.math`: Math expression evaluator + * - `system.python`: Expert at generating and understanding Python code. + * - `system.retrieval_fuzz_search`: Full Text Fuzzy Search + * - `system.retrieval_vector_search`: Embeddings Vector Search + * - `system.retrieval_web_search`: Web Search + * - `system.schema`: JSON Schema support + * - `system.tasks`: Generates tasks + * - `system.technical`: Technical Writer + * - `system.typescript`: Export TypeScript Developer + * - `system.zero_shot_cot`: Zero-shot Chain Of Though + **/ + system?: SystemPromptId[] /** - * JSON object schema for the output. Enables the `JSON` output mode. + * List of tools used by the prompt. */ - responseSchema?: JSONSchemaObject + /** + * System tool identifiers ([reference](https://microsoft.github.io/genaiscript/reference/scripts/tools/)) + * - `fs_find_files`: Finds file matching a glob pattern. + * - `fs_read_file`: Reads a file as text from the file system. + * - `fs_read_summary`: Reads a summary of a file from the file system. + * - `math_eval`: Evaluates a math expression + * - `retrieval_fuzz_search`: Search for keywords using the full text of files and a fuzzy distance. + * - `retrieval_vector_search`: Search files using embeddings and similarity distance. + * - `retrieval_web_search`: Search the web for a user query using Bing Search. + **/ + tools?: SystemToolId[] /** * Secrets required by the prompt @@ -311,7 +361,7 @@ interface PromptTest { */ keywords?: string | string[] /** - * List of keywords that should not be contained in the LLM output. + * List of keywords that should not be contained in the LLM output. */ forbidden?: string | string[] /** @@ -320,7 +370,11 @@ interface PromptTest { asserts?: PromptAssertion | PromptAssertion[] } -interface PromptScript extends PromptLike, ModelOptions, ScriptRuntimeOptions { +interface PromptScript + extends PromptLike, + ModelOptions, + EmbeddingsModelOptions, + ScriptRuntimeOptions { /** * Groups template in UI */ @@ -332,7 +386,7 @@ interface PromptScript extends PromptLike, ModelOptions, ScriptRuntimeOptions { parameters?: PromptParametersSchema /** - * A file path or list of file paths or globs. + * A file path or list of file paths or globs. * The content of these files will be by the files selected in the UI by the user or the cli arguments. */ files?: string | string[] @@ -380,7 +434,7 @@ interface WorkspaceFileWithScore extends WorkspaceFile { score?: number } -interface ChatFunctionDefinition { +interface ToolDefinition { /** * The name of the function to be called. Must be a-z, A-Z, 0-9, or contain * underscores and dashes, with a maximum length of 64. @@ -405,7 +459,7 @@ interface ChatFunctionDefinition { parameters?: JSONSchema } -interface ChatFunctionCallTrace { +interface ToolCallTrace { log(message: string): void item(message: string): void tip(message: string): void @@ -431,6 +485,7 @@ interface FileEdit { type: string filename: string label?: string + validated?: boolean } interface ReplaceEdit extends FileEdit { @@ -459,35 +514,52 @@ interface CreateFileEdit extends FileEdit { type Edits = InsertEdit | ReplaceEdit | DeleteEdit | CreateFileEdit -interface ChatFunctionCallContent { +interface ToolCallContent { type?: "content" content: string edits?: Edits[] } -type ChatFunctionCallOutput = string | ChatFunctionCallContent +type ToolCallOutput = string | ToolCallContent | ShellOutput interface WorkspaceFileSystem { /** * Searches for files using the glob pattern and returns a list of files. - * If the file is text, also return the content. + * Ignore `.env` files and apply `.gitignore` if present. * @param glob */ findFiles( glob: string, options?: { /** - * Set to false to read text content by default + * Set to false to skip read text content. True by default */ readText?: boolean } ): Promise + + /** + * Performs a grep search over the files in the workspace + * @param query + * @param globs + */ + grep( + query: string | RegExp, + globs: string | string[] + ): Promise<{ files: WorkspaceFile[] }> + /** * Reads the content of a file as text * @param path */ readText(path: string | WorkspaceFile): Promise + /** + * Reads the content of a file and parses to JSON, using the JSON5 parser. + * @param path + */ + readJSON(path: string | WorkspaceFile): Promise + /** * Writes a file as text to the file system * @param path @@ -496,15 +568,29 @@ interface WorkspaceFileSystem { writeText(path: string, content: string): Promise } -interface ChatFunctionCallContext { - trace: ChatFunctionCallTrace +interface ToolCallContext { + trace: ToolCallTrace } -interface ChatFunctionCallback { - definition: ChatFunctionDefinition +interface ToolCallback { + definition: ToolDefinition fn: ( - args: { context: ChatFunctionCallContext } & Record - ) => ChatFunctionCallOutput | Promise + args: { context: ToolCallContext } & Record + ) => ToolCallOutput | Promise +} + +type ChatParticipantHandler = ( + context: ChatTurnGenerationContext, + messages: ChatCompletionMessageParam[] +) => Awaitable + +interface ChatParticipantOptions { + label?: string +} + +interface ChatParticipant { + generator: ChatParticipantHandler + options: ChatParticipantOptions } /** @@ -512,9 +598,9 @@ interface ChatFunctionCallback { */ interface ExpansionVariables { /** - * Description of the context as markdown; typically the content of a .gpspec.md file. + * Directory where the prompt is executed */ - spec: WorkspaceFile + dir: string /** * List of linked files parsed in context @@ -532,9 +618,14 @@ interface ExpansionVariables { vars: PromptParameters /** - * List of secrets used by the prompt, must be registred in `genaiscript`. + * List of secrets used by the prompt, must be registered in `genaiscript`. */ secrets?: Record + + /** + * Root prompt generation context + */ + generator: ChatGenerationContext } type MakeOptional = Partial> & Omit @@ -544,6 +635,7 @@ type PromptArgs = Omit type PromptSystemArgs = Omit< PromptArgs, | "model" + | "embeddingsModel" | "temperature" | "topP" | "maxTokens" @@ -749,6 +841,12 @@ interface Path { * @param pathSegments */ resolve(...pathSegments: string[]): string + + /** + * Determines whether the path is an absolute path. + * @param path + */ + isAbsolute(path: string): boolean } interface Fenced { @@ -807,6 +905,13 @@ interface Parsers { content: string | WorkspaceFile, options?: { defaultValue?: any } ): any | undefined + + /** + * Parses text or file as a JSONL payload. Empty lines are ignore, and JSON5 is used for parsing. + * @param content + */ + JSONL(content: string | WorkspaceFile): any[] | undefined + /** * Parses text as a YAML paylaod */ @@ -1025,6 +1130,19 @@ interface XML { parse(text: string): any } +interface JSONL { + /** + * Parses a JSONL string to an array of objects + * @param text + */ + parse(text: string): any[] + /** + * Converts objects to JSONL format + * @param objs + */ + stringify(objs: any[]): string +} + interface INI { /** * Parses a .ini file @@ -1058,7 +1176,7 @@ interface CSV { * @param csv * @param options */ - mardownify(csv: object[], options?: { headers?: string[] }): string + markdownify(csv: object[], options?: { headers?: string[] }): string } interface HighlightOptions { @@ -1069,25 +1187,15 @@ interface WebSearchResult { webPages: WorkspaceFile[] } -interface VectorSearchOptions { - indexName?: string -} - -interface VectorSearchEmbeddingsOptions extends VectorSearchOptions { - llmModel?: string +interface VectorSearchOptions extends EmbeddingsModelOptions { /** - * Model used to generated models. - * ollama:nomic-embed-text ollama:all-minilm + * Maximum number of embeddings to use */ - embedModel?: - | "text-embedding-ada-002" - | "ollama:mxbai-embed-large" - | "ollama:nomic-embed-text" - | "ollama:all-minilm" - | string - temperature?: number - chunkSize?: number - chunkOverlap?: number + topK?: number + /** + * Minimum similarity score + */ + minScore?: number } interface FuzzSearchOptions { @@ -1145,20 +1253,7 @@ interface Retrieval { vectorSearch( query: string, files: (string | WorkspaceFile) | (string | WorkspaceFile)[], - options?: { - /** - * Maximum number of embeddings to use - */ - topK?: number - /** - * Minimum similarity score - */ - minScore?: number - /** - * Specifies the type of output. `chunk` returns individual chunks of the file, fill returns a reconstructed file from chunks. - */ - outputType?: "file" | "chunk" - } & Omit + options?: VectorSearchOptions ): Promise /** @@ -1211,12 +1306,15 @@ interface DefDataOptions } interface DefSchemaOptions { + /** + * Output format in the prompt. + */ format?: "typescript" | "json" | "yaml" } type ChatFunctionHandler = ( - args: { context: ChatFunctionCallContext } & Record -) => ChatFunctionCallOutput | Promise + args: { context: ToolCallContext } & Record +) => ToolCallOutput | Promise interface WriteTextOptions extends ContextExpansionOptions { /** @@ -1225,17 +1323,29 @@ interface WriteTextOptions extends ContextExpansionOptions { assistant?: boolean } -type RunPromptGenerator = (ctx: RunPromptContext) => Awaitable +type PromptGenerator = (ctx: ChatGenerationContext) => Awaitable -interface RunPromptOptions extends ModelOptions { +interface PromptGeneratorOptions extends ModelOptions { /** * Label for trace */ label?: string } -// keep in sync with prompt_type.d.ts -interface RunPromptContext { +interface FileOutputOptions { + /** + * Schema identifier to validate the generated file + */ + schema?: string +} + +interface FileOutput { + pattern: string + description: string + options?: FileOutputOptions +} + +interface ChatTurnGenerationContext { writeText(body: Awaitable, options?: WriteTextOptions): void $(strings: TemplateStringsArray, ...args: any[]): void fence(body: StringLike, options?: FenceOptions): void @@ -1245,22 +1355,37 @@ interface RunPromptContext { data: object[] | object, options?: DefDataOptions ): string + console: PromptGenerationConsole +} + +interface FileUpdate { + before: string + after: string + validation?: JSONSchemaValidation +} + +interface ChatGenerationContext extends ChatTurnGenerationContext { defSchema( name: string, schema: JSONSchema, options?: DefSchemaOptions ): string - runPrompt( - generator: string | RunPromptGenerator, - options?: RunPromptOptions - ): Promise + defImages(files: StringLike, options?: DefImagesOptions): void defTool( name: string, description: string, parameters: PromptParametersSchema | JSONSchema, fn: ChatFunctionHandler ): void - console: PromptConsole + defChatParticipant( + participant: ChatParticipantHandler, + options?: ChatParticipantOptions + ): void + defFileOutput( + pattern: string, + description: string, + options?: FileOutputOptions + ): void } interface GenerationOutput { @@ -1282,7 +1407,7 @@ interface GenerationOutput { /** * A map of file updates */ - fileEdits: Record + fileEdits: Record /** * Generated variables, typically from AICI.gen @@ -1440,7 +1565,7 @@ interface ShellHost { command: string, args: string[], options?: ShellOptions - ): Promise> + ): Promise } interface ContainerOptions { @@ -1473,7 +1598,6 @@ interface ContainerOptions { } interface PromptHost extends ShellHost { - askUser(question: string): Promise container(options?: ContainerOptions): Promise } @@ -1499,7 +1623,7 @@ interface ContainerHost extends ShellHost { containerPath: string /** - * Writes a file as text to the file system + * Writes a file as text to the container file system * @param path * @param content */ @@ -1510,14 +1634,24 @@ interface ContainerHost extends ShellHost { * @param path */ readText(path: string): Promise + + /** + * Copies a set of files into the container + * @param fromHost glob matching files + * @param toContainer directory in the container + */ + copyTo(fromHost: string | string[], toContainer: string): Promise } -interface PromptContext extends RunPromptContext { +interface PromptContext extends ChatGenerationContext { script(options: PromptArgs): void system(options: PromptSystemArgs): void - defImages(files: StringLike, options?: DefImagesOptions): void defFileMerge(fn: FileMergeHandler): void defOutputProcessor(fn: PromptOutputProcessorHandler): void + runPrompt( + generator: string | PromptGenerator, + options?: PromptGeneratorOptions + ): Promise fetchText( urlOrFile: string | WorkspaceFile, options?: FetchTextOptions @@ -1536,20 +1670,19 @@ interface PromptContext extends RunPromptContext { workspace: WorkspaceFileSystem YAML: YAML XML: XML + JSONL: JSONL CSV: CSV INI: INI AICI: AICI host: PromptHost } - - // keep in sync with PromptContext! /** * Console functions */ -declare var console: PromptConsole +declare var console: PromptGenerationConsole /** * Setup prompt title and other parameters. @@ -1599,6 +1732,17 @@ declare function def( options?: DefOptions ): string +/** + * Declares a file that is expected to be generated by the LLM + * @param pattern file name or glob-like path + * @param options expectations about the generated file content + */ +declare function defFileOutput( + pattern: string, + description: string, + options?: FileOutputOptions +): void + /** * Declares a tool that can be called from the prompt. * @param name The name of the tool to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. @@ -1660,6 +1804,21 @@ declare var YAML: YAML */ declare var INI: INI +/** + * CSV parsing and stringifying. + */ +declare var CSV: CSV + +/** + * XML parsing and stringifying. + */ +declare var XML: XML + +/** + * JSONL parsing and stringifying. + */ +declare var JSONL: JSONL + /** * AICI operations */ @@ -1689,7 +1848,7 @@ declare function defSchema( name: string, schema: JSONSchema, options?: DefSchemaOptions -): void +): string /** * Adds images to the prompt @@ -1722,8 +1881,8 @@ declare function cancel(reason?: string): void * @param generator */ declare function runPrompt( - generator: string | RunPromptGenerator, - options?: RunPromptOptions + generator: string | PromptGenerator, + options?: PromptGeneratorOptions ): Promise /** @@ -1732,6 +1891,15 @@ declare function runPrompt( */ declare function defOutputProcessor(fn: PromptOutputProcessorHandler): void +/** + * Registers a chat participant + * @param participant + */ +declare function defChatParticipant( + participant: ChatParticipantHandler, + options?: ChatParticipantOptions +): void + /** * @deprecated Use `defOutputProcessor` instead. */ diff --git a/genaisrc/jsconfig.json b/genaisrc/jsconfig.json index 4c21c58ce..edf1f30e9 100644 --- a/genaisrc/jsconfig.json +++ b/genaisrc/jsconfig.json @@ -12,6 +12,7 @@ }, "include": [ "*.js", + "*.mjs", "./genaiscript.d.ts" ] } \ No newline at end of file