Add Ollama SDK with Core Functionality and Documentation
- Introduced the Ollama SDK, providing a comprehensive interface for interacting with Ollama AI models, including text generation, chat conversations, embeddings, and model management. - Implemented core components such as Client, Config, and various request/response entities to facilitate API interactions. - Added structured error handling with specific error types for improved clarity and debugging. - Included a README and usage guide to assist developers in integrating the SDK into their applications, ensuring a smooth onboarding experience. - Established a fluent API for chat interactions and streaming responses, enhancing usability and flexibility for developers.
This commit is contained in:
n.nakhostin
@@ -0,0 +1,263 @@
|
||||
# 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?")
|
||||
```
|
||||
Reference in New Issue
Block a user