Component

Components that protect PII around another component.

PrivacyComponent(component, backend, mask_inputs, restore_output=True, value_adapters=None)

Bases: Component

Mask selected inputs of a component, call it, and restore the known placeholders in its result.

Each invocation opens its own PrivacySession, so all selected inputs and the result share one mapping, and concurrent invocations never share a mapping. The wrapper exposes the wrapped component's input_params and tool schema, so it works anywhere the wrapped component works, including gllm_pipeline.steps.step().

The wrapper fails closed, and every masking or restoring failure is a BasePrivacyError: 1. If masking fails, the wrapped component is not called. If restoring fails, the result is discarded. 2. A privacy error that the backend raises propagates unchanged. With TextAnonymizerBackend, a detection failure is a PrivacyRuntimeError or a remote recognizer error. Any other backend exception becomes MaskingError or RestorationError. 3. A selected value that has no masking rule raises UnsupportedValueError. Add a PrivacyValueAdapter to support its type.

Errors raised by the wrapped component propagate unchanged, and cancellation is never converted to a privacy error. The wrapper's own trace span records "[REDACTED]" instead of its input and output, and its logs contain no input, output, or mapping values. The wrapped component's span records the masked input when I/O capture is on.

Only the completed return value is restored. Events that the wrapped component streams through event_emitter still contain placeholders. The wrapper does not detect new PII that the wrapped component generates.

Example

private_synthesizer = PrivacyComponent(
    component=response_synthesizer,
    backend=TextAnonymizerBackend(text_analyzer=TextAnalyzer(), entities=["PERSON"], language="id"),
    mask_inputs=["query", "chunks"],
)
answer = await private_synthesizer.run(query=user_query, chunks=retrieved_chunks)

Initialize the wrapper.

Parameters:

Name	Type	Description	Default
component	Component	The component to wrap. The wrapper does not modify it.	required
backend	PrivacyBackend	Opens the masking session of each invocation.	required
mask_inputs	Sequence[str]	Names of the wrapped component's arguments to mask. Arguments that a call does not pass are skipped, so the wrapped component's default values are not masked.	required
restore_output	bool | Sequence[str]	True restores the whole result. A sequence of field names restores only those fields of a dict result. False returns the result with its placeholders. Defaults to True.	True
value_adapters	Sequence[PrivacyValueAdapter] | None	Adapters for types without a built-in rule. They are asked in order, before the built-in rules. Defaults to None.	None

Raises:

Type	Description
InvalidConfigError	If mask_inputs is empty, is a string, names event_emitter, or names an argument that the wrapped component does not accept, or if restore_output is a string or an empty sequence.

input_params property

Return the wrapped component's input parameter model.

Returns:

Type	Description
type[BaseModel] | None	type[BaseModel] | None: The wrapped component's input_params.

as_tool(name=None, description=None, title=None)

Convert the wrapped component into a tool that masks and restores like this wrapper.

The tool has the wrapped component's name, description, and input schema.

Parameters:

Name	Type	Description	Default
name	str | None	Identifier for the tool. Defaults to the wrapped component's class name.	None
description	str | None	Summary of the tool. Defaults to the wrapped main method's docstring.	None
title	str | None	Display title for the tool. Defaults to None.	None

Returns:

Name	Type	Description
Tool	Tool	The privacy-aware tool. Calling it raises InvalidToolArgumentsError if the arguments do not match the wrapped main method's signature.

Raises:

Type	Description
RuntimeError	If the wrapped component does not declare a main method.

execute(**kwargs) async

Mask the selected inputs, run the wrapped component, and restore its result.

Parameters:

Name	Type	Description	Default
**kwargs	Any	The arguments of the wrapped component.	{}

Returns:

Name	Type	Description
Any	Any	The wrapped component's result, restored as configured by restore_output.

Raises:

Type	Description
BasePrivacyError	If masking or restoring fails. The backend's privacy error propagates unchanged.
MaskingError	If the backend raises another exception while masking. The wrapped component is not called.
RestorationError	If the backend raises another exception while restoring.
UnsupportedValueError	If a selected input or the restored result contains an unsupported value.

release_resources() async

Release the wrapped component's resources.

PrivacyValueAdapter

Bases: Protocol

Mask or restore the text inside a type that PrivacyComponent does not support by itself.

PrivacyComponent asks its adapters in order and uses the first one whose supports returns True, before its built-in rules. The same adapter is used to mask inputs and to restore the result.

Example

class MessageAdapter:
    def supports(self, value: object) -> bool:
        return isinstance(value, Message)

    async def transform(self, value: object, transform: ValueTransform) -> object:
        assert isinstance(value, Message)
        return Message(role=value.role, contents=await transform(value.contents))

supports(value)

Return whether this adapter handles the value.

Parameters:

Name	Type	Description	Default
value	object	A selected argument, a result, or a value nested inside one.	required

Returns:

Name	Type	Description
bool	bool	True if transform should handle the value.

transform(value, transform) async

Return a copy of the value with its text masked or restored.

Do not mutate the value. Call transform on each part that holds text. It masks or restores a string, and handles nested values with the same rules as PrivacyComponent, including the other adapters.

Parameters:

Name	Type	Description	Default
value	object	A value for which supports returned True.	required
transform	ValueTransform	Masks or restores a nested value, depending on the current direction.	required

Returns:

Name	Type	Description
object	object	The transformed copy.