Skip to main content

Semantic Validator Python SDK

Español · Source · Runnable example

A synchronous Python SDK for semantic field validation and custom yes/no questions using Jev. Call Jev directly with your own key, or connect to your own Semantic Validator REST API. Requires Python 3.10+ and has no runtime dependencies. Free and open source under Apache-2.0; Jev usage belongs to your own TypeSafe account.

Installation

The PyPI distribution name is semantic-validator; the Python import is semantic_validator. The registry installation command is:

python -m pip install semantic-validator

For installation from a repository checkout:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e sdk/python

Direct Jev mode

Make your own Jev key available as TYPESAFE_API_KEY in your backend's environment, then run:

import os
from semantic_validator import DirectValidator, SemanticValidatorError

validator = DirectValidator(jev_api_key=os.environ["TYPESAFE_API_KEY"])

try:
    result = validator.check(
        "My order arrived damaged and I want a replacement",
        "Is the customer reporting a problem with their order?",
    )
    if result.status == "uncertain":
        print("Needs review", result.confidence)
    else:
        print(result.valid, result.confidence, result.status)
except SemanticValidatorError as error:
    print("Provider request failed:", error.code)

Calls send your text directly to Jev and may consume credits. Keep keys in trusted backend code. A .env file is not loaded automatically.

Built-in field rules

name = validator.name("Jorge Eduardo")
description = validator.validate(
    "product_description", "Cordless 18 V drill with two batteries"
)
address = validator.validate("address", "Av. Libertad 123, floor 2")

The built-in rules are person_name, product_description, and address (v1). Read the rule definitions and limits. Semantic plausibility does not verify identity, product facts, or whether an address is deliverable.

Results and errors

Each result has valid, confidence, and status. A confidence score below 0.80 returns valid=None and status="uncertain"; treat it as a request for review. Confidence is the provider's score, not a guarantee of correctness. SemanticValidatorError represents request, HTTP, or response failures and must be handled separately from an invalid value.

Batch

results = validator.validate_batch([
    {"id": "name", "rule": "person_name", "value": "Jorge Eduardo"},
    {"id": "other", "rule": "person_name", "value": "sdgfxcdg"},
])

Direct mode makes one Jev request per item and retains input order. Items can have their own errors.

Self-hosted API mode

import os
from semantic_validator import Validator

validator = Validator(
    api_key=os.environ["SEMANTIC_VALIDATOR_API_KEY"],
    base_url="http://localhost:8080",
)
result = validator.name("Jorge Eduardo")
print(result.valid, result.confidence, result.status)

This client's API key belongs to your Semantic Validator instance. Follow the self-hosted guide.

Development

From a checkout with the SDK installed:

python -m unittest discover -s sdk/python/tests -p 'test_*.py'
python -m unittest discover -s examples/python-direct -p 'test_*.py'

These tests use simulated provider responses and do not need a Jev key. Contributions are welcome; see the contribution guide and report issues.

Metadata

Release files for semantic-validator 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for semantic-validator 0.3.0
File Size Uploaded Provenance Actions
semantic_validator-0.3.0.tar.gz 13.2 kB Without provenance Details for semantic_validator-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for semantic-validator 0.3.0
File Interpreter ABI Platform Actions
semantic_validator-0.3.0-py3-none-any.whl Python 3 none any Details for semantic_validator-0.3.0-py3-none-any.whl

Total release size: 24.4 kB

Release files / semantic_validator-0.3.0.tar.gz

Download URL semantic_validator-0.3.0.tar.gz
Size 13.2 kB
Tags Source
SHA-256 checksum
How to use checksums
d84c95f40e782f6d304a3fdc0e7e41738c2087b915b8acdf5b06e10b9f5c12d5
BLAKE2b-256 checksum
How to use checksums
a270b32111c4e89598e8880400e3aeb9d365c177282cedc368054c2c9a86c3d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.2

Release files / semantic_validator-0.3.0-py3-none-any.whl

Download URL semantic_validator-0.3.0-py3-none-any.whl
Size 11.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cc445c4902d054673451f029392d72b778f83809b027af48c35efc92e5abc611
BLAKE2b-256 checksum
How to use checksums
664e7fd90b06e221907b609e8d9422efe8c086a3e8ac98cb4d7847158c1dbff1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.2

Security for semantic-validator 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page