pi_llm.providers.faux

faux

Deterministic mock LLM provider for testing.

Provides register_faux_provider() which registers a fake API provider that returns scripted responses, simulating streaming events without hitting any real LLM API. Useful for unit and integration tests.

FauxContentBlock = TextContent | ThinkingContent | ToolCall module-attribute

Content block types that can appear in a faux assistant message.

FauxResponseFactory = Callable[[Context, StreamOptions | None, dict[str, int], Model], 'AssistantMessage'] module-attribute

Callable (context, options, state, model) -> AssistantMessage that builds a response dynamically. Can also be async.

FauxResponseStep = AssistantMessage | FauxResponseFactory module-attribute

A scripted response: either a static message or a factory function.

FauxModelDefinition(id, name=None, reasoning=False, input_types=(lambda: ['text', 'image'])(), cost=None, context_window=128000, max_tokens=16384) dataclass

Definition for a mock model.

RegisterFauxProviderOptions(api=None, provider=None, models=None, tokens_per_second=None, token_size_min=None, token_size_max=None) dataclass

Options for register_faux_provider().

FauxProviderRegistration(api, models, state, *, _set_responses, _append_responses, _get_pending, _unregister)

Handle returned by register_faux_provider().

Use this to configure scripted responses and inspect call state.

Attributes:

Name	Type	Description
api		The API name this provider was registered under.
models		List of mock Model instances.
state		Dict with callCount tracking total stream calls.

get_model(model_id=None)

Get a mock model by ID, or the first model if no ID given.

set_responses(responses)

Replace the scripted response queue.

append_responses(responses)

Add responses to the end of the queue.

get_pending_response_count()

Return the number of queued responses remaining.

unregister()

Remove this provider from the registry.

faux_text(text)

Create a TextContent block for scripted responses.

faux_thinking(thinking)

Create a ThinkingContent block for scripted responses.

faux_tool_call(name, arguments, *, id=None)

Create a ToolCall block for scripted responses.

faux_assistant_message(content, *, stop_reason='stop', error_message=None, response_id=None, timestamp=None)

Build a complete AssistantMessage for scripted responses.

Parameters:

Name	Type	Description	Default
content	str | FauxContentBlock | list[FauxContentBlock]	Text string, single content block, or list of blocks.	required
stop_reason	str	Stop reason (default "stop").	'stop'
error_message	str | None	Error description if stop_reason is "error".	None
response_id	str | None	Provider-assigned response ID.	None
timestamp	int | None	Unix timestamp in ms (defaults to current time).	None

register_faux_provider(options=None)

Register a deterministic mock LLM provider.

Returns a FauxProviderRegistration that lets you queue scripted AssistantMessage responses. Each call to the registered stream function pops the next response and simulates streaming events.

Parameters:

Name	Type	Description	Default
options	RegisterFauxProviderOptions | None	Configuration (API name, models, token speed, etc.).	None

Returns:

Type	Description
FauxProviderRegistration	A registration handle for managing responses and models.