{"id":51291068,"url":"https://github.com/wintermi/sigma","last_synced_at":"2026-06-30T10:02:11.347Z","repository":{"id":361175422,"uuid":"1253291046","full_name":"wintermi/sigma","owner":"wintermi","description":"sigma is a Go package for provider-neutral AI model calls.","archived":false,"fork":false,"pushed_at":"2026-06-27T15:49:12.000Z","size":1738,"stargazers_count":17,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T17:21:34.690Z","etag":null,"topics":["claude","codex","fireworks-ai","gemini","go","golang","grok","kimi","openai","xai"],"latest_commit_sha":null,"homepage":"","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/wintermi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-29T10:14:48.000Z","updated_at":"2026-06-27T15:49:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wintermi/sigma","commit_stats":null,"previous_names":["wintermi/sigma"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/wintermi/sigma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintermi%2Fsigma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintermi%2Fsigma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintermi%2Fsigma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintermi%2Fsigma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wintermi","download_url":"https://codeload.github.com/wintermi/sigma/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintermi%2Fsigma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34961549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"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":["claude","codex","fireworks-ai","gemini","go","golang","grok","kimi","openai","xai"],"created_at":"2026-06-30T10:02:06.739Z","updated_at":"2026-06-30T10:02:11.338Z","avatar_url":"https://github.com/wintermi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sigma\n\n`sigma` is a Go package for provider-neutral AI model calls. The stable release\nsurface is text-first: one root API for model metadata, text streaming,\ncompletions, tools, request persistence, custom OpenAI-compatible endpoints, and\ndeterministic tests. Other documented surfaces, including image generation and\nsome provider adapters, are preview or future work until release notes say\notherwise.\n\nThe module path is currently:\n\n```sh\ngo get github.com/wintermi/sigma\n```\n\nThe root package name is `sigma`. Version tags follow standard\nMajor.Minor.Patch numbering, starting with `v0.1.0`. Any breaking changes before\n`v1.0.0` should be documented in [CHANGELOG.md](CHANGELOG.md),\n[release notes](docs/release-notes-v0.5.0.md), and upgrade guidance. This\ncheckout is licensed under the [MIT License](LICENSE).\n\n## Quick Start\n\nThe fastest path uses `sigmatest`, which is deterministic and makes no network\ncalls:\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/wintermi/sigma\"\n\t\"github.com/wintermi/sigma/sigmatest\"\n)\n\nfunc main() {\n\tprovider := sigmatest.NewFauxProvider(sigmatest.Script{\n\t\tFinal: sigma.AssistantMessage{\n\t\t\tContent: []sigma.ContentBlock{\n\t\t\t\tsigma.Text(\"Sigma provides provider-neutral model calls for Go.\"),\n\t\t\t},\n\t\t},\n\t})\n\tregistry, err := sigmatest.Registry(provider)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tclient := sigma.NewClient(sigma.WithRegistry(registry))\n\ttext, err := client.CompleteText(\n\t\tcontext.Background(),\n\t\tsigmatest.TextModel(),\n\t\t\"Write one short sentence about Sigma.\",\n\t)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Println(text)\n}\n```\n\nFor a real provider, register a provider package on the same registry as the\nmodel metadata and provide credentials through options, an auth resolver, or the\ndocumented environment variables:\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/wintermi/sigma\"\n\t\"github.com/wintermi/sigma/provider/openai\"\n)\n\nfunc main() {\n\tregistry := sigma.NewRegistry()\n\tif err := openai.Register(registry, sigma.ProviderOpenAI); err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tmodel := sigma.Model{\n\t\tID:              \"gpt-4o-mini\",\n\t\tProvider:        sigma.ProviderOpenAI,\n\t\tAPI:             sigma.APIOpenAICompletions,\n\t\tSupportedInputs: []sigma.ContentBlockType{sigma.ContentBlockText},\n\t\tSupportsTools:   true,\n\t}\n\tif err := registry.RegisterModel(model); err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tclient := sigma.NewClient(sigma.WithRegistry(registry))\n\ttext, err := client.CompleteText(context.Background(), model, \"Reply in one sentence.\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tlog.Println(text)\n}\n```\n\nThe OpenAI example above can use `OPENAI_API_KEY` through\n`EnvironmentAuthResolver`, or `sigma.WithAPIKey(\"...\")` for a request-scoped\noverride. Tests should prefer `sigmatest` or `httptest.Server`; the repository\ntest suite must not make live provider calls.\n\n## Streaming\n\n`Client.Stream` returns a single-consumer `*sigma.Stream`. Read ordered events\nfrom `Events`, then inspect `Err` and `Final`, or call `sigma.Collect` when you\nonly need the final assistant message.\n\n```go\nstream := client.Stream(ctx, model, sigma.Request{\n\tMessages: []sigma.Message{sigma.UserText(\"Explain streaming briefly.\")},\n})\ndefer stream.Close()\n\nfor event := range stream.Events() {\n\tswitch event.Kind {\n\tcase sigma.EventKindTextDelta:\n\t\tfmt.Print(event.DeltaText)\n\tcase sigma.EventKindToolCallDelta:\n\t\t// Tool-call JSON may arrive over multiple deltas.\n\tcase sigma.EventKindDone, sigma.EventKindError:\n\t\t// Terminal events also carry the final assistant message.\n\t}\n}\nif err := stream.Err(); err != nil {\n\tlog.Fatal(err)\n}\nfinal, ok := stream.Final()\n_ = final\n_ = ok\n```\n\nText, thinking, and tool-call blocks can be interleaved. Use\n`Event.ContentIndex` when building UI or transcript state.\n\n## How Requests Flow\n\n```text\nClient\n  -\u003e Registry lookup for Model and Provider\n  -\u003e Provider.Stream or ImageProvider.Generate\n  -\u003e Stream events\n  -\u003e AssistantMessage\n```\n\nFor text calls, `Complete` is implemented by collecting the provider stream. For\nimages, `GenerateImages` dispatches to a registered image provider and returns\n`AssistantImages`.\n\n## Documentation\n\n- [Changelog](CHANGELOG.md) tracks release-visible changes and known\n  limitations.\n- [Release notes](docs/release-notes-v0.5.0.md) summarize the latest closed tag\n  scope and compatibility boundary.\n- [Releasing](RELEASING.md) documents the validation commands and pre-tag\n  checklist used for every release.\n- [TODO](TODO.md) lists deferred work that is outside the current release scope.\n- [Providers](docs/providers.md) covers registration, credentials, environment\n  variables, and caveats.\n- [Streaming](docs/streaming.md) covers event handling and terminal messages.\n- [Tools](docs/tools.md) covers schemas, validation, and tool-result replay.\n- [Images](docs/images.md) covers image input and image generation.\n- [Reasoning](docs/reasoning.md) covers thinking controls and streamed thinking\n  blocks.\n- [Errors](docs/errors.md) covers typed errors, cancellation, retries, and\n  redaction-safe diagnostics.\n- [Custom models](docs/custom-models.md) covers local OpenAI-compatible models\n  and routers.\n- [Testing](docs/testing.md) covers `sigmatest`, `httptest`, and live-test\n  boundaries.\n- [Request persistence](docs/persistence.md) covers JSON replay.\n- [Inspired by `@earendil-works/pi-ai`](docs/inspired-by-pi-ai.md) maps\n  familiar TypeScript concepts to Go.\n- [Provider parity](docs/provider-parity.md) distinguishes implemented, partial,\n  planned, unsupported, and preview provider features.\n- [Security](docs/security.md) covers credential handling and diagnostic\n  redaction.\n- [Generated model metadata](tools/modeldata/README.md) describes catalog\n  refreshes.\n- [Examples](examples/README.md) lists runnable examples.\n\n## Verification\n\n```sh\nmise run go:test\nmise run go:race\nmise run go:vet\nmise run go:generate\ngit diff --exit-code\n```\n\nRun `mise run ci` for the full CI-equivalent suite (formatting, lint, vet, and\nthe race-enabled test run). The repository includes a Markdown internal-link\ntest and builds the examples as part of `mise run go:test`. External links and\nlive provider calls are not checked by default so verification stays\ndeterministic and does not require credentials.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwintermi%2Fsigma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwintermi%2Fsigma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwintermi%2Fsigma/lists"}