Jev SEO: How to Use TypeSafe AI's Jev in SEO Workflows

Jev SEO is the use of TypeSafe AI's Jev as a typed decision layer inside an SEO workflow. Instead of asking a general-purpose language model to write an explanation and hoping its JSON can be parsed, you give Jev prepared evidence and ask a bounded question. The result can be a fixed choice, an ordered score, or a binary probability.

That makes Jev relevant to tasks such as classifying search intent, choosing among approved internal-link targets, scoring meta-description relevance, and routing uncertain content checks to an editor. It does not remove the rest of the system. A crawler still fetches pages. Code still calculates status codes, traffic thresholds, and priority formulas. Editors or generative models still write copy.

This guide explains where Jev fits, how its Choice, Score, and Noul primitives differ, and how to keep confidence from becoming a false promise of correctness. It also connects six focused Screpy guides so you can move from the Jev SEO concept to one bounded workflow you can evaluate.

What Jev SEO changes about the model contract

A normal LLM request often begins with a writing instruction: explain a finding, propose an anchor, or return a JSON object containing a label. Even when the response is constrained to a schema, the model is still being used as a general-purpose generator.

Jev starts from a narrower contract. Your application sends the evidence in state and defines one or more typed questions. Each question uses a primitive that determines the legal response shape. A Choice question selects from a closed set. A Score question evaluates an ordered scale. A Noul question estimates the probability of one proposition.

This changes the role of the model, not the need for system design:

The application still decides what evidence Jev sees, what the available labels mean, and what happens after the response. It also decides when a case is too uncertain or consequential to automate.

Typed output solves an engineering problem: downstream code receives a known kind of value instead of trying to extract a decision from prose. It does not solve the evaluation problem. A response can match the required type and still choose the wrong intent, assign a weak relevance score, or reflect missing context. A useful Jev SEO implementation therefore needs both a strict response contract and a task-specific way to test decision quality.

Where Jev fits in an SEO system

Jev does not begin with a URL. It begins with evidence your system has already collected and reduced to the context needed for one decision. A practical flow looks like this:

crawler, API, or export
        ↓
normalize and filter evidence
        ↓
ask atomic Jev questions
        ↓
combine typed results in code
        ↓
automate, sample, or send to review

Suppose you want to prioritize technical SEO issues. A crawler can supply the issue type, affected URLs, indexability, and status codes. Analytics or business systems can add traffic and conversion importance. Deterministic code can calculate affected-page counts and remove resolved findings. Jev can then score a bounded judgment such as likely search impact, provided the relevant evidence and scoring criteria are in state and the question.

The final priority should still be calculated in code. That keeps explicit business rules, such as multiplying impact by affected URLs or applying a fixed compliance override, visible and testable.

Atomic questions matter because broad instructions hide several judgments inside one answer. “Is this page good for SEO?” combines intent match, factual support, crawlability, internal-link coverage, and editorial quality. Those signals use different evidence and may need different owners. Ask them separately, then combine only the results the application actually needs.

This separation also makes failures easier to diagnose. If a decision is poor, you can inspect the supplied evidence, the question criteria, the probability distribution, and the policy that acted on it. Without that boundary, a bad source document, an unclear prompt, and an unsafe automation rule can look like one model problem.

Choose Choice, Score, or Noul

The primitive should match the decision your code needs. Choosing it after writing a long prompt usually produces a question that is too broad.

Use Choice for a closed decision

A good Choice question names alternatives your application can handle. The labels should be mutually understandable, and the criteria should distinguish them. When real inputs may fall outside the list, add an explicit option such as insufficient_context instead of forcing the nearest label.

Use Score for ordered judgment

A Score question needs meaningful levels. “Rate quality from 1 to 5” leaves too much unstated. Define what the low, middle, and high points mean for the task. Jev can return values between defined levels, so downstream code should not assume that only the legend points are possible.

Use Noul for one proposition

Noul is useful when your code needs a probability that a statement is true. Ask “Does this draft substantively cover the refund-policy requirement?” rather than “Is the draft complete, accurate, and persuasive?” The second question contains three different judgments.

Noul's value is already the model's probability for the proposition. Unlike Choice and Score, the documented response does not include a separate confidence field. A value near the middle signals ambiguity, but the action threshold still depends on your workflow. Missing one optional supporting phrase and approving a legally sensitive claim should not share the same policy.

