[AI] support on-device structured output

[milaGGL]

This PR introduces Structured Output support on device, allowing developers to generate strongly-typed objects using ML Kit's backend. It defines the public API (GenerateObjectResponse and generateObject()), handles the necessary Kotlin Symbol Processing (KSP) logic for schema translation.

How to use On-Device Structured Output

1. Define a data class annotated with @generable (and @Guide). Note: You must provide an empty companion object so the KSP processor can generate the necessary schema extensions.
2. Call generateObject

import com.google.firebase.ai.annotations.Generable
@Generable
data class Recipe(
    val recipeName: String,
    @Guide(description = "A list of ingredients", minItems = 2)
    val ingredients: List<String>,
    @Guide(description = "Preparation time in minutes", minimum = 1.0)
    val prepTimeMinutes: Int
) {
    companion object
}

val schema = Recipe.firebaseAISchema()
val prompt = "Give me a recipe for chocolate chip cookies"

val response = model.generateObject(schema, prompt)
val recipe: Recipe? = response.getObject()
recipe?.let {
    println("Recipe: ${it.recipeName}")
    println("Ingredients: ${it.ingredients.joinToString()}")
    println("Prep time: ${it.prepTimeMinutes} mins")
}

[github-actions]

📝 PRs merging into main branch

Our main branch should always be in a releasable state. If you are working on a larger change, or if you don't want this change to see the light of the day just yet, consider using a feature branch first, and only merge into the main branch when the code complete and ready to be released.

[google-oss-bot]

	1 Warning
⚠️	Did you forget to add a changelog entry? (Add the 'no-changelog' label to the PR to silence this warning.)

Generated by 🚫 Danger

[gemini-code-assist]

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 the 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 counterproductive. 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.

[google-oss-bot]

The public api surface has changed for the subproject ai-logic_firebase-ai-ondevice-interop:
error: Added class com.google.firebase.ai.ondevice.interop.GenerateObjectResponse [AddedClass]
error: Added method com.google.firebase.ai.ondevice.interop.GenerativeModel.generateObject(com.google.firebase.ai.ondevice.interop.GenerateContentRequest,kotlin.reflect.KClass,kotlin.coroutines.Continuation<? super com.google.firebase.ai.ondevice.interop.GenerateObjectResponse>) [AddedAbstractMethod]

Please update the api.txt files for the subprojects being affected by this change by running ./gradlew ${subproject}:generateApiTxtFile. Also perform a major/minor bump accordingly.

[milaGGL]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for structured object generation (generateObject) in the on-device model interop and implementation layers, including updates to the KSP processor to generate ML Kit companion classes and support enum values in the @Guide annotation. Feedback on these changes highlights a type-safety issue in GenerateObjectResponse.kt regarding MutableList invariance, as well as an opportunity to replace unsafe non-null assertions (!!) with idiomatic safe calls in SchemaSymbolProcessorVisitor.kt.

[emilypgoogle]

Gave a quick pass and left some comments

[emilypgoogle]

Is it prudent to analyze hierarchy here? I can imagine weird issues if you wanted to use an immutable list or ArrayList or otherwise.

[milaGGL]

We can't safely rely on full hierarchy analysis here because we need to know exactly how to reconstruct the collection when generating the toSdk() map the MLkit response back to developer code. If a developer provided a custom list implementation and we just allowed it through, our KSP processor would generate invalid mapping code that fails to compile on their end.

However, I completely agree that we should support the common variants. I've just updated the KSP processor to explicitly support MutableList and ArrayList properties in @generable classes, along with the correct construction logic to convert them safely in the generated toSdk() method.

[milaGGL]

@VinayGuthal , this should be the reason.

[VinayGuthal]

why do we require changes to generateFileSpec function?

[milaGGL]

To be able to support nested Generable classes. We could have create top level shadow classes for nested classes, but there is a chance that 2 classes could have nested classes with same name, eg:

@Generable
data class User(val name: String) {
    @Generable
    data class Settings(...)
}

@Generable
data class Account(val id: String) {
    @Generable
    data class Settings(...)
}

With the original way, the 2 nested Settings could end up with name collison. but with the current changes, they would generate seperate files like User_SettingsGeneratedSchema.kt and Account_SettingsGeneratedSchema.kt.

[milaGGL]

This could be an overkill, but we can't rule out the possibility of such cases.

[milaGGL]

is it okay to hard code mlkit package name here? do we have any other type of generated classes?