@kiwicha-ai/sdk

Cliente del motor Kiwicha por MCP — la capa de verificación anti-alucinación para tus aplicaciones con IA, en cualquier dominio.

Tu modelo genera; Kiwicha decide y verifica contra hechos reales. Las respuestas y los veredictos salen de los datos de tu tenant, no de la imaginación del modelo. Este paquete es solo el cliente (HTTP / JSON-RPC): todo el razonamiento corre en el motor — sirve igual para salud, legal, retail, finanzas o lo que conectes.

npm install @kiwicha-ai/sdk

Requiere Node 18+. Necesitas una URL y un token de tu cuenta Kiwicha. El paquete es público; sin un token válido no hace nada — la protección está en el motor.

Configuración

KIWICHA_MCP_URL=https://api.kiwicha.ai/v3/mcp
KIWICHA_TOKEN=tok-<token-opaco>        # se entrega una sola vez, por canal seguro

import { Kiwicha } from "@kiwicha-ai/sdk";

const kiwicha = Kiwicha.fromEnv();      // o: new Kiwicha(url, token)

Tres formas de usarlo (genéricas, para cualquier dominio)

1. decide(question) — conversar sin alucinar

Pregunta en lenguaje natural; recibes la respuesta grounded (el motor interpreta → razona → verbaliza). Si la respuesta no está respaldada por los datos de tu tenant, el motor no la inventa: reconduce o pide el dato que falta.

const r = await kiwicha.decide(userMessage);   // el texto del usuario, tal cual
// r.answer   → respuesta verbalizada SOLO desde los hechos de tu tenant
// r.grounded → true si está respaldada por datos
// r.receipt  → recibo re-verificable del turno

if (!r.grounded) {
  // el motor no tenía con qué responder → no inventó. Decide tú (derivar, reformular…)
}

2. verify(text, context?) — chequear lo que generó tu modelo

Le pasas el texto crudo que produjo tu LLM; el motor extrae las afirmaciones, las verifica contra las reglas de tu tenant y devuelve los problemas, listos para mostrar.

const issues = await kiwicha.verify(modelOutput, supportingContext);
// issues: [{ code, severity: "blocking" | "warning", message, citations: [...] }]

if (issues.some((i) => i.severity === "blocking")) {
  // no muestres la respuesta tal cual: contradice tus datos
}

severity: "blocking" significa no muestres esa respuesta. Kiwicha falla cerrado: si la verificación no se pudo completar (token inválido, cuota, error), verify lanza — un fallo nunca se interpreta como "0 problemas". Solo si el motor está inalcanzable (red caída) devuelve [].

3. query / values — decisión lógica determinística

Cuando ya tienes datos estructurados y quieres una decisión sin alucinación posible. La regla y los predicados los defines tú, por dominio:

const result = await kiwicha.query(rule, ["?X"], facts);
// result: { holds, count, solutions, receipt }

// atajo: los valores de una variable libre
const flagged = await kiwicha.values(rule, "?X", facts);

API

| Método | Qué hace | |---|---| | Kiwicha.fromEnv() | Instancia desde KIWICHA_MCP_URL + KIWICHA_TOKEN (o null si faltan) | | decide(question) | Pregunta NL → { answer, grounded, receipt } (interpreta → razona → verbaliza) | | verify(text, context?) | Texto crudo → VerifyIssue[] (extracción + reglas server-side) | | query(pred, vars, facts?, max?) | Consulta lógica → { holds, count, solutions, receipt } | | values(pred, variable, facts?, max?) | Atajo: los valores de una variable libre | | summarizeIssues(...listas) | Junta tus chequeos + los de Kiwicha y clasifica por severidad |

El bridge — solo si Kiwicha verifica contra TU base de datos

Si una regla necesita cruzar contra tu base (tu catálogo, tus expedientes, lo que sea), corres un conector de solo lectura junto a tu base. Ya viene en este paquete — un comando:

DATABASE_URL="postgres://USUARIO:CLAVE@HOST:5432/TU_BASE?sslmode=require" \
BRIDGE_TOKEN="un-secreto-que-tu-eliges" \
npx kiwicha-bridge
# escucha en :8133 (configurable con PORT) · verifica con: curl localhost:8133/healthz

• Postgres gestionado (Supabase, RDS, Neon): agrega ?sslmode=require (TLS 1.3, sin instalar nada). Con Supabase, usa el session pooler (puerto 5432), no el transaction pooler (6543).
• Tu DATABASE_URL se queda en tu infraestructura — Kiwicha nunca la ve.
• Es TypeScript legible (src/bridge/, ~400 líneas auditables): introspección de esquema + SELECTs parametrizados, nada más. ¿MySQL? npm install mysql2 y usa mysql://….

Para conectarlo a tu cuenta (self-service): expón el bridge con una URL pública HTTPS y crea tu sub-tenant con la tool MCP kiwicha_onboard usando tu key de administración — pasa resolver_url (tu URL pública + /mcp) y dp_token (el mismo BRIDGE_TOKEN). Kiwicha introspecciona tu esquema, deriva las reglas sola y te devuelve el token del sub-tenant, activo al instante. Sin pasos manuales de nuestro lado.

El caso común —verificar texto o conversar— no necesita el bridge.

Soporte: [email protected] · Licencia: propietaria (ver LICENSE) · © 2026 KIWICHA