If a workflow needs several checks, send several atomic questions against the same prepared state and combine them in code. This preserves the meaning of each result and makes evaluation possible at the question level.

Six Jev SEO workflows worth separating

The strongest Jev use cases are not broad requests such as “improve this site.” They are recurring decisions with a known input, a constrained output, and a defined response when the evidence is weak. The six workflows below illustrate that pattern.

These are related, but they should not become one large question. A team might use Choice to route search intent, Noul to check a brief requirement, and Score to evaluate relevance. Combining all three into “Is this page optimized?” would produce a result that is hard to interpret and harder to test.

The input boundary is equally important. An internal-link decision should receive only destinations that have already passed deterministic eligibility checks. Otherwise the model could select a URL that is redirected, non-canonical, blocked, or already linked from the source. Jev can choose among the candidates it receives; it cannot prove that the candidate set was prepared correctly.

The same principle applies to issue prioritization. Jev can evaluate a semantic judgment from the supplied evidence, but the application should calculate known numbers and enforce explicit rules. If an issue affects 4,000 indexable product pages, code should count those pages. If a policy says checkout failures always require immediate review, code should enforce that override.

This separation gives each child workflow a testable contract. You can evaluate intent labels against a labeled query set, overlap decisions against editorial judgments, or relevance scores against an agreed rubric. The hub is the map; the linked guides show how to design each task without turning Jev into a general SEO agent.

Build a minimal Jev SEO request

The following example routes one prepared SEO finding. It uses the current top-level fields documented for the TypeSafe API: state, model, and a questions map. The Choice question defines the instruction and the allowed answers in criteria.

This is an illustrative integration example. It is not a response captured from Screpy production, and the values below do not measure Jev's accuracy.

{
  "state": {
    "finding": "The same title appears on 186 indexable product pages.",
    "page_type": "product",
    "affected_urls": 186,
    "observed_status": 200
  },
  "model": "jev-1.13.0",
  "questions": {
    "issue_route": {
      "type": "choice",
      "instructions": "Which SEO workstream should own this finding?",
      "criteria": {
        "technical": "Crawl, indexation, rendering, status, or canonical behavior",
        "content": "On-page text, titles, descriptions, or content differentiation",
        "authority": "Links, mentions, or off-page signals",
        "insufficient_context": "The supplied evidence is not enough to choose safely"
      }
    }
  }
}

An illustrative response could look like this:

{
  "model": "jev-1.13.0",
  "answers": {
    "issue_route": {
      "type": "choice",
      "choice": "content",
      "confidence": 0.82,
      "probabilities": {
        "technical": 0.12,
        "content": 0.84,
        "authority": 0.01,
        "insufficient_context": 0.03
      }
    }
  },
  "usage": {
    "input_tokens": 214,
    "output_tokens": 42
  }
}

The response is useful because code can consume the selected route and inspect the full distribution. The question ID issue_route is chosen by the application and appears under answers. The selected choice is the option with the highest probability, while confidence summarizes how concentrated or spread the distribution is.

Do not jump directly from the example's 0.82 confidence to an automation threshold. The numbers are invented to demonstrate the response shape. Production policy should come from evaluation on your own findings.

A conservative routing function might follow this structure:

if evidence is incomplete:
    send to review
else if evaluated policy allows this confidence and risk level:
    assign the selected workstream
else:
    send to review with the probability distribution

The same request could contain additional independent questions, but each should ask one bounded thing. If you also need search impact, business criticality, and owner, define them separately and combine their answers in code. Check the official request and response documentation again when implementing the call because model versions and API details can change.

Treat probability and confidence as routing evidence

A high confidence value does not prove that a decision is correct. It shows that the probability distribution is concentrated rather than spread across competing answers. A model can be decisive and wrong when the state is incomplete, the criteria are unclear, or the evaluation data differs from the real workload.

Start by building a labeled set for the exact question. Include clear cases, ambiguous cases, missing-context cases, and the page or query types that matter most to the business. Compare Jev's choices or scores with the accepted labels, then inspect performance across those slices. A single overall accuracy figure can hide a weak result on one high-impact category.

