← Semantic Validator

Guía de SDKs · usa tu propia clave de Jev

Valida significado
sin nuestro servidor.

Usa tu propia cuenta de TypeSafe/Jev desde un backend de confianza. El SDK envía el texto directamente a Jev y devuelve valid, confidence y status. No necesitas una cuenta ni una clave nuestra. La API alojada en este dominio sigue pausada.

01 / Inicio

Obtén tu clave de Jev

El código es gratuito y abierto bajo Apache-2.0. Crea una clave en tu cuenta de TypeSafe y expónla a tu proceso backend como TYPESAFE_API_KEY. No la subas al repositorio, no la pongas en el frontend ni nos la compartas. Los SDKs TypeScript y Python ya están publicados en npm y PyPI. Java se instala desde el código fuente (Maven Central pendiente); el SDK Go forma parte del módulo público.

Las tres reglas de campos son person_name, product_description y address; usa check(value, question) para otras preguntas semánticas. Una confianza inferior a 0.80 devuelve status="uncertain" y valid=null. Cada elemento del batch consulta Jev por separado y se carga a tu cuenta.

Configuración / Paso a paso

Tu clave en un archivo .env

  1. Elige e instala tu SDK. En la carpeta de tu ejemplo (prueba.ts, prueba.py o tu proyecto Go/Java), crea un archivo llamado .env con tu editor.
  2. Copia este contenido y reemplaza el marcador por tu clave real de Jev:
TYPESAFE_API_KEY=tu_clave_real_de_jev

En modo directo solo necesitas TYPESAFE_API_KEY. No necesitas una cuenta nuestra, una URL de nuestra API ni SEMANTIC_VALIDATOR_API_KEY. El SDK no carga el archivo automáticamente.

No publiques tu clave

Añade estas líneas al .gitignore de tu proyecto. Si la clave ya fue publicada, ignorar el archivo no la elimina del historial: revócala y crea otra.

.env
.venv/
node_modules/

Carga .env y ejecuta tu ejemplo

En Debian/Linux o macOS con Bash, abre una terminal en la carpeta que contiene tu .env. Ejecuta:

set -a
source ./.env
set +a

Esto exporta la clave a los programas que ejecutes desde esa misma terminal. Usa solo un archivo propio y de confianza: source puede ejecutar instrucciones de shell. Comprueba la carga sin mostrar la clave:

test -n "$TYPESAFE_API_KEY" && echo "Clave cargada" || echo "Falta TYPESAFE_API_KEY"

Ahora ejecuta el comando de tu lenguaje:

# TypeScript (en la carpeta de prueba.ts)
npx tsx prueba.ts

# Python (activa primero el entorno virtual)
source .venv/bin/activate
python prueba.py

# Go (en la carpeta de main.go y go.mod)
go run .

Para Java, lanza tu aplicación Maven desde esta misma terminal; si usas un IDE, configura TYPESAFE_API_KEY en las variables de entorno de su configuración de ejecución. En Windows/PowerShell, el bloque source no funciona: configura esa variable en el entorno del proceso o usa un cargador de .env apropiado.

Al terminar, puedes quitar la variable de la terminal con unset TYPESAFE_API_KEY. Si abres otra terminal, vuelve a cargar el archivo.

02 / Cómo usarlo

De un texto a una decisión

Una vez instalado un SDK, crea un cliente DirectValidator (en Go, NewDirectClient) con tu clave de Jev. Usa validate("product_description", texto) para una regla registrada, o check(texto, pregunta) para una pregunta propia. Lee status antes de actuar: uncertain significa que valid es nulo y requiere revisión; una excepción o error indica que la consulta falló, no que el texto sea inválido. Debajo tienes un ejemplo ejecutable para cada lenguaje. Un archivo .env no se carga automáticamente: asegúrate de que TYPESAFE_API_KEY esté presente en el entorno del proceso.

Evaluación abierta

Qué ocurrió en una prueba

En una ejecución de 90 casos ficticios, 71 de 72 casos etiquetados coincidieron; uno quedó incierto y no hubo errores del proveedor. Los casos ambiguos se contaron aparte. Esto no demuestra precisión en casos reales. Consulta los resultados completos y sus límites.

03 / SDKs

Elige tu lenguaje

Prueba los cuatro proyectos ejecutables sin clave de Jev. El ejemplo de formulario TypeScript usa las tres reglas y distingue resultados inciertos de fallos del proveedor.

TypeScript / Node.js

Instala el SDK publicado en npm. Node.js 18+; úsalo en el servidor, nunca en el navegador.

npm init -y
npm install @jorge-arequipa/semantic-validator@0.3.0
npm install -D tsx @types/node

Guarda como prueba.ts y, después de cargar tu .env, ejecuta npx tsx prueba.ts:

import { DirectValidator } from "@jorge-arequipa/semantic-validator";

const jevApiKey = process.env.TYPESAFE_API_KEY;
if (!jevApiKey) throw new Error("Falta TYPESAFE_API_KEY");
const validator = new DirectValidator({ jevApiKey });

async function main() {
  const producto = await validator.validate(
    "product_description", "Taladro Bosch de 750 W"
  );
  const reclamo = await validator.check(
    "Mi pedido llegó dañado y quiero una solución",
    "¿El cliente está presentando un reclamo?"
  );
  for (const [campo, resultado] of [["producto", producto], ["reclamo", reclamo]] as const) {
    if (resultado.status === "uncertain") console.log(campo, "requiere revisión");
    else console.log(campo, resultado.valid, resultado.confidence);
  }
}

main().catch((error) => {
  console.error("No se pudo validar:", error);
  process.exitCode = 1;
});

