docs: recommend current models and explain provider-only validation (stack 3/4)

.changeset/open-model-ids.md

@@ -0,0 +1,9 @@
+---
+"@browserbasehq/stagehand-protocol": minor
+"@browserbasehq/stagehand-extension": patch
+"@browserbasehq/stagehand-python": minor
+"@browserbasehq/stagehand-go": minor
+"@browserbasehq/stagehand": minor
+---
+
+Accept any nonempty model ID under the OpenAI, Anthropic, and Google provider prefixes without a Stagehand release. Unknown model IDs now fail on the provider request instead of during configuration validation. Public model ID types widen from literal unions to strings. Examples and generated schema samples use current provider IDs such as `openai/gpt-6-luna`, `anthropic/claude-sonnet-5-5`, and `google/gemini-3.8-flash`.

.changeset/remove-groq-cerebras.md

@@ -0,0 +1,9 @@
+---
+"@browserbasehq/stagehand-protocol": major
+"@browserbasehq/stagehand-extension": patch
+"@browserbasehq/stagehand-python": patch
+"@browserbasehq/stagehand-go": patch
+"@browserbasehq/stagehand": patch
+---
+
+Remove native Groq and Cerebras provider support.

README.md

@@ -58,7 +58,7 @@ import { z } from "zod/v4";
 const browser = await localBrowser.launch({ userDataDir: "./browser-data" });
 const stagehand = await Stagehand.create({
   browser,
-  model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY },
+  model: { modelName: "openai/gpt-6-luna", apiKey: process.env.OPENAI_API_KEY },
 });
 
 const [page] = await browser.context.pages();
@@ -115,7 +115,7 @@ async def main() -> None:
     try:
         stagehand = await Stagehand.create(
             browser=browser,
-            model="openai/gpt-5.4-mini",
+            model="openai/gpt-6-luna",
             model_api_key=os.environ["OPENAI_API_KEY"],
         )
         try:
