Typed Questions — ถามให้เป็นชนิดข้อมูลAsk Typed Questions with Jev — AI-Core + Jev in Practice

Part 3 of ten: Build a single request with Choice and Noul, pin the model, and read documented response fields without inventing an API.

Local review draft • Default code uses offline fixtures. Numbers are fictional scenarios, not measured Jev results. Faster performance and lower cost remain hypotheses.

Outcome and prerequisites

Start with the companion repository and its detailed README. The website ZIP remains an alternative offline snapshot; run the same Node commands from either project root. GitHub repository · README / Quickstart

Use the same Support Ticket Decision Lab throughout the series. Have Node 22.18+, a terminal and a writable directory. Run commands from the cloned ai-core-jev-tutorial root, or the extracted ai-core-jev-lab folder if using the website ZIP. Offline work needs no npm install. Allow roughly 20–40 minutes for experiments; the article reading-time label excludes hands-on work.

Download the complete code and tests (ZIP) · Project README

This chapter focuses on src/providers.mjs. Fixture outputs test the integration mechanics only. The author did not install the SDK or use an API key while preparing the lab. The separately documented live path has not been tested against the API.

How this boundary works

Choose the smallest output your code needs. Routing needs a closed Choice, not a paragraph explaining a department. A human-request check needs a Noul probability, not a generated yes/no sentence. The two questions see the same ticket independently. Combining them in one request reduces duplicated state transmission in this architecture; it does not prove a latency or cost benefit for your workload.

The question ID is an application handle, so make the instructions complete rather than relying on the name route or wantsHuman to teach the model the task. Criteria should distinguish invoices and payments from software failures. Keep an other option, but evaluate ambiguous and out-of-domain tickets: adding that label does not guarantee graceful rejection.

A typed result is a machine-readable proposal, not a certificate of truth. The adapter returns Choice fields and the Noul value exactly as documented. It must not invent a separate Noul confidence. Pin jev-1.13.0 so the initial evaluation targets one model version; log the returned model too, since an alias is not a reproducibility boundary.

Seven practical steps

Step 1 — Inspect requestShape

Inspect requestShape. Its state contains only the ticket text. The helper exists separately from the SDK so you can test request construction offline and inspect every byte that would be sent, without resolving the package or making an authenticated call.

Step 2 — Write distinct route criteria

Write distinct route criteria. Read each description and ask whether an ordinary colleague could use it consistently. If billing and technical overlap, clarify the policy or add a separate decision; do not hide a business-policy disagreement inside a confidence threshold.

Step 3 — Keep the human-request question atomic

Keep the human-request question atomic. It asks whether the customer explicitly wants a human, not whether the model thinks a person would be useful. Distinguishing these meanings gives the evaluator a label it can actually annotate, review and contest.

Step 4 — Print T-004 and compare it with T-001

Print T-004 and compare it with T-001. Both concern billing, but only one explicitly requests a human. In the fixtures that distinction changes wantsHuman.noul. Your program, not a generated sentence, combines the fields into a routing policy.

Step 5 — Trace the live-only import without executing it

Trace the live-only import without executing it. providers.mjs imports choice, noul and TypeSafeClient only after the explicit live flag and an API-key check. The rest of the project stays usable without node_modules. The live adapter is documented code, not a verified live integration.

Step 6 — Read an actual fixture response

Read an actual fixture response. Choice contains choice, probabilities and confidence; Noul contains type and noul. Do not use questions.route or a top-level route as an answer. Those are different locations and accepting either silently can hide a version mismatch.

Step 7 — Run the contract tests

Run the contract tests. Then rewrite one criterion in a disposable copy and print the request again. Offline canned predictions will not change when criteria change; that is an intentional limit of the mock, and an important reason not to call this experiment a live model benchmark.

Files and commands

Companion code on GitHub: ai-core-jev-tutorial · README. Use the companion repository as the default working copy. These file links pin the tested revision. src/providers.mjs · src/questions.mjs

