---
name: jev-decision
description: Use the Jev System One API as a general-purpose decision engine for classification, routing, yes/no judgments, scoring, prioritization, and structured decisions. Use when an agent needs to choose among explicit alternatives, score something against an ordered rubric, or make a bounded judgment from supplied context.
---

# Jev Decision

Use Jev System One when the task is a **bounded decision** rather than open-ended generation.

## Configuration

Read the API key from the environment variable `JEV_API_KEY`.

- Endpoint: `https://jev-api.com/v1/systemone`
- Default model: `jev-latest`
- Authentication: `Authorization: Bearer $JEV_API_KEY`
- Never print, log, or expose the API key.
- Never hard-code a real API key in this skill or application source.

If `JEV_API_KEY` is missing, stop and tell the caller that the environment variable must be configured.

## When to use

Use this skill for tasks such as:

- classification / tagging into a bounded set of labels
- routing a request to one team, workflow, tool, or agent
- yes/no or degree-of-belief judgments
- urgency, risk, quality, relevance, sentiment, or priority scoring
- choosing among explicitly supplied actions or candidates
- evaluating several independent decision dimensions in one call

Do not use it merely to generate prose, summarize, translate, retrieve facts, calculate deterministic values, or answer a question that has no bounded decision space.

Do not delegate decisions that must remain with a human or require specialized safety/legal/medical authority merely because this API can return a score. In such cases, use Jev only as one input if appropriate and preserve human review.

## Map the decision to a question type

### `choice`

Use when exactly one option should be selected from an explicit set.

```json
{
  "type": "choice",
  "instructions": "Which option best fits the state?",
  "criteria": {
    "option_a": "Clear definition of option A",
    "option_b": "Clear definition of option B"
  }
}
```

Make criteria mutually distinguishable. Put the meaning of each option in `criteria`, not only in the instructions.

### `score`

Use for an ordered scale. Criteria are ordered from the lowest level upward.

```json
{
  "type": "score",
  "instructions": "How urgent is this?",
  "criteria": [
    "Not urgent",
    "Needs attention soon",
    "Immediate attention required"
  ]
}
```

### `noul`

Use for a yes/no-like judgment where a degree from 0 to 1 is useful.

```json
{
  "type": "noul",
  "instructions": "Does this require urgent attention?"
}
```

## Build the request

1. Put all facts required for the decision in `state`.
2. Do not add unsupported facts to `state`.
3. Create one question per independent decision dimension.
4. Give each question a stable, machine-readable key such as `category`, `priority`, or `should_escalate`.
5. Prefer one API call containing multiple questions when they operate on the same state.
6. Default to `jev-latest` unless the caller explicitly requests another supported model.

Request shape:

```json
{
  "model": "jev-latest",
  "state": "The complete decision context goes here.",
  "questions": {
    "decision_key": {
      "type": "choice",
      "instructions": "Choose the best option.",
      "criteria": {
        "a": "Definition A",
        "b": "Definition B"
      }
    }
  }
}
```

## Call the API

Shell example:

```bash
curl --fail-with-body --silent --show-error \
  https://jev-api.com/v1/systemone \
  --request POST \
  --header "Authorization: Bearer $JEV_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "$PAYLOAD"
```

When implementing this in code, use the runtime's normal HTTP client instead of spawning curl if possible. Set a reasonable timeout and handle non-2xx responses.

## Interpret results

The response contains `answers`, keyed by the question IDs sent in the request.

- For `choice`, read `choice`, `confidence`, and `probabilities`.
- For `score`, read `score`, `confidence`, `legend`, and `probabilities`.
- For `noul`, read `noul` as a value from 0 to 1.

Do not invent a confidence value that is not returned by the API.

For `choice`, normally return the selected option. If the surrounding workflow benefits from uncertainty handling, also inspect `confidence` and the probability distribution. The caller may define a threshold for human review; do not silently invent a universal threshold.

For `score`, preserve the returned numeric score and use `legend` to interpret it.

For `noul`, preserve the numeric value unless the caller explicitly defines a threshold that converts it to a boolean. Do not assume `0.5` is always the correct operational threshold.

## Failure handling

- `401` / `403`: report an authentication/authorization problem without exposing the key.
- `429`: respect retry information when available; retry with bounded exponential backoff if the workflow permits.
- `5xx` / network failure: retry a small bounded number of times for automated workflows, then fall back to agent reasoning or request human review according to the parent workflow.
- Invalid response / missing expected answer: do not fabricate a decision. Surface the failure or use an explicitly permitted fallback.

## Decision quality rules

- Supply enough context in `state` to make the decision meaningful.
- Keep criteria concrete, non-overlapping where possible, and tailored to the actual task.
- Do not manipulate criteria to force a predetermined result.
- If the available choices are incomplete, fix the decision space before calling the API.
- If multiple labels are independently allowed, model them as separate questions rather than forcing a single `choice` question.
- Keep deterministic business rules in code. Use Jev for ambiguous judgment, not for rules that can be evaluated exactly.

## Example: news classification

```json
{
  "model": "jev-latest",
  "state": "广东顺德一纺织公司厂房火灾事故，造成8人死亡。",
  "questions": {
    "category": {
      "type": "choice",
      "instructions": "Choose the single best news category.",
      "criteria": {
        "国内": "中国境内的综合国内新闻",
        "国际": "海外事件或国际关系",
        "财经": "经济、金融、商业和市场",
        "科技": "科技、互联网和技术",
        "社会": "公共安全、事故、灾害、治安和社会事件",
        "文化娱乐": "文化、影视、音乐、明星和娱乐",
        "体育": "体育赛事、运动员和体育产业",
        "健康": "医疗、疾病、健康和公共卫生",
        "教育": "学校、考试、学生和教育行业",
        "网络热梗": "网络流行语、迷因和网络热点",
        "生活": "消费、旅游、美食、家居和生活方式",
        "其他": "不属于以上类别"
      }
    }
  }
}
```

## Example: multi-dimensional agent decision

An agent deciding how to handle a support request can ask all dimensions at once:

```json
{
  "model": "jev-latest",
  "state": "A production payment integration has failed for three days. Customers cannot complete purchases.",
  "questions": {
    "owner": {
      "type": "choice",
      "instructions": "Which team should own this?",
      "criteria": {
        "billing": "Invoices, subscription charges, or account billing",
        "technical": "Software, outage, API, or integration failure",
        "sales": "Pricing, purchasing, or sales inquiry"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is the issue?",
      "criteria": [
        "Routine",
        "Important but can wait",
        "Urgent",
        "Critical production impact"
      ]
    },
    "should_escalate": {
      "type": "noul",
      "instructions": "Should this issue be escalated immediately?"
    }
  }
}
```

Use the structured answer as decision input for the parent agent. The parent agent remains responsible for executing actions, enforcing permissions, and applying any hard business or safety rules.