API reference

Every public name in the groundlens package, with its parameters, their types, their defaults and the value to use when you are not sure. Version 3.0.1.

Installation

The core package has no runtime dependencies. Not numpy, not torch. A CI job fails the build if that ever changes, so pip install groundlens can never grow into a deep learning install by accident.

pip install groundlens                    # core only, no dependencies
pip install "groundlens[encoder]"         # + the reference sentence encoder
pip install "groundlens[encoder,mcp]"     # + the MCP server
pip install "groundlens[dev]"             # + pytest, ruff, mypy

Python 3.10 through 3.14. Linux, macOS and Windows.

Quickstart

from groundlens import proofread, SentenceTransformerEncoder

answer  = "The rate is 4.75% payable within 45 days."
sources = [("policy.pdf#p3", "The rate stated is 3.90% and the term is 30 days.")]

marks = proofread(answer, sources, encoder=SentenceTransformerEncoder(), k=2)

print(marks.report())
#  4.75%   support 0.00    nearest in policy.pdf#p3: '3.90%'
#  45      support 0.00    nearest in policy.pdf#p3: '30'

Constructing SentenceTransformerEncoder() downloads the model on first use, roughly 420 MB, and caches it. Build it once and reuse it: it is the expensive object in the library.

Concepts

Four terms recur through this reference and are worth fixing before the signatures.

Functions

functiongroundlens.proofread(…)

proofread(
    answer: str,
    context: str | Sequence[str] | Sequence[tuple[str, str]] | Sequence[Evidence],
    *,
    encoder: Encoder,
    k: int = 1,
    locale: str = "und",
    max_anchors: int = 2048,
) -> Proofread

Score one answer against its sources and return where to look. This is the function the rest of the library exists to serve.

Parameters

Returns

A Proofread. There is no verdict in it and no threshold on it.

Raises

• TypeError if a context item is not a string, an (id, text) pair or an Evidence.
• ValueError if the answer exceeds max_anchors scoring words, or if locale is not a known name.
• RuntimeError if a word aligns to no encoder token, which means the encoder adapter is broken. It refuses rather than continues, because a silently dropped word can only push the floor up and make a truncated answer look better grounded than it is.

Notes

Passing no context at all is not an error. Every word then reads as unsupported, which is the correct result, and a warning saying so is attached to Proofread.warnings.

functiongroundlens.adaptive_k(n)

adaptive_k(n: int) -> int
# max(1, min(4, ceil(0.15 * n)))

How many weakest anchors to use for an answer of n scoring words: one weak word decides a short answer, up to four decide a long one. Selected by passing k=0 to proofread(). Call it directly only if you want the number before you score.

functiongroundlens.calibrate(…)

calibrate(
    labelled: Sequence[tuple[Proofread | float, bool]],
    *,
    target_recall: float = 0.95,
    seed: int = 0,
    min_labelled: int = 200,
) -> OperatingPoint

Fit a threshold on your own labelled data and hand back what it costs. This library ships no threshold, and this function is the only supported way to get one.

Parameters

Returns

An OperatingPoint carrying the threshold and the measured false-positive rate with a bootstrap 95% interval.

Raises

• ValueError if target_recall is outside (0, 1].
• ValueError if fewer than min_labelled examples are supplied.
• ValueError if the data contains no defects, or no clean examples.

Example

from groundlens import calibrate

point = calibrate(labelled, target_recall=0.95)
print(point.threshold, point.fpr, point.fpr_ci95)   # read the fpr first

Result classes

All of these are frozen dataclasses with slots. They are values, not handles: nothing mutates after proofread() returns.

classgroundlens.Proofread

The result of scoring one answer against its sources.

Methods

classgroundlens.Anchor

One word of the answer and the best support it found in the sources.

Methods

classgroundlens.OperatingPoint

A threshold measured on your own labelled data, with its cost attached. Returned by calibrate().

Input classes

classgroundlens.Evidence

One retrieved source, with an id so findings can point at it. Construct these yourself when you want explicit typing; (id, text) tuples are converted into them internally.

Encoders

protocolgroundlens.Encoder

The one thing Groundlens needs from a model. It is a runtime-checkable Protocol, so any object with these four members satisfies it and no inheritance is required. Implement it to score words with your own retrieval encoder, which makes the check agree with the retrieval that produced the answer.

classgroundlens.WindowEncoding

What an Encoder returns for one window of text.

classgroundlens.SentenceTransformerEncoder

SentenceTransformerEncoder(
    model: str = "sentence-transformers/all-mpnet-base-v2",
    *,
    revision: str | None = None,
    device: str | None = None,
    max_tokens: int | None = None,
)

The reference encoder, behind the [encoder] extra. Importing groundlens never imports torch; only constructing this class does.

Attributes

Raises

• ImportError at construction if the [encoder] extra is not installed. The message names the install command.

Type aliases

Note codes

groundlens.NOTE_CODES is a frozenset of every code that can appear in Anchor.notes. The set is closed on purpose so you can assert on it.

Locales

The locale argument tells the numeral channel how this corpus writes numbers. It is read from the argument and never from LC_ALL, so the same input gives the same result on any machine.

An unknown name raises ValueError listing the known ones.

Constants

Command line

Installing the package puts a groundlens command on your path. It has one subcommand. groundlens --help works without the [encoder] extra installed, because it does not import torch.

groundlens read --answer ANSWER --context CONTEXT [--context CONTEXT ...]
                [--k K] [--locale LOCALE] [--model MODEL] [--json]

Example

groundlens read \
  --answer answer.txt \
  --context policy.pdf#p3=policy.txt \
  --locale es --k 2

Warnings go to stderr and the report to stdout. The exit code is 0 on a successful check; the command does not signal a verdict through its exit code, because there is no verdict.

MCP server

Groundlens ships an MCP server so Claude Desktop, Claude Code, Cursor, VS Code or any other MCP client can run the check inside the conversation. It speaks stdio and runs locally. No text leaves the machine.

pip install "groundlens[encoder,mcp]"
python -m groundlens.mcp

Client configuration, in claude_desktop_config.json or the equivalent mcp.json:

{
  "mcpServers": {
    "groundlens": {
      "command": "python",
      "args": ["-m", "groundlens.mcp"]
    }
  }
}

Use the absolute path to the Python that has Groundlens installed if it is not the one on your PATH.

toolfind_unsupported_words

One tool. If a second ever looks necessary, the product has stopped being one thing.

Returns

The encoder is constructed on the first call rather than at startup, so the server completes the handshake and answers tools/list with no model on disk.

Exceptions

Groundlens defines no exception classes of its own. It raises built-ins, and each one means something specific.

Limitations

• Computed values. It cannot check "revenue tripled" against a source saying revenue went from 5M to 15M.
• Attachment. The word channel checks whether a word is supported, not whether it is attached to the right thing. If an answer says "payable in 30 days" about invoice A and the 30 days belong to invoice B elsewhere in the same context, the word is supported and no mark appears.
• Reasoning. It cannot check an inference. That belongs to entailment models.
• Retrieval. It inherits yours. If the passage is wrong, so is the answer's grounding.
• Segmentation. It assumes space-delimited scripts, and warns rather than pretending when the text is largely CJK or Thai.