reis-mobile 0.3.6 → 0.5.0

package/skills/mobile-android/references/on-device-ai/ml-kit-genai-prompt-api/references/prefix-caching.md

@@ -0,0 +1,146 @@
+> [!NOTE]
+> **Note:** Prefix caching is experimental and may change in the future. This feature is only available on a subset of the supported devices for Prompt API, with support for more devices coming soon. We encourage you to experiment with this API on a Pixel device to understand how it can improve inference latency speeds for your specific use case.
+
+*Prefix caching* is a feature that reduces inference time by storing and reusing
+the intermediate LLM state of processing a shared and recurring prompt prefix
+part. To enable prefix caching, you only have to separate the static prefix from
+the dynamic suffix in your API request.
+
+Prefix caching currently only supports text-only input, so you shouldn't use
+this feature if you're providing an image in your prompt.
+
+There are two approaches to implement prefix caching: implicit or explicit:
+
+- [Implicit (automatic) prefix caching](https://developer.android.com/agents/skills/device-ai/ml-kit-genai-prompt-api/references/prefix-caching#implicit) is a lightweight approach where the application only needs to define a shared portion of the prompt.
+- [Explicit (manual) prefix caching](https://developer.android.com/agents/skills/device-ai/ml-kit-genai-prompt-api/references/prefix-caching#explicit) allows applications to have more control over caches, including cache creation, querying, and deletion.
+
+## Use prefix caching implicitly
+
+To enable prefix caching, add the shared portion of the prompt to the
+`promptPrefix` field, as shown in the following code snippets:
+
+### Kotlin
+
+    val promptPrefix = "Reverse the given sentence: "
+    val dynamicSuffix = "Hello World"
+
+    val result = generativeModel.generateContent(
+      generateContentRequest(TextPart(dynamicSuffix)) {
+        promptPrefix = PromptPrefix(promptPrefix)
+      }
+    )
+
+### Java
+
+    String promptPrefix = "Reverse the given sentence: ";
+    String dynamicSuffix = "Hello World";
+
+    GenerateContentResponse response = generativeModelFutures.generateContent(
+        new GenerateContentRequest.Builder(new TextPart(dynamicSuffix))
+        .setPromptPrefix(new PromptPrefix(promptPrefix))
+        .build())
+        .get();
+
+In the preceding snippet, the `dynamicSuffix` is passed as the main content, and
+the `promptPrefix` is provided separately.
+
+### Estimated performance gains
+
+|---|---|---|
+|   | **Without prefix caching** | **With prefix cache-hit** (Prefix cache-miss may occur when prefix is used for the first time) |
+| Pixel 9 with 300-token fixed prefix and a 50-token dynamic suffix prompt | 0.82 seconds | 0.45 seconds |
+| Pixel 9 with a 1,000-token fixed prefix and a 100-token dynamic suffix prompt | 2.11 seconds | 0.5 seconds |
+
+### Storage considerations
+
+With implicit prefix caching, cache files are saved on the client application's
+private storage, which increases your app's storage usage. Encrypted cache files
+and their associated metadata, including original prefix text, are stored. Keep
+the following storage considerations in mind:
+
+- The number of caches is managed by an LRU (Least Recently Used) mechanism. Least used caches are deleted automatically when exceeding the max total cache amount.
+- Prompt cache sizes are dependent on the length of the prefix.
+- To clear all caches created from prefix caching, use the
+  [`generativeMode.clearImplicitCaches()`](https://developer.android.com/android/reference/kotlin/com/google/mlkit/genai/prompt/GenerativeModel#clearCaches%28%29) method.
+
+  > [!NOTE]
+  > **Note:** The `clearImplicitCaches()` method is experimental and may change in the future.
+
+## Use explicit cache management
+
+The Prompt API includes explicit cache management methods to give developers
+more precise control over how caches are created, searched, used, and removed.
+These manual operations run independently of the system's automated cache
+handling.
+
+This example illustrates how to initialize explicit cache management and
+perform inference:
+
+### Kotlin
+
+    val cacheName = "my_cache"
+    val promptPrefix = "Reverse the given sentence: "
+    val dynamicSuffix = "Hello World"
+
+    // Create a cache
+    val cacheRequest = createCachedContextRequest(cacheName, PromptPrefix(promptPrefix))
+    val cache = generativeModel.caches.create(cacheRequest)
+
+    // Run inference with the cache
+    val response = generativeModel.generateContent(
+      generateContentRequest(TextPart(dynamicSuffix)) {
+        cachedContextName = cache.name
+      }
+    )
+
+### Java
+
+    String cacheName = "my_cache";
+    String promptPrefix = "Reverse the given sentence: ";
+    String dynamicSuffix = "Hello World";
+
+    // Create a cache
+    CachedContext cache = cachesFutures.create(
+      new CreateCachedContextRequest.Builder(cacheName, new PromptPrefix(promptPrefix))
+      .build())
+      .get();
+
+    // Run inference with the cache
+    GenerateContentResponse response = generativeModelFutures.generateContent(
+      new GenerateContentRequest.Builder(new TextPart(dynamicSuffix))
+      .setCachedContextName(cache.getName())
+      .build())
+      .get();
+
+This example demonstrates how to query, retrieve, and delete explicitly managed
+caches using `generativeModel.caches`:
+
+### Kotlin
+
+    val cacheName = "my_cache"
+
+    // Query pre-created caches
+    for (cache in generativeModel.caches.list()) {
+      // Do something with cache
+    }
+
+    // Get specific cache
+    val cache = generativeModel.caches.get(cacheName)
+
+    // Delete a pre-created cache
+    generativeModel.caches.delete(cacheName)
+
+### Java
+
+    String cacheName = "my_cache";
+
+    // Query pre-created caches
+    for (PrefixCache cache : cachesFutures.list().get()) {
+      // Do something with cache
+    }
+
+    // Get specific cache
+    PrefixCache cache = cachesFutures.get(cacheName).get();
+
+    // Delete a pre-created cache
+    cachesFutures.delete(cacheName);

package/skills/mobile-android/references/on-device-ai/ml-kit-genai-prompt-api/references/prompt-design.md

@@ -0,0 +1,55 @@
+When using Prompt API, there are specific strategies you can use to tailor your
+prompts and receive optimal results. This page describes best practices for
+formatting prompts for Gemini Nano.
+
+For more general prompt engineering guidance, see [Prompt Engineering
+whitepaper](https://www.kaggle.com/whitepaper-prompt-engineering), [Prompt Engineering for Generative
+AI](https://developer.android.com/machine-learning/resources/prompt-eng), and [Prompt design strategies](https://ai.google.dev/gemini-api/docs/prompting-strategies).
+
+Alternatively, to automatically refine and improve prompts, you can use the
+[zero-shot optimizer](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/zero-shot-optimizer#optimizing_for_smaller_models), which can target on-device models such as
+`gemma-3n-e4b-it`.
+
+## Prompt design best practices
+
+When designing prompts for Prompt API, use the following techniques:
+
+- **Provide examples for in-context learning**. Add well-distributed examples to
+  your prompt to show Gemini Nano the kind of result you expect.
+
+  Consider using the [prefix caching](https://developer.android.com/agents/skills/device-ai/prompt-api/references/prefix-caching) feature when you use in-context
+  learning, as providing examples makes the prompt longer and increases
+  inference time.
+- **Be concise** . Verbose preambles with repeated instructions can produce
+  suboptimal results. Keep your prompt focused and to-the-point. If you need to
+  repeat a short directive that guides the model's behavior, consider using
+  [system instructions](https://developer.android.com/agents/skills/device-ai/prompt-api/references/system-instructions).
+
+- **Structure prompts** to generate more effective responses, such as this
+  [sample prompt template](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/prompt-design-strategies#sample-prompt-template) that clearly defines instructions,
+  constraints, and examples.
+
+- **Keep output short** . LLM inference speeds are heavily dependent on the
+  output length. Carefully consider how you can generate the shortest possible
+  output for your use case and do manual post-processing to structure the output
+  in the chosen format. To help ensure that the response output is in your
+  preferred format, use the [Structured Output API](https://developer.android.com/agents/skills/device-ai/prompt-api/references/structured-output).
+
+- **Add delimiters** . Use delimiters like `<background_information>`,
+  `<instruction>`, and `##` to create separation between different parts of your
+  prompt. Using `##` between components is particularly critical for Gemini
+  Nano, as it significantly reduces the chances of the model failing to
+  correctly interpret each component.
+
+- **Prefer simple logic and a more focused task** . If you find it challenging
+  to achieve good results with a prompt requiring multi-step reasoning (for
+  example, *do X first, if the result of X is A, do M; otherwise do N;
+  then do Y...* ), consider breaking the task up and let each Gemini Nano call
+  handle a more focused task, while using code to chain multiple calls together.
+  If you do need to tackle a complex, reasoning-intensive task all at once,
+  consider using [thinking mode](https://developer.android.com/ml-kit/genai/prompt/android/thinking-mode).
+
+- **Use lower temperature values for deterministic tasks** . For tasks such as
+  entity extraction or translation that don't rely on creativity, consider
+  starting with a `temperature` value of `0.2`, and tune this value based on
+  your testing.

package/skills/mobile-android/references/on-device-ai/ml-kit-genai-prompt-api/references/prompt-optimization.md

@@ -0,0 +1,74 @@
+This skill provides guidance on how to optimize prompts for use with the ML Kit
+Prompt API.
+
+## Guidelines \& Rules
+
+The best practices for prompt design for Prompt API are at
+[Prompt Design](https://developer.android.com/agents/skills/device-ai/prompt-api/references/prompt-design). Apply these core rules:
+
+- Include examples for in-context learning with examples of the output. This is an example prompt that includes in-context learning because it has examples of the desired model output: Analyze the message and return whether the customer sentiment is positive, negative, or neutral. Example 1: Input - "This product doesn't work"; Output - "Negative" Example 2: Input - "I liked this product"; Output - "Positive"
+- Make prompts concise. Remove duplicate or repeated instructions. Do not include conversational filler such as: hello, please, do this, help me with, etc. For example, a verbose prompt such as: "Hello! I want you to act as an expert translator for me today. I am going to give you a short paragraph of text in English, and I would really like it if you could translate it into formal, high-level Business French. Please make sure that you do not include any intro like 'Here is your translation' or any closing remarks at all. Just output the translation itself." can be improved with this concise prompt: "Translate to formal Business French. Return ONLY the translation"
+- Use paired XML/HTML delimiters to denote dynamic inputs (for example `<email>[content]</email>`) to clearly isolate user data from prompt instructions. Mention that the delimiters represent placeholder text that should be replaced by code in the actual implementation.
+- Use the [Structured Output API](https://developer.android.com/agents/skills/device-ai/prompt-api/references/structured-output) if the output requires parsing responses into certain formats. Don't include the Structured Output API implementation in the prompt itself, but mention it after presenting the optimized prompt to the user so the user knows how to parse the model output. Prompts that use Structured Output API must return the `@Generable` typed object from the function signature instead of a string or JSON string.
+- Keep output short by adding output constraints such as word count, character count, or number of bullets or sentences. For example, add constraints such as "The summarization must be 10 words or fewer."
+- Use [system instructions](https://developer.android.com/agents/skills/device-ai/prompt-api/references/system-instructions) for short instructions that define how a model should behave, and use [prefix caching](https://developer.android.com/agents/skills/device-ai/prompt-api/references/prefix-caching) for prompts that are over 200 words.
+
+## Examples
+
+Here are examples of prompts that the user might ask you to optimize, and the
+improved, optimized versions.
+
+### Example 1
+
+Unoptimized prompt:
+
+    Process this customer email and return the order ID, what was bought, the phone
+    number, and what they want. Format it as JSON so my app can read it.
+
+Optimized prompt:
+
+    ## Task
+
+    Extract key details from the customer email below.
+
+    ## Customer Email
+
+    <email>
+    [email_content]
+    </email>
+
+Explanation: Because the information that the user wants to extract using the
+prompt is well suited for the Structured Output API, the optimized prompt
+implicitly uses the Structured Output API and doesn't need to explicitly define
+the schema for the extracted data. In your response to the user that explains
+the optimizations made to the prompt, mention that the optimized prompt is
+designed for use with the Structured Output API. Also, mention that the
+"" delimiters signify placeholder text that should be replaced with code in the user's actual implementation.
+
+### Example 2
+
+Unoptimized prompt:
+
+    Given this itinerary for a trip: [Flight to Paris (CDG), Check-in: Hotel Le
+    Meurice, Visit to the Louvre, Dinner at Le Jules Verne, Eiffel Tower Visit,
+    Versailles Palace Tour, Montmartre Walk, Seine River Cruise, Pastry and Macaron
+    Tasting, Flight Out], generate the following: overall vibe, tips on how to
+    prepare for this trip, and common short phrases to learn for the trip.
+
+Optimized prompt:
+
+    ## Task
+
+    Analyze the trip itinerary below and extract details to build a concise travel
+    guide.
+
+    ## Rules
+    - Overall vibe: Limit to 1 short sentence (under 15 words).
+    - Preparation tips: Provide exactly 3 short tips (maximum 10 words per tip).
+    - Useful phrases: Provide exactly 3 phrases (under 15 words each).
+
+    ## Itinerary
+
+    <itinerary>
+    [itinerary_content]
+    </itinerary>

package/skills/mobile-android/references/on-device-ai/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/mobile-android/references/on-device-ai/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/mobile-android/references/on-device-ai.md

@@ -0,0 +1,10 @@
+# Android: On-device AI
+
+App Functions and the ML Kit GenAI Prompt API.
+
+| Guide | What it covers |
+|---|---|
+| [appfunctions](on-device-ai/appfunctions/GUIDE.md) | Analyzes Android apps to identify key user workflows for AppFunctions such as creating a note, playing media, or sending an automated or AI agent triggered message, voice commands, or system shortcuts, without needing to open the app UI. |
+| [ml-kit-genai-prompt-api](on-device-ai/ml-kit-genai-prompt-api/GUIDE.md) | Analyzes Android codebases to implement ML Kit GenAI Prompt API. |
+
+Each guide lives in its own folder with its references and scripts. Relative paths in a guide — and `<repo_root>` where a guide uses it — refer to that guide's folder.