fixed: Add smart fallback mechanism for model selection

[Solventerritory]

🎯 Problem Statement #493

New Google Cloud accounts created after 2024 receive 404 Not Found errors when attempting to use standard Gemini 1.5 models (gemini-1.5-flash, gemini-1.5-pro) because these accounts only have access to Gemini 2.x models:

• ✅ gemini-2.5-flash
• ✅ gemini-2.0-flash
• ✅ gemini-flash-latest
• ❌ gemini-1.5-flash (not available)
• ❌ gemini-1.5-pro (not available)

This creates a poor developer experience where:

1. Documentation and examples reference 1.5 models that don't exist for new users
2. Error messages are cryptic: [404 Not Found] models/gemini-1.5-flash is not found for API version v1beta
3. No guidance on which models to use instead
4. Developers waste hours debugging what appears to be a broken API

🚀 Solution

This PR introduces a Smart Model Fallback System that:

1. Automatic Model Discovery

• Queries available models via listModels() on first use
• Caches results to avoid repeated API calls
• Provides clear visibility into what models are accessible

2. Intelligent Fallback Chain

• If requested model is unavailable, automatically tries compatible alternatives
• Fallback priority based on capability and performance:

  gemini-1.5-flash → gemini-2.5-flash → gemini-2.0-flash → gemini-flash-latest
  gemini-1.5-pro   → gemini-2.0-flash → gemini-2.5-flash → gemini-flash-latest
  gemini-pro       → gemini-2.0-flash → gemini-2.5-flash → gemini-flash-latest
  

3. Developer-Friendly Messaging

• Console warnings when fallback is used
• Helpful error messages listing all available models
• Clear guidance for new account limitations

📦 Changes

New Files

src/utils/model-fallback.ts

• ModelFallbackManager class handles model discovery and resolution
• Maintains cache of available models
• Implements fallback priority map
• Provides detailed error messages

src/utils/smart-client.ts

• SmartGenerativeAI class - drop-in replacement for GoogleGenerativeAI
• Wraps standard SDK with smart fallback logic
• Maintains API compatibility

examples/smart-fallback-example.ts

• Demonstrates usage of SmartGenerativeAI
• Shows automatic fallback in action
• Lists available models

README-FALLBACK.md

• Comprehensive documentation
• Usage examples
• Fallback priority tables
• Guidance for new accounts

🔧 Usage

Before (throws 404 error for new accounts):

const genAI = new GoogleGenerativeAI(API_KEY);
const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });
// ❌ Error: 404 Not Found

After (automatic fallback):

const smartAI = new SmartGenerativeAI(API_KEY);
const model = await smartAI.getGenerativeModel('gemini-1.5-flash');
// ✅ Resolves to gemini-2.5-flash with console warning
// ⚠️  Model 'gemini-1.5-flash' not available. Using fallback: 'gemini-2.5-flash'

🧪 Testing

Manual Testing

# Run the example
npm run build
node examples/smart-fallback-example.ts

Expected Behavior

1. New accounts: Automatic fallback to Gemini 2.x with warning
2. Legacy accounts: Uses requested Gemini 1.5 models if available
3. Invalid models: Clear error with list of available alternatives

Test Cases

• ✅ Request unavailable 1.5 model → falls back to 2.x
• ✅ Request available model → uses requested model
• ✅ Request invalid model → throws helpful error
• ✅ Cache prevents repeated API calls
• ✅ Fallback warnings appear in console

🎁 Benefits

1. Zero Breaking Changes: Optional wrapper, existing code unaffected
2. Improved DX: New developers can start immediately without debugging 404s
3. Future-Proof: Handles model availability changes gracefully
4. Self-Documenting: Console output explains what's happening
5. Minimal Overhead: Model discovery cached after first call

📊 Impact

Before This PR

• ❌ New developers hit 404 wall immediately
• ❌ Hours wasted debugging "broken" API
• ❌ Confusion about which models to use
• ❌ Silent failures or cryptic errors

After This PR

• ✅ Automatic resolution to working models
• ✅ Clear warnings when fallback occurs
• ✅ Helpful error messages with alternatives
• ✅ Smooth onboarding for new accounts

🔮 Future Enhancements

• Add configuration for custom fallback chains
• Support for regional model availability
• Metrics/telemetry for fallback usage
• Integration with model pricing/quota information
• Automatic model version updates

📝 Related Issues

Fixes: #[issue-number] - 404 errors for new Google Cloud accounts with Gemini 1.5 models

✅ Checklist

• Code follows project style guidelines
• New utility classes are well-documented
• Example demonstrates usage clearly
• README documentation added
• Manual testing completed
• Unit tests added (if applicable)
• Integration tests added (if applicable)
• No breaking changes to existing API

🙋 Questions for Reviewers

1. Should we make this the default behavior or keep it as an optional wrapper?
2. Do we need additional fallback models in the priority chain?
3. Should we add metrics to track fallback usage?
4. Is the console warning verbosity appropriate?

📸 Demo Output

Requesting gemini-1.5-flash...
Available models: gemini-2.5-flash, gemini-2.0-flash, gemini-flash-latest
⚠️  Model 'gemini-1.5-flash' not available. Using fallback: 'gemini-2.5-flash'

Response: Code flows like streams,
Bugs dance in moonlit dreams,
Debug, compile, gleam.

--- Listing all available models ---
- models/gemini-2.5-flash
- models/gemini-2.0-flash
- models/gemini-flash-latest

---

Type: Enhancement
Priority: High (affects new user onboarding)
Backward Compatibility: 100% (opt-in feature)

[gemini-code-assist]

Summary of Changes

Hello @Solventerritory, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a "Smart Model Fallback System" to address the 404 Not Found errors encountered by new Google Cloud accounts when trying to access Gemini 1.5 models. The system automatically discovers available Gemini 2.x models and intelligently falls back to compatible alternatives, significantly improving the developer experience by providing seamless model resolution and clear guidance.

Highlights

• Automatic Model Discovery: The system now queries available models via listModels() on first use and caches the results to avoid repeated API calls, providing clear visibility into accessible models.
• Intelligent Fallback Chain: If a requested model is unavailable, the system automatically tries compatible alternatives based on a defined priority, such as gemini-1.5-flash falling back to gemini-2.5-flash, then gemini-2.0-flash, and finally gemini-flash-latest.
• Developer-Friendly Messaging: Console warnings are issued when a fallback is used, and helpful error messages are provided, listing all available models and offering clear guidance for new account limitations.
• Improved Developer Experience: This feature resolves 404 Not Found errors for new Google Cloud accounts attempting to use Gemini 1.5 models, ensuring a smoother onboarding process without introducing breaking changes to existing code.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This is a great initiative to improve the developer experience for new users facing issues with model availability. The fallback mechanism is well-thought-out and the wrapper class SmartGenerativeAI makes it easy to adopt.

I've identified a few areas for improvement to make this feature more robust and polished:

• Exporting the new class: The new SmartGenerativeAI class needs to be exported from the main package entry point to be accessible to users.
• Caching for listModels: The listModels method in SmartGenerativeAI currently doesn't leverage the caching mechanism, making it inefficient.
• Testing: Adding unit tests for the ModelFallbackManager would be valuable to ensure the fallback logic is correct and to prevent future regressions.
• Code cleanup: There are some minor code cleanup opportunities, like removing unused code and avoiding direct console logging from the library.

My detailed comments are below. Great work on this feature!