API de evaluación de JEV

Modos de evaluación y ejemplos

Usa el mismo endpoint y la clave de API Bearer para ambos modos. Envía useCase + input o state + questions. No los mezcles ni envíes model. La herramienta MCP nexscope_jev_evaluate acepta el mismo cuerpo.

El modo personalizado acepta texto no vacío, un objeto o un array como estado y entre 1 y 32 preguntas. Las instrucciones son cadenas obligatorias de hasta 4 000 caracteres. Choice acepta entre 2 y 255 opciones; Score acepta entre 2 y 32 niveles de texto ordenados. Las descripciones de criterios admiten hasta 2 000 caracteres. Los ID de preguntas y opciones usan entre 1 y 64 letras, dígitos, guiones bajos o guiones. Los ID de palabras clave, evidencias, hechos y candidatos usan el mismo formato y deben ser únicos dentro de sus respectivos arrays.

La solicitud serializada completa debe ocupar como máximo 16 000 bytes UTF-8, aunque cada campo cumpla sus límites. Cada llamada cuenta como una solicitud, incluso si incluye un lote de palabras clave. No se obtienen datos automáticamente. Envía solo contexto que tengas autorización para compartir con TypeSafe.

{
  "state": {
    "product": "750ml insulated steel water bottle",
    "keyword": "hiking water bottle"
  },
  "questions": {
    "relevant": {
      "type": "noul",
      "instructions": "Is the keyword relevant to this product?"
    },
    "intent": {
      "type": "choice",
      "instructions": "Classify the search intent.",
      "criteria": {
        "purchase": "Looking for a product to buy",
        "research": "Looking for information",
        "other": "Neither"
      }
    },
    "fit": {
      "type": "score",
      "instructions": "Rate keyword fit using only the product description.",
      "criteria": [
        "Unrelated",
        "Weak fit",
        "Good fit",
        "Direct fit"
      ]
    }
  }
}

{
  "useCase": "response_guardrails",
  "input": {
    "content": "Never share your password with anyone."
  }
}

{
  "useCase": "ip_risk_triage",
  "input": {
    "text": "A product description using a third-party brand name."
  }
}

{
  "useCase": "seo_relevance",
  "input": {
    "query": "insulated hiking bottle",
    "title": "Insulated steel water bottle for hiking"
  }
}

{
  "useCase": "evidence_check",
  "input": {
    "claim": "The bottle holds 750ml.",
    "sourceText": "Capacity: 750ml. Material: steel.",
    "quote": "Capacity: 750ml."
  }
}

{
  "useCase": "keyword_business_relevance",
  "input": {
    "businessDescription": "We sell reusable hiking bottles.",
    "exclusions": [
      "Disposable bottles"
    ],
    "keywords": [
      {
        "id": "k1",
        "keyword": "steel hiking bottle"
      }
    ],
    "serpEvidence": [
      {
        "id": "e1",
        "keywordId": "k1",
        "source": "Supplied search result excerpt",
        "text": "Reusable steel bottles for outdoor use."
      }
    ]
  }
}

{
  "useCase": "keyword_cluster_fit",
  "input": {
    "keywords": [
      {
        "id": "k1",
        "keyword": "insulated hiking bottle"
      }
    ],
    "candidates": [
      {
        "id": "c1",
        "keyword": "hiking water bottles"
      }
    ]
  }
}

{
  "useCase": "amazon_keyword_product_fit",
  "input": {
    "marketplace": "US",
    "productFacts": [
      {
        "id": "f1",
        "source": "title",
        "value": "750ml insulated steel water bottle"
      }
    ],
    "keywords": [
      {
        "id": "k1",
        "keyword": "steel water bottle"
      }
    ]
  }
}

Leer una respuesta personalizada

El sobre de Nexscope sigue siendo code / msg / data. El modo personalizado devuelve data.useCase = custom, policyVersion = jev-custom-v1, decision = evaluated, reasonCodes y checks vacíos y las respuestas en data.result.answers. Evaluated confirma que hay respuestas disponibles; no aprueba ninguna acción. Usa tus propios umbrales de decisión. No se expone el uso de tokens.

{
  "code": 0,
  "msg": "success",
  "data": {
    "useCase": "custom",
    "policyVersion": "jev-custom-v1",
    "model": "<resolved model>",
    "decision": "evaluated",
    "reasonCodes": [],
    "checks": {},
    "result": {
      "answers": {
        "relevant": {
          "type": "noul",
          "noul": 0.92
        },
        "intent": {
          "type": "choice",
          "choice": "purchase",
          "confidence": 0.9,
          "probabilities": {
            "purchase": 0.9,
            "research": 0.08,
            "other": 0.02
          }
        },
        "fit": {
          "type": "score",
          "score": 2.8,
          "confidence": 0.9,
          "probabilities": {
            "0": 0,
            "1": 0,
            "2": 0.2,
            "3": 0.8
          },
          "legend": {
            "0": "Unrelated",
            "1": "Weak fit",
            "2": "Good fit",
            "3": "Direct fit"
          }
        }
      }
    }
  }
}

Los valores anteriores son ilustrativos. Noul es la probabilidad de sí, no un booleano. Score es el promedio de niveles con índice inicial cero ponderado por probabilidades y puede ser fraccionario. Los ajustes predefinidos de palabras clave devuelven filas en data.result.rows, identificadas por el ID de entrada, con etiquetas, confianza y reasonCodes; evidenceRefs identifica el contexto proporcionado, no fuentes verificadas de forma independiente. La versión de la política de palabras clave es jev-keyword-tools-v1; los ajustes predefinidos originales conservan jev-evaluation-v1.

Errores y límites

Comprueba el código de respuesta antes de leer los datos. 99001: parámetros no válidos; corrige la solicitud. 99009: cuota compartida superada; espera antes de volver a intentarlo. 13007: evaluación no disponible, tiempo de espera agotado o respuesta ascendente no válida; no se devuelve ninguna decisión utilizable. Se requiere una suscripción activa. Cada evaluación tiene un límite de espera ascendente de 10 segundos y no se reintenta automáticamente.

Este es el contrato de API de Nexscope. Usa TypeSafe internamente y aplica de forma intencionada los límites anteriores; no es un acceso sin restricciones a la TypeSafe API.