reis-mobile 0.3.6 → 0.5.0

package/skills/mobile-android/references/on-device-ai/appfunctions/references/migrate-to-service-entry-point.md

@@ -0,0 +1,226 @@
+Follow this systematic procedure to migrate Android applications that use the
+AppFunctions API in version 1.0.0-alpha09 and lower to the compile-time
+`@AppFunctionServiceEntryPoint` architecture introduced in version
+`1.0.0-alpha10`.
+
+*** ** * ** ***
+
+## Architectural shift overview
+
+In lower versions of the AppFunctions API, for example version `1.0.0-alpha09`:
+
+- Applications require separate dependencies for core functionality, specifically `androidx.appfunctions:appfunctions`, and service components, specifically `androidx.appfunctions:appfunctions-service`.
+- The application implements `AppFunctionConfiguration.Provider` on its `Application` class.
+- You manually register enclosing class instantiation using `AppFunctionConfiguration.Builder().addEnclosingClassFactory(...)`.
+- You place metadata property tags directly under `<application>`.
+
+In version `1.0.0-alpha10` featuring `@AppFunctionServiceEntryPoint`:
+
+- The core and service dependencies are consolidated into a single runtime artifact, `androidx.appfunctions:appfunctions`, which eliminates the need for the standalone `appfunctions-service` library.
+- A dedicated wrapper class extending `AppFunctionService` is annotated with `@AppFunctionServiceEntryPoint` and Hilt's `@AndroidEntryPoint` or an alternative dependency injection framework.
+- The KSP compiler generates a concrete service subclass and an XML metadata schema file in `assets/`.
+- The OS discovers and routes executions using a consolidated `<service>` and `app_metadata` declaration in `AndroidManifest.xml`.
+
+### Strict migration requirements from 1.0.0-alpha09 to 1.0.0-alpha10
+
+When focusing solely on the mandatory API changes required by the new
+`@AppFunctionServiceEntryPoint` architecture, the migration consists of four
+strict requirements that you must complete:
+
+1. **Build dependency consolidation** : Remove the merged `appfunctions-service` dependency while retaining core `appfunctions` and the KSP compiler.
+2. **Service wrapper creation** : Replace the legacy `AppFunctionConfiguration.Provider` on the `Application` class with an abstract class extending `AppFunctionService`, annotated with `@AppFunctionServiceEntryPoint`.
+3. **Annotation and context decoupling** : Move `@AppFunction` annotations to the new wrapper methods and drop `AppFunctionContext` parameters because `AppFunctionService` inherits directly from `Context`.
+4. **Manifest registration** : Register the KSP-generated concrete service in `AndroidManifest.xml` with `BIND_APP_FUNCTION_SERVICE`, the `AppFunctionService` intent filter, and metadata property tags.
+
+*** ** * ** ***
+
+## Systematic migration steps
+
+### Consolidate AppFunctions build dependencies
+
+Remove the standalone `appfunctions-service` library from your module build
+files like `build.gradle.kts` and version catalog like `libs.versions.toml`. In
+version `1.0.0-alpha10`, all core service capabilities are consolidated directly
+within the main `appfunctions` artifact.
+
+    // build.gradle.kts
+    dependencies {
+        implementation(libs.androidx.appfunctions)
+    -   implementation(libs.androidx.appfunctions.service)
+        ksp(libs.androidx.appfunctions.compiler)
+    }
+
+    # libs.versions.toml
+    [versions]
+    appfunctions = "1.0.0-alpha10"
+
+    [libraries]
+    androidx-appfunctions = { module = "androidx.appfunctions:appfunctions", version.ref = "appfunctions" }
+    -   androidx-appfunctions-service = { module = "androidx.appfunctions:appfunctions-service", version.ref = "appfunctions" }
+    androidx-appfunctions-compiler = { module = "androidx.appfunctions:appfunctions-compiler", version.ref = "appfunctions" }
+
+> [!NOTE]
+> **Note:** If another dependency in your project uses snapshot builds like `1.0.0-SNAPSHOT` or custom snapshot repositories from `https://androidx.dev/snapshots/...`, preserve your custom snapshot repository configuration in `settings.gradle.kts`. Otherwise, standard Google Maven repositories resolve `1.0.0-alpha10` directly.
+
+*** ** * ** ***
+
+### Create a dedicated wrapper service extending `AppFunctionService`
+
+Instead of annotating standalone business logic classes or implementing manual
+configuration providers, create an abstract service wrapper across your project,
+for example `BaseAppFunctionService`, extending `AppFunctionService` and
+annotated with `@AppFunctionServiceEntryPoint`.
+
+#### Recommended approach using Hilt
+
+Annotate your service with `@AndroidEntryPoint` and inject your data
+repositories or use cases using standard `@Inject internal lateinit var`:
+
+
+```kotlin
+@RequiresApi(36)
+@AndroidEntryPoint
+@AppFunctionServiceEntryPoint(
+    serviceName = "MyAppFunctionService",
+    appFunctionXmlFileName = "my_app_function_service", // Do NOT include .xml extension
+)
+abstract class BaseAppFunctionService : AppFunctionService() {
+    @Inject internal lateinit var messageRepository: MessageRepository
+
+    @AppFunction(isDescribedByKDoc = true)
+    internal suspend fun send(
+        name: String,
+        endpointValue: String,
+        messageBody: String,
+    ): MessageResult {
+        return messageRepository.send(name, endpointValue, messageBody)
+    }
+}
+```
+
+<br />
+
+#### Framework-agnostic approach using alternative dependency injection or a service locator
+
+While Hilt is recommended, many Android applications implement AppFunctions with
+alternative dependency injection frameworks like Koin, Anvil, or manual Service
+Locators. Because `AppFunctionService` inherits from Android
+`android.app.Service` and therefore `Context`, you are able access your
+application's DI container directly through `applicationContext` in property
+getters or during service lifecycle execution:
+
+
+```kotlin
+@RequiresApi(36)
+@AppFunctionServiceEntryPoint(
+    serviceName = "ServiceLocatorMyAppFunctionService",
+    appFunctionXmlFileName = "service_locator_my_app_function_service",
+)
+abstract class ServiceLocatorBaseAppFunctionService : AppFunctionService() {
+    // Example using a manual Service Locator or Application container
+    private val messageRepository by lazy {
+        (applicationContext as AppFunctionApplication).appContainer.messageRepository
+    }
+    // Or with Koin / alternative DI locators:
+    // private val messageRepository: MessageRepository by inject()
+
+    @AppFunction(isDescribedByKDoc = true)
+    internal suspend fun send(
+        name: String,
+        endpointValue: String,
+        messageBody: String,
+    ): MessageResult {
+        return messageRepository.send(name, endpointValue, messageBody)
+    }
+}
+```
+
+<br />
+
+> [!IMPORTANT]
+> **Important:** The `appFunctionXmlFileName` parameter, for example `"my_app_function_service"`, mustn't include the `.xml` extension, as the KSP compiler automatically appends `.xml`. Passing `"my_app_function_service.xml"` results in the asset being named `"my_app_function_service.xml.xml"`.
+
+*** ** * ** ***
+
+### Simplify method signatures and decouple context
+
+Remove legacy `AppFunctionContext` parameters from your core methods. When a
+method requires an Android `Context`, for example when constructing a
+`PendingIntent`, access `this` directly from your `AppFunctionService` wrapper
+because the wrapper inherently extends `android.content.Context`.
+
+    -   suspend fun makeCall(appFunctionContext: AppFunctionContext, contactName: String?): PendingIntent
+    +   suspend fun makeCall(contactName: String?): PendingIntent
+
+*** ** * ** ***
+
+### Remove legacy configuration provider
+
+Update your `Application` class by removing
+`AppFunctionConfiguration.Provider` and its associated builder entry points:
+
+    -   abstract class BaseChatApplication : Application(), AppFunctionConfiguration.Provider { ... }
+    +   abstract class BaseChatApplication : Application()
+
+*** ** * ** ***
+
+### Avoid redundant abstraction layers
+
+Don't attempt to make an `AppFunction` class or method OS-agnostic---AppFunctions
+are inherently part of the Android platform integration through the
+`androidx.appfunctions` package. For architectural cleanliness, use existing
+application functionality, such as existing repositories, use cases, or domain
+orchestrators, to execute the behavior within your `@AppFunction` methods rather
+than creating redundant abstraction layers around the OS service.
+
+*** ** * ** ***
+
+### Consolidate service and metadata manifest declarations
+
+Register the KSP-generated service declaration and `app_metadata` property
+inside your module manifest, for example in `src/main/AndroidManifest.xml`
+within the `<application>` tag:
+
+
+```xml
+<service
+    android:name="com.example.snippets.ai.MyAppFunctionService"
+    android:permission="android.permission.BIND_APP_FUNCTION_SERVICE"
+    android:exported="true"
+    tools:targetApi="36">
+    <property
+        android:name="android.app.appfunctions.schema"
+        android:value="app_functions_schema.xsd" />
+    <property
+        android:name="android.app.appfunctions.v2"
+        android:value="my_app_function_service.xml" />
+    <intent-filter>
+        <action android:name="android.app.appfunctions.AppFunctionService" />
+    </intent-filter>
+</service>
+<property
+    android:name="android.app.appfunctions.app_metadata"
+    android:resource="@xml/app_metadata" />
+```
+
+<br />
+
+*** ** * ** ***
+
+## Verification and troubleshooting
+
+1. **Clean rebuild and deploy** : `bash
+   ./gradlew clean installDebug`
+2. **Verify AppSearch discovery / indexing** : Run the following ADB command to
+   confirm the OS successfully discovered and indexed your functions:
+   `bash
+   adb shell cmd app_function list-app-functions`
+   *If your package doesn't appear, confirm that `android.app.appfunctions.v2`
+   matches the exact asset name generated in `assets/`.*
+
+3. **Verify execution using ADB** :
+   `bash
+   adb shell "cmd app_function execute-app-function \
+   --package com.example.chatapp \
+   --function 'com.example.chatapp.appfunctions.BaseAppFunctionService#send' \
+   --parameters '{\"name\": \"Alice\", \"endpointValue\": \"1\", \"messageBody\": \"Hello Alice!\"}'"`

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

