State Design: State Is Not a Prompt

The most common beginner mistake with Jev is treating state like a prompt — stuffing it with everything you know, phrased like instructions. It isn't a prompt. The state field is closer to the case file you slide across the desk to an expert: the expert brings the judgment; your file just needs the relevant facts, organized so the right facts are easy to find.

The question's instructions tell the expert what to decide; state is what they're deciding about. Keep those two jobs separate and your accuracy goes up. Blur them and it goes down.

#Rule 1: Filter in code, not in the model

Every irrelevant field in state costs you twice: once in input tokens, and again in accuracy. Jev's performance is jagged — strong on clean, well-scoped inputs, noticeably weaker when the signal is buried in noise. The model will not reliably ignore the parts of the file that don't matter; that's your job.

# Bad: dump the whole ORM object and hope
state = user.model_dump()  # 47 fields, most irrelevant

# Good: the case file for THIS question
state = {
    "account_age_days": (now - user.created_at).days,
    "email_domain": user.email.split("@")[-1],
    "failed_logins_24h": user.security.failed_logins_24h,
    "requested_action": request.action,
}

If a field wouldn't change a human expert's verdict, delete it. "Might be useful someday" fields are accuracy poison today.

#Rule 2: Organize like a record, not like prose

Use structured objects with stable field names over free-text blobs. A short labeled record beats a paragraph containing the same facts:

{
  "email": {
    "from": "no-reply@secure-verify-example.com",
    "subject": "URGENT: your account has been suspended",
    "body_excerpt": "Dear customer, verify your password within 24 hours...",
    "links": ["http://example.invalid/verify"]
  },
  "account": { "age_days": 12, "prior_reports": 0 }
}

state accepts a string, an object, or an array — but "accepts a string" is not "wants a string." Reach for a plain string only when the input genuinely is one indivisible text (an article body being scored, a review being moderated). The moment your judgment depends on several facts, give them several named fields.

#Rule 3: Name fields so questions can point at them

Field names in state are the shared vocabulary between your state and your question instructions. Instructions like "Answer yes if email.links contains a domain that doesn't match email.from" only work because the names line up. Two corollaries:

• Use descriptive names. body_excerpt beats text; failed_logins_24h beats n7.
• Remember what the model never sees: the keys of the questions map are not sent to the model — but state field names are. All naming effort goes into state, none into question keys.

#Rule 4: Mind the budget

The context window is 64k tokens total, with state plus the longest single question capped at 32k. For most classification work that's enormous — but it bites when you stuff raw documents into state. If you're hitting the ceiling, the fix is almost never "trim harder"; it's "you're sending a document where a record was wanted." Summarize into fields upstream (that's what LLMs are for), send the record to Jev.

#A checklist before every call

1. Could a human expert answer the question from this state alone? If not, a field is missing.
2. Does every field plausibly change the verdict? If not, delete it.
3. Do instruction references (email.from) match actual state keys?
4. Is any field duplicated, derivable, or "for context"? Cut it — jaggedness punishes clutter.

#Where to go next

• Speculative Fan-Out — one well-designed state, many questions
• Confidence & Calibration — measuring whether your state design actually works
• API Reference — the state field's type contract

#Sources

• learnjev.com — Getting started and course materials on question/state design (community documentation).
• jevai.wiki — API reference (community documentation; state field types and context limits).
• jev101.com — 什么是 Jev（中文） (community documentation, Chinese).

Unofficial fan-made handbook. Not affiliated with TypeSafe AI or jev.com.