Skip to content
← Public packages

@kentcdodds/jev

Call TypeSafe Jev evaluations via Cloudflare AI Gateway (same token/gateway as @kentcdodds/ai).

FollowFork

Files

choose-transition.ts

209 lines · 6.4 KB · TypeScript
/**
 * Pick the next state-machine transition with TypeSafe Jev.
 * Model agent logic as a state machine: give Jev the state + goal; enabled
 * events become Choices (pattern credit: David Khourshid / Stately).
 *
 * Single enabled event short-circuits without calling Jev (confidence 1).
 * Zero events returns a clear error. Multi-event builds a `choice` question
 * and calls `./evaluate`.
 *
 * @param input.state - Current machine/agent state snapshot (string or serializable object; XState `{ value, context? }` is fine).
 * @param input.goal - Desired outcome / what we are trying to achieve.
 * @param input.events - Enabled events as id→description map or `{ id, description }[]`.
 * @param input.context - Optional extra blob merged into the evaluate state.
 * @param input.accountId - Optional Cloudflare account id override.
 * @param input.gatewayId - Optional AI Gateway id override.
 * @param input.model - Optional model id (default `typesafe/jev`).
 * @returns `{ ok, event, confidence, probabilities, answers, model, usage }` — never logs secrets.
 *
 * @example
 * import chooseTransition from 'kody:@kentcdodds/jev/choose-transition'
 *
 * const result = await chooseTransition({
 *   state: { value: 'awaitingPayment', context: { retries: 1 } },
 *   goal: 'Collect payment or escalate if stuck',
 *   events: {
 *     RETRY: 'Retry the payment charge',
 *     ESCALATE: 'Notify a human operator',
 *     CANCEL: 'Cancel the order',
 *   },
 * })
 * // => { ok: true, event: 'RETRY', confidence, probabilities, ... }
 */

import evaluate from './evaluate.ts'
import buildChoiceFromEvents, {
	normalizeTransitionEvents,
} from './build-choice-from-events.ts'
import type {
	Answer,
	ChoiceAnswer,
	ChooseTransitionInput,
	ChooseTransitionResult,
	JevState,
	JevUsage,
	TransitionEvents,
} from './types.ts'
import { DEFAULT_JEV_MODEL } from './types.ts'

const QUESTION_KEY = 'transition'

function isChoiceAnswer(answer: Answer | undefined): answer is ChoiceAnswer {
	return Boolean(answer && answer.type === 'choice' && typeof answer.choice === 'string')
}

function buildEvaluateState(input: ChooseTransitionInput): JevState {
	const blob: Record<string, unknown> = {
		goal: input.goal,
		machineState: input.state,
	}
	if (input.context !== undefined) {
		blob.context = input.context
	}
	return blob
}

/**
 * Pick the next state-machine transition with TypeSafe Jev.
 * Model agent logic as a state machine: give Jev the state + goal; enabled
 * events become Choices (pattern credit: David Khourshid / Stately).
 *
 * Single enabled event short-circuits without calling Jev (confidence 1).
 * Zero events returns a clear error. Multi-event builds a `choice` question
 * and calls `./evaluate`.
 *
 * @param input.state - Current machine/agent state snapshot (string or serializable object; XState `{ value, context? }` is fine).
 * @param input.goal - Desired outcome / what we are trying to achieve.
 * @param input.events - Enabled events as id→description map or `{ id, description }[]`.
 * @param input.context - Optional extra blob merged into the evaluate state.
 * @param input.accountId - Optional Cloudflare account id override.
 * @param input.gatewayId - Optional AI Gateway id override.
 * @param input.model - Optional model id (default `typesafe/jev`).
 * @returns `{ ok, event, confidence, probabilities, answers, model, usage }` — never logs secrets.
 *
 * @example
 * import chooseTransition from 'kody:@kentcdodds/jev/choose-transition'
 *
 * const result = await chooseTransition({
 *   state: { value: 'awaitingPayment', context: { retries: 1 } },
 *   goal: 'Collect payment or escalate if stuck',
 *   events: {
 *     RETRY: 'Retry the payment charge',
 *     ESCALATE: 'Notify a human operator',
 *     CANCEL: 'Cancel the order',
 *   },
 * })
 * // => { ok: true, event: 'RETRY', confidence, probabilities, ... }
 */
export default async function chooseTransition(
	input: ChooseTransitionInput,
): Promise<ChooseTransitionResult> {
	if (!input || typeof input.goal !== 'string' || !input.goal.trim()) {
		return {
			ok: false,
			error: 'goal is required (non-empty string describing the desired outcome)',
		}
	}

	if (input.state === undefined || input.state === null) {
		return {
			ok: false,
			error: 'state is required (current machine/agent snapshot)',
		}
	}

	const criteria = normalizeTransitionEvents(input.events as TransitionEvents)
	const eventIds = Object.keys(criteria)

	if (eventIds.length === 0) {
		return {
			ok: false,
			error:
				'events is empty — pass at least one enabled event (id → description) as Choices',
		}
	}

	// Single enabled event: no model call; confidence 1.
	if (eventIds.length === 1) {
		const event = eventIds[0]
		const probabilities: Record<string, number> = { [event]: 1 }
		const answers: Record<string, Answer> = {
			[QUESTION_KEY]: {
				type: 'choice',
				choice: event,
				confidence: 1,
				probabilities,
			},
		}
		return {
			ok: true,
			event,
			confidence: 1,
			probabilities,
			answers,
			model: input.model?.trim() || DEFAULT_JEV_MODEL,
			usage: undefined,
			shortCircuited: true,
		}
	}

	const { questions } = buildChoiceFromEvents(criteria, {
		questionKey: QUESTION_KEY,
		instructions:
			'Given the goal and current machine state, which enabled event should fire next? Pick exactly one.',
	})

	const result = await evaluate({
		state: buildEvaluateState(input),
		questions,
		accountId: input.accountId,
		gatewayId: input.gatewayId,
		model: input.model,
	})

	if (!result.ok) {
		return {
			ok: false,
			status: result.status,
			error: result.error,
			setup: result.setup,
		}
	}

	const answer = result.answers[QUESTION_KEY]
	if (!isChoiceAnswer(answer)) {
		return {
			ok: false,
			status: result.status,
			error:
				'Jev returned no choice answer for transition — check events criteria and response shape',
			answers: result.answers,
			model: result.model,
			usage: result.usage,
		}
	}

	const event = answer.choice
	if (!criteria[event]) {
		return {
			ok: false,
			status: result.status,
			error: `Jev chose "${event}" which is not in the enabled events list`,
			answers: result.answers,
			model: result.model,
			usage: result.usage,
		}
	}

	return {
		ok: true,
		event,
		confidence: typeof answer.confidence === 'number' ? answer.confidence : 0,
		probabilities: answer.probabilities || {},
		answers: result.answers,
		model: result.model,
		usage: result.usage as JevUsage | undefined,
		shortCircuited: false,
		meta: result.meta,
	}
}