Merge pull request #53 from petal-labs/docs/update-example-models

docs(examples): refresh README and examples to latest models

Author: erikhoward

README.md

@@ -80,7 +80,7 @@ func main() {
     client := core.NewClient(provider)
 
     // Send a chat request
-    resp, err := client.Chat("gpt-4o").
+    resp, err := client.Chat("gpt-5.6").
         System("You are a helpful assistant.").
         User("What is the capital of France?").
         Temperature(0.7).
@@ -393,7 +393,7 @@ client := core.NewClient(provider, core.WithTimeout(5*time.Minute))
 client := core.NewClient(provider, core.WithTimeout(0))
 
 // Per-call override
-resp, err := client.Chat("gpt-4o").
+resp, err := client.Chat("gpt-5.6").
     User("Hello").
     Timeout(30 * time.Second).
     GetResponse(context.Background())
@@ -409,7 +409,7 @@ Precedence: a deadline already on the caller's `ctx` always wins; otherwise the
 ### Streaming Responses
 
 ```go
-stream, err := client.Chat("gpt-4o").
+stream, err := client.Chat("gpt-5.6").
     User("Write a short poem about Go.").
     Stream(context.Background())
 
@@ -445,7 +445,7 @@ client := core.NewClient(provider,
 // Define a tool
 weatherTool := mytools.NewWeatherTool()
 
-resp, err := client.Chat("gpt-4o").
+resp, err := client.Chat("gpt-5.6").
     User("What's the weather in San Francisco?").
     Tools(weatherTool).
     GetResponse(ctx)
@@ -473,7 +473,7 @@ wrappedTool := tools.ApplyMiddleware(
     tools.WithLogging(logger),
 )
 
-resp, err := client.Chat("gpt-4o").
+resp, err := client.Chat("gpt-5.6").
     User("What's the weather in San Francisco?").
     Tools(wrappedTool).
     GetResponse(ctx)
@@ -487,7 +487,7 @@ Constrain model output to valid JSON or a specific JSON Schema:
 
 ```go
 // JSON mode - model outputs valid JSON
-resp, err := client.Chat("gpt-4o").
+resp, err := client.Chat("gpt-5.6").
     User("List 3 programming languages with their year created").
     ResponseJSON().
     GetResponse(ctx)
@@ -517,7 +517,7 @@ schema := &core.JSONSchemaDefinition{
     }`),
 }
 
-resp, err := client.Chat("gpt-4o").
+resp, err := client.Chat("gpt-5.6").
     User("Extract: John is 30 years old").
     ResponseJSONSchema(schema).
     GetResponse(ctx)
@@ -533,7 +533,7 @@ The `Conversation` type manages message history automatically:
 
 ```go
 // Create a conversation with a system prompt
-conv := core.NewConversation(client, "gpt-4o",
+conv := core.NewConversation(client, "gpt-5.6",
     core.WithSystemMessage("You are a helpful assistant."),
 )
 
@@ -561,8 +561,8 @@ if !ok {
 
 // Create batch requests
 requests := []core.BatchRequest{
-    {CustomID: "req-1", Request: core.ChatRequest{Model: "gpt-4o", Messages: msgs1}},
-    {CustomID: "req-2", Request: core.ChatRequest{Model: "gpt-4o", Messages: msgs2}},
+    {CustomID: "req-1", Request: core.ChatRequest{Model: "gpt-5.6", Messages: msgs1}},
+    {CustomID: "req-2", Request: core.ChatRequest{Model: "gpt-5.6", Messages: msgs2}},
 }
 
 // Submit batch
@@ -719,7 +719,7 @@ iris keys set zai
 iris keys set ollama  # Only needed for Ollama Cloud
 
 # Chat with OpenAI
-iris chat --provider openai --model gpt-4o --prompt "Hello, world!"
+iris chat --provider openai --model gpt-5.6 --prompt "Hello, world!"
 
 # Chat with Anthropic Claude
 iris chat --provider anthropic --model claude-sonnet-5 --prompt "Hello, world!"
@@ -740,11 +740,11 @@ iris chat --provider ollama --model llama3.2 --prompt "Hello, world!"
 iris chat --provider openai --model gpt-5 --prompt "Explain quantum entanglement"
 
 # Stream responses
-iris chat --provider openai --model gpt-4o --prompt "Tell me a story" --stream
+iris chat --provider openai --model gpt-5.6 --prompt "Tell me a story" --stream
 iris chat --provider anthropic --model claude-sonnet-5 --prompt "Tell me a story" --stream
 
 # Get JSON output
-iris chat --provider openai --model gpt-4o --prompt "Hello" --json
+iris chat --provider openai --model gpt-5.6 --prompt "Hello" --json
 
 # Initialize a new project
 iris init myproject

docs/changes/2026-08-02_v0.17.0_example-model-refresh.md

@@ -0,0 +1,119 @@
+---
+date: 2026-08-02
+version: v0.17.0
+feature: Example/README Model Refresh (latest provider models)
+product: iris
+change_type: docs
+affected_components: [README.md, examples/batch/basic/main.go, examples/chat/basic/main.go, examples/chat/conversation/main.go, examples/chat/conversation-streaming/main.go, examples/chat/streaming/main.go, examples/chat/structured-output/main.go, examples/chat/system-message/main.go, examples/chat/xai-basic/main.go, examples/chat/zai-basic/main.go, examples/chat/zai-streaming/main.go, examples/image/gemini/main.go, examples/testing/mock-provider/main.go, examples/tools/weather/main.go]
+related_frds: []
+---
+
+## Summary
+
+Updated the model identifiers used throughout `README.md`'s code snippets and the `examples/` programs so they demonstrate Iris against each provider's current latest models instead of older/deprecated ones. This is a documentation/example-only change: no `core/` or `providers/` production code was modified (provider `models.go` files were only read, to confirm target constant names exist). The refresh replaces the generic OpenAI small/flagship model strings (`gpt-4o-mini`, `gpt-4o`) and two typed provider constants (`xai.ModelGrok41FastNonReasoning`, `zai.ModelGLM47Flash`) with their current equivalents, and swaps the Gemini image example onto the newest image-generation constant. The xAI reasoning example intentionally stays on `grok-3-mini` (see below).
+
+## Motivation
+
+Examples are the first code a new Iris user copies and runs. Several had drifted behind the provider model catalogs (already kept current in the README's own "Supported Models" tables and in `providers/*/models.go`), so a user following the README or `go run`-ing an example would unknowingly reach for an older/soon-to-be-legacy model. This change brings example code back in line with the catalog without touching the catalog itself or the reference tables, which were already current.
+
+## What Changed
+
+### New Additions
+
+N/A — no new files, types, or exported symbols were added. This change only edits existing example programs and README code fences.
+
+### Modifications
+
+- **`"gpt-4o-mini"` → `"gpt-5.4-mini"`** (string literal, OpenAI small model) in:
+  - `examples/batch/basic/main.go` (3 occurrences — three batch request entries)
+  - `examples/chat/basic/main.go` (1)
+  - `examples/chat/conversation/main.go` (1)
+  - `examples/chat/conversation-streaming/main.go` (1)
+  - `examples/chat/streaming/main.go` (1)
+  - `examples/chat/structured-output/main.go` (2)
+  - `examples/chat/system-message/main.go` (3)
+  - `examples/testing/mock-provider/main.go` (2 — both the `RecordingProvider` fallback mock response's declared `Model` field and the live `client.Chat(...)` call in `demonstrateRecordingProvider`/`demonstrateRecordingWithProvider`, so the two stay consistent with each other)
+  - `examples/tools/weather/main.go` (1)
+- **`"gpt-4o"` → `"gpt-5.6"`** (string literal, OpenAI flagship model, used generically) in `README.md`, 13 occurrences across the Quick Start example, the Timeouts/Streaming/Tools/Tool-Middleware/Structured-Output/Conversation-Management/Batch-API sections, and three `iris chat --model gpt-4o ...` CLI examples.
+- **`xai.ModelGrok41FastNonReasoning` → `xai.ModelGrok45`** in `examples/chat/xai-basic/main.go`. The stale inline comment ("Using grok-4-1-fast-non-reasoning for quick responses") was updated to reference grok-4.5.
+- **`examples/chat/xai-reasoning/main.go` deliberately keeps `xai.ModelGrok3Mini`.** Per the provider catalog, `grok-3-mini` is the model that exposes `reasoning_content` in responses; newer models like `grok-4.5` support reasoning but do not surface the reasoning trace via `resp.Reasoning`. Since this example prints `resp.Reasoning.Summary`, bumping it to a "latest" model would make the demo produce no reasoning output. It is left on `grok-3-mini` with its explanatory comments intact.
+- **`zai.ModelGLM47Flash` → `zai.ModelGLM52`** in `examples/chat/zai-basic/main.go` and `examples/chat/zai-streaming/main.go`.
+- **`gemini.ModelGemini25FlashImage` → `gemini.ModelGemini31FlashImagePreview`** in `examples/image/gemini/main.go`.
+
+### Removals
+
+N/A — nothing was deleted; only model references and the comments describing them were updated.
+
+## Technical Specification
+
+### Data Schemas / Types
+
+N/A — no schema or type changes. All edits are string-literal or constant-reference swaps in example `main()` functions, plus corresponding comment updates.
+
+### CLI Interface
+
+README's `iris chat` invocation examples now use `gpt-5.6` in place of `gpt-4o` for the three flagship-model illustrations (basic chat, `--stream`, `--json`). The CLI itself is unchanged; these are documentation examples only.
+
+### Go Package API
+
+No exported Go API changed. Example programs now reference:
+- `xai.ModelGrok45` (`core.ModelID = "grok-4.5"`) instead of `xai.ModelGrok41FastNonReasoning` (in `xai-basic`). `xai-reasoning` keeps `xai.ModelGrok3Mini` (the model that exposes `reasoning_content`).
+- `zai.ModelGLM52` (`core.ModelID = "glm-5.2"`) instead of `zai.ModelGLM47Flash`.
+- `gemini.ModelGemini31FlashImagePreview` (`core.ModelID = "gemini-3.1-flash-image-preview"`) instead of `gemini.ModelGemini25FlashImage`.
+
+All three constants were confirmed to already exist in the corresponding `providers/*/models.go` files before use; no constant names needed correcting.
+
+### Configuration
+
+N/A — no configuration fields changed.
+
+## Usage Examples
+
+### Example: xAI basic example now uses grok-4.5
+
+```go
+// examples/chat/xai-basic/main.go (after this change)
+resp, err := client.Chat(xai.ModelGrok45).
+    User("What are the three laws of robotics?").
+    GetResponse(ctx)
+```
+
+The reasoning example (`examples/chat/xai-reasoning/main.go`) is intentionally NOT bumped: it stays on `xai.ModelGrok3Mini` because that model exposes `reasoning_content` (surfaced via `resp.Reasoning`), which the example prints.
+
+### Example: Gemini image generation now targets the 3.1 preview image model
+
+```go
+// examples/image/gemini/main.go (after this change)
+resp, err := imageGen.GenerateImage(ctx, &core.ImageGenerateRequest{
+    Model:  gemini.ModelGemini31FlashImagePreview,
+    Prompt: "A serene mountain landscape at sunset with a calm lake reflecting the colors of the sky",
+    Size:   core.ImageSize1024x1024,
+})
+```
+
+## Integration Notes
+
+- `providers/gemini/models.go` lists Gemini model series newest-first in file order and comments: "Gemini 3.6", "Gemini 3.5", "Gemini 3.1" (which includes `ModelGemini31FlashImagePreview`), then "Gemini 3" (which includes the older `ModelGemini3ProImage`, nicknamed "Nano Banana Pro" in its `DisplayName`). Despite the "Pro" naming suggesting more capability, `ModelGemini31FlashImagePreview` belongs to the newer 3.1 series and is therefore the constant this refresh selects — per the task's explicit tie-breaking rule ("prefer the newest image-generation constant that actually exists"), version series takes priority over tier name.
+- The mock-provider example's `"mock-model"` and `"any-model"` literals, and the Ollama (`llama3.2`, `qwen3`) and HuggingFace (`meta-llama/Llama-3.1-8B-Instruct`) example model strings, were deliberately left unchanged — these are either testing placeholders or represent locally-pulled/availability-varies models, not provider flagship references.
+- `examples/chat/responses-api/main.go` was left unchanged: it already uses `openai.ModelGPT56` (latest) for all Responses API calls, plus one intentional `openai.ModelGPT4o` call used specifically to contrast the Chat Completions code path against the Responses API path.
+- `examples/chat/xai-streaming/main.go` (already `xai.ModelGrok45`) and `examples/chat/zai-reasoning/main.go` (already `zai.ModelGLM52`) were already current and required no changes.
+- `examples/chat/xai-reasoning/main.go` was deliberately left on `xai.ModelGrok3Mini`: it is the model that returns `reasoning_content`, which the example demonstrates by printing `resp.Reasoning.Summary`. Bumping it to a newer model that does not expose the reasoning trace would defeat the example's purpose.
+- README's "Supported Models" / provider reference tables (OpenAI, Anthropic, xAI, Z.ai, Perplexity, Gemini, Ollama sections starting around line 850) were not touched — they were already catalog-current and are explicitly out of scope for this refresh.
+- README's Configuration section (`default_model: gpt-5.6  # or gpt-4o for older models`) was left as-is; it already shows the latest model and intentionally references `gpt-4o` as a contrasting "older model" example, not a generic flagship reference.
+
+## Breaking Changes & Migration
+
+N/A — example programs and documentation only; no public API, CLI, or configuration surface changed. Users who copy these examples will simply target newer provider models by default.
+
+## Deferred / Out of Scope
+
+- No production code changes (`core/`, `providers/*` implementation files) — only `providers/*/models.go` files were read to confirm constant names.
+- No changes to Ollama or HuggingFace example model strings, per explicit scope exclusion.
+- No changes to `examples/chat/responses-api/main.go`'s intentional `gpt-4o` comparison, or to any README "Supported Models" table.
+
+## Testing Notes
+
+- `go build ./examples/... ./...` — succeeds with no errors.
+- `go vet ./examples/...` — clean, no findings.
+- `gofmt -l examples/` — empty output (no formatting diffs).
+- Verified via `rg` that no unintended `"gpt-4o-mini"` or non-excluded `"gpt-4o"` literals remain in `examples/` or `README.md`, and that `xai.ModelGrok45`, `zai.ModelGLM52`, and `gemini.ModelGemini31FlashImagePreview` are valid, existing exported constants in their respective `providers/*/models.go` files.

examples/batch/basic/main.go

@@ -47,7 +47,7 @@ func main() {
 		{
 			CustomID: "translate-1",
 			Request: core.ChatRequest{
-				Model: "gpt-4o-mini",
+				Model: "gpt-5.4-mini",
 				Messages: []core.Message{
 					{Role: core.RoleSystem, Content: "You are a translator. Translate to French."},
 					{Role: core.RoleUser, Content: "Hello, how are you?"},
@@ -57,7 +57,7 @@ func main() {
 		{
 			CustomID: "translate-2",
 			Request: core.ChatRequest{
-				Model: "gpt-4o-mini",
+				Model: "gpt-5.4-mini",
 				Messages: []core.Message{
 					{Role: core.RoleSystem, Content: "You are a translator. Translate to Spanish."},
 					{Role: core.RoleUser, Content: "Good morning!"},
@@ -67,7 +67,7 @@ func main() {
 		{
 			CustomID: "translate-3",
 			Request: core.ChatRequest{
-				Model: "gpt-4o-mini",
+				Model: "gpt-5.4-mini",
 				Messages: []core.Message{
 					{Role: core.RoleSystem, Content: "You are a translator. Translate to German."},
 					{Role: core.RoleUser, Content: "Thank you very much."},

examples/chat/basic/main.go

@@ -38,7 +38,7 @@ func main() {
 	defer cancel()
 
 	// Send chat request using fluent builder
-	resp, err := client.Chat("gpt-4o-mini").
+	resp, err := client.Chat("gpt-5.4-mini").
 		User("What is the capital of France? Please respond in one sentence.").
 		GetResponse(ctx)
 

examples/chat/conversation-streaming/main.go

@@ -30,7 +30,7 @@ func main() {
 	client := core.NewClient(provider)
 
 	// Create a conversation with a system prompt
-	conv := core.NewConversation(client, "gpt-4o-mini",
+	conv := core.NewConversation(client, "gpt-5.4-mini",
 		core.WithSystemMessage("You are a helpful programming tutor. Keep responses concise. Remember our conversation context."),
 	)
 

examples/chat/conversation/main.go

@@ -93,7 +93,7 @@ func main() {
 	// Create conversation with system prompt
 	conv := NewConversation(
 		client,
-		"gpt-4o-mini",
+		"gpt-5.4-mini",
 		"You are a helpful programming tutor. Keep responses concise but informative. Remember the context of our conversation.",
 	)
 

examples/chat/streaming/main.go

@@ -36,7 +36,7 @@ func main() {
 	fmt.Println("---")
 
 	// Start streaming request
-	stream, err := client.Chat("gpt-4o-mini").
+	stream, err := client.Chat("gpt-5.4-mini").
 		User("Write a short poem about programming in Go. Make it 4 lines.").
 		Stream(ctx)
 

examples/chat/structured-output/main.go

@@ -42,7 +42,7 @@ func main() {
 
 	// Example 1: JSON mode - model outputs valid JSON
 	fmt.Println("=== JSON Mode ===")
-	resp, err := client.Chat("gpt-4o-mini").
+	resp, err := client.Chat("gpt-5.4-mini").
 		System("You are a helpful assistant that responds in JSON format.").
 		User("List 3 programming languages with their name, year created, creator, and a brief description.").
 		ResponseJSON().
@@ -101,7 +101,7 @@ func main() {
 		}`),
 	}
 
-	resp, err = client.Chat("gpt-4o-mini").
+	resp, err = client.Chat("gpt-5.4-mini").
 		User("Extract information: Sarah is a 28-year-old software engineer who enjoys hiking, reading, and playing chess.").
 		ResponseJSONSchema(schema).
 		GetResponse(ctx)

examples/chat/system-message/main.go

@@ -34,7 +34,7 @@ func main() {
 
 	// Example 1: Technical assistant
 	fmt.Println("=== Technical Assistant ===")
-	resp, err := client.Chat("gpt-4o-mini").
+	resp, err := client.Chat("gpt-5.4-mini").
 		System("You are a technical assistant. Provide concise, accurate answers focused on programming and technology. Use code examples when helpful.").
 		User("How do I read a file in Go?").
 		GetResponse(ctx)
@@ -48,7 +48,7 @@ func main() {
 
 	// Example 2: Friendly tutor
 	fmt.Println("=== Friendly Tutor ===")
-	resp, err = client.Chat("gpt-4o-mini").
+	resp, err = client.Chat("gpt-5.4-mini").
 		System("You are a friendly programming tutor. Explain concepts simply, as if teaching a beginner. Use analogies and encouraging language.").
 		User("How do I read a file in Go?").
 		GetResponse(ctx)
@@ -62,7 +62,7 @@ func main() {
 
 	// Example 3: Pirate personality
 	fmt.Println("=== Pirate Personality ===")
-	resp, err = client.Chat("gpt-4o-mini").
+	resp, err = client.Chat("gpt-5.4-mini").
 		System("You are a pirate programmer. Answer questions about code but speak like a pirate. Use nautical terms and pirate expressions.").
 		User("How do I read a file in Go?").
 		Temperature(0.9). // Higher temperature for more creative responses

examples/chat/xai-basic/main.go

@@ -38,8 +38,8 @@ func main() {
 	defer cancel()
 
 	// Send chat request using fluent builder
-	// Using grok-4-1-fast-non-reasoning for quick responses
-	resp, err := client.Chat(xai.ModelGrok41FastNonReasoning).
+	// Using grok-4.5 for quick responses
+	resp, err := client.Chat(xai.ModelGrok45).
 		User("What is the capital of France? Please respond in one sentence.").
 		GetResponse(ctx)