@@ -195,7 +195,7 @@ func run(ctx context.Context) (err error) {
 	client, err := stagehand.Create(ctx, stagehand.CreateOptions{
 		Browser: browser,
 		Model: &stagehand.ModelConfig{
-			ModelName: "openai/gpt-5.4-mini",
+			ModelName: "openai/gpt-6-luna",
 			APIKey:    &modelAPIKey,
 		},
 	})

packages/docs/v2/configuration/models.mdx

@@ -35,7 +35,6 @@ Set up your API keys before configuring Stagehand:
 OPENAI_API_KEY=your_openai_key_here
 ANTHROPIC_API_KEY=your_anthropic_key_here
 GOOGLE_API_KEY=your_google_key_here
-GROQ_API_KEY=your_groq_key_here
 ```
 </CodeGroup>
 
@@ -54,10 +53,8 @@ Stagehand supports major LLM providers with structured output capabilities:
 ### Additional Providers
 
 <Expandable title="More Providers">
-- **Groq** - `llama-3.3-70b-versatile` (Good for speed critical applications)
 - **xAI** - `grok-beta` (Good for complex reasoning)
 - **Azure** - Enterprise OpenAI deployment
-- **Cerebras** - High-speed inference
 - **TogetherAI** - Open-source models
 - **Mistral** - `mixtral-8x7b-32768` (European option)
 - **DeepSeek** - Cost-effective alternative
@@ -302,4 +299,4 @@ For each provider, use their latest models that meet these requirements. Some ex
 <Card title="Cache Results" href="/v2/best-practices/caching" icon="database">
   Store successful patterns using our Caching Guide
 </Card>
-</CardGroup>
+</CardGroup>

packages/docs/v3/configuration/models.mdx

@@ -340,24 +340,6 @@ For Microsoft Entra ID authentication, pass the bearer token explicitly in `auth
 [View all supported Azure models →](https://ai.azure.com/catalog)
 </Tab>
 
-<Tab title="Cerebras">
-<CodeGroup>
-```typescript TypeScript
-import { Stagehand } from "@browserbasehq/stagehand";
-
-const stagehand = new Stagehand({
-  env: "BROWSERBASE",
-  model: "cerebras/llama-4-scout"
-  // API key auto-loads from CEREBRAS_API_KEY - set in your .env
-});
-
-await stagehand.init();
-```
-
-</CodeGroup>
-[View all supported Cerebras models →](https://inference-docs.cerebras.ai/models/overview)
-</Tab>
-
 <Tab title="DeepSeek">
 
 <CodeGroup>
@@ -377,26 +359,6 @@ await stagehand.init();
 [View all supported DeepSeek models →](https://api-docs.deepseek.com/quick_start/pricing)
 </Tab>
 
-<Tab title="Groq">
-
-
-<CodeGroup>
-```typescript TypeScript
-import { Stagehand } from "@browserbasehq/stagehand";
-
-const stagehand = new Stagehand({
-  env: "BROWSERBASE",
-  model: "groq/llama-3.1-8b-instant"
-  // API key auto-loads from GROQ_API_KEY - set in your .env
-});
-
-await stagehand.init();
-```
-
-</CodeGroup>
-[View all supported Groq models →](https://console.groq.com/docs/models)
-</Tab>
-
 <Tab title="Mistral">
 
 <CodeGroup>
@@ -1003,19 +965,6 @@ The following models work without the `provider/` prefix in the model parameter
 - `gpt-4o-2024-08-06`
 - `o1-preview`
 
-</Accordion>
-<Accordion title="Cerebras">
-
-- `cerebras-llama-3.3-70b`
-- `cerebras-llama-3.1-8b`
-
-</Accordion>
-<Accordion title="Groq">
-
-- `groq-llama-3.3-70b-versatile`
-- `groq-llama-3.3-70b-specdec`
-- `moonshotai/kimi-k2-instruct`
-
 </Accordion>
 </AccordionGroup>
 
@@ -1042,9 +991,7 @@ The following models work without the `provider/` prefix in the model parameter
 | Anthropic  | `ANTHROPIC_API_KEY`            |
 | OpenAI     | `OPENAI_API_KEY`               |
 | Azure      | `AZURE_API_KEY`                |
-| Cerebras   | `CEREBRAS_API_KEY`             |
 | DeepSeek   | `DEEPSEEK_API_KEY`             |
-| Groq       | `GROQ_API_KEY`                 |
 | Mistral    | `MISTRAL_API_KEY`              |
 | Ollama     | None (local)                   |
 | Perplexity | `PERPLEXITY_API_KEY`           |

packages/docs/v4/basics/extract.mdx

@@ -380,7 +380,7 @@ const result = await stagehand.extract(
   z.object({ name: z.string() }),
   {
     model: {
-      modelName: "anthropic/claude-sonnet-5",
+      modelName: "anthropic/claude-sonnet-5-5",
       apiKey: process.env.ANTHROPIC_API_KEY,
     },
     timeout: 30000,
@@ -402,7 +402,7 @@ result = await stagehand.extract(
     "extract the repository name",
     Repository,
     model=ModelConfig(
-        model_name="anthropic/claude-sonnet-5",
+        model_name="anthropic/claude-sonnet-5-5",
         api_key=os.environ["ANTHROPIC_API_KEY"],
     ),
     timeout=30000,
@@ -416,7 +416,7 @@ result = await stagehand.extract(
 
 modelAPIKey := os.Getenv("ANTHROPIC_API_KEY")
 model := stagehand.ModelConfig{
-	ModelName: "anthropic/claude-sonnet-5",
+	ModelName: "anthropic/claude-sonnet-5-5",
 	APIKey:    &modelAPIKey,
 }
 timeout := 30000.0

packages/docs/v4/basics/observe.mdx

@@ -264,7 +264,7 @@ const page = await stagehand.browser.context.activePage();
 // Custom model configuration
 const { data: actions } = await stagehand.observe("find navigation links", {
   model: {
-    modelName: "openai/gpt-5.6-luna",
+    modelName: "openai/gpt-6-luna",
     apiKey: process.env.OPENAI_API_KEY,
   },
   timeout: 30000,
@@ -285,7 +285,7 @@ page = await stagehand.browser.context.active_page()
 result = await stagehand.observe(
     "find navigation links",
     model=ModelConfig(
-        model_name="openai/gpt-5.6-luna",
+        model_name="openai/gpt-6-luna",
         api_key=os.environ["OPENAI_API_KEY"],
     ),
     timeout=30000,
@@ -299,7 +299,7 @@ result = await stagehand.observe(
 // Custom model configuration
 modelAPIKey := os.Getenv("OPENAI_API_KEY")
 model := stagehand.ModelConfig{
-	ModelName: "openai/gpt-5.6-luna",
+	ModelName: "openai/gpt-6-luna",
 	APIKey:    &modelAPIKey,
 }
 timeout := 30000.0

packages/docs/v4/best-practices/caching.mdx

@@ -599,7 +599,7 @@ const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_K
 
 const stagehand = await Stagehand.create({
   browser,
-  model: { modelName: "openai/gpt-5.6-sol" }, // Routed through Model Gateway
+  model: { modelName: "openai/gpt-6.1-sol" }, // Routed through Model Gateway
   cache: true,                                // Served by Browserbase Cache
 });
 ```
@@ -611,7 +611,7 @@ browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
 
 stagehand = await Stagehand.create(
     browser=browser,
-    model="openai/gpt-5.6-sol",  # Routed through Model Gateway
+    model="openai/gpt-6.1-sol",  # Routed through Model Gateway
     cache=True,                  # Served by Browserbase Cache
 )
 ```
@@ -621,7 +621,7 @@ stagehand = await Stagehand.create(
 ```go
 apiKey := os.Getenv("BROWSERBASE_API_KEY")
 // Routed through Model Gateway: no model API key
-model := stagehand.ModelConfig{ModelName: "openai/gpt-5.6-sol"}
+model := stagehand.ModelConfig{ModelName: "openai/gpt-6.1-sol"}
 cache := stagehand.CacheEnabled(true) // Served by Browserbase Cache
 
 browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{

packages/docs/v4/best-practices/cost-optimization.mdx

@@ -31,7 +31,7 @@ const termsSchema = z.object({ summary: z.string() });
 // One hard extraction gets the expensive model, everything else stays cheap
 await stagehand.extract("summarize the contract terms", termsSchema, {
   model: {
-    modelName: "anthropic/claude-sonnet-5",
+    modelName: "anthropic/claude-sonnet-5-5",
     apiKey: process.env.ANTHROPIC_API_KEY,
   },
 });
@@ -60,7 +60,7 @@ await stagehand.extract(
     instruction="summarize the contract terms",
     schema=Terms,
     model=ModelConfig(
-        model_name="anthropic/claude-sonnet-5",
+        model_name="anthropic/claude-sonnet-5-5",
         api_key=os.environ["ANTHROPIC_API_KEY"],
     ),
 )
@@ -98,7 +98,7 @@ if err != nil {
 // One hard extraction gets the expensive model, everything else stays cheap
 anthropicKey := os.Getenv("ANTHROPIC_API_KEY")
 strongModel := stagehand.ModelConfig{
-	ModelName: "anthropic/claude-sonnet-5",
+	ModelName: "anthropic/claude-sonnet-5-5",
 	APIKey:    &anthropicKey,
 }
 
@@ -271,7 +271,7 @@ Automatically fall back to cheaper models for simple tasks. Escalate on `observe
 async function smartAct(stagehand: Stagehand, prompt: string) {
   const models = [
     { modelName: "google/gemini-3.8-flash", apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY },
-    { modelName: "openai/gpt-5.4", apiKey: process.env.OPENAI_API_KEY },
+    { modelName: "openai/gpt-6.1-sol", apiKey: process.env.OPENAI_API_KEY },
   ] as const;
 
   for (const model of models) {
@@ -302,7 +302,7 @@ async def smart_act(stagehand: Stagehand, prompt: str):
             "model_name": "google/gemini-3.8-flash",
             "api_key": os.environ["GOOGLE_GENERATIVE_AI_API_KEY"],
         },
-        {"model_name": "openai/gpt-5.4", "api_key": os.environ["OPENAI_API_KEY"]},
+        {"model_name": "openai/gpt-6.1-sol", "api_key": os.environ["OPENAI_API_KEY"]},
     ]
 
     for model in models:
@@ -338,7 +338,7 @@ func smartAct(ctx context.Context, client *stagehand.Stagehand, prompt string) (
 			APIKey:    &googleKey,
 		},
 		stagehand.ModelConfig{
-			ModelName: "openai/gpt-5.4",
+			ModelName: "openai/gpt-6.1-sol",
 			APIKey:    &openaiKey,
 		},
 	}

packages/docs/v4/configuration/logging.mdx

@@ -1094,7 +1094,7 @@ Emitted before each LLM call, carrying the operation and prompt metadata:
   "data": {
     "category": "llm",
     "operation": "act",
-    "model": "openai/gpt-5.4-mini"
+    "model": "openai/gpt-6-luna"
   }
 }
 ```
@@ -1269,7 +1269,7 @@ Unlike v3's `LogLine`, `data` is a flat JSON object: values are already typed, s
   "message": "inference completed",
   "data": {
     "category": "llm",
-    "model": "openai/gpt-5.4-mini",
+    "model": "openai/gpt-6-luna",
     "promptTokens": 3451,
     "completionTokens": 45
   }