### Run a Go Example

Source: https://github.com/teilomillet/gollm/blob/main/examples/README.md

Execute a specific gollm example script using the `go run` command. Navigate to the examples directory first.

```bash
go run 1_basic_usage.go
```

--------------------------------

### Load Examples from File in Go

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Load examples from a file to provide context for prompt generation. Ensure the file exists and is correctly formatted. Handles potential errors during file reading and LLM generation.

```go
examples, err := utils.ReadExamplesFromFile("examples.txt")
if err != nil {
    log.Fatalf("Failed to read examples: %v", err)
}

prompt := gollm.NewPrompt("Generate a similar example:",
    gollm.WithExamples(examples...),
)

response, err := llm.Generate(ctx, prompt)
if err != nil {
    log.Fatalf("Failed to generate example: %v", err)
}
fmt.Printf("Generated Example:\n%s\n", response)
```

--------------------------------

### Run GoLLM OpenRouter Example

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Execute the main Go program for the OpenRouter example. The API key can be provided via environment variable or directly as a flag.

```bash
go run main.go
```

```bash
go run main.go -key="your_api_key_here"
```

--------------------------------

### Run the Structured Caching Example

Source: https://github.com/teilomillet/gollm/blob/main/examples/caching_structured/README.md

Executes the Go example program that demonstrates structured message caching.

```bash
# Run the example
go run examples/caching_structured/main.go
```

--------------------------------

### Basic Test Setup

Source: https://github.com/teilomillet/gollm/blob/main/assess/README.md

Sets up a new test with a specific provider and adds a simple query case with a timeout and validation.

```go
func TestBasic(t *testing.T) {
    test := testing.NewTest(t).
        WithProvider("anthropic", "claude-3-5-haiku-latest")

    test.AddCase("simple_query", "What is 2+2?").
        WithTimeout(30 * time.Second).
        Validate(ExpectContains("4"))

    ctx := context.Background()
    test.Run(ctx)
}
```

--------------------------------

### Complete Example: Custom Local Provider

Source: https://github.com/teilomillet/gollm/blob/main/docs/custom_providers.md

This Go code demonstrates a full implementation of a custom provider for a local LLM server, including registration and usage.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "strings"
    
    "github.com/teilomillet/gollm"
    "github.com/teilomillet/gollm/config"
    "github.com/teilomillet/gollm/providers"
    "github.com/teilomillet/gollm/utils"
)

// LocalProvider is a custom provider for a local LLM server
type LocalProvider struct {
    serverURL    string
    extraHeaders map[string]string
    options      map[string]interface{}
    logger       utils.Logger
}

// NewLocalProvider creates a new provider for a local LLM
func NewLocalProvider(apiKey, model string, extraHeaders map[string]string) providers.Provider {
    // In this case, we use apiKey parameter as the server URL
    serverURL := apiKey
    if serverURL == "" {
        serverURL = "http://localhost:8080/generate" // Default
    }
    
    return &LocalProvider{
        serverURL:    serverURL,
        extraHeaders: extraHeaders,
        options:      map[string]interface{}{"model": model},
        logger:       utils.NewLogger(utils.LogLevelInfo),
    }
}

// Name returns the provider identifier
func (p *LocalProvider) Name() string {
    return "local"
}

// Endpoint returns the API endpoint
func (p *LocalProvider) Endpoint() string {
    return p.serverURL
}

// Headers returns HTTP headers for requests
func (p *LocalProvider) Headers() map[string]string {
    headers := map[string]string{
        "Content-Type": "application/json",
    }
    
    for k, v := range p.extraHeaders {
        headers[k] = v
    }
    
    return headers
}

// PrepareRequest creates the request body
func (p *LocalProvider) PrepareRequest(prompt string, options map[string]interface{}) ([]byte, error) {
    request := map[string]interface{}{
        "prompt": prompt,
    }
    
    // Add all options
    for k, v := range p.options {
        request[k] = v
    }
    
    for k, v := range options {
        request[k] = v
    }
    
    return json.Marshal(request)
}

// ParseResponse extracts text from response
func (p *LocalProvider) ParseResponse(body []byte) (string, error) {
    var response struct {
        Text  string `json:"text"`
        Error string `json:"error"`
    }
    
    if err := json.Unmarshal(body, &response); err != nil {
        return "", fmt.Errorf("failed to parse response: %v", err)
    }
    
    if response.Error != "" {
        return "", fmt.Errorf("API error: %s", response.Error)
    }
    
    return response.Text, nil
}

// Implement other required methods...

// Register the provider
func init() {
    providers.GetDefaultRegistry().Register("local", NewLocalProvider)
}

func main() {
    // Now use your custom provider
    llm, err := gollm.NewLLM(
        config.SetProvider("local"),
        config.SetAPIKey("http://localhost:8080/generate"), // URL as the API key
        config.SetModel("llama2"),
    )
    
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    ctx := context.Background()
    prompt := gollm.NewPrompt("Explain quantum computing")
    
    response, err := llm.Generate(ctx, prompt)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    fmt.Println(response)
}
```

--------------------------------

### Install gollm Package

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Use this command to add the gollm package to your Go project.

```bash
go get github.com/teilomillet/gollm
```

--------------------------------

### Set API Keys via .env File

Source: https://github.com/teilomillet/gollm/blob/main/examples/README.md

Alternatively, create a .env file in the examples directory to store your LLM provider API keys. This is useful for managing keys locally.

```bash
OPENAI_API_KEY=your_api_key_here
ANTHROPIC_API_KEY=your_api_key_here
GROQ_API_KEY=your_api_key_here
```

--------------------------------

### Create LLM Instance with NewLLM

Source: https://context7.com/teilomillet/gollm/llms.txt

Create a new LLM instance using NewLLM and configure it with various options. This example demonstrates setting the provider, model, API key, and generation parameters.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/teilomillet/gollm"
)

func main() {
    llm, err := gollm.NewLLM(
        gollm.SetProvider("openai"),
        gollm.SetModel("gpt-4o-mini"),
        gollm.SetAPIKey(os.Getenv("OPENAI_API_KEY")),
        gollm.SetMaxTokens(500),
        gollm.SetTemperature(0.7),
        gollm.SetMaxRetries(3),
        gollm.SetRetryDelay(time.Second*2),
        gollm.SetLogLevel(gollm.LogLevelInfo),
    )
    if err != nil {
        log.Fatalf("Failed to create LLM: %v", err)
    }

    ctx := context.Background()
    prompt := gollm.NewPrompt("Explain the concept of recursion in programming.")
    response, err := llm.Generate(ctx, prompt)
    if err != nil {
        log.Fatalf("Failed to generate: %v", err)
    }
    fmt.Println(response)
}
```

