tm_back/pkg/ollama/USAGE.md

# Ollama SDK - Quick Usage Guide

## Installation
The SDK is already part of your `tm` module. Import it as:
```go
import "tm/pkg/ollama"
```

## Basic Setup
```go
// 1. Configuration
config := ollama.DefaultConfig()
config.BaseURL = "http://localhost:11434" // Your Ollama server URL
config.DefaultModel = "llama2" // Default model to use

// 2. Logger (using project's logger)
loggerConfig := &logger.Config{Level: "info", Format: "json", Output: "stdout"}
projectLogger := logger.NewLogger(loggerConfig)

// 3. Create SDK
sdk, err := ollama.New(config, projectLogger)
if err != nil {
    log.Fatal("Failed to create Ollama SDK:", err)
}
```

## Environment Variables
```bash
export OLLAMA_BASE_URL="http://localhost:11434"
export OLLAMA_TIMEOUT="300s"
export OLLAMA_RETRY_ATTEMPTS="3"
export OLLAMA_RETRY_DELAY="2s"
export OLLAMA_ENABLE_LOGGING="true"
export OLLAMA_DEFAULT_MODEL="llama2"
export OLLAMA_DEFAULT_TEMPERATURE="0.7"
export OLLAMA_DEFAULT_TOP_P="0.9"
export OLLAMA_DEFAULT_MAX_TOKENS="1000"
```

## Quick Examples

### Simple Text Generation
```go
ctx := context.Background()

// Generate text with default model
response, err := sdk.QuickGenerate(ctx, "Write a short story about a robot")
if err != nil {
    log.Printf("Generation failed: %v", err)
}
fmt.Println(response)

// Generate with specific model
response, err := sdk.QuickGenerateWithModel(ctx, "codellama", "Write a Python function to sort a list")
```

### Chat Conversations
```go
// Simple chat
response, err := sdk.QuickChat(ctx, "What is the capital of France?")
fmt.Println(response)

// Chat with system prompt
response, err := sdk.QuickChatWithSystem(ctx, 
    "You are a helpful coding assistant.", 
    "How do I implement a binary search in Go?")
```

### Advanced Chat with Builder
```go
// Create a chat builder
builder := sdk.NewChatBuilder().
    SetModel("llama2").
    SetSystem("You are a helpful coding assistant.").
    SetTemperature(0.7).
    SetMaxTokens(500)

// Start conversation
response, err := builder.
    AddMessage(ollama.MessageRoleUser, "How do I create a struct in Go?").
    Send(ctx)

fmt.Printf("Assistant: %s\n", response.Message.Content)

// Continue the conversation
response, err = builder.Continue(ctx, "Can you show me an example with methods?")
fmt.Printf("Assistant: %s\n", response.Message.Content)
```

### Streaming Responses
```go
// Streaming text generation
err := sdk.StreamGenerate(ctx, &ollama.GenerateRequest{
    Model:  "llama2",
    Prompt: "Write a poem about programming",
}, func(chunk string) error {
    fmt.Print(chunk) // Print each chunk as it arrives
    return nil
})

// Streaming chat
err := sdk.StreamChat(ctx, &ollama.ChatRequest{
    Model: "llama2",
    Messages: []ollama.Message{
        {
            Role:    ollama.MessageRoleUser,
            Content: "Tell me a story",
        },
    },
}, func(chunk string) error {
    fmt.Print(chunk)
    return nil
})
```

### Embeddings
```go
// Generate embeddings
embeddings, err := sdk.QuickEmbed(ctx, "This is some text to embed")
if err != nil {
    log.Printf("Embedding failed: %v", err)
}

fmt.Printf("Embedding dimension: %d\n", len(embeddings))
```

