API reference

plural.Client(*, api_key: 'str | None' = None, providers: 'Mapping[str, str | Provider] | None' = None, base_url: 'str | None' = None, catalog: 'ModelCatalog | None' = None, policy: 'RoutingPolicy | None' = None, sink: 'Sink | None' = None, redactor: 'Redactor | None' = None, sampler: 'Sampler | None' = None, capture_content: 'bool | None' = None, max_retries: 'int' = 2, max_cost_usd: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, tags: 'dict[str, str] | None' = None, trace_dir: 'str | Path | None' = None, project: 'str | None' = None) -> 'None'

is_authenticated(self) -> 'bool'

Sends a lightweight authenticated request to each HTTP provider.In-process providers (no HTTP client) are treated as authenticated. Returns:    ``True`` when every provider accepts the credentials or has no    HTTP client to probe. Raises:    PluralTimeoutError: If a provider cannot be reached.    PluralError: If a transport error occurs while probing.

push(self, obj: 'Any', **kwargs: 'Any') -> 'dict[str, Any]'

The revision is usable as soon as it is saved and stays private tothe project. Pushing identical content again returns the samerevision. To push a project directory with its dependencies, use``plural <kind> push`` or :func:`plural.project.sync.push`. Args:    obj: Environment, Task, Verifier, Agent, Harness, Benchmark, or Trace.    **kwargs: Hosted revision ids for graph edges, such as a Task's        ``environment_revision_id`` and ``verifier_revision_ids``. Returns:    The hosted revision record.

chat(self, *, model: 'str', messages: 'Sequence[Message | dict[str, Any]]', models: 'list[str] | None' = None, tools: 'Sequence[Tool | dict[str, Any]] | None' = None, temperature: 'float | None' = None, max_tokens: 'int | None' = None, metadata: 'dict[str, Any] | None' = None, tags: 'dict[str, str] | None' = None, write_trace: 'bool' = True, trace_context: 'TraceContext | None' = None, **kwargs: 'Any') -> 'ChatResponse'

achat(self, *, model: 'str', messages: 'Sequence[Message | dict[str, Any]]', models: 'list[str] | None' = None, tools: 'Sequence[Tool | dict[str, Any]] | None' = None, temperature: 'float | None' = None, max_tokens: 'int | None' = None, metadata: 'dict[str, Any] | None' = None, tags: 'dict[str, str] | None' = None, write_trace: 'bool' = True, trace_context: 'TraceContext | None' = None, **kwargs: 'Any') -> 'ChatResponse'

stream(self, *, model: 'str', messages: 'Sequence[Message | dict[str, Any]]', models: 'list[str] | None' = None, tags: 'dict[str, str] | None' = None, write_trace: 'bool' = True, trace_context: 'TraceContext | None' = None, **kwargs: 'Any') -> 'Iterator[StreamChunk]'

Args:    model: Primary model id.    messages: Conversation messages.    models: Optional fallback chain.    tags: Extra trace tags.    write_trace: Whether to persist this model-call trace.    trace_context: Optional parent and episode lineage.    **kwargs: Additional request fields. Yields:    Stream chunks.

astream(self, *, model: 'str', messages: 'Sequence[Message | dict[str, Any]]', models: 'list[str] | None' = None, tags: 'dict[str, str] | None' = None, write_trace: 'bool' = True, trace_context: 'TraceContext | None' = None, **kwargs: 'Any') -> 'AsyncIterator[StreamChunk]'

Args:    model: Primary model id.    messages: Conversation messages.    models: Optional fallback chain.    tags: Extra trace tags.    write_trace: Whether to persist this model-call trace.    trace_context: Optional parent and episode lineage.    **kwargs: Additional request fields. Yields:    Stream chunks.

label(self, trace_id: 'str', *, scores: 'dict[str, float] | None' = None, reward: 'float | None' = None, labels: 'dict[str, Any] | None' = None, feedback: 'str | None' = None) -> 'None'

Args:    trace_id: Trace id returned via ``response.raw['plural_trace_id']``.    scores: Named scores.    reward: Scalar reward.    labels: Discrete labels.    feedback: Free-form feedback.

flush(self) -> 'None'

close(self) -> 'None'

aclose(self) -> 'None'

Attributes:    type: Discriminator; always ``"input_audio"``.    data: Base64-encoded audio bytes.    format: Audio format such as ``"wav"`` or ``"mp3"``.

Attributes:    index: Choice index.    message: The assistant message.    finish_reason: Why generation stopped.

plural.types.FinishReason(*values)

Attributes:    name: Function name to call.    arguments: JSON-encoded argument object as a string.

Attributes:    name: Function name exposed to the model.    description: Human-readable description of the function.    parameters: JSON Schema object describing the parameters.    strict: Whether to request strict schema adherence when supported.

Attributes:    type: Discriminator; always ``"image_url"``.    url: HTTP(S) URL or ``data:`` URL for the image.    detail: Optional detail hint for vision models.

Attributes:    order: Provider slugs to try in order.    allow_fallbacks: Whether to allow backup providers.    require_parameters: Only use providers that support all request params.    data_collection: Whether to allow providers that may store data.    only: Allow-list of provider slugs.    ignore: Deny-list of provider slugs.    sort: Sort key such as ``"price"``, ``"latency"``, or ``"throughput"``.    max_price: Maximum price constraints for prompt/completion tokens.

Attributes:    type: Format type such as ``"text"``, ``"json_object"``, or ``"json_schema"``.    json_schema: Schema payload when ``type`` is ``"json_schema"``.

plural.types.Role(*values)

Attributes:    id: Completion id.    model: Model id.    delta: Incremental content.    finish_reason: Present on the final chunk when known.    usage: Usage, typically only on the final chunk.    provider: Provider slug.    region: Region of the host serving the stream.    raw: Original provider chunk payload.

to_openai(self) -> 'dict[str, Any]'

Every adapter yields :class:`StreamChunk`. Hosted gateways and HTTPclients that speak the OpenAI wire format must call this rather thanforwarding :attr:`raw`, which is the provider-native event and is nota stable client contract. Returns:    A ``chat.completion.chunk`` object. ``usage`` is present only when    the host reported it, typically on the last chunk.

Attributes:    role: Role, typically present only on the first delta.    content: Incremental text content.    reasoning: Incremental reasoning ("thinking") text. Thinking models emit        this for seconds before any ``content`` appears, so a client that        ignores it looks frozen.    reasoning_started: ``True`` when a thinking block opens. Some hosts        encrypt the tokens and send empty ``thinking_delta`` events; this        flag is how a UI learns the model is thinking anyway.    reasoning_finished: ``True`` when that thinking block closes.    reasoning_signature: Incremental attestation for the reasoning block.    tool_calls: Incremental tool call fragments, in OpenAI's streaming shape        (``index``, ``id``, ``function.name``, ``function.arguments``).

Attributes:    type: Discriminator; always ``"text"``.    text: The text content.

Attributes:    id: Provider-assigned call id used to correlate tool responses.    type: Tool type; currently only ``"function"``.    function: The function call payload.    extra_content: Opaque provider data that must be sent back with the        call on the next turn, keyed by provider, such as Gemini's        ``{"google": {"thought_signature": ...}}``. Gemini rejects a replayed        function call without its signature.

