Skip to content
RightNow
Skip to article
Docs navigation: Decision model / Quickstart

Quickstart

RightNow AIDecision modelQuickstart Updated

View as Markdown
On this page

Install an SDK and send a text state with a named question to get a structured answer.

Get a key

Create a named key under API keys in an active workspace. The full key appears only when it is created.

Set SYSTEM_ZERO_API_KEY in the process that makes the call. Keep the key on your server and call over HTTPS.

Get an API key

  1. Get a key

    Set SYSTEM_ZERO_API_KEY on your server.

  2. Install an SDK

    Run npm install @rightnowai/system-zero@0.4.7 or python -m pip install rightnow-system-zero==0.4.7.

  3. First call

    Copy decide.ts, decide.py or decide.sh and run it.

  4. Read the answer

    Read answers.damaged.decision. It is true or false.

Your first call, step by step.

Install an SDK

Node 22 or newer, ES modules, server side only. Python 3.10 or newer, server side only.

TypeScript package README and Python package README.

install.sh
npm install @rightnowai/system-zero@0.4.7

SDK 0.4.7 adds typed decision provenance, webhook methods and request compression.

Tool selection: the RightNow decision model picks which of your tools to call next, or none, with a probability for each. It does not write arguments or messages, and it does not run tools.

Text, PDF and video allow 9 tools and none, or 10 when a tool is required; image or audio allows 25 tools and none, or 26 when a tool is required.

Use toolQuestions / tool_questions and selectTool / select_tool. See Tool selection.

First call

Send a state and a named question, then read the answer and list the available models.

decide.ts
import { SystemZeroClient } from '@rightnowai/system-zero';

const client = new SystemZeroClient({
  apiKey: process.env.SYSTEM_ZERO_API_KEY,
  baseURL: "https://api.rightnowai.co/v1",
});
const reply = await client.decide({
  "model": "rightnow-decision",
  "state": "The blender I ordered arrived with a cracked jar.",
  "questions": {
    "damaged": {
      "type": "boolean",
      "instructions": "Did the item arrive damaged?"
    }
  }
});
console.log(JSON.stringify(reply, null, 2));
const models = await client.models.list();
console.log(models);

// Set SYSTEM_ZERO_API_KEY to your API key before running this example.
// Run this example on your server.
// SDK defaults: The default is 5 retries, also the maximum, with 150 seconds
// per attempt and a 60-second total retry budget. A single wait longer than 60
// seconds raises the last error.
// Use Retry-After-Ms, or Retry-After when milliseconds are absent. The wait is
// never shorter than a random backoff floor: a random fraction of 0.5 seconds
// doubled for each attempt, capped at 8 seconds.

Request bodies of 32 KB or more are sent gzip-compressed when that makes them at least 10 percent smaller; pass compressRequests: false / compress_requests=False to turn this off.

Read the answer

Read answers.damaged in your response. answers.damaged.probability is the likelihood of true. decision selects true when true is at least as likely as false; confidence is its probability. alternatives contains the other outcome and its confidence. calibrated is false in this release.

reply shape
Text
id: string
model: string
served_by: string
created: integer
context:
  route: string
  tokens: integer
answers:
  damaged:
    type: "boolean"
    probability: number
    confidence: number
    calibration_version: string
    decision: boolean
    alternatives:
      decision: boolean
      confidence: number
    calibrated: boolean
usage:
  input_tokens: integer
  cached_input_tokens: integer
  media_tokens: integer
  long_input_tokens: integer
  media_items: integer
  thought_tokens: integer
The shape of a reply. Each type stands in for a value.

SDK retries

RuleBehavior
BoundsThe default is 5 retries, also the maximum, with 150 seconds per attempt and a 60-second total retry budget. A single wait longer than 60 seconds raises the last error.
Safe requestsOnly GET requests or requests carrying a non-empty idempotency key can retry. With retries enabled, decide POSTs receive a generated key when none is supplied. An explicit blank key omits the header and disables decision retries. Each retry retains the same key and serialized body. Setting the retry count or budget to zero disables retries.
Retry flagsMarked means error.retryable is true or the x-should-retry header is true. An explicit false in either marker vetoes retry.
429capacity_exhausted, rate_limit_exceeded, concurrency_limit_exceeded or workspace_limit_exceeded.
5xxexcept 504 and maintenance, including service_unavailable and system_zero_unavailable.
409idempotency_conflict.
TransportA qualifying connection failure or timeout before any response byte can also retry, even if the request was sent. Failures after a response byte never retry. Errors of authentication and permission types never retry.
WaitUse Retry-After-Ms, or Retry-After when milliseconds are absent. The wait is never shorter than a random backoff floor: a random fraction of 0.5 seconds doubled for each attempt, capped at 8 seconds.
Cold startA cold pool returns marked 503 system_zero_unavailable with a wait in Retry-After. The SDK retries the same request body with the same idempotency key. An explicit false retry marker stops retries.

Handle a refusal

The SDK follows the retry rules above. For Manual HTTP, use the policy printed in that example.

Keep the same Idempotency-Key and JSON body for the decision's retries. A new decision needs a fresh key. See Idempotency and Errors.