Skip to content

feat: Add Firebase AI provider with comprehensive features #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
bagintz wants to merge 9 commits into
base: main
Choose a base branch
from
Open

feat: Add Firebase AI provider with comprehensive features #63

bagintz wants to merge 9 commits into from

Conversation

@bagintz
Copy link

@bagintz bagintz commented Oct 10, 2025 •
edited
Loading

Overview

This PR introduces a comprehensive Firebase AI provider implementation for the dartantic_ai ecosystem, providing seamless integration with Google's Gemini models through Firebase.

Key Features

🔥 Dual Backend Support

  • Google AI Backend: Simplified setup for development and prototyping
  • Vertex AI Backend: Production-ready infrastructure with enterprise features

⚡ Complete dartantic Compliance

  • Full provider pattern implementation following unified architecture
  • Comprehensive error handling with thinking metadata
  • Proper logging integration with context preservation
  • Standardized test coverage with proper headers
  • Model configuration compliance with string format support

🛠 Rich Functionality

  • Streaming and non-streaming chat completions
  • Advanced tool calling capabilities
  • Multi-turn conversation support
  • Flexible model configuration
  • Usage tracking and monitoring

Implementation Highlights

Provider Architecture

  • Clean separation of concerns with proper abstraction layers
  • Backend-agnostic implementation allowing easy switching between Google AI and Vertex AI
  • Comprehensive error handling with proper exception types and recovery mechanisms

Testing Infrastructure

  • 204 comprehensive tests covering all functionality
  • Tests require flutter test (not dart test) due to Flutter framework dependencies
  • Complete coverage of streaming, tool calling, error scenarios, and configuration options

Documentation & Setup

  • Comprehensive README with setup instructions for both backends
  • Firebase AI test application demonstrating all features
  • Test execution guide explaining Flutter test requirements
  • Troubleshooting documentation for common setup issues

Files Added/Modified

Core Implementation

  • packages/dartantic_firebase_ai/ - Complete provider package
  • packages/dartantic_firebase_ai/lib/src/firebase_ai_provider.dart - Main provider implementation
  • packages/dartantic_firebase_ai/test/ - Comprehensive test suite (204 tests)

Documentation

  • packages/dartantic_firebase_ai/README.md - Provider documentation
  • packages/dartantic_firebase_ai/TEST_EXECUTION.md - Test execution guide
  • Firebase AI test app with setup documentation

Testing

All tests pass successfully:

cd packages/dartantic_firebase_ai
flutter test
# Output: 00:02 +204: All tests passed!

Note: Tests must be run with flutter test rather than dart test due to Flutter framework dependencies in the firebase_ai package.

Compliance Verification

This implementation has been verified against all dartantic standards:

✅ Provider Patterns: Full unified provider architecture compliance
✅ Test Headers: All test files include proper standardized headers
✅ Thinking Metadata: Error handling includes contextual thinking information
✅ Error Handling: Comprehensive exception handling with proper types
✅ Model Configuration: Support for both object and string-based model specs
✅ Logging Architecture: Proper logging integration with context preservation

Backend Configuration

Google AI (Development)

Providers.providerMap['firebase_dev'] = FirebaseAIProvider(
  backend: FirebaseAIBackend.googleAI,
);

Vertex AI (Production)

Providers.providerMap['firebase'] = FirebaseAIProvider();
// Uses Vertex AI backend by default

Ready for Review

This implementation is production-ready with:

  • Complete feature parity with other dartantic providers
  • Comprehensive test coverage
  • Full documentation
  • Demonstrated functionality
  • Standards compliance verification

bagintz added 6 commits October 8, 2025 22:33
@bagintz
feat: Complete Firebase AI provider with comprehensive enhancements
3345814 
🚀 Added full Firebase AI provider implementation with advanced features:

## Core Provider
- firebase_ai_provider.dart: Enhanced error handling & validation
- firebase_ai_chat_model.dart: Complete chat model with streaming
- firebase_ai_chat_options.dart: Comprehensive configuration options
- firebase_message_mappers.dart: Firebase AI message conversion

## Advanced Features
- firebase_ai_streaming_accumulator.dart: Advanced streaming with metadata
- firebase_ai_thinking_utils.dart: Thinking/reasoning mode utilities
- firebase_ai_multimodal_utils.dart: Multi-modal validation & optimization

## Documentation & Examples
- ADVANCED_USAGE.md: 400+ lines comprehensive documentation
- firebase_ai_demo.dart: Simple demo following repo patterns
- Complete test suite with mocked Firebase dependencies