### Model Management
```go
// List available models
models, err := sdk.ListModels(ctx)
for _, model := range models.Models {
    fmt.Printf("Model: %s, Size: %d bytes\n", model.Name, model.Size)
}

// Pull a new model
pullResp, err := sdk.PullModel(ctx, "codellama")
fmt.Printf("Pull status: %s\n", pullResp.Status)

// Show model information
modelInfo, err := sdk.ShowModel(ctx, "llama2")
fmt.Printf("Model family: %s\n", modelInfo.Details.Family)

// Delete a model
deleteResp, err := sdk.DeleteModel(ctx, "unwanted-model")
fmt.Printf("Delete status: %s\n", deleteResp.Status)
```

### Health Check
```go
err := sdk.Health(ctx)
if err != nil {
    log.Printf("Ollama service is not available: %v", err)
} else {
    fmt.Println("Ollama service is healthy")
}
```

## Error Handling
```go
resp, err := sdk.Generate(ctx, req)
if err != nil {
    switch e := err.(type) {
    case *ollama.ConfigError:
        fmt.Printf("Configuration error: %s\n", e.Message)
    case *ollama.ModelError:
        fmt.Printf("Model error for %s: %s\n", e.Model, e.Message)
    case *ollama.GenerationError:
        fmt.Printf("Generation error: %s\n", e.Message)
    case *ollama.ConnectionError:
        fmt.Printf("Connection error: %s\n", e.Message)
    case *ollama.TimeoutError:
        fmt.Printf("Timeout during %s: %s\n", e.Operation, e.Message)
    default:
        fmt.Printf("Unexpected error: %v\n", err)
    }
}
```

## Advanced Configuration
```go
config := &ollama.Config{
    BaseURL:            "http://localhost:11434",
    Timeout:            300 * time.Second,
    RetryAttempts:      3,
    RetryDelay:         2 * time.Second,
    EnableLogging:      true,
    UserAgent:          "MyApp-OllamaSDK/1.0",
    DefaultModel:       "llama2",
    DefaultTemperature: 0.7,
    DefaultTopP:        0.9,
    DefaultMaxTokens:   1000,
    EnableStreaming:    false,
}

sdk, err := ollama.New(config, logger)
```

## Custom HTTP Client
```go
httpClient := &http.Client{
    Timeout: 60 * time.Second,
    Transport: &http.Transport{
        MaxIdleConns:        10,
        IdleConnTimeout:     30 * time.Second,
        DisableCompression:  true,
    },
}

sdk, err := ollama.NewWithClient(config, httpClient, logger)
```

## Integration with Project Logger
```go
// Use the project's logger system
loggerConfig := &logger.Config{
    Level:  "info",
    Format: "json",
    Output: "stdout",
}
projectLogger := logger.NewLogger(loggerConfig)

sdk, err := ollama.New(config, projectLogger)
```

## Best Practices

1. **Always use context**: Pass context for cancellation and timeouts
2. **Handle errors properly**: Use type assertions for specific error handling
3. **Configure timeouts**: Set appropriate timeouts for your use case
4. **Use streaming for long responses**: Enable streaming for better user experience
5. **Monitor model usage**: Keep track of token usage and costs
6. **Validate inputs**: Ensure prompts and parameters are within limits
7. **Use structured logging**: Leverage the built-in logging for debugging

## Common Use Cases

### Document Summarization
```go
response, err := sdk.QuickChatWithSystem(ctx, 
    "You are a helpful assistant that summarizes documents concisely.", 
    "Please summarize this document: [document content]")
```

### Code Review Assistant
```go
response, err := sdk.QuickChatWithSystem(ctx, 
    "You are a senior software engineer reviewing code. Provide constructive feedback.", 
    "Please review this Go code: [code snippet]")
```

### Translation Service
```go
response, err := sdk.QuickChatWithSystem(ctx, 
    "You are a professional translator. Translate the following text accurately.", 
    "Translate this to French: Hello, how are you?")
```

### Question Answering
```go
response, err := sdk.QuickChatWithSystem(ctx, 
    "You are a helpful assistant that answers questions accurately and concisely.", 
    "What is the difference between HTTP and HTTPS?")
```