← Semantic Validator

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

  1. Choose and install your SDK. Use your editor to create a file named .env in your example folder (next to prueba.ts, prueba.py, or your Go/Java project).
  2. 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/node

Save 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.0

Save 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.0

Save 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 install

Add 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"}
statusvalidWhat it means
validtrueThe engine considers the text to satisfy the condition.
invalidfalseThe engine considers the text not to satisfy the condition.
uncertainnullAsk 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/check

See 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.