Attributes:    prompt_tokens: Input token count.    completion_tokens: Output token count. Includes reasoning tokens when the        provider bills them as output.    total_tokens: Sum of prompt and completion tokens.    cost: Estimated USD cost when known.    reasoning_tokens: How many completion tokens were reasoning, when the        provider reports the split. ``None`` means unreported, not zero.    cache_read_tokens: How many prompt tokens were served from the host's        prompt cache. Always a subset of ``prompt_tokens``.    cache_write_tokens: How many prompt tokens were written to the host's        prompt cache. Always a subset of ``prompt_tokens``.    cache_write_long_tokens: How many of ``cache_write_tokens`` were written        with a long-lived cache (Anthropic's one-hour TTL), which bills higher.

from_counts(prompt: 'int', completion: 'int', cost: 'float | None' = None, *, reasoning_tokens: 'int | None' = None, cache_read_tokens: 'int' = 0, cache_write_tokens: 'int' = 0, cache_write_long_tokens: 'int' = 0) -> 'Usage'

plural.types.cached_prompt_tokens_of(raw: 'Mapping[str, Any] | None') -> 'tuple[int, int]'

OpenAI Chat Completions uses ``completion_tokens_details.reasoning_tokens`` andthe Responses API uses ``output_tokens_details.reasoning_tokens``. Gemini reports``thoughtsTokenCount``. A host may also send ``reasoning_tokens`` directly. Args:    raw: A provider usage object. Returns:    The count, or ``None`` when the provider reported none.

plural.types.reasoning_tokens_of(raw: 'Mapping[str, Any] | None') -> 'int | None'

Args:    message: The message to extract text from. Returns:    Concatenated text content, or an empty string.

plural.types.text_content(message: 'Message') -> 'str'

add_llm(self, *, request: 'ChatRequest | dict[str, Any] | None', response: 'ChatResponse | None', attempts: 'list[Attempt] | None' = None, error: 'str | None' = None) -> 'LLMCall'

Args:    request: Chat request.    response: Chat response if successful.    attempts: Attempt records.    error: Error message if failed. Returns:    The appended :class:`LLMCall`.

add_action(self, name: 'str', arguments: 'dict[str, Any]', *, action_id: 'str | None' = None, tool_call_id: 'str | None' = None, source: 'ActionSource' = 'environment_native', observation: 'Any' = None, result: 'Any' = None, error: 'str | None' = None, latency_ms: 'float | None' = None) -> 'ActionStep'

add_turn(self, *, observation: 'Any' = None, model_context: 'ChatRequest | dict[str, Any] | None' = None, model_output: 'ChatResponse | None' = None, parsed_action: 'list[ParsedAction] | None' = None, actions: 'list[ActionStep] | None' = None, reward_events: 'list[RewardEvent] | None' = None, reasoning: 'list[ReasoningBlock] | None' = None, turn: 'int | None' = None) -> 'Turn'

transitions(self, *, source: "Literal['outcome', 'events', 'both']" = 'outcome') -> 'list[Transition]'

Prefers :class:`Turn` steps. Falls back to grouping flat``llm`` / ``action`` steps so production traces still export. Args:    source: Reward source, matching :meth:`turn_rewards`. Returns:    One :class:`Transition` per turn.

turns(self) -> 'list[Turn]'

credit(self, value: 'float', *, name: 'str' = 'late', reason: 'str | None' = None, turn_index: 'int | None' = None) -> 'RewardEvent | TraceOutcome'

turn_rewards(self, *, source: "Literal['outcome', 'events', 'both']" = 'outcome') -> 'list[float]'

returns(self, gamma: 'float' = 1.0, *, source: "Literal['outcome', 'events', 'both']" = 'outcome') -> 'list[float]'

label(self, *, scores: 'dict[str, float] | None' = None, reward: 'float | None' = None, labels: 'dict[str, Any] | None' = None, feedback: 'str | None' = None) -> 'TraceOutcome'

Args:    scores: Named Verifier outputs.    reward: Scalar reward.    labels: Discrete labels.    feedback: Free-form feedback. Returns:    The updated :class:`TraceOutcome`.

Returns:    The JSON Schema as a mutable dictionary. Raises:    ValueError: If the packaged resource is not a JSON object.

plural.tracing.resources.trace_json_schema() -> 'dict[str, Any]'

``credentials`` gives each Agent's credential values by Agent name, such as``{"sales-bot": {"SALESFORCE_TOKEN": token}}``. A credential an Agentdeclares and is not given here is read from the exported variable of thesame name. For a Task whose Environment has a party, ``party`` lists the Agents thatshare each episode, in seat order; list one Agent more than once forself-play. Left out, every Agent in ``agents`` plays, once each. ``episode_server`` says where the Job serves an external Agent's episodes;by default it listens on a free loopback port.

plural.Job(source: 'Task | Benchmark', agents: 'Sequence[Agent]', *, party: 'Sequence[Agent] | None' = None, mode: 'JobMode' = <JobMode.EVAL: 'eval'>, attempts: 'int' = 1, concurrency: "int | Literal['auto']" = 1, per_runtime_concurrency: 'int | None' = None, priority: 'int' = 0, retry: 'RetryPolicy | None' = None, provider: 'Any' = None, providers: 'Mapping[str, Any] | None' = None, registry: 'Any' = None, store: 'Any' = None, environ: 'Mapping[str, str] | None' = None, resource_resolvers: 'Mapping[str, Any] | None' = None, progress: 'Any' = None, project_policy: 'Any' = None, catalog: 'ModelCatalog | None' = None, client: 'Any' = None, api_key: 'str | None' = None, credentials: 'Mapping[str, Mapping[str, str]] | None' = None, episode_server: 'Any' = None) -> 'None'

run_async(self, *, resume: 'bool' = False) -> 'JobResult'

Returns:    The collected Trial outcomes.

run(self, *, resume: 'bool' = False) -> 'JobResult'

Returns:    The collected Trial outcomes.

Each version is a release. Beyond its Tasks it may declare categories,scoring rules, and evaluation tracks; see :class:`BenchmarkRelease`.

diff(self, other: 'Benchmark') -> 'BenchmarkDiff'

dependency_graph(self) -> 'dict[str, Any]'

Returns:    Benchmark metadata and all pinned Task dependencies.

export(self) -> 'dict[str, Any]'

plural.project.resources.LocalResource(ref: 'ResourceRef', directory: 'Path', value: 'Any', dependencies: 'tuple[ResourceRef, ...]') -> None

Hosted identifiers belong to ``project_id``. Entries recorded for anotherhosted project are never used as dependency pins.

plural.project.layout.Project(root: 'Path', manifest: 'ProjectManifest') -> None

find(start: 'Path | None' = None) -> 'Project'

Returns:    The project. Raises:    ProjectError: When no enclosing directory holds ``project.yaml``.

at(root: 'Path') -> 'Project'

Returns:    The project. Raises:    ProjectError: When ``project.yaml`` is missing or invalid.

resource_dir(self, ref: 'ResourceRef') -> 'Path'

Returns:    The resource directory, whether or not it exists. Raises:    ValueError: When the name is not one folder name, such as one a        hosted record supplied with ``/`` or ``..``.

manifest_path(self, ref: 'ResourceRef') -> 'Path'

Returns:    The manifest path, whether or not it exists.

has(self, ref: 'ResourceRef') -> 'bool'

Returns:    ``True`` when the directory exists.

names(self, kind: 'ResourceKind') -> 'list[str]'

Returns:    The names.

resource_at(self, path: 'Path') -> 'ResourceRef | None'

Returns:    The resource, or ``None`` outside any resource directory.

read_lock(self) -> 'LockFile'

Raises:    ProjectError: When the lock exists but is invalid.

write_lock(self, lock: 'LockFile') -> 'None'

read_binding(self) -> 'ProjectBinding | None'

Raises:    ProjectError: When the binding file is unreadable.

write_binding(self, binding: 'ProjectBinding') -> 'None'

``problems`` lists every independent issue so one run reports all of them.

plural.project.layout.ProjectError(message: 'str', problems: 'list[str] | None' = None) -> 'None'

plural.project.layout.ResourceKind(name: 'str', cli: 'str', directory: 'str', manifest: 'str', label: 'str') -> None

plural.project.layout.ResourceRef(kind: 'str', name: 'str') -> None

parse(value: 'str') -> 'ResourceRef'

Returns:    The reference.

plural.project.resources.Workspace(project: 'Project', *, catalog: 'ModelCatalog | None' = None) -> 'None'

load(self, ref: 'ResourceRef') -> 'LocalResource'

Returns:    The validated resource. Raises:    ProjectError: Listing every problem found.

get(self, kind: 'str', name: 'str') -> 'Any'

unfinished(self, roots: 'Iterable[ResourceRef]') -> 'list[str]'

A resource with markers still loads and runs locally; it cannot bepushed, released, or recorded until they are gone. Returns:    One ``path:line: note`` entry per marker, dependencies first.

dependencies(self, ref: 'ResourceRef') -> 'tuple[ResourceRef, ...]'

Returns:    The declared dependencies. Raises:    ProjectError: When the manifest cannot be read.

dependency_order(self, roots: 'Iterable[ResourceRef]') -> 'list[ResourceRef]'

Unresolved references and cycles are reported before any code isimported or anything is uploaded. Raises:    ProjectError: Listing unresolved references or the first cycle.

A valid name is already a hosted slug, so a local directory and its hostedresource are the same string on every filesystem. Returns:    The name, unchanged. Raises:    ProjectError: When the name cannot be used as a directory and slug.

plural.project.layout.check_name(name: 'str', what: 'str') -> 'str'

plural.project.layout.find_project_root(start: 'Path | None' = None) -> 'Path | None'

Returns:    Schemas keyed by file name, such as ``task.yaml``.

plural.project.schemas.manifest_schemas() -> 'dict[str, dict[str, Any]]'

Returns:    A detached schema safe for generated public references.

plural.project.schemas.public_schema(model: 'type[BaseModel]') -> 'dict[str, Any]'

Raises:    ValueError: When the name is not a resource kind.

plural.project.layout.resource_kind(name: 'str') -> 'ResourceKind'

plural.execution.JobStore(root: 'Path' = PosixPath('<default>'), *, on_event: 'Callable[[ProgressEvent], None] | None' = None) -> 'None'

job_path(self, job_id: 'str') -> 'Path'

initialize(self, spec: 'JobSpec', plan: 'JobPlan') -> 'Path'

load_spec(self, job_id: 'str') -> 'JobSpec'

load_lock(self, job_id: 'str') -> 'JobLock'

list_jobs(self) -> 'tuple[dict[str, Any], ...]'

emit(self, job_id: 'str', event_type: 'str', status: 'str', *, trial_id: 'str | None' = None, execution_id: 'int | None' = None, message: 'str' = '', data: 'Mapping[str, Any] | None' = None, secret_values: 'Iterable[str]' = ()) -> 'ProgressEvent'

events(self, job_id: 'str', *, after: 'int' = 0, follow: 'bool' = False, poll_interval: 'float' = 0.1) -> 'Iterable[ProgressEvent]'

request_cancel(self, job_id: 'str') -> 'None'

clear_cancel(self, job_id: 'str') -> 'None'

cancel_requested(self, job_id: 'str') -> 'bool'

trial_path(self, trial: 'TrialSpec | str', job_id: 'str | None' = None) -> 'Path'

successful_result(self, trial: 'TrialSpec') -> 'TrialResult | None'

next_execution_id(self, trial: 'TrialSpec') -> 'int'

trial_results(self, job_id: 'str') -> 'tuple[TrialResult, ...]'

write_trial_execution(self, trial: 'TrialSpec', execution_id: 'int', result: 'TrialResult', *, stdout: 'bytes' = b'', stderr: 'bytes' = b'', artifacts: 'Iterable[DownloadedFile]' = (), verifier_stdout: 'bytes' = b'', verifier_stderr: 'bytes' = b'') -> 'Path'

write_job_result(self, result: 'JobResult') -> 'Path'

write_review(self, trial: 'TrialSpec', verifier_name: 'str', submission: 'Mapping[str, Any]', result: 'TrialResult') -> 'Path'

read_job_result(self, job_id: 'str') -> 'JobResult | None'

write_sync_state(self, job_id: 'str', state: 'Mapping[str, Any]') -> 'Path'

read_sync_state(self, job_id: 'str') -> 'dict[str, Any] | None'

An Environment owns the episode: ``reset`` and ``step``, the table ofactions every App offers, and the rule that the Agent only ever sees anaction's observation. Most Environments need no subclass::     environment = Environment(apps=[Wordle()], runtime=Runtime.docker()) Subclass it only when Apps affect one another. Override :meth:`on_step`to react after any App's action, or :meth:`terminated` to end the episodefrom the state of several Apps.

plural.Environment(*, apps: 'Iterable[App[Any]]' = (), runtime: 'EnvironmentRuntime | Mapping[str, Any] | None' = None, name: 'str | None' = None, version: 'str | None' = None, description: 'str | None' = None, overview: 'str | None' = None, readme: 'str | None' = None, resources: 'Iterable[EnvironmentResource]' = (), guardrails: 'Iterable[Guardrail]' = (), harness_policy: 'HarnessPolicy | None' = None, limits: 'ExecutionLimits | None' = None, party: 'Party | int | Mapping[str, int] | None' = None, metadata: 'dict[str, Any] | None' = None, source: 'str | Path | None' = None) -> 'None'

on_step(self, call: 'ActionCall', result: 'Any', apps: 'Mapping[str, Any]') -> 'None'

``apps`` maps each App's name to a handle with ``call(action, **args)``,``snapshot()``, and ``state``. An effect here is not an Agent action andis not shown to the Agent. Apps never call each other directly. Rewards are not given here: they depend on the Task, so they come fromthe ``reward`` hook of a Task's Verifier.

terminated(self) -> 'bool'

truncated(self) -> 'bool'

reset(self, *, initial_state: 'Mapping[str, Any] | None' = None, info: 'Any' = None, seed: 'int | None' = None, verifiers: 'Sequence[Any]' = ()) -> 'tuple[Any, dict[str, Any]]'

``initial_state`` maps each App's name to its starting state; with oneApp it may be that App's state directly. ``verifiers`` gives each:meth:`step` its reward: Verifiers with a ``reward`` hook, or functionsof one :class:`~plural.Step`. Returns:    The opening observation and reset information.

step(self, action: 'str | Mapping[str, Any] | None' = None, /, **kwargs: 'Any') -> 'tuple[Any, float, bool, bool, dict[str, Any]]'

``action`` is an exposed action name with keyword arguments, or amapping with ``name`` and the arguments. With exactly one action thename may be omitted. Returns:    Observation, reward, terminated, truncated, and step information.

snapshot(self) -> 'dict[str, Any]'

close(self) -> 'None'

Args:    fn: Method to register (decorator usage).    name: Optional explicit action name. Defaults to the method name.    read_only: The action never changes state. Verifiers may call only        read-only actions after the episode.    timeout_seconds: How long one call may run. Returns:    The original method (decorator) or a decorator.

plural.action(fn: 'Callable[..., Any] | None' = None, *, name: 'str | None' = None, read_only: 'bool' = False, timeout_seconds: 'float' = 30) -> 'Any'

bind_source(self, digest: 'str', directory: 'Path | None' = None) -> 'None'

bind_source_digest(self, digest: 'str') -> 'None'

invoke(self, episode: 'Episode') -> 'VerifierOutput'

Returns:    A validated VerifierOutput.

model_post_init(self: 'BaseModel', context: 'Any', /) -> 'None'

It takes context as an argument since that's what pydantic-core passes when calling it. Args:    self: The BaseModel instance.    context: The context.

``observation`` is what the Agent saw back; ``error`` is set instead whenthe action rejected its input. ``previous_state`` and ``current_state``are the acting App's snapshots around the action, or ``None`` when it doesnot snapshot on each step. ``apps`` reads any App, by name: ``state`` fora Python App, ``snapshot()``, and ``query(action, **arguments)`` for aread-only action. Nothing here reaches the Agent. When several Agents share the episode, ``seat`` is the one that acted and``seats`` lists them all. A number a ``reward`` hook returns credits theacting seat; a mapping of seat to number credits each seat named, as in azero-sum game.

plural.Step(task: 'StepTask', turn: 'int', app: 'str', action: 'str', arguments: 'Mapping[str, Any]', observation: 'Any' = None, error: 'str | None' = None, previous_state: 'Any' = None, current_state: 'Any' = None, apps: 'Mapping[str, Any]' = <factory>, seat: 'str | None' = None, seats: 'tuple[str, ...]' = ()) -> None

This is the only Environment surface sent to the Agent. Internal State isnever copied here automatically. Subclass this with typed fields. The JSON Schema of the subclass is theobservation contract hosted with the environment. Implement :meth:`render`when the prompt should not be a raw dump of the fields. Attributes:    text: Default rendered view. Structured subclasses may ignore this.    metadata: Extra visible fields that do not need a typed attribute.

render(self) -> 'str'

Returns:    ``text``, or a subclass-specific prompt string.

State is never sent to the Agent. Only :class:`Observation` is visible.Verifiers receive the final State on :class:`~plural.verifiers.Episode`. Mark a field with :func:`initial` when a Task should supply it. Unmarkedfields are episode progress and cannot be set as ``initial_state``. Attributes:    seed: Optional deterministic seed a Task may set.    metadata: Extra internal fields that do not need a typed attribute.

Args:    value: Observation, string, or dumpable object. Returns:    Text for a user message.

plural.environments.types.as_text(value: 'Any') -> 'str'

plural.environments.types.initial(default: 'Any' = Ellipsis, *, default_factory: 'Any' = None, description: 'str | None' = None, **constraints: 'Any') -> 'Any'

Args:    value: Observation or fallback payload. Returns:    ``True`` when there is no rendered text.

plural.environments.types.is_empty_observation(value: 'Any') -> 'bool'

Args:    value: Observation or other payload. Returns:    A JSON-ready value for ``Turn.observation``.

plural.environments.types.serialize_observation(value: 'Any') -> 'Any'

Subclasses implement :meth:`run`. Plural discovers and hashes the Pythonclass directory, invokes ``run`` in the Environment Runtime, and emits thestandard result, trajectory, and log artifacts.

model_post_init(self, context: 'Any', /) -> 'None'

run(self, task: 'HarnessTask', agent: 'HarnessAgent', environment: 'HarnessEnvironment') -> 'HarnessResult | str | dict[str, Any] | Any'

load(path: 'str | Path | None' = None, *, environ: 'Mapping[str, str] | None' = None) -> 'AgentConfig'

Args:    path: The file. Defaults to ``PLURAL_AGENT_CONFIG``, then        ``plural-agent.yaml`` in the working directory.    environ: Environment to read; defaults to ``os.environ``. Returns:    The config. Raises:    ConfigurationError: When the file is missing or invalid.

with_environment(self, environ: 'Mapping[str, str]') -> 'AgentConfig'

Returns:    A copy with the overrides applied. Raises:    ConfigurationError: When an override has the wrong form.

studio(self, environ: 'Mapping[str, str] | None' = None) -> 'Studio'

Returns:    The client. Raises:    ConfigurationError: When that environment variable is not set.

Every call goes to the Job that started it, with the episode's own token.Pass ``verify`` (a CA bundle path, or ``False`` for a self-signed testcertificate) when the Job serves HTTPS with a private certificate.

plural.external.client.Episode(start: 'EpisodeStart', *, verify: 'str | bool' = True, timeout: 'float' = 120.0) -> 'None'

tools(self) -> 'list[dict[str, Any]]'

Returns:    The actions as OpenAI-compatible tools.

act(self, action: 'str', /, **arguments: 'Any') -> 'Any'

Returns:    Its observation.

read(self, path: 'str') -> 'bytes'

Returns:    Its bytes.

trace(self, trajectory: 'Mapping[str, Any]') -> 'None'

The Trial keeps it as self-reported, next to the actions the Job saw.

finish(self, response: 'Any') -> 'None'

plural.external.client.EpisodeError

``end`` writes it once, when the run finishes. ``interval`` also writes itevery ``interval_seconds`` while the run is going, and ``steps`` every``every_steps`` steps, so a long run can be watched live. Each writereplaces the last until the run finishes.

parse(value: 'FlushPolicy | str | Mapping[str, Any]') -> 'FlushPolicy'

Returns:    The policy. Raises:    ConfigurationError: When the value names no policy.

Record what happens with :meth:`user`, :meth:`llm`, :meth:`tool`, and:meth:`message`, then :meth:`finish` with the answer. Leaving the ``with``block finishes the run if you did not, as failed when it raised.

plural.external.tracing.Run(tracer: 'Tracer', sink: '_Sink | None', *, trace_id: 'str', kind: "Literal['episode', 'production']", flush: 'FlushPolicy', capture: 'Capture', tags: 'Mapping[str, str] | None' = None, metadata: 'Mapping[str, Any] | None' = None, episode: 'Episode | None' = None) -> 'None'

system(self, text: 'str') -> 'None'

user(self, text: 'str') -> 'None'

message(self, text: 'str') -> 'None'

llm(self, *, model: 'str | None' = None, messages: 'Sequence[Mapping[str, Any]]' = (), output: 'str | None' = None, tool_calls: 'Sequence[ToolCall | Mapping[str, Any]]' = (), reasoning: 'str | None' = None, usage: 'Mapping[str, Any] | None' = None, latency_ms: 'float | None' = None, error: 'str | None' = None, started_at: 'datetime | None' = None) -> 'None'

Args:    model: The model that answered.    messages: What it was sent, in the OpenAI chat format.    output: The text it returned.    tool_calls: The tool calls it asked for.    reasoning: Its reasoning, when it reported any.    usage: ``prompt_tokens``, ``completion_tokens``, ``cached_tokens``,        and ``cost_usd``, any of which may be missing.    latency_ms: How long the call took.    error: Why it failed, when it did.    started_at: When it started; defaults to now.

tool(self, name: 'str', arguments: 'Mapping[str, Any] | None' = None, result: 'Any' = None, *, call_id: 'str | None' = None, error: 'str | None' = None, latency_ms: 'float | None' = None, started_at: 'datetime | None' = None) -> 'None'

``call_id`` ties it to the model call that asked for it; without one itis matched to the latest unanswered call of the same tool.

metadata(self, **values: 'Any') -> 'None'

finish(self, answer: 'Any' = None) -> 'None'

In a Job this also ends the episode, so call it once, last.

fail(self, error: 'str') -> 'None'

snapshot(self) -> 'tuple[list[_Record], dict[str, Any]]'

Returns:    Its records in time order, and its metadata.

atif(self) -> 'dict[str, Any]'

Returns:    The ATIF document.

trace(self) -> 'dict[str, Any]'

Returns:    The Plural ``Trace`` payload.

plural.external.protocol.SignatureError

plural.external.tracing.ToolCall(id: 'str', name: 'str', arguments: 'Mapping[str, Any]' = <factory>) -> None

Args:    config: The agent and tracing config.    environ: Where the API key and overrides are read; defaults to        ``os.environ``.    studio: The Plural API client, for tests. Built from the API key when        omitted. Raises:    ConfigurationError: When production tracing is on and the API key's        environment variable is not set.

plural.external.tracing.Tracer(config: 'AgentConfig', *, environ: 'Mapping[str, str] | None' = None, studio: 'Any' = None) -> 'None'

from_config(path: 'str | None' = None, *, environ: 'Mapping[str, str] | None' = None) -> 'Tracer'

Returns:    The tracer.

for_agent(name: 'str', version: 'str', *, model: 'str' = '', environ: 'Mapping[str, str] | None' = None) -> 'Tracer'

Returns:    The tracer.

run(self, *, input: 'str | None' = None, trace_id: 'str | None' = None, flush: 'FlushPolicy | str | Mapping[str, Any] | None' = None, capture: 'Capture | Mapping[str, bool] | None' = None, tags: 'Mapping[str, str] | None' = None, metadata: 'Mapping[str, Any] | None' = None) -> 'Run'

Args:    input: The request the agent is working on, recorded as a user message.    trace_id: The trace's id; a new one when omitted.    flush: When to write the trace, overriding the config for this run.    capture: Which optional fields to keep, overriding the config.    tags: Labels for this run, added to the config's.    metadata: Values to attach to the trace. Returns:    The run; use it as a context manager.

episode(self, episode: 'Episode', *, flush: 'FlushPolicy | str | Mapping[str, Any] | None' = None, capture: 'Capture | Mapping[str, bool] | None' = None) -> 'Run'

The Task's instructions are recorded as the first user message, and:meth:`Run.finish` also finishes the episode. Returns:    The run; use it as a context manager.

flush(self, timeout: 'float' = 10.0) -> 'bool'

Returns:    Whether everything was written within ``timeout`` seconds.

Returns:    The run, or ``None`` outside one.

plural.external.tracing.current_run() -> 'Run | None'

Returns:    32 random bytes, as ``whsec_`` and base64.

plural.external.protocol.new_signing_key() -> 'str'

Args:    url: The service's episode URL.    key: The signing key.    ca_bundle: A PEM CA file for a private certificate.    timeout: Seconds to wait. Returns:    The status the service answered with. Raises:    httpx.HTTPError: When the service could not be reached.

plural.external.client.ping(url: 'str', key: 'str', *, ca_bundle: 'str | None' = None, timeout: 'float' = 15) -> 'int'

plural.external.tracing.set_tracer(value: 'Tracer | None') -> 'None'

Returns:    ``webhook-id``, ``webhook-timestamp``, and ``webhook-signature``.

plural.external.protocol.sign(key: 'bytes', body: 'bytes', *, message_id: 'str', timestamp: 'int | None' = None) -> 'dict[str, str]'

Returns:    The bytes to sign with. Raises:    ValueError: When the key is shorter than 32 bytes.

plural.external.protocol.signing_key(value: 'str') -> 'bytes'

Returns:    The tracer.

plural.external.tracing.tracer() -> 'Tracer'

Returns:    The request's ``webhook-id``. Raises:    SignatureError: When a header is missing, the timestamp is more than        five minutes off, the id was already seen, or no signature matches.

plural.external.protocol.verify(key: 'bytes', body: 'bytes', headers: 'Mapping[str, str]', *, now: 'float | None' = None, seen: '_Seen | None' = <configured default>) -> 'str'

Args:    body: The request's raw bytes, before any JSON parsing.    headers: Its headers.    key: The shared signing key. Defaults to ``PLURAL_SIGNING_KEY``. Returns:    The episode to start, or a ping to answer with any 2xx. Raises:    SignatureError: When the request is not signed with the key, is more        than five minutes old, was received before, or is not one Plural sends.

plural.external.client.verify_request(body: 'bytes', headers: 'Mapping[str, str]', *, key: 'str | None' = None) -> 'EpisodeStart | Ping'

plural.sandbox.SandboxProvider()

capabilities(self) -> 'ProviderCapabilities'

preflight(self, requirements: 'SandboxRequirements') -> 'EffectiveSandboxPolicy'

doctor(self) -> 'ProviderDoctor'

create(self, requirements: 'SandboxRequirements') -> 'SandboxHandle'

upload_files(self, handle: 'SandboxHandle', files: 'Sequence[FileUpload]', *, root: 'str' = '/workspace') -> 'None'

upload_bundle(self, handle: 'SandboxHandle', bundle: 'Path', *, root: 'str' = '/workspace') -> 'None'

exec(self, handle: 'SandboxHandle', request: 'ExecRequest') -> 'ExecResult'

download_files(self, handle: 'SandboxHandle', paths: 'Sequence[str]', *, root: 'str' = '/workspace') -> 'tuple[DownloadedFile, ...]'

download_artifacts(self, handle: 'SandboxHandle', paths: 'Sequence[str]', *, root: 'str' = '/workspace', user: 'str | None' = None) -> 'tuple[DownloadedFile, ...]'

stop_user_processes(self, handle: 'SandboxHandle', users: 'Sequence[str | None]') -> 'None'

``None`` names the sandbox's default user. A provider that cannot dothis safely does nothing; the App host refuses actions after the Job's``finish`` either way.

isolate_apps(self, handle: 'SandboxHandle') -> 'AppIsolation'

Returns:    The users to run the App host and the Harness as; no ``app_user``    when the sandbox cannot separate them.

open_workspace(self, handle: 'SandboxHandle', isolation: 'AppIsolation', paths: 'Sequence[str]') -> 'None'

isolate_seats(self, handle: 'SandboxHandle', seats: 'Sequence[str]') -> 'dict[str, str]'

Each must differ from the App host's user and from every other seat's,and must not be able to become another user, so one seat's Harnesscannot read another's files or process. Returns:    Seat to user, or empty when the sandbox cannot separate them.

cancel(self, handle: 'SandboxHandle') -> 'None'

destroy(self, handle: 'SandboxHandle') -> 'None'

required_capabilities(self) -> 'frozenset[SandboxCapability]'

plural.sandbox.ProviderRegistry() -> 'None'

register(self, provider: 'SandboxProvider', *, replace: 'bool' = False) -> 'None'

get(self, name: 'str') -> 'SandboxProvider'

doctors(self, *, include_unavailable: 'bool' = False) -> 'tuple[ProviderDoctor, ...]'

This provider intentionally does not advertise network, resource, image, orread-only-root enforcement. It is suitable only for explicitly trusted localdevelopment workloads.

plural.sandbox.LocalProvider(*, base_dir: 'Path | None' = None) -> 'None'

capabilities(self) -> 'ProviderCapabilities'

doctor(self) -> 'ProviderDoctor'

create(self, requirements: 'SandboxRequirements') -> 'SandboxHandle'

upload_files(self, handle: 'SandboxHandle', files: 'Sequence[FileUpload]', *, root: 'str' = '/workspace') -> 'None'

exec(self, handle: 'SandboxHandle', request: 'ExecRequest') -> 'ExecResult'

download_files(self, handle: 'SandboxHandle', paths: 'Sequence[str]', *, root: 'str' = '/workspace') -> 'tuple[DownloadedFile, ...]'

cancel(self, handle: 'SandboxHandle') -> 'None'

destroy(self, handle: 'SandboxHandle') -> 'None'

plural.sandbox.DockerProvider(*, executable: 'str' = 'docker', default_image: 'str' = 'python:3.12-slim') -> 'None'

capabilities(self) -> 'ProviderCapabilities'

preflight(self, requirements: 'SandboxRequirements') -> 'EffectiveSandboxPolicy'

doctor(self) -> 'ProviderDoctor'

extend_image(self, requirements: 'SandboxRequirements', context: 'Path', key: 'str') -> 'SandboxRequirements'

The context's Dockerfile receives the base image as the ``BASE`` buildargument. The result is tagged by base identity and ``key``, so laterTrials and Jobs reuse it instead of building again. Returns:    The requirements, pointing at the extended image.

create(self, requirements: 'SandboxRequirements') -> 'SandboxHandle'

upload_files(self, handle: 'SandboxHandle', files: 'Sequence[FileUpload]', *, root: 'str' = '/workspace') -> 'None'

isolate_apps(self, handle: 'SandboxHandle') -> 'AppIsolation'

The container runs everything else as ``65532``, with every capabilitydropped, so the Harness cannot read the App host's ``0700`` folder orits process. Returns:    The App host's user, and the default user for the Harness.

isolate_seats(self, handle: 'SandboxHandle', seats: 'Sequence[str]') -> 'dict[str, str]'

Every capability is dropped, so no seat's user can read another's``0700`` folder or process, or the App host's. Returns:    Seat to a numeric user, ``65400`` for the first.

exec(self, handle: 'SandboxHandle', request: 'ExecRequest') -> 'ExecResult'

download_files(self, handle: 'SandboxHandle', paths: 'Sequence[str]', *, root: 'str' = '/workspace') -> 'tuple[DownloadedFile, ...]'

download_artifacts(self, handle: 'SandboxHandle', paths: 'Sequence[str]', *, root: 'str' = '/workspace', user: 'str | None' = None) -> 'tuple[DownloadedFile, ...]'

No capability is kept, so only a seat's own user can enter its ``0700`` folder.

stop_user_processes(self, handle: 'SandboxHandle', users: 'Sequence[str | None]') -> 'None'

``None`` is the container's default user, whose ``sleep`` keeps it aliveas PID 1 and is spared.

cancel(self, handle: 'SandboxHandle') -> 'None'

destroy(self, handle: 'SandboxHandle') -> 'None'

plural.sandbox.DaytonaProvider(*, adapter: 'DaytonaClientAdapter | None' = None, environ: 'Mapping[str, str] | None' = None) -> 'None'

capabilities(self) -> 'ProviderCapabilities'

preflight(self, requirements: 'SandboxRequirements') -> 'EffectiveSandboxPolicy'

doctor(self) -> 'ProviderDoctor'

create(self, requirements: 'SandboxRequirements') -> 'SandboxHandle'

upload_files(self, handle: 'SandboxHandle', files: 'Sequence[FileUpload]', *, root: 'str' = '/workspace') -> 'None'

isolate_apps(self, handle: 'SandboxHandle') -> 'AppIsolation'

Daytona's default user can ``sudo``, so a Harness running as it couldread anything. Here the Harness runs as ``plural-agent``, which cannot,and the App host as ``plural-apps``. Returns:    Both users, or no ``app_user`` when the image has no passwordless    ``sudo`` or ``useradd``.

isolate_seats(self, handle: 'SandboxHandle', seats: 'Sequence[str]') -> 'dict[str, str]'

Returns:    Seat to user, or empty when the image has no passwordless ``sudo``    or ``useradd``.

open_workspace(self, handle: 'SandboxHandle', isolation: 'AppIsolation', paths: 'Sequence[str]') -> 'None'

Raises:    SandboxError: When the folders cannot be opened to it.

exec(self, handle: 'SandboxHandle', request: 'ExecRequest') -> 'ExecResult'

A ``user`` other than ``root`` runs through ``sudo -n -E -u``, whichfails rather than falling back to the default user.

download_files(self, handle: 'SandboxHandle', paths: 'Sequence[str]', *, root: 'str' = '/workspace') -> 'tuple[DownloadedFile, ...]'

download_artifacts(self, handle: 'SandboxHandle', paths: 'Sequence[str]', *, root: 'str' = '/workspace', user: 'str | None' = None) -> 'tuple[DownloadedFile, ...]'

Daytona's file API reads as the sandbox's default user, which can readthe App host's folder, so a symlink or a path that resolves outside``root`` is refused first, as the Harness's ``user`` when given, andthe resolved file is what is read. Raises:    FileNotFoundError: When a declared path is not a regular file inside ``root``.

stop_user_processes(self, handle: 'SandboxHandle', users: 'Sequence[str | None]') -> 'None'

The default user is skipped: it is the one Daytona runs its own tools as.

cancel(self, handle: 'SandboxHandle') -> 'None'

destroy(self, handle: 'SandboxHandle') -> 'None'

Multi-host models expand to US endpoints first, then the lab host. Examples:    >>> from plural.catalog import ModelCatalog    >>> from plural.types import ChatRequest, Message    >>> policy = Explicit()    >>> req = ChatRequest(    ...     model="openai/gpt-5.6-luna", messages=[Message(role="user", content="x")]    ... )    >>> policy.select(req, [req.model], ModelCatalog())[0].model    'openai/gpt-5.6-luna'

plural.routing.policies.Explicit()

select(self, request: 'ChatRequest', candidates: 'list[str]', catalog: 'ModelCatalog') -> 'list[ModelRoute]'

Args:    request: The chat request.    candidates: Candidate model ids.    catalog: Model catalog. Returns:    Ordered routes.

plural.routing.policies.Fallback()

The primary model remains first; remaining candidates are sorted byestimated prompt+completion price (using equal token weights). Eachmodel then expands to its host endpoints (US first).

plural.routing.policies.LeastCost()

select(self, request: 'ChatRequest', candidates: 'list[str]', catalog: 'ModelCatalog') -> 'list[ModelRoute]'

Args:    request: The chat request.    candidates: Candidate model ids.    catalog: Model catalog. Returns:    Ordered routes.

Uses a static heuristic table for v1; a learned policy can replace thislater via the same :class:`RoutingPolicy` protocol.

plural.routing.policies.LowestLatency()

select(self, request: 'ChatRequest', candidates: 'list[str]', catalog: 'ModelCatalog') -> 'list[ModelRoute]'

Args:    request: The chat request.    candidates: Candidate model ids.    catalog: Model catalog. Returns:    Ordered routes.

Attributes:    model: Model id in ``author/slug`` form.    provider: Host slug that should serve the request.    region: Host region. Carried through so billing can charge the region's        own rate rather than whichever one happens to be listed first.    upstream_id: Model id the host expects, when different from ``model``.    priority: Lower values are tried first.

plural.routing.policies.RoutingPolicy(*args, **kwargs)

select(self, request: 'ChatRequest', candidates: 'list[str]', catalog: 'ModelCatalog') -> 'list[ModelRoute]'

Args:    request: The chat request.    candidates: Candidate model ids (primary + fallbacks).    catalog: Model catalog used for cost/latency metadata. Returns:    Ordered list of :class:`ModelRoute` values.

Returns:    Every host route for the candidates, ordered by model then endpoint priority.

plural.routing.policies.expand_models(model_ids: 'list[str]', catalog: 'ModelCatalog') -> 'list[ModelRoute]'

Args:    model_id: Canonical ``author/slug`` id.    catalog: Model catalog.    priority_base: Starting priority for this model's endpoints. Returns:    Ordered host routes for the model.

plural.routing.policies.routes_for_model(model_id: 'str', catalog: 'ModelCatalog', *, priority_base: 'int' = 0) -> 'list[ModelRoute]'

Args:    dataset: Source dataset. Returns:    List of flat-ish records suitable for ``datasets.Dataset.from_list``.

plural.environments.export.hf.to_huggingface_records(dataset: 'TraceDataset') -> 'list[dict[str, Any]]'

Prefers :class:`~plural.tracing.schema.Turn` steps (observation,actions, observations). Falls back to flat ``llm`` / ``action`` steps. Args:    trace: Source trace. Returns:    A dictionary with ``messages``, ``reward``, ``task``, and ``extra``.

plural.environments.export.verifiers.to_verifiers_trace(trace: 'Trace') -> 'dict[str, Any]'

Args:    path: Optional path to a catalog JSON file. Defaults to the bundled snapshot. Examples:    >>> catalog = ModelCatalog()    >>> len(catalog.models()) > 0    True

plural.ModelCatalog(path: 'str | Path | None' = None, *, entries: 'Iterable[ModelSpec | Mapping[str, Any]]' = (), include_bundled: 'bool' = True) -> 'None'

add(self, *entries: 'ModelSpec | Mapping[str, Any]') -> 'ModelCatalog'

Project entries replace bundled entries with the same stable model ID.The catalog is intentionally passed explicitly; no process-globalregistration is performed. Returns:    This catalog, for convenient construction.

with_entries(self, *entries: 'ModelSpec | Mapping[str, Any]') -> 'ModelCatalog'

Returns:    A copy containing the effective bundled and project entries.

load_bundled(self) -> 'None'

load_path(self, path: 'Path') -> 'None'

Args:    path: Path to a JSON catalog file.

models(self) -> 'list[ModelSpec]'

Returns:    A list of :class:`ModelSpec` entries.

ids(self) -> 'list[str]'

suggest(self, model_id: 'str', *, limit: 'int' = 5) -> 'list[str]'

Args:    model_id: The ID the caller tried to use.    limit: Maximum suggestions. Returns:    Close catalog IDs, or a short prefix of the catalog.

get(self, model_id: 'str') -> 'ModelSpec | None'

Args:    model_id: Model id in ``author/slug`` form. Returns:    The matching :class:`ModelSpec`, or ``None``.

require(self, model_id: 'str') -> 'ModelSpec'

Args:    model_id: Model id in ``author/slug`` form. Returns:    The matching :class:`ModelSpec`. Raises:    NotFoundError: If the model is not in the catalog.

refresh_from_openrouter(self, url: 'str' = 'https://openrouter.ai/api/v1/models') -> 'int'

Args:    url: Models endpoint URL. Returns:    Number of models loaded. Note:    This performs a network request and is intended for maintainer    tooling, not runtime hot paths.

write_snapshot(self, path: 'Path') -> 'None'

Args:    path: Destination path.

ordered_endpoints(self) -> 'list[ModelEndpoint]'

Returns:    Ordered endpoints, or a single implicit author host when none are listed.

host_providers(self) -> 'list[str]'

pricing_for(self, provider: 'str | None' = None, region: 'str | None' = None) -> 'ModelPricing | None'

Region matters because the same provider charges different rates indifferent regions: Azure EU lists above Azure US for identical models.When a region is given it must match, so a miss falls back to the defaultrather than billing a cheaper region's rate for a pricier one. Args:    provider: Host slug. ``None`` uses the default endpoint.    region: Host region. ``None`` matches the first endpoint for the provider. Returns:    Per-token pricing, or ``None``.

plural.catalog.estimate_cost(usage: 'Usage', spec: 'ModelSpec | None', *, provider: 'str | None' = None, region: 'str | None' = None) -> 'float | None'

Attributes:    candidates: Upstream models we could carry but do not. Reported only; the        catalog is curated, so adding one is an explicit choice.    removed: Catalog ids the upstream reference no longer lists.    repriced: Rates that moved upstream.    unpriced: Catalog ids with no usable price, which stay hidden.    unconfirmed: Catalog ids no configured provider currently lists.    providers_checked: Provider slugs whose listings were fetched.    discounted: Model ids where upstream is running a promotion. Recorded so a        reviewer can see we deliberately kept the list price.    retiered: Prompt-length rates that differ from the catalog's.    new_hosts: Hosts upstream offers for models we carry but we do not list.

plural.catalog.sync.CatalogDiff(candidates: 'list[UpstreamModel]' = <factory>, removed: 'list[str]' = <factory>, repriced: 'list[PriceChange]' = <factory>, unpriced: 'list[str]' = <factory>, unconfirmed: 'list[str]' = <factory>, providers_checked: 'list[str]' = <factory>, discounted: 'list[str]' = <factory>, retiered: 'list[TierChange]' = <factory>, new_hosts: 'list[tuple[str, str]]' = <factory>) -> None

Attributes:    id: Model id.    field_name: Which rate changed (``prompt`` or ``completion``).    old: Price currently in the catalog.    new: Undiscounted list price reported upstream.    provider: Host the rate belongs to, or ``None`` for the model default.    region: Host region, or ``None`` for the model default.

plural.catalog.sync.PriceChange(id: 'str', field_name: 'str', old: 'float | None', new: 'float | None', provider: 'str | None' = None, region: 'str | None' = None) -> None

Attributes:    id: Model id.    tiers: Tiers reported upstream, at list prices.    provider: Host the tiers belong to, or ``None`` for the model default.    region: Host region, or ``None`` for the model default.

plural.catalog.sync.TierChange(id: 'str', tiers: 'tuple[UpstreamTier, ...]', provider: 'str | None' = None, region: 'str | None' = None) -> None

describe(self) -> 'str'

Returns:    A human-readable description, or a note that tiers were dropped.

Attributes:    provider: Catalog provider slug, or ``None`` when the tag is unmapped.    region: Coarse region key.    tier: Service tier. Only ``standard`` is used for catalog pricing.    upstream_id: Model id the host expects.    prompt: Undiscounted USD per prompt token.    completion: Undiscounted USD per completion token.    discount: Promotional fraction OpenRouter applied, if any.    tiers: Prompt-length rates, ordered by threshold.    tag: Raw upstream tag, kept for reporting unmapped hosts.    cache_read: Undiscounted USD per prompt token read from the cache.    cache_write: Undiscounted USD per prompt token written to the cache.

plural.catalog.sync.UpstreamEndpoint(provider: 'str | None', region: 'str', tier: 'str', upstream_id: 'str', prompt: 'float | None', completion: 'float | None', discount: 'float | None', tiers: 'tuple[UpstreamTier, ...]', tag: 'str', cache_read: 'float | None' = None, cache_write: 'float | None' = None) -> None

Attributes:    id: Canonical ``author/slug`` id.    name: Display name.    context_length: Context window in tokens.    prompt: USD per prompt token, or ``None`` when unknown.    completion: USD per completion token, or ``None`` when unknown.    modality: High-level modality string.    input_modalities: Accepted input modalities.    output_modalities: Produced output modalities.    supported_parameters: Request parameters the model accepts.    description: Upstream description, a starting point for the model card.    created: Upstream release date, ``YYYY-MM-DD``.    max_output_tokens: Largest completion upstream reports.

plural.catalog.sync.UpstreamModel(id: 'str', name: 'str | None' = None, context_length: 'int | None' = None, prompt: 'float | None' = None, completion: 'float | None' = None, modality: 'str | None' = None, input_modalities: 'tuple[str, ...]' = ('text',), output_modalities: 'tuple[str, ...]' = ('text',), supported_parameters: 'tuple[str, ...]' = (), description: 'str | None' = None, created: 'str | None' = None, max_output_tokens: 'int | None' = None) -> None

Attributes:    min_prompt_tokens: Prompt size at which the rate takes over.    prompt: Undiscounted USD per prompt token.    completion: Undiscounted USD per completion token.

plural.catalog.sync.UpstreamTier(min_prompt_tokens: 'int', prompt: 'float', completion: 'float') -> None

plural.catalog.sync.apply_diff(current: 'Mapping[str, Any]', upstream: 'Mapping[str, UpstreamModel]', changes: 'CatalogDiff', *, add: 'Iterable[str]' = (), add_hosts: 'Iterable[str]' = (), endpoints_by_model: 'Mapping[str, list[UpstreamEndpoint]] | None' = None, now: 'datetime | None' = None) -> 'dict[str, Any]'

Args:    client: HTTP client to use.    env: Environment mapping to read keys from. Defaults to ``os.environ``. Returns:    A pair of (normalized slugs, provider slugs that answered).

plural.catalog.sync.collect_served_slugs(client: 'httpx.Client', env: 'Mapping[str, str] | None' = None) -> 'tuple[set[str], list[str]]'

Args:    current: Decoded ``models.json``.    upstream: Upstream models keyed by id.    served: Normalized slugs configured providers report. Empty means        availability could not be confirmed, so nothing is filtered on it.    providers_checked: Provider slugs that answered.    endpoints_by_model: Per-model host records. Models absent from this        mapping are skipped for repricing rather than assumed unchanged, so a        failed lookup never looks like a price drop. Returns:    The differences a human needs to review.

plural.catalog.sync.diff_catalog(current: 'Mapping[str, Any]', upstream: 'Mapping[str, UpstreamModel]', served: 'set[str]', *, providers_checked: 'Iterable[str]' = (), endpoints_by_model: 'Mapping[str, list[UpstreamEndpoint]] | None' = None) -> 'CatalogDiff'

Args:    client: HTTP client to use.    model_id: Canonical ``author/slug`` id. Returns:    Host records, empty when the model is unknown upstream.

plural.catalog.sync.fetch_endpoints(client: 'httpx.Client', model_id: 'str') -> 'list[UpstreamEndpoint]'

Args:    client: HTTP client to use. Returns:    Upstream models keyed by canonical id.

plural.catalog.sync.fetch_openrouter(client: 'httpx.Client') -> 'dict[str, UpstreamModel]'

Args:    client: HTTP client to use.    slug: Provider slug.    api_key: Provider API key. Returns:    Normalized slugs the provider reports, empty when the call fails.

plural.catalog.sync.fetch_provider_models(client: 'httpx.Client', slug: 'str', api_key: 'str') -> 'set[str]'

Args:    qualifier: A segment after the provider in an endpoint tag. Returns:    ``True`` when the segment looks like a region rather than a variant. Examples:    >>> is_region("us-east-1"), is_region("global"), is_region("fp8")    (True, True, False)

plural.catalog.sync.is_region(qualifier: 'str') -> 'bool'

Args:    path: Location of ``models.json``. Returns:    The decoded document.

plural.catalog.sync.load_catalog(path: 'Path' = PosixPath('<default>')) -> 'dict[str, Any]'

Args:    argv: Command-line arguments. Returns:    Process exit code. ``1`` under ``--check`` when the catalog is stale.

plural.catalog.sync.main(argv: 'list[str] | None' = None) -> 'int'

plural.catalog.sync.normalize_model_id(model_id: 'str') -> 'str'

A price added to an entry that had none would otherwise land at the end,which makes the review diff harder to read than it needs to be. Args:    spec: A single catalog entry. Returns:    The same entry with known keys first, in canonical order. Examples:    >>> list(order_spec_keys({"endpoints": [], "id": "a/b"}))    ['id', 'endpoints']

plural.catalog.sync.order_spec_keys(spec: 'Mapping[str, Any]') -> 'dict[str, Any]'

plural.catalog.sync.parse_endpoint_tag(tag: 'str') -> 'tuple[str | None, str, str]'

Args:    payload: Decoded ``/api/v1/models/{id}/endpoints`` response. Returns:    Every host described upstream, with list rather than promotional prices.

plural.catalog.sync.parse_endpoints(payload: 'Mapping[str, Any]') -> 'list[UpstreamEndpoint]'

Args:    payload: Decoded ``/api/v1/models`` response. Returns:    Upstream models keyed by canonical id.

plural.catalog.sync.parse_openrouter(payload: 'Mapping[str, Any]') -> 'dict[str, UpstreamModel]'

A tier is only usable if both rates are present, since billing one side at thelong-prompt rate and the other at the base rate matches neither. Args:    pricing: The endpoint's ``pricing`` mapping.    discount: Promotional fraction to divide back out. Returns:    Tiers ordered by threshold.

plural.catalog.sync.parse_tiers(pricing: 'Mapping[str, Any]', discount: 'float | None') -> 'tuple[UpstreamTier, ...]'

Args:    changes: Differences from :func:`diff_catalog`. Returns:    A markdown summary.

plural.catalog.sync.render_report(changes: 'CatalogDiff') -> 'str'

Args:    endpoints: Host records for one model. Returns:    Mapping of (provider, region) to endpoint, cheapest kept on collision.

plural.catalog.sync.standard_endpoints(endpoints: 'Iterable[UpstreamEndpoint]') -> 'dict[tuple[str, str], UpstreamEndpoint]'

Args:    document: Catalog document to serialize.    path: Location of ``models.json``.

plural.catalog.sync.write_catalog(document: 'Mapping[str, Any]', path: 'Path' = PosixPath('<default>')) -> 'None'

plural.catalog.edit.EditError

Unknown keys are rejected so a misspelled field fails validation instead ofsilently never reaching the card.

Returns:    The argument parser.

plural.catalog.edit.build_parser() -> 'argparse.ArgumentParser'

Returns:    The text ending at its last complete sentence. Examples:    >>> complete_sentences("Fast model. Good at code, and...")    'Fast model.'    >>> complete_sentences("Fast model.")    'Fast model.'

plural.catalog.edit.complete_sentences(text: 'str') -> 'str'

Returns:    ``0`` on success, ``1`` when the command failed or validation did.

plural.catalog.edit.main(argv: 'list[str] | None' = None) -> 'int'

OpenRouter lists ``x-ai/grok-4.3`` where the catalog says ``xai/grok-4.3``, andwrites versions with dots where a lab uses dashes. An exact id wins, then an``alias``, then a unique match on the version-insensitive slug. Returns:    The upstream record, or ``None`` when there is no unambiguous match. Examples:    >>> match_upstream("xai/grok-4.3", {"x-ai/grok-4.3": 1})    1    >>> match_upstream("anthropic/claude-haiku-4-5", {"anthropic/claude-haiku-4.5": 2})    2    >>> match_upstream("a/x", {"b/x": 1, "c/x": 2}) is None    True

plural.catalog.edit.match_upstream(model_id: 'str', upstream: 'Mapping[str, Any]', alias: 'str | None' = None) -> 'Any'

plural.catalog.edit.parse_rate(raw: 'str') -> 'str'

plural.catalog.edit.parse_value(path: 'str', raw: 'str') -> 'Any'

Returns:    The JSON result to print. Raises:    EditError: When the command cannot be applied or would leave the        catalog invalid.

plural.catalog.edit.run(args: 'argparse.Namespace') -> 'dict[str, Any]'

Returns:    An entry with placeholder values for every card field.

plural.catalog.edit.template(model_id: 'str') -> 'dict[str, Any]'

Args:    document: Decoded ``models.json``. Returns:    Every issue across every entry.

plural.catalog.edit.validate_document(document: 'Mapping[str, Any]') -> 'list[Issue]'

Args:    card: A parsed catalog entry. Returns:    Errors, which block a write, and warnings, which ``--strict`` promotes.

plural.catalog.edit.validate_entry(card: 'ModelCardDocument') -> 'list[Issue]'

Args:    sink: Destination sink.    redactor: Optional redactor applied before write.    sampler: Optional sampler; defaults to keep-all.    maxsize: Queue size before ``record`` blocks.

plural.tracing.TraceWriter(sink: 'Sink', *, redactor: 'Redactor | None' = None, sampler: 'Sampler | None' = None, maxsize: 'int' = 1000) -> 'None'

record(self, trace: 'Trace') -> 'None'

Args:    trace: Trace to record.

label(self, trace_id: 'str', *, scores: 'dict[str, float] | None' = None, reward: 'float | None' = None, labels: 'dict[str, Any] | None' = None, feedback: 'str | None' = None) -> 'None'

If the trace has not been written yet, the label is merged on record.If a SQLite sink is used and the trace already exists, it is updated. Args:    trace_id: Trace id to label.    scores: Named scores.    reward: Scalar reward.    labels: Discrete labels.    feedback: Free-form feedback.

flush(self) -> 'None'

close(self) -> 'None'

Args:    path: Destination ``.jsonl`` path.

plural.tracing.sinks.JSONLSink(path: 'str | Path') -> 'None'

write(self, trace: 'Trace') -> 'None'

Args:    trace: Trace to persist.

read_all(self) -> 'list[Trace]'

Returns:    List of traces in file order.

close(self) -> 'None'

Args:    sinks: Child sinks.

plural.tracing.sinks.MultiSink(sinks: 'list[Sink]') -> 'None'

write(self, trace: 'Trace') -> 'None'

Args:    trace: Trace to persist.

close(self) -> 'None'

The plural :class:`~plural.tracing.schema.Trace` remains canonical. Thissink is an exporter onto the still-Development ``gen_ai.*`` conventions. Args:    tracer_name: Tracer instrumentation name. Note:    Requires the ``plural[otel]`` extra.

plural.tracing.sinks.OTelSink(tracer_name: 'str' = 'plural') -> 'None'

write(self, trace: 'Trace') -> 'None'

Args:    trace: Trace to export.

close(self) -> 'None'

Args:    path: Destination ``.sqlite`` path.

plural.tracing.sinks.SQLiteSink(path: 'str | Path') -> 'None'

write(self, trace: 'Trace') -> 'None'

Args:    trace: Trace to persist.

get(self, trace_id: 'str') -> 'Trace | None'

Args:    trace_id: Trace id. Returns:    The trace, or ``None``.

query(self, *, environment: 'str | None' = None, tag: 'str | None' = None, limit: 'int' = 100) -> 'list[Trace]'

Args:    environment: Optional environment name filter.    tag: Optional tag key that must be present.    limit: Maximum rows. Returns:    Matching traces, newest first.

close(self) -> 'None'

plural.tracing.sinks.Sink(*args, **kwargs)

write(self, trace: 'Trace') -> 'None'

close(self) -> 'None'

Args:    path: Path to a JSONL file. Returns:    Parsed traces.

plural.tracing.sinks.traces_from_jsonl(path: 'str | Path') -> 'list[Trace]'

Args:    fields: Dot-paths to replace with ``[REDACTED]`` (e.g. ``metadata.email``).    patterns: Regex patterns applied to all string values.    replacement: Replacement string for matches.    callables: Custom callables ``(trace) -> trace`` applied last.    drop_content: If ``True``, strip message content from LLM request/response.

plural.tracing.Redactor(*, fields: 'set[str] | None' = None, patterns: 'list[str] | None' = None, replacement: 'str' = '[REDACTED]', callables: 'list[Callable[[Trace], Trace]] | None' = None, drop_content: 'bool' = False) -> 'None'

apply(self, trace: 'Trace') -> 'Trace'

Args:    trace: The original trace. Returns:    A redacted deep copy.

Args:    api_key: Anthropic API key.    base_url: API base URL.    timeout_s: Request timeout in seconds.    default_headers: Extra headers.    anthropic_version: Value for the ``anthropic-version`` header.

plural.providers.anthropic.AnthropicProvider(api_key: 'str', *, base_url: 'str | None' = None, timeout_s: 'float' = 60.0, default_headers: 'dict[str, str] | None' = None, anthropic_version: 'str' = '2023-06-01') -> 'None'

chat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

stream(self, request: 'ChatRequest') -> 'Iterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

achat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

astream(self, request: 'ChatRequest') -> 'AsyncIterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

close(self) -> 'None'

aclose(self) -> 'None'

plural.providers.azure.AzureOpenAIProvider(api_key: 'str', *, endpoint: 'str | None' = None, deployments: 'dict[str, str] | None' = None, api_version: 'str | None' = None, use_bearer_auth: 'bool' = False, base_url: 'str | None' = None, region: 'str' = 'us', name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.openai_compatible.BasetenProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.bedrock.BedrockProvider(api_key: 'str | None' = None, *, region: 'str' = 'us-east-1', models: 'dict[str, str] | None' = None, access_key_id: 'str | None' = None, secret_access_key: 'str | None' = None, session_token: 'str | None' = None, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None) -> 'None'

chat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

stream(self, request: 'ChatRequest') -> 'Iterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

achat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

astream(self, request: 'ChatRequest') -> 'AsyncIterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

close(self) -> 'None'

aclose(self) -> 'None'

plural.providers.openai_compatible.DeepSeekProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.openai_compatible.FireworksProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

Args:    api_key: Google AI Studio API key.    base_url: API base URL.    timeout_s: Request timeout in seconds.    default_headers: Extra headers.    include_thoughts: Whether to ask Gemini for its thought summaries.        Gemini reasons whether or not they are requested, and withholds them        unless asked, which makes a thinking model look like a stalled one.

plural.providers.google.GoogleProvider(api_key: 'str', *, base_url: 'str | None' = None, timeout_s: 'float' = 60.0, default_headers: 'dict[str, str] | None' = None, include_thoughts: 'bool' = True) -> 'None'

chat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

stream(self, request: 'ChatRequest') -> 'Iterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

achat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

astream(self, request: 'ChatRequest') -> 'AsyncIterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

close(self) -> 'None'

aclose(self) -> 'None'

plural.providers.openai_compatible.GroqProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.openai_compatible.MetaProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.openai_compatible.MistralProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.openai_compatible.MoonshotProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

Args:    api_key: Provider API key.    base_url: API base URL.    name: Provider slug used in traces and errors.    timeout_s: Request timeout in seconds.    default_headers: Extra headers.    organization: Optional OpenAI organization header.    strip_model_prefix: Whether to strip ``author/`` from model ids.    http_transport: Transport for synchronous requests, such as one that        refuses private addresses. ``None`` uses httpx's default.    async_http_transport: Transport for asynchronous requests.

plural.providers.openai_compatible.OpenAICompatible(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

chat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

stream(self, request: 'ChatRequest') -> 'Iterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

achat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

astream(self, request: 'ChatRequest') -> 'AsyncIterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

close(self) -> 'None'

aclose(self) -> 'None'

plural.providers.openai_compatible.OpenAIProvider(api_key: 'str', *, transport: "Literal['auto', 'chat', 'responses']" = 'auto', **kwargs: 'Any') -> 'None'

chat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

achat(self, request: 'ChatRequest') -> 'ChatResponse'

Args:    request: Normalized chat request. Returns:    Normalized chat response.

stream(self, request: 'ChatRequest') -> 'Iterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

astream(self, request: 'ChatRequest') -> 'AsyncIterator[StreamChunk]'

Args:    request: Normalized chat request. Yields:    Normalized stream chunks.

close(self) -> 'None'

aclose(self) -> 'None'

Args:    api_key: OpenAI API key.    reasoning_summaries: Whether to ask for streamed reasoning summaries.        On by default, because a thinking model that emits nothing for ten        seconds is indistinguishable from a hung connection.    store: Whether to let OpenAI retain the response. Off by default to        match Chat Completions, which retains nothing.    **kwargs: Forwarded to :class:`OpenAICompatible`. Examples:    >>> provider = OpenAIResponsesProvider("sk-test")    >>> provider.endpoint_path    '/responses'

plural.providers.openai_responses.OpenAIResponsesProvider(api_key: 'str', *, reasoning_summaries: 'bool' = True, store: 'bool' = False, **kwargs: 'Any') -> 'None'

serves_exactly(request: 'ChatRequest') -> 'bool'

Args:    request: Normalized chat request. Returns:    ``False`` when something would have to be dropped or adjusted, which    is what tells the OpenAI dispatcher to prefer Chat Completions. Examples:    >>> from plural.types import Message    >>> hello = [Message(role="user", content="hi")]    >>> req = ChatRequest(model="openai/gpt-5.6", messages=hello, seed=7)    >>> OpenAIResponsesProvider.serves_exactly(req)    False

Adapters must provide sync and async chat/stream methods that acceptnormalized :class:`~plural.types.ChatRequest` objects and returnnormalized responses.

plural.providers.base.Provider(*args, **kwargs)

chat(self, request: 'ChatRequest') -> 'ChatResponse'

stream(self, request: 'ChatRequest') -> 'Iterator[StreamChunk]'

achat(self, request: 'ChatRequest') -> 'ChatResponse'

astream(self, request: 'ChatRequest') -> 'AsyncIterator[StreamChunk]'

Implementations are typically ``async def`` generators whose returntype is :class:`~typing.AsyncIterator`.

close(self) -> 'None'

aclose(self) -> 'None'

Attributes:    api_key: Provider API key.    base_url: API base URL including version prefix when required.    timeout_s: Request timeout in seconds.    default_headers: Extra headers sent with every request.    organization: Optional organization id (OpenAI-style).

plural.providers.openai_compatible.QwenProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.openai_compatible.TogetherProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.openai_compatible.XAIProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.providers.openai_compatible.ZhipuProvider(api_key: 'str', *, base_url: 'str | None' = None, name: 'str | None' = None, timeout_s: 'float | None' = None, default_headers: 'dict[str, str] | None' = None, organization: 'str | None' = None, strip_model_prefix: 'bool | None' = None, http_transport: 'httpx.BaseTransport | None' = None, async_http_transport: 'httpx.AsyncBaseTransport | None' = None) -> 'None'

plural.errors.AuthenticationError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.BudgetExceededError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.ConfigurationError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.ConflictError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.ContentFilterError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.ContextLengthError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.InvalidRequestError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.NotFoundError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

Args:    message: Human-readable description of the failure.    provider: Provider slug associated with the failure, if any.    status_code: HTTP status code, if the failure came from an HTTP response.    body: Raw response body or structured error payload, if available.    model: Model id that was being called, if known.

plural.errors.PluralError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

Formerly ``plural.TimeoutError``, which shadowed Python's built-in.

plural.errors.PluralTimeoutError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.ProviderUnavailable(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

plural.errors.RateLimitError(message: 'str', *, provider: 'str | None' = None, status_code: 'int | None' = None, body: 'Any' = None, model: 'str | None' = None) -> 'None'

Args:    error: The exception raised by a provider call. Returns:    ``True`` if the error is a known retryable plural error. Examples:    >>> is_retryable(PluralTimeoutError("timed out"))    True    >>> is_retryable(AuthenticationError("bad key"))    False

plural.errors.is_retryable(error: 'BaseException') -> 'bool'