reis-mobile 0.3.6 → 0.4.0

package/skills/android-ml-kit-genai-prompt-api/references/structured-output.md

@@ -0,0 +1,219 @@
+If you need to parse the responses from the Prompt API into certain formats,
+such as JSON, for further processing, use the Structured Output API.
+
+With the Structured Output API, you define the target output structure using
+Kotlin classes and annotations. The Prompt API then returns a response in the
+form of your Kotlin object.
+
+Generating structured output is particularly useful for tasks like the
+following:
+
+- **Entity extraction**: Extracting structured fields (for example, event name, date, location) from unstructured text.
+- **Classification**: Categorizing input text into predefined categories.
+- **Data serialization**: Converting unstructured user input into a format suitable for database storage or API calls.
+
+## Prerequisites
+
+To verify that the Structured Output API is available on the device, use the
+`isStructuredOutputFeatureAvailable()` API. The API returns `true` if the
+Structured Output API is available on the device, and `false` otherwise.
+
+    suspend fun isStructuredOutputFeatureAvailable(): Boolean
+
+The Structured Output API also has the following requirements:
+
+- Android API level 26 or higher (`minSdk` 26)
+- KSP plugin version 2.3.6 or higher
+
+## Limitations
+
+The Structured Output API has the following limitations:
+
+- Works in Kotlin only.
+- ProGuard might interfere with the parsing of your annotated class. Add your annotated class to your [keep rules](https://developer.android.com/topic/performance/app-optimization/keep-rules-overview) to exclude them from ProGuard if you get errors parsing, for example:
+
+    # Keep classes used by structured output for deserialization for release builds.
+    -keep class com.google.mlkit.genai.demo.kotlin.Plant { *; }
+
+## Configure project
+
+To get started with the Structured Output API, follow these steps:
+
+1. [Add the ML Kit Prompt API as a dependency](https://developer.android.com/agents/skills/device-ai/prompt-api/references/get-started#configure-project) in your
+   app-level `build.gradle.kts` (or `build.gradle`) file, if you haven't
+   already.
+
+2. Add the KSP plugin to your project-level `build.gradle.kts` file. Use a
+   KSP plugin version that is compatible with your Kotlin version; we
+   recommend KSP version 2.3.6 or higher.
+
+       dependencies {
+           ...
+           classpath "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin:2.3.6"
+       }
+
+3. Add the structured compiler dependencies to your app-level
+   `build.gradle.kts` file:
+
+       dependencies {
+           ...
+           ksp("com.google.mlkit:genai-schema-compiler:1.0.0-alpha1")
+       }
+
+## Define the output structure
+
+Define the structure of the data you want the model to return using Kotlin
+data classes. There are two main annotations for defining the output
+structure:
+
+- Use the `@Generable` annotation to define the class as a target for structured output.
+- Use the `@Guide` annotations on the class properties to provide descriptions and constraints that guide the model's output.
+
+The following example defines a structure for extracting plant information:
+
+    import com.google.mlkit.genai.schema.annotations.Generable
+    import com.google.mlkit.genai.schema.annotations.Guide
+
+    @Generable
+    data class PlantList(
+        @Guide(description = "The list of plants found", minItems = 1, maxItems = 5)
+        val plants: List<Plant>
+    )
+
+    @Generable("Information about a plant species")
+    data class Plant(
+        @Guide(description = "The common name of the plant")
+        val commonName: String,
+        
+        @Guide(description = "The full latin scientific name of the plant")
+        val scientificName: String,
+        
+        @Guide(
+            description = "The maximum height of the plant in centimeters.",
+            minimum = 1.0,
+            maximum = 10000.0
+        )
+        val maxHeightCm: Int,
+        
+        @Guide(description = "Whether the plant is poisonous or not")
+        val isPoisonous: Boolean?,
+        
+        @Guide(
+            description = "The primary continent where this plant is native to",
+            enumValues = ["Africa", "Antarctica", "Asia", "Australia", "Europe", "North America", "South America"]
+        )
+        val nativeContinent: String
+    )
+
+### Supported types and constraints
+
+The following types are supported within a `@Generable` annotated class,
+along with their respective `@Guide` constraints:
+
+| Type | Description | Supported `@Guide` constraints |
+|---|---|---|
+| `String` | For text. | `description`, `enumValues` |
+| `Double` / `Float` | For floating-point numbers. | `description`, `minimum`, `maximum` |
+| `Int` / `Long` | For whole numbers. | `description`, `minimum`, `maximum` |
+| `Boolean` | For true/false values. | `description` |
+| `List<T>` | For lists of supported types or nested `@Generable` classes. | `description`, `minItems`, `maxItems` |
+| `List<String>` | For lists of `String` values. | `description`, `enumValues`, `minItems`, `maxItems` > [!NOTE] > **Note:** Setting the `enumValues` parameter defines the values allowed for the individual list items. |
+| `@Generable` class | For nested structured objects. | `description` |
+
+> [!NOTE]
+> **Note:** Circular dependencies between nested `@Generable` classes are not supported (for example, a class referencing itself, or Class A referencing Class B which in turn references Class A).
+
+## Generate structured content
+
+To request structured output, use the `generateTypedContentRequest` helper
+function to wrap your standard prompt and specify the target output class.
+
+    // 1. Initialize your GenerativeModel as usual
+    val generativeModel = Generation.getClient()
+
+    // 2. Prepare the prompt text
+    val promptText = "List some common plants found in California."
+    val baseRequest = GenerateContentRequest.Builder(TextPart(promptText)).build()
+
+    // 3. Create the typed request, specifying the target class (e.g., PlantList)
+    val typedRequest = generateTypedContentRequest(
+        generateContentRequest = baseRequest,
+        outputClass = PlantList::class
+    )
+
+    // 4. Run the inference
+    try {
+        val typedResponse = generativeModel.generateContent(typedRequest)
+        
+        // 5. Access the parsed object
+        // The response candidates contain the parsed object of type T (PlantList in this case)
+        val plantList: PlantList? = typedResponse.candidates.firstOrNull()?.response
+        
+        if (plantList != null) {
+            // Process the structured data
+            for (plant in plantList.plants) {
+                Log.d("StructuredOutput", "Found plant: ${plant.commonName} (${plant.scientificName})")
+            }
+        } else {
+            Log.e("StructuredOutput", "Failed to parse response into the desired structure.")
+            
+            // Inspect finish reason for details
+            val finishReason = typedResponse.candidates.firstOrNull()?.finishReason
+            Log.d("StructuredOutput", "Finish reason: $finishReason")
+        }
+    } catch (e: GenAiException) {
+        // Handle API errors
+        when (e.errorCode) {
+            GenAiException.STRUCTURED_OUTPUT_INVALID_CLASS -> {
+                Log.e("StructuredOutput", "The class structure is not supported.")
+            }
+            GenAiException.STRUCTURED_OUTPUT_INVALID_VALUE -> {
+                Log.e("StructuredOutput", "The model generated values that violate the schema constraints.")
+            }
+            else -> {
+                Log.e("StructuredOutput", "API error: ${e.message}")
+            }
+        }
+    }
+
+## Handle finish reasons and errors
+
+When using the Structured Output API, you should handle potential exceptions
+thrown by the API and inspect the `finishReason` property in the response
+candidates if the parsed response is null.
+
+### finishReason values
+
+The `finishReason` property can take one of the following values:
+
+- `TypedFinishReason.STOP`: The model finished generating successfully and the output matches the schema.
+- `TypedFinishReason.MAX_TOKENS`: The model stopped because it reached the token limit. The output might be incomplete.
+- `TypedFinishReason.PARSE_CLASS_ERROR`: The model completed generation, but the resulting JSON couldn't be parsed into the target Kotlin class.
+- `TypedFinishReason.STRUCTURE_NOT_ANNOTATED`: The target class or its nested classes are missing the required `@Generable` annotation.
+- `TypedFinishReason.STRUCTURE_VALUES_INVALID`: The generated values violated the constraints defined in the `@Guide` annotations (for example value out of range, list size out of bounds).
+- `TypedFinishReason.OTHER`: Generation stopped due to other reasons.
+
+### Exceptions
+
+The Structured Output API might throw `GenAiException` with the following
+error codes:
+
+- `GenAiException.STRUCTURED_OUTPUT_INVALID_CLASS` (-104): The structure of the annotated class is invalid or contains unsupported types. This is typically a development-time configuration error. Review your `@Generable` data class definition to check that all property types are supported and that there aren't any circular dependencies.
+- `GenAiException.STRUCTURED_OUTPUT_INVALID_VALUE` (-105): The values generated by the model are invalid or fail constraints verification. This is a runtime error. If you encounter this error frequently, consider the following solutions:
+  - Refining your prompt instructions to guide the model more strictly.
+  - Relaxing the constraints (like minimum, maximum, or list size limits) in your `@Guide` annotations if they are too restrictive for the model's capabilities.
+  - Implementing a fallback strategy in your app, such as retrying the request or displaying a default state.
+
+## Count tokens
+
+To check if your structured prompt is within the input token limit, calculate
+the token count using the [`countTokens()`](https://developer.android.com/android/reference/com/google/mlkit/genai/prompt/GenerativeModel#countTokens(com.google.mlkit.genai.prompt.GenerateContentRequest)) method.
+
+Because structured output requests need to instruct the model on the schema
+structure, counting tokens on just the raw prompt text (using a
+`GenerateContentRequest` instance) isn't accurate. To get an accurate token
+count, you must pass the complete `GenerateTypedContentRequest` instance, which
+includes your target class and schema configurations, to the `countTokens()`
+method:
+
+    suspend fun <T : Any> countTokens(request: GenerateTypedContentRequest<T>): CountTokensResponse

package/skills/android-ml-kit-genai-prompt-api/references/system-instructions.md

@@ -0,0 +1,71 @@
+System instructions let you give the model a persona, set the tone of its
+responses, or provide specific rules it must follow. These instructions are
+separate from the user's prompt and are treated with higher priority by the
+model to ensure it behaves as expected.
+
+Common use cases include:
+
+- **Setting a persona:** For example, "You are a helpful math tutor."
+- **Enforcing output format:** For example, "Always respond in bullet points."
+- **Setting constraints:** For example, "Do not answer questions about politics."
+
+## Prerequisites
+
+System instructions work on devices running Gemini Nano V3 and higher. For a
+list of supported devices, see [Prompt API device support](https://developer.android.com/ml-kit/genai#prompt-device).
+
+## Limitations
+
+We don't recommend using system instructions with
+[prefix caching](https://developer.android.com/agents/skills/device-ai/prompt-api/references/prefix-caching). In general, use system instructions for
+short instructions that define how the model should behave; use prefix
+caching if you need to repeat a large part of your prompt across queries and
+need to optimize performance.
+
+## How to use system instructions
+
+To provide system instructions, create a `SystemInstruction` object and pass it
+to the `GenerateContentRequest` builder:
+
+    import com.google.mlkit.genai.prompt.SystemInstruction
+    import com.google.mlkit.genai.prompt.TextPart
+    import com.google.mlkit.genai.prompt.generateContentRequest
+
+    // 1. Define the system instruction
+    val systemInstruction =
+        SystemInstruction("You are a concise assistant. Answer in 2 sentences or less.")
+
+    // 2. Create the request
+    val request = generateContentRequest(TextPart("How does photosynthesis work?")) {
+        this.systemInstruction = systemInstruction
+    }
+
+    // 3. Run inference
+    try {
+        val response = generativeModel.generateContent(request)
+        println(response.candidates.firstOrNull()?.text)
+    } catch (e: GenAiException) {
+        // Handle SDK-specific exceptions
+    }
+
+You can further simplify the code by passing the system instructions directly
+into the `generateContentRequest` request builder:
+
+    val request = generateContentRequest(
+        SystemInstruction("You are a pirate. Speak like one."),
+        TextPart("What is the weather like today?")
+    ) {
+        // Optional configurations like temperature
+        temperature = 0.7f
+    }
+
+## Best practices
+
+Here are some best practices when using system instructions:
+
+- **Be clear and direct:** The model follows clear, direct instructions better than ambiguous ones. Here are some examples:
+  - Vague (avoid): "Don't write too much. Try to be helpful and friendly, and format the output nicely."
+  - Clear (preferred): "You are a friendly customer support assistant. Limit your responses to a maximum of 3 sentences. Format any lists using bullet points."
+- **Be concise:** While system instructions are powerful, very long instructions can consume the model's limited context window.
+- **Factor in token counts:** Make sure that your token counting logic includes the system instructions to avoid underestimating request size. We recommend keeping your system instructions to under 150 words (100-200 tokens).
+- **Test and iterate:** Model behavior can vary based on phrasing. Test with various user inputs to ensure the model maintains its persona consistently.

package/skills/android-navigation-3/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: android-navigation-3
+description: Learn how to install and migrate to Jetpack Navigation 3, and how to
+  implement features and patterns such as deep links, multiple backstacks, scenes
+  (dialogs, bottom sheets, list-detail, two-pane, supporting pane), conditional navigation
+  (such as logged-in navigation versus anonymous), returning results from flows, integration
+  with Hilt, ViewModel, Kotlin, and view interoperability.
+license: Apache-2.0
+source: https://github.com/android/skills
+routing: manual
+stacks: [android]
+metadata:
+  author: Google LLC
+  last-updated: '2026-09-10'
+  keywords:
+  - recipe
+  - Android
+  - Navigation 2
+  - Navigation 3
+  - migration
+  - Compose
+  - guide
+  - dependencies
+  - NavKey
+  - NavHost
+  - NavDisplay
+  - BottomSheet
+  - list-detail
+  - scenes
+  - two-pane
+  - supporting pane
+  - multiple backstacks
+  - dialog
+  - Hilt
+  - ViewModel
+  - View interop.
+---
+
+*** ** * ** ***
+
+## Migration guide
+
+- *[Navigation 2 to Navigation 3 migration guide](references/android/guide/navigation/navigation-3/migration-guide.md)*: Step-by-step guide to migrate an Android application from Navigation 2 to Navigation 3, covering dependency updates, route changes, state management, and UI component replacements.
+
+### Requirements
+
+- *[Guide: Migrate to type-safe navigation in Compose](references/android/guide/navigation/type-safe-destinations.md)* : Step-by-step guide to migrating an Android application from string-based navigation to **Type-Safe Navigation** in Jetpack Compose using Jetpack Navigation 2.
+
+## Developer documentation
+
+- *[Navigation 3](references/android/guide/navigation/navigation-3/index.md)*. Search documentation for more information on basics, saving and managing navigation state, modularizing navigation code, creating custom layouts using Scenes, animating between destinations, or applying logic or wrappers to destinations.
+
+## Recipes
+
+Code examples showcasing common patterns.
+
+### Basic API usage
+
+- *[Basic](references/android/guide/navigation/navigation-3/recipes/basic.md)*: Shows most basic API usage.
+- *[Saveable back stack](references/android/guide/navigation/navigation-3/recipes/basicsaveable.md)*: Shows basic API usage with a persistent back stack.
+- *[Entry provider DSL](references/android/guide/navigation/navigation-3/recipes/basicdsl.md)*: Shows basic API usage using the entryProvider DSL.
+
+### Common UI
+
+- *[Common UI](references/android/guide/navigation/navigation-3/recipes/common-ui.md)*: Demonstrates how to implement a common navigation UI pattern with a bottom navigation bar and multiple back stacks, where each tab in the navigation bar has its own navigation history.
+
+### Deep links
+
+- *[Static URI](references/android/guide/navigation/navigation-3/recipes/deeplinks-staticuri.md)*: Shows how to handle simple static URI deep links.
+- *[URI with Arguments](https://developer.android.com/guide/navigation/navigation-3/recipes/deeplinks-uriarguments)*: Shows how to parse path and query arguments from a deep link.
+- *[Synthetic BackStack](references/android/guide/navigation/navigation-3/recipes/deeplinks-syntheticbackstack.md)*: Shows how to handle deep links with a synthetic back stack.
+- *[Custom Matcher](references/android/guide/navigation/navigation-3/recipes/deeplinks-custommatcher.md)*: Shows how to implement custom deep link matching logic.
+
+### Scenes
+
+#### Use built-in Scenes
+
+- *[Dialog](references/android/guide/navigation/navigation-3/recipes/dialog.md)*: Shows how to create a Dialog.
+
+#### Create custom Scenes
+
+- *[BottomSheet](references/android/guide/navigation/navigation-3/recipes/bottomsheet.md)*: Shows how to create a BottomSheet destination.
+- *[List-Detail Scene](references/android/guide/navigation/navigation-3/recipes/scenes-listdetail.md)*: Demonstrates how to implement adaptive list-detail layouts using the Navigation 3 Scenes API.
+- *[Two pane Scene](references/android/guide/navigation/navigation-3/recipes/scenes-twopane.md)*: Demonstrates how to implement adaptive two-pane layouts using the Navigation 3 Scenes API.
+
+### Material Adaptive
+
+- *[Material List-Detail](references/android/guide/navigation/navigation-3/recipes/material-listdetail.md)*: Demonstrates how to implement an adaptive list-detail layout using Material 3 Adaptive.
+- *[Material Supporting Pane](references/android/guide/navigation/navigation-3/recipes/material-supportingpane.md)*: Demonstrates how to implement an adaptive supporting pane layout using Material 3 Adaptive.
+
+### Animations
+
+- *[Animations](references/android/guide/navigation/navigation-3/recipes/animations.md)*: Shows how to override the default animations for all destinations and a single destination.
+- *[Conditional Transitions](references/android/guide/navigation/navigation-3/recipes/conditional-transitions.md)*: Shows how to implement conditional transition animations.
+
+### Common back stack behavior
+
+- *[Multiple back stacks](references/android/guide/navigation/navigation-3/recipes/multiple-backstacks.md)*: Shows how to create multiple top level routes, each with its own back stack. Top level routes are displayed in a navigation bar allowing users to switch between them. State is retained for each top level route, and the navigation state persists config changes and process death.
+
+### Conditional navigation
+
+- *[Conditional navigation](references/android/guide/navigation/navigation-3/recipes/conditional.md)*: Switch to a different navigation flow when a condition is met. For example, for authentication or first-time user onboarding.
+
+### Lifecycle
+
+- *[Lifecycle Owner](references/android/guide/navigation/navigation-3/recipes/lifecycle-owner.md)*: Shows how to use and observe Lifecycle in Navigation 3.
+
+### Architecture
+
+- *[Modularized navigation code (Hilt)](references/android/guide/navigation/navigation-3/recipes/modular-hilt.md)*: Demonstrates how to decouple navigation code into separate modules using Hilt or Dagger for DI.
+- *[Modularized navigation code (Koin)](references/android/guide/navigation/navigation-3/recipes/modular-koin.md)*: Demonstrates how to decouple navigation code into separate modules using Koin for DI.
+
+### Working with ViewModel
+
+#### Passing navigation arguments
+
+- *[Basic ViewModel](references/android/guide/navigation/navigation-3/recipes/passingarguments.md)* : Navigation arguments are passed to a `ViewModel` constructed using `viewModel()`
+
+### Returning results
+
+- *[Returning Results as Events](references/android/guide/navigation/navigation-3/recipes/results-event.md)* : Returning results as events to content in another `NavEntry`
+- *[Returning Results as State](references/android/guide/navigation/navigation-3/recipes/results-state.md)* : Returning results as state stored in a `CompositionLocal`

package/skills/android-navigation-3/references/android/guide/navigation/navigation-3/index.md

@@ -0,0 +1,51 @@
+## Android skills
+
+[View on GitHub](https://github.com/android/skills/tree/main/navigation/navigation-3)
+
+### Jetpack Navigation 3
+
+Use an Android skill to help you build using Jetpack Navigation 3. To install the skill from the [Android CLI](https://developer.android.com/tools/agents/android-cli), run:
+
+    android skills add navigation-3
+
+<br />
+
+Navigation 3 is a new navigation library designed to work with Compose. With
+Navigation 3, you have full control over your back stack, and you navigate to
+and from destinations by adding and removing items from a list. It creates a
+flexible app navigation system by providing:
+
+- Conventions for modeling a back stack, where each entry on the back stack represents content that the user has navigated to
+- A UI that automatically updates with back stack changes (including animations)
+- A scope for items in the back stack, allowing state to be retained while an item is in the back stack
+- An adaptive layout system that allows multiple destinations to be displayed at the same time, and allowing seamless switching between those layouts
+- A mechanism for content to communicate with its parent layout (metadata)
+
+At a high level, you implement Navigation 3 in the following ways:
+
+1. Define the content that users can navigate to in your app, each with a unique key, and add a function to resolve that key to the content. See [Resolve keys
+   to content](https://developer.android.com/guide/navigation/navigation-3/basics#resolve-keys).
+2. Create a back stack that keys are pushed onto and removed as users navigate your app. See [Create a back stack](https://developer.android.com/guide/navigation/navigation-3/basics#create-back).
+3. Use a [`NavDisplay`](https://developer.android.com/reference/kotlin/androidx/navigation3/ui/NavDisplay.composable) to display your app's back stack. Whenever the back stack changes, it updates the UI to display relevant content. See [Display
+   the back stack](https://developer.android.com/guide/navigation/navigation-3/basics#display-back).
+4. Modify `NavDisplay`'s [scene strategies](https://developer.android.com/guide/navigation/navigation-3/custom-layouts) as needed to support adaptive layouts and different platforms.
+5. [Support deep links](https://developer.android.com/guide/navigation/navigation-3/deep-links) to navigate directly to destinations.
+
+You can see the [full source code](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:navigation3/) for Navigation 3 on AOSP.
+
+## Improvements upon Jetpack Navigation
+
+Navigation 3 improves upon the original Jetpack Navigation API in the following
+ways:
+
+- Provides a simpler integration with Compose
+- Offers you full control of the back stack
+- Makes it possible to create layouts that can read more than one destination from the back stack at the same time, allowing them to adapt to changes in window size and other inputs.
+
+Read more about Navigation 3's principles and API design choices in the
+[announcement blog post](https://android-developers.googleblog.com/2025/05/announcing-jetpack-navigation-3-for-compose.html).
+
+## Code samples
+
+The [recipes repository](https://github.com/android/nav3-recipes) contains examples of how to use the
+Navigation 3 building blocks to solve common navigation challenges.