# pllm.search Python API

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

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

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

Search APIs generate immutable experiment candidates and compare only cohort-compatible evidence with explicit metric directions. 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
import pllm.search as search
from pllm.kernels import Cpu
from pllm.profiles import MaskedLinearCpu

base = pllm.Experiment(
    name="search-base",
    pipeline=MaskedLinearCpu(pllm.Model("org/model"), kernels=Cpu(threads=1)),
    deployment=pllm.Deployment.local(root="local://search"),
    budget=pllm.ExecutionBudget(requests=1, max_input_tokens=8, max_new_tokens=2),
)
space = search.SearchSpace(base, {"pipeline__kernels__threads": [1, 2]})
assert [candidate.parameters for candidate in search.GridSearch("cpu", space).candidates()] == [
    {"pipeline__kernels__threads": 1},
    {"pipeline__kernels__threads": 2},
]
```

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

## Objects and signatures

### `Constraint`

Immutable `Constraint` record carrying `path`, `operator`, `value` for the workflow where search apis generate immutable experiment candidates and compare only cohort-compatible evidence with explicit metric directions.

- Canonical object: `pllm.search.Constraint`
- Kind: `class`
- Signature/type: `__init__(self, path: str, operator: str, value: Any) -> None`
- Public exports: `pllm.Constraint`, `pllm.search.Constraint`
- Public members: `path: str`; `operator: str`; `value: Any`; `__init__(self, path: str, operator: str, value: Any) -> None`; `accepts(self, experiment: Experiment) -> bool`

### `GridSearch`

Immutable `GridSearch` record carrying `identity`, `space` for the workflow where search apis generate immutable experiment candidates and compare only cohort-compatible evidence with explicit metric directions.

- Canonical object: `pllm.search.GridSearch`
- Kind: `class`
- Signature/type: `__init__(self, identity: str, space: SearchSpace) -> None`
- Public exports: `pllm.GridSearch`, `pllm.search.GridSearch`
- Public members: `identity: str`; `space: SearchSpace`; `__init__(self, identity: str, space: SearchSpace) -> None`; `candidates(self) -> tuple[SearchCandidate, ...]`; `evaluate(self, evaluator: Callable[[SearchCandidate], BenchmarkResult]) -> tuple[SearchEvaluation, ...]`

### `ParetoFrontier`

Immutable `ParetoFrontier` record carrying `objectives` for the workflow where search apis generate immutable experiment candidates and compare only cohort-compatible evidence with explicit metric directions.

- Canonical object: `pllm.search.ParetoFrontier`
- Kind: `class`
- Signature/type: `__init__(self, evaluations: Iterable[SearchEvaluation], *, objectives: Mapping[str, str]) -> None`
- Public exports: `pllm.ParetoFrontier`, `pllm.search.ParetoFrontier`
- Public members: `objectives: Mapping[str, str]`; `__init__(self, evaluations: Iterable[SearchEvaluation], *, objectives: Mapping[str, str]) -> None`; `results(self) -> tuple[SearchEvaluation, ...]`; `excluded(self) -> tuple[SearchEvaluation, ...]`

### `RandomSearch`

Immutable `RandomSearch` record carrying `identity`, `space`, `count`, `seed` for the workflow where search apis generate immutable experiment candidates and compare only cohort-compatible evidence with explicit metric directions.

- Canonical object: `pllm.search.RandomSearch`
- Kind: `class`
- Signature/type: `__init__(self, identity: str, space: SearchSpace, *, count: int, seed: int) -> None`
- Public exports: `pllm.RandomSearch`, `pllm.search.RandomSearch`
- Public members: `identity: str`; `space: SearchSpace`; `count: int`; `seed: int`; `__init__(self, identity: str, space: SearchSpace, *, count: int, seed: int) -> None`; `candidates(self) -> tuple[SearchCandidate, ...]`; `evaluate(self, evaluator: Callable[[SearchCandidate], BenchmarkResult]) -> tuple[SearchEvaluation, ...]`

### `SearchCandidate`

Immutable `SearchCandidate` record carrying `trial_id`, `index`, `experiment`, `parameters`, `configuration_digest` for the workflow where search apis generate immutable experiment candidates and compare only cohort-compatible evidence with explicit metric directions.

- Canonical object: `pllm.search.SearchCandidate`
- Kind: `class`
- Signature/type: `constructor not exposed`
- Public exports: `pllm.SearchCandidate`, `pllm.search.SearchCandidate`
- Public members: `trial_id: str`; `index: int`; `experiment: Experiment`; `parameters: Mapping[str, Any]`; `configuration_digest: str`

### `SearchError`

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

- Canonical object: `pllm.search.SearchError`
- Kind: `class`
- Signature/type: `constructor not exposed`
- Public exports: `pllm.SearchError`, `pllm.search.SearchError`

### `SearchEvaluation`

Immutable `SearchEvaluation` record carrying `candidate`, `result` for the workflow where search apis generate immutable experiment candidates and compare only cohort-compatible evidence with explicit metric directions.

- Canonical object: `pllm.search.SearchEvaluation`
- Kind: `class`
- Signature/type: `constructor not exposed`
- Public exports: `pllm.SearchEvaluation`, `pllm.search.SearchEvaluation`
- Public members: `candidate: SearchCandidate`; `result: BenchmarkResult`

### `SearchSpace`

Immutable `SearchSpace` record carrying `base`, `parameters`, `constraints` for the workflow where search apis generate immutable experiment candidates and compare only cohort-compatible evidence with explicit metric directions.

- Canonical object: `pllm.search.SearchSpace`
- Kind: `class`
- Signature/type: `__init__(self, base: Experiment, parameters: Mapping[str, Sequence[Any]], *, constraints: Iterable[Constraint]=...) -> None`
- Public exports: `pllm.SearchSpace`, `pllm.search.SearchSpace`
- Public members: `base: Experiment`; `parameters: Mapping[str, tuple[Any, ...]]`; `constraints: tuple[Constraint, ...]`; `__init__(self, base: Experiment, parameters: Mapping[str, Sequence[Any]], *, constraints: Iterable[Constraint]=...) -> None`

### `evaluate_search`

Evaluates candidate benchmark evidence using explicit cohort-safe metric directions.

- Canonical object: `pllm.search.evaluate_search`
- Kind: `function`
- Signature/type: `evaluate_search(candidates: Iterable[SearchCandidate], evaluator: Callable[[SearchCandidate], BenchmarkResult]) -> tuple[SearchEvaluation, ...]`
- Public exports: `pllm.evaluate_search`, `pllm.search.evaluate_search`