example

Documentation

Overview

Package example provides few-shot example management for improving model performance through demonstration.

The example package implements a system for providing few-shot examples to language models, which can significantly improve their performance on specific tasks by showing examples of desired input-output patterns.

Core Components

The package provides:

• Example: Represents a single few-shot example with input and output
• Provider: Interface for retrieving relevant examples based on queries
• Formatting utilities for converting examples to model-readable format
• Integration with Vertex AI example stores

Basic Usage

Creating examples:

example := &example.Example{
	Input: &genai.Content{
		Parts: []genai.Part{genai.Text("What is the capital of France?")},
	},
	Output: []*genai.Content{{
		Parts: []genai.Part{genai.Text("The capital of France is Paris.")},
	}},
}

Using with providers:

provider := example.NewVertexAIProvider(client, "my-example-store")

examples, err := provider.GetExamples(ctx, "geography questions")
if err != nil {
	log.Fatal(err)
}

// Format examples for model
formatted := example.FormatExamples(examples)

Example Formatting

The package provides standardized formatting for examples:

<EXAMPLES>
Begin few-shot
The following are examples of user queries and model responses using the available tools.

EXAMPLE 1:
Begin example
[user]
What is the weather in Tokyo?

[model]
I'll check the weather in Tokyo for you.
```tool_code
weather_tool(city="Tokyo")
```
```tool_outputs
{"temperature": "22°C", "condition": "sunny"}
```
The weather in Tokyo is currently 22°C and sunny.
End example

End few-shot
<EXAMPLES>

Provider Interface

Implement the Provider interface to create custom example sources:

type CustomProvider struct {
	examples map[string][]*example.Example
}

func (p *CustomProvider) GetExamples(ctx context.Context, query string) ([]*example.Example, error) {
	// Retrieve relevant examples based on query
	return p.examples[query], nil
}

Vertex AI Integration

The package includes integration with Vertex AI example stores:

provider := example.NewVertexAIProvider(
	vertexClient,
	"projects/my-project/locations/us-central1/exampleStores/my-store",
)

// Retrieve examples based on semantic similarity
examples, err := provider.GetExamples(ctx, "technical documentation questions")

Tool Integration

Examples can include tool usage patterns:

toolExample := &example.Example{
	Input: &genai.Content{
		Parts: []genai.Part{genai.Text("Calculate 15% tip on $42.50")},
	},
	Output: []*genai.Content{{
		Parts: []genai.Part{
			genai.Text("I'll calculate the tip for you."),
			&genai.FunctionCall{
				Name: "calculator",
				Args: map[string]any{
					"expression": "42.50 * 0.15",
				},
			},
		},
	}},
}

Dynamic Example Selection

Providers can implement intelligent example selection:

func (p *SemanticProvider) GetExamples(ctx context.Context, query string) ([]*example.Example, error) {
	// Use embeddings to find most relevant examples
	embedding, err := p.embedQuery(ctx, query)
	if err != nil {
		return nil, err
	}

	// Search example store by similarity
	return p.searchBySimilarity(ctx, embedding, maxExamples)
}

Best Practices

1. Use 2-5 examples for most tasks (more examples = higher token usage)
2. Choose diverse examples that cover different input patterns
3. Ensure examples demonstrate the desired output format
4. Include both successful and edge case examples
5. Update examples based on model performance
6. Use semantic similarity for dynamic example selection

Performance Considerations

Few-shot examples impact:

• Token usage: Examples are included in every request
• Latency: More examples increase processing time
• Cost: Larger prompts cost more to process
• Accuracy: Good examples significantly improve performance

Balance the number and quality of examples based on your use case requirements.

Integration with Agents

Examples integrate with the agent system through instructions:

examples, _ := provider.GetExamples(ctx, "code review tasks")
formatted := example.FormatExamples(examples)

agent := agent.NewLLMAgent(ctx, "reviewer",
	agent.WithInstruction(fmt.Sprintf(`
		You are a code reviewer. Here are examples of good reviews:
		%s

		Now review the following code...
	`, formatted)),
)

This enables dynamic, context-aware example injection for improved agent performance.

Index

• Constants
• func BuildExampleSI[T any](ctx context.Context, examples T, query string, modelStr string) (string, error)
• func ConvertExamplesToText(examples []*Example, modelStr string) (string, error)
• type Example
• type Provider
• type VertexAIExampleStore
  • func NewVertexAIExampleStore(ctx context.Context, exampleStore string, opts ...option.ClientOption) (*VertexAIExampleStore, error)
  • func (e *VertexAIExampleStore) GetExamples(ctx context.Context, query string) ([]*Example, error)

Constants

const (
	ExamplesIntro          = "<EXAMPLES>\nBegin few-shot\nThe following are examples of user queries and model responses using the available tools.\n\n"
	ExamplesEnd            = "End few-shot\n<EXAMPLES>"
	ExampleStart           = "EXAMPLE %d:\nBegin example\n"
	ExampleEnd             = "End example\n\n"
	UserPrefix             = "[user]\n"
	ModelPrefix            = "[model]\n"
	FunctionPrefix         = "```\n"
	FunctionCallPrefix     = "```tool_code\n"
	FunctionCallSuffix     = "\n```\n"
	FunctionResponsePrefix = "```tool_outputs\n"
	FunctionResponseSuffix = "\n```\n"
)

Constant parts of the example string.

Functions

func BuildExampleSI

func BuildExampleSI[T any](ctx context.Context, examples T, query string, modelStr string) (string, error)

BuildExampleSI builds a system instruction string from examples.

func ConvertExamplesToText

func ConvertExamplesToText(examples []*Example, modelStr string) (string, error)

ConvertExamplesToText converts a list of examples to a string that can be used in a system instruction.

TODO(adk-python: yaojie): Add unit tests for this function.

Types

type Example

type Example struct {
	Input  *genai.Content
	Output []*genai.Content
}

Example represents a few-shot example.

type Provider

type Provider interface {
	GetExamples(ctx context.Context, query string) ([]*Example, error)
}

Provider represents a base interface for example providers.

This type defines the interface for providing examples for a given query.

type VertexAIExampleStore

type VertexAIExampleStore struct {
	// contains filtered or unexported fields
}

VertexAiExampleStore provides examples from Vertex example store.

func NewVertexAIExampleStore

func NewVertexAIExampleStore(ctx context.Context, exampleStore string, opts ...option.ClientOption) (*VertexAIExampleStore, error)

NewVertexAIExampleStore creates a new VertexAiExampleStore client from the given examplesStoreName.

examplesStoreName is the resource name of the vertex example store, in the format of

projects/{project}/locations/{location}/exampleStores/{example_store}

func (*VertexAIExampleStore) GetExamples

func (e *VertexAIExampleStore) GetExamples(ctx context.Context, query string) ([]*Example, error)

GetExamples returns the slice of *Example from Vertex AI example store for a given query.