feat(genai sdk): code samples (#5268)

* feat(genai sdk): generate text content from text prompt

* feat: update genai sdk version to 0.2.0

* feat: standardize error messages

* feat: text generation: generate from mute video

* feat: add http params to client init

* feat: text generation: generate from video w. sound

* feat: text generation: generate from audio input

* feat: text generation: generate an audio transcript

* update test desc

* wip: batch predict is unavailable in 0.2.0

* feat: text generation from  YT video input

* leave out wip for batch predict (not supporte by the sdk yet)

* feat: text generation: generate from local video input

* feat(genaisdk): text generation w. txt inputs and configs

* remove phase-shifted test

* add test input to index

* chore(genai sdk): update sdk version

* chore(genai sdk): update sdk version

* chore(genai sdk): update sdk version

* chore: migrate */test_data to */testdata to comply with the 'badfiles' test

* chore: migrate */test_data to */testdata to comply with the 'badfiles' test

* feat(genai sdk): text generation: generate using text and image inputs

* feat(genai sdk): generate text using tools

* feat(genai sdk): controlled text generation

* feat: generate with google search

* feat(genai sdk): count tokens: obtain usage metadata from model response

* feat: count tokens when using text prompt

* feat: count tokens with text and video inputs

* feat: compute with text input

* feat(genai sdk): content cache: create and update

* feat(genai sdk): content caching

* feat(genai sdk): text gen: batch 1

* chore: rename to match py samples naming convention

* chore: rename to match py samples naming convention

* chore: rename to match py samples naming convention

* chore: rename to match py samples naming convention

* chore: rename to match py samples naming convention

* chore: update genai sdk version

* update version

* go tidy

* update mod and sum

* testing file

* update testing file

* update testing

* update test file

* update testing file

* update testing

* adding testing png

* adding testing file

* adding testing file

* update header

* tidy

* updating testing

* update test

* updating files

* remove old samples

* removing examples

* update file

* update file

* tidy

* rerunning pipeline

* update test file

---------

Co-authored-by: Valeriy Burlaka <[email protected]>
Co-authored-by: Eric Schmidt <[email protected]>
Co-authored-by: Sampath Kumar <[email protected]>

Author: 4 people

Diff for: genai/content_cache/content_cache_test.go

@@ -0,0 +1,66 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package content_cache
+
+import (
+	"bytes"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/GoogleCloudPlatform/golang-samples/internal/testutil"
+)
+
+func TestContentCaching(t *testing.T) {
+	tc := testutil.SystemTest(t)
+
+	t.Setenv("GOOGLE_GENAI_USE_VERTEXAI", "1")
+	t.Setenv("GOOGLE_CLOUD_LOCATION", "us-central1")
+	t.Setenv("GOOGLE_CLOUD_PROJECT", tc.ProjectID)
+
+	buf := new(bytes.Buffer)
+
+	// 1) Create a content cache.
+	// The name of the cache resource created in this step will be used in the next test steps.
+	cacheName, err := createContentCache(buf)
+	if err != nil {
+		t.Fatalf("createContentCache: %v", err.Error())
+	}
+
+	// 2) Update the expiration time of the content cache.
+	err = updateContentCache(buf, cacheName)
+	if err != nil {
+		t.Errorf("updateContentCache: %v", err.Error())
+	}
+
+	// 3) Use cached content with a text prompt.
+	err = useContentCacheWithTxt(buf, cacheName)
+	if err != nil {
+		t.Errorf("useContentCacheWithTxt: %v", err.Error())
+	}
+
+	// 4) Delete the content cache.
+	buf.Reset()
+	err = deleteContentCache(buf, cacheName)
+	if err != nil {
+		t.Errorf("deleteContentCache: %v", err.Error())
+	}
+
+	exp := fmt.Sprintf("Deleted cache %q", cacheName)
+	act := buf.String()
+	if !strings.Contains(act, exp) {
+		t.Errorf("deleteContentCache: got %q, want %q", act, exp)
+	}
+}

Diff for: genai/content_cache/contentcache_create_with_txt_gcs_pdf.go

@@ -0,0 +1,102 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package content_cache shows examples of using content caching with the GenAI SDK.
+package content_cache
+
+// [START googlegenaisdk_contentcache_create_with_txt_gcs_pdf]
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+
+	genai "google.golang.org/genai"
+)
+
+// createContentCache shows how to create a content cache with an expiration parameter.
+func createContentCache(w io.Writer) (string, error) {
+	ctx := context.Background()
+
+	client, err := genai.NewClient(ctx, &genai.ClientConfig{
+		HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta1"},
+	})
+	if err != nil {
+		return "", fmt.Errorf("failed to create genai client: %w", err)
+	}
+
+	modelName := "gemini-2.0-flash-001"
+
+	systemInstruction := "You are an expert researcher. You always stick to the facts " +
+		"in the sources provided, and never make up new facts. " +
+		"Now look at these research papers, and answer the following questions."
+
+	cacheContents := []*genai.Content{
+		{
+			Parts: []*genai.Part{
+				{FileData: &genai.FileData{
+					FileURI:  "gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf",
+					MIMEType: "application/pdf",
+				}},
+				{FileData: &genai.FileData{
+					FileURI:  "gs://cloud-samples-data/generative-ai/pdf/2403.05530.pdf",
+					MIMEType: "application/pdf",
+				}},
+			},
+			Role: "user",
+		},
+	}
+	config := &genai.CreateCachedContentConfig{
+		Contents: cacheContents,
+		SystemInstruction: &genai.Content{
+			Parts: []*genai.Part{
+				{Text: systemInstruction},
+			},
+		},
+		DisplayName: "example-cache",
+		TTL:         "86400s",
+	}
+
+	res, err := client.Caches.Create(ctx, modelName, config)
+	if err != nil {
+		return "", fmt.Errorf("failed to create content cache: %w", err)
+	}
+
+	cachedContent, err := json.MarshalIndent(res, "", "  ")
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal cache info: %w", err)
+	}
+
+	// See the documentation: https://pkg.go.dev/google.golang.org/genai#CachedContent
+	fmt.Fprintln(w, string(cachedContent))
+
+	// Example response:
+	// {
+	//   "name": "projects/111111111111/locations/us-central1/cachedContents/1111111111111111111",
+	//   "displayName": "example-cache",
+	//   "model": "projects/111111111111/locations/us-central1/publishers/google/models/gemini-1.5-pro-002",
+	//   "createTime": "2025-02-18T15:05:08.29468Z",
+	//   "updateTime": "2025-02-18T15:05:08.29468Z",
+	//   "expireTime": "2025-02-19T15:05:08.280828Z",
+	//   "usageMetadata": {
+	//     "imageCount": 167,
+	//     "textCount": 153,
+	//     "totalTokenCount": 43125
+	//   }
+	// }
+
+	return res.Name, nil
+}
+
+// [END googlegenaisdk_contentcache_create_with_txt_gcs_pdf]