--------------------------------

### Create and Use a New LLM Instance (OpenAI)

Source: https://github.com/teilomillet/gollm/blob/main/docs/provider_system.md

Instantiate an LLM client using the `gollm.NewLLM` function with provider-specific configurations. Ensure you have the necessary imports for `context`, `gollm`, and `config`. This example shows basic usage with an OpenAI-compatible provider.

```go
import (
    "context"
    "github.com/teilomillet/gollm"
    "github.com/teilomillet/gollm/config"
)

// Create an LLM instance
llm, err := gollm.NewLLM(
    config.SetProvider("openai"),
    config.SetAPIKey("your-api-key"),
    config.SetModel("gpt-4"),
)

// Use it as before
ctx := context.Background()
prompt := gollm.NewPrompt("Explain quantum computing in simple terms")
response, err := llm.Generate(ctx, prompt)
```

--------------------------------

### Creating a Prompt with Advanced Options

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Shows how to create a prompt object with additional context, directives, expected output format, and maximum length. Useful for guiding the LLM's response more precisely.

```go
prompt := gollm.NewPrompt("Your prompt text here",
    gollm.WithContext("Additional context"),
    gollm.WithDirectives("Be concise", "Use examples"),
    gollm.WithOutput("Expected output format"),
    gollm.WithMaxLength(300),
)
```

--------------------------------

### Set OpenRouter API Key

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Set your OpenRouter API key as an environment variable before running the example.

```bash
export OPENROUTER_API_KEY="your_api_key_here"
```

--------------------------------

### LLM Client Configuration Options

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Illustrates different ways to configure an LLM client, including specifying the provider, model, API key, token limits, temperature, and memory. Shows examples for OpenAI and OpenRouter, including setting fallback models.

```go
// Using OpenAI
llm, err := gollm.NewLLM(
    gollm.SetProvider("openai"),
    gollm.SetModel("gpt-4"),
    gollm.SetAPIKey("your-api-key"),
    gollm.SetMaxTokens(100),
    gollm.SetTemperature(0.7),
    gollm.SetMemory(4096),
)
```

```go
// Using OpenRouter (with model fallback)
llm, err := gollm.NewLLM(
    gollm.SetProvider("openrouter"),
    gollm.SetModel("anthropic/claude-3-5-sonnet"),
    gollm.SetAPIKey("your-openrouter-api-key"),
    gollm.SetMaxTokens(500),
)
// Enable fallback models if primary model is unavailable
llm.SetOption("fallback_models", []string{"openai/gpt-4o", "mistral/mistral-large"})
// Or use OpenRouter's auto-routing capability
// llm.SetOption("auto_route", true)
```

--------------------------------

### Set API Keys via Environment Variables

Source: https://github.com/teilomillet/gollm/blob/main/examples/README.md

Set your LLM provider API keys as environment variables before running examples. Ensure you replace 'your_api_key_here' with your actual keys.

```bash
export OPENAI_API_KEY=your_api_key_here
export ANTHROPIC_API_KEY=your_api_key_here
export GROQ_API_KEY=your_api_key_here
```

--------------------------------

### Run Tests in gollm Project

Source: https://github.com/teilomillet/gollm/blob/main/CONTRIBUTING.md

Execute all tests in the project except those in the examples directory. This command ensures your changes do not break existing functionality.

```bash
go test -v (go list ./... | grep -v /examples)
```

--------------------------------

### System Prompts

Source: https://github.com/teilomillet/gollm/blob/main/assess/README.md

Configures a test case to use a system prompt, guiding the LLM's behavior for a specific task.

```go
test.AddCase("with_system_prompt", "Analyze this code").
    WithSystemPrompt("You are an expert code reviewer").
    WithTimeout(45 * time.Second)
```

--------------------------------

### Add Messages to Memory with Cache Control

Source: https://github.com/teilomillet/gollm/blob/main/examples/caching_structured/README.md

Demonstrates adding messages to memory. The first example adds a regular message without specific cache instructions. The second example uses `AddStructuredMessage` with 'ephemeral' cache control.

```go
// Regular message addition (no cache control)
memLLM.AddToMemory("user", "Hello, how are you?")

// Message with cache control
memLLM.AddStructuredMessage("user", "Tell me about machine learning", "ephemeral")
```

--------------------------------

### Dynamically Configure Azure OpenAI Endpoint

Source: https://github.com/teilomillet/gollm/blob/main/docs/provider_system.md

Get the 'azure-openai' provider from the registry and dynamically set its endpoint if it's a GenericProvider.

