[Feature] Add Microsoft.Maui.Essentials.AI - Android / Gemini Nano

[mattleibow]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Important

This PR is huge because it is based on 2 PRs, one of which is the main part of the code.
The true diff is dev/alt-main...dev/ai-android

Description

This PR adds Android Gemini Nano (MLKit GenAI) support to Microsoft.Maui.Essentials.AI, enabling on-device AI chat capabilities through the Microsoft.Extensions.AI abstractions on Android.

What's Added

Android Gemini Nano Integration

GeminiNanoChatClient - Full IChatClient implementation for Google MLKit GenAI:

Feature	Description
Synchronous Responses	GetResponseAsync() for complete responses
Streaming Responses	GetStreamingResponseAsync() returns IAsyncEnumerable<ChatResponseUpdate> for real-time UI updates
Singleton Model	Default constructor uses Generation.Instance.Client singleton
Custom Model Support	Constructor overload accepts existing IGenerativeModel
Cancellation Support	Full CancellationToken support via Android CancellationSignal
Middleware Compatible	Works with IChatClient pipeline builders (.AsBuilder().UseLogging().Build())

Extension Methods:

• IGenerativeModel.AsIChatClient() - Wrap existing IGenerativeModel as IChatClient

Internal C# Extensions:

• GenerativeModelExtensions - Async wrappers converting Kotlin coroutines to C# Task-based patterns
  • GenerateContentAsync() - Non-streaming content generation
  • GenerateContentStreamAsync() - Streaming content generation as IAsyncEnumerable
  • CheckStatusAsync() - Model availability check
  • WarmupAsync() - Model warmup for better first-response latency

---

Capabilities

Feature	Status	Notes
Chat Completion	✅ Supported	Full non-streaming via GetResponseAsync()
Streaming Responses	✅ Supported	IAsyncEnumerable<ChatResponseUpdate> via Kotlin Flow bridge
Text Embeddings	❌ Not Available	MLKit GenAI doesn't expose embedding API; use cloud services
Function/Tool Calling	❌ Not Supported	Not available in Gemini Nano
Structured JSON Output	❌ Not Supported	Not available in Gemini Nano
System Prompts	✅ Supported	Via PromptPrefix in GenerateContentRequest
Multi-turn Conversation	⚠️ Flattened	Messages concatenated into single TextPart
Image Input	✅ Supported	Single image via DataContent → ImagePart (one per request)
Temperature	✅ Supported	Via GenerateContentRequest.Builder.Temperature
TopK	✅ Supported	Via GenerateContentRequest.Builder.TopK
TopP	❌ Not Supported	Not exposed by MLKit GenAI
Seed	✅ Supported	Via GenerateContentRequest.Builder.Seed
Max Output Tokens	❌ Not Supported	Not exposed by MLKit GenAI
Cancellation	✅ Supported	Via Android CancellationSignal

Note: The sample app uses OpenAI for embeddings on Android since Gemini Nano doesn't provide a local embedding API.

---

Architecture: Kotlin Native Layer & C# Integration

The Gemini Nano integration uses a two-layer architecture to bridge .NET with Google's Kotlin coroutine-based MLKit GenAI:

┌─────────────────────────────────────────────────────────────────┐
│                    .NET MAUI Application                        │
│                        IChatClient                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   C# Layer (Essentials.AI)                      │
│  GeminiNanoChatClient : IChatClient                             │
│  • Implements Microsoft.Extensions.AI abstractions              │
│  • Converts ChatMessage → GenerateContentRequest                │
│  • Uses GenerativeModelExtensions for async operations          │
│  GenerativeModelExtensions                                      │
│  • Task-based wrappers calling Kotlin listener interfaces       │
│  • IAsyncEnumerable streaming via Channel<T>                    │
└─────────────────────────────────────────────────────────────────┘
                              │ (Java Binding)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                Kotlin Layer (AndroidNative)                     │
│  GenerativeModelExtensions.kt                                   │
│  • Extension functions for GenerativeModel                      │
│  • Bridges Kotlin coroutines → CancellationSignal + listeners   │
│  Listener Interfaces                                            │
│  • ContentGenerationListener (non-streaming)                    │
│  • StreamContentGenerationListener (streaming)                  │
│  • ModelStatusListener, ModelWarmupListener                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              Google MLKit GenAI (Gemini Nano)                   │
│  com.google.mlkit.genai.prompt.GenerativeModel                  │
└─────────────────────────────────────────────────────────────────┘

