Adapters

Adapter

Bases: ABC

Abstract base class for a conversation data source.

fetch abstractmethod

fetch() -> Iterator[Conversation]

Yield conversations from the source.

Implementations should be lazy — yielding one conversation at a time — so users can stream large datasets without loading everything into memory. Wrap with collect() if a list is needed.

collect

collect() -> list[Conversation]

Materialize all conversations from fetch() into a list.

File-based

JSONAdapter

JSONAdapter(path: Path | str, *, format: JsonFormat = 'auto')

Bases: Adapter

Read conversations from a JSON or JSONL file.

CSVAdapter

CSVAdapter(path: Path | str, *, delimiter: str = ',', role_mapping: Mapping[str, Role] | None = None)

Bases: Adapter

Read conversations from a CSV file (one row per message).

API-based

IntercomAdapter

IntercomAdapter(access_token: str | None = None, *, per_page: int = 50, max_conversations: int | None = None, client: Client | None = None)

Bases: Adapter

Fetch conversations from Intercom.

Configure the adapter.

Parameters:

Name	Type	Description	Default
access_token	str | None	Intercom access token. Defaults to the INTERCOM_ACCESS_TOKEN environment variable.	None
per_page	int	Page size for the list endpoint. Max 150.	50
max_conversations	int | None	Optional cap on total conversations fetched.	None
client	Client | None	Pre-configured httpx Client. If None, one is created with the access token and a 30-second timeout. Injecting a client is the main extension point for testing and custom networking.	None

ZendeskAdapter

ZendeskAdapter(subdomain: str | None = None, *, email: str | None = None, api_token: str | None = None, oauth_token: str | None = None, per_page: int = 100, max_conversations: int | None = None, bot_user_ids: Sequence[int | str] | None = None, client: Client | None = None)

Bases: Adapter

Fetch tickets (as conversations) from Zendesk.

Configure the adapter.

Parameters:

Name	Type	Description	Default
subdomain	str | None	Zendesk subdomain. Defaults to ZENDESK_SUBDOMAIN env.	None
email	str | None	Zendesk user email (with API token auth). Defaults to ZENDESK_EMAIL.	None
api_token	str | None	Zendesk API token (paired with email for basic auth). Defaults to ZENDESK_API_TOKEN.	None
oauth_token	str | None	Alternative OAuth bearer token. If given, email and api_token are ignored. Defaults to ZENDESK_OAUTH_TOKEN.	None
per_page	int	Page size for list endpoints.	100
max_conversations	int | None	Optional cap on total tickets fetched.	None
bot_user_ids	Sequence[int | str] | None	User IDs representing bot accounts. Comments from these users map to Role.BOT.	None
client	Client | None	Pre-configured httpx Client. Injecting one bypasses auth resolution and is the main extension point for testing.	None