Jev quickstart

This guide explains the workflow without freezing a provider-specific snippet that may age quickly. Use the current code from the official TypeSafe quickstart or your selected provider page when you implement it.

1. Pick one bounded decision

Start with a decision whose legal outputs are already known. Ticket routing is a good first example:

• billing;
• technical;
• account;
• other.

Do not begin with a high-stakes action or a fuzzy request like “solve this case.” The smallest useful decision is easier to evaluate.

2. Choose an access path

Use TypeSafe direct for the canonical API, OpenRouter if you already use its model catalog and billing, or Vercel AI Gateway if your application is built around AI SDK and Vercel observability.

Keep the API key on the server. Pin the endpoint and model identifier used by your test.

3. Build the request

A System One request contains shared state and named questions. In simplified pseudocode:

{
  "model": "jev-latest",
  "state": "Customer: I was charged twice and need help.",
  "questions": {
    "queue": {
      "type": "choice",
      "instructions": "Which queue should receive this case?",
      "criteria": {
        "billing": "Charges, refunds, invoices, or payment problems",
        "technical": "The product is broken or unavailable",
        "account": "Login, identity, or account settings",
        "other": "None of the above"
      }
    }
  }
}

The exact field names and primitive names vary by API surface. Copy them from current provider documentation.

4. Apply policy in code

Do not automatically accept every top choice. Use the returned probability or confidence with a threshold that reflects the cost of a mistake.

For example: route clear cases automatically, but send uncertain cases to a general queue or human reviewer. Keep that threshold in code so it is visible and testable.

5. Evaluate before automating

Create a small labeled set from real, privacy-safe examples. Measure accuracy and coverage at several thresholds. Include ambiguous cases, not only easy demos.

Then run a shadow period: record what Jev would have done without changing the live action. Review disagreements before enabling automation.

6. Observe the whole workflow

Log the provider, operation, safe model identifier, HTTP status, request ID, latency, and final route. Never log API keys or raw private content.

Track outcomes separately:

• provider accepted the request;
• response matched the expected typed contract;
• policy produced a valid next step;
• downstream action completed;
• reviewer or user outcome confirmed the decision.

That is the difference between a successful API call and a working product.