```go
// Get the provider from the registry
registry := providers.GetDefaultRegistry()
provider, err := registry.Get("azure-openai", apiKey, model, extraHeaders)

// Check if it's a GenericProvider and set the endpoint
if genericProvider, ok := provider.(*providers.GenericProvider); ok {
    genericProvider.SetEndpoint("https://custom-endpoint.com/api")
}
```

--------------------------------

### Optimizing Prompts with a Prompt Optimizer

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Demonstrates how to initialize and use a `PromptOptimizer` to refine prompts based on a task description and custom metrics. Allows for setting a rating system and threshold for optimization.

```go
optimizer := optimizer.NewPromptOptimizer(llm, initialPrompt, taskDescription,
    optimizer.WithCustomMetrics(/* custom metrics */),
    optimizer.WithRatingSystem("numerical"),
    optimizer.WithThreshold(0.8),
)
optimizedPrompt, err := optimizer.OptimizePrompt(ctx)
```

--------------------------------

### Basic LLM Initialization and Text Generation in Go

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Demonstrates how to initialize an LLM client with custom settings (provider, model, API key, token limits, retries, logging) and generate text based on a prompt. Requires the OPENAI_API_KEY environment variable to be set.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/teilomillet/gollm"
)

func main() {
    // Load API key from environment variable
    apiKey := os.Getenv("OPENAI_API_KEY")
    if apiKey == ""
        log.Fatalf("OPENAI_API_KEY environment variable is not set")
    }

    // Create a new LLM instance with custom configuration
    llm, err := gollm.NewLLM(
        gollm.SetProvider("openai"),
        gollm.SetModel("gpt-4o-mini"),
        gollm.SetAPIKey(apiKey),
        gollm.SetMaxTokens(200),
        gollm.SetMaxRetries(3),
        gollm.SetRetryDelay(time.Second*2),
        gollm.SetLogLevel(gollm.LogLevelInfo),
    )
    if err != nil {
        log.Fatalf("Failed to create LLM: %v", err)
    }

    ctx := context.Background()

    // Create a basic prompt
    prompt := gollm.NewPrompt("Explain the concept of 'recursion' in programming.")

    // Generate a response
    response, err := llm.Generate(ctx, prompt)
    if err != nil {
        log.Fatalf("Failed to generate text: %v", err)
    }
    fmt.Printf("Response:\n%s\n", response)
}
```

--------------------------------

### Set Anthropic API Key

Source: https://github.com/teilomillet/gollm/blob/main/examples/caching_structured/README.md

Sets the Anthropic API key as an environment variable. This is required before running the Go example.

```bash
# Set your API key
export ANTHROPIC_API_KEY=your_api_key_here
```

--------------------------------

### Get Default Headers

Source: https://github.com/teilomillet/gollm/blob/main/assess/README.md

Retrieves the default headers automatically set for a given provider. This is for informational purposes as the framework handles this internally.

```go
// Headers are automatically set based on provider
headers := getDefaultHeaders("anthropic")
// Returns: {"anthropic-beta": "prompt-caching-2024-07-31"}
```

--------------------------------

### Create Structured Prompt with Options

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Use NewPrompt() with options like WithContext(), WithDirectives(), and WithOutput() to create well-structured prompts for consistent generation.

```go
prompt := gollm.NewPrompt("Your main prompt here",
    gollm.WithContext("Provide relevant context"),
    gollm.WithDirectives("Be concise", "Use examples"),
    gollm.WithOutput("Specify expected output format"),
)
```

--------------------------------

### Manage LLM Memory

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Check if memory is enabled, get current conversation history, add messages manually, or clear the entire conversation history.

```go
// Check if memory is enabled
if llm.HasMemory() {
    // Get current conversation history
    messages := llm.GetMemory()

    // Add a message manually
    llm.AddToMemory("user", "Remember this context")

    // Clear conversation history
    llm.ClearMemory()
}
```

--------------------------------

### Run the Go Application

Source: https://github.com/teilomillet/gollm/blob/main/docs/azure_openai_quickstart.md

Execute the Go application from the command line.

```bash
go run main.go
```

--------------------------------

### Get Test Metrics

Source: https://github.com/teilomillet/gollm/blob/main/assess/README.md

Retrieves and prints various performance metrics collected during test execution, such as average response time, cache hit rate, and error rate.

```go
metrics := test.GetMetrics()
fmt.Printf("Average response time: %v\n", metrics.AverageResponseTime())
fmt.Printf("Cache hit rate: %v%%\n", metrics.CacheHitRate())
fmt.Printf("Error rate: %v%%\n", metrics.ErrorRate())
```

--------------------------------

### Build All Go Packages

Source: https://github.com/teilomillet/gollm/blob/main/AGENTS.md

Use this command to build all packages within the Go project. Ensure you are in the project's root directory.

```bash
go build ./...
```

--------------------------------

### Configure Additional LLM Options for Azure OpenAI

Source: https://github.com/teilomillet/gollm/blob/main/docs/azure_openai_quickstart.md

Demonstrates how to set additional configuration options like temperature, max tokens, and log level when creating the LLM instance for Azure OpenAI.

```go
llm, err := gollm.NewLLM(
    config.SetProvider("azure-openai"),
    config.SetAPIKey(apiKey),
    config.SetModel(deploymentName),
    config.SetExtraHeaders(map[string]string{
        "azure_endpoint": endpoint,
    }),
    config.SetTemperature(0.7),
    config.SetMaxTokens(500),
    config.SetLogLevel(gollm.LogLevelDebug),
)
```

--------------------------------

### Basic OpenRouter Text Generation

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Initialize the GoLLM client with the OpenRouter provider and perform basic text generation. Specify the model, temperature, and max tokens.

```go
llm, err := gollm.NewLLM(
    gollm.SetProvider("openrouter"),
    gollm.SetAPIKey(apiKey),
    gollm.SetModel("anthropic/claude-3-5-sonnet"),
    gollm.SetTemperature(0.7),
    gollm.SetMaxTokens(1000),
)

