What you can do with jev-tree

Jev-tree is a small walk. TypeSafe’s Jev can list 255 options in one choice question. A real catalog is bigger. You give the library a JSON taxonomy and a record; it asks one small choice per level (or per partition) and returns a leaf.

There is no website product. The repo is the product. An interactive essay lives at jev-tree explained.

Current release: 0.1.0, public preview. Live calls need AI_GATEWAY_API_KEY (Vercel AI Gateway, not an OpenAI key). Production accuracy has not been independently validated.

Why a tree

A flat choice with 320 incident types does not fit. Truncating to 255 silently drops Cape Town. Auto-partitioning a flat list is the fallback. Explicit branches beat a 10,000-item flat list because every named child is in the question.

Default 32 options per call (narrower than 255). Raise maxFanout up to 255 if you must.

Install

npm install jev-tree

import { createJevTree } from 'jev-tree';

const tree = createJevTree({ maxFanout: 32 });
const result = await tree.select({
  state: 'Replica lag 47m on primary still accepting writes',
  question: 'Which incident type is this?',
  shape: { /* TreeNode */ },
});

if (result.reason === 'unavailable') {
  // timeout / provider / budget. Do not treat result.node as a chosen leaf.
} else {
  result.ids;    // ['catalog', 'data', 'replica_lag']
  result.value;  // whatever you stored on that leaf
}

Ids in your taxonomy do not have to be legal Jev choice keys. The library sends o0, o1, … and maps back.

CLI

npx jev-tree                         # offline demo, no key
npx jev-tree --live --shape examples/taxonomy.json --state "the record"
npx jev-tree --count --shape examples/taxonomy.json

Fail closed

Timeouts, 429s after retries, invalid answers, depth/call caps, and oversized input return reason: 'unavailable' and do not invent a leaf. That is the same policy as jevlogs: a miss is better than a wrong queue.

Evidence

A 320-leaf multi-region catalog (past the 255 cap) with labeled tickets is on Hugging Face: reachjalil/jev-tree-choice-cap. Write-up: docs/article/jev-tree-choice-cap.md. Click through the wall: jev-tree explained.

What this is not

Not a host for Jev. Not a substitute for a well-authored taxonomy. Not a guarantee that Jev will pick the gold leaf — only that it will never be asked more than maxFanout names at once, and that a failure will not mint an id.

License

MIT. Independent of TypeSafe and Vercel. The hosted model is theirs, via AI Gateway.