Cli | Alex Ho

Offline retrieval-augmented generation (RAG)

Sun, 11 Aug 2024 00:00:00 +0000

was my first experience with generative artificial intelligence (AI). I was impressed by its ability to make code suggestions and to generate unit tests. Translation between code comments and code was pretty seamless even the technology was based on ChatGPT-3.5 in 2022.

No matter it is GitHub Copilot or Chat GPT from OpenAI, it is available as a service which runs mostly as a black box to an end user. Although there were free tokens for anyone who wants to try it out, for more advanced usages like API calls to the service, a not insignificant amount of money would be charged. So I was not very interested in learning how does it work other than just learning enough to use it in my code editor for my $10 GitHub Copilot subscription.

Fast forward to early 2024, when I was messing with one of the tools named , I realised that there are options other than OpenAI offerings and the thing is named . Ollama allows users to run models locally and it has Docker support as well. I was intrigued by the idea of running a model locally and tried to run it on my laptop using Docker. Little that I know, at the time, that running a Docker image on Mac does not have GPU support and Ollama was running on CPU. Thus, even a small model like was super slow to spit out a response. Luckily, it did not take long for me to realise that I need to run it on bare metal on Mac to utilise GPU. I was truely amazed by the capabilities of the models that can be run locally on my machine.

Tools like works by talking to API of services like OpenAI. Similarly, Ollama has its own API initially but it later extended its API to add support for . The API makes tools can easily talk to the models via the API. Ollama is written in and uses to build the API.

As a software engineer, prompting the models via command line (or via a GUI like ) is definitely not enough for my appetite. Naturally, I started to think of building a semi-useful toy application and my idea is to build a question and answer CLI tool where it answers questions based on the markdown notes that I have locally on my machine.

To demonstrate the idea, here is one of the questions that I asked.

$ rag ask \
    -m llama3.1:8b \
    -n notes \
    -q "What is the best way to conduct an interview?"

And the response was

Based on the provided documentation, the best way to conduct an interview
involves a general approach that includes giving people a real problem to solve,
regardless of the medium of the exercise. This allows you to get a better sense
for how their brain works.

Here are some specific steps and tips mentioned in the documentation:

1. **Give people a real problem**: Provide candidates with a genuine challenge
   to tackle, which can help assess their thought process and problem-solving
skills.
2. **Use whiteboarding**: Whiteboarding can be useful for sketching out system
   designs or explaining thinking on a problem. It's essential to give people
   a chance to express themselves in the medium they're most comfortable with.
3. **Ask open-ended questions**: Try to ask questions that encourage candidates
   to share their thought process and approach, rather than just seeking
   a specific answer.
4. **Look for passion and curiosity**: Pay attention to whether candidates show
   genuine interest in the role, company, technology, and products. A lack of
   curiosity or defensiveness can be red flags.
5. **Provide feedback**: After the interview, don't hesitate to give feedback on
   what candidates did well. This can help them understand their strengths and
   weaknesses.

Additionally, the documentation suggests that you should:

* Reassure candidates that you're interested in how they approach problems, not
  just the answers.