prompt := gollm.NewPrompt("What are the main features of OpenRouter?")
response, err := llm.Generate(ctx, prompt)
```

--------------------------------

### Advanced Prompt Engineering with Directives and Context

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Illustrates creating a detailed prompt for explaining recursion, including specific directives, context for the target audience, desired output structure, and a maximum length. This is useful for complex or nuanced requests.

```go
prompt := gollm.NewPrompt(
    "Explain the concept of recursion in programming",
    gollm.WithDirectives(
        "Be concise and clear", 
        "Include code examples in multiple languages",
        "Provide a practical example.",
    ),
    gollm.WithContext("This is for a beginner programmer who is just starting to learn."),
    gollm.WithOutput("Structure your response with sections: Definition, Example, Pitfalls, Best Practices."),
    gollm.WithMaxLength(1000),
)
```

--------------------------------

### Chain-of-Thought Reasoning with presets.ChainOfThought

Source: https://context7.com/teilomillet/gollm/llms.txt

Utilize the ChainOfThought preset to instruct the LLM to break down problems into logical steps before providing a final answer. This preset supports standard prompt options like context and examples.

```go
import (
    "github.com/teilomillet/gollm"
    "github.com/teilomillet/gollm/presets"
)

llm, _ := gollm.NewLLM(gollm.SetProvider("openai"), gollm.SetModel("gpt-4o-mini"),
    gollm.SetAPIKey(os.Getenv("OPENAI_API_KEY")),
    gollm.SetMaxTokens(500))

question := "How might climate change affect global agriculture over the next 50 years?"

response, err := presets.ChainOfThought(ctx, llm, question,
    gollm.WithMaxLength(400),
    gollm.WithContext("Climate change is causing global temperature increases and changing precipitation patterns."),
    gollm.WithExamples("Effect: Shifting growing seasons, Adaptation: Developing heat-resistant crops"),
    gollm.WithDirectives(
        "Break the problem into steps",
        "Show your reasoning for each step",
        "Conclude with actionable recommendations",
    ),
)
if err != nil {
    log.Fatal(err)
}
fmt.Println(response)
```

--------------------------------

### Enable OpenRouter Reasoning Tokens

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Enable reasoning tokens to obtain step-by-step thinking from the model during generation.

```go
llm.SetOption("enable_reasoning", true)
```

--------------------------------

### Reusable Dynamic Prompts with PromptTemplate

Source: https://context7.com/teilomillet/gollm/llms.txt

Create reusable prompt blueprints using Go templates. Templates ensure consistent behavior by sharing options like directives and output format across all rendered prompts.

```go
analysisTemplate := gollm.NewPromptTemplate(
    "TopicAnalysis",
    "Analyzes a topic from multiple perspectives",
    "Provide a comprehensive analysis of {{.Topic}} covering:\n"+
        "1. Historical context\n"+
        "2. Current relevance\n"+
        "3. Future implications",
    gollm.WithPromptOptions(
        gollm.WithDirectives(
            "Use clear, concise language",
            "Provide specific examples where appropriate",
        ),
        gollm.WithOutput("Structure your analysis with clear headings for each section."),
        gollm.WithMaxLength(600),
    ),
)

prompt, err := analysisTemplate.Execute(map[string]interface{}{
    "Topic": "artificial intelligence in healthcare",
})
if err != nil {
    log.Fatal(err)
}

response, err := llm.Generate(context.Background(), prompt)
if err != nil {
    log.Fatal(err)
}
fmt.Println(response)
```

--------------------------------

### Run OpenRouter Integration Tests with main.go

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Verify OpenRouter provider functionality using the main.go script with the -test flag. The API key can be set via environment variable or a flag.

```bash
# Using environment variable
export OPENROUTER_API_KEY="your_api_key_here"
go run main.go -test

# Or providing the key directly
go run main.go -test -key="your_api_key_here"
```

--------------------------------

### Complete Azure OpenAI Integration with Gollm

Source: https://github.com/teilomillet/gollm/blob/main/docs/azure_openai_quickstart.md

This Go code initializes the Azure OpenAI client using environment variables, constructs the endpoint, creates an LLM instance, and generates a response to a prompt.

```go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/teilomillet/gollm"
	"github.com/teilomillet/gollm/config"
)

