# pllm.passes Python API

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

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

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

Graph passes transform semantic plans under explicit state and lifecycle contracts rather than rewriting adapter-specific operation names. Presence documents API availability, not complete model, security, or deployment coverage; check [implementation status](/sdk/reference/status/) before relying on a path.

## Research context

Relevant design inputs: [MPCache](/research/papers/r23-mpcache/). PLLM's implementation and evidence claims remain independent.

## 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.passes as passes
cache = passes.KvCacheEviction(cluster_sizes=(32, 16), share_adjacent_layers=True)
assert cache.get_params()["implementation"] == "pllm/importance-kv-cache-eviction/v1"
```

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

## Objects and signatures

### `KvCacheEviction`

Selects component `pllm/kv-cache-eviction` during `model-lowering`; it provides `bounded-kv-cache-eviction`.

- Canonical object: `pllm.passes.KvCacheEviction`
- Kind: `class`
- Signature/type: `__init__(self, *, implementation: str='pllm/importance-kv-cache-eviction/v1', observation_window: tuple[int, int] \| Mapping[str, int]=(1, 5), static_keep: tuple[int, int] \| Mapping[str, int]=(3, 10), dynamic_keep: tuple[int, int] \| Mapping[str, int]=(1, 4), alpha: tuple[int, int] \| Mapping[str, int]=(3, 5), cluster_sizes: Sequence[int]=(32, 16), share_adjacent_layers: bool=True) -> None`
- Public exports: `pllm.KvCacheEviction`, `pllm.passes.KvCacheEviction`
- Public members: `descriptor: ComponentDescriptor`; `__init__(self, *, implementation: str='pllm/importance-kv-cache-eviction/v1', observation_window: tuple[int, int] \| Mapping[str, int]=(1, 5), static_keep: tuple[int, int] \| Mapping[str, int]=(3, 10), dynamic_keep: tuple[int, int] \| Mapping[str, int]=(1, 4), alpha: tuple[int, int] \| Mapping[str, int]=(3, 5), cluster_sizes: Sequence[int]=(32, 16), share_adjacent_layers: bool=True) -> None`; `classmethod describe(cls) -> ComponentDescriptor`

### `PlanPass`

Immutable `PlanPass` record carrying `component`, `params` for the workflow where graph passes transform semantic plans under explicit state and lifecycle contracts rather than rewriting adapter-specific operation names.

- Canonical object: `pllm.passes.PlanPass`
- Kind: `class`
- Signature/type: `constructor not exposed`
- Public exports: `pllm.passes.PlanPass`