* Ask questions that allow candidates to showcase themselves.
* Encourage candidates to explain complex concepts in simple terms.
* Look for passion and enthusiasm in a candidate's work.
* Use easy programming questions to filter out unsuitable candidates (e.g.,
  "Write a function that determines if a string starts with an upper-case letter
  A-Z").
* Leave time at the end of the interview to sell the company and job to the
  candidate.

By following these guidelines, you can conduct a more effective and informative
interview.

The response was based on and the model summarised the relevant parts of the markdown to answer the question pretty well.

Background

One of the ways to include customised data in a generated response is to pre-train the model with the data. Although this approach provides the best performace in terms of quality of response, it requires a lot of resources and time to train a new customised model. Another approach is to use where generation involves a step of retriving relevant information from a database of customised data and incorporating it into the generated response. This approach is more efficient in terms of resources and time as the model does not need to be re-trained with customised data which it can be changed frequently.

Preparing database of customised data

The steps required to load reference markdown files and to store in a database are outlined in this diagram.

To prepare the database of customised data, we load markdown files in a specified directory into memory. Along with the text of each markdown file, we also retrieve the metadata of the markdown file such as the filename. The metadata can be stored in the database the later steps.

The texts cannot be be directly stored into a database. One of the reasons is that the text is either too large to be used as embedding of a LLM or it contains too many topics which affects the quality of the response. To address this issue, text chunking is done before storing the text into the database. There are many text chunking techniques including the use of NLP to split text based on semantic meaning. However, I am no NLP expert and so I will use the simplest technique where text will be splitted into fixed-length chunks (1500 characters) and there will be a bit of overlap (300 characters) between chunks to avoid splitting up an important sentence. Each model has a limit of number of tokens to be used in an embedding. For example, model llama3.1 has a limit of 4096 token and model gemma2 has a limit of 3584 token. Therefore parameters used in chunking depends on the models to be used.

After splitting the text into chunks, a model is used to convert each chunk into a vector. The model used in this conversion is . There are many models can be used such conversion and it can be found on . The converted vectors along with its associated text and metadata are stored in a database. The database of choice is and it is a database for storing embedding vectors. Chroma stores text and metadata in a database and the associated vectors in its own indexed data structure.

The above steps can be summarised as the following code.

documents := retrieveDocuments(documentDirectoryPath)
splitter := createMarkdownSplitter(splitterChunkSize, splitterChunkOverlap)
splittedDocuments := splitDocuments(splitter, documents)
embedClient := ollama.New(
  ollama.WithModel(embeddingModelName),
)
embedder := embeddings.NewEmbedder(embedClient)
store := chroma.New(
  chroma.WithChromaURL(databaseURL),
  chroma.WithNameSpace(databaseName),
  chroma.WithEmbedder(embedder),
  chroma.WithDistanceFunction(types.COSINE),
)
for i := 0; i < len(splittedDocuments); i += VECTOR_STORE_BATCH_SIZE {
  end := i + VECTOR_STORE_BATCH_SIZE
  if end > len(splittedDocuments) {
    end = len(splittedDocuments)
  }
  store.AddDocuments(ctx, splittedDocuments[i:end])
}

where

ollama refers to package github.com/tmc/langchaingo/llms/ollama,
embeddings refers to package github.com/tmc/langchaingo/embeddings, and
chroma refers to package github.com/tmc/langchaingo/chroma.

An example of invoking the CLI application is as follows.

$ rag load -f ~/notes/ -n notes

The above command loads markdown files in the directory ~/notes/ into Chroma database with collection name as notes.

Generate answers to questions

The steps taken to generate answers to questions are outlined in this diagram.

The first step is to retrieve relevant documents from the vector database Chroma previously created. The retrieval is done by using model to convert the question into a vector and the vector is then used by Chroma to find the closest vectors in the database. Chroma will then return the associated text and metadata of the closest vectors.

To ensure the quality of the response, the retrieved documents are graded by a model to filter out irrelevant retrievals. The model used in this grading is the same model which will be used to generate an answer. The grading is done by asking the grader to give a binary score of yes or no to indicate whether the document is relevant to the question.

The following system prompt is used in the grader to specify the role we want the model (grader) to play.

You are a grader assessing relevance of a retrieved document to a user question.
If the document contains keywords related to the user question,
grade it as relevant. It does not need to be a stringent test.
The goal is to filter out erroneous retrievals.
Give a binary score 'yes' or 'no' score to indicate whether the document is
relevant to the question.
Provide the binary score as a JSON with a single key 'score' and no premable or
explanation.

User’s question and the retrieved document are then passed to the model via user prompt. The model will then generate a response in the form of a JSON which contains the binary score and can be parsed in the code.

After the grading, the remaining relevant documents are then used to generate the response for an answer to the question from user. The system prompt used in this step to specify the role of the model is as follows.

You are an assistant for question-answering tasks.
Use the following pieces of retrieved documentation to answer the question.
Please write in full sentences with correct spelling and punctuation. If it
makes sense, use lists.
If the documentation does not contain the answer, just respond that you are
unable to find an answer.
Explain the reasoning as well.

One of the major problems with generative AI is . To reduce the chance of this problem, statement If the documentation does not contain the answer, just respond that you are unable to find an answer. is used in the system prompt to let the model knows that it should not be too “creative” when there is no relevant context to answer a question. Thus, with the above system prompt set, the model will answer “I don’t know” if there is no relevant documents retrieved from Chroma database.

The following code summarises the above process of generating an answer to a user’s question.

embedder := getEmbedder(embeddingModelName)
store := chroma.New(
  chroma.WithChromaURL(databaseURL),
  chroma.WithNameSpace(databaseName),
  chroma.WithEmbedder(embedder),
)
retriever := vectorstores.ToRetriever(
  store,
  NUM_DOCUMENTS_TO_BE_USED,
  vectorstores.WithScoreThreshold(DEFAULT_SEARCH_SCORE_THRESHOLD),
)

documents := retriever.GetRelevantDocuments(ctx, askOpts.question)
if len(documents) == 0 {
  fmt.Println("No reference documents found")
  return nil
}

llm := ollama.New(
  ollama.WithModel(modelName),
)
relevantDocuments := []schema.Document{}
for _, doc := range documents {
  graderSystemPrompt := `
    You are a grader assessing relevance of a retrieved document to a user question.
    If the document contains keywords related to the user question,
    grade it as relevant. It does not need to be a stringent test.
    The goal is to filter out erroneous retrievals.
    Give a binary score 'yes' or 'no' score to indicate whether the document is relevant to the question.
    Provide the binary score as a JSON with a single key 'score' and no premable or explanation.`
  graderUserPrompt := fmt.Sprintf("Here is the retrieved document: %s \n\nHere is the user question: %s", doc.PageContent, question)
  gradingResponse, err := llm.GenerateContent(
    ctx,
    []llms.MessageContent{
      {
        Role:  llms.ChatMessageTypeSystem,
        Parts: []llms.ContentPart{llms.TextContent{Text: graderSystemPrompt}},
      },
      {
        Role:  llms.ChatMessageTypeHuman,
        Parts: []llms.ContentPart{llms.TextContent{Text: graderUserPrompt}},
      },
    },
  )
  if err != nil {
    return fmt.Errorf("unable to grade reference document: %w", err)
  }
  var graderResponse GraderResponse
  errParse := jsonhelper.ParseJSONString(gradingResponse.Choices[0].Content, &graderResponse)
  if errParse != nil {
    return fmt.Errorf("unable to parse grading response: %w", errParse)
  }
  if graderResponse.Score == "yes" {
    relevantDocuments = append(relevantDocuments, doc)
  }
}

if len(relevantDocuments) == 0 {
  fmt.Println("No relevant documents found")
  return nil
}

fmt.Printf("About to answer your question using %d relevant document sections...\n\n\n", len(relevantDocuments))

systemPrompt := `
  You are an assistant for question-answering tasks.
  Use the following pieces of retrieved documentation to answer the question.
  Please write in full sentences with correct spelling and punctuation. if it makes sense use lists.
  If the documentation doen't contain the answer, just respond that you are unable to find an answer.
    Explain the reasoning as well.`
relevantTexts := make([]string, 0, len(relevantDocuments))
for _, doc := range relevantDocuments {
  relevantTexts = append(relevantTexts, doc.PageContent)
}
userPrompt := fmt.Sprintf("Documentation: %s \n\nQuestion: %s \n\nAnswer: ", strings.Join(relevantTexts, " ; "), question)
llm.GenerateContent(
  ctx,
  []llms.MessageContent{
    {
      Role: llms.ChatMessageTypeSystem,
      Parts: []llms.ContentPart{llms.TextContent{Text: systemPrompt}},
    },
    {
      Role: llms.ChatMessageTypeHuman,
      Parts: []llms.ContentPart{llms.TextContent{Text: userPrompt}},
    },
  },
  llms.WithStreamingFunc(func(_ context.Context, chunk []byte) error {
    fmt.Print(string(chunk))
    return nil
  }),
)

where

embeddingModelName is set as nomic-embed-text,
vectorstores refers to package github.com/tmc/langchaingo/embeddings
ollama refers to package github.com/tmc/langchaingo/llms/ollama
llms refers to package github.com/tmc/langchaingo/llms

The command built using the code above can be demonstrated by the following.

$ rag ask \
    -m llama3.1:8b \
    -n notes \
    -q "What is the best way to conduct an interview?"

where llama3.1:8b is the model used to generate an answer via Ollama API and notes is the collection of documents stored in Chroma database.

The End

As you can see, this CLI application allows me to ask questions against my latest version of notes without training any new models and using models running offline on my laptop. When there is a new version of notes, all I need to do is to rebuild the Chroma vector database which takes about a minute for 200 markdown files on a laptop.

This is only my first exploration into generative AI. Things like can be build using . Hopefully, I will be able to spend time and build more stuff in the near future. I will share my journey in my future posts.

Happy coding!

Code of the CLI can be found on .

Bubble Tea

Fri, 17 Feb 2023 16:00:00 +0800

My software development work is mostly done in a terminal. So I suppose it is natural that most of my tools are using a . Besides writing bash scripts, there are situations where I need to write CLI programs myself from time to time. In my day job of writing enterprise applications, I almost use C# and JavaScript exclusively. However, when it comes to writing CLI tools, Go is the language I preferred. There are many CLI frameworks written in Go but is the one I used most. It is also a framework used by many tools like kubectl.

cobra itself is a very powerful framework and, combining it with viper and pflag, it has pretty much all you need in terms of writing a command line program.

Using arguments or flags with a CLI program makes it easy to automate things. However, there are times that I will need to handle more complicated interactions between users and the program. These interactions can be done via a but cobra does not have any coverage on it. As you could probably guess by now, is the tool which can be integrated into cobra to allow building a TUI with such interactions.

is a TUI framework from and it does not contain any UI components. It can be used without UI components and developer will have to write the code responsible for rendering and behaviour. Luckily, as also provides a set of common UI components in repository and it can be used in programs.

CLI programs which I built with bubbletea usually start with cobra as not all workflows require a TUI (such as my-app login). Some of the commands requires a TUI and that is when code will be written to start a bubbletea program.

An example on command login with cobra.

func runLogin(_ *cobra.Command, _ []string) error {
	token, err := authhelper.GetToken()
	if err != nil {
		return err
	}
	fmt.Println("Login has been completed successfully")
	return nil
}

An example on command list (which is interactive) with cobra.

func runList(_ *cobra.Command, _ []string) error {
  config, err := getOAuthConfigurationFromViper()
  if err != nil {
    return err
  }
  client, err := api.NewClient(config.GetOAuthConfig())
  if err != nil {
    return err
  }
  items, err := client.ListItems()
  if err != nil {
    return err
  }

  columns := getItemColumns()
  rows := getRows(items)

  t := table.New(
    table.WithColumns(columns),
    table.WithRows(rows),
    table.WithFocused(true),
    table.WithHeight(displayRowCount),
  )

  t.SetStyles(getStyles())

  m := tableModel{
    apiClient: client,
    table:     t,
    data:      items,
    tableKeys: tableEventKeys,
    inputKeys: inputEventKeys,
    help:      help.New(),
  }

  if err := bubbleteahelper.SetupLogFile(logFilePath, logFilePrefix); err != nil {
    return err
  }

  if _, err := tea.NewProgram(m).Run(); err != nil {
    return err
  }
  return nil
}

As you can see in the example with command list, although there is a bit setup work to be done before starting bubbletea, it is no very involved and relatively easy. The above example retrieves data from an API and populate it into a table. We setup a table with column headers, data (items), number of rows to be displayed, key bindings (tableKeys and inputKeys). We also setup of bubbletea with a log file as we cannot print log lines into a terminal since bubbletea takes over the whole terminal screen most of the time. tea.NewProgram(m).Run() returns the final model (which contains states) being used in bubbletea but we are ignoring it in this example.

One of the nice things with bubbletea is that the architecture (or program flow) can be easily understood. It uses . The architecture is mostly used to generate HTML renderings and the data flow is shown below.

(illustration taken from )

To start a program tea.NewProgram(m), developer will have to supply a model and the model m implements the following interface.

type Model interface {
	// Init is the first function that will be called. It returns an optional
	// initial command. To not perform an initial command return nil.
	Init() Cmd

	// Update is called when a message is received. Use it to inspect messages
	// and, in response, update the model and/or send a command.
	Update(Msg) (Model, Cmd)

	// View renders the program's UI, which is just a string. The view is
	// rendered after every Update.
	View() string
}

We can ignore Init() and focus on Update() and View(). Update() processes input Msg from bubbletea framework (or “Elm Runtime” in the illustration). Msg is likely an event (such as a key event, a window resize event or a custom event representing a business event). Update() contains the logic to process Msg and determines the model Model and command Cmd to be returned. Model responsible for all things about a UI including states and behaviour. Therefore, Model returned from Update() represents the next UI to be presented to the user while Cmd is a function returning a Msg for the next UI (Model) to be processed in its Update(). Update() has access to Model and, thus, it is also responsible to update states in Model. View() will be invoked after Update() and it is responsible for drawing (or writing characters) to the terminal to create UI required.

An example on Model and its functions.

type dateInputModel struct {
	fieldDescription string
	itemName         string
	input            textinput.Model
	originalText     string
	err              error
	help             help.Model
	keys             inputKeyMap
	parent           tea.Model
}

func (m dateInputModel) Init() tea.Cmd { return nil }

// Update updates the states of the date input
func (m dateInputModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	var cmd tea.Cmd
	var cmds []tea.Cmd

	switch msg := msg.(type) {
	case tea.WindowSizeMsg:
		m.input.SetValue(m.originalText)
		m.input.Focus()
	case tea.KeyMsg:
		switch {
		case key.Matches(msg, m.keys.SaveAndExit):
			cmds = append(cmds, m.patchItem())
		case key.Matches(msg, m.keys.Cancel):
			return m.parent, showTable(nil)
		}
	case recordUpdated:
		return m.parent, showTable(msg.records)
	case errored:
		m.err = msg.err
	}

	m.input, cmd = m.input.Update(msg)
	cmds = append(cmds, cmd)
	return m, tea.Batch(cmds...)
}

// View renders the date input view
func (m dateInputModel) View() string {
	title := fmt.Sprintf("%s of '%s'", m.fieldDescription, m.itemName)
	errorMessage := ""
	if m.err != nil {
		errorMessage = m.err.Error()
	}

	return fmt.Sprintf(
		"%s\n\n%s\n\n%s%s\n",
		title,
		m.input.View(),
		getErrorMessageSection(errorMessage),
		m.help.View(m.keys),
	)
}

As you may be aware dateInputModel from the example above, a Model can contain multiple bubbles UI components (textinput.Model and help.Model in the example above) to help with rendering UI in View().

In Update() in the example above, besides it processes business messages recordUpdated and errored, it also processes key presses via tea.KeyMsg. As you can see in the switch statement followed, we can define keys to be handled in the UI. The following example shows how keys can be defined.

import "github.com/charmbracelet/bubbles/key"

func (k inputKeyMap) ShortHelp() []key.Binding {
	return []key.Binding{k.SaveAndExit, k.Cancel}
}

func (k inputKeyMap) FullHelp() [][]key.Binding {
	return [][]key.Binding{k.ShortHelp()}
}

var inputEventKeys = inputKeyMap{
	SaveAndExit: key.NewBinding(
		key.WithKeys("ctrl+s"),
		key.WithHelp("ctrl+s", "save and exit"),
	),
	Cancel: key.NewBinding(
		key.WithKeys("esc", "ctrl+c"),
		key.WithHelp("esc/ctrl+c", "cancel"),
	),
}

type inputKeyMap struct {
	SaveAndExit key.Binding
	Cancel      key.Binding
}

Package key from bubbles provides functionalities required to define keys. This allows naming of key bindings and assigning multiple keys to the same binding. It is also a nice feature that this allows defining help message for a binding.

is one of the most useful UI components is dealing with data. It is easy to setup table by calling its SetRows() with []Row where Row is just []string. We can also have key bindings previous example as show below.

With key bindings, we can provide actions to a table row and it makes interactions with or changes to a row possible. If you want, it is also possible to configure a table to allow multiple row selection which allows bulk action on selected rows. Table has a viewport included and that means height could be set to a table and, if not all rows of data fit into the table, scrolling will be enabled and it is a very nice UX.

is an UI component handling a number of items well. Each item can have its name and description.

Filtering on items before selection/de-selection is also possible. Each item in a list has to satisfy Item interface includes FilterValue() returning a string so that the list can use that value for filtering.

type Item interface {
	// Filter value is the value we use when filtering against this item when
	// we're filtering the list.
	FilterValue() string
}

// an implementation example
func (i listItem) FilterValue() string { return i.title }

Toggling of an item in a multi-select list can be done by adding a DefaultDelegate. (The following example does not allow toggling when multi-select is not enabled.)

type listSelectModel struct {
	fieldDescription   string
	originalSelections []string
	selections         []string
	multiSelect        bool
	itemName           string
	list               list.Model
	help               help.Model
	itemKeys           listMultiItemKeyMap
}

type listMultiItemKeyMap struct {
	ToggleSelection key.Binding
}

func newListSelectModel(fieldDescription string, originalSelections []string, selections []string, multiSelect bool, item string) listSelectModel {
	delegate := newListItemDelegate(listMultiItemEventKeys, multiSelect)
	newList := list.New(getListItems(selections, originalSelections), delegate, 0, 0)
	newList.Title = fmt.Sprintf("%s of '%s'", fieldDescription, item)
	return listSelectModel{
		fieldDescription:   fieldDescription,
		originalSelections: originalSelections,
		selections:         selections,
		multiSelect:        multiSelect,
		itemName:           item,
		list:               newList,
		help:               help.New(),
		itemKeys:           listMultiItemEventKeys,
	}
}

func newListItemDelegate(keys listMultiItemKeyMap, multiSelect bool) list.DefaultDelegate {
	d := list.NewDefaultDelegate()

	if !multiSelect {
		return d
	}

	d.UpdateFunc = func(msg tea.Msg, m *list.Model) tea.Cmd {
		switch msg := msg.(type) {
		case tea.KeyMsg:
			switch {
			case key.Matches(msg, keys.ToggleSelection):
				if i, ok := m.SelectedItem().(listItem); ok {
					i.selected = !i.selected
					return m.SetItem(m.Index(), i)
				}
				return nil
			}
		}
		return nil
	}

	d.ShortHelpFunc = func() []key.Binding { return keys.ShortHelp() }
	d.FullHelpFunc = func() [][]key.Binding { return keys.FullHelp() }

	return d
}

There are which we still have not explored here. I hope this gives a rough idea of what bubbletea and bubbles could do in writing CLI programs. If you want to learn more about it or products from visit .

I hope I will have time later to showcase more usages of the libraries. Until then, happy coding!

gum

Sun, 12 Feb 2023 22:00:00 +0800

I have been a full-time vim user for 5 years. Naturally, I’m also a heavy command line user and, even more naturally, I automate most of my workflows using commands in bash (sorry zsh). Writing scripts to automate stuff is fun. But there are times that I want to do stuff interactively with the shell especially workflow involving a number of parameters. One of the ways to go about it is writing a Go program. However, it could be too time-consuming even if I am proficient with writing Go. All I need is to glue different commands together. fzf is super handy when it comes to selections and it fits the use case of tmux very well. When it comes to things like asking for user input, presenting lines of data in a table or applying styles or formatting to output, there are not many good tools can be used with shell. Luckily, from can solve most of the problems mentioned here. It is an executable written in Go (and it also means it can be used in all major operating systems). charm.sh has a number of CLI tools created but we will focus only on gum in this post.

gum has a number of commands. choose, filter and file pretty much cover most of the functionalities in fzf and it probably has a nicer interface in terms of aesthetics. The usage of gum filter is very similar to fzf.

sha=$(gcloud builds list --limit 20 --format json \
  | jq -r '.[] | .substitutions.SHORT_SHA' \
  | fzf)

gum filter equivalent

sha=$(gcloud builds list --limit 20 --format json \
  | jq -r '.[] | .substitutions.SHORT_SHA' \
  | gum filter --limit=1)

Another example with multiple selections.

fd | fzf -m | xargs nvim

gum filter equivalent

fd | gum filter --no-limit | xargs nvim

The usage of gum choose is very similar to gum filter but slightly different in UI where it is tailored towards a selection of a smaller number of items and it does not have filtering functionality.

gum file is similar to running fzf in command line without any piped input.

The above commands are nice but it did not make me jumping to use gum. When I need to handle user input, gum input is really nice and it is something I cannot avoid anymore.

priority=$(gum input --placeholder "Enter priority" --value="$priority")

The above examples prompts user to input a priority number with a default number (supplied via $priority).

gum input also has masks built-in so that you can handle input like passwords.

gum write works in a very similar way to gum input but it handles multi-line input.

gum table is a super nice tool to present CSV data as a table in command line.

az sql mi list \
  | jq -r '.[] | .resourceGroup + "," + .name' \
  | gum table -c "Resource Group,Instance" -w 30,50

If option -c is not specified, it uses the first line of CSV as column headers. Option -w allows user to specify column widths (in number of characters).

One of the nice things with gum table is that it returns the selected row in CSV format. This allows further parsing of the selected data with commands like awk.

gum confirm has a nice interface in asking user to confirm before executing a command. For example,

gum confirm "Update keys?" &&\
  gcloud compute project-info add-metadata --metadata-from-file=ssh-keys=$key_file

gum style and gum format provides a lot of tools in allowing users to specify the aesthetics of the output.

echo IP address changed from $(gum style --foreground=#99000 $old_ip) to \
  $(gum style --foreground=#009900 $new_ip) in \
  $(gum style --foreground=#999900 $rg/$nsg/$rule) :+1: \
  | gum format -t emoji

For more practical examples, you can refer to the following files of bash functions.

There is also a videos tutorial from charm.sh.