func main() {
	// Get configuration from environment
	apiKey := os.Getenv("AZURE_OPENAI_API_KEY")
	resourceName := os.Getenv("AZURE_OPENAI_RESOURCE_NAME")
	deploymentName := os.Getenv("AZURE_OPENAI_DEPLOYMENT_NAME")
	apiVersion := os.Getenv("AZURE_OPENAI_API_VERSION")
	
	if apiKey == "" || resourceName == "" || deploymentName == "" {
		fmt.Println("Error: Missing required environment variables")
		fmt.Println("Please set: AZURE_OPENAI_API_KEY, AZURE_OPENAI_RESOURCE_NAME, AZURE_OPENAI_DEPLOYMENT_NAME")
		os.Exit(1)
	}
	
	if apiVersion == "" {
		apiVersion = "2023-05-15" // Default value
	}
	
	// Create the endpoint URL
	endpoint := fmt.Sprintf(
		"https://%s.openai.azure.com/openai/deployments/%s/chat/completions?api-version=%s", 
		resourceName, deploymentName, apiVersion,
	)
	
	// Create the LLM instance
	llm, err := gollm.NewLLM(
		config.SetProvider("azure-openai"),
		config.SetAPIKey(apiKey),
		config.SetModel(deploymentName),
		config.SetExtraHeaders(map[string]string{
			"azure_endpoint": endpoint,
		}),
	)
	
	if err != nil {
		fmt.Printf("Error creating LLM: %v\n", err)
		os.Exit(1)
	}
	
	// Create a prompt
	ctx := context.Background()
	prompt := gollm.NewPrompt("Explain what Azure OpenAI Service is in 3 sentences.")
	
	// Generate a response
	response, err := llm.Generate(ctx, prompt)
	if err != nil {
		fmt.Printf("Error generating response: %v\n", err)
		os.Exit(1)
	}
	
	// Print the response
	fmt.Println("Response from Azure OpenAI:")
	fmt.Println(response)
}
```

--------------------------------

### Structured Prompt Construction with NewPrompt

Source: https://context7.com/teilomillet/gollm/llms.txt

Construct a detailed prompt using NewPrompt and functional options to specify system prompts, context, directives, output format, and maximum length.

```go
prompt := gollm.NewPrompt(
    "Explain the concept of blockchain technology",
    gollm.WithSystemPrompt("You are a technical educator.", gollm.CacheTypeEphemeral),
    gollm.WithContext("The audience is composed of software engineers with no prior blockchain experience."),
    gollm.WithDirectives(
        "Use a simple analogy to illustrate the concept",
        "Highlight key features: immutability, decentralization, consensus",
        "Mention two real-world applications",
    ),
    gollm.WithOutput("Structure your response with: Definition, Analogy, Key Features, Applications."),
    gollm.WithMaxLength(400),
)

response, err := llm.Generate(context.Background(), prompt)
if err != nil {
    log.Fatal(err)
}
fmt.Println(response)
```

--------------------------------

### Comparing LLM Model Performance

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Shows how to use the `CompareModels` utility function to evaluate and compare the performance of different LLM models for a given prompt and validation function.

```go
results, err := tools.CompareModels(ctx, promptText, validateFunc, configs...)
```

--------------------------------

### Register a GenericProvider Configuration

Source: https://github.com/teilomillet/gollm/blob/main/docs/custom_providers.md

Use this approach for APIs compatible with OpenAI or Anthropic. Define provider details like name, type, endpoint, and authentication headers, then register it.

```go
import "github.com/teilomillet/gollm/providers"

// Define provider configuration
config := providers.ProviderConfig{
    Name:       "my-provider",
    Type:       providers.TypeOpenAI,
    Endpoint:   "https://api.myprovider.com/v1/completions",
    AuthHeader: "Authorization",
    AuthPrefix: "Bearer ",
    RequiredHeaders: map[string]string{
        "Content-Type": "application/json",
    },
    SupportsSchema:    true,
    SupportsStreaming: true,
}

// Register it
providers.RegisterGenericProvider("my-provider", config)
```

--------------------------------

### Implement the Provider Interface

Source: https://context7.com/teilomillet/gollm/llms.txt

Implement the full `Provider` interface for maximum flexibility with unique APIs. This involves defining methods for name, endpoint, headers, request preparation, and response parsing.

```go
import "github.com/teilomillet/gollm/providers"
import "encoding/json"

// Option 2: Implement the full Provider interface (most flexible)
type LocalProvider struct {
    serverURL    string
    options      map[string]interface{}}

func (p *LocalProvider) Name() string    { return "local" }
func (p *LocalProvider) Endpoint() string { return p.serverURL }
func (p *LocalProvider) Headers() map[string]string {
    return map[string]string{"Content-Type": "application/json"}
}
func (p *LocalProvider) PrepareRequest(prompt string, options map[string]interface{}) ([]byte, error) {
    return json.Marshal(map[string]interface{}{"prompt": prompt, "model": p.options["model"]})
}
func (p *LocalProvider) ParseResponse(body []byte) (string, error) {
    var resp struct{ Text string `json:"text"` }
    if err := json.Unmarshal(body, &resp); err != nil {
        return "", err
    }
    return resp.Text, nil
}

func init() {
    providers.GetDefaultRegistry().Register("local",
        func(apiKey, model string, extraHeaders map[string]string) providers.Provider {
            return &LocalProvider{serverURL: apiKey, options: map[string]interface{}{"model": model}})
        })
}
```

--------------------------------

### Register Multiple Providers from Application Configuration

Source: https://github.com/teilomillet/gollm/blob/main/docs/provider_system.md

For applications needing to support multiple LLM providers dynamically based on configuration, define provider configurations within your application's config structure. During application initialization, iterate through these configurations and register each provider using `providers.RegisterGenericProvider`.

```go
// Define provider configurations in your app config
type AppConfig struct {
    LLMProviders map[string]providers.ProviderConfig `json:"llm_providers"`
    // other app config...
}

// During app initialization
func initLLM(appConfig *AppConfig) {
    // Register all configured providers
    for name, providerConfig := range appConfig.LLMProviders {
        providers.RegisterGenericProvider(name, providerConfig)
    }
}
```

--------------------------------

### Enable OpenRouter Prompt Caching

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Enable prompt caching for the OpenRouter provider to improve performance and reduce costs.

```go
llm.SetOption("enable_prompt_caching", true)
```

--------------------------------

### Create LLM with Memory and Structured Messages

Source: https://github.com/teilomillet/gollm/blob/main/examples/caching_structured/README.md

Initializes a base LLM and then wraps it with memory capabilities. Structured messages are enabled by default. Cast the result to access specific memory methods.

```go
// Create base LLM instance
baseLLM, err := llm.NewLLM(cfg, logger, registry)
if err != nil {
    log.Fatalf("Failed to create LLM: %v", err)
}

