EvidPort evidence library integration¶
EvidPort is the independent evidence layer.
Its existing distribution name local-evidence-database, Python module
evidence_database, and evidence-db command remain compatible.
The optional --evidence-library grounder reads an existing independent
local-evidence-database store. It does not download, ingest, convert, or approve
papers. Existing ground, profiles, schemas, and frozen benchmark replays
retain their previous behavior. This public integration adds only the
independent --evidence-library option.
Install and validate¶
From this Validator checkout, install both reviewed packages into the activated
environment, or install their built wheels. The independent library is not assumed
to exist on PyPI. Use the configured store folder when validating; evidence below
is a project-relative example:
python -m pip install -e .
python -m pip install 'local-evidence-database[pdf] @ git+https://github.com/NingyuSUN/evidport.git@fa5ef4bc3db8b7c2ac416a41539ed56ab033b4e2'
bioevidence validate record.json --profile literature-claim \
--evidence-library evidence --output validation.json
Use the independent library's PDF extra when working with PDF review packets.
The library must support Store(root, read_only=True). A missing package, old
package, absent store, or unusable store produces an operational error; the
validator never silently disables this requested check. Validation output must
be outside the library directory.
Accepting machine-verified quotations¶
By default a quotation passes only after a recorded human original-page review. Add
--accept-independent-reading to also accept a quotation that the library reports as
confirmed by an independent OCR reading of the same page region:
bioevidence validate record.json --profile literature-claim \
--evidence-library /path/to/project/store --accept-independent-reading
The validator recomputes this from the read-only library; it does not take a server's word.
Each check in the report carries admission_route (human_review or
independent_reading), and evidence_library.independent_reading_accepted records that the
option was on. A recorded rejection or revocation still blocks the quotation. A library that
predates the route is an operational error, not a silent fallback. Through the MCP bridge
(--accept-independent-reading on bioevidence_validator.evidence_mcp) the server's project
must enable the same route; a disagreement between server and local library blocks admission.
Without the option, a quotation that the server admits by independent reading is not a
disagreement: it stays review_required (BEV015), and its check carries
server_route_not_accepted: independent_reading. Any other admission the local library cannot
confirm is still rejected.
Machine verification settles transcription only and is never reported as human review.
Record contract¶
source_artifacts[].sha256is the exact original PDF hash, not a parsed text hash. Seturito the publication's DOI, PMID, or PMCID URI, andtitleto its pinned title. Metadata-only acquisition candidates have no full-text citation.evidence_items[].locatoris the complete library citation, for exampleevidence:cv_<64 hexadecimal characters>#b000001. Copy it from library output; do not substitute a page number, filename, DOI, or legacy database citation.extracted_textcontains the actual quotation from that block. The library checks numeric boundaries and does not treat related text elsewhere as a match.- Publication identity must have a source-bound acquisition receipt with the
original-file identity check, under rule version 2 or 3, and matching frozen
provider metadata. A check made under any other rule version is not accepted.
Older imports without these receipts remain
review_required; filenames and document IDs alone are insufficient. Parent-paper DOIs do not identify supplementary files. Contradictory identifiers/titles and pinned retractions block admission, including when another grounder accepts the evidence item. - The exact conversion, block, and quotation require a human original-page review in the independent library. AI diagnostics, text matches, inspection mode, or approval of another quotation/version cannot supply this review. Revocations are honored on the next validation. Human identity remains locally self-declared; this is not an authenticated review service.
The adapter calls Store.check(..., require_review=True) unconditionally.
Failures emit findings rather than merely omitting an item from the verified set:
BEV014 for integrity/read failures, BEV015 for unavailable identity or review,
BEV017 for source/identifier/title/quotation disagreement, and BEV019 for pinned
retraction evidence. Existing CLI exit codes remain 0 admitted, 1 rejected,
2 review required, and 3 operational error.
Warnings, provenance, and replay¶
When this flag is used, the report adds an evidence_library.checks receipt for
each checked evidence item: exact citation and quotation, source hash, conversion,
original-page locator, parser/version, conversion and block warnings, and the
specific review ID/status where available. A reviewed quotation from a partial
conversion can pass its specific extraction gate; partial-conversion warnings
remain visible. Admission does not establish the correctness of the whole
conversion, scientific support, or clinical validity.
Python callers can instantiate EvidenceLibraryGrounder(path) and pass it in
validate_record(..., grounders=[grounder]). Its last_checks contains the most
recent evaluation receipts. Library imports are lazy; ordinary validation does
not require the optional package.
The check is offline and uses frozen provider metadata. It does not claim to
detect retractions published after acquisition. It does not rerun parsers: the
stored original, conversion, native artifacts, indexes, and quote-specific
review packet are checked by the library. Preserve the exact library snapshot,
record, report, and installed package versions to replay a decision. New review
events intentionally change a validation of the live store. Historical benchmark
snapshots and tools/reproduce.py are not migrated or rewritten by this adapter.
No real-paper reviews are created by the integration or its tests. Positive approval/revocation tests use explicitly synthetic PDFs and reviewers only.