Skip to content
← Public packages

@kentcdodds/jev

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

FollowFork

IntegrationsTopics: jev, typesafe, evaluation, cloudflare, ai-gateway, noul, choice, score, state-machine, transition, xstate

Version
1.0.0
License
Published
October 16, 2026
Pinned commit
cfc20cb
Rating
No ratings yet
Forks
0
Adaptation effort
—

README

Agent docs

@kentcdodds/jev

Intent

Call TypeSafe Jev (typesafe/jev) — a System One evaluation model — through Cloudflare AI Gateway, so other Kody packages can ask typed noul / choice / score questions and get calibrated answers. When agent logic is a state machine, Jev can pick the next transition from enabled events as Choices. Reuses the same cloudflareApiToken and account/gateway setup as @kentcdodds/ai when local Jev storage is empty. Success means a tiny evaluate returns { ok, answers } without anyone pasting tokens into chat.

What it does

  • Evaluate shared state against named questions (noul, choice, score)
  • Pick the next state-machine transition (./choose-transition) from enabled events
  • Walk a declarative machine toward a goal (./run-toward-goal) via repeated choices
  • Return parsed answers, model, and usage
  • Escape-hatch raw /ai/run for progressive disclosure
  • Package storage for account/gateway ids, with fallback read from @kentcdodds/ai/settings

Prerequisites / setup

  1. Save user secret cloudflareApiToken (do not paste the value in chat) with Workers AI access and host api.cloudflare.com (optional also gateway.ai.cloudflare.com if you already use @kentcdodds/ai):

    Create / update cloudflareApiToken

  2. Set Cloudflare account id (and optionally gateway id) via this package's ./settings export — stored in package storage, no republish. If you already configured @kentcdodds/ai/settings, leave Jev storage empty: reads fall back to those values. Gateway defaults to kody.

  3. AI Gateway Unified Billing — typesafe/jev is a third-party model on Cloudflare. The account needs AI Gateway credits (or BYOK for TypeSafe) or /ai/run returns HTTP 402 Insufficient balance.

  4. Confirm readiness:

import overview from 'kody:@kentcdodds/jev'

export default async function main() {
  return await overview()
}
  1. Smoke (live, cheap):
import smokeTest from 'kody:@kentcdodds/jev/smoke-test'

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

Evaluate example

import evaluate from 'kody:@kentcdodds/jev/evaluate'

export default async function main() {
  return await evaluate({
    state: 'Help! My payouts have been failing for 3 days.',
    questions: {
      is_urgent: {
        type: 'noul',
        instructions: 'Does this convey urgency?',
        criteria: {
          true: 'Explicitly time-sensitive',
          false: 'No urgency expressed',
        },
      },
    },
  })
}

Auth / settings vs @kentcdodds/ai

ConcernShared?Where
SecretYes — same namecloudflareApiToken (user scope)
Account idPrefer one setupJev ./settings → else @kentcdodds/ai/settings
Gateway idPrefer one setupSame fallback chain; default kody
ModelSeparateJev defaults to typesafe/jev

Do not invent a second Cloudflare token secret for this package.

Alternate: Vercel AI Gateway

Vercel also exposes typesafe-ai/jev via AI SDK 7 experimental_evaluate. This package implements the Cloudflare path first to match @kentcdodds/ai. Prefer Cloudflare unless you already standardize on Vercel.

Docs: Cloudflare Jev · TypeSafe · Package

Done when

  • cloudflareApiToken is saved with api.cloudflare.com host approval
  • Account (and optional gateway) resolve via ./settings or @kentcdodds/ai
  • Account has AI Gateway Unified Billing balance (or TypeSafe BYOK)
  • ./smoke-test with { live: true } returns ok: true and a noul answer
Report this listing

Log in to report this listing.