// Create LLM with memory (uses structured messages by default)
memoryLLM, err := llm.NewLLMWithMemory(baseLLM, 4000, cfg.Model)
if err != nil {
    log.Fatalf("Failed to create LLM with memory: %v", err)
}

// Cast to access specific methods
memLLM := memoryLLM.(*llm.LLMWithMemory)
```

--------------------------------

### Configure OpenRouter Tool/Function Calling

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Set up tools or functions for the model to call, including their definitions and parameters. Also configure tool choice behavior.

```go
tools := []interface{}{
    map[string]interface{}{
        "type": "function",
        "function": map[string]interface{}{
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "parameters": map[string]interface{}{
                // ...
            },
        },
    },
}

llm.SetOption("tools", tools)
llm.SetOption("tool_choice", "auto")
```

--------------------------------

### Use a Custom Provider

Source: https://context7.com/teilomillet/gollm/llms.txt

After registering a custom provider, you can use it with `gollm.NewLLM` by specifying the provider name and its associated API key and model.

```go
import "context"
import "fmt"
import "github.com/teilomillet/gollm"

// Use the custom provider
llm, _ := gollm.NewLLM(
    gollm.SetProvider("local"),
    gollm.SetAPIKey("http://localhost:8080/generate"),
    gollm.SetModel("llama2"),
)
response, _ := llm.Generate(context.Background(), gollm.NewPrompt("Explain quantum computing"))
fmt.Println(response)
```

--------------------------------

### Create and Use Prompt Templates in Go

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Define reusable prompt templates with dynamic fields and options for directives and output structure. Execute templates with specific data to generate prompts for LLM interaction. Handles errors during template execution and LLM generation.

```go
// Create a new prompt template
template := gollm.NewPromptTemplate(
    "AnalysisTemplate",
    "A template for analyzing topics",
    "Provide a comprehensive analysis of {{.Topic}}. Consider the following aspects:\n" +
    "1. Historical context\n" +
    "2. Current relevance\n" +
    "3. Future implications",
    gollm.WithPromptOptions(
        gollm.WithDirectives(
            "Use clear and concise language",
            "Provide specific examples where appropriate",
        ),
        gollm.WithOutput("Structure your analysis with clear headings for each aspect."),
    ),
)

// Use the template to create a prompt
data := map[string]interface{}{
    "Topic": "artificial intelligence in healthcare",
}
prompt, err := template.Execute(data)
if err != nil {
    log.Fatalf("Failed to execute template: %v", err)
}

// Generate a response using the created prompt
response, err := llm.Generate(ctx, prompt)
if err != nil {
    log.Fatalf("Failed to generate response: %v", err)
}

fmt.Printf("Analysis:\n%s\n", response)
```

--------------------------------

### Optimize Prompt with Custom Metrics using PromptOptimizer

Source: https://context7.com/teilomillet/gollm/llms.txt

Use PromptOptimizer to iteratively refine a prompt based on custom metrics and a defined threshold. Ensure necessary LLM, DebugManager, and prompt objects are initialized.

```go
import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/teilomillet/gollm"
    "github.com/teilomillet/gollm/optimizer"
    "github.com/teilomillet/gollm/utils"
)

func main() {
    llm, _ := gollm.NewLLM(
        gollm.SetProvider("groq"),
        gollm.SetModel("llama-3.1-70b-versatile"),
        gollm.SetAPIKey(os.Getenv("GROQ_API_KEY")),
        gollm.SetMaxTokens(1024),
    )

    debugManager := utils.NewDebugManager(llm.GetLogger(), utils.DebugOptions{
        LogPrompts: true, LogResponses: true,
    })
    initialPrompt := llm.NewPrompt("Write the opening paragraph of a mystery novel set in a small coastal town.")

    opt := optimizer.NewPromptOptimizer(
        llm,
        debugManager,
        initialPrompt,
        "Create an engaging, atmospheric opening that hooks the reader",
        optimizer.WithCustomMetrics(
            optimizer.Metric{Name: "Atmosphere",            Description: "How well the writing evokes the coastal setting"},
            optimizer.Metric{Name: "Intrigue",              Description: "How effectively it sets up the mystery"},
            optimizer.Metric{Name: "Character Introduction", Description: "How well it introduces key characters"},
        ),
        optimizer.WithRatingSystem("numerical"),
        optimizer.WithThreshold(0.9),
        optimizer.WithMaxRetries(3),
        optimizer.WithRetryDelay(time.Second*2),
    )

    optimizedPrompt, err := opt.OptimizePrompt(context.Background())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Optimized prompt: %s\n", optimizedPrompt.Input)

    // Use the optimized prompt
    response, _ := llm.Generate(context.Background(), optimizedPrompt)
    fmt.Println(response)
}

```

--------------------------------

### Initialize LLM with Structured Messages and Memory

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Structured messages are enabled by default when SetMemory() is used. This is recommended for caching.

```go
llm, err := gollm.NewLLM(
    gollm.SetProvider("anthropic"),
    gollm.SetModel("claude-3-5-sonnet-20241022"),
    gollm.SetAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
    gollm.SetMemory(4096), // Structured messages enabled by default
)
```

--------------------------------

### NewPrompt / Prompt Options — Structured Prompt Construction

Source: https://context7.com/teilomillet/gollm/llms.txt

Constructs a `Prompt` object with various options to enrich the prompt with system instructions, context, directives, output format specifications, and multimodal content.

```APIDOC
## NewPrompt

### Description
Builds a `Prompt` struct using functional options to define the user's request, including system prompts, context, specific directives, output format requirements, and maximum length constraints. It also supports multimodal inputs like images.