## Key Capabilities
✅ Enhanced error handling with Firebase-specific validation
✅ Advanced streaming with accumulation and metadata handling
✅ Thinking/reasoning mode implementation
✅ Multi-modal support (images, audio, video, documents)
✅ Comprehensive documentation and examples
✅ Production-ready with proper logging and validation

All 6 enhancement areas completed for maintainer review.
Ready for dart fix auto-cleanup and integration.
@bagintz
refactor: Apply dart fix auto-improvements
e50be46 
- Fixed 146 style and formatting issues automatically
- Reduced total linting issues from 242 to 97
- Improved code consistency with proper const usage
- Fixed string escaping and interpolation issues
- Applied proper variable scoping (final locals)

Remaining issues are mostly acceptable (example print statements,
minor line length, missing docs for utility enums).
@bagintz
feat: Complete Firebase AI provider compliance with dartantic standards
f67bd52 
- Provider Implementation Pattern: Restructured constructor with proper logger placement, baseUrl parameter handling
- Test Headers & Philosophy: Added mandatory testing philosophy headers to all test files
- Thinking Metadata: Integrated thinking extraction and streaming via ChatResult.metadata['thinking']
- Error Handling: Verified 'Don't Swallow Errors' compliance across all components
- Model Configuration: Added comprehensive validation tests for gemini patterns and defaults
- Logging Architecture: Implemented hierarchical logging (dartantic.chat.providers.firebase_ai, etc.)
- Additional test coverage: Added unit tests for all utility components
- Documentation: Updated providers.mdx with Firebase AI capabilities
- Build: Added coverage/ and ai_notes/ to .gitignore for cleaner repo

All 200+ tests passing with full compliance verification complete.
@bagintz
Merge remote-tracking branch 'origin/main' into firebase-ai-provider-v2
51767f1
@bagintz
docs: Add test execution guide for Firebase AI provider
c9af691 
- Documents requirement for flutter test vs dart test
- Explains Flutter dependency requirements
- Provides CI/CD guidance for proper test execution
- All 204 tests confirmed passing with flutter test
@bagintz
fix: Correct .gitignore configurations
ee8e0fe 
- Restore packages/dartantic_ai/example/.env to main .gitignore
- Remove duplicate example/.env from firebase_ai package .gitignore
- Maintain proper separation of package-specific ignores
csells
csells reviewed Oct 10, 2025
View reviewed changes
csells
csells reviewed Oct 10, 2025
View reviewed changes
csells
csells reviewed Oct 10, 2025
View reviewed changes
@csells
Copy link
Owner

csells commented Oct 10, 2025

Love this, @bagintz ! Some comments for you.

@bagintz
feat: Update Firebase AI provider naming to address Chris Sells' feed…
ade971c 
…back

- Change provider aliases from 'firebase'/'firebase_dev' to 'firebase-vertex'/'firebase-google'
- Clarify Firebase project requirements in README:
  - Google AI backend: No Firebase project needed, just API key
  - Vertex AI backend: Requires full Firebase project setup
- Add Flutter dependency clarification - package requires Flutter, not just Dart
- Update all examples and tests to use new naming convention
- Add comparison table showing dependencies and requirements

Addresses feedback from PR review: csells#63
@bagintz
docs: Correct Firebase project requirements based on testing
0ce4826 
- Both Google AI and Vertex AI backends require Firebase.initializeApp()
- Both require Firebase project configuration (even if minimal)
- Both require Flutter SDK, not just Dart
- Key difference: Google AI routes to Gemini Developer API, Vertex AI routes through Firebase infrastructure
- Verified through official Firebase documentation and test attempts

This corrects the previous misconception that Google AI backend doesn't need Firebase setup.
@csells csells mentioned this pull request Oct 13, 2025
Open
@bagintz
docs(firebase-ai): Remove incorrect on-device inference claims
54e75dd 
Research confirmed on-device inference is only available for web apps
via Firebase AI Logic, not for Flutter mobile apps.

Changes:
- Removed 'Hybrid On-Device Inference' section with non-existent InferenceMode
- Removed inferenceMode from configuration options list
- Updated comparison table: 'Yes (preview)' -> 'No (web only)'
- Added note with official Firebase documentation link

Sources:
- https://firebase.blog/posts/2025/06/hybrid-inference-firebase-ai-logic/
- https://firebase.blog/posts/2025/10/understand-ai-logic-hybrid-inference

Resolves csells' review comment asking for sample/documentation.
csells
csells requested changes Oct 19, 2025
View reviewed changes
@csells
Copy link
Owner

csells commented Oct 20, 2025

Thanks for this, @bagintz!

Let me get the underlying PR landed (waiting on Google -- hopefully this week) and then we'll get this one landed, too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@csells csells csells requested changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@bagintz @csells