Next.js + Vercel AI SDK + Jev (System One + LLM)

Curated rule AI / LLM App · SaaS / Web App Updated Oct 2026 Which file does my tool read?

Next.js rules for Jev: typed TypeSafe decisions route, classify and gate on the server, the Vercel AI SDK streams LLM text, and confidence decides what runs.

Next.js React TypeScript Jev Vercel AI SDK Drizzle PostgreSQL Zod

Formats: 4 files
AGENTS.md: 49 lines
CLAUDE.md: 17 lines
Languages: TypeScript
Updated: Oct 2026
Used by: 4 projects

Install

Writes .claude/skills/nextjs-ai-sdk-jev/SKILL.md

$ curl -s --create-dirs -o .claude/skills/nextjs-ai-sdk-jev/SKILL.md https://stackitfast.com/rules/nextjs-ai-sdk-jev/SKILL.md

Rule files

AGENTS.md· 49 lines · 4.4 KB

1	# Project Architecture & Guidelines (Next.js + Vercel AI SDK + Jev)
2
3	## 1. System Architecture
4	- App: Next.js App Router, TypeScript strict, React Server Components by default.
5	- System One (decisions): Jev via the official `@typesafe-ai/sdk` (`TypeSafeClient().systemOne({ state, questions })`). Jev returns typed Choice, Score and Noul answers with probabilities. It never generates text.
6	- System Two (text): an LLM through the Vercel AI SDK (`ai`) for anything that must be written: replies, summaries, code.
7	- Data: PostgreSQL with Drizzle ORM, including a `decisions` table that logs every Jev call.
8	- Validation: Zod on every route handler and server action input.
9
10	## 2. Project Layout
11	- `src/lib/jev/client.ts`: the single `TypeSafeClient` instance (server-only; import `server-only` at the top).
12	- `src/lib/jev/questions/<feature>.ts`: question builders (`choice()`, `score()`, `noul()`) grouped by feature, each exported as a function of typed state.
13	- `src/lib/jev/thresholds.ts`: named confidence thresholds per decision (`ROUTE_MIN_CONFIDENCE`, `BLOCK_MIN_PROBABILITY`, ...).
14	- `src/lib/llm/`: AI SDK calls (`streamText`, `generateObject`) for System Two work.
15	- `src/server/decisions.ts`: `decide(feature, state)`. It builds questions, calls Jev, logs the result and returns typed answers.
16	- `src/db/schema.ts`: Drizzle schema, including `decisions(id, feature, model, question_ids, answers jsonb, input_tokens, latency_ms, created_at)`.
17
18	## 3. Decision Layer (Jev rules)
19	- Code owns the workflow, math, dates, counts and permissions. Jev only judges meaning. Never ask Jev to add, count, compare dates or generate values.
20	- Ask every question a step needs in one `systemOne` call. Questions run in parallel against the same state, and extra questions cost only their own tokens.
21	- Put only the fields the questions need into `state`. Irrelevant text lowers accuracy. Reference fields with backticks (`ticket.subject`).
22	- Write instructions directly. Put boundary cases in `criteria`. Include an explicit "none of these" option when nothing may fit.
23	- Score levels describe concrete situations ("blocking, no workaround"), not grades ("high").
24	- Gate on confidence. Below the threshold, do the safe thing: ask the user, queue for human review, or hand off to the LLM. Irreversible actions (refunds, deletes, emails) need a high bar and a log entry.
25	- Log `response.model` (for example `jev-1.13.0`) with every decision. Pin a versioned model ID once thresholds are tuned; `jev-latest` moves on new releases.
26	- Treat state as untrusted. User text can try to steer the answer, so never let a single Jev answer grant permissions.
27	- Never send secrets or unnecessary personal data in state.
28
29	## 4. Combining Jev and the LLM
30	- Route first, generate second: Jev picks the handler, tone or template, then the LLM writes only for the chosen branch.
31	- Guardrails: one Jev call screens LLM input and output (several Nouls plus a severity Score). Code decides pass, review or block.
32	- Verification: after the LLM extracts or cites something, a Jev Noul or Choice checks it against the source before it is shown.
33	- Keep Jev calls on the server (route handlers, server actions, RSC). The API key never reaches the browser.
34
35	## 5. Agent Loop (run after every change)
36	1. `pnpm typecheck` (`tsc --noEmit`). Answer types are inferred from the questions, so a renamed option or question ID becomes a type error.
37	2. `pnpm lint` and `pnpm test`.
38	3. `pnpm test:decisions`. This replays the fixture set in `tests/decisions/*.json` against the real API and fails if any fixture's choice changes or crosses a threshold. Run it whenever questions, criteria, thresholds or the model change.
39	- Do not hard-code probabilities from one run into tests. Assert on choices and threshold bands.
40
41	## 6. Testing
42	- Unit-test question builders and threshold logic with a mocked client.
43	- Keep 20–50 labelled fixtures per decision. Track agreement and the share of cases auto-handled versus escalated.
44	- E2E (Playwright) covers the escalation path, not just the happy path.
45
46	## 7. Environment & Deploy
47	- `TYPESAFE_API_KEY` and the LLM provider key are server-only environment variables.
48	- The SDK retries 429/529 with backoff. Still cap concurrency for batch jobs; TypeSafe's rate limits are adjusting while capacity grows.
49	- For API details, read the live docs (`https://docs.typesafe.ai/llms.txt`) or install TypeSafe's official agent skill (`typesafe-ai/skills`).