### Usage
```go
prompt := gollm.NewPrompt(
    "Explain the concept of blockchain technology",
    gollm.WithSystemPrompt("You are a technical educator.", gollm.CacheTypeEphemeral),
    gollm.WithContext("The audience is composed of software engineers with no prior blockchain experience."),
    gollm.WithDirectives(
        "Use a simple analogy to illustrate the concept",
        "Highlight key features: immutability, decentralization, consensus",
        "Mention two real-world applications",
    ),
    gollm.WithOutput("Structure your response with: Definition, Analogy, Key Features, Applications."),
    gollm.WithMaxLength(400),
)
```

### Options
- `NewPrompt(content string, options ...PromptOption)`: Creates a new prompt with initial content and applies subsequent options.
- `WithSystemPrompt(systemPrompt string, cacheType ...gollm.CacheType)`: Adds a system-level instruction.
- `WithContext(context string)`: Provides additional context for the LLM.
- `WithDirectives(directives ...string)`: Specifies instructions or tasks for the LLM.
- `WithOutput(outputFormat string)`: Defines the desired format of the output.
- `WithMaxLength(maxLength int)`: Sets the maximum length for the generated response.
- `WithImage(imageURL string)`: Includes an image for multimodal input.
```

--------------------------------

### Run OpenRouter Integration Tests Directly

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Execute the OpenRouter integration tests directly using the go test command. Ensure the API key is set as an environment variable.

```bash
# Set your API key as an environment variable
export OPENROUTER_API_KEY="your_api_key_here"

# Run just the OpenRouter integration tests
go test -v ./providers -run TestOpenRouterIntegration
```

--------------------------------

### Run All Tests

Source: https://github.com/teilomillet/gollm/blob/main/assess/README.md

Command to execute all tests within the testing directory.

```bash
go test ./testing/...
```

--------------------------------

### Run All Go Tests

Source: https://github.com/teilomillet/gollm/blob/main/AGENTS.md

Execute all tests across all packages in the Go project. This is useful for a comprehensive test run.

```bash
go test ./...
```

--------------------------------

### Implement and Register a Custom Provider

Source: https://github.com/teilomillet/gollm/blob/main/docs/provider_system.md

Implement the Provider interface directly for unique APIs and register your custom provider constructor with the default registry.

```go
// Create a new provider implementation
type CustomProvider struct {
    // Your implementation
}

// Implement all required methods of the Provider interface
func (p *CustomProvider) Name() string { return "custom" }
// ... implement other methods

// Register your provider constructor
func init() {
    providers.GetDefaultRegistry().Register("custom", NewCustomProvider)
}

// Constructor function
func NewCustomProvider(apiKey, model string, extraHeaders map[string]string) providers.Provider {
    // Initialize and return your provider
}
```

--------------------------------

### Optimize Prompts with Custom Metrics in Go

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Utilize the PromptOptimizer to refine prompts based on a task description and custom evaluation metrics. Configure rating systems, thresholds, and verbosity for the optimization process. Handles errors during prompt optimization.

```go
initialPrompt := gollm.NewPrompt("Write a short story about a robot learning to love.")
taskDescription := "Generate a compelling short story that explores the theme of artificial intelligence developing emotions."

optimizerInstance := optimizer.NewPromptOptimizer(
    llm,
    initialPrompt,
    taskDescription,
    optimizer.WithCustomMetrics(
        optimizer.Metric{Name: "Creativity", Description: "How original and imaginative the story is"},
        optimizer.Metric{Name: "Emotional Impact", Description: "How well the story evokes feelings in the reader"},
    ),
    optimizer.WithRatingSystem("numerical"),
    optimizer.WithThreshold(0.8),
    optimizer.WithVerbose(),
)

optimizedPrompt, err := optimizerInstance.OptimizePrompt(ctx)
if err != nil {
    log.Fatalf("Optimization failed: %v", err)
}

fmt.Printf("Optimized Prompt: %s\n", optimizedPrompt.Input)
```

--------------------------------

### Configuring OpenRouter Special Features

Source: https://github.com/teilomillet/gollm/blob/main/README.md

Details how to configure advanced features for the OpenRouter provider, including fallback models, auto-routing, prompt caching, reasoning tokens, and provider-specific routing weights.

```go
// Create OpenRouter client
llm, err := gollm.NewLLM(
    gollm.SetProvider("openrouter"),
    gollm.SetModel("anthropic/claude-3-5-sonnet"),
    gollm.SetAPIKey(apiKey),
)
```

```go
// Enable model fallbacks (tried in order if primary model fails)
llm.SetOption("fallback_models", []string{"openai/gpt-4o", "mistral/mistral-large"})
```

```go
// Use auto-routing (automatically select best model)
llm.SetOption("auto_route", true)
```

```go
// Enable prompt caching (improves performance and reduces costs)
llm.SetOption("enable_prompt_caching", true)
```

```go
// Enable reasoning tokens (step-by-step thinking)
llm.SetOption("enable_reasoning", true)
```

```go
// Specify provider routing preferences
llm.SetOption("provider_preferences", map[string]interface{}{
    "openai": map[string]interface{}{
        "weight": 1.0,
    },
})
```

--------------------------------

### Configure OpenAI Client

Source: https://github.com/teilomillet/gollm/blob/main/examples/README.md

Define custom configurations for the OpenAI provider using a YAML file. This allows specifying the model, temperature, and max tokens.

```yaml
# ~/.gollm/configs/openai.yaml
provider: openai
model: gpt-4o-mini
temperature: 0.7
max_tokens: 100
```

--------------------------------

### Multimodal Inputs with gollm

Source: https://context7.com/teilomillet/gollm/llms.txt

Attach images to prompts using URLs or base64 encoding. Supported by vision-capable models. Multiple images can be included in a single prompt.

```go
// From URL
llm, _ := gollm.NewLLM(
    gollm.SetProvider("openai"),
    gollm.SetModel("gpt-4o"),
    gollm.SetAPIKey(os.Getenv("OPENAI_API_KEY")),
    gollm.SetMaxTokens(1000),
)

