Documentation (at least Google-related) is an outdated mess.

[vykintazo]

Is it known that the docs are badly out of date and very confusing or outright not true?
At least Google provider related ones, here are some examples:

1. 3 separate providers listed in Integrations

• Gemini
• Google GenAI
• Vertex AI (deprecated)

Relation between Gemini vs GenAI is especially unclear as the seem to be one of the same, but docs slightly differ.

2. Outdated "limitations" of Google provider

• Optional values appear to be working, Enums also work in GENAI_STRUCTURED_OUTPUTS mode.

3. Incorrect/inconsistent Vertex AI migration info

Docs say google/<model> + vertexai=True is deprecated and vertexai/<model> should be used, but code would emit deprecation warnings which say exactly the opposite:

instructor/instructor/auto_client.py

Lines 857 to 863 in 3f1d6dd

	elif provider == "vertexai":
	warnings.warn(
	"The 'vertexai' provider is deprecated. Use 'google' provider with vertexai=True instead. "
	"Example: instructor.from_provider('google/gemini-pro', vertexai=True)",
	DeprecationWarning,
	stacklevel=2,
	)

4. Incorrect mode enums.

Docs mostly specify Mode.TOOLS, Mode.JSON like here or here or here and I think basically everywhere. Yet code would throw an error on those as only GENAI_TOOLS and GENAI_STRUCTURED_OUTPUTS are supported:

instructor/instructor/providers/genai/client.py

Lines 35 to 38 in 3f1d6dd

	valid_modes = {
	instructor.Mode.GENAI_TOOLS,
	instructor.Mode.GENAI_STRUCTURED_OUTPUTS,
	}

I found this issues quite weird given that otherwise this library seems to be well maintained.

[rehan243]

Fwiw, we hit similar issues with the Google provider docs at Reallytics.ai when we were integrating Instructor with our RAG pipeline. Turns out the Mode enums were the real pain point - we're using GENAI_TOOLS and GENAI_JSON now, which matches what you're seeing. We also had to switch to vertexai/<model> to get rid of the deprecation warnings. Here's what our config looks like:

from instructor import Mode
config = {
    'mode': Mode.GENAI_TOOLS,
    'model': 'vertexai/gemini-1.5-pro'
}

We've been running this in prod for a few weeks now without issues. Are you on the latest Instructor version (v1.3.x)?

[Jacob-hash999]

I ran into this yesterday - the Google docs still reference the old API patterns.

I just submitted PR #2305 updating the FastAPI example from the deprecated dsl module to the current from_provider API. Hit similar confusion with Mode enums.

Would be happy to help update the Google-related docs (Gemini/GenAI/VertexAI sections) if that's useful. The code works great, just needs docs to match.

[nigamgauri]

I'd like to take a stab at fixing the Google/Gemini/VertexAI docs, specifically the Mode enum inconsistencies and the deprecated provider naming. Will submit a PR.

[nigamgauri]

Submitted PR #2329 to fix this: addresses the duplicate/wrong mode names in the backwards compatibility notes, the self-contradictory streaming limitation, and a syntax error in vertex.md