@kody/ai

@kody/ai — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by name only — never paste key values. Do not disable live webhooks or jobs (this package ships none).

Secrets / storage

Multi-account: account: "work" → openaiApiKey-work (or matching provider secret), or pass apiKeySecret explicitly. Live @kody/ai storage is the platform bucket — fork (or invoke the user's copy) before writing defaults.

Import paths

Prefer static kody:@kody/ai/... imports from execute. Do not lead with packages.invoke. Prefer runModelStep when a host package should execute tools in its own package context (correct secret allowlists). runAgentTurn still runs tools as package ai.

Smoke test (read-only)

Safe before credentials: returns { ok: true, live: false } plus setup URLs. With a secret and host approval, lists models only — no completion tokens.

import smokeTest from 'kody:@kody/ai/smoke-test'

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

Equivalent via root:

import ai from 'kody:@kody/ai'

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

dryRun / confirm

./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,
	})
}

Edge cases