@@ -0,0 +1,105 @@
+> Adapted from the `ml-kit-genai-prompt-api` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
+
+This skill provides step-by-step guidance for integrating and optimizing the ML
+Kit GenAI Prompt API in Android apps.
+
+## Prerequisites
+
+- Android API level must be 26 or higher. If `minSdk` is below 26, update it to 26.
+- Add the ML Kit GenAI Prompt API dependency (`com.google.mlkit:genai-prompt`) to the app-level `build.gradle` file, with version at least `1.0.0-beta4`.
+- If `com.google.mlkit:genai-schema-compiler` dependency is used and KSP plugin version is below 2.3.6, update it to 2.3.6.
+
+## Detailed steps
+
+### 1. Prompt optimization
+
+To optimize prompts for use with the ML Kit Prompt API, follow the
+[prompt optimization guide](https://developer.android.com/agents/skills/device-ai/prompt-api/references/prompt-optimization).
+
+### 2. Prefix caching optimization
+
+If the prompt is more than 200 words, implement the [prefix caching API](https://developer.android.com/agents/skills/device-ai/prompt-api/references/prefix-caching).
+
+### 3. Lifecycle and best practices
+
+- The model must be fully downloaded and available before calling the first inference. Follow the guide on [implementing a generative model](https://developer.android.com/agents/skills/device-ai/prompt-api/references/get-started) to check that the `FeatureStatus` of a model is `AVAILABLE` before making an inference.
+- Release ML Kit instances by calling `close()` when an `Activity`,
+  `Fragment`, or `ViewModel` is destroyed. Example:
+
+
+  ```kotlin
+  // Instantiating model in activity, fragment, or ViewModel
+      val generativeModel = Generation.getClient()
+
+  // When activity, fragment, or ViewModel is destroyed
+      generativeModel.close()
+  ```
+
+  <br />
+
+### 4. Structured output
+
+When implementing or refactoring a prompt to use structured output, follow
+these rules:
+
+1. **Check for API availability:** Verify Structured Output feature is available on the device with `isStructuredOutputFeatureAvailable()` before using it. Refer to the [Structured Output API guide](https://developer.android.com/agents/skills/device-ai/prompt-api/references/structured-output) for full instructions.
+2. **Return type:** Return the `@Generable` typed object from the function
+   signature instead of a `String` or JSON string.
+
+   For example:
+
+       fun parseEmail(email: String): String {
+           ... 
+       }
+
+   should be refactored to:
+
+       fun parseEmail(email: String): ParsedEmail? {
+           ...
+       }
+
+3. **Example:**
+
+   This is the example code before refactoring:
+
+
+   ```kotlin
+   suspend fun parseEmail(email: String): String {
+       val parseEmailPrompt = "Parse this email and return the sender, title, and short summary of the email less than 10 words: "
+
+       val parsedEmail = generativeModel.generateContent(parseEmailPrompt + email)
+
+       return parsedEmail.candidates[0].text
+   }
+   ```
+
+   <br />
+
+   This is the example code after using Structured Output API:
+
+
+   ```kotlin
+   @Generable
+   data class ParsedEmail(
+       @Guide(description = "Sender of the email")
+       var sender: String = "",
+
+       @Guide(description = "Title of the email")
+       var title: String = "",
+
+       @Guide(description = "Summary of the email less than 10 words")
+       var summary: String = ""
+   )
+
+   suspend fun parseEmail(email: String): ParsedEmail? {
+       val parseEmailPrompt =
+           "Parse this email: $email"
+
+       val baseRequest = GenerateContentRequest.Builder(TextPart(parseEmailPrompt)).build()
+       val typedRequest = generateTypedContentRequest(baseRequest, ParsedEmail::class)
+       val typedResponse = generativeModel.generateContent(typedRequest)
+       return typedResponse.candidates[0].response
+   }
+   ```
+
+   <br />

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

@@ -0,0 +1,272 @@
+This page describes how to do the following:
+
+- Configure your project to use Prompt API
+- Provide text-only input and receive a response
+- Provide an image input with related text input and receive a response
+
+For more details about the Prompt API, see the
+reference documentation for Kotlin ([com.google.mlkit.genai.prompt](https://developer.android.com/android/reference/kotlin/com/google/mlkit/genai/prompt/package-summary)) and
+Java ([com.google.mlkit.genai.prompt.java](https://developer.android.com/android/reference/com/google/mlkit/genai/prompt/java/package-summary),
+[com.google.mlkit.genai.prompt](https://developer.android.com/android/reference/com/google/mlkit/genai/prompt/package-summary)).
+
+## Configure project
+
+> [!NOTE]
+> **Note:** This API requires Android API level 26 or higher.
+
+Add the ML Kit Prompt API as a dependency in your `build.gradle` configuration:
+
+    implementation("com.google.mlkit:genai-prompt:1.0.0-beta2")
+
+If you need your responses in a certain format using the Structured Output API,
+you need to configure KSP and add additional dependencies. For details, see
+[Generate structured output](https://developer.android.com/agents/skills/device-ai/prompt-api/references/structured-output).
+
+## Implement generative model
+
+To implement the code in your project, follow these steps:
+
+- Create a `generativeModel` object:
+
+  ### Kotlin
+
+      // Get a GenerativeModel instance
+      val generativeModel = Generation.getClient()
+
+  ### Java
+
+      // Get a GenerativeModel instance
+      GenerativeModelFutures generativeModelFutures = GenerativeModelFutures
+          .from(Generation.INSTANCE.getClient());
+
+- Check if Gemini Nano is `AVAILABLE,` `DOWNLOADABLE`, or `UNAVAILABLE`. Then,
+  download the feature if it is downloadable:
+
+  ### Kotlin
+
+      val status = generativeModel.checkStatus()
+      when (status) {
+          FeatureStatus.UNAVAILABLE -> {
+              // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
+          }
+
+          FeatureStatus.DOWNLOADABLE -> {
+              // Gemini Nano can be downloaded on this device, but is not currently downloaded
+              generativeModel.download().collect { status ->
+                  when (status) {
+                      is DownloadStatus.DownloadStarted ->
+                          Log.d(TAG, "starting download for Gemini Nano")
+
+                      is DownloadStatus.DownloadProgress ->
+                          Log.d(TAG, "Nano ${status.totalBytesDownloaded} bytes downloaded")
+
+                      DownloadStatus.DownloadCompleted -> {
+                          Log.d(TAG, "Gemini Nano download complete")
+                          modelDownloaded = true
+                      }
+
+                      is DownloadStatus.DownloadFailed -> {
+                          Log.e(TAG, "Nano download failed ${status.e.message}")
+                      }
+                  }
+              }
+          }
+
+          FeatureStatus.DOWNLOADING -> {
+              // Gemini Nano currently being downloaded
+          }
+
+          FeatureStatus.AVAILABLE -> {
+              // Gemini Nano currently downloaded and available to use on this device
+          }
+      }
+
+  ### Java
+
+      ListenableFuture<Integer> status = generativeModelFutures.checkStatus();
+      Futures.addCallback(generativeModelFutures.checkStatus(), new FutureCallback<>() {
+          @Override
+          public void onSuccess(Integer featureStatus) {
+              switch (featureStatus) {
+                  case FeatureStatus.AVAILABLE -> {
+                      // Gemini Nano currently downloaded and available to use on this device
+                  }
+                  case FeatureStatus.UNAVAILABLE -> {
+                      // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
+                  }
+                  case FeatureStatus.DOWNLOADING -> {
+                      // Gemini Nano currently being downloaded
+                  }
+                  case FeatureStatus.DOWNLOADABLE -> {
+                      generativeModelFutures.download(new DownloadCallback() {
+                          @Override
+                          public void onDownloadStarted(long l) {
+                              Log.d(TAG, "starting download for Gemini Nano");
+                          }
+                          @Override
+                          public void onDownloadProgress(long l) {
+                              Log.d(TAG, "Nano " + l + " bytes downloaded");
+                          }
+                          @Override
+                          public void onDownloadCompleted() {
+                              Log.d(TAG, "Gemini Nano download complete");
+                          }
+                          @Override
+                          public void onDownloadFailed(@NonNull GenAiException e) {
+                              Log.e(TAG, "Nano download failed: " + e.getMessage());
+                          }
+                      });
+                  }
+              }
+          }
+          @Override
+          public void onFailure(@NonNull Throwable t) {
+              // Failed to check status
+          }
+      }, ContextCompat.getMainExecutor(context));
+
+## Provide text-only input
+
+### Kotlin
+
+    val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog.")
+
+### Java
+
+    GenerateContentResponse response = generativeModelFutures.generateContent(
+      new GenerateContentRequest.Builder(
+        new TextPart("Write a 3 sentence story about a magical dog."))
+      .build())
+      .get();
+
+Alternatively, add optional parameters:
+
+### Kotlin
+
+    val response = generativeModel.generateContent(
+        generateContentRequest(
+            TextPart("Write a 3 sentence story about a magical dog."),
+        ) {
+            // Optional parameters
+            temperature = 0.2f
+            topK = 10
+            candidateCount = 3
+        },
+    )
+
+### Java
+
+    GenerateContentRequest.Builder requestBuilder =
+            new GenerateContentRequest.Builder(
+                    new TextPart("Write a 3 sentence story about a magical dog."));
+    requestBuilder.setTemperature(.2f);
+    requestBuilder.setTopK(10);
+    requestBuilder.setCandidateCount(3);
+
+    GenerateContentResponse response =
+            generativeModelFutures.generateContent(requestBuilder.build()).get();
+
+For more information about the optional parameters, see [Optional
+configurations](https://developer.android.com/agents/skills/device-ai/ml-kit-genai-prompt-api/references/get-started#optional-configurations).
+
+## Provide multimodal (image and text) input
+
+Bundle an image and a text input together in the `generateContentRequest()`
+function, with the text prompt being a question or command related to the
+image. You can bundle multiple images and text together in the same request.
+
+### Kotlin
+
+    val response = generativeModel.generateContent(
+        generateContentRequest(ImagePart(bitmap), TextPart(textPrompt)) {
+            // optional parameters
+            ...
+        },
+    )
+
+### Java
+
+    GenerateContentResponse response = generativeModelFutures.generateContent(
+        new GenerateContentRequest.Builder(
+            new ImagePart(bitmap),
+            new TextPart("textPrompt"))
+        // optional parameters
+        .build())
+    .get();
+
+## Process inference result
+
+- Run the inference and retrieve the result. You can choose to either wait for
+  the full result or stream the response as it's generated for both text-only
+  and multimodal prompts.
+
+  - This uses non-streaming inference, which retrieves the entire result from
+    the AI model before returning the result:
+
+  ### Kotlin
+
+      // Call the AI model to generate content and store the complete
+      // in a new variable named 'response' once it's finished
+      val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog")
+
+  ### Java
+
+      GenerateContentResponse response = generativeModelFutures.generateContent(
+              new GenerateContentRequest.Builder(
+                      new TextPart("Write a 3 sentence story about a magical dog."))
+                      .build())
+              .get();
+
+  - The following snippets are examples of using streaming inference, which
+    retrieves the result in chunks as it's being generated:
+
+  ### Kotlin
+
+      // Streaming inference
+      var fullResponse = ""
+      generativeModel.generateContentStream("Write a 3 sentence story about a magical dog").collect { chunk ->
+          val newChunkReceived = chunk.candidates[0].text
+          print(newChunkReceived)
+          fullResponse += newChunkReceived
+      }
+
+  ### Java
+
+      // Streaming inference
+      StringBuilder fullResponse = new StringBuilder();
+      generativeModelFutures.generateContent(new GenerateContentRequest.Builder(
+          (new TextPart("Write a 3 sentence story about a magical dog"))).build(),
+              chunk -> {
+                  Log.d(TAG, chunk);
+                  fullResponse.append(chunk);
+              });
+
+For more information about streaming and non-streaming inference, see [Streaming
+versus non-streaming](https://developer.android.com/ml-kit/genai#streaming-vs-non).
+
+## Latency optimization
+
+To optimize for the first inference call, your application may optionally call
+`warmup()`. This loads Gemini Nano into memory and initializes runtime
+components.
+
+## Optional configurations
+
+As part of each `GenerateContentRequest`, you can set the following optional
+parameters:
+
+- `temperature` : Controls the degree of randomness in token selection.
+- `seed` : Enables generating stable and deterministic results.
+- `topK` : Controls randomness and diversity in results.
+- `candidateCount` : Requests the number of unique responses returned. Note that the exact number of responses may not be the same as `candidateCount` because duplicate responses are automatically removed.
+- `maxOutputTokens` : Defines the maximum number of tokens that can be generated in the response.
+
+For more guidance on setting optional configurations, see
+[`GenerateContentRequest`](https://developer.android.com/android/reference/kotlin/com/google/mlkit/genai/prompt/GenerateContentRequest).
+
+## Supported features and limitations
+
+- Input must be under 4000 tokens (or approximately 3000 English words). For more information, see the [`countTokens`](https://developer.android.com/android/reference/com/google/mlkit/genai/prompt/GenerativeModel#countTokens(com.google.mlkit.genai.prompt.GenerateContentRequest)) reference.
+- Use cases that require long output (more than 4K tokens) should be avoided.
+- AICore enforces an inference quota per app. For more information, see [Quota
+  per application](https://developer.android.com/ml-kit/genai#quota-per).