Why Kotlin is Required:

• MLKit GenAI uses Kotlin coroutines (suspend functions, Flow<T>)
• No direct Java/C# API for async operations
• Kotlin extension functions provide callback-based bridge for C# consumption

Layer Responsibilities:

Layer	Responsibility
C# (GeminiNanoChatClient)	IChatClient implementation, message conversion, response mapping
C# (GenerativeModelExtensions)	Task/IAsyncEnumerable wrappers using Kotlin listeners
Kotlin (GenerativeModelExtensions.kt)	Coroutine → CancellationSignal + listener bridge
Kotlin (Listener interfaces)	Callback contracts for C# to implement

---

Why

1. Unified AI API: Same IChatClient abstractions work with cloud AI (OpenAI, Azure) or on-device (Gemini Nano, Apple Intelligence, Windows Copilot Runtime)

2. On-Device Privacy: Gemini Nano runs entirely on-device, keeping user data private

3. Cross-Platform Parity: Android developers get the same AI capabilities as Apple and Windows platform developers

---

Native Library Build

The Kotlin native library is located at src/AI/src/AndroidNative/:

AndroidNative/
├── build.gradle
├── settings.gradle
├── gradle.properties
├── gradlew / gradlew.bat
└── essentialsai/
    ├── build.gradle
    └── src/main/kotlin/com/microsoft/maui/essentials/ai/
        ├── GenerativeModelExtensions.kt
        ├── ContentGenerationListener.kt
        ├── StreamContentGenerationListener.kt
        ├── ModelStatusListener.kt
        └── ModelWarmupListener.kt

Build with: ./gradlew :essentialsai:assembleRelease

---

Public API Surface

Namespace: Microsoft.Maui.Essentials.AI

// Android Gemini Nano Chat Client
public sealed class GeminiNanoChatClient : IChatClient
{
    public GeminiNanoChatClient();
    public GeminiNanoChatClient(IGenerativeModel model);
    public ChatClientMetadata Metadata { get; }
    public Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default);
    public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default);
}

public static class GeminiNanoExtensions
{
    public static IChatClient AsIChatClient(this IGenerativeModel model);
}

Usage Examples:

// Chat with Gemini Nano
var chatClient = new GeminiNanoChatClient();

// Simple response
var response = await chatClient.GetResponseAsync([new ChatMessage(ChatRole.User, "Hello!")]);

// Streaming response
await foreach (var update in chatClient.GetStreamingResponseAsync(messages))
{
    Console.Write(update.Text); // Progressive output
}

// With middleware pipeline
var client = new GeminiNanoChatClient()
    .AsBuilder()
    .UseLogging(loggerFactory)
    .Build();

// From existing IGenerativeModel
var model = Generation.Instance.Client;
var chatClient = model.AsIChatClient();

---

Sample App Changes

The Essentials.AI.Sample now automatically uses:

• Android: Gemini Nano for chat (on-device) + OpenAI for embeddings (cloud)
• Other platforms: OpenAI (cloud)

This is configured via conditional compilation in MauiProgram.cs.

---

Requirements

• Android device with Gemini Nano support (Pixel 8+, Samsung Galaxy S24+, etc.)
• Google Play Services with MLKit GenAI
• Model must be downloaded before use (handled by MLKit)

---

Files Changed

Category	Files	Description
C# Implementation	3	GeminiNanoChatClient, Extensions, GenerativeModelExtensions
Kotlin Native	5	Extension functions and listener interfaces
Gradle Build	7	Build configuration, wrapper, properties
Sample	1	MauiProgram.cs with Android-specific DI
Public API	1	PublicAPI.Unshipped.txt
Bindings	1	Metadata.xml transforms

Total: 23 files changed, +1094/-2 lines

[kubaflo]

/review -b feature/refactor-copilot-yml

[kubaflo]

/review -b feature/enhanced-reviewer -p android

[MauiBot]

⚠️ Merge Conflict Detected — This PR has merge conflicts with its target branch. Please rebase onto the target branch and resolve the conflicts.