Evidence

Marivo is a pure Python analysis library. It does not use an LLM, decide what a business result means, or choose the next analysis step. Its evidence engine makes deterministic operator results cheaper to read and easier to audit.

The evidence model

Each committed operator result follows one path:

artifact -> typed findings -> bounded artifact digest

A Finding is a typed extraction from one artifact. An ArtifactDigest is an operator-specific projection of those findings for the immediate read. The agent remains responsible for combining artifacts, judging business impact, and deciding what to execute next.

The digest never upgrades contribution into cause, correlation into effect, a candidate into a confirmed anomaly, a statistical test into business importance, or a forecast into an observed outcome. Explicit boundaries state which inference the operator did not support.

Read the immediate result

Use one structured path:

result = session.compare(current, baseline)

print(result.evidence_status)
digest = result.evidence_digest
result.show()

evidence_status is complete, partial, or unavailable. evidence_digest is the immutable commit-time ArtifactDigest, or None when it could not be produced. show() renders that same bounded digest before the data preview.

A digest contains at most five typed items and three inference boundaries. Its omissions reports discarded item counts, and fallback tells you whether exact findings and raw rows are available. Absence from a bounded digest does not mean absence from the artifact.

The main item types match operator semantics:

Operator	Digest item	Meaning
observe	ObservationFact	observed value or distribution summary
compare	ChangeFact	algebraic change
attribute	ContributionFact	algebraic contribution, not cause
correlate	AssociationFact	estimated association, not cause
hypothesis_test	TestDecision	decision under the declared statistical test
forecast	ForecastOutput	prediction, not observed actual
discover.*	AnomalyCandidate	candidate requiring review
assess_quality	QualityCheckResult	evaluated quality predicate
transform.* / MetricFrame.metric(...)	empty digest	lineage-preserving transformation or projection only

Inspect limits and exact evidence

If the question needs omitted items, row-level validation, or evidence outside the operator’s inference boundary, follow the digest’s exact-read contract:

digest = session.evidence.digest(result.ref)
findings = session.evidence.findings(artifact_ref=result.ref, limit=50)
frame = session.get_frame(result.ref)

for finding in findings.items:
    print(finding.finding_type, finding.value)

Trace one finding back to its declared source fields and retained digest items:

trace = session.evidence.trace(findings.items[0].finding_id)
print(trace.derivation.rule_id, trace.source_fields)

The trace is an audit record, not a system-generated claim or judgment.

Recover a session with bounded pages

List reads are bounded and newest-first:

frames = session.frame_summaries(limit=20)
digests = session.evidence.digests(limit=10)
findings = session.evidence.findings(limit=50)

if digests.has_more:
    digests = session.evidence.digests(
        limit=10,
        cursor=digests.next_cursor,
    )

Pages expose immutable items, limit, has_more, and next_cursor. They use ordinary keyset paging, not snapshot isolation; a new commit between page reads may change the newest edge. Treat cursors as opaque continuation tokens.

If the evidence store is unavailable, list and exact reads raise EvidenceStoreUnavailableError. An empty page means the healthy store matched no records.

Issues and repair

result.contract().issues contains closed typed issues:

• DataQualityIssue for evaluated quality failures;
• ComparabilityIssue for incompatible or approximate comparisons;
• EvidenceAvailabilityIssue for extraction, digest, or store degradation.

The current cutover is destructive: non-v3 evidence stores and frame sidecars containing removed evidence fields are rejected. Recreate the analysis session; Marivo does not migrate or reinterpret judgment-era state.

An issue may carry AnalysisRepair, which explains how to retry the failing capability. Repair is local error recovery; it is not a persisted follow-up plan. The agent chooses whether and how to continue.

Review a conclusion

Check three things:

1. The result uses the intended metric, scope, and comparison.
2. Every material claim is supported by an artifact or typed evidence item.
3. The conclusion respects omissions, quality issues, and inference boundaries.

If the metric definition is wrong, stop and repair it through marivo-semantic. More analysis cannot compensate for the wrong business contract. See Analysis Workflow for the typed operator loop.