ADR-009: Groq as the Default Free LLM Provider
Date: 2026-06-02
Status: Accepted
Context
The v2 TypeScript runtime (ADR-008) requires a default LLM provider. Adopters runningnpx agenthood init should be able to invoke Society members without a paid API key.
The provider must be fast enough for interactive use and reliable enough for CI.
Four providers were evaluated: OpenAI, Anthropic, Google Gemini, and Groq. The key
constraint is that the default must be free-tier accessible — adopters should not need
a billing account to experience the Society's agentic capabilities.
Decision
Groq is the default LLM provider in src/llm/providers/GroqProvider.ts. It is
selected for its free tier, low-latency inference (LPU hardware), and OpenAI-compatible
API surface, which minimises the ILLMProvider implementation complexity.
Adopters can override the provider via .agenthood/config.json:
{ "llm": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" } }
Alternatives Considered
| Option | Pros | Cons | Why Rejected |
|---|---|---|---|
OpenAI (gpt-5.4-mini) | Most widely known; extensive docs | No free tier; requires billing account | Fails the zero-cost-to-start requirement |
Anthropic (claude-haiku-4-5) | Best Society alignment; multimodal | No free tier | Same as OpenAI |
Google Gemini (gemini-flash) | Free tier available; fast | API surface differs from OpenAI; more adapter code | Groq free tier is faster |
| Groq (chosen) | Free tier; OpenAI-compatible API; fastest inference | Smaller model selection; rate limits on free tier | — |
Consequences
Easier:
- Zero-friction onboarding —
npx agenthood initworks without a credit card GroqProviderreuses the OpenAI-compatible SDK path, reducing adapter surface- Swapping providers is a one-line config change
Harder:
- Groq free tier has rate limits that may throttle heavy CI usage
- Groq model availability changes more frequently than OpenAI/Anthropic
New risk:
- If Groq discontinues the free tier, the default must be updated;
ILLMProviderabstraction ensures this is a single-file change
Note: OpenRouter is also supported as an OpenAI-compatible provider
(src/llm/providers/OpenRouterProvider.ts, api.openrouter.ai/api/v1), giving access
to many models behind one key — it does not change this default-provider decision.