Introduction
In this tutorial, you'll learn how to work with TypeSafe AI's Jev, a System One model that returns typed, calibrated decisions instead of text. Unlike traditional language models that generate text, Jev outputs structured data with probabilities, making it ideal for applications requiring precise, decision-making outputs. You'll build a simple application that queries Jev to make binary decisions and interpret the confidence scores.
Prerequisites
- Basic understanding of Python programming
- Python 3.7 or higher installed
- API key from TypeSafe AI (you'll need to register for access)
- Installed
requestslibrary (install withpip install requests)
Step-by-Step Instructions
1. Set Up Your Development Environment
First, create a new Python project directory and install the required dependencies:
mkdir jev-tutorial
cd jev-tutorial
pip install requests
This creates a clean project space and ensures you have the necessary HTTP library to communicate with Jev's API.
2. Prepare Your API Key
Before making API calls, store your TypeSafe AI API key in an environment variable for security:
export JEV_API_KEY='your_api_key_here'
This approach prevents accidentally exposing your key in code or version control systems.
3. Create the Main Application Script
Create a file named jev_client.py with the following structure:
import os
import requests
import json
# Load API key from environment variable
API_KEY = os.getenv('JEV_API_KEY')
BASE_URL = 'https://api.typesafe.ai/jev/v1'
This sets up the basic configuration for connecting to Jev's API.
4. Define the Decision-Making Function
Implement a function that sends a question to Jev and processes the response:
def make_decision(question, decision_type='boolean'):
url = f'{BASE_URL}/query'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
}
payload = {
'question': question,
'type': decision_type,
'output_format': 'json'
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 200:
return response.json()
else:
raise Exception(f'API Error: {response.status_code} - {response.text}')
This function formats the request according to Jev's API specifications and handles the response appropriately.
5. Test with a Simple Binary Decision
Add the following code to test the decision-making function:
if __name__ == '__main__':
try:
# Example: Should we launch a new product?
result = make_decision(
'Should we launch a new product given current market conditions?'
)
print('Decision Result:')
print(json.dumps(result, indent=2))
except Exception as e:
print(f'Error: {e}')
This demonstrates how to use Jev for a binary decision with clear output formatting.
6. Handle Different Decision Types
Jev supports multiple decision types. Here's how to work with different output formats:
def make_categorical_decision(question, categories):
url = f'{BASE_URL}/query'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
}
payload = {
'question': question,
'type': 'categorical',
'categories': categories,
'output_format': 'json'
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 200:
return response.json()
else:
raise Exception(f'API Error: {response.status_code} - {response.text}')
This function allows you to specify multiple categories for Jev to choose from, which is useful for multi-class decisions.
7. Interpret the Confidence Scores
When Jev returns a decision, it includes confidence scores. Here's how to parse and use them:
def interpret_decision(result):
decision = result.get('decision')
confidence = result.get('confidence')
print(f'Decision: {decision}')
print(f'Confidence: {confidence:.2%}')
# Make business logic decisions based on confidence
if confidence > 0.8:
print('High confidence - proceed with decision')
elif confidence > 0.6:
print('Moderate confidence - review before proceeding')
else:
print('Low confidence - seek additional input')
Confidence scores are crucial for determining how much weight to give Jev's decisions in your application.
8. Complete Example Application
Combine everything into a complete script:
import os
import requests
import json
API_KEY = os.getenv('JEV_API_KEY')
BASE_URL = 'https://api.typesafe.ai/jev/v1'
def make_decision(question, decision_type='boolean'):
url = f'{BASE_URL}/query'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
}
payload = {
'question': question,
'type': decision_type,
'output_format': 'json'
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 200:
return response.json()
else:
raise Exception(f'API Error: {response.status_code} - {response.text}')
def interpret_decision(result):
decision = result.get('decision')
confidence = result.get('confidence')
print(f'Decision: {decision}')
print(f'Confidence: {confidence:.2%}')
if confidence > 0.8:
print('High confidence - proceed with decision')
elif confidence > 0.6:
print('Moderate confidence - review before proceeding')
else:
print('Low confidence - seek additional input')
if __name__ == '__main__':
try:
# Test binary decision
result = make_decision(
'Should we launch a new product given current market conditions?'
)
print('=== Binary Decision ===')
interpret_decision(result)
# Test categorical decision
categories = ['marketing', 'engineering', 'sales', 'support']
result2 = make_categorical_decision(
'Which department should lead the new product initiative?',
categories
)
print('\n=== Categorical Decision ===')
interpret_decision(result2)
except Exception as e:
print(f'Error: {e}')
This comprehensive example shows how to work with both binary and categorical decision types from Jev.
Summary
In this tutorial, you've learned how to integrate TypeSafe AI's Jev into your applications. You've seen how to:
- Set up a Python environment for Jev API interaction
- Send questions to Jev and receive structured decisions with confidence scores
- Handle different decision types (boolean and categorical)
- Interpret and act on Jev's confidence scores
Jev's approach of returning typed, calibrated decisions rather than text makes it particularly valuable for automated decision-making systems where precision and confidence metrics are essential for production use.