nullspan

Single-pass System One structured extraction, multi-numeric contract disambiguation, calibrated p_null abstention, character-offset [start, end] spans, zero-shot boolean/enum judgment, cross-field algebraic invariant verification, and calibrated quantile estimation (p10, median, p90) in JavaScript, Python, and Browser WebAssembly ONNX (512-token context + long-document windowing).

• Interactive Playground (Browser WASM ONNX + Zero-Dep Engine): https://hemanth.github.io/nullspan/
• NullspanBench Leaderboard (JevBench-Style 19-System Evaluation, N=500): https://hemanth.github.io/nullspan/bench.html
• Hugging Face Space: https://huggingface.co/spaces/gnumanth/nullspan
• Fine-Tuned Hugging Face Model (344.2M PyTorch + 330.1 MB Int8 ONNX): https://huggingface.co/gnumanth/nullspan
• Hugging Face Dataset: https://huggingface.co/datasets/gnumanth/nullspan-dataset
• Empirical Science Report: bench/SCIENCE_REPORT.md

In Plain English

Standard LLMs extract data by generating JSON token-by-token, which is slow, bills per output token, can get hijacked by "ignore previous instructions" prompt injections, and often hallucinates values when a field is missing. nullspan acts like a grounded highlighter + calculator instead of a chatbot:

1. Points to Exact Text ([start, end] Span): Highlights exact character positions in your input text (0 output tokens generated), making fabricated strings and prompt-injection payloads impossible.
2. Knows When to Say "Not There" (p_null): Computes a calibrated probability that a field is missing (p_null) and returns null with abstention_reason when evidence is absent.
3. Disambiguates Multi-Numeric Contracts & Checks Math (constraint & verified): Separates competing dollar caps, percentages, day windows, and numeric tranches across multi-section agreements (96/96 on unseen contracts) and verifies equations like subtotal == nodes * hourly_rate.
4. Gives Realistic Ranges (p10 / median / p90): Returns calibrated low/middle/high quantile distributions for estimates and forecasts.

Install

npm install nullspan
pip install nullspan

Usage (JavaScript / ESM)

import { extract } from 'nullspan';

const incident =
  "Incident INC-40928 opened on Apr 12, 2026 with a 502 Bad Gateway errors and a TLS handshake timeouts. " +
  "Issued $1240.50 plus $310.25 SLA credit. Severity is sev-1 and customer data loss was false. " +
  "Root cause CVE not yet assigned. Cluster stabilized on Apr 19, 2026. Reported by Mira";

const result = extract(incident, {
  incident_id: { type: 'text', instructions: 'Incident ticket identifier' },
  opened_on: { type: 'date', instructions: 'Date the incident opened' },
  total_credit: { type: 'number', decimals: 2, unit: 'USD', instructions: 'Total credit including SLA penalty' },
  outage_days: { type: 'duration', unit: 'days', integer: true, instructions: 'Days from incident open to cluster stabilization' },
  failure_modes: { type: 'list', items: 'text', instructions: 'Each failure mode triggered' },
  severity: { type: 'enum', options: ['sev-1', 'sev-2', 'sev-3'], instructions: 'Incident severity tier' },
  data_loss: { type: 'boolean', instructions: 'Whether customer data loss occurred' },
  cve_id: { type: 'text', instructions: 'Assigned CVE identifier if present' },
  remediation_cost: { type: 'estimate', unit: 'USD', min: 100, max: 25000, scale: 'log', step: 10, instructions: 'Estimated engineering remediation cost' },
});

Usage (Python + Cross-Field Invariants + Hugging Face Backend)

from nullspan import extract

invoice = (
    "Invoice from TensorCore Cloud\n"
    "Invoice #88310 | Issued: 2026-08-14 18:20\n"
    "Nodes: 4 @ $3.50 each\n"
    "Subtotal: $14.00\n"
    "Egress Fee: $0.00\n"
    "Priority Surcharge: $1.75"
)

# Zero-dependency fast engine or GCP V100 fine-tuned 344.2M checkpoint (backend="hf" or "onnx")
out = extract(
    state=invoice,
    fields={
        "nodes": {"type": "number", "integer": True, "instructions": "Provisioned GPU node count"},
        "hourly_rate": {"type": "number", "decimals": 2, "unit": "USD", "instructions": "Hourly rate per node"},
        "subtotal": {
            "type": "number",
            "decimals": 2,
            "unit": "USD",
            "constraint": "subtotal == nodes * hourly_rate",
            "instructions": "Compute subtotal before fees and surcharge",
        },
        "promo_rebate": {"type": "number", "decimals": 2, "unit": "USD", "instructions": "Promotional rebate amount if present"},
    },
    backend="hf",
    model_id="gnumanth/nullspan",
)
# out["invariants_passed"] -> True, out["answers"]["subtotal"]["verified"] -> True

Architecture (NullspanForExtraction v2.0 · 344.2M ELECTRA-Large + Adapter)

1. null_head (Span-Attended Calibrated Abstention): Bilinear span-summary + [CLS] margin residual with held-out temperature scaling (p_null AUROC 0.9983, ECE 0.0121) and abstention_reason (unassigned_placeholder vs missing_field).
2. span_head (Grounded Pointer + Shannon Entropy): Projects 512-token encoder states (plus query-conditioned sliding windows on ultra-long contracts) to [start, end] character spans with calibrated confidence and Shannon span_entropy_bits.
3. bio_head (Multi-Span List Tagging): Extracts ordered text and numeric tranche arrays (type: "list") in a single pass.
4. op_head (10-Way System One Router): Routes fields across SPAN_TEXT, SPAN_NUMBER, ARITH_SUM, ARITH_DIFF, ARITH_MUL, ISO_DATETIME, DATE_DURATION, DIST_ESTIMATE_FORECAST, BOOL_JUDGE (p_true), and ENUM_CLASSIFY (probs).
5. quantile_head + Invariant Verifier: Predicts monotone (p10, median, p90) quantiles and verifies cross-field algebraic constraints (verified: true/false).

NullspanBench Leaderboard (bench/run_bench.py · 19 Systems · $N=500$ Zero-Leakage Decisions)

Modeled after BenchmarkHeaven's JevBench, NullspanBench v3.2 evaluates 19 systems (13 local open-weights/open-code models running live forward passes, live Cloudflare Workers AI @cf/cloudflare/clairic + @cf/cloudflare/clef, 2 reference JSON-mode LLM decoders, and 3 published JevBench v1.7 reference anchors) across 500 zero-leakage observations (336 Open structured items + 164 Sealed items: 60 Stanford SQuAD v2.0, 96 Multi-Numeric Legal/Commercial Contract fields across 12 unseen agreements, and 8 Adversarial prompt-injection traps) on four axes: Intelligence (I), Calibration (C), Speed (S), and Cost (K).

Explore interactive weight sliders, Pareto frontier plots, and 2-system radar comparisons at https://hemanth.github.io/nullspan/bench.html:

See full methodology, proper scoring definitions, request-type breakdowns (100.0% on Multi-Numeric Contracts n=96, 100.0% Choice n=41, 100.0% Math & Invariants n=51), and head-to-head analysis in bench/SCIENCE_REPORT.md.

License

MIT © Hemanth.HM