Client SDK · Chat

Text helpers.

Filter a chat stream down to assistant text with the text-only helpers.

These helpers filter the event stream to just text — useful when you only need the response text and don't care about tool calls, usage, or status events.

`chat.stream_text(...)`

An async generator that yields raw string deltas. Raises SafetyReplaceError when the server replaces the output (safety filter). Raises MatildaStreamError on stream errors.

Python

from matilda_client import MatildaClient, SafetyReplaceError


async def main():
    async with MatildaClient(token="...") as client:
        try:
            async for chunk in client.chat.stream_text(input="Write a haiku."):
                print(chunk, end="", flush=True)
        except SafetyReplaceError as err:
            print(f"\nSafety replace: {', '.join(err.categories)}")

Note

Why raise on safety replace? The original text has already been yielded to the consumer by the time the replace event arrives. Raising forces the consumer to handle the replacement explicitly — silently dropping it would lose the replacement message.

`chat.create_text(...)`

Non-streaming convenience that returns just the final output text. Safety replace is handled naturally — the replacement text is returned. Raises MatildaStreamError if the stream produced any error events.

Python

text = await client.chat.create_text(input="What is 2 + 2?")
print(text)  # "4"

`SafetyReplaceError`

Python

class SafetyReplaceError(MatildaError):
    categories: list[str]
    # args[0] (str(err)) = replacement content (or empty string)