Project 2: llmPlay Compose

Cover Page

Expected behavior

Preparing your GitHub repo

If you have not completed the llmChat tutorial, please do so first. Then depending on whether you have completed the Maps tutorial, we have two different preparatory paths. Please click on your option to proceed:

• In your /app/res/values/strings.xml file, set your "message" string to a single space, “ ”, instead of howdy?
• Delete the file ChattScrollView.kt from your project
• Push your local /YOUR:TUTORIALS/ repo to GitHub and make sure there’re no git issues:
  git push

  • Open GitHub Desktop and click on Current Repository on the top left of the interface
  • Click on your reactive GitHub repo
  • Add Summary to your changes and click Commit to main
  • If you have pushed other changes to your Git repo, click Pull Origin to synch up the clone on your laptop
  • Finally click on Push Origin to push changes to GitHub

Go to the GitHub website to confirm that your folders follow this structure outline:

  reactive
    |-- chatterd
    |-- chatterd.crt
    |-- llmchat
    |-- llmplay
        |-- composeChatter
            |-- app
            |-- gradle
    # and other files or folders

Interacting with Ollama

I think of the interaction with Ollama as separated into three phases:

1. When the app launches, it starts a game by prompting the model, through chatterd’s /llmprep API, for a set of hints about a city. In the same prompt, it also specifies what the model must do to announce that the user has guessed correctly.
2. As the game progress, the app interacts with the model through chatterd’s modified /llmchat API: receiving hints, sending guesses. We’ll be using a modified llmChat(), which I call llmPlay(), to handle this phase.
3. Finally, the app must be able to receive, recognize, and handle a LatLon SSE event that chatterd sends when Ollama announces a winner.

When the app launches, in the onCreate() method of my MainActivity, after I’ve registered for location access permission, and before calling setContent(), I send the system prompt as described in the Front-end UX section using llmPrep() (see the llmPrep TODO in the llmChat tutorial for an example usage). After sending the system prompt, I follow with sending a single “Yes” string using llmPlay() to prime the model and get it to return the first set of hints about the mystery city.

Be careful with the wording of your prompt. For example, opening your session with a “Test” or “This is a test” prompt could lead to confusing subsequent interaction with the model.

I collect the hints returned by Ollama in an observable property hints in my ChattViewModel, also in MainActivity.kt. Since this initial prompt will never result in any winning notification, I give null as the argument for the winner parameter.

Location class

To communicate lat/lon information between functions, I define the following data class in my LocManager.kt file:

@Serializable
@JsonIgnoreUnknownKeys
data class Location(
  var lat: Double = 0.0,
  var lon: Double = 0.0
)

llmPlay()

Here’s the full signature I use for llmPlay() in ChattStore:

    suspend fun llmPlay(appID: String?, chatt: Chatt,
                        hints: MutableState<String>,
                        winner: ((Location) -> Unit)?,
                        errMsg: MutableState<String>) { }

The first, second, and last parameters are the same as those of llmChat(). The hints parameter is an observable string we use to hold hints Ollama returns about the city for the user to guess. We update hints similar to how we update errMsg. Appending newly arriving chunks to hints accumulates the hints. Compose automatically re-composes any composable observing a MutableState<T> variable, such as hints and errMsg. The winner parameter is a lambda expression that takes a Location, as argument and handles the winning notification. Location is defined above in LocManager.kt.

I will build llmPlay() by modifying llmChat(), as follows. Unlike in the llmChat tutorial, we do not need to show a timeline of user exchanges with Ollama. Thus, instead of creating a placeholder chatt message to append to a chatts array, as we did in llmChat(), you can decode each Message data line of the returning stream into an OllamaResponse class and append its content to the hints parameter directly. Remember to clear the hints parameter before you start processing Ollama’s reply and start appending to it.

Handling of SSE Error event and all other error handling code can be adopted from llmChat().

To recognize and handle a LatLon SSE event, you may want to read closely the llmChat() code for handling SSE Error event, and the accompanying explanation in the llmChat tutorial. To implement SSE LatLon event handling, first add a LatLon enum constant to your SseEventType at the top of ChattStore file. Then for each line of the incoming stream, when you detect an event tag, in addition transitioning to an Error event, you want to recognize and transition to a LatLon event.

When parsing a data line, if it’s part of a LatLon event, decode the line into a Location data class, not an OllamaResponse data class, and call the winner lambda expression with the decoded Location as its argument. Since winner can be null, to invoke it, you must use the invoke method, after checking that it is indeed not null:

                                winner?.invoke(location)

We will discuss what goes into the winner lambda expression at llmPlay() use site in SubmitButton later.

Game UI

The Game UI is simply the MainView with a GoogleMap taking the place of ChattScrollView. We want to show the GoogleMap only when the location read on our device has yielded some data. We also want to move the map’s camera around when there’s a winner notification.

