diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000..301e22e599 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "githubPullRequests.pullRequestDescription": "branchName" +} \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 24a8fcd9f8..d97e15376c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5402,14 +5402,14 @@ } }, "node_modules/google-auth-library": { - "version": "11.1.0", - "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-11.1.0.tgz", - "integrity": "sha512-YIBq5KNoHQrZ9PM4PeodDBqqBGlSTIxh1zibN8u3zNIO9UJg8gvKuCpdKV7fWXhsZ2zRkU6FhGrgKNgLJ2IRgw==", + "version": "11.3.1", + "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-11.3.1.tgz", + "integrity": "sha512-mQS0R2Ev/DKkzuWSYtDeq15uhDeaWuT2qzLYqJ41LmooxVKHmn5ut3pc6dlHY6wfHW/D7FBmOYjAtkjaD1A7qA==", "license": "Apache-2.0", "dependencies": { "base64-js": "^1.3.0", "ecdsa-sig-formatter": "^1.0.11", - "gaxios": "^7.1.4", + "gaxios": "^8.3.0", "gcp-metadata": "^9.0.0", "google-logging-utils": "^2.0.0", "jws": "^4.0.0" @@ -5419,9 +5419,9 @@ } }, "node_modules/google-auth-library/node_modules/gaxios": { - "version": "7.1.4", - "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.1.4.tgz", - "integrity": "sha512-bTIgTsM2bWn3XklZISBTQX7ZSddGW+IO3bMdGaemHZ3tbqExMENHLx6kKZ/KlejgrMtj8q7wBItt51yegqalrA==", + "version": "8.3.2", + "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-8.3.2.tgz", + "integrity": "sha512-7VsaTExxjbDv2ZK1YuC4jbgfN33NI/6/7zdYWUHB6mcg51v4tCBZe+xzjqPzOpVzI+C5k1Kk9OQ80WVrXAHOqw==", "license": "Apache-2.0", "dependencies": { "extend": "^3.0.2", @@ -5429,7 +5429,7 @@ "node-fetch": "^3.3.2" }, "engines": { - "node": ">=18" + "node": ">=22" } }, "node_modules/google-auth-library/node_modules/gcp-metadata": { @@ -5446,6 +5446,20 @@ "node": ">=22" } }, + "node_modules/google-auth-library/node_modules/gcp-metadata/node_modules/gaxios": { + "version": "7.3.1", + "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.3.1.tgz", + "integrity": "sha512-kB3rzJV7d9juLZh8/56QTXCwQfxyhdOMdyYk1HdQKFtF8TJTDTZQJtixWIwXdE9Jji91mC41DUNpjleo4L4eAQ==", + "license": "Apache-2.0", + "dependencies": { + "extend": "^3.0.2", + "https-proxy-agent": "^7.0.1", + "node-fetch": "^3.3.2" + }, + "engines": { + "node": ">=18" + } + }, "node_modules/google-auth-library/node_modules/google-logging-utils": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-2.0.1.tgz", diff --git "a/test/integration/# Genkit Documentation & CLI This reference lists common tasks and workflows using the `genkit` CLI. For authoritative command details, always run `genkit --help` or `genkit --help`. ## Prerequisites: Ensure that the CLI is on `genkit-cli` version >= 1.29.0. If not, or if an older version (1.x < 1.29.0) is present, update the Genkit CLI version. Alternatively, to run commands with a specific version or without global installation, prefix them with `npx -y genkit-cli@^1.29.0`. ## Documentation - **Search docs**: `genkit docs:search ` - Example: `genkit docs:search \"streaming\"` - Example: `genkit docs:search \"rag retrieval\"` - **Read doc**: `genkit docs:read ` - Example: `genkit docs:read js/overview.md` - **List docs**: `genkit docs:list` ## Development Workflow (recommended) `genkit start` unintrusively wraps any Node.js program that uses the Genkit library, running it unchanged while capturing traces from every Genkit action so you can prove tools were actually called and inspect model I/O from the terminal, even for headless checks. It forwards stdio, so interactive CLI tools that rely on stdin/stdout work without issues. Running your app directly (`node`/`tsx`/`npm start`) skips trace capture, so you're debugging blind. **Primary pattern (default):** prefix `genkit start --` to your normal run command. This collects telemetry from any Genkit code your program runs, whether triggered from the dev UI, your own web server/web UI, or a plain script: - **Node.js (TypeScript)**: ```bash genkit start -- npx tsx --watch src/index.ts ``` - **Next.js**: ```bash genkit start -- npx next dev ``` - **Without the Dev UI** (still a persistent server): ```bash genkit start --noui -- npx tsx src/index.ts ``` `genkit start` runs until you stop it with Ctrl+C. That is expected and correct for the common cases: a server your web/mobile app calls, or an interactive CLI you exit yourself. `--noui` only drops the Dev UI; it is **not** a one-shot command and will not exit on its own. Do **not** use `genkit start` as a blocking step in automated/non-interactive contexts; use `flow:run` (below) for that. For non-interactive/agent/CI use, add the global `--non-interactive` flag before `--` so the CLI uses defaults and never blocks on a prompt (e.g. the first-run analytics notice), e.g. `genkit flow:run myFlow '' --non-interactive -- npx tsx src/index.ts`. ## Flow Execution (secondary) - **Run a flow**: `genkit flow:run '' -- ` - Invokes a specific flow by name from the CLI. Append your run command after `--` to spin up the runtime for this run (the command runs as-is to register your flows): it runs once, prints a `Trace ID`, then exits, so it's the right choice for a quick, non-interactive check that must self-terminate (unlike `genkit start`). Note: `flow:run` runs **flows** (`ai.defineFlow`), not agents; you can't `flow:run` an agent (`ai.defineAgent`) directly. To verify an agent, wrap one turn in a throwaway flow and run that. Traces for the run can be inspected with the tracing commands below. - **Always pass input JSON explicitly.** `flow:run` sends `undefined` when the input is omitted and does **not** fall back to a schema `.default()`, so a flow with a defaulted input will fail validation unless you pass the value. - **Simple Input**: ```bash genkit flow:run tellJoke '\"chicken\"' -- npx tsx src/index.ts ``` - **Object Input**: ```bash genkit flow:run generateStory '{\"subject\": \"robot\", \"genre\": \"sci-fi\"}' -- npx tsx src/index.ts ``` ## Evaluation - **Evaluate a flow**: `genkit eval:flow [data] -- ` - Runs a flow and evaluates the output against configured evaluators. As with `flow:run`, append your run command after `--` to spin up the runtime for the run. - **Example (Single Input)**: ```bash genkit eval:flow answerQuestion '[{\"testCaseId\": \"1\", \"input\": {\"question\": \"What is Genkit?\"}}]' -- npx tsx src/index.ts ``` - **Example (Batch Input)**: ```bash genkit eval:flow answerQuestion --input inputs.json -- npx tsx src/index.ts ``` - **Run Evaluation**: `genkit eval:run ` - Evaluates a dataset against configured evaluators. - **Example**: ```bash genkit eval:run dataset.json --output results.json ``` ## Tracing - **Get a trace**: `genkit trace:get ` - Retrieves detailed information for a specific trace by its ID. This is particularly useful for debugging failed model calls, inspecting tool execution, or analyzing the exact inputs and outputs of a specific step in your flow. - **Machine-readable output**: add `--format json` (e.g. `genkit trace:get --format json`) to get clean JSON you can pipe into `jq` or other parsers. - **List traces**: `genkit trace:list [options]` - Lists recent traces. Use this to find trace IDs from recent executions. - **Piping to parsers**: the **default** trace output is human-oriented (extra banner/log lines, possible truncation on large traces), so don't pipe that form directly into `jq`. Use `--format json` for clean JSON, or the Dev UI trace viewer (`genkit start`) for complex traces." "b/test/integration/# Genkit Documentation & CLI This reference lists common tasks and workflows using the `genkit` CLI. For authoritative command details, always run `genkit --help` or `genkit --help`. ## Prerequisites: Ensure that the CLI is on `genkit-cli` version >= 1.29.0. If not, or if an older version (1.x < 1.29.0) is present, update the Genkit CLI version. Alternatively, to run commands with a specific version or without global installation, prefix them with `npx -y genkit-cli@^1.29.0`. ## Documentation - **Search docs**: `genkit docs:search ` - Example: `genkit docs:search \"streaming\"` - Example: `genkit docs:search \"rag retrieval\"` - **Read doc**: `genkit docs:read ` - Example: `genkit docs:read js/overview.md` - **List docs**: `genkit docs:list` ## Development Workflow (recommended) `genkit start` unintrusively wraps any Node.js program that uses the Genkit library, running it unchanged while capturing traces from every Genkit action so you can prove tools were actually called and inspect model I/O from the terminal, even for headless checks. It forwards stdio, so interactive CLI tools that rely on stdin/stdout work without issues. Running your app directly (`node`/`tsx`/`npm start`) skips trace capture, so you're debugging blind. **Primary pattern (default):** prefix `genkit start --` to your normal run command. This collects telemetry from any Genkit code your program runs, whether triggered from the dev UI, your own web server/web UI, or a plain script: - **Node.js (TypeScript)**: ```bash genkit start -- npx tsx --watch src/index.ts ``` - **Next.js**: ```bash genkit start -- npx next dev ``` - **Without the Dev UI** (still a persistent server): ```bash genkit start --noui -- npx tsx src/index.ts ``` `genkit start` runs until you stop it with Ctrl+C. That is expected and correct for the common cases: a server your web/mobile app calls, or an interactive CLI you exit yourself. `--noui` only drops the Dev UI; it is **not** a one-shot command and will not exit on its own. Do **not** use `genkit start` as a blocking step in automated/non-interactive contexts; use `flow:run` (below) for that. For non-interactive/agent/CI use, add the global `--non-interactive` flag before `--` so the CLI uses defaults and never blocks on a prompt (e.g. the first-run analytics notice), e.g. `genkit flow:run myFlow '' --non-interactive -- npx tsx src/index.ts`. ## Flow Execution (secondary) - **Run a flow**: `genkit flow:run '' -- ` - Invokes a specific flow by name from the CLI. Append your run command after `--` to spin up the runtime for this run (the command runs as-is to register your flows): it runs once, prints a `Trace ID`, then exits, so it's the right choice for a quick, non-interactive check that must self-terminate (unlike `genkit start`). Note: `flow:run` runs **flows** (`ai.defineFlow`), not agents; you can't `flow:run` an agent (`ai.defineAgent`) directly. To verify an agent, wrap one turn in a throwaway flow and run that. Traces for the run can be inspected with the tracing commands below. - **Always pass input JSON explicitly.** `flow:run` sends `undefined` when the input is omitted and does **not** fall back to a schema `.default()`, so a flow with a defaulted input will fail validation unless you pass the value. - **Simple Input**: ```bash genkit flow:run tellJoke '\"chicken\"' -- npx tsx src/index.ts ``` - **Object Input**: ```bash genkit flow:run generateStory '{\"subject\": \"robot\", \"genre\": \"sci-fi\"}' -- npx tsx src/index.ts ``` ## Evaluation - **Evaluate a flow**: `genkit eval:flow [data] -- ` - Runs a flow and evaluates the output against configured evaluators. As with `flow:run`, append your run command after `--` to spin up the runtime for the run. - **Example (Single Input)**: ```bash genkit eval:flow answerQuestion '[{\"testCaseId\": \"1\", \"input\": {\"question\": \"What is Genkit?\"}}]' -- npx tsx src/index.ts ``` - **Example (Batch Input)**: ```bash genkit eval:flow answerQuestion --input inputs.json -- npx tsx src/index.ts ``` - **Run Evaluation**: `genkit eval:run ` - Evaluates a dataset against configured evaluators. - **Example**: ```bash genkit eval:run dataset.json --output results.json ``` ## Tracing - **Get a trace**: `genkit trace:get ` - Retrieves detailed information for a specific trace by its ID. This is particularly useful for debugging failed model calls, inspecting tool execution, or analyzing the exact inputs and outputs of a specific step in your flow. - **Machine-readable output**: add `--format json` (e.g. `genkit trace:get --format json`) to get clean JSON you can pipe into `jq` or other parsers. - **List traces**: `genkit trace:list [options]` - Lists recent traces. Use this to find trace IDs from recent executions. - **Piping to parsers**: the **default** trace output is human-oriented (extra banner/log lines, possible truncation on large traces), so don't pipe that form directly into `jq`. Use `--format json` for clean JSON, or the Dev UI trace viewer (`genkit start`) for complex traces." new file mode 100644 index 0000000000..e69de29bb2