{"id":35727213,"url":"https://github.com/joakimcarlsson/ai","last_synced_at":"2026-05-13T06:16:00.368Z","repository":{"id":310631559,"uuid":"1022994412","full_name":"JoakimCarlsson/ai","owner":"JoakimCarlsson","description":"A unified Go client library for multiple AI providers (OpenAI, Anthropic, Google, AWS Bedrock, etc.) with streaming, tool calling, structured output, and multimodal support. Features type-safe interfaces, cost tracking, and MCP integration.","archived":false,"fork":false,"pushed_at":"2026-02-01T09:03:54.000Z","size":969,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-01T19:17:02.709Z","etag":null,"topics":["ai","golang","llm","structured-output","tool-calling"],"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/JoakimCarlsson.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-20T09:51:24.000Z","updated_at":"2026-02-01T09:03:55.000Z","dependencies_parsed_at":"2025-08-19T10:46:50.355Z","dependency_job_id":"27dc6a9e-0e95-401a-825a-a3123ec468fc","html_url":"https://github.com/JoakimCarlsson/ai","commit_stats":null,"previous_names":["joakimcarlsson/ai"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/JoakimCarlsson/ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoakimCarlsson%2Fai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoakimCarlsson%2Fai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoakimCarlsson%2Fai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoakimCarlsson%2Fai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JoakimCarlsson","download_url":"https://codeload.github.com/JoakimCarlsson/ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoakimCarlsson%2Fai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29134209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T20:50:26.975Z","status":"ssl_error","status_checked_at":"2026-02-05T20:49:26.082Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","llm","structured-output","tool-calling"],"created_at":"2026-01-06T09:14:55.055Z","updated_at":"2026-05-10T14:06:23.749Z","avatar_url":"https://github.com/JoakimCarlsson.png","language":"Go","funding_links":[],"categories":["Artificial Intelligence"],"sub_categories":[],"readme":"# Go AI Client Library\n\n[![CI](https://github.com/joakimcarlsson/ai/actions/workflows/ci.yml/badge.svg)](https://github.com/joakimcarlsson/ai/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Version](https://img.shields.io/badge/go-1.25%2B-00ADD8?logo=go)](https://go.dev/)\n\n\u003e **Migrating?** [MIGRATION.md](MIGRATION.md) covers two transitions: `v0.18.x → v0.1.0` (single module split into ~50 per-vendor modules) and `v0.1.x → v0.2.0` (`memory` and `session` lifted out of `agent/` to top-level modules).\n\nA multi-provider Go library for AI: LLMs, embeddings, image generation, TTS,\nSTT, rerankers, and fill-in-the-middle. Each capability is a modality module\nand each vendor implementation is its own sub-module — you import only the\nSDKs you actually use.\n\n**[Documentation](https://joakimcarlsson.github.io/ai)**\n\n## Features\n\n- **Per-vendor modules** — Pull only the SDKs you need; no transitive bloat\n- **LLM** — Chat, streaming, tool calling, structured output, reasoning\n- **Agent framework** — Sub-agents, handoffs, fan-out, sessions, persistent memory, context strategies\n- **Embeddings** — Text, multimodal, and contextualized\n- **Image generation** — OpenAI, Gemini, xAI\n- **Audio** — TTS (ElevenLabs, OpenAI, Google Cloud, Azure Speech) and STT (OpenAI Whisper, ElevenLabs Scribe, Deepgram, AssemblyAI, Google Cloud)\n- **Rerankers** — Voyage AI, Cohere\n- **Fill-in-the-middle** — Mistral, DeepSeek\n- **Batch processing** — Native batch APIs (OpenAI, Anthropic, Gemini) or bounded concurrency for any provider\n- **MCP integration** — Model Context Protocol tooling\n- **OpenTelemetry tracing** — GenAI semantic conventions across every provider call\n- **Cost tracking** — Token / character usage with cost calculation\n\n## Module structure\n\nThe library is published as ~50 independent Go modules organised by tier:\n\n- **Tier 0 leaves** — `model`, `message`, `tool`, `schema`, `tracing`, `prompt`, `types` (no vendor SDKs)\n- **Tier 1 modality interfaces** — `llm`, `embeddings`, `tts`, `stt`, `image`, `rerankers`, `fim` (no vendor SDKs)\n- **Tier 2 vendor implementations** — `llm/openai`, `llm/anthropic`, `embeddings/voyage`, `tts/elevenlabs`, etc. (carry the vendor SDK)\n- **Tier 3 utilities** — `tokens/{sliding,truncate,summarize}`, `batch/{openai,anthropic,gemini,concurrent}`\n- **Tier 4 agent runtime** — `agent`, `agent/team`, `session`, `memory`\n- **Tier 5 persistence** — `memory/{pgvector,postgres,sqlite}`\n\nSee the **[full module list](https://joakimcarlsson.github.io/ai/modules/)** for every package, its purpose, and the vendor SDK it carries.\n\n## Installation\n\nYou install only the modules you use. For an OpenAI chat client:\n\n```bash\ngo get github.com/joakimcarlsson/ai/llm\ngo get github.com/joakimcarlsson/ai/llm/openai\ngo get github.com/joakimcarlsson/ai/message\ngo get github.com/joakimcarlsson/ai/model\n```\n\n## Quick start\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n    \"os\"\n\n    llmopenai \"github.com/joakimcarlsson/ai/llm/openai\"\n    \"github.com/joakimcarlsson/ai/message\"\n    \"github.com/joakimcarlsson/ai/model\"\n)\n\nfunc main() {\n    client := llmopenai.NewLLM(\n        llmopenai.WithAPIKey(os.Getenv(\"OPENAI_API_KEY\")),\n        llmopenai.WithModel(model.OpenAIModels[model.GPT4o]),\n    )\n\n    response, err := client.SendMessages(context.Background(), []message.Message{\n        message.NewUserMessage(\"Hello, how are you?\"),\n    }, nil)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    fmt.Println(response.Content)\n}\n```\n\n## Supported providers\n\n| Provider | LLM | Embeddings | Images | TTS | STT | Rerankers | FIM |\n|----------|-----|------------|--------|-----|-----|-----------|-----|\n| OpenAI | ✅ | ✅ | ✅ | ✅ | ✅ | | |\n| Anthropic | ✅ | | | | | | |\n| Google Gemini | ✅ | ✅ | ✅ | | | | |\n| Google Cloud | | | | ✅ | ✅ | | |\n| AWS Bedrock | ✅ | ✅ | | | | | |\n| Azure OpenAI | ✅ | | | | | | |\n| Azure Speech | | | | ✅ | | | |\n| Vertex AI | ✅ | | | | | | |\n| Groq | ✅ | | | | | | |\n| OpenRouter | ✅ | | | | | | |\n| xAI | ✅ | | ✅ | | | | |\n| Voyage AI | | ✅ | | | | ✅ | |\n| Cohere | ✅ | ✅ | | | | ✅ | |\n| Mistral | ✅ | ✅ | | | | | ✅ |\n| DeepSeek | ✅ | | | | | | ✅ |\n| ElevenLabs | | | | ✅ | ✅ | | |\n| Deepgram | | | | | ✅ | | |\n| AssemblyAI | | | | | ✅ | | |\n\nPlus any OpenAI-compatible endpoint via [BYOM](https://joakimcarlsson.github.io/ai/advanced/byom/).\n\n## Agent framework\n\n```go\nimport (\n    \"github.com/joakimcarlsson/ai/agent\"\n    \"github.com/joakimcarlsson/ai/session\"\n)\n\nmyAgent := agent.New(llmClient,\n    agent.WithSystemPrompt(\"You are a helpful assistant.\"),\n    agent.WithTools(\u0026weatherTool{}),\n    agent.WithSession(\"user-123\", session.FileStore(\"./sessions\")),\n)\n\nresponse, _ := myAgent.Chat(ctx, \"What's the weather in Tokyo?\")\n```\n\nThe agent framework supports [sub-agents](https://joakimcarlsson.github.io/ai/agent/sub-agents/), [handoffs](https://joakimcarlsson.github.io/ai/agent/handoffs/), [fan-out](https://joakimcarlsson.github.io/ai/agent/fan-out/), [team coordination](https://joakimcarlsson.github.io/ai/agent/team-coordination/), [continue/resume](https://joakimcarlsson.github.io/ai/agent/continue/), [context strategies](https://joakimcarlsson.github.io/ai/agent/context-strategies/), [persistent memory](https://joakimcarlsson.github.io/ai/memory/), and [instruction templates](https://joakimcarlsson.github.io/ai/agent/instruction-templates/).\n\n## Batch processing\n\nEach batch backend is its own module. Native batch APIs submit a single async\njob; the concurrent runner wraps an existing client with bounded concurrency.\n\n```go\nimport (\n    \"github.com/joakimcarlsson/ai/batch\"\n    batchopenai \"github.com/joakimcarlsson/ai/batch/openai\"\n)\n\nproc := batchopenai.NewProcessor(\n    batchopenai.WithAPIKey(\"your-api-key\"),\n    batchopenai.WithModel(model.OpenAIModels[model.GPT4o]),\n)\n\nrequests := []batch.Request{\n    {ID: \"q1\", Type: batch.RequestTypeChat, Messages: msgs1},\n    {ID: \"q2\", Type: batch.RequestTypeChat, Messages: msgs2},\n}\n\nresp, _ := proc.Process(ctx, requests)\nfor _, r := range resp.Results {\n    fmt.Printf(\"[%s] %s\\n\", r.ID, r.ChatResponse.Content)\n}\n```\n\nPer-item error handling, progress callbacks, and async channel-based tracking\nare all supported. See the [batch processing docs](https://joakimcarlsson.github.io/ai/advanced/batch-processing/).\n\n## Workspace setup\n\nThe repo is a pure Go workspace with no root module. To work locally:\n\n```bash\ngit clone https://github.com/joakimcarlsson/ai\ncd ai\ncp go.work.example go.work   # go.work is gitignored\ngo build ./...\n```\n\n`go.work.example` is the canonical workspace file checked into git;\ncontributors copy or symlink it to `go.work`.\n\n## Versioning\n\nEach module is versioned independently using path-prefixed git tags. The tag\nprefix **must** match the subdirectory path exactly — this is how the Go module\nsystem resolves versions.\n\n| Module | Tag format | Example |\n|--------|-----------|---------|\n| llm/openai | `llm/openai/vX.Y.Z` | `llm/openai/v0.1.0` |\n| embeddings/voyage | `embeddings/voyage/vX.Y.Z` | `embeddings/voyage/v0.1.0` |\n| agent | `agent/vX.Y.Z` | `agent/v0.2.0` |\n| memory/pgvector | `memory/pgvector/vX.Y.Z` | `memory/pgvector/v0.1.0` |\n\nAll modules follow [semantic versioning](https://semver.org).\n\n## Release process\n\nReleases follow the AWS SDK v2 pattern: CI on main is the safety net, git tags\ndrive `go get` resolution, and dated GitHub Releases provide changelogs.\n\n### 1. Ensure main is green\n\nCI must pass on the latest commit before tagging.\n\n### 2. Tag modules that changed\n\n```bash\n# List every module\nscripts/release.sh modules\n\n# Tag a single module (dry-run — creates local tag only)\nscripts/release.sh tag -m llm/openai -v v0.1.0\n\n# Tag and push\nmake release-tag MODULE=llm/openai VERSION=v0.1.0\n```\n\nThe script verifies the module's `go.mod` exists and the tag prefix matches\nthe directory path.\n\n### 3. Warm the Go module proxy\n\n```bash\nscripts/release.sh warm -t llm/openai/v0.1.0\n```\n\nThis ensures the tagged version is immediately available via `go get`.\n\n### 4. Create a dated GitHub Release\n\n```bash\n# Dry-run (shows what would be published)\nscripts/release.sh release\n\n# Publish\nmake release-publish\n```\n\nThis creates a `release-YYYY-MM-DD` tag and a GitHub Release listing all\nmodule tags created since the previous release.\n\n## License\n\nSee [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoakimcarlsson%2Fai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoakimcarlsson%2Fai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoakimcarlsson%2Fai/lists"}