# pllm.research Python API

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

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

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

The research registry exposes locked paper sources, clean-room method records, evidence requirements, and promotion assessments without executing quarantined upstream artifacts. 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.research as research

lock = research.ArtifactLock(
    id="slalom-upstream",
    source_record_id="R07",
    revision="a" * 40,
    artifact_digest="b" * 64,
    license_review="external_reproduction_only",
    isolation="external_process",
)
assert lock.verify(evidence_digest="c" * 64).status == "reproduction_verified"
```

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

## Objects and signatures

### `ArtifactLock`

Immutable `ArtifactLock` record carrying `id`, `source_record_id`, `revision`, `artifact_digest`, `license_review`, `isolation`, `repository_url`, `status`, `evidence_digest` for the workflow where the research registry exposes locked paper sources, clean-room method records, evidence requirements, and promotion assessments without executing quarantined upstream artifacts.

- Canonical object: `pllm.research.ArtifactLock`
- Kind: `class`
- Signature/type: `__init__(self, id: str, source_record_id: str, revision: str, artifact_digest: str \| None, license_review: str, isolation: str, repository_url: str \| None=None, status: str='quarantined', evidence_digest: str \| None=None) -> None`
- Public exports: `pllm.ArtifactLock`, `pllm.research.ArtifactLock`
- Public members: `id: str`; `source_record_id: str`; `revision: str`; `artifact_digest: str \| None`; `license_review: str`; `isolation: str`; `repository_url: str \| None`; `status: str`; `evidence_digest: str \| None`; `__init__(self, id: str, source_record_id: str, revision: str, artifact_digest: str \| None, license_review: str, isolation: str, repository_url: str \| None=None, status: str='quarantined', evidence_digest: str \| None=None) -> None`; `property digest: str`; `canonical_bytes(self) -> bytes`; `to_dict(self) -> dict[str, Any]`; `classmethod from_dict(cls, document: Mapping[str, Any]) -> ArtifactLock`; `lock_artifact(self, *, artifact_digest: str) -> ArtifactLock`; `verify(self, *, evidence_digest: str) -> ArtifactLock`; `reject(self, *, evidence_digest: str) -> ArtifactLock`

### `MethodRecord`

Opaque immutable `MethodRecord` record created by its public factories for the workflow where the research registry exposes locked paper sources, clean-room method records, evidence requirements, and promotion assessments without executing quarantined upstream artifacts.

- Canonical object: `pllm.research.MethodRecord`
- Kind: `class`
- Signature/type: `constructor not exposed`
- Public exports: `pllm.MethodRecord`, `pllm.research.MethodRecord`
- Public members: `classmethod from_dict(cls, document: Mapping[str, Any]) -> MethodRecord`; `property id: str`; `property digest: str`; `canonical_bytes(self) -> bytes`; `to_dict(self) -> dict[str, Any]`

### `PromotionDecision`

Immutable `PromotionDecision` record carrying `method_id`, `eligible`, `blockers` for the workflow where the research registry exposes locked paper sources, clean-room method records, evidence requirements, and promotion assessments without executing quarantined upstream artifacts.

- Canonical object: `pllm.research.PromotionDecision`
- Kind: `class`
- Signature/type: `constructor not exposed`
- Public exports: `pllm.PromotionDecision`, `pllm.research.PromotionDecision`
- Public members: `method_id: str`; `eligible: bool`; `blockers: tuple[str, ...]`

### `ResearchRegistry`

Opaque immutable `ResearchRegistry` record created by its public factories for the workflow where the research registry exposes locked paper sources, clean-room method records, evidence requirements, and promotion assessments without executing quarantined upstream artifacts.

- Canonical object: `pllm.research.ResearchRegistry`
- Kind: `class`
- Signature/type: `__init__(self, *, sources: Iterable[SourceRecord]=..., methods: Iterable[MethodRecord]=..., artifacts: Iterable[ArtifactLock]=...) -> None`
- Public exports: `pllm.ResearchRegistry`, `pllm.research.ResearchRegistry`
- Public members: `__init__(self, *, sources: Iterable[SourceRecord]=..., methods: Iterable[MethodRecord]=..., artifacts: Iterable[ArtifactLock]=...) -> None`; `sources(self) -> tuple[SourceRecord, ...]`; `methods(self) -> tuple[MethodRecord, ...]`; `artifacts(self) -> tuple[ArtifactLock, ...]`; `source(self, identity: str) -> SourceRecord`; `method(self, identity: str) -> MethodRecord`; `artifact(self, identity: str) -> ArtifactLock`; `promotion(self, method_id: str) -> PromotionDecision`

### `SourceRecord`

Opaque immutable `SourceRecord` record created by its public factories for the workflow where the research registry exposes locked paper sources, clean-room method records, evidence requirements, and promotion assessments without executing quarantined upstream artifacts.

- Canonical object: `pllm.research.SourceRecord`
- Kind: `class`
- Signature/type: `constructor not exposed`
- Public exports: `pllm.SourceRecord`, `pllm.research.SourceRecord`
- Public members: `classmethod from_dict(cls, document: Mapping[str, Any]) -> SourceRecord`; `property id: str`; `property digest: str`; `canonical_bytes(self) -> bytes`; `to_dict(self) -> dict[str, Any]`