From 83cd9e16138525e711803929b735b57d12505c17 Mon Sep 17 00:00:00 2001 From: dianed-square <73617011+dianed-square@users.noreply.github.com> Date: Fri, 13 Jun 2025 16:07:42 -0700 Subject: [PATCH] docs: updates for lead-worker model (#2916) --- documentation/docs/guides/config-file.md | 12 +++++++---- documentation/docs/guides/creating-plans.md | 4 ++++ .../docs/guides/environment-variables.md | 20 +++++++++++++------ 3 files changed, 26 insertions(+), 10 deletions(-) diff --git a/documentation/docs/guides/config-file.md b/documentation/docs/guides/config-file.md index f5f28bbd..d79e7e73 100644 --- a/documentation/docs/guides/config-file.md +++ b/documentation/docs/guides/config-file.md @@ -11,7 +11,7 @@ Goose uses a YAML configuration file to manage settings and extensions. This fil * macOS/Linux: `~/.config/goose/config.yaml` * Windows: `%APPDATA%\Block\goose\config\config.yaml` -The configuration file allows you to set default behaviors, configure language models, and manage extensions. While many settings can also be set using environment variables, the config file provides a persistent way to maintain your preferences. +The configuration file allows you to set default behaviors, configure language models, and manage extensions. While many settings can also be set using [environment variables](/docs/guides/environment-variables), the config file provides a persistent way to maintain your preferences. ## Global Settings @@ -19,18 +19,22 @@ The following settings can be configured at the root level of your config.yaml f | Setting | Purpose | Values | Default | Required | |---------|---------|---------|---------|-----------| -| `GOOSE_PROVIDER` | Primary LLM provider | "anthropic", "openai", etc. | None | Yes | +| `GOOSE_PROVIDER` | Primary [LLM provider](/docs/getting-started/providers) | "anthropic", "openai", etc. | None | Yes | | `GOOSE_MODEL` | Default model to use | Model name (e.g., "claude-3.5-sonnet", "gpt-4") | None | Yes | | `GOOSE_TEMPERATURE` | Model response randomness | Float between 0.0 and 1.0 | Model-specific | No | | `GOOSE_MODE` | Tool execution behavior | "auto", "approve", "chat", "smart_approve" | "smart_approve" | No | -| `GOOSE_PLANNER_PROVIDER` | Provider for planning mode | Same as GOOSE_PROVIDER options | Falls back to GOOSE_PROVIDER | No | -| `GOOSE_PLANNER_MODEL` | Model for planning mode | Model name | Falls back to GOOSE_MODEL | No | +| `GOOSE_LEAD_PROVIDER` | Provider for lead model in [lead/worker mode](/docs/guides/environment-variables#leadworker-model-configuration) | Same as `GOOSE_PROVIDER` options | Falls back to `GOOSE_PROVIDER` | No | +| `GOOSE_LEAD_MODEL` | Lead model for lead/worker mode | Model name | None | No | +| `GOOSE_PLANNER_PROVIDER` | Provider for [planning mode](/docs/guides/creating-plans) | Same as `GOOSE_PROVIDER` options | Falls back to `GOOSE_PROVIDER` | No | +| `GOOSE_PLANNER_MODEL` | Model for planning mode | Model name | Falls back to `GOOSE_MODEL` | No | | `GOOSE_TOOLSHIM` | Enable tool interpretation | true/false | false | No | | `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Model for tool interpretation | Model name (e.g., "llama3.2") | System default | No | | `GOOSE_CLI_MIN_PRIORITY` | Tool output verbosity | Float between 0.0 and 1.0 | 0.0 | No | | `GOOSE_ALLOWLIST` | URL for allowed extensions | Valid URL | None | No | | `GOOSE_RECIPE_GITHUB_REPO` | GitHub repository for recipes | Format: "org/repo" | None | No | +Additional [environment variables](/docs/guides/environment-variables) may also be supported in config.yaml. + ## Example Configuration Here's a basic example of a config.yaml file: diff --git a/documentation/docs/guides/creating-plans.md b/documentation/docs/guides/creating-plans.md index c62077a8..39dcdf19 100644 --- a/documentation/docs/guides/creating-plans.md +++ b/documentation/docs/guides/creating-plans.md @@ -31,6 +31,10 @@ The Goose CLI plan mode uses two configuration values: - `GOOSE_PLANNER_PROVIDER`: Which provider to use for planning - `GOOSE_PLANNER_MODEL`: Which model to use for planning +:::tip Use Lead/Worker Mode For Automatic Model Switching +[Lead/worker mode](/docs/guides/environment-variables#leadworker-model-configuration) is an alternative to plan mode. It allows you to configure a powerful lead model for initial planning and reasoning before automatically switching to a faster and/or cheaper worker model for execution. Both modes help you achieve optimal results by balancing model capabilities with cost and speed. +::: + ### Set Goose planner environment variables You might add these lines to your bash shell config file (.bashrc) to add the planner environment variables: ```bash diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index 487661a2..4c397b3c 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -50,15 +50,23 @@ export GOOSE_PROVIDER__API_KEY="your-api-key-here" ### Lead/Worker Model Configuration -Configure a lead/worker model pattern where a powerful model handles initial planning and complex reasoning, then switches to a faster/cheaper model for execution. +These variables configure a lead/worker model pattern where a powerful lead model handles initial planning and complex reasoning, then switches to a faster/cheaper worker model for execution. The switch happens automatically based on your settings. | Variable | Purpose | Values | Default | |----------|---------|---------|---------| -| `GOOSE_LEAD_MODEL` | **Required to enable lead mode.** Specifies the lead model name | Model name (e.g., "gpt-4o", "claude-3.5-sonnet") | None | -| `GOOSE_LEAD_PROVIDER` | Provider for the lead model | [See available providers](/docs/getting-started/providers#available-providers) | Falls back to GOOSE_PROVIDER | -| `GOOSE_LEAD_TURNS` | Number of initial turns using the lead model | Integer | 3 | -| `GOOSE_LEAD_FAILURE_THRESHOLD` | Consecutive failures before fallback to lead model | Integer | 2 | -| `GOOSE_LEAD_FALLBACK_TURNS` | Number of turns to use lead model in fallback mode | Integer | 2 | +| `GOOSE_LEAD_MODEL` | **Required to enable lead mode.** Name of the lead model | Model name (e.g., "gpt-4o", "claude-3.5-sonnet") | None | +| `GOOSE_LEAD_PROVIDER` | Provider for the lead model | [See available providers](/docs/getting-started/providers#available-providers) | Falls back to `GOOSE_PROVIDER` | +| `GOOSE_LEAD_TURNS` | Number of initial turns using the lead model before switching to the worker model | Integer | 3 | +| `GOOSE_LEAD_FAILURE_THRESHOLD` | Consecutive failures before fallback to the lead model | Integer | 2 | +| `GOOSE_LEAD_FALLBACK_TURNS` | Number of turns to use the lead model in fallback mode | Integer | 2 | + +A _turn_ is one complete prompt-response interaction. Here's how it works with the default settings: +- Use the lead model for the first 3 turns +- Use the worker model starting on the 4th turns +- Fallback to the lead model if the worker model struggles for 2 consecutive turns +- Use the lead model for 2 turns and then switch back to the worker model + +The lead model and worker model names are displayed at the start of the Goose CLI session. If you don't export a `GOOSE_MODEL` for your session, the worker model defaults to the `GOOSE_MODEL` in your [configuration file](/docs/guides/config-file). **Examples**