# pllm.config Python API

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

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

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

Immutable configuration records describe experiments before any checkpoint, network connection, credential, or one-use material is opened. 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.config as pllm
from pllm.kernels import Cpu
from pllm.profiles import MaskedLinearCpu

experiment = pllm.Experiment(
    name="qwen-local",
    pipeline=MaskedLinearCpu(
        pllm.Model("Qwen/Qwen2.5-0.5B-Instruct"),
        kernels=Cpu(threads=2),
    ),
    deployment=pllm.Deployment.local(root=".pllm/qwen-local"),
    budget=pllm.ExecutionBudget(requests=1, max_input_tokens=32, max_new_tokens=8),
)
assert len(pllm.configuration_digest(experiment)) == 64
```

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

## Objects and signatures

### `ComponentRef`

Immutable `ComponentRef` record carrying `component`, `params` for the workflow where immutable configuration records describe experiments before any checkpoint, network connection, credential, or one-use material is opened.

- Canonical object: `pllm.configuration.ComponentRef`
- Kind: `class`
- Signature/type: `__init__(self, component: str, params: Mapping[str, Any] \| None=None) -> None`
- Public exports: `pllm.ComponentRef`, `pllm.components.ComponentRef`, `pllm.config.ComponentRef`
- Public members: `component: str`; `params: Mapping[str, Any]`; `__init__(self, component: str, params: Mapping[str, Any] \| None=None) -> None`; `classmethod from_params(cls, params: Mapping[str, Any]) -> ComponentRef`; `get_params(self, deep: bool=True) -> dict[str, Any]`; `with_params(self, **changes: object) -> Self`; `to_spec(self) -> dict[str, Any]`

### `ConfigurationError`

Raised when a Configuration condition prevents the requested operation from completing.

- Canonical object: `pllm.configuration.ConfigurationError`
- Kind: `class`
- Signature/type: `constructor not exposed`
- Public exports: `pllm.ConfigurationError`, `pllm.config.ConfigurationError`

### `Deployment`

Immutable `Deployment` record carrying `kind`, `root` for the workflow where immutable configuration records describe experiments before any checkpoint, network connection, credential, or one-use material is opened.

- Canonical object: `pllm.configuration.Deployment`
- Kind: `class`
- Signature/type: `__init__(self, kind: str, root: str) -> None`
- Public exports: `pllm.Deployment`, `pllm.config.Deployment`, `pllm.deployment.Deployment`
- Public members: `kind: str`; `root: str`; `__init__(self, kind: str, root: str) -> None`; `classmethod local(cls, *, root: str) -> Self`; `get_params(self, deep: bool=True) -> dict[str, Any]`; `with_params(self, **changes: object) -> Self`; `to_spec(self) -> dict[str, Any]`

### `ExecutionBudget`

Immutable `ExecutionBudget` record carrying `requests`, `max_input_tokens`, `max_new_tokens` for the workflow where immutable configuration records describe experiments before any checkpoint, network connection, credential, or one-use material is opened.

- Canonical object: `pllm.configuration.ExecutionBudget`
- Kind: `class`
- Signature/type: `__init__(self, requests: int, max_input_tokens: int, max_new_tokens: int) -> None`
- Public exports: `pllm.ExecutionBudget`, `pllm.config.ExecutionBudget`, `pllm.runtime.ExecutionBudget`
- Public members: `requests: int`; `max_input_tokens: int`; `max_new_tokens: int`; `__init__(self, requests: int, max_input_tokens: int, max_new_tokens: int) -> None`; `get_params(self, deep: bool=True) -> dict[str, Any]`; `with_params(self, **changes: object) -> Self`; `to_spec(self) -> dict[str, Any]`

### `Experiment`

Immutable `Experiment` record carrying `name`, `pipeline`, `deployment`, `budget` for the workflow where immutable configuration records describe experiments before any checkpoint, network connection, credential, or one-use material is opened.

- Canonical object: `pllm.configuration.Experiment`
- Kind: `class`
- Signature/type: `__init__(self, name: str, pipeline: Pipeline, deployment: Deployment, budget: ExecutionBudget) -> None`
- Public exports: `pllm.Experiment`, `pllm.config.Experiment`, `pllm.pipeline.Experiment`
- Public members: `name: str`; `pipeline: Pipeline`; `deployment: Deployment`; `budget: ExecutionBudget`; `__init__(self, name: str, pipeline: Pipeline, deployment: Deployment, budget: ExecutionBudget) -> None`; `classmethod from_spec(cls, spec: Mapping[str, Any], *, providers: Iterable[ProviderDescriptor]=...) -> Self`; `classmethod from_file(cls, path: str \| Path, *, providers: Iterable[ProviderDescriptor]=...) -> Self`; `get_params(self, deep: bool=True) -> dict[str, Any]`; `with_params(self, **changes: object) -> Self`; `to_spec(self) -> dict[str, Any]`; `canonical_bytes(self) -> bytes`; `configuration_digest(self) -> str`; `resolve(self) -> ExperimentProfile`

### `ExperimentProfile`

Immutable runtime resolution of one component composition.

- Canonical object: `pllm.configuration.ExperimentProfile`
- Kind: `class`
- Signature/type: `__init__(self, experiment: Experiment) -> None`
- Public exports: `pllm.ExperimentProfile`, `pllm.config.ExperimentProfile`
- Public members: `model: str`; `canonical_composition: bytes`; `composition_digest: str`; `configuration_digest: str`; `profile: str \| None`; `privacy_mode: str`; `proprietary_protocol: str`; `requires_preparation: bool`; `client_runtime: str`; `privacy_protocol: str \| None`; `verification_component: str \| None`; `verification_target_failure_bits: int`; `__init__(self, experiment: Experiment) -> None`

### `Model`

Immutable `Model` record carrying `source`, `kind`, `model_id`, `revision`, `local_files_only`, `endpoint` for the workflow where immutable configuration records describe experiments before any checkpoint, network connection, credential, or one-use material is opened.

- Canonical object: `pllm.configuration.Model`
- Kind: `class`
- Signature/type: `__init__(self, source: str, *, kind: str='huggingface', model_id: str \| None=None, revision: str \| None=None, local_files_only: bool=False, endpoint: str \| None=None) -> None`
- Public exports: `pllm.Model`, `pllm.config.Model`
- Public members: `source: str`; `kind: str`; `model_id: str \| None`; `revision: str \| None`; `local_files_only: bool`; `endpoint: str \| None`; `__init__(self, source: str, *, kind: str='huggingface', model_id: str \| None=None, revision: str \| None=None, local_files_only: bool=False, endpoint: str \| None=None) -> None`; `classmethod hf(cls, repo_id: str, *, model_id: str \| None=None, revision: str \| None=None, local_files_only: bool=False) -> Model`; `classmethod path(cls, path: str, *, format: str='huggingface', model_id: str \| None=None) -> Model`; `classmethod tiny(cls, name: str='qwen2', *, model_id: str \| None=None) -> Model`; `classmethod ollama(cls, name: str, *, endpoint: str='http://127.0.0.1:11434', model_id: str \| None=None) -> Model`; `classmethod from_spec(cls, value: Mapping[str, Any]) -> Model`; `get_params(self, deep: bool=True) -> dict[str, Any]`; `with_params(self, **changes: object) -> Self`; `to_spec(self) -> dict[str, Any]`; `canonical_bytes(self) -> bytes`; `digest(self) -> str`; `to_runtime_spec(self) -> dict[str, Any]`

### `Pipeline`

Immutable `Pipeline` record carrying `model`, `components`, `profile` for the workflow where immutable configuration records describe experiments before any checkpoint, network connection, credential, or one-use material is opened.

- Canonical object: `pllm.configuration.Pipeline`
- Kind: `class`
- Signature/type: `__init__(self, model: Model, components: Mapping[str, ComponentRef], profile: str \| None=...) -> None`
- Public exports: `pllm.Pipeline`, `pllm.config.Pipeline`, `pllm.pipeline.Pipeline`
- Public members: `model: Model`; `components: Mapping[str, ComponentRef]`; `profile: str \| None`; `__init__(self, model: Model, components: Mapping[str, ComponentRef], profile: str \| None=...) -> None`; `classmethod from_profile(cls, profile: str, *, model: Model, components: Mapping[str, ComponentRef]) -> Self`; `classmethod from_spec(cls, value: Mapping[str, Any], *, providers: Iterable[ProviderDescriptor]=...) -> Pipeline`; `get_params(self, deep: bool=True) -> dict[str, Any]`; `with_params(self, **changes: object) -> Self`; `to_spec(self) -> dict[str, Any]`; `canonical_bytes(self) -> bytes`; `digest(self) -> str`

### `canonical_bytes`

Return deterministic UTF-8 JSON bytes for a supported public specification.

- Canonical object: `pllm.configuration.canonical_bytes`
- Kind: `function`
- Signature/type: `canonical_bytes(configuration: Experiment \| Mapping[str, Any], *, providers: Iterable[ProviderDescriptor]=...) -> bytes`
- Public exports: `pllm.canonical_bytes`, `pllm.config.canonical_bytes`

### `configuration_digest`

Return domain-separated SHA-256 identity for public configuration.

- Canonical object: `pllm.configuration.configuration_digest`
- Kind: `function`
- Signature/type: `configuration_digest(configuration: Experiment \| Mapping[str, Any], *, providers: Iterable[ProviderDescriptor]=...) -> str`
- Public exports: `pllm.config.configuration_digest`, `pllm.configuration_digest`

### `load_configuration`

Read and parse one experiment file; constructors themselves perform no I/O.

- Canonical object: `pllm.configuration.load_configuration`
- Kind: `function`
- Signature/type: `load_configuration(path: str \| Path, *, providers: Iterable[ProviderDescriptor]=...) -> Experiment`
- Public exports: `pllm.config.load_configuration`, `pllm.load_configuration`

### `loads_configuration`

Parse one strict JSON or safe YAML experiment document.

- Canonical object: `pllm.configuration.loads_configuration`
- Kind: `function`
- Signature/type: `loads_configuration(text: str, *, format: str \| None=None, providers: Iterable[ProviderDescriptor]=...) -> Experiment`
- Public exports: `pllm.config.loads_configuration`, `pllm.loads_configuration`