ProveML

What it adds

Most grounding systems verify around text. ProveML puts the verification boundary inside the text itself. Entity mentions, direct facts, and thresholded inferences can all be checked against a fact store and registry without another model in the loop.

It is designed to be easy to pull into an existing flow: one JavaScript package, one verifier, one optional renderer, and no extra model call to perform verification.

It also ships with built-in TypeScript declarations, so JavaScript and TypeScript agents can consume the same small runtime without extra wrappers.

Reference implementation

markdown-it plugin for rendered, verification-aware HTML
Embeddable HTML renderer for direct browser or app integration
Standalone verifier for pipeline checks and audits
Threshold registry with boolean composition
Optional reference CSS with stable classes for easy restyling

Core constructs

Entity

@[entity:id]{text}

Binds the current lexical context to an addressable subject. Facts that follow resolve against this entity until another entity is introduced or a scoped entity block ends.

Fact

%[field]{value}

Checks direct fact reproduction against the current entity path. Equality is exact against the fact store’s canonical representation, including units when present.

Inference

?[label: THRESHOLD]{text}

Verifies qualitative claims through registered predicates such as numeric ranges, missing-value checks, membership, and cross-entity comparisons.

Agent quick reference

ProveML works best when agents treat it as a small authoring language rather than decorative markup. Bind an entity, reproduce exact stored facts with fact references, and express qualitative judgments through registered thresholds.

Bind first: write an entity reference before facts.
Facts are exact: `%[price]{29.90}` does not match a stored `29.9`.
Inferences are semantic: use thresholds for ranges, missing values, membership, and comparisons.
Coverage is separate: unsupported prose outside markup is not verified.

Open the agent reference

Minimal pattern

@[company:aapl]{Apple Inc.} reported revenue of
%[revenue]{416161000000 USD} with net income of
%[netIncome]{112010000000 USD}.
?[profitable: IS_PROFITABLE]{This is a highly profitable company}.

Getting data in

ProveML does not need a heavy importer. It expects a flat fact store with keys like company:aapl.revenue and optional unit metadata such as company:aapl.revenue._unit.

If your source is already structured JSON, CSV rows, or query results, the mapping step is usually small. That mapping code is often a good place to use AI, because it remains short, inspectable, and easy to test.

Once you have a first draft, run npx proveml doctor --facts facts.json to catch obvious key-shape, unit, and missing-name issues before debugging markup.

Open the fact-store guide

Canonical shape

{
  'company:aapl.name': 'Apple Inc.',
  'company:aapl.revenue': 416161000000,
  'company:aapl.revenue._unit': 'USD',
  'company:aapl.netIncome': 112010000000,
  'company:aapl.netIncome._unit': 'USD',
}

From markup to verified text

These examples show the source markup next to the rendered result a reader would see.

Direct facts

Source

@[company:aapl]{Apple Inc.} reported revenue of
%[revenue]{416161000000 USD} with net income of
%[netIncome]{112010000000 USD}.

Rendered

Apple Inc. reported revenue of 416161000000 USD^✓ with net income of 112010000000 USD^✓.

The entity is bound once; both facts resolve against the current entity context.

Threshold inference

Source

@[company:msft]{Microsoft Corporation} has
%[netMargin]{36}%.
?[high: IS_ABOVE_30]{This exceeds the 30%
net-margin threshold}.

Registered as IS_ABOVE_30: { field: 'netMargin', op: 'gt', value: 30 }; not part of the built-in example registry.

Rendered

Microsoft Corporation has 36%^✓. This exceeds the 30% net-margin threshold^✓

The sentence is accepted because the registered predicate holds for the bound value.

Unchecked prose

Source

@[company:AAPL]{Apple Inc.} reported
%[revenue]{391.0 USD bn}.
This performance was extremely safe.

Interpretation

Verified boundary: entity and direct facts are machine-checkable.

Outside boundary: “extremely safe” remains plain prose with no verification status.

Quick start

npm install proveml

npx proveml example

npx proveml strip --input report.md > plain.md

npx proveml doctor --facts facts.json

import { verifyProveml } from 'proveml/verify';

const factStore = {
  'company:aapl.name': 'Apple Inc.',
  'company:aapl.revenue': 416161000000,
  'company:aapl.revenue._unit': 'USD',
  'company:aapl.netIncome': 112010000000,
  'company:aapl.netIncome._unit': 'USD',
};

const result = verifyProveml(
  '@[company:aapl]{Apple Inc.} reported revenue of %[revenue]{416161000000 USD} with net income of %[netIncome]{112010000000 USD}.',
  factStore
);

console.log(result.verified, result.total);

Add markdown-it only if you want the plugin integration path.

For plain browser or app embedding without markdown-it, use proveml/render. It emits stable semantic class names and exports a small class-name map; proveml/style.css is only the reference theme.

verifyProveml, renderProveml, and the plugin factStore option also accept adapters with resolve(path) when you want source-authentication metadata in addition to plain fact matching.

Package surface

npx proveml: Tiny CLI for strip, doctor, verify, render, and copyable example output
proveml: markdown-it plugin for rendering and verification metadata
proveml/render: Lightweight HTML renderer for ordinary DOM embedding, with optional hover behavior and stable class names
proveml/verify: Standalone verification plus syntax stripping for CI, pipelines, correction loops, and clean persisted text
proveml/trust-adapter: Helpers for wrapping plain fact stores or custom authenticated backends behind the same resolve(path) contract
proveml/thresholds: Threshold registry and predicate evaluation
proveml/style.css: Reference rendering styles for verified spans

What ships in this repo

JavaScript reference implementation for parsing, rendering, and verification
Self-contained test suites for plugin behavior, grammar conformance, and error detection
Examples that show how ProveML can sit inside larger AI workflows
Agent-oriented docs for discovery and correct usage in developer tooling

Current repo direction

ProveML is intended as a clear, usable package-first reference implementation: small enough to inspect, light enough to embed, and permissive enough for other teams to build on.

The practical adoption target is simple: npm package for the runtime, optional skill for agent ergonomics, optional CSS for quick default rendering.

Read the README

The companion research repository now holds the paper, benchmarks, experiment outputs, and citation-audit workflow so this repo can stay focused on the runtime and docs.