# pllm.models Python API

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

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

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

Model APIs separate semantic architecture lowering from checkpoint import so a plan can be reviewed before weights or runtime state exist. 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.models as pllm

config = {
    "model_type": "qwen2",
    "hidden_size": 16,
    "intermediate_size": 32,
    "num_hidden_layers": 1,
    "num_attention_heads": 4,
    "num_key_value_heads": 2,
    "vocab_size": 64,
    "max_position_embeddings": 128,
    "hidden_act": "silu",
    "rope_theta": 10000.0,
    "rms_norm_eps": 1e-6,
    "tie_word_embeddings": False,
    "attention_bias": True,
}
plan = pllm.lower_model(config, batch=1, max_input_tokens=8, max_new_tokens=2)
assert plan.to_dict()["model_family"] == "qwen2"
```

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

## Objects and signatures

### `load_model`

Resolves and imports a model source while recording path-independent checkpoint hashes.

- Canonical object: `pllm.model_loader.load_model`
- Kind: `function`
- Signature/type: `load_model(value: Model \| str \| Mapping[str, Any], *, token: str \| bool \| None=None, cache_dir: str \| Path \| None=None, api_key: str \| None=None) -> ModelManifest`
- Public exports: `pllm.load_model`, `pllm.models.load_model`

### `DecoderCoverageReport`

Compiler coverage that distinguishes primitives from executable operators.

- Canonical object: `pllm.modeling.DecoderCoverageReport`
- Kind: `class`
- Signature/type: `not publicly constructible`
- Public exports: `pllm.DecoderCoverageReport`, `pllm.models.DecoderCoverageReport`
- Public members: `canonical_bytes(self) -> 'bytes'`; `property complete: 'bool'`; `property operators: 'tuple[Mapping[str, Any], ...]'`; `to_dict(self) -> 'dict[str, Any]'`

### `DecoderRuntimeSchedule`

Opaque immutable `DecoderRuntimeSchedule` record created by its public factories for the workflow where model apis separate semantic architecture lowering from checkpoint import so a plan can be reviewed before weights or runtime state exist.

- Canonical object: `pllm.modeling.DecoderRuntimeSchedule`
- Kind: `class`
- Signature/type: `not publicly constructible`
- Public exports: `pllm.DecoderRuntimeSchedule`, `pllm.models.DecoderRuntimeSchedule`
- Public members: `canonical_bytes(self) -> 'bytes'`; `property complete: 'bool'`; `property composition_digest: 'str'`; `property decode: 'Mapping[str, Any]'`; `property digest: 'str'`; `property prefill: 'Mapping[str, Any]'`; `property protected_execution: 'bool'`; `to_dict(self) -> 'dict[str, Any]'`

### `ModelPlan`

Immutable bounded semantic graph produced by a model-family adapter.

- Canonical object: `pllm.modeling.ModelPlan`
- Kind: `class`
- Signature/type: `not publicly constructible`
- Public exports: `pllm.ModelPlan`, `pllm.models.ModelPlan`
- Public members: `apply(self, component: "'ComponentRef'") -> "'ModelPlan'"`; `canonical_bytes(self) -> 'bytes'`; `coverage(self, composition: "'Pipeline \| None'" = None) -> "'DecoderCoverageReport'"`; `property decode: 'Mapping[str, Any]'`; `property digest: 'str'`; `property prefill: 'Mapping[str, Any]'`; `runtime_schedule(self, composition: "'Pipeline'") -> "'DecoderRuntimeSchedule'"`; `to_dict(self) -> 'dict[str, Any]'`

### `lower_model`

Lower a supported Hugging Face model config without loading weights.

- Canonical object: `pllm.modeling.lower_model`
- Kind: `function`
- Signature/type: `(config: 'Mapping[str, Any] \| bytes \| str', *, batch: 'int', max_input_tokens: 'int', max_new_tokens: 'int') -> 'ModelPlan'`
- Public exports: `pllm.lower_model`, `pllm.models.lower_model`

### `ModelLoadError`

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

- Canonical object: `pllm.runtime.loaders.ModelLoadError`
- Kind: `class`
- Signature/type: `signature not exposed`
- Public exports: `pllm.ModelLoadError`, `pllm.models.ModelLoadError`

### `ModelManifest`

Immutable `ModelManifest` record carrying `id`, `architecture`, `source_format`, `source`, `vocab_size`, `hidden_size`, `intermediate_size`, `num_hidden_layers`, `num_attention_heads`, `num_key_value_heads`, `head_dim`, `context_length`, `tokenizer_path`, `chat_template`, `quantization`, `tied_embeddings`, `stages`, `metadata`, `created_at` for the workflow where model apis separate semantic architecture lowering from checkpoint import so a plan can be reviewed before weights or runtime state exist.

- Canonical object: `pllm.runtime.models.ModelManifest`
- Kind: `class`
- Signature/type: `(id: 'str', architecture: 'str', source_format: 'str', source: 'str', vocab_size: 'int', hidden_size: 'int', intermediate_size: 'int', num_hidden_layers: 'int', num_attention_heads: 'int', num_key_value_heads: 'int', head_dim: 'int', context_length: 'int', tokenizer_path: 'str \| None' = None, chat_template: 'str \| None' = None, quantization: 'dict[str, Any] \| None' = None, tied_embeddings: 'bool' = False, stages: 'list[StageSpec]' = , metadata: 'dict[str, Any]' = , created_at: 'float' = ) -> None`
- Public exports: `pllm.ModelManifest`, `pllm.models.ModelManifest`
- Public members: `classmethod from_dict(cls, value: 'dict[str, Any]') -> "'ModelManifest'"`; `classmethod load(cls, path: 'str \| Path') -> "'ModelManifest'"`; `property checkpoint_digest: 'str \| None'`; `property fingerprint: 'str'`; `property source_lock_digest: 'str \| None'`; `save(self, path: 'str \| Path') -> 'None'`; `to_dict(self, *, include_fingerprint: 'bool' = True) -> 'dict[str, Any]'`