Diff for: genai/content_cache/contentcache_delete.go

@@ -0,0 +1,51 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package content_cache shows examples of using content caching with the GenAI SDK.
+package content_cache
+
+// [START googlegenaisdk_contentcache_update]
+import (
+	"context"
+	"fmt"
+	"io"
+
+	genai "google.golang.org/genai"
+)
+
+// deleteContentCache shows how to delete content cache.
+func deleteContentCache(w io.Writer, cacheName string) error {
+	ctx := context.Background()
+
+	client, err := genai.NewClient(ctx, &genai.ClientConfig{
+		HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta1"},
+	})
+	if err != nil {
+		return fmt.Errorf("failed to create genai client: %w", err)
+	}
+
+	_, err = client.Caches.Delete(ctx, cacheName, &genai.DeleteCachedContentConfig{})
+	if err != nil {
+		return fmt.Errorf("failed to delete content cache: %w", err)
+	}
+
+	fmt.Fprintf(w, "Deleted cache %q\n", cacheName)
+
+	// Example response:
+	// Deleted cache "projects/111111111111/locations/us-central1/cachedContents/1111111111111111111"
+
+	return nil
+}
+
+// [END googlegenaisdk_contentcache_update]

Diff for: genai/content_cache/contentcache_update.go

@@ -0,0 +1,67 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package content_cache shows examples of using content caching with the GenAI SDK.
+package content_cache
+
+// [START googlegenaisdk_contentcache_update]
+import (
+	"context"
+	"fmt"
+	"io"
+	"time"
+
+	genai "google.golang.org/genai"
+)
+
+// updateContentCache shows how to update content cache expiration time.
+func updateContentCache(w io.Writer, cacheName string) error {
+	ctx := context.Background()
+
+	client, err := genai.NewClient(ctx, &genai.ClientConfig{
+		HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta1"},
+	})
+	if err != nil {
+		return fmt.Errorf("failed to create genai client: %w", err)
+	}
+
+	// Update expire time using TTL
+	resp, err := client.Caches.Update(ctx, cacheName, &genai.UpdateCachedContentConfig{
+		TTL: "36000s",
+	})
+	if err != nil {
+		return fmt.Errorf("failed to update content cache exp. time with TTL: %w", err)
+	}
+
+	fmt.Fprintf(w, "Cache expires in: %s\n", time.Until(*resp.ExpireTime))
+	// Example response:
+	// Cache expires in: 10h0m0.005875s
+
+	// Update expire time using specific time stamp
+	inSevenDays := time.Now().Add(7 * 24 * time.Hour)
+	resp, err = client.Caches.Update(ctx, cacheName, &genai.UpdateCachedContentConfig{
+		ExpireTime: &inSevenDays,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to update content cache expire time: %w", err)
+	}
+
+	fmt.Fprintf(w, "Cache expires in: %s\n", time.Until(*resp.ExpireTime))
+	// Example response:
+	// Cache expires in: 167h59m59.80327s
+
+	return nil
+}
+
+// [END googlegenaisdk_contentcache_update]

Diff for: genai/content_cache/contentcache_use_with_txt.go

@@ -0,0 +1,65 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package content_cache shows examples of using content caching with the GenAI SDK.
+package content_cache
+
+// [START googlegenaisdk_contentcache_use_with_txt]
+import (
+	"context"
+	"fmt"
+	"io"
+
+	genai "google.golang.org/genai"
+)
+
+// useContentCacheWithTxt shows how to use content cache to generate text content.
+func useContentCacheWithTxt(w io.Writer, cacheName string) error {
+	ctx := context.Background()
+
+	client, err := genai.NewClient(ctx, &genai.ClientConfig{
+		HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta1"},
+	})
+	if err != nil {
+		return fmt.Errorf("failed to create genai client: %w", err)
+	}
+
+	resp, err := client.Models.GenerateContent(ctx,
+		"gemini-2.0-flash-001",
+		genai.Text("Summarize the pdfs"),
+		&genai.GenerateContentConfig{
+			CachedContent: cacheName,
+		},
+	)
+	if err != nil {
+		return fmt.Errorf("failed to use content cache to generate content: %w", err)
+	}
+
+	respText, err := resp.Text()
+	if err != nil {
+		return fmt.Errorf("failed to convert model response to text: %w", err)
+	}
+	fmt.Fprintln(w, respText)
+
+	// Example response:
+	// The provided research paper introduces Gemini 1.5 Pro, a multimodal model capable of recalling
+	// and reasoning over information from very long contexts (up to 10 million tokens).  Key findings include:
+	//
+	// * **Long Context Performance:**
+	// ...
+
+	return nil
+}
+
+// [END googlegenaisdk_contentcache_use_with_txt]