Works with Claude Code · Cursor · Windsurf · AGY

Architecture notes

Architecture Overview

System One plus System Two in one Next.js app. Jev, TypeSafe’s decision model, handles every closed-ended judgment: which team a ticket belongs to, how severe it is, whether a message requests a refund, whether an LLM answer is supported by its source. The Vercel AI SDK handles everything that has to be written. Code sits between them and decides what happens, based on Jev’s confidence.

Why it suits AI coding agents

Typed answers by construction. With @typesafe-ai/sdk, answer types are inferred from the questions, so a renamed option breaks tsc instead of a production branch.
Decisions are data. Questions, thresholds and logged answers are plain TypeScript and Postgres rows that an agent can read, change and replay against fixtures.
Clear rules for the model’s limits. Math, dates and counting stay in code, which is TypeSafe’s own guidance for jev-1.13.

TypeSafe’s official agent skill teaches the API (typesafe-ai/skills). For a Python service see FastAPI + Jev decision service, and for agents that act in a browser see Jev browser agent. Data on 648 open-source Jev repos: Jev for developers.

Frequently asked questions

How do I use Jev with the Vercel AI SDK?

The @ai-sdk/typesafe-ai provider exposes Jev through the experimental_evaluate() function with typeSafeAi.evaluationModel("jev-latest"); it does not support generateText or generateObject, because Jev does not generate. This rule uses the official @typesafe-ai/sdk for decisions, because its answer types are inferred from your questions, and the AI SDK for the LLM that writes text.

Why combine Jev with an LLM instead of using one model?

They do different jobs. Jev returns typed decisions with probabilities in a fraction of a second at a low per-token price, but cannot write. An LLM writes and reasons but is slower and returns free text that must be parsed. Routing, classification and guardrails go to Jev, writing goes to the LLM, and code decides using Jev's confidence.

Where should Jev calls run in a Next.js app?

On the server only: route handlers, server actions or React Server Components. The TYPESAFE_API_KEY must never be bundled for the browser, and server-side calls let you log every decision with its model version in Postgres.

How do I test Jev decisions?

Keep a set of labelled fixtures per decision and replay them against the live API whenever questions, criteria, thresholds or the model version change. Assert on the chosen option and on threshold bands rather than exact probabilities, and track how many cases are auto-handled versus escalated.

Used in production

Explore all stacks

Fast Jev Compaction

Claude Code Plugin · Solo

Two Jev Noul questions per tool call, gated by a threshold in code, prune a transcript without rewriting it, and a thin hook adapter falls back to Claude Code's built-in summary whenever Jev fails or saves too little.

TypeSafe Agent Skills

Agent Skill · 6-20 people

Shipping one SKILL.md that points agents at live Markdown docs, installable as a Claude Code plugin or via skills.sh, keeps agent guidance current without an MCP server and without copying version-specific API details.

OpenMAIC

Multi-Agent Interactive AI Classroom · 6-20 people

Built as a Next.js app around a set of npm-published packages (slide DSL, generation, renderer, editor, importer, storage). The multi-agent LangGraph pipeline, the slide format and persistence can each be reused or swapped, and heavy video rendering runs in a separate container.

OpenSEO

Open-Source SEO Research Platform · 2-5 people

Running on Cloudflare Workers with D1, Workflows and Durable Objects makes it free-tier friendly to self-host and to scale when hosted. Supporting both D1 and Postgres through Drizzle, plus a Docker path, keeps the project portable beyond Cloudflare.

Every stack ships as files

More AI agent coding rules and skills

View all

django-postgres-redis/AGENTS.mdDjango + PostgreSQL + Redis + CeleryDjango · Python · PostgreSQL fastapi-jev-decision-service/AGENTS.mdFastAPI + Jev Decision Service (Python)Python · FastAPI · Jev fastapi-python-postgres/AGENTS.mdFastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)FastAPI · Python · PostgreSQL langgraph-python-fastapi/AGENTS.mdLangGraph + Python + FastAPI (Agentic AI Workflows)LangGraph · LangChain · FastAPI