Compare this file with the source in the ZIP before editing. The listing is the implementation used by the lab, not pseudocode. Model output is input to validation and routing code; it grants no permission to bypass approval.

src/providers.mjs

import {readFile} from 'node:fs/promises';
import {performance} from 'node:perf_hooks';
import {requestShape,ROUTES,ROUTE_QUESTION,HUMAN_QUESTION} from './questions.mjs';
import {tokenUsage} from './contracts.mjs';
export async function fixtureProviders() {
  const fixtures=JSON.parse(await readFile(new URL('../data/predictions.mock.json',import.meta.url),'utf8'));
  async function call(kind,ticket) {
    const f=fixtures[ticket.id]?.[kind];if(!f)throw new Error('fixture not found');
    return {value:structuredClone(f.value),attempt:{provider:kind,mode:'MOCK / FICTIONAL SCENARIO',usage:f.usage,scenarioLatencyMs:f.scenarioLatencyMs,wallMs:null,httpAttempts:1,costComplete:true}};
  }
  return {jev:t=>call('jev',t),baseline:t=>call('baseline',t)};
}
export async function liveJev(ticket,{live=false}={}) {
  if(!live)throw new Error('Live API requires explicit --live');
  if(!process.env.TYPESAFE_API_KEY)throw new Error('TYPESAFE_API_KEY is not set');
  // Offline mode never resolves the SDK or reads a secret.
  const {choice,noul,TypeSafeClient}=await import('@typesafe-ai/sdk');
  const client=new TypeSafeClient({defaultModel:'jev-1.13.0'});
  const started=performance.now();
  const value=await client.systemOne({state:requestShape(ticket).state,questions:{route:choice(ROUTE_QUESTION,{...ROUTES}),wantsHuman:noul(HUMAN_QUESTION)}});
  return {value,attempt:{provider:'jev',mode:'LIVE / NOT VERIFIED BY THE AUTHOR',usage:tokenUsage(value),wallMs:performance.now()-started,scenarioLatencyMs:null,httpAttempts:null,costComplete:false}};
  // SDK retries may occur internally. No outer retry loop is added. Final
  // response usage alone cannot establish the total bill across failed attempts.
}

Run these offline commands without an SDK installation or API key:

node src/cli.mjs request --ticket T-001
node src/cli.mjs request --ticket T-004
node src/cli.mjs demo --mode jev --ticket T-004
node --test --test-reporter=spec test/contracts.test.mjs

Verify the expected behavior

T-004 should end in needs_review even though its route is billing. Confirm that no fixture claims a separate Noul confidence and that request printing does not require a key. A response to changed criteria requires a real provider; our mock deliberately cannot answer that research question.

Read the named tests and refusal paths, not just the exit code or final label. Unknown values must remain unknown, and every report must distinguish simulation inputs from real measurements.

Troubleshooting

If a request depends on an earlier answer to construct its state, it cannot be made independent by putting both questions into one object. Split the calls and count both. If the live package is unavailable, keep working offline; do not replace documented helper names with guessed APIs.

When previewing with Python http.server, use the .html continuation links below when needed. Extensionless series chips rely on GitHub Pages resolution; that documented preview limitation is separate from the Node example.

Change one thing, then test

Rewrite the billing criterion to clarify a boundary you disagree with, then print requestShape and review the change. The fixture response will remain unchanged because it is canned. Record the real model experiment you would need to test the revised criterion, including the frozen ticket set and unchanged success rule.

Make changes in a disposable copy, retain the reference files for comparison, and restore them before the next chapter. If you later use a real provider, create a new experiment record rather than overwriting the fixture transcript.

Next checkpoint

Before moving on, identify the contract file, the policy file, what was observed in a run, and what remains untested against a real model. Keeping those four things separate matters more than making the demo look effortless.

← Previous chapter · Next chapter →

References and evidence

Key takeaways