v0.26.0

v0.26.0

Released 2026-05-12

provider is now optional everywhere. Set POTATO_HEAD_DEFAULT_PROVIDER once in your environment and omit it from every Prompt, Agent, and spec YAML. If neither an explicit provider nor the env var is present, you get a clear error pointing you at the right variable.

---

Breaking changes

None. AgentSpec.provider changed from String to Option<String> internally, but this type isn't part of the public Rust API — it's deserialized from YAML/JSON. Existing spec files with provider: set continue to work. Existing Python code passing provider= explicitly is unaffected.

---

What's new

Default provider resolution

Before this release, every Prompt(...) and Agent(...) call required provider=, and every spec YAML required a provider: key. That's fine for single-prompt scripts, annoying for services that only ever talk to one provider.

POTATO_HEAD_DEFAULT_PROVIDER fixes that. Resolution order is:

1. Explicit provider= argument (or provider: in YAML/JSON) — takes precedence over everything
2. POTATO_HEAD_DEFAULT_PROVIDER env var
3. Error: No provider specified. Pass 'provider=' explicitly or set the POTATO_HEAD_DEFAULT_PROVIDER env var.

Whitespace-only values — both explicit and env — are treated as unset, so export POTATO_HEAD_DEFAULT_PROVIDER=" " behaves the same as not setting it at all.

Python

# Before: provider required on every call
p = Prompt(messages=..., model="gpt-4o", provider="openai")
a = Agent(provider="openai")

# After: omit when POTATO_HEAD_DEFAULT_PROVIDER=openai is set
p = Prompt(messages=..., model="gpt-4o")
a = Agent()

YAML specs

# Before: provider required per agent
agents:
  - id: worker
    provider: openai
    model: gpt-4o

# After: provider optional
agents:
  - id: worker
    model: gpt-4o

YAML prompts

# provider: openai  ← can now be omitted
model: gpt-4o
messages:
  - "Summarize ${content}"

Valid values for POTATO_HEAD_DEFAULT_PROVIDER: openai, gemini, google, vertex, anthropic, google_adk. An unrecognized value raises UnknownProviderError at construction time, not silently at call time. (f7e5397, #67)

---

Upgrading from v0.25.0

No action required for existing code. To take advantage of the new behavior, set POTATO_HEAD_DEFAULT_PROVIDER in your environment and remove provider= from call sites where you want to rely on it.

If you construct AgentSpec directly in Rust, the provider field changed from String to Option<String>. Wrap existing values in Some(...).

---

Contributors

@Thorrester

Full changelog: v0.25.0...v0.26.0