@kody/ai

@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.

Auth

Secret-backed HTTP. There is no AI OAuth integration and no baked-in key. Do not open /connect/oauth for this package.

Readable defaults (not secrets) live in this package's packageStorage() after you fork: provider, model, baseUrl, cloudflareAccountId, cloudflareAiGatewayId. Writes default to dry-run and need confirm: true.

Required setup

1. Create an API key in the provider console. Never paste it into chat.
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

Exports

• kody:@kody/ai — overview, or generateText / generateObject when you pass messages / schema
• kody:@kody/ai/complete — one chat completion (generateText)
• kody:@kody/ai/generate-object — structured JSON from a JSON Schema
• kody:@kody/ai/model-step — model-only step plus default Kody search/execute tool schemas
• kody:@kody/ai/turn — optional tool-using agent turn (runs kody.search / kody.execute in this package)
• kody:@kody/ai/settings — fork-local provider/model defaults; writes need confirm: true
• kody:@kody/ai/guide — console steps and prefilled secret URLs
• kody:@kody/ai/smoke-test — dry-run self-check; optional models-list when a secret exists
• kody:@kody/ai/types — input/output type metadata

Prefer runModelStep when a host package should execute tools in its own package context (correct secret allowlists). runAgentTurn still runs tools as package ai.

No jobs or schedules ship in this package.

Smoke test

./smoke-test is safe before anyone saves credentials: it returns { ok: true, live: false } and the setup URLs. After a secret and host approval, invoke the package so placeholders resolve. The live path lists models only — it does not spend completion tokens.

import ai from 'kody:@kody/ai'

export default async function main() {
	return await ai()
}

import { packages } from 'kody:runtime'

export default async function main() {
	return await packages.invoke({
		kodyId: 'ai',
		exportName: './smoke-test',
	})
}

dryRun

./settings writes default to dry-run and need confirm: true. Completions are live when you pass messages (that is the helper). Pass dryRun: true to preview the provider, model, URL, and body without calling the vendor.

import { generateText } from 'kody:@kody/ai'

export default async function main() {
	return await generateText({
		provider: 'openai',
		messages: [{ role: 'user', content: 'Say hello in one word.' }],
		dryRun: true,
	})
}

Live completion after the secret exists:

import { generateText } from 'kody:@kody/ai'

export default async function main() {
	return await generateText({
		provider: 'openai',
		messages: [{ role: 'user', content: 'Say hello in one word.' }],
	})
}

Structured JSON:

import { generateObject } from 'kody:@kody/ai'

export default async function main() {
	return await generateObject({
		provider: 'openai',
		messages: [{ role: 'user', content: 'Label this: I love this package' }],
		schema: {
			type: 'object',
			properties: {
				label: { type: 'string', enum: ['positive', 'neutral', 'negative'] },
			},
			required: ['label'],
			additionalProperties: false,
		},
		dryRun: true,
	})
}

Errors

Docs

• OpenAI Chat Completions
• Anthropic Messages
• Groq OpenAI compatibility
• Cloudflare Workers AI OpenAI compatible