WordSentinel™ Developer Guide

Technical documentation for the Universal Judgment Engine (UJE). Validate documents against version-pinned, SHA-secured rulebooks and produce cryptographically signed Evidence Packs.

Live Production Profiles
99.9% Uptime SLA
Sub-Second Processing

Quick Start Guide

Get started with the WordSentinel™ API in minutes

AGet a JWT Token

Obtain authentication token from your authentication flow. Never embed secrets in code.

BList Available Profiles
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://universal-judgment-engine-985987917853.us-central1.run.app/profiles" | jq
CSubmit Document for Validation
curl -s -H "Authorization: Bearer $TOKEN" \
  -F "file=@doc.pdf" \
  "https://universal-judgment-engine-985987917853.us-central1.run.app/validate?profile=ops.ksa.hse.ptw@0.1" | jq

Returns a job_id and status of "queued"

DPoll for Job Completion
JOB_ID="..."
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://universal-judgment-engine-985987917853.us-central1.run.app/jobs/$JOB_ID" | jq

When completed, a signed evidence_url will be present

EDownload the Evidence Pack
EVIDENCE_URL="..."
curl -s "$EVIDENCE_URL" | jq '.header, .findings | length'

The Evidence Pack

What to expect from validation results

Header FieldsRequired for Audit
profileExact profile and version used
rulebook_versionSpecific rulebook version
languages_detectedArray of detected languages
rulebook_sha64-char hex for provenance
run_tsISO8601 timestamp
signatureES256 signature via Cloud KMS
Findings Structure

Each finding is deterministic and includes:

  • rule_id - Unique rule identifier
  • severity - Critical, warning, or info
  • rationale - Human-readable explanation
  • measured_vs_required - Comparison values
  • text_spans - Matched document sections
  • citation_ids - Regulatory references

Verifying Signatures

For auditors and security teams

1Fetch Public Key from Google Cloud KMS
gcloud kms keys versions get-public-key \
  --location=us-central1 --keyring=ws-evidence --key=evidence-signing \
  --version=1 --output-file=pubkey.pem
2Python Verification Snippet
import json, hashlib, base64
from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import ec

def canonicalize(d): 
    return json.dumps(d, separators=(",",":"), sort_keys=True).encode()

def b64url_decode(s): 
    s += "=" * (-len(s) % 4)
    return base64.urlsafe_b64decode(s.encode())

pub_key = serialization.load_pem_public_key(open("pubkey.pem", "rb").read())
evidence_pack = json.load(open("evidence.json"))

signature = evidence_pack["signature"]["value"]
header = evidence_pack["header"]
digest = hashlib.sha256(canonicalize(header)).digest()

pub_key.verify(b64url_decode(signature), digest, ec.ECDSA(hashes.SHA256()))
print("Signature OK")

Live Production Profiles

Available validation profiles for operators

PTW KSA
ops.ksa.hse.ptw@0.1
Live Production

Input Format

Permit to Work PDF (EN/AR)

Validation Checks

  • Sign-offs verification
  • Gas test freshness/intervals
  • O2/LEL/H2S thresholds
  • SIMOPS zone/time overlaps
  • LOTO presence
Swiss Finance
finance.ch.disclosure@0.3
Live Production

Input Format

Marketing/disclosure PDF/TXT (DE/FR/IT/EN)

Validation Checks

  • Required disclaimers
  • Prohibited claims
  • KID/BIS references
  • Prominence (warn-only)
UAE Agreements
energy.uae.agreements@0.1
Live Production

Input Format

Agreement PDF (EN/AR)

Validation Checks

  • Liability caps
  • Indemnity breadth
  • Gross negligence/willful misconduct softening
  • ADR clauses
  • Prevailing language
  • EN↔AR parity

Platform & Security

For admins and product teams

Quality Controls

Conservative 'guard bands' prevent false criticals and 'context gating' ensures rules only apply where relevant.

Tenant Overlays

Client-specific rule adjustments (e.g., tighter thresholds) via SHA-pinned overlays.

Rulebook Studio

Internal tool for authoring, testing, and publishing new version-pinned rulebooks.

Security Posture

REQUIRE_JWT=true, no unpinned configurations (ALLOW_UNPINNED=false), evidence signing enabled.

Observability

Dashboards for latency, error rates, key metrics, with alerts for 99.9% uptime SLA deviations.

Reproducibility

Every Evidence Pack tied to release_set, ensuring perfect judgment reproduction for audits.

Security
JWT RequiredEvidence SigningSBOM Attached
Performance
99.9% UptimeSub-Second ProcessingReal-time Monitoring
Compliance
Version PinningSHA VerificationAudit Ready

Contact & Support

Get help from our technical team

Sales & Pilots

Ready to get started with WordSentinel™?

Developer Support

Technical documentation and API references

Security Reviews

Evidence verification guides and SBOMs available

Common Error Codes & Troubleshooting

401

Invalid or expired JWT token

404

Profile not found or inactive

422

Invalid document format or size