diff options
Diffstat (limited to 'docs/api-keys-setup.md')
| -rw-r--r-- | docs/api-keys-setup.md | 15 |
1 files changed, 10 insertions, 5 deletions
diff --git a/docs/api-keys-setup.md b/docs/api-keys-setup.md index 1a9daf9..83c98e1 100644 --- a/docs/api-keys-setup.md +++ b/docs/api-keys-setup.md @@ -6,9 +6,9 @@ Providers, in escalation-ladder order (cheapest/free first): | Provider | Status | Cost | Wire format | |---|---|---|---| -| Groq | to add (works once configured — Phase 1's `openaicompat` adapter, no dedicated phase needed) | free tier (real, no card required historically) | OpenAI-compatible | -| OpenRouter | to add (same as Groq) | free tier (rate-limited) + pay-as-you-go | OpenAI-compatible | -| OpenAI | to add (same as Groq) | prepaid credit, no ongoing free tier | OpenAI-compatible (native) | +| Groq | **wired up (Phase 5)** — `agent.type: "groq"` works as soon as a key is in `config.toml` (Phase 1's `openaicompat` adapter, no dedicated adapter package needed) | free tier (real, no card required historically) | OpenAI-compatible | +| OpenRouter | **wired up (Phase 5)** — `agent.type: "openrouter"` works as soon as a key is in `config.toml` (same adapter as Groq) | free tier (rate-limited) + pay-as-you-go | OpenAI-compatible | +| OpenAI | **wired up (Phase 5)** — `agent.type: "openai"` works as soon as a key is in `config.toml` (same adapter as Groq) | prepaid credit, no ongoing free tier | OpenAI-compatible (native) | | Google (Gemini) | **wired up (Phase 4)** — `agent.type: "google"` works as soon as a key is in `config.toml` | paid (already have account) | native (Gemini API) | | Anthropic (Claude) | **wired up (Phase 2)** — `agent.type: "anthropic"` works as soon as a key is in `config.toml` | paid (already have account) | native (Messages API) | @@ -60,6 +60,7 @@ Free tier, no credit card required to start. Good first escalation rung above lo 3. Copy the key immediately — Groq only shows it once (`gsk_...`). 4. Rate limits (free tier, vary per model): roughly 30 requests/minute, 6K–70K tokens/minute, 1K–14.4K requests/day, 100K–500K tokens/day depending on the specific model. Check `console.groq.com/settings/limits` for your account's current numbers per model — this varies enough by model that it's worth checking directly rather than trusting a fixed table here. 5. Put the key in `config.toml` under `[providers.groq]` as shown above. `endpoint` is Groq's OpenAI-compatible base: `https://api.groq.com/openai/v1`. +6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "groq"` as a usable runner — no restart-time flag needed beyond having the key present. To turn it off without removing the key, set `[runners] groq = false`. --- @@ -72,6 +73,7 @@ Aggregates many providers/models behind one key, including models with a `:free` 3. Free-tier limits: **without any credit purchase**, 50 free-model requests/day total across all `:free`-suffixed models. **With $10+ in purchased credits**, that jumps to 1000 requests/day (a one-time credit purchase, not a subscription) — worth doing once your usage grows past the bare free tier, since it's a 20x limit increase for a fixed cost, not a recurring charge. 4. Pick a free model when configuring the harness — model IDs ending in `:free` (e.g. `meta-llama/llama-3.3-70b-instruct:free`) don't draw down credits. Browse current free models at `openrouter.ai/models?max_price=0`. 5. `endpoint` is `https://openrouter.ai/api/v1`. +6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "openrouter"` as a usable runner. To turn it off without removing the key, set `[runners] openrouter = false`. --- @@ -84,6 +86,7 @@ No meaningful ongoing free tier at this point — expect to prepay. Included in 3. **Dashboard → API keys** (`platform.openai.com/api-keys`) → **Create new secret key**. Name it, copy it (`sk-...`) — shown once. 4. Consider setting a spend limit under **Billing → Limits** so a runaway harness escalation can't produce a surprise bill — this matters more here than for Groq/OpenRouter's free tiers. 5. `endpoint` is `https://api.openai.com/v1`. +6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "openai"` as a usable runner. To turn it off without removing the key, set `[runners] openai = false`. --- @@ -119,7 +122,7 @@ Same situation as Gemini: `credentials/claude/` holds the `claude` CLI's OAuth s ## Sanity-checking a key works -Once phase 1/2/4 of the harness redesign land (native `Provider` adapters), the quickest check is submitting a trivial role-typed task pinned to a single rung, e.g. via the CLI: +All five providers are wired up as of Phase 5 (`internal/cli/cloudrunners.go`). The quickest check is submitting a trivial task pinned to a single provider directly (bypassing role-based escalation), e.g. via the CLI: ```bash ./claudomator run - <<'EOF' @@ -131,4 +134,6 @@ agent: EOF ``` -and checking `GET /api/budget` afterward to confirm the provider's spend/usage was recorded. Until then, you can at minimum confirm the key itself is valid with a raw `curl` against the provider's chat-completions endpoint using the docs above. +and checking `GET /api/budget` afterward to confirm the provider's spend/usage was recorded. You can also confirm the key itself is valid directly with a raw `curl` against the provider's chat-completions endpoint using the docs above. + +To exercise a provider through the escalation ladder instead of pinning `agent.type` directly, create a role via `POST /api/roles/{role}/versions` with an `escalation_ladder` naming the provider, activate it with `POST /api/roles/{role}/activate?version=1`, and submit a task with `agent.role` set instead of `agent.type`/`agent.model` — see `CLAUDE.md`'s "Role-based dispatch & escalation" section. |