https://github.com/rizome-dev/go-hfip
pure go huggingface inference provider SDK
https://github.com/rizome-dev/go-hfip
ai golang huggingface inference sdk
Last synced: 2 months ago
JSON representation
pure go huggingface inference provider SDK
- Host: GitHub
- URL: https://github.com/rizome-dev/go-hfip
- Owner: rizome-dev
- License: mit
- Created: 2025-07-16T15:25:20.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-16T21:05:53.000Z (11 months ago)
- Last Synced: 2025-09-14T03:52:27.382Z (9 months ago)
- Topics: ai, golang, huggingface, inference, sdk
- Language: Go
- Homepage: https://pkg.go.dev/github.com/rizome-dev/go-hfip
- Size: 41 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# go-hfip
[](https://pkg.go.dev/github.com/rizome-dev/go-hfip)
[](https://goreportcard.com/report/github.com/rizome-dev/go-hfip)
[](https://opensource.org/licenses/MIT)
A comprehensive Go SDK for the **HuggingFace Inference Providers API** with support for 16+ providers and 21+ AI tasks.
```bash
go get github.com/rizome-dev/go-hfip
```
## Quick Start
```go
package main
import (
"context"
"fmt"
"log"
"github.com/rizome-dev/go-hfip"
"github.com/rizome-dev/go-hfip/pkg/types"
)
func main() {
// Create SDK instance (automatically uses HF_TOKEN env var)
sdk := hfip.New()
// Create a simple chat request
req := &hfip.ChatCompletionRequest{
BaseRequest: types.BaseRequest{
Model: "moonshotai/Kimi-K2-Instruct",
},
Messages: []hfip.Message{
hfip.CreateUserMessage("Hello! Tell me a joke."),
},
MaxTokens: hfip.Int(100),
Temperature: hfip.Float64(0.7),
}
// Get response
resp, err := sdk.Chat.Complete(context.Background(), req)
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.Choices[0].Message.Content)
}
```
## Supported Providers
| Provider | Chat | Text-to-Image | Embeddings | Audio | Status |
|----------|------|---------------|------------|-------|--------|
| **Cerebras** | ✅ | ❌ | ❌ | ❌ | Stable |
| **Groq** | ✅ | ❌ | ❌ | ✅ | Stable |
| **Fireworks AI** | ✅ | ✅ | ✅ | ❌ | Stable |
| **Together AI** | ✅ | ✅ | ✅ | ❌ | Stable |
| **OpenAI** | ✅ | ✅ | ✅ | ✅ | Stable |
| **Cohere** | ✅ | ❌ | ✅ | ❌ | Stable |
| **Replicate** | ✅ | ✅ | ❌ | ✅ | Stable |
| **Fal AI** | ❌ | ✅ | ❌ | ❌ | Stable |
| **Black Forest Labs** | ❌ | ✅ | ❌ | ❌ | Stable |
| **SambaNova** | ✅ | ❌ | ❌ | ❌ | Stable |
| **HuggingFace** | ✅ | ✅ | ✅ | ✅ | Stable |
| Auto Selection | ✅ | ✅ | ✅ | ✅ | Stable |
## Usage Examples
### Chat Completion with Specific Provider
```go
req := &hfip.ChatCompletionRequest{
BaseRequest: types.BaseRequest{
Model: "llama-3.1-8b-instant",
Provider: hfip.ProviderCerebras, // Ultra-fast inference
},
Messages: []hfip.Message{
hfip.CreateSystemMessage("You are a helpful assistant."),
hfip.CreateUserMessage("What is the capital of France?"),
},
MaxTokens: hfip.Int(50),
Temperature: hfip.Float64(0.1),
}
resp, err := sdk.Chat.Complete(context.Background(), req)
```
### Streaming Chat
```go
req := &hfip.ChatCompletionRequest{
BaseRequest: types.BaseRequest{
Model: "llama-3.1-8b-instant",
},
Messages: []hfip.Message{
hfip.CreateUserMessage("Write a short poem about AI."),
},
Stream: true,
}
responseChan, errorChan := sdk.Chat.Stream(context.Background(), req)
for {
select {
case chunk, ok := <-responseChan:
if !ok {
return // Stream ended
}
if len(chunk.Choices) > 0 && chunk.Choices[0].Delta.Content != nil {
fmt.Print(*chunk.Choices[0].Delta.Content)
}
case err := <-errorChan:
if err != nil {
log.Fatal(err)
}
return
}
}
```
### Function Calling
```go
// Define a calculator tool
calculatorTool := hfip.CreateTool(
"calculator",
"Perform basic arithmetic operations",
map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"operation": map[string]interface{}{
"type": "string",
"enum": []string{"add", "subtract", "multiply", "divide"},
"description": "The arithmetic operation to perform",
},
"a": map[string]interface{}{
"type": "number",
"description": "First number",
},
"b": map[string]interface{}{
"type": "number",
"description": "Second number",
},
},
"required": []string{"operation", "a", "b"},
},
)
req := &hfip.ChatCompletionRequest{
BaseRequest: types.BaseRequest{
Model: "llama-3.1-8b-instant",
},
Messages: []hfip.Message{
hfip.CreateUserMessage("What is 15 multiplied by 7?"),
},
Tools: []hfip.Tool{calculatorTool},
ToolChoice: "auto",
}
resp, err := sdk.Chat.Complete(context.Background(), req)
```
### Provider Information
```go
// List all available providers
providers := sdk.Providers.ListProviders()
for _, provider := range providers {
fmt.Printf("%s: %s\n", provider.DisplayName, provider.Description)
}
// Get providers for specific task
chatProviders := sdk.Providers.GetProvidersForTask(hfip.TaskChatCompletion)
imageProviders := sdk.Providers.GetProvidersForTask(hfip.TaskTextToImage)
// Automatic provider selection
provider, err := sdk.Providers.SelectProvider(hfip.TaskChatCompletion, &hfip.ProviderPreferences{
PreferFast: true,
AllowExperimental: false,
})
```
## Configuration
### Environment Variables
- `HF_TOKEN` or `HUGGINGFACE_TOKEN`: Your HuggingFace API token
- `HFIP_DEBUG`: Set to `"true"` to enable debug mode
### SDK Options
```go
sdk := hfip.New(
"your-api-key", // API key
hfip.WithTimeout(30*time.Second), // Request timeout
hfip.WithMaxRetries(3), // Max retry attempts
hfip.WithDebug(true), // Enable debug mode
hfip.WithHeaders(map[string]string{ // Custom headers
"Custom-Header": "value",
}),
)
```
## Error Handling
The SDK provides detailed error types for different scenarios:
```go
resp, err := sdk.Chat.Complete(context.Background(), req)
if err != nil {
switch {
case hfip.IsAPIError(err):
apiErr := err.(*hfip.APIError)
fmt.Printf("API Error: %s (Status: %d, Provider: %s)\n",
apiErr.Message, apiErr.StatusCode, apiErr.Provider)
case hfip.IsRateLimitError(err):
rateLimitErr := err.(*hfip.RateLimitError)
fmt.Printf("Rate limited, retry after %d seconds\n", rateLimitErr.RetryAfter)
case hfip.IsValidationError(err):
valErr := err.(*hfip.ValidationError)
fmt.Printf("Validation error in field '%s': %s\n", valErr.Field, valErr.Message)
case hfip.IsTaskNotSupportedError(err):
taskErr := err.(*hfip.TaskNotSupportedError)
fmt.Printf("Task '%s' not supported by provider '%s'\n", taskErr.Task, taskErr.Provider)
}
}
```
## Supported Tasks
### Text & Language (13 tasks)
- **Chat Completion**: Conversational AI with context
- **Text Generation**: Creative writing and completion
- **Feature Extraction**: Text embeddings and vectors
- **Text Classification**: Sentiment, topic, intent classification
- **Token Classification**: Named entity recognition, POS tagging
- **Translation**: Language-to-language translation
- **Zero-shot Classification**: Classification without training
- **Summarization**: Text summarization and extraction
- **Question Answering**: Reading comprehension
- **Table Question Answering**: Structured data queries
- **Fill Mask**: Missing word prediction
### Vision (6 tasks)
- **Text-to-Image**: Generate images from text prompts
- **Text-to-Video**: Generate videos from text (coming soon)
- **Image Classification**: Classify and tag images
- **Image Segmentation**: Segment and identify regions
- **Image-to-Image**: Transform and edit images
- **Object Detection**: Detect and locate objects
### Audio (2 tasks)
- **Audio Classification**: Classify sounds and music
- **Speech Recognition**: Convert speech to text
## Performance
The SDK is optimized for performance with features like:
- **Connection pooling** for HTTP requests
- **Automatic retries** with exponential backoff
- **Provider failover** for high availability
- **Concurrent request support** with proper rate limiting
- **Streaming support** for real-time responses
## Examples
See the [`examples/`](examples/) directory for comprehensive usage examples:
- [`examples/basic/`](examples/basic/) - Basic usage patterns and API calls
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📖 [Documentation](https://pkg.go.dev/github.com/rizome-dev/go-hfip)
- 🐛 [Issues](https://github.com/rizome-dev/go-hfip/issues)
- 💬 [Discussions](https://github.com/rizome-dev/go-hfip/discussions)
## Acknowledgments
- [HuggingFace](https://huggingface.co/) for providing the Inference Providers API
- All the amazing AI infrastructure providers that make this possible