# @kody/ai

Generic geometric mark (not a vendor logo). This package is not affiliated
with OpenAI, Anthropic, Groq, or Cloudflare.

## Intent

Give every Kody account reusable, provider-agnostic AI helpers: chat
completions, structured JSON generation, and a thin host-side tool loop.
Callers pass the provider, model, and their own saved API key. Success means
a forked copy can dry-run a request, then generate text or JSON, without
anyone baking in personal keys, account ids, or a single vendor.

Live `@kody/ai` storage is the platform package bucket, not the caller's.
Fork first (or `packages.invoke` the user's copy) before saving defaults.

## What it does

- Chat completions across OpenAI, Anthropic, Groq, Cloudflare Workers AI, and OpenAI-compatible base URLs
- Structured JSON generation from a JSON Schema
- Model-only steps with default Kody search/execute tool schemas for host packages
- Optional tool-using agent turns (search/execute run as package `ai`)
- Fork-local provider/model defaults via `./settings` (writes need `confirm: true`)

No jobs or schedules ship in this package.

## Prerequisites / setup

**API key** (secret-backed). There is no AI OAuth integration and no baked-in key.
Do not open `/connect/oauth` for this package. Never paste key values into chat.
Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke, and dryRun.

| Secret | Provider | Hosts to approve |
| --- | --- | --- |
| `openaiApiKey` | OpenAI | `api.openai.com` |
| `anthropicApiKey` | Anthropic | `api.anthropic.com` |
| `groqApiKey` | Groq | `api.groq.com` |
| `cloudflareApiToken` | Cloudflare Workers AI | `api.cloudflare.com`, `gateway.ai.cloudflare.com` |
| `openaiCompatibleApiKey` | Custom OpenAI-compatible base URL | the host you pass as `baseUrl` |

Readable defaults (not secrets) live in this package's `packageStorage()`
after you fork: `provider`, `model`, `baseUrl`, `cloudflareAccountId`,
`cloudflareAiGatewayId`.

1. Create an API key in the provider console.
2. Save the matching secret (pick one provider to start):

https://kody.codes/account/secrets/new?name=openaiApiKey&description=OpenAI%20API%20key%20for%20chat%20completions&allowedHosts=api.openai.com&scope=user

https://kody.codes/account/secrets/new?name=anthropicApiKey&description=Anthropic%20API%20key%20for%20Messages&allowedHosts=api.anthropic.com&scope=user

https://kody.codes/account/secrets/new?name=groqApiKey&description=Groq%20API%20key%20for%20OpenAI-compatible%20chat&allowedHosts=api.groq.com&scope=user

https://kody.codes/account/secrets/new?name=cloudflareApiToken&description=Cloudflare%20API%20token%20for%20Workers%20AI&allowedHosts=api.cloudflare.com,gateway.ai.cloudflare.com&scope=user

https://kody.codes/account/secrets/new?name=openaiCompatibleApiKey&description=API%20key%20for%20an%20OpenAI-compatible%20base%20URL&scope=user

3. Approve the host(s) listed above for that secret.
4. Cloudflare also needs `cloudflareAccountId` in `./settings` on your fork
   (optional `cloudflareAiGatewayId` if you already have a gateway — this
   package never creates one).
5. Run the smoke test.

### Additional accounts

Pass `account: "work"` to use `openaiApiKey-work` (or the matching provider
secret), or pass `apiKeySecret` explicitly.

https://kody.codes/account/secrets/new?name=openaiApiKey-work&description=OpenAI%20API%20key%20for%20chat%20completions&allowedHosts=api.openai.com&scope=user

## Done when

- A provider secret is saved and its host(s) are approved
- Smoke test returns `{ ok: true }` (`live: false` before credentials; models-list only when a secret exists — no completion tokens)
- `./settings` writes refuse unless `confirm: true`; `dryRun: true` never calls the vendor

## Branding

Keep `LICENSE` (MIT), `## Intent`, and `community-icon.svg` intact for community listing.

## Docs

- [OpenAI Chat Completions](https://platform.openai.com/docs/api-reference/chat)
- [Anthropic Messages](https://docs.anthropic.com/en/api/messages)
- [Groq OpenAI compatibility](https://console.groq.com/docs/openai)
- [Cloudflare Workers AI OpenAI compatible](https://developers.cloudflare.com/workers-ai/configuration/open-ai-compatibility/)