# pllm.evidence Python API

Public objects, practical usage, and research context for pllm.evidence.

[View canonical HTML](https://pllm.run/sdk/reference/python/pllm/evidence/)

Document ID: `pllm.docs.reference.python.pllm.evidence`  
Release: `0.1.0`

Evidence records preserve exact benchmark cohorts, environment identity, and assurance results without silently ranking incomparable runs. Presence documents API availability, not complete model, security, or deployment coverage; check [implementation status](/sdk/reference/status/) before relying on a path.

## Research context

This API is project infrastructure rather than an implementation of one specific paper. Relevant method pages link their primary sources separately.

## Python SDK example

The example performs a bounded offline task and checks an observable result. It does not download a checkpoint or contact a provider.

```python
import pllm.evidence as evidence

digest = evidence.environment_digest({"python": "3.13", "machine": "local"})
assert len(digest) == 64 and int(digest, 16) >= 0
```

API: [`pllm.evidence`](/sdk/reference/python/pllm/evidence/#objects-and-signatures)

## Objects and signatures

### `BenchmarkResult`

Opaque immutable `BenchmarkResult` record created by its public factories for the workflow where evidence records preserve exact benchmark cohorts, environment identity, and assurance results without silently ranking incomparable runs.

- Canonical object: `pllm.evidence.BenchmarkResult`
- Kind: `class`
- Signature/type: `not publicly constructible`
- Public exports: `pllm.BenchmarkResult`, `pllm.evidence.BenchmarkResult`
- Public members: `canonical_bytes(self) -> 'bytes'`; `classmethod from_dict(cls, document: 'Mapping[str, Any]') -> 'BenchmarkResult'`; `property data: 'Mapping[str, Any]'`; `property digest: 'str'`; `property id: 'str'`; `to_dict(self) -> 'dict[str, Any]'`

### `EvidenceRegistry`

Opaque immutable `EvidenceRegistry` record created by its public factories for the workflow where evidence records preserve exact benchmark cohorts, environment identity, and assurance results without silently ranking incomparable runs.

- Canonical object: `pllm.evidence.EvidenceRegistry`
- Kind: `class`
- Signature/type: `(results: 'Iterable[BenchmarkResult]' = ()) -> 'None'`
- Public exports: `pllm.EvidenceRegistry`, `pllm.evidence.EvidenceRegistry`
- Public members: `get(self, identity: 'str') -> 'BenchmarkResult'`; `list(self) -> 'tuple[BenchmarkResult, ...]'`; `query(self, *, profile: 'str \| None' = None, component: 'str \| None' = None, model: 'str \| None' = None, environment_digest: 'str \| None' = None, privacy_cohort: 'str \| None' = None, numeric_cohort: 'str \| None' = None, metric: 'str \| None' = None, status: 'str \| None' = None) -> 'tuple[BenchmarkResult, ...]'`; `register(self, result: 'BenchmarkResult') -> 'EvidenceRegistry'`

### `EvidenceReport`

Immutable, canonical benchmark or assurance evidence.

- Canonical object: `pllm.evidence.EvidenceReport`
- Kind: `class`
- Signature/type: `not publicly constructible`
- Public exports: `pllm.EvidenceReport`, `pllm.evidence.EvidenceReport`
- Public members: `canonical_bytes(self) -> 'bytes'`; `property data: 'Mapping[str, Any]'`; `property schema_version: 'str'`; `to_dict(self) -> 'dict[str, Any]'`

### `assure`

Run deterministic native assurance fixtures, including negative controls.

- Canonical object: `pllm.evidence.assure`
- Kind: `function`
- Signature/type: `() -> 'EvidenceReport'`
- Public exports: `pllm.assure`, `pllm.evidence.assure`

### `benchmark`

Benchmark one native compiled region against its scalar oracle.

- Canonical object: `pllm.evidence.benchmark`
- Kind: `function`
- Signature/type: `(plan: 'CompiledPlan', *, weights: 'bytes', input: 'bytes', id: 'str', privacy_cohort: 'str', numeric_cohort: 'str', environment: 'Mapping[str, Any]', warmups: 'int' = 3, repetitions: 'int' = 10, threads: 'int' = 1, simd: 'bool' = True) -> 'EvidenceReport'`
- Public exports: `pllm.benchmark`, `pllm.evidence.benchmark`

### `deployment_benchmark`

Validate deployment observations and return canonical benchmark evidence.

- Canonical object: `pllm.evidence.deployment_benchmark`
- Kind: `function`
- Signature/type: `(request: 'Mapping[str, Any]') -> 'EvidenceReport'`
- Public exports: `pllm.deployment_benchmark`, `pllm.evidence.deployment_benchmark`

### `environment_digest`

Computes a deterministic digest for the exact benchmark environment record.

- Canonical object: `pllm.evidence.environment_digest`
- Kind: `function`
- Signature/type: `(attributes: 'Mapping[str, Any]') -> 'str'`
- Public exports: `pllm.environment_digest`, `pllm.evidence.environment_digest`