First add a cameraPositionState variable to your MainView() composable. This gives us a handle on the camera that we will use to move it around the map.

    val cameraPositionState = rememberCameraPositionState()

You can remove the listScroll variable as we will no longer be showing a timeline of chatts.

Then, guard your call to GoogleMap() with a conditional check on the availability of location data. If location data is not (yet) available, show a CircularProgressIndicator as we do with SubmitButton:

            if (LocManager.location.value.latitude != 0.0 || LocManager.location.value.longitude != 0.0) {
              // show GoogleMap()
            } else {
              // show CircularProgressIndicator()
            }

When we displayed GoogleMap() in the Maps tutorial, we initialized it with a camera position for its cameraPositionState parameter. For this programming assignment, initialize GoogleMap() with the “blank” cameraPositionState variable above. Then inside the content lambda, where we called MarkerInfoWindow()s in the Maps tutorial, put the following LaunchedEffect() to position the camera on launch instead:

                    LaunchedEffect(Unit) {
                        cameraPositionState.move(
                            CameraUpdateFactory.newCameraPosition(
                                CameraPosition.Builder()
                                    .target(LatLng(
                                          LocManager.location.value.latitude,
                                          LocManager.location.value.longitude
                                    ))
                                    .zoom(14f).tilt(60f).build()
                            )
                        )
                    }

Below all that, we want to show the hints returned by Ollama in a Text() box above the OutlinedTextField() where user enters their guesses. The content of the Text() box should be the observable property hints in ChattViewModel where you’ve collected the hints from Ollama. Put these two text boxes in a Column() with modifier .fillMaxWidth(.88f) and replace the modifier parameter for OutlinedTextField() with:

                        modifier = Modifier
                            .fillMaxWidth(1f)
                            .padding(end = 18.dp),

Next to these two text boxes, we want to show the SubmitButton:

• You want to update the SubmitButton from the llmChat tutorial to take an argument of type CameraPositionState.
• When calling SubmitButton, since we don’t have a timeline of chatts to show anymore, replace the parameter listScroll with cameraPositionState we defined above. Then in SubmitButton remove the call to animateScrolltToItem(), along with its surrounding withContext().
• Also add the following local variable to SubmitButton:

      val focus = LocalFocusManager.current
  

• In SubmitButton, call llmPlay() in lieu of llmChat(), passing it the hints property in ChattViewModel.
• As for the winner parameter of llmPlay(), pass it the following lambda expression, which moves the camera on the GoogleMap to the city’s lat/lon:

  { loc ->
    vm.viewModelScope.launch {
        withContext(AndroidUiDispatcher.Main) {
            cameraPositionState.move(
                CameraUpdateFactory.newLatLng(
                    LatLng(loc.lat, loc.lon)
                )
            )
            focus.clearFocus()
        }
    }
  },
  

Finally, as usual, MainView must pop up an alert dialog box if there were any error messages.

Additional UX (optional)

The following UX feature is intended to increase the perceived responsiveness and interactivity of the app. You can choose to implement it to match the demo video, but you won’t be deducted point if you don’t (nor will there be extra credit if you do!).

While waiting for the first batch of hints from Ollama, the message in the text box holding the hints should show Waiting for hints… and the SubmitButton is disabled and shows a CircularProgressIndicator() which changes back to the “paper plane” icon when the hints finished arriving.

That’s all for Project 2!

Run and test to verify and debug

Be sure to run your front end against your back end. You will not get full credit if your front end is not set up to work with your back end!

Submission guidelines

Be sure you have submitted your modified back end in addition to submitting your updated front end. As usual, we will only grade files committed to the main branch. If you use multiple branches, please merge them all to the main branch for submission.

Push your front-end code to the same GitHub repo you’ve submitted your back-end code:

• Open GitHub Desktop and click on Current Repository on the top left of the interface
• Click on the GitHub repo you created at the start of this tutorial
• Add Summary to your changes and click Commit to main at the bottom of the left pane
• If you have pushed code to your repo, click Pull Origin to synch up the repo on your laptop
• Finally click Push Origin to push all changes to GitHub

Go to the GitHub website to confirm that your front-end files have been uploaded to your GitHub repo under the folder llmplay. Confirm that your repo has a folder structure outline similar to the following. If your folder structure is not as outlined, our script will not pick up your submission and, further, you may have problems getting started on latter tutorials. There could be other files or folders in your local folder not listed below, don’t delete them. As long as you have installed the course .gitignore as per the instructions in Preparing GitHub for Reactive Tutorials, only files needed for grading will be pushed to GitHub.

  reactive
    |-- chatterd
    |-- chatterd.crt
    |-- llmchat
    |-- llmplay
        |-- composeChatter
            |-- app
            |-- gradle
    # and other files or folders

Appendix: imports