The TypeSafe confidence guidance recommends using confidence architecturally. In an SEO workflow, that can become three policy bands:

1. Automate: The task is reversible and low risk, the evidence is complete, and evaluated performance supports acting on this result.
2. Review a sample: The workflow is performing acceptably, but periodic human checks are needed to detect drift or weak segments.
3. Require review: The distribution is ambiguous, required evidence is missing, the case belongs to a weak evaluation slice, or a wrong decision would have material consequences.

Those are policy categories, not universal numeric thresholds. An internal-link suggestion can be reviewed before it is published, so a team may tolerate more uncertainty. A decision that could deindex many pages should have a much stricter path and explicit deterministic safeguards.

Use the full probability distribution when it adds operational value. If two intent labels are close, the runner-up can help a reviewer understand the ambiguity. If insufficient_context has meaningful probability, the safest action may be to gather more evidence rather than choose the leading label.

Re-evaluate after changing the question, criteria, model version, input preparation, or content population. Confidence routing is part of the system's tested behavior. It is not a one-time number copied from a documentation example.

Keep the wrong jobs out of a Jev decision call

The current documented Jev interface evaluates supplied state and returns typed answers. Do not assign it responsibilities that require fetching data, calculating an exact fact, producing prose, or executing a change.

Sometimes the correct decision is to use no model. A stable rule such as status_code >= 400, canonical_url != current_url, or title_length == 0 is faster to understand, easier to test, and exact for the data it checks. Adding Jev to such a rule creates another failure surface without resolving ambiguity.

The opposite boundary matters too. Do not force an open-ended editorial task into a sequence of tiny scores merely because typed outputs are convenient. A good product description, outreach email, or article introduction requires composition. Jev may classify the brief or evaluate one bounded property, but an editor or generative system still creates the text.

Human review remains necessary when the acceptable answer depends on brand strategy, legal or policy context, disputed evidence, or a consequence the evaluation did not cover. A typed result can make that review easier to route. It does not transfer accountability to the model.

Clear ownership is what makes the system dependable: machines collect facts, code enforces known rules, Jev handles bounded judgment, generators create language, and people approve decisions whose impact deserves it.

Choose a first workflow you can evaluate

The best first Jev SEO workflow is rarely the most ambitious one. Choose a decision that occurs often enough to evaluate, has a finite answer space, and can fail safely.

1. Define one decision. Write the value your application needs, such as one intent label or one relevance score. If the output needs several independent judgments, split them now.
2. Prepare the evidence. Decide which crawl fields, page summaries, query data, or business context belong in state. Remove data that does not help answer the question.
3. Create accepted examples. Have the appropriate people label a representative set, including ambiguous and insufficient-context cases. Record disagreements instead of hiding them.
4. Design the fallback. Add an explicit option when the taxonomy may not cover the input, and define when the application must stop for review.
5. Evaluate before expanding. Compare decisions with the accepted set, inspect important slices, review errors, and change one part of the workflow at a time.

Use a simple go/no-go test before implementation:

• Go when the task needs semantic judgment, accepts a typed output, has clear criteria, and has a safe review path.
• Use code instead when an exact rule or database calculation determines the answer.
• Use a generative workflow instead when the required output is original language.
• Pause when you cannot assemble representative examples or describe the consequence of a wrong decision.

Keep the first release reversible. Store the input version, question version, model version, answer, distribution, and resulting action so errors can be traced. Sample accepted cases as well as rejected ones; otherwise you only learn where the system hesitated, not where it acted confidently and incorrectly.

Once one decision performs reliably for its intended risk level, add another atomic question or a second workflow. Do not turn the successful first task into permission for an unbounded “optimize SEO” agent.

Use Jev when the SEO output is a decision

Jev SEO is most useful when your system needs a bounded judgment it can inspect and route, not another paragraph of generated text. The work still depends on well-prepared evidence, atomic questions, task-specific evaluation, deterministic safeguards, and human review where the consequences justify it.

Choose one workflow from the use-case map, define its accepted output, and test it on representative examples before automating an action. If the task cannot be expressed as a clear Choice, Score, or Noul question, Jev may be the wrong layer. That boundary is a design advantage: it keeps each model call narrow enough to understand, evaluate, and improve.