Evidence Index

The evidence index makes routine metadata queries fast and bounded. It is a rebuildable SQLite projection of portable TrialRecord files. The record JSON, run manifest, and referenced artefact bytes remain the evidence authority.

Build the index

Rebuild the index from a portable evidence root:

uv run aec-bench evidence index rebuild \
  --ledger-root artefacts/ledger \
  --database artefacts/ledger/evidence-index.sqlite

The command rebuilds the index from validated portable records and their manifests. Its report identifies unreadable or conflicting records alongside the indexed count and rebuild generation, so you can investigate errors before querying the results.

The index stores metadata such as:

• trial, run, and experiment identities;
• task identity, revision, kind, and world profile;
• dataset, adapter, model, attempt, reward, and status values;
• start and completion times;
• provider-evidence presence; and
• the portable record path and SHA-256.

Query metadata in Python

Use EvidenceQuery for bounded pages. The query reads index rows and returns portable record paths for a later evidence read.

from pathlib import Path

from aec_bench.ledger import EvidenceIndex, EvidenceQuery

index = EvidenceIndex(Path("artefacts/ledger/evidence-index.sqlite"))
query = EvidenceQuery(index)
filters = {
    "task_prefix": "electrical/",
    "execution_status": "completed",
    "provider_evidence_missing": True,
}
page = query.page(
    page_size=100,
    **filters,
)

for row in page.rows:
    print(row.trial_id, row.record_path, row.reward)

if page.next_cursor is not None:
    next_page = query.page(
        page_size=100,
        after_cursor=page.next_cursor,
        **filters,
    )

Use EvidenceQuery.page() to narrow a query by:

Each page contains at most 1,000 rows. Cursors bind the filters to the current index generation, so start a new query after rebuilding the index.

The query page returns bounded metadata rows and portable record paths. Use record_path to load the selected portable evidence record for detailed review.

Verify portable evidence

Run an explicit verification pass over structured records and referenced artefact bytes:

uv run aec-bench evidence verify --ledger-root artefacts/ledger
uv run aec-bench evidence verify --run <run-id> --ledger-root artefacts/ledger

The report counts records, receipts, finalizations, and artefacts, and lists validation errors. Verification reads current portable evidence and reports its findings.

See Review and Reporting for how verified trial records enter review and reporting workflows.