feat(client)!: replace google-generativeai formatter with google-genai

[mikeldking]

Resolves #15040

Summary

Phoenix prompt formatting now supports only the maintained google-genai SDK. This removes the deprecated google-generativeai formatter, whose protobuf constraint conflicts with LangGraph environments requiring protobuf 6 or newer.

Breaking change

• PromptVersion.format(sdk=\"google_generativeai\") is removed.
• PromptVersion.from_google_generativeai() is removed.
• Google prompts now format through google-genai; install google-genai and call PromptVersion.format() (or pass sdk=\"google_genai\").

Changes

• Delete the legacy formatter, its canary tests, test environment, and development requirement.
• Route model_provider=\"GOOGLE\" directly to the Google Gen AI formatter.
• Update API documentation and record the migration in the client changelog.

Testing

• uvx tox run -e phoenix_client_canary_tests_sdk_google_genai
• uvx tox run -e phoenix_client -- -ra -x

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
arize-phoenix	🟢 Ready	View Preview	Aug 5, 2026, 4:01 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mikeldking]

Pushed b9c441c, which closes six conversion gaps found while reviewing the new formatter. I used the server-side converter in playground_clients.py as the reference for each, since it already handles them correctly.

Two were functional bugs I reproduced before fixing:

• Tool messages produced Content(parts=[]). tool_call/tool_result parts were skipped, so a message containing only those collapsed to empty parts, which Gemini rejects — every multi-turn tool-calling prompt would have failed at call time. These now become function_call/function_response parts, matched to the originating call by function name (Google identifies responses by name, not call id).
• Tool parameters lost anyOf/$ref/default. The hand-rolled Schema conversion turned an Optional[str] property into an empty untyped Schema(). Parameters now go through parameters_json_schema, so JSON schema passes through verbatim. The lossy direction is removed; the reverse direction is kept.

Also: thinking_config and response_format are now propagated (the latter matching the OpenAI formatter), raw tools are supported, tool_config is omitted when there are no function declarations (Google rejects it for built-in tools like google_search), and the degenerate empty Tool is gone.

I also corrected the _default_google_sdk docstring. The original rationale was wrong: the two Google SDKs co-install cleanly — it's the legacy package's protobuf<6 pin that conflicts with protobuf>=6 consumers like langgraph-cli[inmem].

One finding I deliberately left alone, since it's your call: _default_google_sdk still prefers the legacy SDK whenever it's importable, so the new path is only auto-selected when the legacy package is absent. That's what fixes the reported issue (the reporter can't install the legacy SDK), and it keeps format()'s return type stable for existing users. But google-generativeai is deprecated and its formatter is strictly worse — it never attaches tools and raises NotImplementedError on system messages — so there's a reasonable argument for flipping the default to google_genai when both are installed. That's a breaking change for anyone relying on the current default, so I didn't do it unilaterally. Happy to flip it if you'd prefer.

Tests now cover the to_google direction, which the round-trip tests structurally couldn't reach: 18 canary tests, plus strict pyright/mypy clean on the helper, tests, and prompts.py.

---

Generated by Claude Code

[mikeldking]

Flagged priority: high — @RogerHYang you're the assignee on this one, please take a review pass.

Raised during standup triage on 2026-08-10.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[mikeldking]

Pushed fe04d0d to green up Format and Lint and Clean Jupyter Notebooks, both of which were failing on the docs migration commit (eac2429).

What was broken: the migration rewrote cell 0's imports in examples/prompts/prompts_for_various_SDKs.ipynb and dropped to_chat_messages_and_kwargs, but five cells still called it — OpenAI, Anthropic, HuggingFace, Ollama, Mistral — so ruff failed with five F821s.

How I fixed it: rather than restore that import, those five cells now use prompt_version.format(variables=..., sdk=...), matching your migrated Google cell. Worth flagging why: the old helper was imported from phoenix.client.utils, which has never exported it (utils exposes only config, executors, template_formatters, etc.). So restoring the import would have satisfied ruff while leaving the cells broken at runtime — those five had been dead since before this PR. Happy to swap in a plain import restore instead if you'd rather keep the diff minimal.

I also ran ruff format/check and the notebook cleaner over both notebooks the migration touched. The import ordering (from google import genai) needed sorting in both, and neither notebook had been run through make clean-notebooks, which is what the clean gate checks. Verified the cleaner is now a no-op on both, so git diff --exit-code passes.

Confirmed locally on top of e12fdb1: ruff format --check and ruff check clean repo-wide, the 18 google_genai canary tests pass, and _to_sdk("GOOGLE") now resolves to google_genai with no dangling references to the removed legacy API anywhere in the tree.

Two notes on the earlier red checks, for the record: most of the Python CI Required failures were the aggregate gate reporting One or more CI jobs were cancelled — the test-python-${{ github.head_ref }} concurrency group cancels in-flight runs, so each rapid push superseded the previous run rather than genuinely failing. And the card-link-check failure was an external huggingface.co HTTP 500 in a docs file this PR doesn't touch; it has since gone green on its own.

---

Generated by Claude Code

[mikeldking]

@RogerHYang I've pushed two follow-up commits to keep Format and Lint green — 19baf66 (isort in tests/integration/client/test_prompts.py) and 0b5318e (an E501 in the id-less function-response guard, rewrapped so the pytest.raises(match="id, name") assertion still holds).

One request that would save us both a round trip: running make format-python && make lint-python before pushing would catch these locally. That job runs both and then git diff --exit-code, so anything the fixers would change fails the gate. Worth noting E501 in particular isn't auto-fixable — ruff check --fix won't catch it, so it needs the manual wrap.

I reviewed the conversion work in e80bcf0, 8d3d6dd, d13a1d0, f9ad471, and 31fe20e and it looks sound to me. Resolving id-less function responses by name against preceding calls is the right call — Google matches on name, and the paired NotImplementedError for a response with neither an id, a name, nor a matching prior call is better than silently emitting something Gemini would reject. Same for rejecting thought parts rather than dropping them. Verified locally on 0b5318e: 38 canary tests pass, pyright strict clean on both the helper and its tests, and both lint gates clean repo-wide.

Also flagging one stale line in the PR description, since it's now the reviewer-facing record: it says the migration is recorded in the client changelog, but 87e6f90 removed that entry on the grounds that release automation owns it.

---

Generated by Claude Code

[github-actions]

Card links check

No broken Card links found. Checked external links in 16.9s