{"id":48915558,"url":"https://github.com/rizome-dev/go-hfip","last_synced_at":"2026-04-17T02:31:19.838Z","repository":{"id":306399184,"uuid":"1020911142","full_name":"rizome-dev/go-hfip","owner":"rizome-dev","description":"pure go huggingface inference provider SDK","archived":false,"fork":false,"pushed_at":"2025-07-16T21:05:53.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T03:52:27.382Z","etag":null,"topics":["ai","golang","huggingface","inference","sdk"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/rizome-dev/go-hfip","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rizome-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-16T15:25:20.000Z","updated_at":"2025-07-16T21:05:57.000Z","dependencies_parsed_at":"2025-07-25T14:06:36.835Z","dependency_job_id":"82e7f8a4-8e91-4b6f-a42a-a09a66c0e9a8","html_url":"https://github.com/rizome-dev/go-hfip","commit_stats":null,"previous_names":["rizome-dev/go-hfip"],"tags_count":0,"template":false,"template_full_name":"rizome-dev/tmpl","purl":"pkg:github/rizome-dev/go-hfip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizome-dev%2Fgo-hfip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizome-dev%2Fgo-hfip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizome-dev%2Fgo-hfip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizome-dev%2Fgo-hfip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rizome-dev","download_url":"https://codeload.github.com/rizome-dev/go-hfip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rizome-dev%2Fgo-hfip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31912323,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","golang","huggingface","inference","sdk"],"created_at":"2026-04-17T02:31:16.959Z","updated_at":"2026-04-17T02:31:19.810Z","avatar_url":"https://github.com/rizome-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-hfip\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/rizome-dev/go-hfip.svg)](https://pkg.go.dev/github.com/rizome-dev/go-hfip)\n[![Go Report Card](https://goreportcard.com/badge/github.com/rizome-dev/go-hfip)](https://goreportcard.com/report/github.com/rizome-dev/go-hfip)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA comprehensive Go SDK for the **HuggingFace Inference Providers API** with support for 16+ providers and 21+ AI tasks.\n\n```bash\ngo get github.com/rizome-dev/go-hfip\n```\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n\n    \"github.com/rizome-dev/go-hfip\"\n    \"github.com/rizome-dev/go-hfip/pkg/types\"\n)\n\nfunc main() {\n    // Create SDK instance (automatically uses HF_TOKEN env var)\n    sdk := hfip.New()\n\n    // Create a simple chat request\n    req := \u0026hfip.ChatCompletionRequest{\n        BaseRequest: types.BaseRequest{\n            Model: \"moonshotai/Kimi-K2-Instruct\",\n        },\n        Messages: []hfip.Message{\n            hfip.CreateUserMessage(\"Hello! Tell me a joke.\"),\n        },\n        MaxTokens:   hfip.Int(100),\n        Temperature: hfip.Float64(0.7),\n    }\n\n    // Get response\n    resp, err := sdk.Chat.Complete(context.Background(), req)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    fmt.Println(resp.Choices[0].Message.Content)\n}\n```\n\n## Supported Providers\n\n| Provider | Chat | Text-to-Image | Embeddings | Audio | Status |\n|----------|------|---------------|------------|-------|--------|\n| **Cerebras** | ✅ | ❌ | ❌ | ❌ | Stable |\n| **Groq** | ✅ | ❌ | ❌ | ✅ | Stable |\n| **Fireworks AI** | ✅ | ✅ | ✅ | ❌ | Stable |\n| **Together AI** | ✅ | ✅ | ✅ | ❌ | Stable |\n| **OpenAI** | ✅ | ✅ | ✅ | ✅ | Stable |\n| **Cohere** | ✅ | ❌ | ✅ | ❌ | Stable |\n| **Replicate** | ✅ | ✅ | ❌ | ✅ | Stable |\n| **Fal AI** | ❌ | ✅ | ❌ | ❌ | Stable |\n| **Black Forest Labs** | ❌ | ✅ | ❌ | ❌ | Stable |\n| **SambaNova** | ✅ | ❌ | ❌ | ❌ | Stable |\n| **HuggingFace** | ✅ | ✅ | ✅ | ✅ | Stable |\n| Auto Selection | ✅ | ✅ | ✅ | ✅ | Stable |\n\n## Usage Examples\n\n### Chat Completion with Specific Provider\n\n```go\nreq := \u0026hfip.ChatCompletionRequest{\n    BaseRequest: types.BaseRequest{\n        Model:    \"llama-3.1-8b-instant\",\n        Provider: hfip.ProviderCerebras, // Ultra-fast inference\n    },\n    Messages: []hfip.Message{\n        hfip.CreateSystemMessage(\"You are a helpful assistant.\"),\n        hfip.CreateUserMessage(\"What is the capital of France?\"),\n    },\n    MaxTokens:   hfip.Int(50),\n    Temperature: hfip.Float64(0.1),\n}\n\nresp, err := sdk.Chat.Complete(context.Background(), req)\n```\n\n### Streaming Chat\n\n```go\nreq := \u0026hfip.ChatCompletionRequest{\n    BaseRequest: types.BaseRequest{\n        Model: \"llama-3.1-8b-instant\",\n    },\n    Messages: []hfip.Message{\n        hfip.CreateUserMessage(\"Write a short poem about AI.\"),\n    },\n    Stream: true,\n}\n\nresponseChan, errorChan := sdk.Chat.Stream(context.Background(), req)\n\nfor {\n    select {\n    case chunk, ok := \u003c-responseChan:\n        if !ok {\n            return // Stream ended\n        }\n        if len(chunk.Choices) \u003e 0 \u0026\u0026 chunk.Choices[0].Delta.Content != nil {\n            fmt.Print(*chunk.Choices[0].Delta.Content)\n        }\n    case err := \u003c-errorChan:\n        if err != nil {\n            log.Fatal(err)\n        }\n        return\n    }\n}\n```\n\n### Function Calling\n\n```go\n// Define a calculator tool\ncalculatorTool := hfip.CreateTool(\n    \"calculator\",\n    \"Perform basic arithmetic operations\",\n    map[string]interface{}{\n        \"type\": \"object\",\n        \"properties\": map[string]interface{}{\n            \"operation\": map[string]interface{}{\n                \"type\": \"string\",\n                \"enum\": []string{\"add\", \"subtract\", \"multiply\", \"divide\"},\n                \"description\": \"The arithmetic operation to perform\",\n            },\n            \"a\": map[string]interface{}{\n                \"type\": \"number\",\n                \"description\": \"First number\",\n            },\n            \"b\": map[string]interface{}{\n                \"type\": \"number\", \n                \"description\": \"Second number\",\n            },\n        },\n        \"required\": []string{\"operation\", \"a\", \"b\"},\n    },\n)\n\nreq := \u0026hfip.ChatCompletionRequest{\n    BaseRequest: types.BaseRequest{\n        Model: \"llama-3.1-8b-instant\",\n    },\n    Messages: []hfip.Message{\n        hfip.CreateUserMessage(\"What is 15 multiplied by 7?\"),\n    },\n    Tools:      []hfip.Tool{calculatorTool},\n    ToolChoice: \"auto\",\n}\n\nresp, err := sdk.Chat.Complete(context.Background(), req)\n```\n\n### Provider Information\n\n```go\n// List all available providers\nproviders := sdk.Providers.ListProviders()\nfor _, provider := range providers {\n    fmt.Printf(\"%s: %s\\n\", provider.DisplayName, provider.Description)\n}\n\n// Get providers for specific task\nchatProviders := sdk.Providers.GetProvidersForTask(hfip.TaskChatCompletion)\nimageProviders := sdk.Providers.GetProvidersForTask(hfip.TaskTextToImage)\n\n// Automatic provider selection\nprovider, err := sdk.Providers.SelectProvider(hfip.TaskChatCompletion, \u0026hfip.ProviderPreferences{\n    PreferFast: true,\n    AllowExperimental: false,\n})\n```\n\n## Configuration\n\n### Environment Variables\n\n- `HF_TOKEN` or `HUGGINGFACE_TOKEN`: Your HuggingFace API token\n- `HFIP_DEBUG`: Set to `\"true\"` to enable debug mode\n\n### SDK Options\n\n```go\nsdk := hfip.New(\n    \"your-api-key\",                           // API key\n    hfip.WithTimeout(30*time.Second),        // Request timeout\n    hfip.WithMaxRetries(3),                  // Max retry attempts\n    hfip.WithDebug(true),                    // Enable debug mode\n    hfip.WithHeaders(map[string]string{      // Custom headers\n        \"Custom-Header\": \"value\",\n    }),\n)\n```\n\n## Error Handling\n\nThe SDK provides detailed error types for different scenarios:\n\n```go\nresp, err := sdk.Chat.Complete(context.Background(), req)\nif err != nil {\n    switch {\n    case hfip.IsAPIError(err):\n        apiErr := err.(*hfip.APIError)\n        fmt.Printf(\"API Error: %s (Status: %d, Provider: %s)\\n\", \n            apiErr.Message, apiErr.StatusCode, apiErr.Provider)\n            \n    case hfip.IsRateLimitError(err):\n        rateLimitErr := err.(*hfip.RateLimitError)\n        fmt.Printf(\"Rate limited, retry after %d seconds\\n\", rateLimitErr.RetryAfter)\n        \n    case hfip.IsValidationError(err):\n        valErr := err.(*hfip.ValidationError)\n        fmt.Printf(\"Validation error in field '%s': %s\\n\", valErr.Field, valErr.Message)\n        \n    case hfip.IsTaskNotSupportedError(err):\n        taskErr := err.(*hfip.TaskNotSupportedError)\n        fmt.Printf(\"Task '%s' not supported by provider '%s'\\n\", taskErr.Task, taskErr.Provider)\n    }\n}\n```\n\n## Supported Tasks\n\n### Text \u0026 Language (13 tasks)\n- **Chat Completion**: Conversational AI with context\n- **Text Generation**: Creative writing and completion\n- **Feature Extraction**: Text embeddings and vectors  \n- **Text Classification**: Sentiment, topic, intent classification\n- **Token Classification**: Named entity recognition, POS tagging\n- **Translation**: Language-to-language translation\n- **Zero-shot Classification**: Classification without training\n- **Summarization**: Text summarization and extraction\n- **Question Answering**: Reading comprehension\n- **Table Question Answering**: Structured data queries\n- **Fill Mask**: Missing word prediction\n\n### Vision (6 tasks)\n- **Text-to-Image**: Generate images from text prompts\n- **Text-to-Video**: Generate videos from text (coming soon)\n- **Image Classification**: Classify and tag images\n- **Image Segmentation**: Segment and identify regions\n- **Image-to-Image**: Transform and edit images\n- **Object Detection**: Detect and locate objects\n\n### Audio (2 tasks)\n- **Audio Classification**: Classify sounds and music\n- **Speech Recognition**: Convert speech to text\n\n## Performance\n\nThe SDK is optimized for performance with features like:\n\n- **Connection pooling** for HTTP requests\n- **Automatic retries** with exponential backoff\n- **Provider failover** for high availability\n- **Concurrent request support** with proper rate limiting\n- **Streaming support** for real-time responses\n\n## Examples\n\nSee the [`examples/`](examples/) directory for comprehensive usage examples:\n\n- [`examples/basic/`](examples/basic/) - Basic usage patterns and API calls\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- 📖 [Documentation](https://pkg.go.dev/github.com/rizome-dev/go-hfip)\n- 🐛 [Issues](https://github.com/rizome-dev/go-hfip/issues)\n- 💬 [Discussions](https://github.com/rizome-dev/go-hfip/discussions)\n\n## Acknowledgments\n\n- [HuggingFace](https://huggingface.co/) for providing the Inference Providers API\n- All the amazing AI infrastructure providers that make this possible\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frizome-dev%2Fgo-hfip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frizome-dev%2Fgo-hfip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frizome-dev%2Fgo-hfip/lists"}