diff --git a/genaisrc/.gitattributes b/genaisrc/.gitattributes deleted file mode 100644 index b89350c92..000000000 --- a/genaisrc/.gitattributes +++ /dev/null @@ -1 +0,0 @@ -genaiscript.d.ts -diff merge=ours linguist-generated \ No newline at end of file diff --git a/genaisrc/.gitignore b/genaisrc/.gitignore deleted file mode 100644 index 6641d96c0..000000000 --- a/genaisrc/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -# auto-generated -genaiscript.d.ts -tsconfig.json -jsconfig.json \ No newline at end of file diff --git a/genaisrc/FixBuildIssue.genai.mjs b/genaisrc/FixBuildIssue.genai.mjs deleted file mode 100644 index c4b9dfb03..000000000 --- a/genaisrc/FixBuildIssue.genai.mjs +++ /dev/null @@ -1,21 +0,0 @@ - -def("FILE", env.files) - -def("ERR", "/home/nbjorner/z3/src/nlsat/nlsat_simple_checker.cpp: In member function ‘bool nlsat::simple_checker::imp::Endpoint::operator==(const nlsat::simple_checker::imp::Endpoint&) const’:\ -/home/nbjorner/z3/src/nlsat/nlsat_simple_checker.cpp:63:82: warning: C++20 says that these are ambiguous, even though the second is reversed:\ - 63 | if (!m_inf && !rhs.m_inf && m_open == rhs.m_open && m_val == rhs.m_val) {\ - | ^~~~~\ -In file included from /home/nbjorner/z3/src/util/mpz.h:26,\ - from /home/nbjorner/z3/src/util/mpq.h:21,\ - from /home/nbjorner/z3/src/util/rational.h:21,\ - from /home/nbjorner/z3/src/math/polynomial/algebraic_numbers.h:21,\ - from /home/nbjorner/z3/src/nlsat/nlsat_simple_checker.h:20,\ - from /home/nbjorner/z3/src/nlsat/nlsat_simple_checker.cpp:1:\ -/home/nbjorner/z3/src/util/scoped_numeral.h:96:17: note: candidate 1: ‘bool operator==(const _scoped_numeral&, const _scoped_numeral::numeral&)’\ - 96 | friend bool operator==(_scoped_numeral const & a, numeral const & b) {\ - | ^~~~~~~~\ -/home/nbjorner/z3/src/util/scoped_numeral.h:96:17: note: candidate 2: ‘bool operator==(const _scoped_numeral&, const _scoped_numeral::numeral&)’ (reversed)") - -$`You are an expert C++ programmer. -Your task is to fix the compilation bug reported in the error message ERR. -How should FILE be changed to fix the error message?` diff --git a/genaisrc/agentz3.genai.mts b/genaisrc/agentz3.genai.mts deleted file mode 100644 index 62714d5b0..000000000 --- a/genaisrc/agentz3.genai.mts +++ /dev/null @@ -1,44 +0,0 @@ -script({ - tools: ["agent_z3"], -}) - -$`Solve the following problems using Z3: - -The Zhang family has 6 children: Harry, Hermione, Ron, Fred, George, and Ginny. -The cost of taking Harry is $1200, Hermione is $1650, Ron is $750, Fred is $800, -George is $800, and Ginny is $1500. Which children should the couple take to minimize -the total cost of taking the children? They can take up to four children on the upcoming trip. - -Ginny is the youngest, so the Zhang family will definitely take her. - -If the couple takes Harry, they will not take Fred because Harry does not get along with him. - -If the couple takes Harry, they will not take George because Harry does not get along with him. - -If they take George, they must also take Fred. - -If they take George, they must also take Hermione. - -Even though it will cost them a lot of money, the Zhang family has decided to take at least three children. - -The SMTLIB2 formula must not contain forall or exists. -Use the Z3 command "minimize" to instruct the solver to minimize the cost of taking the children. -use the Z3 command "(check-sat)" to check if the formula is satisfiable. -` - - -/* - - -Twenty golfers wish to play in foursomes for 5 days. Is it possible for each golfer to play no more - than once with any other golfer? - -Use SMTLIB2 to formulate the problem as a quantifier free formula over linear integer arithmetic, -also known as QF_LIA. - -For every golfer and for every day assign a slot. -The golfers are numbered from 1 to 20 and the days are numbered from 1 to 5. -Express the problem as a set of integer variables, where each variable represents a golfer's slot on a given day. -The variables should be named as follows: golfer_1_day_1, golfer_1_day_2, ..., golfer_20_day_5. - -*/ \ No newline at end of file diff --git a/genaisrc/codecomplete.genai.mts b/genaisrc/codecomplete.genai.mts deleted file mode 100644 index a1217cfe6..000000000 --- a/genaisrc/codecomplete.genai.mts +++ /dev/null @@ -1,149 +0,0 @@ - -script({ - title: "Invoke LLM completion for code snippets", -}) - - -import * as fs from 'fs'; -import * as path from 'path'; - - -async function runCodePrompt(role, message, code) { - const answer = await runPrompt( - (_) => { - _.def("ROLE", role); - _.def("REQUEST", message); - _.def("CODE", code); - _.$`Your role is . - The request is given by - original code snippet: - .` - } - ) - console.log(answer.text); - return answer.text; -} - -async function invokeLLMCompletion(code, prefix) { - - let role = `You are a highly experienced compiler engineer with over 20 years of expertise, - specializing in C and C++ programming. Your deep knowledge of best coding practices - and software engineering principles enables you to produce robust, efficient, and - maintainable code in any scenario.`; - - let userMessage = `Please complete the provided C/C++ code to ensure it is compilable and executable. - Return only the fully modified code while preserving the original logic. - Add any necessary stubs, infer data types, and make essential changes to enable - successful compilation and execution. Avoid unnecessary code additions. - Ensure the final code is robust, secure, and adheres to best practices.`; - - return runCodePrompt(role, userMessage, code); -} - -async function invokeLLMAnalyzer(code, inputFilename, funcName) { - // Define the llm role - let role = - `You are a highly experienced compiler engineer with over 20 years of expertise, - specializing in C and C++ programming. Your deep knowledge of best coding practices - and software engineering principles enables you to produce robust, efficient, and - maintainable code in any scenario.`; - - // Define the message to send - let userMessage = - `Please analyze the provided C/C++ code and identify any potential issues, bugs, or opportunities for performance improvement. For each observation: - - - Clearly describe the issue or inefficiency. - - Explain the reasoning behind the problem or performance bottleneck. - - Suggest specific code changes or optimizations, including code examples where applicable. - - Ensure recommendations follow best practices for efficiency, maintainability, and correctness. - - At the end of the analysis, provide a detailed report in **Markdown format** summarizing: - - 1. **Identified Issues and Their Impact:** - - Description of each issue and its potential consequences. - - 2. **Suggested Fixes (with Code Examples):** - - Detailed code snippets showing the recommended improvements. - - 3. **Performance Improvement Recommendations:** - - Explanation of optimizations and their expected benefits. - - 4. **Additional Insights or Best Practices:** - - Suggestions to further enhance the code's quality and maintainability.`; - - return runCodePrompt(role, userMessage, code); - } - -async function createGitUpdateRequest(src_directory : string, filename : string, modifiedCode : string) { - // extract relative path from filename after slice_directory, extract function and source file name. - // Relative path: code_slices\ast\sls\orig_sls_smt_solver.cpp_updt_params.cpp file name: orig_sls_smt.cpp - const regex = /code_slices\\(.*)\\([^_]*)_(.*)\.cpp_(.*)\.cpp/; - const match = filename.match(regex); - if (!match) { - console.log(`Filename does not match expected pattern: ${filename}`); - return ""; - } - const [_, relative_path, prefix, fileName, funcName] = match; - - console.log(`Relative path: ${relative_path} file name: ${fileName}.cpp`); - - const srcFilePath = path.join(src_directory, relative_path, fileName + ".cpp"); - const srcFileContent = await workspace.readText(srcFilePath); - - let role = - `You are a highly experienced compiler engineer with over 20 years of expertise, - specializing in C and C++ programming. Your deep knowledge of best coding practices - and software engineering principles enables you to produce robust, efficient, and - maintainable code in any scenario.`; - - const answer = await runPrompt( - (_) => { - _.def("ROLE", role); - _.def("SOURCE", srcFileContent); - _.def("REVIEW", modifiedCode); - _.def("FUNCTION", funcName); - _.$`Your role is . - Please create a well-formed git patch based on the source code given in - - A code analysis is for the method or function . - The analysis is he following: - ` - } - ) - console.log(answer.text); - return answer.text; -} - -const input_directory = "code_slices"; -const output_directory = "code_slices_analyzed"; -const src_directory = "src"; -const code_slice_files = await workspace.findFiles("code_slices/**/*.cpp"); - -let count = 0; -for (const file of code_slice_files) { - if (path.extname(file.filename) === '.cpp') { - console.log(`Processing file: ${file.filename}`); - - const regex = /(.*)_(.*)\.cpp_(.*)\.cpp/; - const match = file.filename.match(regex); - - if (!match) { - console.log(`Filename does not match expected pattern: ${file.filename}`); - continue; - } - const [_, prefix, fileName, funcName] = match; - - const content = file.content; - const answer1 = await invokeLLMCompletion(content, fileName); - const answer2 = await invokeLLMAnalyzer(answer1, fileName, funcName); - const outputFilePath = path.join(output_directory, fileName + "_" + funcName + ".md"); - await workspace.writeText(outputFilePath, answer2); - const answer3 = await createGitUpdateRequest(src_directory, file.filename, answer2); - const outputFilePath2 = path.join(output_directory, fileName + "_" + funcName + ".patch"); - await workspace.writeText(outputFilePath2, answer3); - ++count; - if (count > 3) - break; - } -} - diff --git a/genaisrc/codeupdate.genai.mts b/genaisrc/codeupdate.genai.mts deleted file mode 100644 index ae74331e9..000000000 --- a/genaisrc/codeupdate.genai.mts +++ /dev/null @@ -1,76 +0,0 @@ - -script({ - title: "Invoke LLM code update", -}) - - -async function runCodePrompt(role, message, code) { - const answer = await runPrompt( - (_) => { - _.def("ROLE", role); - _.def("REQUEST", message); - _.def("CODE", code); - _.$`Your role is . - The request is given by - original code: - .` - } - ) - console.log(answer.text); - return answer.text; -} - -async function invokeLLMUpdate(code, inputFile) { - - let role = `You are a highly experienced compiler engineer with over 20 years of expertise, - specializing in C and C++ programming. Your deep knowledge of best coding practices - and software engineering principles enables you to produce robust, efficient, and - maintainable code in any scenario.`; - - let userMessage = `Please modify the original code to ensure that it enforces the following: - - do not use pointer arithmetic for the updates. - - do not introduce uses of std::vector. - - only make replacements that are compatible with the ones listed below. - - add white space between operators: - For example: - i=0 - by - i = 0 - For example - a+b - by - a + b - - remove brackets around single statements: - For example: - { break; } - by - break; - - replaces uses of for loops using begin(), end() iterator patterns by C++21 style for loops - For example replace - for (auto it = x.begin(), end = x.end(); it != end; ++it) - by - for (auto & e : x) - - For example, replace - for (unsigned i = 0; i < a->get_num_args(); ++i) { - expr* arg = a->get_arg(i); - ... - } - by - for (auto arg : *a) { - ... - } - `; - - return runCodePrompt(role, userMessage, code); -} - - -const inputFile = env.files[0]; -const file = await workspace.readText(inputFile); -const answer = await invokeLLMUpdate(file.content, inputFile); -// Extract the code from the answer by removing ```cpp and ```: -let code = answer.replace(/```cpp/g, "").replace(/```/g, ""); -const outputFile = inputFile.filename + ".patch"; -await workspace.writeText(outputFile, code); - diff --git a/genaisrc/gai.genai.mts b/genaisrc/gai.genai.mts deleted file mode 100644 index 9de3cf11a..000000000 --- a/genaisrc/gai.genai.mts +++ /dev/null @@ -1,17 +0,0 @@ -script({ - tools: ["agent_fs", "agent_git", "agent_github"], -}) - -const { - workflow = "latest failed", - failure_run_id = "latest", - branch = await git.defaultBranch(), -} = env.vars - -$`Investigate the status of the ${workflow} workflow and identify the root cause of the failure of run ${failure_run_id} in branch ${branch}. - -- Correlate the failure with the relevant commits, pull requests or issues. -- Compare the source code between the failed run commit and the last successful run commit before that run. - -In your report, include html links to the relevant runs, commits, pull requests or issues. -` diff --git a/genaisrc/gcm.genai.mts b/genaisrc/gcm.genai.mts deleted file mode 100644 index 93e28e1d1..000000000 --- a/genaisrc/gcm.genai.mts +++ /dev/null @@ -1,142 +0,0 @@ -/** - * Script to automate the git commit process with AI-generated commit messages. - * It checks for staged changes, generates a commit message, and prompts the user to review or edit the message before committing. - */ - -script({ - title: "git commit message", - description: "Generate a commit message for all staged changes", -}) - -// Check for staged changes and stage all changes if none are staged -const diff = await git.diff({ - staged: true, - askStageOnEmpty: true, -}) - -// If no staged changes are found, cancel the script with a message -if (!diff) cancel("no staged changes") - -// Display the diff of staged changes in the console -console.log(diff) - -// chunk if case of massive diff -const chunks = await tokenizers.chunk(diff, { chunkSize: 10000 }) -if (chunks.length > 1) - console.log(`staged changes chunked into ${chunks.length} parts`) - -let choice -let message -do { - // Generate a conventional commit message based on the staged changes diff - message = "" - for (const chunk of chunks) { - const res = await runPrompt( - (_) => { - _.def("GIT_DIFF", chunk, { - maxTokens: 10000, - language: "diff", - detectPromptInjection: "available", - }) - _.$`Generate a git conventional commit message that summarizes the changes in GIT_DIFF. - - : - - - can be one of the following: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert - - is a short, imperative present-tense description of the change - - GIT_DIFF is generated by "git diff" - - do NOT use markdown syntax - - do NOT add quotes, single quote or code blocks - - keep it short, 1 line only, maximum 50 characters - - follow the conventional commit spec at https://www.conventionalcommits.org/en/v1.0.0/#specification - - do NOT confuse delete lines starting with '-' and add lines starting with '+' - ` - }, - { - model: "large", // Specifies the LLM model to use for message generation - label: "generate commit message", // Label for the prompt task - system: [ - "system.assistant", - "system.safety_jailbreak", - "system.safety_harmful_content", - "system.safety_validate_harmful_content", - ], - } - ) - if (res.error) throw res.error - message += res.text + "\n" - } - - // since we've concatenated the chunks, let's compress it back into a single sentence again - if (chunks.length > 1) { - const res = - await prompt`Generate a git conventional commit message that summarizes the COMMIT_MESSAGES. - - : - - - can be one of the following: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert - - is a short, imperative present-tense description of the change - - do NOT use markdown syntax - - do NOT add quotes or code blocks - - keep it short, 1 line only, maximum 50 characters - - use gitmoji - - follow the conventional commit spec at https://www.conventionalcommits.org/en/v1.0.0/#specification - - do NOT confuse delete lines starting with '-' and add lines starting with '+' - - do NOT respond anything else than the commit message - - COMMIT_MESSAGES: - ${message} - `.options({ - model: "large", - label: "summarize chunk commit messages", - system: [ - "system.assistant", - "system.safety_jailbreak", - "system.safety_harmful_content", - "system.safety_validate_harmful_content", - ], - }) - if (res.error) throw res.error - message = res.text - } - - message = message?.trim() - if (!message) { - console.log( - "No commit message generated, did you configure the LLM model?" - ) - break - } - - // Prompt user to accept, edit, or regenerate the commit message - choice = await host.select(message, [ - { - value: "commit", - description: "accept message and commit", - }, - { - value: "edit", - description: "edit message and commit", - }, - { - value: "regenerate", - description: "regenerate message", - }, - ]) - - // Handle user's choice for commit message - if (choice === "edit") { - message = await host.input("Edit commit message", { - required: true, - }) - choice = "commit" - } - // If user chooses to commit, execute the git commit and optionally push changes - if (choice === "commit" && message) { - console.log(await git.exec(["commit", "-m", message])) - if (await host.confirm("Push changes?", { default: true })) - console.log(await git.exec("push")) - break - } -} while (choice !== "commit") - diff --git a/genaisrc/genaiscript.d.ts b/genaisrc/genaiscript.d.ts deleted file mode 100644 index 18c579951..000000000 --- a/genaisrc/genaiscript.d.ts +++ /dev/null @@ -1,6800 +0,0 @@ -/** - * GenAIScript Ambient Type Definition File - * @version 1.138.2 - */ -type OptionsOrString = (string & {}) | TOptions - -type ElementOrArray = T | T[] - -interface PromptGenerationConsole { - log(...data: any[]): void - warn(...data: any[]): void - debug(...data: any[]): void - error(...data: any[]): void -} - -type DiagnosticSeverity = "error" | "warning" | "info" - -interface Diagnostic { - filename: string - range: CharRange - severity: DiagnosticSeverity - message: string - /** - * suggested fix - */ - suggestion?: string - /** - * error or warning code - */ - code?: string -} - -type Awaitable = T | PromiseLike - -interface SerializedError { - name?: string - message?: string - stack?: string - cause?: unknown - code?: string - line?: number - column?: number -} - -interface PromptDefinition { - /** - * Based on file name. - */ - id: string - - /** - * Something like "Summarize children", show in UI. - */ - title?: string - - /** - * Longer description of the prompt. Shows in UI grayed-out. - */ - description?: string - - /** - * Groups template in UI - */ - group?: string - - /** - * List of tools defined in the script - */ - defTools?: { id: string; description: string; kind: "tool" | "agent" }[] -} - -interface PromptLike extends PromptDefinition { - /** - * File where the prompt comes from (if any). - */ - filename?: string - - /** - * The actual text of the prompt template. - * Only used for system prompts. - */ - text?: string - - /** - * The text of the prompt JS source code. - */ - jsSource?: string - - /** - * Resolved system ids - */ - resolvedSystem?: SystemPromptInstance[] - - /** - * Inferred input schema for parameters - */ - inputSchema?: JSONSchemaObject -} - -type SystemPromptId = OptionsOrString< - | "system" - | "system.agent_data" - | "system.agent_docs" - | "system.agent_fs" - | "system.agent_git" - | "system.agent_github" - | "system.agent_interpreter" - | "system.agent_mcp" - | "system.agent_planner" - | "system.agent_user_input" - | "system.agent_video" - | "system.agent_web" - | "system.agent_z3" - | "system.annotations" - | "system.assistant" - | "system.chain_of_draft" - | "system.changelog" - | "system.cooperation" - | "system.diagrams" - | "system.diff" - | "system.do_not_explain" - | "system.english" - | "system.explanations" - | "system.fetch" - | "system.files" - | "system.files_schema" - | "system.fs_ask_file" - | "system.fs_data_query" - | "system.fs_diff_files" - | "system.fs_find_files" - | "system.fs_read_file" - | "system.git" - | "system.git_diff" - | "system.git_info" - | "system.github_actions" - | "system.github_files" - | "system.github_info" - | "system.github_issues" - | "system.github_pulls" - | "system.math" - | "system.mcp" - | "system.md_find_files" - | "system.md_frontmatter" - | "system.meta_prompt" - | "system.meta_schema" - | "system.node_info" - | "system.node_test" - | "system.output_ini" - | "system.output_json" - | "system.output_markdown" - | "system.output_plaintext" - | "system.output_yaml" - | "system.planner" - | "system.python" - | "system.python_code_interpreter" - | "system.python_types" - | "system.retrieval_fuzz_search" - | "system.retrieval_vector_search" - | "system.retrieval_web_search" - | "system.safety_canary_word" - | "system.safety_harmful_content" - | "system.safety_jailbreak" - | "system.safety_protected_material" - | "system.safety_ungrounded_content_summarization" - | "system.safety_validate_harmful_content" - | "system.schema" - | "system.tasks" - | "system.technical" - | "system.think" - | "system.today" - | "system.tool_calls" - | "system.tools" - | "system.transcribe" - | "system.typescript" - | "system.user_input" - | "system.video" - | "system.vision_ask_images" - | "system.z3" - | "system.zero_shot_cot" -> - -type SystemPromptInstance = { - id: SystemPromptId - parameters?: Record - vars?: Record -} - -type SystemToolId = OptionsOrString< - | "agent_data" - | "agent_docs" - | "agent_fs" - | "agent_git" - | "agent_github" - | "agent_interpreter" - | "agent_planner" - | "agent_user_input" - | "agent_video" - | "agent_web" - | "agent_z3" - | "fetch" - | "fs_ask_file" - | "fs_data_query" - | "fs_diff_files" - | "fs_find_files" - | "fs_read_file" - | "git_branch_current" - | "git_branch_default" - | "git_branch_list" - | "git_diff" - | "git_last_tag" - | "git_list_commits" - | "git_status" - | "github_actions_job_logs_diff" - | "github_actions_job_logs_get" - | "github_actions_jobs_list" - | "github_actions_workflows_list" - | "github_files_get" - | "github_files_list" - | "github_issues_comments_list" - | "github_issues_get" - | "github_issues_list" - | "github_pulls_get" - | "github_pulls_list" - | "github_pulls_review_comments_list" - | "math_eval" - | "md_find_files" - | "md_read_frontmatter" - | "meta_prompt" - | "meta_schema" - | "node_test" - | "python_code_interpreter_copy_files_to_container" - | "python_code_interpreter_read_file" - | "python_code_interpreter_run" - | "retrieval_fuzz_search" - | "retrieval_vector_search" - | "retrieval_web_search" - | "think" - | "transcribe" - | "user_input_confirm" - | "user_input_select" - | "user_input_text" - | "video_extract_audio" - | "video_extract_clip" - | "video_extract_frames" - | "video_probe" - | "vision_ask_images" - | "z3" -> - -type FileMergeHandler = ( - filename: string, - label: string, - before: string, - generated: string -) => Awaitable - -interface PromptOutputProcessorResult { - /** - * Updated text - */ - text?: string - /** - * Generated files from the output - */ - files?: Record - - /** - * User defined errors - */ - annotations?: Diagnostic[] -} - -type PromptOutputProcessorHandler = ( - output: GenerationOutput -) => - | PromptOutputProcessorResult - | Promise - | undefined - | Promise - | void - | Promise - -type PromptTemplateResponseType = - | "text" - | "json" - | "yaml" - | "markdown" - | "json_object" - | "json_schema" - | undefined - -type ModelType = OptionsOrString< - | "large" - | "small" - | "tiny" - | "long" - | "vision" - | "vision_small" - | "reasoning" - | "reasoning_small" - | "openai:gpt-4.1" - | "openai:gpt-4.1-mini" - | "openai:gpt-4.1-nano" - | "openai:gpt-4o" - | "openai:gpt-4o-mini" - | "openai:gpt-3.5-turbo" - | "openai:o3-mini" - | "openai:o3-mini:low" - | "openai:o3-mini:medium" - | "openai:o3-mini:high" - | "openai:o1" - | "openai:o1-mini" - | "openai:o1-preview" - | "github:openai/gpt-4.1" - | "github:openai/gpt-4o" - | "github:openai/gpt-4o-mini" - | "github:openai/o1" - | "github:openai/o1-mini" - | "github:openai/o3-mini" - | "github:openai/o3-mini:low" - | "github:microsoft/mai-ds-r1" - | "github:deepseek/deepseek-v3" - | "github:deepseek/deepseek-r1" - | "github:microsoft/phi-4" - | "github_copilot_chat:current" - | "github_copilot_chat:gpt-3.5-turbo" - | "github_copilot_chat:gpt-4o-mini" - | "github_copilot_chat:gpt-4o-2024-11-20" - | "github_copilot_chat:gpt-4" - | "github_copilot_chat:o1" - | "github_copilot_chat:o1:low" - | "github_copilot_chat:o1:medium" - | "github_copilot_chat:o1:high" - | "github_copilot_chat:o3-mini" - | "github_copilot_chat:o3-mini:low" - | "github_copilot_chat:o3-mini:medium" - | "github_copilot_chat:o3-mini:high" - | "azure:gpt-4o" - | "azure:gpt-4o-mini" - | "azure:o1" - | "azure:o1-mini" - | "azure:o1-preview" - | "azure:o3-mini" - | "azure:o3-mini:low" - | "azure:o3-mini:medium" - | "azure:o3-mini:high" - | "azure_ai_inference:gpt-4.1" - | "azure_ai_inference:gpt-4o" - | "azure_ai_inference:gpt-4o-mini" - | "azure_ai_inference:o1" - | "azure_ai_inference:o1-mini" - | "azure_ai_inference:o1-preview" - | "azure_ai_inference:o3-mini" - | "azure_ai_inference:o3-mini:low" - | "azure_ai_inference:o3-mini:medium" - | "azure_ai_inference:o3-mini:high" - | "azure_ai_inference:deepSeek-v3" - | "azure_ai_inference:deepseek-r1" - | "ollama:gemma3:4b" - | "ollama:marco-o1" - | "ollama:tulu3" - | "ollama:athene-v2" - | "ollama:opencoder" - | "ollama:qwen2.5-coder" - | "ollama:llama3.2-vision" - | "ollama:llama3.2" - | "ollama:phi4" - | "ollama:phi3.5" - | "ollama:deepseek-r1:1.5b" - | "ollama:deepseek-r1:7b" - | "ollama:olmo2:7b" - | "ollama:command-r7b:7b" - | "anthropic:claude-3-7-sonnet-latest" - | "anthropic:claude-3-7-sonnet-latest:low" - | "anthropic:claude-3-7-sonnet-latest:medium" - | "anthropic:claude-3-7-sonnet-latest:high" - | "anthropic:claude-3-7-sonnet-20250219" - | "anthropic:claude-3-5-sonnet-latest" - | "anthropic:claude-3-5-sonnet-20240620" - | "anthropic:claude-3-opus-20240229" - | "anthropic:claude-3-sonnet-20240229" - | "anthropic:claude-3-haiku-20240307" - | "anthropic:claude-2.1" - | "anthropic_bedrock:anthropic.claude-3-7-sonnet-20250219-v1:0" - | "anthropic_bedrock:anthropic.claude-3-7-sonnet-20250219-v1:0:low" - | "anthropic_bedrock:anthropic.claude-3-7-sonnet-20250219-v1:0:medium" - | "anthropic_bedrock:anthropic.claude-3-7-sonnet-20250219-v1:0:high" - | "anthropic_bedrock:anthropic.claude-3-5-haiku-20241022-v1:0" - | "anthropic_bedrock:anthropic.claude-3-5-sonnet-20241022-v2:0" - | "anthropic_bedrock:anthropic.claude-3-5-sonnet-20240620-v1:0" - | "anthropic_bedrock:anthropic.claude-3-opus-20240229-v1:0" - | "anthropic_bedrock:anthropic.claude-3-sonnet-20240229-v1:0" - | "anthropic_bedrock:anthropic.claude-3-haiku-20240307-v1:0" - | "huggingface:microsoft/Phi-3-mini-4k-instruct" - | "jan:llama3.2-3b-instruct" - | "google:gemini-2.0-flash-exp" - | "google:gemini-2.0-flash-thinking-exp-1219" - | "google:gemini-1.5-flash" - | "google:gemini-1.5-flash-latest" - | "google:gemini-1.5-flash-8b" - | "google:gemini-1.5-flash-8b-latest" - | "google:gemini-1.5-pro" - | "google:gemini-1.5-pro-latest" - | "mistral:mistral-large-latest" - | "mistral:mistral-small-latest" - | "mistral:pixtral-large-latest" - | "mistral:codestral-latest" - | "mistral:nemo" - | "alibaba:qwen-turbo" - | "alibaba:qwen-max" - | "alibaba:qwen-plus" - | "alibaba:qwen2-72b-instruct" - | "alibaba:qwen2-57b-a14b-instruct" - | "deepseek:deepseek-chat" - // | "transformers:onnx-community/Qwen2.5-0.5B-Instruct:q4" - // | "transformers:HuggingFaceTB/SmolLM2-1.7B-Instruct:q4f16" - | "llamafile" - | "sglang" - | "vllm" - | "echo" - | "none" -> - -type EmbeddingsModelType = OptionsOrString< - | "openai:text-embedding-3-small" - | "openai:text-embedding-3-large" - | "openai:text-embedding-ada-002" - | "github:text-embedding-3-small" - | "github:text-embedding-3-large" - | "azure:text-embedding-3-small" - | "azure:text-embedding-3-large" - | "azure_ai_inference:text-embedding-3-small" - | "azure_ai_inference:text-embedding-3-large" - | "ollama:nomic-embed-text" - | "google:text-embedding-004" - | "huggingface:nomic-ai/nomic-embed-text-v1.5" -> - -type ModelSmallType = OptionsOrString< - | "openai:gpt-4o-mini" - | "github:openai/gpt-4o-mini" - | "azure:gpt-4o-mini" - | "github:microsoft/phi-4" -> - -type ModelVisionType = OptionsOrString< - | "openai:gpt-4o" - | "github:openai/gpt-4o" - | "azure:gpt-4o" - | "azure:gpt-4o-mini" -> - -type ModelImageGenerationType = OptionsOrString< - "openai:gpt-image-1" | "openai:dall-e-2" | "openai:dall-e-3" -> - -type ModelProviderType = OptionsOrString< - | "openai" - | "azure" - | "azure_serverless" - | "azure_serverless_models" - | "anthropic" - | "anthropic_bedrock" - | "google" - | "huggingface" - | "mistral" - | "alibaba" - | "github" - | "transformers" - | "ollama" - | "lmstudio" - | "jan" - | "sglang" - | "vllm" - | "llamafile" - | "litellm" - | "github_copilot_chat" - | "deepseek" - | "whisperasr" - | "echo" -> - -interface ModelConnectionOptions { - /** - * Which LLM model by default or for the `large` alias. - */ - model?: ModelType -} - -interface ModelAliasesOptions extends ModelConnectionOptions { - /** - * Configure the `small` model alias. - */ - smallModel?: ModelSmallType - - /** - * Configure the `vision` model alias. - */ - visionModel?: ModelVisionType - - /** - * A list of model aliases to use. - */ - modelAliases?: Record -} - -type ReasoningEffortType = "high" | "medium" | "low" - -type ChatToolChoice = - | "none" - | "auto" - | "required" - | { - /** - * The name of the function to call. - */ - name: string - } - -interface ModelOptions - extends ModelConnectionOptions, - ModelTemplateOptions, - CacheOptions { - /** - * Temperature to use. Higher temperature means more hallucination/creativity. - * Range 0.0-2.0. - * - * @default 0.2 - */ - temperature?: number - - /** - * Enables fallback tools mode - */ - fallbackTools?: boolean - - /** - * OpenAI o* reasoning models support a reasoning effort parameter. - * For Clause, these are mapped to thinking budget tokens - */ - reasoningEffort?: ReasoningEffortType - - /** - * A list of keywords that should be found in the output. - */ - choices?: ElementOrArray< - string | { token: string | number; weight?: number } - > - - /** - * Returns the log probabilities of the each tokens. Not supported in all models. - */ - logprobs?: boolean - - /** - * Number of alternate token logprobs to generate, up to 5. Enables logprobs. - */ - topLogprobs?: number - - /** - * Specifies the type of output. Default is plain text. - * - `text` enables plain text mode (through system prompts) - * - `json` enables JSON mode (through system prompts) - * - `yaml` enables YAML mode (through system prompts) - * - `json_object` enables JSON mode (native) - * - `json_schema` enables structured outputs (native) - * Use `responseSchema` to specify an output schema. - */ - responseType?: PromptTemplateResponseType - - /** - * JSON object schema for the output. Enables the `json_object` output mode by default. - */ - responseSchema?: PromptParametersSchema | JSONSchema - - /** - * “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, - * which makes the generated text more diverse. - */ - topP?: number - - /** - * Maximum number of completion tokens - * - */ - maxTokens?: number - - /** - * Tool selection strategy. Default is 'auto'. - */ - toolChoice?: ChatToolChoice - - /** - * Maximum number of tool calls to make. - */ - maxToolCalls?: number - - /** - * Maximum number of data repairs to attempt. - */ - maxDataRepairs?: number - - /** - * A deterministic integer seed to use for the model. - */ - seed?: number - - /** - * A list of model ids and their maximum number of concurrent requests. - */ - modelConcurrency?: Record -} - -interface EmbeddingsModelOptions { - /** - * LLM model to use for embeddings. - */ - embeddingsModel?: EmbeddingsModelType -} - -interface PromptSystemOptions extends PromptSystemSafetyOptions { - /** - * List of system script ids used by the prompt. - */ - system?: ElementOrArray - - /** - * List of tools used by the prompt. - */ - tools?: ElementOrArray - - /** - * List of system to exclude from the prompt. - */ - excludedSystem?: ElementOrArray - - /** - * MCP server configuration. The tools will be injected into the prompt. - */ - mcpServers?: McpServersConfig - - /** - * MCP agent configuration. Each mcp server will be wrapped with an agent. - */ - mcpAgentServers?: McpAgentServersConfig -} - -interface ScriptRuntimeOptions extends LineNumberingOptions { - /** - * Secrets required by the prompt - */ - secrets?: string[] -} - -type PromptJSONParameterType = T & { required?: boolean } - -type PromptParameterType = - | string - | number - | boolean - | object - | PromptJSONParameterType - | PromptJSONParameterType - | PromptJSONParameterType -type PromptParametersSchema = Record< - string, - PromptParameterType | [PromptParameterType] -> -type PromptParameters = Record - -type PromptAssertion = { - // How heavily to weigh the assertion. Defaults to 1.0 - weight?: number - /** - * The transformation to apply to the output before checking the assertion. - */ - transform?: string -} & ( - | { - // type of assertion - type: - | "icontains" - | "not-icontains" - | "equals" - | "not-equals" - | "starts-with" - | "not-starts-with" - // The expected value - value: string - } - | { - // type of assertion - type: - | "contains-all" - | "not-contains-all" - | "contains-any" - | "not-contains-any" - | "icontains-all" - | "not-icontains-all" - // The expected values - value: string[] - } - | { - // type of assertion - type: "levenshtein" | "not-levenshtein" - // The expected value - value: string - // The threshold value - threshold?: number - } - | { - type: "javascript" - /** - * JavaScript expression to evaluate. - */ - value: string - /** - * Optional threshold if the javascript expression returns a number - */ - threshold?: number - } -) - -interface PromptTest { - /** - * Short name of the test - */ - name?: string - /** - * Description of the test. - */ - description?: string - /** - * List of files to apply the test to. - */ - files?: ElementOrArray - /** - * List of in-memory files to apply the test to. - */ - workspaceFiles?: ElementOrArray - /** - * Extra set of variables for this scenario - */ - vars?: Record - /** - * LLM output matches a given rubric, using a Language Model to grade output. - */ - rubrics?: ElementOrArray - /** - * LLM output adheres to the given facts, using Factuality method from OpenAI evaluation. - */ - facts?: ElementOrArray - /** - * List of keywords that should be contained in the LLM output. - */ - keywords?: ElementOrArray - /** - * List of keywords that should not be contained in the LLM output. - */ - forbidden?: ElementOrArray - /** - * Additional deterministic assertions. - */ - asserts?: ElementOrArray - - /** - * Determines what kind of output is sent back to the test engine. Default is "text". - */ - format?: "text" | "json" -} - -/** - * Configure promptfoo redteam plugins - */ -interface PromptRedteam { - /** - * The `purpose` property is used to guide the attack generation process. It should be as clear and specific as possible. - * Include the following information: - * - Who the user is and their relationship to the company - * - What data the user has access to - * - What data the user does not have access to - * - What actions the user can perform - * - What actions the user cannot perform - * - What systems the agent has access to - * @link https://www.promptfoo.dev/docs/red-team/troubleshooting/attack-generation/ - */ - purpose: string - - /** - * Redteam identifier used for reporting purposes - */ - label?: string - - /** - * Default number of inputs to generate for each plugin. - * The total number of tests will be `(numTests * plugins.length * (1 + strategies.length) * languages.length)` - * Languages.length is 1 by default, but is added when the multilingual strategy is used. - */ - numTests?: number - - /** - * List of languages to target. Default is English. - */ - language?: string - - /** - * Red team plugin list - * @link https://www.promptfoo.dev/docs/red-team/owasp-llm-top-10/ - */ - plugins?: ElementOrArray< - OptionsOrString< - | "default" - | "nist:ai:measure" - | "owasp:llm" - | "owasp:api" - | "mitre:atlas" - | "owasp:llm:01" - | "owasp:llm:02" - | "owasp:llm:04" - | "owasp:llm:06" - | "owasp:llm:09" - | "contracts" - | "divergent-repetition" - | "excessive-agency" - | "hallucination" - | "harmful:chemical-biological-weapons" - | "harmful:child-exploitation" - | "harmful:copyright-violations" - | "harmful:cybercrime" - | "harmful:cybercrime:malicious-code" - | "harmful:graphic-content" - | "harmful:harassment-bullying" - | "harmful:hate" - | "harmful:illegal-activities" - | "harmful:illegal-drugs" - | "harmful:illegal-drugs:meth" - | "harmful:indiscriminate-weapons" - | "harmful:insults" - | "harmful:intellectual-property" - | "harmful:misinformation-disinformation" - | "harmful:non-violent-crime" - | "harmful:privacy" - | "harmful:profanity" - | "harmful:radicalization" - | "harmful:self-harm" - | "harmful:sex-crime" - | "harmful:sexual-content" - | "harmful:specialized-advice" - | "harmful:unsafe-practices" - | "harmful:violent-crime" - | "harmful:weapons:ied" - | "hijacking" - | "pii:api-db" - | "pii:direct" - | "pii:session" - | "pii:social" - | "politics" - > - > - - /** - * Adversary prompt generation strategies - */ - strategies?: ElementOrArray< - OptionsOrString< - | "default" - | "basic" - | "jailbreak" - | "jailbreak:composite" - | "base64" - | "jailbreak" - | "prompt-injection" - > - > -} - -/** - * Different ways to render a fence block. - */ -type FenceFormat = "markdown" | "xml" | "none" - -interface FenceFormatOptions { - /** - * Formatting of code sections - */ - fenceFormat?: FenceFormat -} - -interface ModelTemplateOptions extends FenceFormatOptions { - /** - * Budget of tokens to apply the prompt flex renderer. - */ - flexTokens?: number -} - -interface McpToolAnnotations { - /** - * Annotations for MCP tools - * @link https://modelcontextprotocol.io/docs/concepts/tools#available-tool-annotations - */ - annotations?: { - /** - * If true, indicates the tool does not modify its environment - */ - readOnlyHint?: boolean - /** - * If true, the tool may perform destructive updates (only meaningful when readOnlyHint is false) - */ - destructiveHint?: boolean - /** - * If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when readOnlyHint is false) - */ - idempotentHint?: boolean - /** - * If true, the tool may interact with an “open world” of external entities - */ - openWorldHint?: boolean - } -} - -interface MetadataOptions { - /** - * Set of 16 key-value pairs that can be attached to an object. - * This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - * Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - */ - metadata?: Record -} - -interface PromptScript - extends PromptLike, - ModelOptions, - ModelAliasesOptions, - PromptSystemOptions, - EmbeddingsModelOptions, - ContentSafetyOptions, - SecretDetectionOptions, - GitIgnoreFilterOptions, - ScriptRuntimeOptions, - McpToolAnnotations, - MetadataOptions { - /** - * Which provider to prefer when picking a model. - */ - provider?: ModelProviderType - - /** - * Additional template parameters that will populate `env.vars` - */ - parameters?: PromptParametersSchema - - /** - * 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?: ElementOrArray - - /** - * A comma separated list of file extensions to accept. - */ - accept?: OptionsOrString<".md,.mdx" | "none"> - - /** - * Extra variable values that can be used to configure system prompts. - */ - vars?: Record - - /** - * Tests to validate this script. - */ - tests?: ElementOrArray - - /** - * Models to use with tests - */ - testModels?: ElementOrArray - - /** - * LLM vulnerability checks - */ - redteam?: PromptRedteam - - /** - * Don't show it to the user in lists. Template `system.*` are automatically unlisted. - */ - unlisted?: boolean - - /** - * Set if this is a system prompt. - */ - isSystem?: boolean -} -/** - * Represent a workspace file and optional content. - */ -interface WorkspaceFile { - /** - * Name of the file, relative to project root. - */ - filename: string - - /** - * Content mime-type if known - */ - type?: string - - /** - * Encoding of the content - */ - encoding?: "base64" - - /** - * Content of the file. - */ - content?: string - - /** - * Size in bytes if known - */ - size?: number -} - -interface WorkspaceFileWithScore extends WorkspaceFile { - /** - * Score allocated by search algorithm - */ - score?: number -} - -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. - */ - name: string - - /** - * A description of what the function does, used by the model to choose when and - * how to call the function. - */ - description?: string - - /** - * The parameters the functions accepts, described as a JSON Schema object. See the - * [guide](https://platform.openai.com/docs/guides/text-generation/function-calling) - * for examples, and the - * [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for - * documentation about the format. - * - * Omitting `parameters` defines a function with an empty parameter list. - */ - parameters?: JSONSchema -} - -/** - * Interface representing an output trace with various logging and tracing methods. - * Extends the `ToolCallTrace` interface. - */ -interface OutputTrace extends ToolCallTrace { - /** - * Logs a heading message at the specified level. - * @param level - The level of the heading. - * @param message - The heading message. - */ - heading(level: number, message: string): void - - /** - * Logs an image with an optional caption. - * @param url - The URL of the image. - * @param caption - The optional caption for the image. - */ - image(url: BufferLike, caption?: string): Promise - - /** - * Logs a markdown table - * @param rows - */ - table(rows: object[]): void - - /** - * Computes and renders diff between two files. - */ - diff( - left: string | WorkspaceFile, - right: string | WorkspaceFile, - options?: { context?: number } - ): void - - /** - * Logs a result item with a boolean value and a message. - * @param value - The boolean value of the result item. - * @param message - The message for the result item. - */ - resultItem(value: boolean, message: string): void - - /** - * Starts a trace with details in markdown format. - * @param title - The title of the trace. - * @param options - Optional settings for the trace. - * @returns A `MarkdownTrace` instance. - */ - startTraceDetails( - title: string, - options?: { expanded?: boolean } - ): OutputTrace - - /** - * Appends content to the trace. - * @param value - The content to append. - */ - appendContent(value: string): void - - /** - * Starts a details section in the trace. - * @param title - The title of the details section. - * @param options - Optional settings for the details section. - */ - startDetails( - title: string, - options?: { success?: boolean; expanded?: boolean } - ): void - - /** - * Ends the current details section in the trace. - */ - endDetails(): void - - /** - * Logs a video with a name, file path, and optional alt text. - * @param name - The name of the video. - * @param filepath - The file path of the video. - * @param alt - The optional alt text for the video. - */ - video(name: string, filepath: string, alt?: string): void - - /** - * Logs an audio file - * @param name - * @param filepath - * @param alt - */ - audio(name: string, filepath: string, alt?: string): void - - /** - * Logs a details section with a title and body. - * @param title - The title of the details section. - * @param body - The body content of the details section, can be a string or an object. - * @param options - Optional settings for the details section. - */ - details( - title: string, - body: string | object, - options?: { success?: boolean; expanded?: boolean } - ): void - - /** - * Logs a fenced details section with a title, body, and optional content type. - * @param title - The title of the details section. - * @param body - The body content of the details section, can be a string or an object. - * @param contentType - The optional content type of the body. - * @param options - Optional settings for the details section. - */ - detailsFenced( - title: string, - body: string | object, - contentType?: string, - options?: { expanded?: boolean } - ): void - - /** - * Logs an item with a name, value, and optional unit. - * @param name - The name of the item. - * @param value - The value of the item. - * @param unit - The optional unit of the value. - */ - itemValue(name: string, value: any, unit?: string): void - - /** - * Adds a url link item - * @param name name url - * @param url url. If missing, name is treated as the url. - */ - itemLink(name: string, url?: string | URL, title?: string): void - - /** - * Writes a paragraph of text with empty lines before and after. - * @param text paragraph to write - */ - p(text: string): void - - /** - * Logs a warning message. - * @param msg - The warning message to log. - */ - warn(msg: string): void - - /** - * Logs a caution message. - * @param msg - The caution message to log. - */ - caution(msg: string): void - - /** - * Logs a note message. - * @param msg - The note message to log. - */ - note(msg: string): void - - /** - * Logs an error object - * @param err - */ - error(message: string, error?: unknown): void -} - -/** - * Interface representing a tool call trace for logging various types of messages. - */ -interface ToolCallTrace { - /** - * Logs a general message. - * @param message - The message to log. - */ - log(message: string): void - - /** - * Logs an item message. - * @param message - The item message to log. - */ - item(message: string): void - - /** - * Logs a tip message. - * @param message - The tip message to log. - */ - tip(message: string): void - - /** - * Logs a fenced message, optionally specifying the content type. - * @param message - The fenced message to log. - * @param contentType - The optional content type of the message. - */ - fence(message: string | unknown, contentType?: string): void -} - -/** - * Position (line, character) in a file. Both are 0-based. - */ -type CharPosition = [number, number] - -/** - * Describes a run of text. - */ -type CharRange = [CharPosition, CharPosition] - -/** - * 0-based line numbers. - */ -type LineRange = [number, number] - -interface FileEdit { - type: string - filename: string - label?: string - validated?: boolean -} - -interface ReplaceEdit extends FileEdit { - type: "replace" - range: CharRange | LineRange - text: string -} - -interface InsertEdit extends FileEdit { - type: "insert" - pos: CharPosition | number - text: string -} - -interface DeleteEdit extends FileEdit { - type: "delete" - range: CharRange | LineRange -} - -interface CreateFileEdit extends FileEdit { - type: "createfile" - overwrite?: boolean - ignoreIfExists?: boolean - text: string -} - -type Edits = InsertEdit | ReplaceEdit | DeleteEdit | CreateFileEdit - -interface ToolCallContent { - type?: "content" - content: string - edits?: Edits[] -} - -type ToolCallOutput = - | string - | number - | boolean - | ToolCallContent - | ShellOutput - | WorkspaceFile - | RunPromptResult - | SerializedError - | undefined - -interface WorkspaceFileCache { - /** - * Name of the cache - */ - name: string - /** - * Gets the value associated with the key, or undefined if there is none. - * @param key - */ - get(key: K): Promise - /** - * Sets the value associated with the key. - * @param key - * @param value - */ - set(key: K, value: V): Promise - - /** - * List the values in the cache. - */ - values(): Promise - - /** - * Gets the sha of the key - * @param key - */ - getSha(key: K): Promise - - /** - * Gets an existing value or updates it with the updater function. - */ - getOrUpdate( - key: K, - updater: () => Promise, - validator?: (val: V) => boolean - ): Promise<{ key: string; value: V; cached?: boolean }> -} - -interface WorkspaceGrepOptions extends FilterGitFilesOptions { - /** - * List of paths to - */ - path?: ElementOrArray - /** - * list of filename globs to search. !-prefixed globs are excluded. ** are not supported. - */ - glob?: ElementOrArray - /** - * Read file content. default is true. - */ - readText?: boolean - - /** - * Enable grep logging to discover what files are searched. - */ - debug?: boolean -} - -interface WorkspaceGrepResult { - files: WorkspaceFile[] - matches: WorkspaceFile[] -} - -interface INIParseOptions extends JSONSchemaValidationOptions { - defaultValue?: any -} - -interface FilterGitFilesOptions { - /** - * Ignore workspace .gitignore instructions - */ - applyGitIgnore?: false | undefined -} - -interface FindFilesOptions extends FilterGitFilesOptions { - /** Glob patterns to ignore */ - ignore?: ElementOrArray - - /** - * Set to false to skip read text content. True by default - */ - readText?: boolean -} - -interface FileStats { - /** - * Size of the file in bytes - */ - size: number - mode: number -} - -interface JSONSchemaValidationOptions { - schema?: JSONSchema - throwOnValidationError?: boolean -} - -interface WorkspaceFileSystem { - /** - * Searches for files using the glob pattern and returns a list of files. - * Ignore `.env` files and apply `.gitignore` if present. - * @param glob - */ - findFiles( - glob: ElementOrArray, - options?: FindFilesOptions - ): Promise - - /** - * Performs a grep search over the files in the workspace using ripgrep. - * @param pattern A string to match or a regex pattern. - * @param options Options for the grep search. - */ - grep( - pattern: string | RegExp, - options?: WorkspaceGrepOptions - ): Promise - grep( - pattern: string | RegExp, - glob: string, - options?: Omit - ): Promise - - /** - * Reads metadata information about the file. Returns undefined if the file does not exist. - * @param filename - */ - stat(filename: string): Promise - - /** - * Reads the content of a file as text - * @param path - */ - readText(path: string | Awaitable): Promise - - /** - * Reads the content of a file and parses to JSON, using the JSON5 parser. - * @param path - */ - readJSON( - path: string | Awaitable, - options?: JSONSchemaValidationOptions - ): Promise - - /** - * Reads the content of a file and parses to YAML. - * @param path - */ - readYAML( - path: string | Awaitable, - options?: JSONSchemaValidationOptions - ): Promise - - /** - * Reads the content of a file and parses to XML, using the XML parser. - */ - readXML( - path: string | Awaitable, - options?: XMLParseOptions - ): Promise - - /** - * Reads the content of a CSV file. - * @param path - */ - readCSV( - path: string | Awaitable, - options?: CSVParseOptions - ): Promise - - /** - * Reads the content of a file and parses to INI - */ - readINI( - path: string | Awaitable, - options?: INIParseOptions - ): Promise - - /** - * Reads the content of a file and attempts to parse it as data. - * @param path - * @param options - */ - readData( - path: string | Awaitable, - options?: CSVParseOptions & - INIParseOptions & - XMLParseOptions & - JSONSchemaValidationOptions - ): Promise - - /** - * Appends text to a file as text to the file system. Creates the file if needed. - * @param path - * @param content - */ - appendText(path: string, content: string): Promise - - /** - * Writes a file as text to the file system - * @param path - * @param content - */ - writeText(path: string, content: string): Promise - - /** - * Caches a buffer to file and returns the unique file name - * @param bytes - */ - writeCached( - bytes: BufferLike, - options?: { - scope?: "workspace" | "run" - /** - * Filename extension - */ - ext?: string - } - ): Promise - - /** - * Writes one or more files to the workspace - * @param file a in-memory file or list of files - */ - writeFiles(file: ElementOrArray): Promise - - /** - * Copies a file between two paths - * @param source - * @param destination - */ - copyFile(source: string, destination: string): Promise - - /** - * Opens a file-backed key-value cache for the given cache name. - * The cache is persisted across runs of the script. Entries are dropped when the cache grows too large. - * @param cacheName - */ - cache( - cacheName: string - ): Promise> -} - -interface ToolCallContext { - log(message: string): void - debug(message: string): void - trace: ToolCallTrace -} - -interface ToolCallback { - spec: ToolDefinition - options?: DefToolOptions - generator?: ChatGenerationContext - impl: ( - args: { context: ToolCallContext } & Record - ) => Awaitable -} - -interface ChatContentPartText { - /** - * The text content. - */ - text: string - - /** - * The type of the content part. - */ - type: "text" -} - -interface ChatContentPartImage { - image_url: { - /** - * Either a URL of the image or the base64 encoded image data. - */ - url: string - - /** - * Specifies the detail level of the image. Learn more in the - * [Vision guide](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding). - */ - detail?: "auto" | "low" | "high" - } - - /** - * The type of the content part. - */ - type: "image_url" -} - -interface ChatContentPartInputAudio { - input_audio: { - /** - * Base64 encoded audio data. - */ - data: string - - /** - * The format of the encoded audio data. Currently supports "wav" and "mp3". - */ - format: "wav" | "mp3" - } - - /** - * The type of the content part. Always `input_audio`. - */ - type: "input_audio" -} - -interface ChatContentPartFile { - file: { - /** - * The base64 encoded file data, used when passing the file to the model as a - * string. - */ - file_data?: string - - /** - * The ID of an uploaded file to use as input. - */ - file_id?: string - - /** - * The name of the file, used when passing the file to the model as a string. - */ - filename?: string - } - - /** - * The type of the content part. Always `file`. - */ - type: "file" -} - -interface ChatContentPartRefusal { - /** - * The refusal message generated by the model. - */ - refusal: string - - /** - * The type of the content part. - */ - type: "refusal" -} - -interface ChatSystemMessage { - /** - * The contents of the system message. - */ - content: string | ChatContentPartText[] - - /** - * The role of the messages author, in this case `system`. - */ - role: "system" - - /** - * An optional name for the participant. Provides the model information to - * differentiate between participants of the same role. - */ - name?: string -} - -/** - * @deprecated - */ -interface ChatFunctionMessage { - content: string - name: string - role: "function" -} - -interface ChatToolMessage { - /** - * The contents of the tool message. - */ - content: string | ChatContentPartText[] - - /** - * The role of the messages author, in this case `tool`. - */ - role: "tool" - - /** - * Tool call that this message is responding to. - */ - tool_call_id: string -} - -interface ChatMessageToolCall { - /** - * The ID of the tool call. - */ - id: string - - /** - * The function that the model called. - */ - function: { - /** - * The arguments to call the function with, as generated by the model in JSON - * format. Note that the model does not always generate valid JSON, and may - * hallucinate parameters not defined by your function schema. Validate the - * arguments in your code before calling your function. - */ - arguments: string - - /** - * The name of the function to call. - */ - name: string - } - - /** - * The type of the tool. Currently, only `function` is supported. - */ - type: "function" -} - -interface ChatAssistantMessage { - /** - * The role of the messages author, in this case `assistant`. - */ - role: "assistant" - - /** - * The contents of the assistant message. Required unless `tool_calls` or - * `function_call` is specified. - */ - content?: string | (ChatContentPartText | ChatContentPartRefusal)[] - - /** - * An optional name for the participant. Provides the model information to - * differentiate between participants of the same role. - */ - name?: string - - /** - * The refusal message by the assistant. - */ - refusal?: string | null - - /** - * The tool calls generated by the model, such as function calls. - */ - tool_calls?: ChatMessageToolCall[] - - /** - * The reasoning of the model - */ - reasoning?: string -} - -type ChatContentPart = - | ChatContentPartText - | ChatContentPartImage - | ChatContentPartInputAudio - | ChatContentPartFile - -interface ChatUserMessage { - /** - * The contents of the user message. - */ - content: string | ChatContentPart[] - - /** - * The role of the messages author, in this case `user`. - */ - role: "user" - - /** - * An optional name for the participant. Provides the model information to - * differentiate between participants of the same role. - */ - name?: string -} - -type ChatMessage = - | ChatSystemMessage - | ChatUserMessage - | ChatAssistantMessage - | ChatToolMessage - | ChatFunctionMessage - -type ChatParticipantHandler = ( - /** - * Prompt generation context to create a new message in the conversation - */ - context: ChatTurnGenerationContext, - /** - * Chat conversation messages - */ - messages: ChatMessage[], - /** - * The last assistant text, without - * reasoning sections. - */ - assistantText: string -) => Awaitable<{ messages?: ChatMessage[] } | undefined | void> - -interface ChatParticipantOptions { - label?: string -} - -interface ChatParticipant { - generator: ChatParticipantHandler - options: ChatParticipantOptions -} - -/** - * A set of text extracted from the context of the prompt execution - */ -interface ExpansionVariables { - /** - * Directory where the prompt is executed - */ - dir: string - - /** - * Directory where output files (trace, output) are created - */ - runDir: string - - /** - * Unique identifier for the run - */ - runId: string - - /** - * List of linked files parsed in context - */ - files: WorkspaceFile[] - - /** - * User defined variables - */ - vars: Record & { - /** - * When running in GitHub Copilot Chat, the current user prompt - */ - question?: string - /** - * When running in GitHub Copilot Chat, the current chat history - */ - "copilot.history"?: (HistoryMessageUser | HistoryMessageAssistant)[] - /** - * When running in GitHub Copilot Chat, the current editor content - */ - "copilot.editor"?: string - /** - * When running in GitHub Copilot Chat, the current selection - */ - "copilot.selection"?: string - /** - * When running in GitHub Copilot Chat, the current terminal content - */ - "copilot.terminalSelection"?: string - /** - * Selected model identifier in GitHub Copilot Chat - */ - "copilot.model"?: string - /** - * selected text in active text editor - */ - "editor.selectedText"?: string - } - - /** - * List of secrets used by the prompt, must be registered in `genaiscript`. - */ - secrets: Record - - /** - * Root prompt generation context - */ - generator: ChatGenerationContext - - /** - * Output trace builder - */ - output: OutputTrace - - /** - * Resolved metadata - */ - meta: PromptDefinition & ModelConnectionOptions - - /** - * The script debugger logger - */ - dbg: DebugLogger -} - -type MakeOptional = Partial> & Omit - -type PromptArgs = Omit< - PromptScript, - "text" | "id" | "jsSource" | "defTools" | "resolvedSystem" -> - -type PromptSystemArgs = Omit< - PromptArgs, - | "model" - | "embeddingsModel" - | "temperature" - | "topP" - | "maxTokens" - | "seed" - | "tests" - | "responseLanguage" - | "responseType" - | "responseSchema" - | "files" - | "modelConcurrency" - | "redteam" - | "metadata" -> - -type StringLike = string | WorkspaceFile | WorkspaceFile[] - -interface LineNumberingOptions { - /** - * Prepend each line with a line numbers. Helps with generating diffs. - */ - lineNumbers?: boolean -} - -interface FenceOptions extends LineNumberingOptions, FenceFormatOptions { - /** - * Language of the fenced code block. Defaults to "markdown". - */ - language?: - | "markdown" - | "json" - | "yaml" - | "javascript" - | "typescript" - | "python" - | "shell" - | "toml" - | string - - /** - * JSON schema identifier - */ - schema?: string -} - -type PromptCacheControlType = "ephemeral" - -interface ContextExpansionOptions { - /** - * Specifies an maximum of estimated tokens for this entry; after which it will be truncated. - */ - maxTokens?: number - - /* - * Value that is conceptually similar to a zIndex (higher number == higher priority). - * If a rendered prompt has more message tokens than can fit into the available context window, the prompt renderer prunes messages with the lowest priority from the ChatMessages result, preserving the order in which they were declared. This means your extension code can safely declare TSX components for potentially large pieces of context like conversation history and codebase context. - */ - priority?: number - - /** - * Controls the proportion of tokens allocated from the container's budget to this element. - * It defaults to 1 on all elements. - */ - flex?: number - - /** - * Caching policy for this text. `ephemeral` means the prefix can be cached for a short amount of time. - */ - cacheControl?: PromptCacheControlType -} - -interface RangeOptions { - /** - * The inclusive start of the line range, with a 1-based index - */ - lineStart?: number - /** - * The inclusive end of the line range, with a 1-based index - */ - lineEnd?: number -} - -interface GitIgnoreFilterOptions { - /** - * Disable filtering files based on the `.gitignore` file. - */ - ignoreGitIgnore?: true | undefined -} - -interface FileFilterOptions extends GitIgnoreFilterOptions { - /** - * Filename filter based on file suffix. Case insensitive. - */ - endsWith?: ElementOrArray - - /** - * Filename filter using glob syntax. - */ - glob?: ElementOrArray -} - -interface ContentSafetyOptions { - /** - * Configure the content safety provider. - */ - contentSafety?: ContentSafetyProvider - /** - * Runs the default content safety validator - * to prevent prompt injection. - */ - detectPromptInjection?: "always" | "available" | boolean -} - -interface PromptSystemSafetyOptions { - /** - * Policy to inject builtin system prompts. See to `false` prevent automatically injecting. - */ - systemSafety?: "default" | boolean -} - -interface SecretDetectionOptions { - /** - * Policy to disable secret scanning when communicating with the LLM. - * Set to `false` to disable. - */ - secretScanning?: boolean -} - -interface DefOptions - extends FenceOptions, - ContextExpansionOptions, - DataFilter, - RangeOptions, - FileFilterOptions, - ContentSafetyOptions { - /** - * By default, throws an error if the value in def is empty. - */ - ignoreEmpty?: boolean - - /** - * The content of the def is a predicted output. - * This setting disables line numbers. - */ - prediction?: boolean -} - -/** - * Options for the `defDiff` command. - */ -interface DefDiffOptions - extends ContextExpansionOptions, - FenceFormatOptions, - LineNumberingOptions {} - -interface ImageTransformOptions { - /** - * Crops the image to the specified region. - */ - crop?: { x?: number; y?: number; w?: number; h?: number } - /** - * Auto cropping same color on the edges of the image - */ - autoCrop?: boolean - /** - * Applies a scaling factor to the image after cropping. - */ - scale?: number - /** - * Rotates the image by the specified number of degrees. - */ - rotate?: number - /** - * Maximum width of the image. Applied after rotation. - */ - maxWidth?: number - /** - * Maximum height of the image. Applied after rotation. - */ - maxHeight?: number - /** - * Removes colors from the image using ITU Rec 709 luminance values - */ - greyscale?: boolean - - /** - * Flips the image horizontally and/or vertically. - */ - flip?: { horizontal?: boolean; vertical?: boolean } - - /** - * Output mime - */ - mime?: "image/jpeg" | "image/png" -} - -interface DefImagesOptions extends ImageTransformOptions { - /** - * A "low" detail image is always downsampled to 512x512 pixels. - */ - detail?: "high" | "low" - /** - * Selects the first N elements from the data - */ - sliceHead?: number - /** - * Selects the last N elements from the data - */ - sliceTail?: number - /** - * Selects the a random sample of N items in the collection. - */ - sliceSample?: number - /** - * Renders all images in a single tiled image - */ - tiled?: boolean - - /** - * By default, throws an error if no images are passed. - */ - ignoreEmpty?: boolean -} - -type JSONSchemaTypeName = - | "string" - | "number" - | "integer" - | "boolean" - | "object" - | "array" - | "null" - -type JSONSchemaSimpleType = - | JSONSchemaString - | JSONSchemaNumber - | JSONSchemaBoolean - | JSONSchemaObject - | JSONSchemaArray - -type JSONSchemaType = JSONSchemaSimpleType | JSONSchemaAnyOf | null - -interface JSONSchemaAnyOf { - anyOf: JSONSchemaType[] - uiGroup?: string -} - -interface JSONSchemaDescribed { - /** - * A short description of the property - */ - title?: string - /** - * A clear description of the property. - */ - description?: string - - /** - * Moves the field to a sub-group in the form, potentially collapsed - */ - uiGroup?: string -} - -interface JSONSchemaString extends JSONSchemaDescribed { - type: "string" - uiType?: "textarea" - uiSuggestions?: string[] - enum?: string[] - default?: string - pattern?: string -} - -interface JSONSchemaNumber extends JSONSchemaDescribed { - type: "number" | "integer" - default?: number - minimum?: number - exclusiveMinimum?: number - maximum?: number - exclusiveMaximum?: number -} - -interface JSONSchemaBoolean extends JSONSchemaDescribed { - type: "boolean" - uiType?: "runOption" - default?: boolean -} - -interface JSONSchemaObject extends JSONSchemaDescribed { - $schema?: string - type: "object" - properties?: { - [key: string]: JSONSchemaType - } - required?: string[] - additionalProperties?: boolean - - default?: object -} - -interface JSONSchemaArray extends JSONSchemaDescribed { - $schema?: string - type: "array" - items?: JSONSchemaType - - default?: any[] -} - -type JSONSchema = JSONSchemaObject | JSONSchemaArray - -interface FileEditValidation { - /** - * JSON schema - */ - schema?: JSONSchema - /** - * Error while validating the JSON schema - */ - schemaError?: string - /** - * The path was validated with a file output (defFileOutput) - */ - pathValid?: boolean -} - -interface DataFrame { - schema?: string - data: unknown - validation?: FileEditValidation -} - -interface Logprob { - /** - * Token text - */ - token: string - /** - * Log probably of the generated token - */ - logprob: number - /** - * Logprob value converted to % - */ - probPercent?: number - /** - * Normalized entropy - */ - entropy?: number - /** - * Other top tokens considered by the LLM - */ - topLogprobs?: { token: string; logprob: number }[] -} - -interface RunPromptUsage { - /** - * Estimated cost in $ of the generation - */ - cost?: number - /** - * Estimated duration of the generation - * including multiple rounds with tools - */ - duration?: number - /** - * Number of tokens in the generated completion. - */ - completion: number - - /** - * Number of tokens in the prompt. - */ - prompt: number - /** - * Total number of tokens used in the request (prompt + completion). - */ - total: number -} - -interface RunPromptResult { - messages: ChatMessage[] - text: string - reasoning?: string - annotations?: Diagnostic[] - fences?: Fenced[] - frames?: DataFrame[] - json?: any - error?: SerializedError - schemas?: Record - finishReason: - | "stop" - | "length" - | "tool_calls" - | "content_filter" - | "cancel" - | "fail" - fileEdits?: Record - edits?: Edits[] - changelogs?: string[] - model?: ModelType - choices?: Logprob[] - logprobs?: Logprob[] - perplexity?: number - uncertainty?: number - usage?: RunPromptUsage -} - -/** - * Path manipulation functions. - */ -interface Path { - parse(path: string): { - /** - * The root of the path such as '/' or 'c:\' - */ - root: string - /** - * The full directory path such as '/home/user/dir' or 'c:\path\dir' - */ - dir: string - /** - * The file name including extension (if any) such as 'index.html' - */ - base: string - /** - * The file extension (if any) such as '.html' - */ - ext: string - /** - * The file name without extension (if any) such as 'index' - */ - name: string - } - - /** - * Returns the last portion of a path. Similar to the Unix basename command. - * @param path - */ - dirname(path: string): string - - /** - * Returns the extension of the path, from the last '.' to end of string in the last portion of the path. - * @param path - */ - extname(path: string): string - - /** - * Returns the last portion of a path, similar to the Unix basename command. - */ - basename(path: string, suffix?: string): string - - /** - * The path.join() method joins all given path segments together using the platform-specific separator as a delimiter, then normalizes the resulting path. - * @param paths - */ - join(...paths: string[]): string - - /** - * The path.normalize() method normalizes the given path, resolving '..' and '.' segments. - */ - normalize(...paths: string[]): string - - /** - * The path.relative() method returns the relative path from from to to based on the current working directory. If from and to each resolve to the same path (after calling path.resolve() on each), a zero-length string is returned. - */ - relative(from: string, to: string): string - - /** - * The path.resolve() method resolves a sequence of paths or path segments into an absolute path. - * @param pathSegments - */ - resolve(...pathSegments: string[]): string - - /** - * Determines whether the path is an absolute path. - * @param path - */ - isAbsolute(path: string): boolean - - /** - * Change the extension of a path - * @param path - * @param ext - */ - changeext(path: string, ext: string): string - - /** - * Converts a file://... to a path - * @param fileUrl - */ - resolveFileURL(fileUrl: string): string - - /** - * Sanitize a string to be safe for use as a filename by removing directory paths and invalid characters. - * @param path file path - */ - sanitize(path: string): string -} - -interface Fenced { - label: string - language?: string - content: string - args?: { schema?: string } & Record - - validation?: FileEditValidation -} - -interface XMLParseOptions extends JSONSchemaValidationOptions { - allowBooleanAttributes?: boolean - ignoreAttributes?: boolean - ignoreDeclaration?: boolean - ignorePiTags?: boolean - parseAttributeValue?: boolean - removeNSPrefix?: boolean - unpairedTags?: string[] -} - -interface ParsePDFOptions { - /** - * Disable removing trailing spaces in text - */ - disableCleanup?: boolean - /** - * Render each page as an image - */ - renderAsImage?: boolean - /** - * Zoom scaling with rendering pages and figures - */ - scale?: number - /** - * Disable caching with cache: false - */ - cache?: boolean - /** - * Force system fonts use - */ - useSystemFonts?: boolean -} - -interface HTMLToTextOptions { - /** - * After how many chars a line break should follow in `p` elements. - * - * Set to `null` or `false` to disable word-wrapping. - */ - wordwrap?: number | false | null | undefined -} - -interface ParseXLSXOptions { - // specific worksheet name - sheet?: string - // Use specified range (A1-style bounded range string) - range?: string -} - -interface WorkbookSheet { - name: string - rows: object[] -} - -interface ParseZipOptions { - glob?: string -} - -type TokenEncoder = (text: string) => number[] -type TokenDecoder = (lines: Iterable) => string - -interface Tokenizer { - model: string - /** - * Number of tokens - */ - size?: number - encode: TokenEncoder - decode: TokenDecoder -} - -interface CSVParseOptions extends JSONSchemaValidationOptions { - delimiter?: string - headers?: string[] - repair?: boolean -} - -interface TextChunk extends WorkspaceFile { - lineStart: number - lineEnd: number -} - -interface TextChunkerConfig extends LineNumberingOptions { - model?: ModelType - chunkSize?: number - chunkOverlap?: number - docType?: OptionsOrString< - | "cpp" - | "python" - | "py" - | "java" - | "go" - | "c#" - | "c" - | "cs" - | "ts" - | "js" - | "tsx" - | "typescript" - | "js" - | "jsx" - | "javascript" - | "php" - | "md" - | "mdx" - | "markdown" - | "rst" - | "rust" - > -} - -interface Tokenizers { - /** - * Estimates the number of tokens in the content. May not be accurate - * @param model - * @param text - */ - count(text: string, options?: { model?: ModelType }): Promise - - /** - * Truncates the text to a given number of tokens, approximation. - * @param model - * @param text - * @param maxTokens - * @param options - */ - truncate( - text: string, - maxTokens: number, - options?: { model?: ModelType; last?: boolean } - ): Promise - - /** - * Tries to resolve a tokenizer for a given model. Defaults to gpt-4o if not found. - * @param model - */ - resolve(model?: ModelType): Promise - - /** - * Chunk the text into smaller pieces based on a token limit and chunking strategy. - * @param text - * @param options - */ - chunk( - file: Awaitable, - options?: TextChunkerConfig - ): Promise -} - -interface HashOptions { - /** - * Algorithm used for hashing - */ - algorithm?: "sha-256" - /** - * Trim hash to this number of character - */ - length?: number - /** - * Include genaiscript version in the hash - */ - version?: boolean - /** - * Optional salting of the hash - */ - salt?: string - /** - * Read the content of workspace files object into the hash - */ - readWorkspaceFiles?: boolean -} - -interface VideoProbeResult { - streams: { - index: number - codec_name: string - codec_long_name: string - profile: string - codec_type: string - codec_tag_string: string - codec_tag: string - width?: number - height?: number - coded_width?: number - coded_height?: number - closed_captions?: number - film_grain?: number - has_b_frames?: number - sample_aspect_ratio?: string - display_aspect_ratio?: string - pix_fmt?: string - level?: number - color_range?: string - color_space?: string - color_transfer?: string - color_primaries?: string - chroma_location?: string - field_order?: string - refs?: number - is_avc?: string - nal_length_size?: number - id: string - r_frame_rate: string - avg_frame_rate: string - time_base: string - start_pts: number - start_time: number - duration_ts: number - duration: number - bit_rate: number - max_bit_rate: string - bits_per_raw_sample: number | string - nb_frames: number | string - nb_read_frames?: string - nb_read_packets?: string - extradata_size?: number - tags?: { - creation_time: string - language?: string - handler_name: string - vendor_id?: string - encoder?: string - } - disposition?: { - default: number - dub: number - original: number - comment: number - lyrics: number - karaoke: number - forced: number - hearing_impaired: number - visual_impaired: number - clean_effects: number - attached_pic: number - timed_thumbnails: number - captions: number - descriptions: number - metadata: number - dependent: number - still_image: number - } - sample_fmt?: string - sample_rate?: number - channels?: number - channel_layout?: string - bits_per_sample?: number | string - }[] - format: { - filename: string - nb_streams: number - nb_programs: number - format_name: string - format_long_name: string - start_time: number - duration: number - size: number - bit_rate: number - probe_score: number - tags: { - major_brand: string - minor_version: string - compatible_brands: string - creation_time: string - } - } -} - -interface PDFPageImage extends WorkspaceFile { - id: string - width: number - height: number -} - -interface PDFPage { - index: number - content: string - image?: string - figures?: PDFPageImage[] -} - -interface DocxParseOptions extends CacheOptions { - /** - * Desired output format - */ - format?: "markdown" | "text" | "html" -} - -interface EncodeIDsOptions { - matcher?: RegExp - prefix?: string - open?: string - close?: string -} - -interface Parsers { - /** - * Parses text as a JSON5 payload - */ - JSON5( - content: string | WorkspaceFile, - options?: { defaultValue?: any } & JSONSchemaValidationOptions - ): any | undefined - - /** - * Parses text generated by an LLM as JSON payload - * @param content - */ - JSONLLM(content: string): 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 payload - */ - YAML( - content: string | WorkspaceFile, - options?: { defaultValue?: any } & JSONSchemaValidationOptions - ): any | undefined - - /** - * Parses text as TOML payload - * @param text text as TOML payload - */ - TOML( - content: string | WorkspaceFile, - options?: { defaultValue?: any } & JSONSchemaValidationOptions - ): any | undefined - - /** - * Parses the front matter of a markdown file - * @param content - * @param defaultValue - */ - frontmatter( - content: string | WorkspaceFile, - options?: { - defaultValue?: any - format: "yaml" | "json" | "toml" - } & JSONSchemaValidationOptions - ): any | undefined - - /** - * Parses a file or URL as PDF - * @param content - */ - PDF( - content: string | WorkspaceFile, - options?: ParsePDFOptions - ): Promise< - | { - /** - * Reconstructed text content from page content - */ - file: WorkspaceFile - /** - * Page text content - */ - pages: string[] - /** - * Rendered pages as images if `renderAsImage` is set - */ - images?: string[] - - /** - * Parse PDF content - */ - data: PDFPage[] - } - | undefined - > - - /** - * Parses a .docx file - * @param content - */ - DOCX( - content: string | WorkspaceFile, - options?: DocxParseOptions - ): Promise<{ file?: WorkspaceFile; error?: string }> - - /** - * Parses a CSV file or text - * @param content - */ - CSV( - content: string | WorkspaceFile, - options?: CSVParseOptions - ): object[] | undefined - - /** - * Parses a XLSX file and a given worksheet - * @param content - */ - XLSX( - content: WorkspaceFile, - options?: ParseXLSXOptions - ): Promise - - /** - * Parses a .env file - * @param content - */ - dotEnv(content: string | WorkspaceFile): Record - - /** - * Parses a .ini file - * @param content - */ - INI( - content: string | WorkspaceFile, - options?: INIParseOptions - ): any | undefined - - /** - * Parses a .xml file - * @param content - */ - XML( - content: string | WorkspaceFile, - options?: { defaultValue?: any } & XMLParseOptions - ): any | undefined - - /** - * Parses .vtt or .srt transcription files - * @param content - */ - transcription(content: string | WorkspaceFile): TranscriptionSegment[] - - /** - * Convert HTML to text - * @param content html string or file - * @param options - */ - HTMLToText( - content: string | WorkspaceFile, - options?: HTMLToTextOptions - ): Promise - - /** - * Convert HTML to markdown - * @param content html string or file - * @param options rendering options - */ - HTMLToMarkdown( - content: string | WorkspaceFile, - options?: HTMLToMarkdownOptions - ): Promise - - /** - * Parsers a mermaid diagram and returns the parse error if any - * @param content - */ - mermaid( - content: string | WorkspaceFile - ): Promise<{ error?: string; diagramType?: string }> - - /** - * Extracts the contents of a zip archive file - * @param file - * @param options - */ - unzip( - file: WorkspaceFile, - options?: ParseZipOptions - ): Promise - - /** - * Estimates the number of tokens in the content. - * @param content content to tokenize - */ - tokens(content: string | WorkspaceFile): number - - /** - * Parses fenced code sections in a markdown text - */ - fences(content: string | WorkspaceFile): Fenced[] - - /** - * Parses various format of annotations (error, warning, ...) - * @param content - */ - annotations(content: string | WorkspaceFile): Diagnostic[] - - /** - * Executes a tree-sitter query on a code file - * @param file - * @param query tree sitter query; if missing, returns the entire tree. `tags` return tags - */ - code( - file: WorkspaceFile, - query?: OptionsOrString<"tags"> - ): Promise<{ captures: QueryCapture[] }> - - /** - * Parses and evaluates a math expression - * @param expression math expression compatible with mathjs - * @param scope object to read/write variables - */ - math( - expression: string, - scope?: object - ): Promise - - /** - * Using the JSON schema, validates the content - * @param schema JSON schema instance - * @param content object to validate - */ - validateJSON(schema: JSONSchema, content: any): FileEditValidation - - /** - * Renders a mustache template - * @param text template text - * @param data data to render - */ - mustache(text: string | WorkspaceFile, data: Record): string - - /** - * Renders a jinja template - */ - jinja(text: string | WorkspaceFile, data: Record): string - - /** - * Computes a diff between two files - */ - diff( - left: string | WorkspaceFile, - right: string | WorkspaceFile, - options?: DefDiffOptions - ): string - - /** - * Cleans up a dataset made of rows of data - * @param rows - * @param options - */ - tidyData(rows: object[], options?: DataFilter): object[] - - /** - * Applies a GROQ query to the data - * @param data data object to filter - * @param query query - * @see https://groq.dev/ - */ - GROQ(query: string, data: any): Promise - - /** - * Computes a sha1 that can be used for hashing purpose, not cryptographic. - * @param content content to hash - */ - hash(content: any, options?: HashOptions): Promise - - /** - * Optionally removes a code fence section around the text - * @param text - * @param language - */ - unfence(text: string, language?: ElementOrArray): string - - /** - * Erase ... tags - * @param text - */ - unthink(text: string): string - - /** - * Remove left indentation - * @param text - */ - dedent(templ: TemplateStringsArray | string, ...values: unknown[]): string - - /** - * Encodes ids in a text and returns the function to decode them - * @param text - * @param options - */ - encodeIDs( - text: string, - options?: EncodeIDsOptions - ): { - encoded: string - text: string - decode: (text: string) => string - matcher: RegExp - ids: Record - } - - /** - * Parses a prompty file - * @param file - */ - prompty(file: WorkspaceFile): Promise -} - -interface YAML { - /** - * Parses a YAML string into a JavaScript object using JSON5. - */ - (strings: TemplateStringsArray, ...values: any[]): any - - /** - * Converts an object to its YAML representation - * @param obj - */ - stringify(obj: any): string - /** - * Parses a YAML string to object - */ - parse(text: string | WorkspaceFile): any -} - -interface Z3Solver { - /** - * Runs Z3 on a given SMT string - * @param smt - */ - run(smt: string): Promise - - /** - * Native underlying Z3 api - */ - api(): any -} - -interface Z3SolverHost { - /** - * Loads the Z3 solver from the host - */ - z3(): Promise -} - -interface PromptyFrontmatter { - name?: string - description?: string - version?: string - authors?: string[] - tags?: string[] - sample?: Record | string - inputs?: Record< - string, - | JSONSchemaArray - | JSONSchemaNumber - | JSONSchemaBoolean - | JSONSchemaString - | JSONSchemaObject - | { type: "list" } - > - outputs?: JSONSchemaObject - model?: { - api?: "chat" | "completion" - configuration?: { - type?: string - name?: string - organization?: string - api_version?: string - azure_deployment: string - azure_endpoint: string - } - parameters?: { - response_format?: { type: "json_object" | "json_schema" } - max_tokens?: number - temperature?: number - top_p?: number - n?: number - seed?: number - stream?: boolean // ignored - tools?: unknown[] // ignored - } - } - - // unofficial - files?: string | string[] - tests?: PromptTest | PromptTest[] -} - -interface PromptyDocument { - meta: PromptArgs - frontmatter: PromptyFrontmatter - content: string - messages: ChatMessage[] -} - -interface DiffFile { - chunks: DiffChunk[] - deletions: number - additions: number - from?: string - to?: string - oldMode?: string - newMode?: string - index?: string[] - deleted?: true - new?: true -} - -interface DiffChunk { - content: string - changes: DiffChange[] - oldStart: number - oldLines: number - newStart: number - newLines: number -} - -interface DiffNormalChange { - type: "normal" - ln1: number - ln2: number - normal: true - content: string -} - -interface DiffAddChange { - type: "add" - add: true - ln: number - content: string -} - -interface DiffDeleteChange { - type: "del" - del: true - ln: number - content: string -} - -type DiffChangeType = "normal" | "add" | "del" - -type DiffChange = DiffNormalChange | DiffAddChange | DiffDeleteChange - -interface DIFF { - /** - * Parses a diff string into a structured object - * @param input - */ - parse(input: string): DiffFile[] - - /** - * Given a filename and line number (0-based), finds the chunk in the diff - * @param file - * @param range line index or range [start, end] inclusive - * @param diff - */ - findChunk( - file: string, - range: number | [number, number] | number[], - diff: ElementOrArray - ): { file?: DiffFile; chunk?: DiffChunk } | undefined - - /** - * Creates a two file path - * @param left - * @param right - * @param options - */ - createPatch( - left: string | WorkspaceFile, - right: string | WorkspaceFile, - options?: { - context?: number - ignoreCase?: boolean - ignoreWhitespace?: boolean - } - ): string -} - -interface XML { - /** - * Parses an XML payload to an object - * @param text - */ - parse(text: string | WorkspaceFile, options?: XMLParseOptions): any -} - -interface JSONSchemaUtilities { - /** - * Infers a JSON schema from an object - * @param obj - * @deprecated Use `fromParameters` instead - */ - infer(obj: any): Promise - - /** - * Converts a parameters schema to a JSON schema - * @param parameters - */ - fromParameters(parameters: PromptParametersSchema | undefined): JSONSchema -} - -interface HTMLTableToJSONOptions { - useFirstRowForHeadings?: boolean - headers?: { - from?: number - to: number - concatWith: string - } - stripHtmlFromHeadings?: boolean - stripHtmlFromCells?: boolean - stripHtml?: boolean | null - forceIndexAsNumber?: boolean - countDuplicateHeadings?: boolean - ignoreColumns?: number[] | null - onlyColumns?: number[] | null - ignoreHiddenRows?: boolean - id?: string[] | null - headings?: string[] | null - containsClasses?: string[] | null - limitrows?: number | null -} - -interface HTMLToMarkdownOptions { - disableGfm?: boolean -} - -interface HTML { - /** - * Converts all HTML tables to JSON. - * @param html - * @param options - */ - convertTablesToJSON( - html: string, - options?: HTMLTableToJSONOptions - ): Promise - /** - * Converts HTML markup to plain text - * @param html - */ - convertToText(html: string): Promise - /** - * Converts HTML markup to markdown - * @param html - */ - convertToMarkdown( - html: string, - options?: HTMLToMarkdownOptions - ): Promise -} - -interface GitCommit { - sha: string - date: string - message: string -} - -interface Git { - /** - * Current working directory - */ - cwd: string - - /** - * Resolves the default branch for this repository - */ - defaultBranch(): Promise - - /** - * Gets the last tag in the repository - */ - lastTag(): Promise - - /** - * Gets the current branch of the repository - */ - branch(): Promise - - /** - * Executes a git command in the repository and returns the stdout - * @param cmd - */ - exec( - args: string[] | string, - options?: { - label?: string - } - ): Promise - - /** - * Git fetches the remote repository - * @param options - */ - fetch( - remote?: OptionsOrString<"origin">, - branchOrSha?: string, - options?: { - prune?: boolean - all?: boolean - } - ): Promise - - /** - * Git pull the remote repository - * @param options - */ - pull(options?: { ff?: boolean }): Promise - - /** - * Lists the branches in the git repository - */ - listBranches(): Promise - - /** - * Finds specific files in the git repository. - * By default, work - * @param options - */ - listFiles( - scope?: "modified-base" | "staged" | "modified", - options?: { - base?: string - /** - * Ask the user to stage the changes if the diff is empty. - */ - askStageOnEmpty?: boolean - paths?: ElementOrArray - excludedPaths?: ElementOrArray - } - ): Promise - - /** - * - * @param options - */ - diff(options?: { - staged?: boolean - /** - * Ask the user to stage the changes if the diff is empty. - */ - askStageOnEmpty?: boolean - base?: string - head?: string - paths?: ElementOrArray - excludedPaths?: ElementOrArray - unified?: number - nameOnly?: boolean - algorithm?: "patience" | "minimal" | "histogram" | "myers" - ignoreSpaceChange?: boolean - extras?: string[] - /** - * Modifies the diff to be in a more LLM friendly format - */ - llmify?: boolean - /** - * Maximum of tokens before returning a name-only diff - */ - maxTokensFullDiff?: number - }): Promise - - /** - * Lists the commits in the git repository - */ - log(options?: { - base?: string - head?: string - count?: number - merges?: boolean - author?: string - until?: string - after?: string - excludedGrep?: string | RegExp - paths?: ElementOrArray - excludedPaths?: ElementOrArray - }): Promise - - /** - * Run git blame on a file, line - * @param filename - * @param line - */ - blame(filename: string, line: number): Promise - - /** - * Create a shallow git clone - * @param repository URL of the remote repository - * @param options various clone options - * @returns the path to the cloned repository - */ - shallowClone( - repository: string, - options?: { - /** - * Branch to clone - */ - branch?: string - - /** - * Do not reuse previous clone - */ - force?: boolean - - /** - * Runs install command after cloning - */ - install?: boolean - - /** - * Number of commits to fetch - */ - depth?: number - } - ): Promise - - /** - * Open a git client on a different directory - * @param cwd working directory - */ - client(cwd: string): Git -} - -/** - * A ffmpeg command builder. This instance is the 'native' fluent-ffmpeg command builder. - */ -interface FfmpegCommandBuilder { - seekInput(startTime: number | string): FfmpegCommandBuilder - duration(duration: number | string): FfmpegCommandBuilder - noVideo(): FfmpegCommandBuilder - noAudio(): FfmpegCommandBuilder - audioCodec(codec: string): FfmpegCommandBuilder - audioBitrate(bitrate: string | number): FfmpegCommandBuilder - audioChannels(channels: number): FfmpegCommandBuilder - audioFrequency(freq: number): FfmpegCommandBuilder - audioQuality(quality: number): FfmpegCommandBuilder - audioFilters( - filters: string | string[] /*| AudioVideoFilter[]*/ - ): FfmpegCommandBuilder - toFormat(format: string): FfmpegCommandBuilder - - videoCodec(codec: string): FfmpegCommandBuilder - videoBitrate( - bitrate: string | number, - constant?: boolean - ): FfmpegCommandBuilder - videoFilters(filters: string | string[]): FfmpegCommandBuilder - outputFps(fps: number): FfmpegCommandBuilder - frames(frames: number): FfmpegCommandBuilder - keepDisplayAspectRatio(): FfmpegCommandBuilder - size(size: string): FfmpegCommandBuilder - aspectRatio(aspect: string | number): FfmpegCommandBuilder - autopad(pad?: boolean, color?: string): FfmpegCommandBuilder - - inputOptions(...options: string[]): FfmpegCommandBuilder - outputOptions(...options: string[]): FfmpegCommandBuilder -} - -interface FFmpegCommandOptions extends CacheOptions { - inputOptions?: ElementOrArray - outputOptions?: ElementOrArray - /** - * For video conversion, output size as `wxh` - */ - size?: string -} - -interface VideoExtractFramesOptions extends FFmpegCommandOptions { - /** - * A set of seconds or timestamps (`[[hh:]mm:]ss[.xxx]`) - */ - timestamps?: number[] | string[] - /** - * Number of frames to extract - */ - count?: number - /** - * Extract frames on the start of each transcript segment - */ - transcript?: TranscriptionResult | string - /** - * Extract Intra frames (keyframes). This is a efficient and fast decoding. - */ - keyframes?: boolean - /** - * Picks frames that exceed scene threshold (between 0 and 1), typically between 0.2, and 0.5. - * This is computationally intensive. - */ - sceneThreshold?: number - /** - * Output of the extracted frames - */ - format?: OptionsOrString<"jpeg" | "png"> -} - -interface VideoExtractClipOptions extends FFmpegCommandOptions { - /** - * Start time of the clip in seconds or timestamp (`[[hh:]mm:]ss[.xxx]`) - */ - start: number | string - /** - * Duration of the clip in seconds or timestamp (`[[hh:]mm:]ss[.xxx]`). - * You can also specify `end`. - */ - duration?: number | string - /** - * End time of the clip in seconds or timestamp (`[[hh:]mm:]ss[.xxx]`). - * You can also specify `duration`. - */ - end?: number | string -} - -interface VideoExtractAudioOptions extends FFmpegCommandOptions { - /** - * Optimize for speech-to-text transcription. Default is true. - */ - transcription?: boolean - - forceConversion?: boolean -} - -interface Ffmpeg { - /** - * Extracts metadata information from a video file using ffprobe - * @param filename - */ - probe( - file: string | WorkspaceFile, - options?: FFmpegCommandOptions - ): Promise - - /** - * Extracts frames from a video file - * @param options - */ - extractFrames( - file: string | WorkspaceFile, - options?: VideoExtractFramesOptions - ): Promise - - /** - * Extracts a clip from a video. Returns the generated video file path. - */ - extractClip( - file: string | WorkspaceFile, - options: VideoExtractClipOptions - ): Promise - - /** - * Extract the audio track from a video - * @param videoPath - */ - extractAudio( - file: string | WorkspaceFile, - options?: VideoExtractAudioOptions - ): Promise - - /** - * Runs a ffmpeg command and returns the list of generated file names - * @param input - * @param builder manipulates the ffmpeg command and returns the output name - */ - run( - input: string | WorkspaceFile, - builder: ( - cmd: FfmpegCommandBuilder, - options?: { input: string; dir: string } - ) => Awaitable, - options?: FFmpegCommandOptions - ): Promise -} - -interface TranscriptionSegment { - id?: string - start: number - end?: number - text: string -} - -interface GitHubOptions { - owner: string - repo: string - baseUrl?: string - auth?: string - ref?: string - refName?: string - issueNumber?: number -} - -type GitHubWorkflowRunStatus = - | "completed" - | "action_required" - | "cancelled" - | "failure" - | "neutral" - | "skipped" - | "stale" - | "success" - | "timed_out" - | "in_progress" - | "queued" - | "requested" - | "waiting" - | "pending" - -interface GitHubWorkflowRun { - id: number - run_number: number - name?: string - display_title: string - status: string - conclusion: string - html_url: string - created_at: string - head_branch: string - head_sha: string - workflow_id: number - run_started_at?: string -} - -interface GitHubWorkflowJob { - id: number - run_id: number - status: string - conclusion: string - name: string - html_url: string - logs_url: string - logs: string - started_at: string - completed_at: string - content: string -} - -interface GitHubIssue { - id: number - body?: string - title: string - number: number - state: string - state_reason?: "completed" | "reopened" | "not_planned" | null - html_url: string - draft?: boolean - reactions?: GitHubReactions - user: GitHubUser - assignee?: GitHubUser -} - -interface GitHubRef { - ref: string - url: string -} - -interface GitHubReactions { - url: string - total_count: number - "+1": number - "-1": number - laugh: number - confused: number - heart: number - hooray: number - eyes: number - rocket: number -} - -interface GitHubComment { - id: number - body?: string - user: GitHubUser - created_at: string - updated_at: string - html_url: string - reactions?: GitHubReactions -} - -interface GitHubPullRequest extends GitHubIssue { - head: { - ref: string - } - base: { - ref: string - } -} - -interface GitHubCodeSearchResult { - name: string - path: string - sha: string - html_url: string - score: number - repository: string -} - -interface GitHubWorkflow { - id: number - name: string - path: string -} - -interface GitHubPaginationOptions { - /** - * Default number of items to fetch, default is 50. - */ - count?: number -} - -interface GitHubFile extends WorkspaceFile { - type: "file" | "dir" | "submodule" | "symlink" - size: number -} - -interface GitHubUser { - login: string -} - -interface GitHubRelease { - id: number - tag_name: string - name: string - draft?: boolean - prerelease?: boolean - html_url: string - published_at: string - body?: string -} - -interface GitHubGist { - id: string - description?: string - created_at?: string - files: WorkspaceFile[] -} - -interface GitHubArtifact { - id: number - name: string - size_in_bytes: number - url: string - archive_download_url: string - expires_at: string -} - -interface GitHub { - /** - * Gets connection information for octokit - */ - info(): Promise - - /** - * Gets the details of a GitHub workflow - * @param workflowId - */ - workflow(workflowId: number | string): Promise - - /** - * Lists workflows in a GitHub repository - */ - listWorkflows(options?: GitHubPaginationOptions): Promise - - /** - * Lists workflow runs for a given workflow - * @param workflowId - * @param options - */ - listWorkflowRuns( - workflow_id: string | number, - options?: { - branch?: string - event?: string - status?: GitHubWorkflowRunStatus - } & GitHubPaginationOptions - ): Promise - - /** - * Gets the details of a GitHub Action workflow run - * @param runId - */ - workflowRun(runId: number | string): Promise - - /** - * List artifacts for a given workflow run - * @param runId - */ - listWorkflowRunArtifacts( - runId: number | string, - options?: GitHubPaginationOptions - ): Promise - - /** - * Gets the details of a GitHub Action workflow run artifact - * @param artifactId - */ - artifact(artifactId: number | string): Promise - - /** - * Downloads and unzips archive files from a GitHub Action Artifact - * @param artifactId - */ - downloadArtifactFiles(artifactId: number | string): Promise - - /** - * Downloads a GitHub Action workflow run log - * @param runId - */ - listWorkflowJobs( - runId: number, - options?: GitHubPaginationOptions - ): Promise - - /** - * Downloads a GitHub Action workflow run log - * @param jobId - */ - downloadWorkflowJobLog( - jobId: number, - options?: { llmify?: boolean } - ): Promise - - /** - * Diffs two GitHub Action workflow job logs - */ - diffWorkflowJobLogs(job_id: number, other_job_id: number): Promise - - /** - * Lists issues for a given repository - * @param options - */ - listIssues( - options?: { - state?: "open" | "closed" | "all" - labels?: string - sort?: "created" | "updated" | "comments" - direction?: "asc" | "desc" - creator?: string - assignee?: string - since?: string - mentioned?: string - } & GitHubPaginationOptions - ): Promise - - /** - * Lists gists for a given user - */ - listGists(): Promise - - /** - * Gets the files of a gist - * @param gist_id - */ - getGist(gist_id: string): Promise - - /** - * Gets the details of a GitHub issue - * @param issueNumber issue number (not the issue id!). If undefined, reads value from GITHUB_ISSUE environment variable. - */ - getIssue(issueNumber?: number | string): Promise - - /** - * Create a GitHub issue comment - * @param issueNumber issue number (not the issue id!). If undefined, reads value from GITHUB_ISSUE environment variable. - * @param body the body of the comment as Github Flavored markdown - */ - createIssueComment( - issueNumber: number | string, - body: string - ): Promise - - /** - * Lists comments for a given issue - * @param issue_number - * @param options - */ - listIssueComments( - issue_number: number | string, - options?: GitHubPaginationOptions - ): Promise - - /** - * Updates a comment on a GitHub issue - * @param comment_id - * @param body the updated comment body - */ - updateIssueComment( - comment_id: number | string, - body: string - ): Promise - - /** - * Lists pull requests for a given repository - * @param options - */ - listPullRequests( - options?: { - state?: "open" | "closed" | "all" - sort?: "created" | "updated" | "popularity" | "long-running" - direction?: "asc" | "desc" - } & GitHubPaginationOptions - ): Promise - - /** - * Gets the details of a GitHub pull request - * @param pull_number pull request number. Default resolves the pull request for the current branch. - */ - getPullRequest(pull_number?: number | string): Promise - - /** - * Lists comments for a given pull request - * @param pull_number - * @param options - */ - listPullRequestReviewComments( - pull_number: number, - options?: GitHubPaginationOptions - ): Promise - - /** - * Gets the content of a file from a GitHub repository - * @param filepath - * @param options - */ - getFile( - filepath: string, - /** - * commit sha, branch name or tag name - */ - ref: string - ): Promise - - /** - * Searches code in a GitHub repository - */ - searchCode( - query: string, - options?: GitHubPaginationOptions - ): Promise - - /** - * Lists branches in a GitHub repository - */ - listBranches(options?: GitHubPaginationOptions): Promise - - /** - * Lists tags in a GitHub repository - */ - listRepositoryLanguages(): Promise> - - /** - * List latest releases in a GitHub repository - * @param options - */ - listReleases(options?: GitHubPaginationOptions): Promise - - /** - * Lists tags in a GitHub repository - */ - getRepositoryContent( - path?: string, - options?: { - ref?: string - glob?: string - downloadContent?: boolean - maxDownloadSize?: number - type?: GitHubFile["type"] - } - ): Promise - - /** - * Uploads a file to an orphaned branch in the repository and returns the raw url - * Uploads a single copy of the file using hash as the name. - * @param file file or data to upload - * @param options - */ - uploadAsset( - file: BufferLike, - options?: { - branchName?: string - } - ): Promise - - /** - * Gets the underlying Octokit client - */ - api(): Promise - - /** - * Opens a client to a different repository - * @param owner - * @param repo - */ - client(owner: string, repo: string): GitHub -} - -interface MD { - /** - * Parses front matter from markdown - * @param text - */ - frontmatter( - text: string | WorkspaceFile, - format?: "yaml" | "json" | "toml" | "text" - ): any - - /** - * Removes the front matter from the markdown text - */ - content(text: string | WorkspaceFile): string - - /** - * Merges frontmatter with the existing text - * @param text - * @param frontmatter - * @param format - */ - updateFrontmatter( - text: string, - frontmatter: any, - format?: "yaml" | "json" - ): string - - /** - * Attempts to chunk markdown in text section in a way that does not splitting the heading structure. - * @param text - * @param options - */ - chunk( - text: string | WorkspaceFile, - options?: { maxTokens?: number; model?: string; pageSeparator?: string } - ): Promise - - /** - * Pretty prints object to markdown - * @param value - */ - stringify( - value: any, - options?: { - quoteValues?: boolean - headings?: number - headingLevel?: number - } - ): string -} - -interface JSONL { - /** - * Parses a JSONL string to an array of objects - * @param text - */ - parse(text: string | WorkspaceFile): any[] - /** - * Converts objects to JSONL format - * @param objs - */ - stringify(objs: any[]): string -} - -interface INI { - /** - * Parses a .ini file - * @param text - */ - parse(text: string | WorkspaceFile): any - - /** - * Converts an object to.ini string - * @param value - */ - stringify(value: any): string -} - -interface JSON5 { - /** - * Parses a JSON/YAML/XML string to an object - * @param text - */ - parse(text: string | WorkspaceFile): any - - /** - * Renders an object to a JSON5-LLM friendly string - * @param value - */ - stringify(value: any): string -} - -interface CSVStringifyOptions { - delimiter?: string - header?: boolean -} - -/** - * Interface representing CSV operations. - */ -interface CSV { - /** - * Parses a CSV string to an array of objects. - * - * @param text - The CSV string to parse. - * @param options - Optional settings for parsing. - * @param options.delimiter - The delimiter used in the CSV string. Defaults to ','. - * @param options.headers - An array of headers to use. If not provided, headers will be inferred from the first row. - * @returns An array of objects representing the parsed CSV data. - */ - parse(text: string | WorkspaceFile, options?: CSVParseOptions): object[] - - /** - * Converts an array of objects to a CSV string. - * - * @param csv - The array of objects to convert. - * @param options - Optional settings for stringifying. - * @param options.headers - An array of headers to use. If not provided, headers will be inferred from the object keys. - * @returns A CSV string representing the data. - */ - stringify(csv: object[], options?: CSVStringifyOptions): string - - /** - * Converts an array of objects that represents a data table to a markdown table. - * - * @param csv - The array of objects to convert. - * @param options - Optional settings for markdown conversion. - * @param options.headers - An array of headers to use. If not provided, headers will be inferred from the object keys. - * @returns A markdown string representing the data table. - */ - markdownify(csv: object[], options?: { headers?: string[] }): string - - /** - * Splits the original array into chunks of the specified size. - * @param csv - * @param rows - */ - chunk( - csv: object[], - size: number - ): { chunkStartIndex: number; rows: object[] }[] -} - -/** - * Provide service for responsible. - */ -interface ContentSafety { - /** - * Service identifier - */ - id: string - - /** - * Scans text for the risk of a User input attack on a Large Language Model. - * If not supported, the method is not defined. - */ - detectPromptInjection?( - content: Awaitable< - ElementOrArray | ElementOrArray - > - ): Promise<{ attackDetected: boolean; filename?: string; chunk?: string }> - /** - * Analyzes text for harmful content. - * If not supported, the method is not defined. - * @param content - */ - detectHarmfulContent?( - content: Awaitable< - ElementOrArray | ElementOrArray - > - ): Promise<{ - harmfulContentDetected: boolean - filename?: string - chunk?: string - }> -} - -interface HighlightOptions { - maxLength?: number -} - -interface WorkspaceFileIndex { - /** - * Gets the index name - */ - name: string - /** - * Uploads or merges files into the index - */ - insertOrUpdate: (file: ElementOrArray) => Promise - /** - * Searches the index - */ - search: ( - query: string, - options?: { topK?: number; minScore?: number } - ) => Promise -} - -interface VectorIndexOptions extends EmbeddingsModelOptions { - /** - * Type of database implementation. - * - `local` uses a local database using embeddingsModel - * - `azure_ai_search` uses Azure AI Search - */ - type?: "local" | "azure_ai_search" - version?: number - deleteIfExists?: boolean - chunkSize?: number - chunkOverlap?: number - - /** - * Embeddings vector size - */ - vectorSize?: number - /** - * Override default embeddings cache name - */ - cacheName?: string - /** - * Cache salt to invalidate cache entries - */ - cacheSalt?: string -} - -interface VectorSearchOptions extends VectorIndexOptions { - /** - * Maximum number of embeddings to use - */ - topK?: number - /** - * Minimum similarity score - */ - minScore?: number - /** - * Index to use - */ - indexName?: string -} - -interface FuzzSearchOptions { - /** - * Controls whether to perform prefix search. It can be a simple boolean, or a - * function. - * - * If a boolean is passed, prefix search is performed if true. - * - * If a function is passed, it is called upon search with a search term, the - * positional index of that search term in the tokenized search query, and the - * tokenized search query. - */ - prefix?: boolean - /** - * Controls whether to perform fuzzy search. It can be a simple boolean, or a - * number, or a function. - * - * If a boolean is given, fuzzy search with a default fuzziness parameter is - * performed if true. - * - * If a number higher or equal to 1 is given, fuzzy search is performed, with - * a maximum edit distance (Levenshtein) equal to the number. - * - * If a number between 0 and 1 is given, fuzzy search is performed within a - * maximum edit distance corresponding to that fraction of the term length, - * approximated to the nearest integer. For example, 0.2 would mean an edit - * distance of 20% of the term length, so 1 character in a 5-characters term. - * The calculated fuzziness value is limited by the `maxFuzzy` option, to - * prevent slowdown for very long queries. - */ - fuzzy?: boolean | number - /** - * Controls the maximum fuzziness when using a fractional fuzzy value. This is - * set to 6 by default. Very high edit distances usually don't produce - * meaningful results, but can excessively impact search performance. - */ - maxFuzzy?: number - /** - * Maximum number of results to return - */ - topK?: number - /** - * Minimum score - */ - minScore?: number -} - -interface Retrieval { - /** - * Executers a web search with Tavily or Bing Search. - * @param query - */ - webSearch( - query: string, - options?: { - count?: number - provider?: "tavily" | "bing" - /** - * Return undefined when no web search providers are present - */ - ignoreMissingProvider?: boolean - } - ): Promise - - /** - * Search using similarity distance on embeddings - */ - vectorSearch( - query: string, - files: (string | WorkspaceFile) | (string | WorkspaceFile)[], - options?: VectorSearchOptions - ): Promise - - /** - * Loads or creates a file index using a vector index - * @param options - */ - index(id: string, options?: VectorIndexOptions): Promise - - /** - * Performs a fuzzy search over the files - * @param query keywords to search - * @param files list of files - * @param options fuzzing configuration - */ - fuzzSearch( - query: string, - files: WorkspaceFile | WorkspaceFile[], - options?: FuzzSearchOptions - ): Promise -} - -interface ArrayFilter { - /** - * Selects the first N elements from the data - */ - sliceHead?: number - /** - * Selects the last N elements from the data - */ - sliceTail?: number - /** - * Selects the a random sample of N items in the collection. - */ - sliceSample?: number -} - -interface DataFilter extends ArrayFilter { - /** - * The keys to select from the object. - * If a key is prefixed with -, it will be removed from the object. - */ - headers?: ElementOrArray - /** - * Removes items with duplicate values for the specified keys. - */ - distinct?: ElementOrArray - /** - * Sorts the data by the specified key(s) - */ - sort?: ElementOrArray -} - -interface DefDataOptions - extends Omit, - FenceFormatOptions, - DataFilter, - ContentSafetyOptions { - /** - * Output format in the prompt. Defaults to Markdown table rendering. - */ - format?: "json" | "yaml" | "csv" - - /** - * GROQ query to filter the data - * @see https://groq.dev/ - */ - query?: string -} - -interface DefSchemaOptions { - /** - * Output format in the prompt. - */ - format?: "typescript" | "json" | "yaml" -} - -type ChatFunctionArgs = { context: ToolCallContext } & Record -type ChatFunctionHandler = (args: ChatFunctionArgs) => Awaitable -type ChatMessageRole = "user" | "assistant" | "system" - -interface HistoryMessageUser { - role: "user" - content: string -} - -interface HistoryMessageAssistant { - role: "assistant" - name?: string - content: string -} - -interface WriteTextOptions extends ContextExpansionOptions { - /** - * Append text to the assistant response. This feature is not supported by all models. - * @deprecated - */ - assistant?: boolean - /** - * Specifies the message role. Default is user - */ - role?: ChatMessageRole -} - -type PromptGenerator = (ctx: ChatGenerationContext) => Awaitable - -interface PromptGeneratorOptions - extends ModelOptions, - PromptSystemOptions, - ContentSafetyOptions, - SecretDetectionOptions, - MetadataOptions { - /** - * Label for trace - */ - label?: string - - /** - * Write file edits to the file system - */ - applyEdits?: boolean - - /** - * Throws if the generation is not successful - */ - throwOnError?: boolean -} - -interface FileOutputOptions { - /** - * Schema identifier to validate the generated file - */ - schema?: string -} - -interface FileOutput { - pattern: string[] - description?: string - options?: FileOutputOptions -} - -interface ImportTemplateOptions { - /** - * Ignore unknown arguments - */ - allowExtraArguments?: boolean - - /** - * Template engine syntax - */ - format?: "mustache" | "jinja" -} - -interface PromptTemplateString { - /** - * Set a priority similar to CSS z-index - * to control the trimming of the prompt when the context is full - * @param priority - */ - priority(value: number): PromptTemplateString - /** - * Sets the context layout flex weight - */ - flex(value: number): PromptTemplateString - /** - * Applies jinja template to the string lazily - * @param data jinja data - */ - jinja(data: Record): PromptTemplateString - /** - * Applies mustache template to the string lazily - * @param data mustache data - */ - mustache(data: Record): PromptTemplateString - /** - * Sets the max tokens for this string - * @param tokens - */ - maxTokens(tokens: number): PromptTemplateString - - /** - * Updates the role of the message - */ - role(role: ChatMessageRole): PromptTemplateString - - /** - * Configure the cacheability of the prompt. - * @param value cache control type - */ - cacheControl(value: PromptCacheControlType): PromptTemplateString -} - -type ImportTemplateArgumentType = - | Awaitable - | (() => Awaitable) - -/** - * Represents the context for generating a chat turn in a prompt template. - * Provides methods for importing templates, writing text, adding assistant responses, - * creating template strings, fencing code blocks, defining variables, and logging. - */ -interface ChatTurnGenerationContext { - importTemplate( - files: ElementOrArray, - arguments?: Record, - options?: ImportTemplateOptions - ): void - writeText(body: Awaitable, options?: WriteTextOptions): void - assistant( - text: Awaitable, - options?: Omit - ): void - $(strings: TemplateStringsArray, ...args: any[]): PromptTemplateString - fence(body: StringLike, options?: FenceOptions): void - def( - name: string, - body: - | string - | WorkspaceFile - | WorkspaceFile[] - | ShellOutput - | Fenced - | RunPromptResult, - options?: DefOptions - ): string - defImages( - files: ElementOrArray, - options?: DefImagesOptions - ): void - defData( - name: string, - data: Awaitable, - options?: DefDataOptions - ): string - defDiff( - name: string, - left: T, - right: T, - options?: DefDiffOptions - ): string - console: PromptGenerationConsole -} - -interface FileUpdate { - before: string - after: string - validation?: FileEditValidation -} - -interface RunPromptResultPromiseWithOptions extends Promise { - options(values?: PromptGeneratorOptions): RunPromptResultPromiseWithOptions -} - -interface DefToolOptions extends ContentSafetyOptions { - /** - * Maximum number of tokens per tool content response - */ - maxTokens?: number - - /** - * Suffix to identify the variant instantiation of the tool - */ - variant?: string - - /** - * Updated description for the variant - */ - variantDescription?: string - - /** - * Intent of the tool that will be used for LLM judge validation of the output. - * `description` uses the tool description as the intent. - * If the intent is a function, it must build a LLM-as-Judge prompt that emits OK/ERR categories. - */ - intent?: - | OptionsOrString<"description"> - | ((options: { - tool: ToolDefinition - args: any - result: string - generator: ChatGenerationContext - }) => Awaitable) -} - -interface DefAgentOptions - extends Omit, - DefToolOptions { - /** - * Excludes agent conversation from agent memory - */ - disableMemory?: boolean - - /** - * Disable memory query on each query (let the agent call the tool) - */ - disableMemoryQuery?: boolean -} - -type ChatAgentHandler = ( - ctx: ChatGenerationContext, - args: ChatFunctionArgs -) => Awaitable - -interface McpToolSpecification { - /** - * Tool identifier - */ - id: string - /** - * The high level intent of the tool, which can be used for LLM judge validation. - * `description` uses the tool description as the intent. - */ - intent?: DefToolOptions["intent"] -} - -interface McpServerConfig extends ContentSafetyOptions { - /** - * The executable to run to start the server. - */ - command: OptionsOrString<"npx" | "uv" | "dotnet" | "docker" | "cargo"> - /** - * Command line arguments to pass to the executable. - */ - args: string[] - /** - * The server version - */ - version?: string - /** - * The environment to use when spawning the process. - * - * If not specified, the result of getDefaultEnvironment() will be used. - */ - env?: Record - /** - * The working directory to use when spawning the process. - * - * If not specified, the current working directory will be inherited. - */ - cwd?: string - - id: string - options?: DefToolOptions - - /** - * A list of allowed tools and their specifications. This filtering is applied - * before computing the sha signature. - */ - tools?: ElementOrArray - - /** - * The sha signature of the tools returned by the server. - * If set, the tools will be validated against this sha. - * This is used to ensure that the tools are not modified by the server. - */ - toolsSha?: string - - /** - * Validates that each tool has responses related to their description. - */ - intent?: DefToolOptions["intent"] - - generator?: ChatGenerationContext -} - -type McpServersConfig = Record> - -interface McpAgentServerConfig extends McpServerConfig { - description: string - instructions?: string - /** - * Maximum number of tokens per tool content response - */ - maxTokens?: number -} - -type McpAgentServersConfig = Record< - string, - Omit -> - -type ZodTypeLike = { _def: any; safeParse: any; refine: any } - -type BufferLike = - | string - | WorkspaceFile - | Buffer - | Blob - | ArrayBuffer - | Uint8Array - | ReadableStream - | SharedArrayBuffer - -type TranscriptionModelType = OptionsOrString< - "openai:whisper-1" | "openai:gpt-4o-transcribe" | "whisperasr:default" -> - -interface ImageGenerationOptions extends ImageTransformOptions, RetryOptions { - model?: OptionsOrString - /** - * The quality of the image that will be generated. - * auto (default value) will automatically select the best quality for the given model. - * high, medium and low are supported for gpt-image-1. - * high is supported for dall-e-3. - * dall-e-2 ignores this flag - */ - quality?: "auto" | "low" | "medium" | "high" - /** - * Image size. - * For gpt-image-1: 1024x1024, 1536x1024 (landscape), 1024x1536 (portrait), or auto (default value) - * For dall-e: 256x256, 512x512, or 1024x1024 for dall-e-2, and one of 1024x1024, 1792x1024. - */ - size?: OptionsOrString< - | "auto" - | "landscape" - | "portrait" - | "square" - | "1536x1024" - | "1024x1536" - | "256x256" - | "512x512" - | "1024x1024" - | "1024x1792" - | "1792x1024" - > - /** - * Only used for DALL-E 3 - */ - style?: OptionsOrString<"vivid" | "natural"> - - /** - * For gpt-image-1 only, the type of image format to generate. - */ - outputFormat?: "png" | "jpeg" | "webp" -} - -interface TranscriptionOptions extends CacheOptions, RetryOptions { - /** - * Model to use for transcription. By default uses the `transcribe` alias. - */ - model?: TranscriptionModelType - - /** - * Translate to English. - */ - translate?: boolean - - /** - * Input language in iso-639-1 format. - * @see https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes - */ - language?: string - - /** - * The sampling temperature, between 0 and 1. - * Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - */ - temperature?: number -} - -interface TranscriptionResult { - /** - * Complete transcription text - */ - text: string - /** - * Error if any - */ - error?: SerializedError - - /** - * SubRip subtitle string from segments - */ - srt?: string - - /** - * WebVTT subtitle string from segments - */ - vtt?: string - - /** - * Individual segments - */ - segments?: (TranscriptionSegment & { - /** - * Seek offset of the segment - */ - seek?: number - /** - * Temperature used for the generation of the segment - */ - temperature?: number - })[] -} - -type SpeechModelType = OptionsOrString< - "openai:tts-1-hd" | "openai:tts-1" | "openai:gpt-4o-mini-tts" -> - -type SpeechVoiceType = OptionsOrString< - | "alloy" - | "ash" - | "coral" - | "echo" - | "fable" - | "onyx" - | "nova" - | "sage" - | "shimmer" - | "verse" - | "ballad" -> - -interface SpeechOptions extends CacheOptions, RetryOptions { - /** - * Speech to text model - */ - model?: SpeechModelType - - /** - * Voice to use (model-specific) - */ - voice?: SpeechVoiceType - - /** - * Control the voice of your generated audio with additional instructions. Does not work with tts-1 or tts-1-hd. - */ - instructions?: string -} - -interface SpeechResult { - /** - * Generate audio-buffer file - */ - filename?: string - /** - * Error if any - */ - error?: SerializedError -} - -interface ChatGenerationContext extends ChatTurnGenerationContext { - env: ExpansionVariables - defSchema( - name: string, - schema: JSONSchema | ZodTypeLike, - options?: DefSchemaOptions - ): string - defTool( - tool: Omit | McpServersConfig, - options?: DefToolOptions - ): void - defTool( - name: string, - description: string, - parameters: PromptParametersSchema | JSONSchema, - fn: ChatFunctionHandler, - options?: DefToolOptions - ): void - defAgent( - name: string, - description: string, - fn: string | ChatAgentHandler, - options?: DefAgentOptions - ): void - defChatParticipant( - participant: ChatParticipantHandler, - options?: ChatParticipantOptions - ): void - defFileOutput( - pattern: ElementOrArray, - description: string, - options?: FileOutputOptions - ): void - runPrompt( - generator: string | PromptGenerator, - options?: PromptGeneratorOptions - ): Promise - prompt( - strings: TemplateStringsArray, - ...args: any[] - ): RunPromptResultPromiseWithOptions - defFileMerge(fn: FileMergeHandler): void - defOutputProcessor(fn: PromptOutputProcessorHandler): void - transcribe( - audio: string | WorkspaceFile, - options?: TranscriptionOptions - ): Promise - speak(text: string, options?: SpeechOptions): Promise - generateImage( - prompt: string, - options?: ImageGenerationOptions - ): Promise<{ image: WorkspaceFile; revisedPrompt?: string }> -} - -interface GenerationOutput { - /** - * full chat history - */ - messages: ChatMessage[] - - /** - * LLM output. - */ - text: string - - /** - * Reasoning produced by model - */ - reasoning?: string - - /** - * Parsed fence sections - */ - fences: Fenced[] - - /** - * Parsed data sections - */ - frames: DataFrame[] - - /** - * A map of file updates - */ - fileEdits: Record - - /** - * Generated annotations - */ - annotations: Diagnostic[] - - /** - * Schema definition used in the generation - */ - schemas: Record - - /** - * Output as JSON if parsable - */ - json?: any - - /** - * Usage stats - */ - usage?: RunPromptUsage -} - -type Point = { - row: number - column: number -} - -interface SyntaxNode { - id: number - typeId: number - grammarId: number - type: string - grammarType: string - isNamed: boolean - isMissing: boolean - isExtra: boolean - hasChanges: boolean - hasError: boolean - isError: boolean - text: string - parseState: number - nextParseState: number - startPosition: Point - endPosition: Point - startIndex: number - endIndex: number - parent: SyntaxNode | null - children: Array - namedChildren: Array - childCount: number - namedChildCount: number - firstChild: SyntaxNode | null - firstNamedChild: SyntaxNode | null - lastChild: SyntaxNode | null - lastNamedChild: SyntaxNode | null - nextSibling: SyntaxNode | null - nextNamedSibling: SyntaxNode | null - previousSibling: SyntaxNode | null - previousNamedSibling: SyntaxNode | null - descendantCount: number - - equals(other: SyntaxNode): boolean - toString(): string - child(index: number): SyntaxNode | null - namedChild(index: number): SyntaxNode | null - childForFieldName(fieldName: string): SyntaxNode | null - childForFieldId(fieldId: number): SyntaxNode | null - fieldNameForChild(childIndex: number): string | null - childrenForFieldName( - fieldName: string, - cursor: TreeCursor - ): Array - childrenForFieldId(fieldId: number, cursor: TreeCursor): Array - firstChildForIndex(index: number): SyntaxNode | null - firstNamedChildForIndex(index: number): SyntaxNode | null - - descendantForIndex(index: number): SyntaxNode - descendantForIndex(startIndex: number, endIndex: number): SyntaxNode - namedDescendantForIndex(index: number): SyntaxNode - namedDescendantForIndex(startIndex: number, endIndex: number): SyntaxNode - descendantForPosition(position: Point): SyntaxNode - descendantForPosition(startPosition: Point, endPosition: Point): SyntaxNode - namedDescendantForPosition(position: Point): SyntaxNode - namedDescendantForPosition( - startPosition: Point, - endPosition: Point - ): SyntaxNode - descendantsOfType( - types: String | Array, - startPosition?: Point, - endPosition?: Point - ): Array - - walk(): TreeCursor -} - -interface TreeCursor { - nodeType: string - nodeTypeId: number - nodeStateId: number - nodeText: string - nodeId: number - nodeIsNamed: boolean - nodeIsMissing: boolean - startPosition: Point - endPosition: Point - startIndex: number - endIndex: number - readonly currentNode: SyntaxNode - readonly currentFieldName: string - readonly currentFieldId: number - readonly currentDepth: number - readonly currentDescendantIndex: number - - reset(node: SyntaxNode): void - resetTo(cursor: TreeCursor): void - gotoParent(): boolean - gotoFirstChild(): boolean - gotoLastChild(): boolean - gotoFirstChildForIndex(goalIndex: number): boolean - gotoFirstChildForPosition(goalPosition: Point): boolean - gotoNextSibling(): boolean - gotoPreviousSibling(): boolean - gotoDescendant(goalDescendantIndex: number): void -} - -interface QueryCapture { - name: string - node: SyntaxNode -} - -interface SgEdit { - /** The start position of the edit */ - startPos: number - /** The end position of the edit */ - endPos: number - /** The text to be inserted */ - insertedText: string -} -interface SgPos { - /** line number starting from 0 */ - line: number - /** column number starting from 0 */ - column: number - /** byte offset of the position */ - index?: number -} -interface SgRange { - /** starting position of the range */ - start: SgPos - /** ending position of the range */ - end: SgPos -} -interface SgMatcher { - /** The rule object, see https://ast-grep.github.io/reference/rule.html */ - rule: SgRule - /** See https://ast-grep.github.io/guide/rule-config.html#constraints */ - constraints?: Record -} -type SgStrictness = "cst" | "smart" | "ast" | "relaxed" | "signature" -interface SgPatternObject { - context: string - selector?: string //NamedKinds // only named node types - strictness?: SgStrictness -} -type SgPatternStyle = string | SgPatternObject -interface SgRule { - /** A pattern string or a pattern object. */ - pattern?: SgPatternStyle - /** The kind name of the node to match. You can look up code's kind names in playground. */ - kind?: string - /** The exact range of the node in the source code. */ - range?: SgRange - /** A Rust regular expression to match the node's text. https://docs.rs/regex/latest/regex/#syntax */ - regex?: string - /** - * `nthChild` accepts number, string or object. - * It specifies the position in nodes' sibling list. */ - nthChild?: string | number - - // relational - /** - * `inside` accepts a relational rule object. - * the target node must appear inside of another node matching the `inside` sub-rule. */ - inside?: SgRelation - /** - * `has` accepts a relational rule object. - * the target node must has a descendant node matching the `has` sub-rule. */ - has?: SgRelation - /** - * `precedes` accepts a relational rule object. - * the target node must appear before another node matching the `precedes` sub-rule. */ - precedes?: SgRelation - /** - * `follows` accepts a relational rule object. - * the target node must appear after another node matching the `follows` sub-rule. */ - follows?: SgRelation - // composite - /** - * A list of sub rules and matches a node if all of sub rules match. - * The meta variables of the matched node contain all variables from the sub-rules. */ - all?: Array - /** - * A list of sub rules and matches a node if any of sub rules match. - * The meta variables of the matched node only contain those of the matched sub-rule. */ - any?: Array - /** A single sub-rule and matches a node if the sub rule does not match. */ - not?: SgRule - /** A utility rule id and matches a node if the utility rule matches. */ - matches?: string -} -interface SgRelation extends SgRule { - /** - * Specify how relational rule will stop relative to the target node. - */ - stopBy?: "neighbor" | "end" | SgRule - /** Specify the tree-sitter field in parent node. Only available in has/inside rule. */ - field?: string -} - -/** - * A asp-grep node, SgNode, is an immutable node in the abstract syntax tree. - */ -interface SgNode { - id(): number - range(): SgRange - isLeaf(): boolean - isNamed(): boolean - isNamedLeaf(): boolean - text(): string - matches(m: string | number): boolean - inside(m: string | number): boolean - has(m: string | number): boolean - precedes(m: string | number): boolean - follows(m: string | number): boolean - kind(): any - is(kind: string): boolean - getMatch(mv: string): SgNode | null - getMultipleMatches(m: string): Array - getTransformed(m: string): string | null - getRoot(): SgRoot - children(): Array - find(matcher: string | number | SgMatcher): SgNode | null - findAll(matcher: string | number | SgMatcher): Array - field(name: string): SgNode | null - fieldChildren(name: string): SgNode[] - parent(): SgNode | null - child(nth: number): SgNode | null - child(nth: number): SgNode | null - ancestors(): Array - next(): SgNode | null - nextAll(): Array - prev(): SgNode | null - prevAll(): Array - replace(text: string): SgEdit - commitEdits(edits: Array): string -} - -interface SgRoot { - /** Returns the root SgNode of the ast-grep instance. */ - root(): SgNode - /** - * Returns the path of the file if it is discovered by ast-grep's `findInFiles`. - * Returns `"anonymous"` if the instance is created by `lang.parse(source)`. - */ - filename(): string -} - -type SgLang = OptionsOrString< - | "html" - | "js" - | "javascript" - | "ts" - | "typescript" - | "tsx" - | "css" - | "c" - | "sql" - | "angular" - | "csharp" - | "python" - | "rust" - | "elixir" - | "haskell" - | "go" - | "dart" - | "swift" - | "scala" -> - -interface SgChangeSet { - count: number - replace(node: SgNode, text: string): SgEdit - commit(): WorkspaceFile[] -} - -interface SgSearchOptions extends Omit { - /** - * Restrict matches that are part of the diff. - */ - diff?: string | ElementOrArray -} - -interface Sg { - /** - * Create a change set - */ - changeset(): SgChangeSet - parse(file: WorkspaceFile, options: { lang?: SgLang }): Promise - search( - lang: SgLang, - glob: ElementOrArray, - matcher: string | SgMatcher, - options?: SgSearchOptions - ): Promise<{ - /** - * Number of files found - */ - files: number - /** - * Each individual file matches as a node - */ - matches: SgNode[] - }> -} - -interface DebugLogger { - /** - * Creates a debug logging function. Debug uses printf-style formatting. Below are the officially supported formatters: - * - `%O` Pretty-print an Object on multiple lines. - * - `%o` Pretty-print an Object all on a single line. - * - `%s` String. - * - `%d` Number (both integer and float). - * - `%j` JSON. Replaced with the string '[Circular]' if the argument contains circular references. - * - `%%` Single percent sign ('%'). This does not consume an argument. - * @param category - * @see https://www.npmjs.com/package/debug - */ - (formatter: any, ...args: any[]): void - /** - * Indicates if this logger is enabled - */ - enabled: boolean - /** - * The namespace of the logger provided when calling 'host.logger' - */ - namespace: string -} - -interface LoggerHost { - /** - * Creates a debug logging function. Debug uses printf-style formatting. Below are the officially supported formatters: - * - `%O` Pretty-print an Object on multiple lines. - * - `%o` Pretty-print an Object all on a single line. - * - `%s` String. - * - `%d` Number (both integer and float). - * - `%j` JSON. Replaced with the string '[Circular]' if the argument contains circular references. - * - `%%` Single percent sign ('%'). This does not consume an argument. - * @param category - * @see https://www.npmjs.com/package/debug - */ - logger(category: string): DebugLogger -} - -interface SgHost { - /** - * Gets an ast-grep instance - */ - astGrep(): Promise -} - -interface ShellOptions { - cwd?: string - - stdin?: string - - /** - * Process timeout in milliseconds, default is 60s - */ - timeout?: number - /** - * trace label - */ - label?: string - - /** - * Ignore exit code errors - */ - ignoreError?: boolean - - /** - * Additional environment variables to set for the process. - */ - env?: Record - - /** - * Inject the content of 'env' exclusively - */ - isolateEnv?: boolean -} - -interface ShellOutput { - stdout?: string - stderr?: string - exitCode: number - failed?: boolean -} - -interface BrowserOptions { - /** - * Browser engine for this page. Defaults to chromium - * - */ - browser?: "chromium" | "firefox" | "webkit" - - /** - * If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is deleted when browser is closed. In either case, the downloads are deleted when the browser context they were created in is closed. - */ - downloadsPath?: string - - /** - * Whether to run browser in headless mode. More details for Chromium and Firefox. Defaults to true unless the devtools option is true. - */ - headless?: boolean - - /** - * Specify environment variables that will be visible to the browser. Defaults to process.env. - */ - env?: Record -} - -interface BrowseGotoOptions extends TimeoutOptions { - /** - * Referer header value. If provided it will take preference over the referer header value set by - * [page.setExtraHTTPHeaders(headers)](https://playwright.dev/docs/api/class-page#page-set-extra-http-headers). - */ - referer?: string - - /** - * When to consider operation succeeded, defaults to `load`. Events can be either: - * - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. - * - `'load'` - consider operation to be finished when the `load` event is fired. - * - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for - * at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead. - * - `'commit'` - consider operation to be finished when network response is received and the document started - * loading. - */ - waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit" -} - -interface BrowseSessionOptions - extends BrowserOptions, - BrowseGotoOptions, - TimeoutOptions { - /** - * Creates a new context for the browser session - */ - incognito?: boolean - - /** - * Base url to use for relative urls - * @link https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url - */ - baseUrl?: string - - /** - * Toggles bypassing page's Content-Security-Policy. Defaults to false. - * @link https://playwright.dev/docs/api/class-browser#browser-new-context-option-bypass-csp - */ - bypassCSP?: boolean - - /** - * Whether to ignore HTTPS errors when sending network requests. Defaults to false. - * @link https://playwright.dev/docs/api/class-browser#browser-new-context-option-ignore-https-errors - */ - ignoreHTTPSErrors?: boolean - - /** - * Whether or not to enable JavaScript in the context. Defaults to true. - * @link https://playwright.dev/docs/api/class-browser#browser-new-context-option-java-script-enabled - */ - javaScriptEnabled?: boolean - - /** - * Enable recording video for all pages. Implies incognito mode. - */ - recordVideo?: - | boolean - | { - width: number - height: number - } - - /** - * CDP connection string - */ - connectOverCDP?: string -} - -interface TimeoutOptions { - /** - * Maximum time in milliseconds. Default to no timeout - */ - timeout?: number -} - -interface ScreenshotOptions extends TimeoutOptions { - quality?: number - scale?: "css" | "device" - type?: "png" | "jpeg" - style?: string -} - -interface PageScreenshotOptions extends ScreenshotOptions { - fullPage?: boolean - omitBackground?: boolean - clip?: { - x: number - y: number - width: number - height: number - } -} - -interface BrowserLocatorSelector { - /** - * Allows locating elements by their ARIA role, ARIA attributes and accessible name. - * @param role - * @param options - */ - getByRole( - role: - | "alert" - | "alertdialog" - | "application" - | "article" - | "banner" - | "blockquote" - | "button" - | "caption" - | "cell" - | "checkbox" - | "code" - | "columnheader" - | "combobox" - | "complementary" - | "contentinfo" - | "definition" - | "deletion" - | "dialog" - | "directory" - | "document" - | "emphasis" - | "feed" - | "figure" - | "form" - | "generic" - | "grid" - | "gridcell" - | "group" - | "heading" - | "img" - | "insertion" - | "link" - | "list" - | "listbox" - | "listitem" - | "log" - | "main" - | "marquee" - | "math" - | "meter" - | "menu" - | "menubar" - | "menuitem" - | "menuitemcheckbox" - | "menuitemradio" - | "navigation" - | "none" - | "note" - | "option" - | "paragraph" - | "presentation" - | "progressbar" - | "radio" - | "radiogroup" - | "region" - | "row" - | "rowgroup" - | "rowheader" - | "scrollbar" - | "search" - | "searchbox" - | "separator" - | "slider" - | "spinbutton" - | "status" - | "strong" - | "subscript" - | "superscript" - | "switch" - | "tab" - | "table" - | "tablist" - | "tabpanel" - | "term" - | "textbox" - | "time" - | "timer" - | "toolbar" - | "tooltip" - | "tree" - | "treegrid" - | "treeitem", - options?: { - checked?: boolean - disabled?: boolean - exact?: boolean - expanded?: boolean - name?: string - selected?: boolean - } & TimeoutOptions - ): BrowserLocator - - /** - * Allows locating input elements by the text of the associated