venice-decisions — Claude Code skill: what it does, install

---
name: venice-decisions
description: Call Venice's Beta POST /decisions (and its TypeSafe-compatible alias POST /systemone) to get typed judgments instead of generated text. Covers the Jev "System One" decision model (jev-latest, aliases jev-1-13-0 / typesafe-jev), the state + questions request shape, the three question/answer types (noul yes/no probability, choice with probability distribution + confidence, score on an ordered rubric), token limits (maxStateTokens / maxTotalTokens), input-token pricing, rate limits, and how upstream 422 validation errors surface as 400.
---

# 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

```json
{
  "refund_requested": {
    "type": "noul",
    "instructions": "Does the customer explicitly request a refund?",
    "criteria": {
      "true": "The customer asks for money to be returned",
      "false": "The customer does not ask for money to be returned"
    }
  }
}
```

```json
{ "refund_requested": { "type": "noul", "noul": 0.88 } }
```

- `noul`: number in `[0, 1]`; ≈1 strong yes, ≈0 strong no, ≈0.5 uncertain. There is **no** `confidence` field on noul answers.

### `choice` — pick one option

```json
{
  "request_type": {
    "type": "choice",
    "instructions": "What is the customer's primary request?",
    "criteria": {
      "refund": "Return money already paid",
      "troubleshooting": "Help resolve a product problem",
      "information": "Answer a question without taking action",
      "other": null
    }
  }
}
```

```json
{
  "request_type": {
    "type": "choice",
    "choice": "refund",
    "probabilities": { "refund": 0.9, "troubleshooting": 0.06, "information": 0.03, "other": 0.01 },
    "confidence": 0.85
  }
}
```

- `choice`: the highest-probability option name.
- `probabilities`: every option → probability in `[0, 1]` (sum to 1).
- `confidence`: `[0, 1]`, derived from the distribution.
- Include an `other` / `none` option when your options may not cover every state.

### `score` — position on an ordered rubric

```json
{
  "severity": {
    "type": "score",
    "instructions": "How severe is the reported issue?",
    "criteria": [
      "Cosmetic or no material impact",
      "Workflow is impaired but a workaround exists",
      "Critical workflow is blocked with no workaround"
    ]
  }
}
```

```json
{
  "severity": {
    "type": "score",
    "score": 1.4,
    "legend": {
      "0": "Cosmetic or no material impact",
      "1": "Workflow is impaired but a workaround exists",
      "2": "Critical workflow is blocked with no workaround"
    },
    "probabilities": { "0": 0.05, "1": 0.5, "2": 0.45 },
    "confidence": 0.55
  }
}
```

- Levels are indexed from `0` in the order you gave them; `legend` and `probabilities` are keyed by the index **as a string**.
- `score`: probability-weighted (≥ 0), so it can land between levels.
- `confidence`: `[0, 1]`, derived from the distribution.

## Response

| Field | Type | Notes |
|---|---|---|
| `model` | string | Always the canonical id `jev-latest`, even if you sent an alias. |
| `answers` | object | One answer per question id (shapes above). |
| `usage.input_tokens` | integer ≥ 0 | Tokens for state + questions. Billed. |
| `usage.output_tokens` | integer ≥ 0 | Tokens produced evaluating the questions. Currently priced at $0. |

Headers: `x-ratelimit-{limit,remaining,reset}-{requests,tokens}`; `Content-Encoding` when compressed. The spec also lists `X-Balance-Remaining` for x402 callers, but the server does not currently set it — poll `GET /x402/balance/{walletAddress}` instead.

## JavaScript / Python

No OpenAI SDK method exists for this route — use plain HTTP.

```ts
const res = await fetch('https://api.venice.ai/api/v1/decisions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'jev-latest',
    state: { ticket: { subject: 'Duplicate charge', message: 'I was charged twice. Please refund the duplicate.' }, account: { plan: 'pro' } },
    questions: {
      covered: { type: 'noul', instructions: 'Does ticket.message request a refund for a duplicate charge?' },
      priority: { type: 'score', instructions: 'How urgent is this ticket?', criteria: ['Low', 'Medium', 'High'] },
    },
  }),
})
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`)
const { answers } = await res.json()

if (answers.covered.type === 'noul' && answers.covered.noul >= 0.9) {
  // auto-approve
}
```

```python
import os, requests

