Quickstart: from a local demo to a live decision

The goal of this chapter is deliberately small. Know whether you ran a fixture or a live request, locate the answer to one question, and identify the sentence in the input that supports your interpretation. Leave batch processing and automated business actions until you can explain this first result.

1. Run the example without an account

Download and extract the companion code. Open a terminal in the project root, the directory containing examples. Replace path/to/hello-jev below with your actual extraction path.

On macOS or Linux:

cd path/to/hello-jev
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m examples.hello_jev tickets --mode offline

Use Python 3.10 or newer for this book. Once the environment is active, python refers to that environment. The examples use the standard library, so there is no package installation step here.

On Windows, PowerShell can use the virtual environment's interpreter directly:

cd path\to\hello-jev
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m examples.hello_jev tickets --mode offline

This avoids changing your script execution policy just to activate an environment. Substitute this interpreter path for python in later commands if you use Windows.

Open the output file reported by the command. Confirm that it is marked offline_fixture, then find a ticket's input and proposed queue. Offline mode replays authored responses and checks their binding to the current input and questions. Edits that change the fingerprint produce an error; the fixture cannot reinterpret new material. Use offline mode to check the workflow and live calls to investigate changed wording.

2. Ask one question in the Playground

The official quickstart links to the TypeSafe Playground. Sign in and confirm that your account can use it. If the console requires access or billing setup, follow its current instructions. This book does not assume that every account has the same allowance or access conditions. Official quickstart

Paste this synthetic message into the state field:

I need a copy of the invoice for my September subscription.
Please send it before our bookkeeping closes on Friday.

Start with one concern and one observable fact. Add a Noul question asking whether the message explicitly names a deadline. If the interface accepts a question JSON object, use:

{
  "has_deadline": {
    "type": "noul",
    "instructions": "Does the message explicitly name a deadline?"
  }
}

Run it and save the input, question, and actual result. This book does not prescribe an invented output such as “you should see 0.99.” We did not execute this request while preparing the chapter. Your current input, account, and model version determine the response. The human reference label is that a deadline is present, with “Friday” as the supporting evidence.

Now change only the second sentence to “There is no rush.” Run again with the same question. Finally, try “Please help when possible.” Compare the three answers with your own labels. Changing one thing at a time lets you investigate the cause of a difference. If you also edit the question and threshold between runs, the comparison becomes harder to interpret.

3. Understand the number you are reading

A Noul value represents the probability of a yes answer. A value around 0.5 gives similar probability to yes and no; it does not mean “medium urgency.” There is no separate Noul confidence field. Noul documentation

The last two ideas receive fuller treatment in Confidence and evaluation. At this stage, retain the values before turning them into an automatic policy. You will want the original evidence when a threshold changes.

4. Make a terminal request

Obtain a usable API key in your TypeSafe console and set it in the current terminal's environment. This input method keeps the key out of the command text. Run the first line, paste the key, and press Enter. Hidden input is expected.

read -r -s TYPESAFE_API_KEY
export TYPESAFE_API_KEY

For Windows PowerShell:

$secureKey = Read-Host "TypeSafe API key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$env:TYPESAFE_API_KEY = $credential.Password

The variable is available to the current session and the programs it launches. Keep it out of sample data, question text, screenshots, and shared output files. Your coding assistant can write code that reads the variable without receiving the key itself.

Create a file named request.json in your editor:

{
  "model": "jev-latest",
  "state": "Please send my invoice before Friday.",
  "questions": {
    "has_deadline": {
      "type": "noul",
      "instructions": "Does the message explicitly name a deadline?"
    }
  }
}

On macOS or Linux, run:

curl --silent --show-error --fail-with-body \
  https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output quickstart-response.json
python -m json.tool quickstart-response.json

This sends a real POST /v1/systemone request and may incur real usage. The request has state, model, and questions; results belong under answers. It is not a chat request using a messages array. API reference

Windows readers can use the next chapter's Python program for an equivalent HTTP request. You can also run the complete companion case:

.\.venv\Scripts\python.exe -m examples.hello_jev tickets --mode live

That case processes its sample collection, so its scope is larger than this one-request exercise. Read the case's input description before switching it to live mode. On macOS or Linux, the equivalent command is python -m examples.hello_jev tickets --mode live.

5. Establish what succeeded

Inspect quickstart-response.json for answers.has_deadline.type and answers.has_deadline.noul. Keep the top-level model and usage fields as well. Do not substitute local estimates for reported usage. Because jev-latest is an alias, recording the response's model identifier helps you compare results later. Models reference

If the real request fails, retain the HTTP status and a redacted error description, then follow Troubleshooting. Repeated clicking will not repair a missing key, and rewording a question will not repair authentication.

Keep a run you can reproduce

Finish with a three-row notebook: explicit deadline, explicitly no rush, and ambiguous wording. Add human labels and actual returns. Without account access, leave the live-result column empty. Keep each complete message, question, run date, input language, and returned model identifier beside its row.

Write “Friday supplies a deadline” as the human rationale rather than “the number should be 1.” A colleague can inspect the first statement; the second confuses a probability with a labeling rule. If reviewers disagree about “when possible,” record that boundary in the standard before adding new examples.

The offline ticket output defaults to examples/hello_jev/output/tickets.json. Append --output first-offline.json to the CLI command to keep a separate copy; the extension must be .json. Save live results separately. Similar file structures do not give the two modes the same evidential meaning. These records are your starting point when a later result changes.

Next: Connect Jev to a Python project.