Evidence collection and JSON reports

The evidence-provider contract

An evidence provider implements one asynchronous method. EvidenceRequest carries the incident, requested kinds, item and character budgets, and an explicit redaction flag; EvidenceCollection carries evidence, safe structured failures, and a truncation signal.

from typing import Protocol

from lumis_sdk.domain import EvidenceCollection, EvidenceRequest


class EvidenceProvider(Protocol):
    name: str

    async def collect(self, request: EvidenceRequest) -> EvidenceCollection: ...

Collect through EvidenceService

Always collect at an application boundary through EvidenceService, so provider output receives consistent timeout, kind filtering, duplicate-ID handling, redaction, per-item limits, and total-size limits regardless of which provider is behind the port:

import asyncio

from lumis_sdk.application import EvidenceService
from lumis_sdk.domain import EvidenceCollection, EvidenceRequest
from lumis_sdk.testkit import (
    FakeEvidenceProvider,
    make_test_evidence,
    make_test_incident,
)

request = EvidenceRequest(
    incident=make_test_incident(),
    kinds=["log_window", "schema_diff"],
    max_items=20,
    max_total_characters=100_000,
    max_item_characters=8_000,
    redact=True,
)
provider = FakeEvidenceProvider(
    EvidenceCollection(provider="fixture", items=[make_test_evidence()])
)
collection = asyncio.run(EvidenceService(provider).collect(request))

Provider exceptions and timeouts are represented as EvidenceFailure values—they are never silently treated as empty successful evidence.

Versioned JSON reports

Set spec.reports.provider to json and lumis diagnose writes a stable lumis.dev/v1 DiagnosisReport: normalized incident input, structured diagnosis and triage, facts, evidence, hypothesis, confidence, missing evidence, recommended next steps, suggested playbook, explicit truth state, and an optional human-confirmed resolution. The checked schema ships in the repository for downstream consumers.

from lumis_sdk.adapters.reports import (
    JsonReportWriter,
    parse_json_report,
    render_json_report,
)

Reusable testkit

from lumis_sdk.testkit import (
    FakeEvidenceProvider,
    assert_evidence_collection_contract,
    assert_json_report_round_trip,
    make_test_evidence,
    make_test_incident,
)

These helpers depend only on Lumis SDK and Python—no live service, credentials, model call, or pytest runtime dependency—so third-party adapters can prove the same collection and round-trip behavior the reference adapters do.

Safety boundary

Evidence remains untrusted data even after collection. Redaction is a conservative baseline, not a substitute for provider-side minimization and access control. Evidence providers do not gain execution authority, and JSON reports do not authorize a suggested playbook.