r = requests.post(
    "https://api.venice.ai/api/v1/decisions",
    headers={"Authorization": f"Bearer {os.environ['VENICE_API_KEY']}"},
    json={
        "model": "jev-latest",
        "state": "Help! My payouts have been failing for 3 days.",
        "questions": {
            "team": {
                "type": "choice",
                "instructions": "Which team should handle this?",
                "criteria": {"billing": "Payments, invoicing, refunds", "technical": "Bugs, outages, integrations"},
            }
        },
    },
    timeout=60,
)
r.raise_for_status()
team = r.json()["answers"]["team"]
route = team["choice"] if team["confidence"] >= 0.8 else "human_review"
```

## Authentication

Both routes accept either (see [`venice-auth`](../venice-auth/SKILL.md)):

- `Authorization: Bearer $VENICE_API_KEY`, or
- `SIGN-IN-WITH-X` wallet auth for x402 (legacy `X-Sign-In-With-X` also accepted). Payment headers (`X-PAYMENT` etc.) are only accepted on `/x402/top-up`; sending one here → `400 PAYMENT_HEADER_NOT_ACCEPTED`. See [`venice-x402`](../venice-x402/SKILL.md).

With no credentials at all you get a `402` x402 discovery response. The spec's `x-payment-info` is `mode: dynamic`, USD, `min 0.001` / `max 10.00`.

API keys whose `modelPrivacy` is `PRIVATE_ONLY` or `PRIVATE_TEXT` are refused (`403`): Jev is an **anonymized** (third-party) model, and `PRIVATE_TEXT` gates decisions as well as text and embeddings.

## Pricing & limits

- **Price** (live `GET /models?type=decision`): **$0.042 per 1M input tokens** (0.042 DIEM); output tokens **$0**. A 429-input-token request costs ≈ $0.000018. Always read `model_spec.pricing` for the current number.
- Charged from `usage` **after** a successful response. If the upstream answer is malformed or missing `usage`, you get `500` and are not charged.
- Balance is checked before the call; insufficient balance → `402`.
- **Rate limits** (per account, shared by all its keys; Jev-specific override): Paid tier **100 RPM / 1,000,000 TPM**; Partner Tier 1 **300 RPM / 10,000,000 TPM**. One request is counted before the model runs; tokens (`input + output`) are metered afterwards. Check yours with `GET /api_keys/rate_limits` ([`venice-api-keys`](../venice-api-keys/SKILL.md)).

## Errors

| Status | Cause | Fix |
|---|---|---|
| `400` | `model` missing / empty or not a string → plain `{ "error": "model is required" }` / `"model must be a string"` (checked before the schema, no `issues`). | Send `"model": "jev-latest"`. |
| `400` | Venice schema validation failed (missing `state`/`questions`, empty `questions`, bad `type`, extra field, `score` with < 2 levels, missing `choice` criteria). Body: `{ error: "Invalid request parameters", details, issues }`. | Fix the field named in `issues[].path`. |
| `400` | **Upstream TypeSafe 400/422** — a request that passed Venice's schema but TypeSafe rejected. Venice flattens FastAPI `detail` into `{ "error": "<loc>: <msg>; …" }` (up to 5 items, `body.` prefix stripped, echoed input never returned). If nothing is extractable: `"Invalid request parameters. For assistance, please reach out to [email protected]"`. | Read `error` — it names the field path and TypeSafe's message. |
| `400` | `PAYMENT_HEADER_NOT_ACCEPTED` | Use `SIGN-IN-WITH-X`, not a payment header. |
| `401` | Auth failed. | Check the key / SIWX header. |
| `402` | No credentials (x402 discovery); insufficient balance (`"Insufficient USD or Diem balance…"` for keys, structured `PAYMENT_REQUIRED` for x402); per-key USD/DIEM spend limit reached. | API key: add credits at https://venice.ai/settings/api, or raise the key's limit (ADMIN key, `PATCH /api_keys`). Wallet: `POST /x402/top-up` ([`venice-x402`](../venice-x402/SKILL.md)). |
| `403` | Key privacy setting forbids anonymized models; region or provider restriction; API access disabled for the account. | Use a key with `modelPrivacy: ALL`. |
| `404` | Unknown `model`. | Send `jev-latest`. |
| `400` | Non-JSON `Content-Type` → `"'Content-Type' must be 'application/json'"` (the spec lists `415`, but the server returns `400`). | `Content-Type: application/json`. |
| `429` | Venice rate limit for your account on this model; **or** TypeSafe capacity (upstream 429/529 → "The model is currently overloaded", with `Retry-After`, upstream value or 30 s); **or** the error-budget lockout (50 non-429 4xx responses within a 30 s window, per key + `model`; this route rejects a `user` field, so all of a key's decisions requests share one bucket). | Honour `Retry-After`; back off with jitter. |
| `500` | Any other upstream failure (non-400/422/429/529 status), the 30 s upstream timeout, or a malformed upstream answer. Not charged. | Retry with backoff. |
| `503` | Model marked offline. | Retry later. |

General retry strategy and body shapes: [`venice-errors`](../venice-errors/SKILL.md).

## Gotchas

- **Beta, one model.** `GET /models?type=decision` currently returns only `jev-latest`; don't hard-code capabilities beyond what `model_spec` reports.
- **Not chat.** There is no `messages`, `temperature`, `max_tokens`, streaming, or tools. Adding any unknown field is a `400` (strict schema).
- **Questions are isolated.** One answer never becomes context for another. If question B depends on A's result, make a second request.
- **Question ids carry no meaning to the model.** `{"urgent": {...}}` with vague `instructions` won't help — write complete instructions and name the fields in structured state (e.g. "Does `ticket.message` request a refund covered by `refund_policy`?").
- **Token budgets are enforced upstream**, so Venice validation passes and the failure arrives from TypeSafe. Pre-trim long states yourself.
- **Every 4xx except 429 counts toward the failed-requests error budget** on this route (the separate unsupported-feature budget applies only to `/chat/completions` and `/responses`), so a client looping on bad requests locks itself out for the rest of the 30 s window.
- **Probabilities vary between requests.** Calibrate thresholds on your own data; `confidence` is not a correctness guarantee. Noul has no `confidence` — use distance from 0.5.
- **`score` keys are strings** (`"0"`, `"1"`, …) in both `legend` and `probabilities`.
- **Branch on `answer.type`** — unknown future answer types are passed through untouched.
- **Anonymized, not private.** State is sent to TypeSafe; don't route data that requires Venice-private inference.
- Model discovery and pricing fields: [`venice-models`](../venice-models/SKILL.md).