From 68e06069f1a73dff7151c79f45141b02c311baae Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Mon, 2 Mar 2026 12:53:29 +0000 Subject: [PATCH 1/2] docs: update model parameter as optional in docs and examples Since #663 made `model` optional in RunSetting/RunParamsInput with tier-based auto-resolution, update all documentation and code examples to reflect this change. Remove hardcoded model values from run() calls, add comments explaining auto-resolution, and rewrite the default model documentation to explain the tier-based system. Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- docs/getting-started/walkthrough.mdx | 4 ++-- docs/operating-experts/deployment.md | 2 +- docs/references/cli.md | 2 +- docs/references/providers-and-models.md | 8 ++++---- packages/runtime/README.md | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index d7c80edc..401c782d 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,7 @@ import { run } from "@perstack/runtime" const checkpoint = await run({ setting: { - model: "claude-sonnet-4-5", + // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic", apiKey: env.ANTHROPIC_API_KEY }, expertKey: "my-expert", input: { text: query }, diff --git a/docs/getting-started/walkthrough.mdx b/docs/getting-started/walkthrough.mdx index e11f558c..97a4c395 100644 --- a/docs/getting-started/walkthrough.mdx +++ b/docs/getting-started/walkthrough.mdx @@ -276,7 +276,7 @@ import { run } from "@perstack/runtime" const checkpoint = await run({ setting: { - model: "claude-sonnet-4-5-20250929", + // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic" }, expertKey: "fitness-assistant", input: { text: "Start today's session" }, @@ -291,7 +291,7 @@ import { run } from "@perstack/runtime" const checkpoint = await run({ setting: { - model: "claude-sonnet-4-5-20250929", + // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic" }, expertKey: "fitness-assistant", input: { text: "Start today's session" }, diff --git a/docs/operating-experts/deployment.md b/docs/operating-experts/deployment.md index 6170e7b8..43086233 100644 --- a/docs/operating-experts/deployment.md +++ b/docs/operating-experts/deployment.md @@ -92,7 +92,7 @@ export default { await run( { setting: { - model: "claude-sonnet-4-5", + // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic", apiKey: env.ANTHROPIC_API_KEY }, expertKey, input: { text: query }, diff --git a/docs/references/cli.md b/docs/references/cli.md index 8cd2ccbd..09b72e6f 100644 --- a/docs/references/cli.md +++ b/docs/references/cli.md @@ -74,7 +74,7 @@ Both `start` and `run` accept the following options: | Option | Default | Description | | ----------------------------- | --------------- | -------------------------------------------------------------------------------------- | | `--provider ` | `anthropic` | LLM provider | -| `--model ` | `claude-sonnet-4-5` | Model name | +| `--model ` | `auto` | Model name (auto-resolved from expert tier or provider's middle tier) | | `--reasoning-budget ` | - | Reasoning budget (`minimal`, `low`, `medium`, `high`, or token count) | Providers: `anthropic`, `google`, `openai`, `deepseek`, `ollama`, `azure-openai`, `amazon-bedrock`, `google-vertex` diff --git a/docs/references/providers-and-models.md b/docs/references/providers-and-models.md index 3f642e80..4f256789 100644 --- a/docs/references/providers-and-models.md +++ b/docs/references/providers-and-models.md @@ -8,12 +8,12 @@ Perstack supports multiple LLM providers. Configure via CLI options, environment ## Default Model -Perstack uses `claude-sonnet-4-5` as the default model, selected based on: +When no model is specified, Perstack resolves it automatically using a tier-based system: -- **Standard tier pricing** — not a flagship model, economically sustainable for extended runs -- **High agentic performance** — demonstrated tool use capability in benchmarks like [𝜏²-Bench](https://artificialanalysis.ai/evaluations/tau2-bench) +1. **Expert's `defaultModelTier`** — if the expert definition sets a `defaultModelTier` (e.g. `high`, `middle`, `low`), the runtime picks the corresponding model from the provider +2. **Provider's middle tier** — if no tier is set, falls back to the provider's "middle" tier (e.g. `claude-sonnet-4-5` for Anthropic) -The default balances cost efficiency with reliable agent behavior. As new models are released, the default may change based on these criteria. +This ensures cost-efficient defaults while letting experts request more capable models when needed. You can always override the resolved model with `--model` via the CLI or `model =` in `perstack.toml`. To override the default, specify in `perstack.toml`: diff --git a/packages/runtime/README.md b/packages/runtime/README.md index fa143de2..90897a52 100644 --- a/packages/runtime/README.md +++ b/packages/runtime/README.md @@ -18,7 +18,7 @@ import { run } from "@perstack/runtime" const checkpoint = await run( { setting: { - model: "claude-sonnet-4-5", + // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic", apiKey: "..." }, jobId: "job-123", runId: "run-123", From 82101807c9cd04b0d671fb173e37e75a55f7e22e Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Mon, 2 Mar 2026 12:54:37 +0000 Subject: [PATCH 2/2] docs: remove unnecessary optional model comments Co-Authored-By: Claude Opus 4.6 --- README.md | 1 - docs/getting-started/walkthrough.mdx | 2 -- docs/operating-experts/deployment.md | 1 - packages/runtime/README.md | 1 - 4 files changed, 5 deletions(-) diff --git a/README.md b/README.md index 401c782d..9a53da8e 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,6 @@ import { run } from "@perstack/runtime" const checkpoint = await run({ setting: { - // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic", apiKey: env.ANTHROPIC_API_KEY }, expertKey: "my-expert", input: { text: query }, diff --git a/docs/getting-started/walkthrough.mdx b/docs/getting-started/walkthrough.mdx index 97a4c395..eaa1ed0e 100644 --- a/docs/getting-started/walkthrough.mdx +++ b/docs/getting-started/walkthrough.mdx @@ -276,7 +276,6 @@ import { run } from "@perstack/runtime" const checkpoint = await run({ setting: { - // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic" }, expertKey: "fitness-assistant", input: { text: "Start today's session" }, @@ -291,7 +290,6 @@ import { run } from "@perstack/runtime" const checkpoint = await run({ setting: { - // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic" }, expertKey: "fitness-assistant", input: { text: "Start today's session" }, diff --git a/docs/operating-experts/deployment.md b/docs/operating-experts/deployment.md index 43086233..2c19085e 100644 --- a/docs/operating-experts/deployment.md +++ b/docs/operating-experts/deployment.md @@ -92,7 +92,6 @@ export default { await run( { setting: { - // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic", apiKey: env.ANTHROPIC_API_KEY }, expertKey, input: { text: query }, diff --git a/packages/runtime/README.md b/packages/runtime/README.md index 90897a52..da8d4d71 100644 --- a/packages/runtime/README.md +++ b/packages/runtime/README.md @@ -18,7 +18,6 @@ import { run } from "@perstack/runtime" const checkpoint = await run( { setting: { - // model is optional — auto-resolved from expert's defaultModelTier or provider's middle tier providerConfig: { providerName: "anthropic", apiKey: "..." }, jobId: "job-123", runId: "run-123",