venice-decisions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Venice Decisions (Beta)

`POST /api/v1/decisions` evaluates a `state` (text or JSON) against a map of typed `questions` and returns one structured `answer` per question — probabilities, picks, and scores your code can branch on directly. It does **not** generate text. The only model is TypeSafe's **Jev** (`jev-latest`), a "System One" decision model.

> **Beta.** The spec labels both routes Beta: "Request/response schemas and behavior may change without notice."

## Use when

- Routing / classifying (support tickets, intents, moderation buckets) into a closed set of options.
- Yes/no gates where the probability itself is useful (`is_urgent`, `requests_refund`).
- Rating something on an ordered rubric (severity, frustration, quality).
- You want several independent judgments about the **same** state in one call.

Use [`venice-chat`](../venice-chat/SKILL.md) instead when you need prose, explanations, multi-turn conversation, tool calling, or open-ended answers.

## Endpoints

| Method | Path | Notes |
|---|---|---|
| `POST` | `/api/v1/decisions` | Main route (`operationId: createDecision`). API key or x402. |
| `POST` | `/api/v1/systemone` | Same behavior as `/decisions` (`createDecisionSystemOne`). Mirrors TypeSafe's upstream path so TypeSafe SDKs work with a base-URL swap: `TYPESAFE_BASE_URL=https://api.venice.ai/api`. |
| `GET` | `/api/v1/models?type=decision` | Lists decision models with pricing and token limits. |

Both POST routes accept `Accept-Encoding: gzip, br`.

## Quick start

```bash
curl https://api.venice.ai/api/v1/decisions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "My payouts have failed for three days and nobody has replied. Please help ASAP.",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this message require urgent attention?"
      },
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": {
          "billing": "Payments, invoices, or refunds",
          "technical": "Bugs, outages, or integrations",
          "sales": "Pricing, upgrades, or new accounts"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated is the customer?",
        "criteria": ["Calm", "Frustrated", "Very angry"]
      }
    }
  }'
```

Illustrative response (values vary per request):

```json
{
  "model": "jev-latest",
  "answers": {
    "is_urgent": { "type": "noul", "noul": 0.95 },
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.95, "technical": 0.05, "sales": 0 },
      "confidence": 0.93
    },
    "frustration": {
      "type": "score",
      "score": 1.27,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0, "1": 0.73, "2": 0.27 },
      "confidence": 0.6
    }
  },
  "usage": { "input_tokens": 429, "output_tokens": 73 }
}
```

## Request schema

Top level is **strict** — unknown fields are rejected with `400`.

| Field | Type | Required | Notes |
|---|---|---|---|
| `model` | string | Yes | `jev-latest`, or an alias `jev-1-13-0` / `typesafe-jev`. Missing/empty → `400 "model is required"`; non-string → `400`; unknown → `404` with a suggestion. |
| `state` | string \| object \| array | Yes | What to evaluate. String must be non-empty; array must have ≥ 1 item; object is free-form JSON (not checked by Venice for emptiness). Use structured JSON for chat logs, records, or app state. |
| `questions` | object (map) | Yes | Map of `question_id → question`. At least one entry (`"At least one question is required"`). Answers come back under the same ids. Each question is evaluated in parallel and in isolation against the same state; question ids are not sent to the model, so put all meaning in `instructions`. |

### Question objects

Each question is **strict** (no extra keys) and discriminated by `type`. `instructions` on every type accepts a non-empty string, a JSON object, or a non-empty array.

| `type` | `instructions` | `criteria` | Venice-side limits |
|---|---|---|---|
| `noul` | Required. The yes/no question. | Optional object `{ "true"?: string, "false"?: string }` — what a yes (≈1) / no (≈0) means. | Any other key inside `criteria` is silently stripped (not rejected). |
| `choice` | Required. What to decide. | **Required** map `option_name → description \| null` (`null` = no extra detail). | No minimum option count enforced by Venice; upstream may reject degenerate sets. |
| `score` | Required. What to rate. | **Required** array of level descriptions, ordered lowest → highest. | `minItems: 2`. |

Any other `type` value is rejected with `400`.

### Token limits

From `GET /models?type=decision` (`model_spec`):

- `maxStateTokens: 32000` — `state` plus the single longest question.
- `maxTotalTokens: 64000` — `state` plus all questions combined.

Venice does **not** count tokens before forwarding; these budgets are enforced by TypeSafe. An oversized request therefore passes Venice validation and fails upstream — as a `400` carrying TypeSafe's message if TypeSafe answers 400/422, otherwise as a `500` (see Errors). The generic JSON body cap is 35 MB.

## Answer types

Every answer has `type`. The response schema passes unknown extra fields through, and an answer whose `type` is not `noul`/`choice`/`score` is forwarded as-is (forward-compat) — branch on `type` and ignore what you don't recognise.

### `noul` — yes/no probability

From veniceai/skills, MIT.

More from veniceai/skills