Python

Instala el SDK publicado en PyPI. Python 3.10+.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install semantic-validator==0.3.0

Guarda como prueba.py y ejecuta python prueba.py:

import os
from semantic_validator import DirectValidator

def mostrar(campo, resultado):
    if resultado.status == "uncertain":
        print(campo, "requiere revisión")
    else:
        print(campo, resultado.valid, resultado.confidence)

validator = DirectValidator(jev_api_key=os.environ["TYPESAFE_API_KEY"])
try:
    mostrar("nombre", validator.name("Jorge Eduardo"))
    mostrar("reclamo", validator.check(
        "Mi pedido llegó dañado y quiero una solución",
        "¿El cliente está presentando un reclamo?"
    ))
except Exception as error:
    raise SystemExit(f"No se pudo validar: {error}") from error

Go

Go 1.22+. Instala desde el módulo Go público o descarga el código del SDK Go (.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

Guarda como main.go; ejecuta 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) }
  nombre, err := client.Name(context.Background(), "Jorge Eduardo")
  if err != nil { log.Fatal(err) }
  reclamo, err := client.Check(context.Background(),
    "Mi pedido llegó dañado y quiero una solución",
    "¿El cliente está presentando un reclamo?")
  if err != nil { log.Fatal(err) }
  mostrar("nombre", nombre)
  mostrar("reclamo", reclamo)
}

func mostrar(campo string, result validator.Result) {
  if result.Status == "uncertain" {
    fmt.Println(campo, "requiere revisión")
    return
  }
  fmt.Println(campo, *result.Valid, result.Confidence)
}

Java

Descarga el SDK Java (.tar.gz). Java 11+ y Maven.

tar -xzf semantic-validator-java-0.3.0.tar.gz
mvn -f semantic-validator/sdk/java/pom.xml install

Agrega la dependencia local al pom.xml de tu aplicación Maven:

<dependency>
  <groupId>io.semanticvalidator</groupId>
  <artifactId>semantic-validator-sdk</artifactId>
  <version>0.3.0</version>
</dependency>

Guarda como Prueba.java en tu aplicación Maven y ejecútalo desde allí:

import io.semanticvalidator.sdk.DirectValidator;
import io.semanticvalidator.sdk.ValidationResult;

public class Prueba {
  public static void main(String[] args) {
    String key = System.getenv("TYPESAFE_API_KEY");
    if (key == null || key.isBlank()) throw new IllegalStateException("Falta TYPESAFE_API_KEY");
    DirectValidator validator = new DirectValidator(key);
    try {
      mostrar("nombre", validator.name("Jorge Eduardo"));
      mostrar("reclamo", validator.check(
        "Mi pedido llegó dañado y quiero una solución",
        "¿El cliente está presentando un reclamo?"));
    } catch (Exception error) {
      System.err.println("No se pudo validar: " + error.getMessage());
      System.exit(1);
    }
  }

  static void mostrar(String campo, ValidationResult result) {
    if ("uncertain".equals(result.getStatus()))
      System.out.println(campo + ": requiere revisión");
    else
      System.out.println(campo + ": " + result.getValid() + " (" + result.getConfidence() + ")");
  }
}

Después de ejecutar

Cómo interpretar la respuesta

Ejemplo ilustrativo de los campos del resultado, no una predicción garantizada:

{"valid": true, "confidence": 0.98, "status": "valid"}
statusvalidQué hacer
validtrueEl motor considera que el texto cumple la condición.
invalidfalseEl motor considera que no cumple la condición.
uncertainnullPide más información o revisión; no lo trates como false.

La confianza es una señal del proveedor, no una garantía de acierto. Una excepción o error de red no es una validación negativa: maneja ese fallo por separado.

Problemas frecuentes

Falta TYPESAFE_API_KEY o apiKey is required

Crear .env no basta. Cárgalo y ejecuta el ejemplo desde esa misma terminal. Comprueba también que usas DirectValidator, no el cliente para un servidor propio.

ModuleNotFoundError en Python

Activa .venv e instala con python -m pip install semantic-validator==0.3.0 usando el mismo Python con el que ejecutarás el ejemplo.

Cannot find name 'process' en TypeScript

Instala npm install -D @types/node. Si tienes un tsconfig con una lista types, incluye "node". Ejecuta con npx tsx prueba.ts, no con node run prueba.ts.

La consulta falla aunque la clave está cargada

Revisa que la clave Jev no esté revocada y que tu cuenta permita usar la inferencia. Revisa tu conexión y el error recibido, sin publicar la clave ni datos privados. No envíes solicitudes a nuestra API alojada: sigue desactivada.

04 / Opcional

Ejecuta tu propia API

Si necesitas una API HTTP o cuotas centralizadas, ejecuta el servidor Go en tu infraestructura con tu propia TYPESAFE_API_KEY. Configura otra SEMANTIC_VALIDATOR_API_KEY para sus clientes y usa las clases anteriores Validator. El servidor no es necesario para el modo directo.

cp .env.example .env
# Configura ambas claves en .env; mantenlo privado.
set -a; source .env; set +a
go run ./cmd/server
# Solo tu servidor: http://localhost:8080/v1/check

Consulta el contrato OpenAPI de tu servidor. Nunca uses la clave Jev como clave de Semantic Validator.

05 / Uso responsable

Protege las claves y el texto

El modo directo exige un backend de confianza. El texto va a Jev, no a esta web. Evita datos personales reales en ejemplos públicos. Apache-2.0 cubre nuestro código, no Jev; usa tu cuenta TypeSafe conforme a sus términos. Nuestra API alojada sigue deshabilitada y este sitio solo sirve documentación.