SDK guide · bring your own Jev key
Validate meaning
without our server.
Use your own TypeSafe/Jev account from a trusted backend. The SDK sends text straight to Jev and returns valid, confidence, and status. No account or key from us is needed. The API hosted on this domain remains paused.
01 / Start
Get your own Jev key
The source is free and open source under Apache-2.0. Create a key in your own TypeSafe account and make it available as TYPESAFE_API_KEY to your backend process. Do not commit it, paste it into frontend code, or share it with us. TypeScript and Python SDKs are now published on npm and PyPI. Java is installed from source (Maven Central pending); the Go SDK is part of the public Go module.
The three built-in field rules are person_name, product_description, and address; use check(value, question) for other semantic questions. Confidence below 0.80 produces status="uncertain" and valid=null. Each batch item calls Jev separately and is charged to your account.
Setup / Step by step
Your key in a .env file
- Choose and install your SDK. Use your editor to create a file named
.envin your example folder (next toprueba.ts,prueba.py, or your Go/Java project). - Paste this line and replace the placeholder with your own Jev key:
TYPESAFE_API_KEY=your_real_jev_key
Direct mode only needs TYPESAFE_API_KEY. No account with us, hosted API URL, or SEMANTIC_VALIDATOR_API_KEY is required. The SDK does not load .env automatically.
Keep your key out of Git
Add these lines to your project's .gitignore. If you already published a key, ignoring the file does not erase its history: revoke the key and create a new one.
.env
.venv/
node_modules/
Load .env and run your example
On Debian/Linux or macOS with Bash, open a terminal in the folder containing .env and run:
set -a
source ./.env
set +a
This exports the key to programs launched from that same terminal. Only source a file you own and trust: source can execute shell instructions. Check without printing your secret:
test -n "$TYPESAFE_API_KEY" && echo "Key loaded" || echo "Missing TYPESAFE_API_KEY"
Then run the command for your language:
# TypeScript (in the prueba.ts folder)
npx tsx prueba.ts
# Python (activate your virtual environment first)
source .venv/bin/activate
python prueba.py
# Go (in the main.go and go.mod folder)
go run .
For Java, launch your Maven application from this same terminal. When using an IDE, add TYPESAFE_API_KEY to its run configuration's environment variables. The source block does not work in Windows/PowerShell: configure the process environment variable or use a suitable .env loader.
When finished, remove the terminal variable with unset TYPESAFE_API_KEY. Load the file again when opening a new terminal.
02 / How to use
From text to a decision
After installing an SDK, create a DirectValidator (or NewDirectClient in Go) with your Jev key. Call validate("product_description", text) for a registered rule, or check(text, question) for your own yes/no question. Read status before acting: uncertain means valid is null and needs review; an exception or error means the request failed, not that the text is invalid. A complete example for each language follows. A .env file is not loaded automatically: make sure TYPESAFE_API_KEY is available to your process.
Open evaluation
What the rules did in one test
In a single run of 90 fictional cases, 71 of 72 labeled cases matched; one was uncertain, with no provider errors. Ambiguous cases were tracked separately. This is not a real-world accuracy claim. Read the full results and limitations.
03 / SDKs
Choose your language
Try the four runnable projects without a Jev key. The TypeScript form example shows all three rules and treats uncertain results and provider failures separately.
TypeScript / Node.js
Install the SDK published on npm. Node.js 18+; run on the server, never in a browser.
npm init -y
npm install @jorge-arequipa/semantic-validator@0.3.0
npm install -D tsx @types/nodeSave as prueba.ts and, after loading your .env, run npx tsx prueba.ts:
import { DirectValidator } from "@jorge-arequipa/semantic-validator";
const jevApiKey = process.env.TYPESAFE_API_KEY;
if (!jevApiKey) throw new Error("Missing TYPESAFE_API_KEY");
const validator = new DirectValidator({ jevApiKey });
async function main() {
const product = await validator.validate(
"product_description", "Bosch 750 W power drill"
);
const complaint = await validator.check(
"My order arrived damaged and I need a solution",
"Is the customer making a complaint?"
);
for (const [field, result] of [["product", product], ["complaint", complaint]] as const) {
if (result.status === "uncertain") console.log(field, "needs review");
else console.log(field, result.valid, result.confidence);
}
}
main().catch((error) => {
console.error("Validation request failed:", error);
process.exitCode = 1;
});
Python
Install the SDK published on PyPI. Python 3.10+.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install semantic-validator==0.3.0Save as prueba.py and run python prueba.py:
import os
from semantic_validator import DirectValidator
def show(field, result):
if result.status == "uncertain":
print(field, "needs review")
else:
print(field, result.valid, result.confidence)
validator = DirectValidator(jev_api_key=os.environ["TYPESAFE_API_KEY"])
try:
show("name", validator.name("Jorge Eduardo"))
show("complaint", validator.check(
"My order arrived damaged and I need a solution",
"Is the customer making a complaint?"
))
except Exception as error:
raise SystemExit(f"Validation request failed: {error}") from error
Go
Go 1.22+. Install from the public Go module, or download the Go SDK source archive (.tar.gz).
mkdir go-example && cd go-example
go mod init go-example
go get github.com/eduardoArequipa/semantic-validator/sdk/go@v0.3.0Save as main.go, then run go run .:
package main
import (
"context"
"fmt"
"log"
"os"
validator "github.com/eduardoArequipa/semantic-validator/sdk/go"
)
func main() {
client, err := validator.NewDirectClient(os.Getenv("TYPESAFE_API_KEY"))
if err != nil { log.Fatal(err) }
name, err := client.Name(context.Background(), "Jorge Eduardo")
if err != nil { log.Fatal(err) }
complaint, err := client.Check(context.Background(),
"My order arrived damaged and I need a solution",
"Is the customer making a complaint?")
if err != nil { log.Fatal(err) }
show("name", name)
show("complaint", complaint)
}
func show(field string, result validator.Result) {
if result.Status == "uncertain" {
fmt.Println(field, "needs review")
return
}
fmt.Println(field, *result.Valid, result.Confidence)
}
Java
Download the Java SDK (.tar.gz). Java 11+ and Maven.
tar -xzf semantic-validator-java-0.3.0.tar.gz
mvn -f semantic-validator/sdk/java/pom.xml installAdd the local dependency to your Maven application's pom.xml:
<dependency>
<groupId>io.semanticvalidator</groupId>
<artifactId>semantic-validator-sdk</artifactId>
<version>0.3.0</version>
</dependency>Save as Example.java in your Maven application and run it there:
import io.semanticvalidator.sdk.DirectValidator;
import io.semanticvalidator.sdk.ValidationResult;
public class Example {
public static void main(String[] args) {
String key = System.getenv("TYPESAFE_API_KEY");
if (key == null || key.isBlank()) throw new IllegalStateException("Missing TYPESAFE_API_KEY");
DirectValidator validator = new DirectValidator(key);
try {
show("name", validator.name("Jorge Eduardo"));
show("complaint", validator.check(
"My order arrived damaged and I need a solution",
"Is the customer making a complaint?"));
} catch (Exception error) {
System.err.println("Validation request failed: " + error.getMessage());
System.exit(1);
}
}
static void show(String field, ValidationResult result) {
if ("uncertain".equals(result.getStatus()))
System.out.println(field + ": needs review");
else
System.out.println(field + ": " + result.getValid() + " (" + result.getConfidence() + ")");
}
}After running
Understand the result
Illustrative result fields, not a guaranteed prediction:
{"valid": true, "confidence": 0.98, "status": "valid"}| status | valid | What it means |
|---|---|---|
| valid | true | The engine considers the text to satisfy the condition. |
| invalid | false | The engine considers the text not to satisfy the condition. |
| uncertain | null | Ask for clarification or review; do not treat this as false. |
Confidence is a provider signal, not a guarantee of correctness. A network error or exception is not a negative validation: handle it separately.
Common problems
Missing TYPESAFE_API_KEY or apiKey is required
Creating .env is not enough. Load it, then run your example from the same terminal. Use DirectValidator, not the self-hosted server client.
Python ModuleNotFoundError
Activate .venv and install with python -m pip install semantic-validator==0.3.0, using the same Python that runs your example.
TypeScript Cannot find name 'process'
Install npm install -D @types/node. If your tsconfig restricts types, include "node". Run npx tsx prueba.ts, not node run prueba.ts.
The request fails even though the key is loaded
Check that your Jev key has not been revoked and your account permits inference. Check your connection and the returned error without sharing secrets or private text. Do not call our hosted API: it remains disabled.
04 / Optional
Run your own API server
If you need an HTTP API or central quotas, run the Go server on your infrastructure with your own TYPESAFE_API_KEY. Then set a separate SEMANTIC_VALIDATOR_API_KEY for its callers and use the legacy Validator clients. The server is not required for direct mode.
cp .env.example .env
# Set both keys in .env; keep it private.
set -a; source .env; set +a
go run ./cmd/server
# Own server only: http://localhost:8080/v1/checkSee the OpenAPI contract for your own server. Never send a Jev key as its Semantic Validator API key.
05 / Responsible use
Protect keys and user text
Direct calls require a trusted backend. The text goes to Jev, not to this website. Avoid real personal data in public examples. Apache-2.0 covers our code, not Jev; use your own TypeSafe account subject to its terms. Our hosted API remains disabled and this site serves documentation only.