prompt := gollm.NewPrompt(
    "What's in this image? Describe it in detail.",
    gollm.WithImageURL("https://example.com/photo.jpg", "auto"),
)
response, _ := llm.Generate(context.Background(), prompt)
fmt.Println(response)

// From base64-encoded file
imageData, _ := os.ReadFile("chart.png")
base64Data := base64.StdEncoding.EncodeToString(imageData)

prompt2 := gollm.NewPrompt(
    "Describe the trends shown in this chart.",
    gollm.WithImageBase64(base64Data, "image/png"),
)

// Multiple images in one prompt
promptMulti := gollm.NewPrompt(
    "Compare these two images.",
    gollm.WithImageURL("https://example.com/before.jpg", "auto"),
    gollm.WithImageURL("https://example.com/after.jpg", "auto"),
)
```

--------------------------------

### Testing Custom Providers

Source: https://github.com/teilomillet/gollm/blob/main/docs/custom_providers.md

This Go code provides a basic structure for unit testing custom LLM providers by retrieving them from the registry and testing their core methods.

```go
package providers_test

import (
    "testing"
    
    "github.com/teilomillet/gollm/providers"
)

func TestCustomProvider(t *testing.T) {
    // Get provider from registry
    provider, err := providers.GetDefaultRegistry().Get("custom", "fake-key", "model", nil)
    if err != nil {
        t.Fatalf("Failed to get provider: %v", err)
    }
    
    // Test basic properties
    if provider.Name() != "custom" {
        t.Errorf("Expected name 'custom', got '%s'", provider.Name())
    }
    
    // Test request preparation
    body, err := provider.PrepareRequest("Test prompt", nil)
    if err != nil {
        t.Fatalf("Failed to prepare request: %v", err)
    }
    
    // Verify request format
    // ... additional tests
}
```

--------------------------------

### Generating a Response from an LLM

Source: https://github.com/teilomillet/gollm/blob/main/README.md

A concise snippet demonstrating the call to generate a response from an LLM client using a given context and prompt.

```go
response, err := llm.Generate(ctx, prompt)
```

--------------------------------

### Register and Use a New Generic Provider

Source: https://github.com/teilomillet/gollm/blob/main/docs/provider_system.md

Register a new LLM provider that is not built into Gollm using `providers.RegisterGenericProvider`. This method is recommended for most cases where you need to integrate a custom or third-party API. Define the provider's configuration, including its name, API type, endpoint, and authentication details.

```go
import (
    "github.com/teilomillet/gollm/providers"
)

// Define a configuration for the new provider
newProvider := providers.ProviderConfig{
    Name:       "new-provider",
    Type:       providers.TypeOpenAI, // If API is OpenAI-compatible
    Endpoint:   "https://api.newprovider.com/v1/chat/completions",
    AuthHeader: "Authorization",
    AuthPrefix: "Bearer ",
    RequiredHeaders: map[string]string{
        "Content-Type": "application/json",
    },
    SupportsSchema:    true,
    SupportsStreaming: true,
}

// Register it with the system
providers.RegisterGenericProvider("new-provider", newProvider)

// Now use it like any built-in provider
llm, err := gollm.NewLLM(
    config.SetProvider("new-provider"),
    config.SetAPIKey("your-api-key"),
    config.SetModel("model-name"),
)
```

--------------------------------

### Configure and Use Azure OpenAI Provider

Source: https://github.com/teilomillet/gollm/blob/main/docs/provider_system.md

Connect to Azure OpenAI by specifying the `azure-openai` provider and providing the necessary Azure-specific details like resource name, deployment name, and API version. The endpoint is constructed dynamically, and the deployment name is used as the model identifier. Extra headers, including the constructed endpoint, are required.

```go
import (
    "context"
    "fmt"
    "github.com/teilomillet/gollm"
    "github.com/teilomillet/gollm/config"
)

// Get Azure details
resourceName := "your-resource-name"
deploymentName := "your-deployment-name"
apiVersion := "2023-05-15"

// Create the endpoint URL
endpoint := fmt.Sprintf(
    "https://%s.openai.azure.com/openai/deployments/%s/chat/completions?api-version=%s", 
    resourceName, deploymentName, apiVersion
)

// Use the built-in azure-openai provider
llm, err := gollm.NewLLM(
    config.SetProvider("azure-openai"),
    config.SetAPIKey("your-azure-api-key"),
    config.SetModel(deploymentName), // Azure uses deployment name as model
    config.SetExtraHeaders(map[string]string{
        "azure_endpoint": endpoint,
    }),
)

// Use it like any other provider
ctx := context.Background()
prompt := gollm.NewPrompt("What are the key features of Go?")
response, err := llm.Generate(ctx, prompt)
```

--------------------------------

### Use OpenRouter Auto-Routing Model

Source: https://github.com/teilomillet/gollm/blob/main/examples/openrouter/README.md

Initialize the GoLLM client to use OpenRouter's auto-routing feature by setting the model to 'openrouter/auto'.

```go
llm, err := gollm.NewLLM(
    gollm.SetProvider("openrouter"),
    gollm.SetAPIKey(apiKey),
    gollm.SetModel("openrouter/auto"),
    // ...
)
```

--------------------------------

### Run Tests for Specific Go Package

Source: https://github.com/teilomillet/gollm/blob/main/AGENTS.md

Run tests for a particular package within the Go project. Add the '-v' flag for verbose output.

```bash
go test github.com/teilomillet/gollm/llm -v
```