sdialog

This package provides utilities for generating synthetic dialogues using instruction-tuned large language models (LLMs). Dialogues are generated primarily via role-playing, where each agent is defined by a Persona object. The package supports dialogue orchestration, context management, and flexible serialization for downstream tasks.

Main components:

  • Dialog, Turn, Event: Data structures for representing dialogues and their events.

  • Context, Persona and Agent: For defining and simulating role-played agents in a given context.

  • Orchestrators: For controlling agent behavior during dialogue generation.

  • Evaluation: Utilities and metrics for assessing dialogue quality (coherence, turn balance, persona/goal adherence, safety screening, lexical/statistical reports) and for building reproducible evaluation pipelines.

  • Interpretability: Layer/token-level activation capture, inspection (Inspector, hooks), steering (directional modulation of representations), and instruction extraction utilities (see interpretability.py).

class sdialog.Turn(*, speaker: str | None = None, text: str)

Bases: BaseModel

Represents a single turn in a dialogue.

Parameters:
  • speaker (Optional[str]) – The name or role of the speaker.

  • text (str) – The utterance text for this turn.

speaker: str | None
text: str
prompt() → str

Generates a prompt string for this turn.

print()
class sdialog.Event(*, agent: str | None = None, action: str, actionLabel: str | None = None, content: str | Dict | List, timestamp: int)

Bases: BaseModel

Represents an event in a dialogue, which may be an utterance, instruction, or other action.

Parameters:
  • agent (Optional[str]) – The agent responsible for the event (e.g., “user”, “system”).

  • action (str) – The type of event (e.g., “utter”, “instruct”).

  • actionLabel (Optional[str]) – A label describing the action (e.g., type of instruction).

  • content (Union[str, Dict, List]) – The content of the event.

  • timestamp (int) – The Unix timestamp of the event.

agent: str | None
action: str
actionLabel: str | None
content: str | Dict | List
timestamp: int
class sdialog.Dialog(*, version: str | None = <factory>, timestamp: str | None = <factory>, model: str | Dict | None = None, seed: int | None = None, id: int | str | None = <factory>, parentId: int | str | None = None, complete: bool | None = None, personas: dict[str, ~typing.Any] | None=None, context: str | dict[str, ~typing.Any] | None=None, scenario: dict | str | None = None, turns: List[Turn] | None = <factory>, events: List[Event] | None = None, annotations: str | dict[str, ~typing.Any] | None=None, notes: Any | None = None)

Bases: BaseModel

A pydantic model representing a conversational dialogue with rich metadata, container-like access to turns, text utilities, analytics, and I/O helpers.

Parameters:
  • version (Optional[str]) – Version of the dialogue format.

  • timestamp (Optional[str]) – Timestamp of dialogue creation.

  • model (Optional[Union[str, Dict]]) – The model used to generate the dialogue.

  • seed (Optional[int]) – The random seed used for generation.

  • id (Optional[Union[int, str]]) – Unique ID for the dialogue.

  • parentId (Optional[Union[int, str]]) – ID of the parent dialogue, if any.

  • complete (Optional[bool]) – Whether the dialogue is complete.

  • personas (Optional[dict[str, Any]]) – Any is a subclass of MetaPersona.

  • context (Optional[Union[str, dict[str, Any]]]) – Shared context for the dialogue.

  • scenario (Optional[Union[dict, str]]) – Scenario description or metadata.

  • turns (Optional[List[Turn]]) – List of dialogue turns.

  • events (Optional[List[Event]]) – List of dialogue events (optional).

  • annotations (Optional[Union[str, dict[str, Any]]]) – Annotation metadata associated with the dialogue, such as labels or structured annotation outputs.

  • notes (Optional[str]) – Free-text notes or comments about the dialogue.

version: str | None
timestamp: str | None
model: str | Dict | None
seed: int | None
id: int | str | None
parentId: int | str | None
complete: bool | None
personas: dict[str, Any] | None
context: str | dict[str, Any] | None
scenario: dict | str | None
turns: List[Turn] | None
events: List[Event] | None
annotations: str | dict[str, Any] | None
notes: Any | None
lower(in_place: bool = True) → Dialog

Apply str.lower() to every turn’s text.

Parameters:

in_place (bool) – If True modify this Dialog in place; otherwise return a cloned transformed Dialog.

Returns:

The modified (or cloned) Dialog.

Return type:

Dialog

upper(in_place: bool = True) → Dialog

Apply str.upper() to every turn’s text.

Parameters:

in_place (bool) – If True modify this Dialog in place; otherwise return a cloned transformed Dialog.

Returns:

The modified (or cloned) Dialog.

Return type:

Dialog

title(in_place: bool = True) → Dialog

Apply str.title() to every turn’s text.

Parameters:

in_place (bool) – If True modify this Dialog in place; otherwise return a cloned transformed Dialog.

Returns:

The modified (or cloned) Dialog.

Return type:

Dialog

capitalize(in_place: bool = True) → Dialog

Apply str.capitalize() to every turn’s text.

Parameters:

in_place (bool) – If True modify this Dialog in place; otherwise return a cloned transformed Dialog.

Returns:

The modified (or cloned) Dialog.

Return type:

Dialog

strip(chars: str = None, in_place: bool = True) → Dialog

Apply str.strip(chars) to every turn’s text.

Parameters:
  • chars (Optional[str]) – Characters to strip; if None, default whitespace is stripped.

  • in_place (bool) – If True modify this Dialog in place; otherwise return a cloned transformed Dialog.

Returns:

The modified (or cloned) Dialog.

Return type:

Dialog

replace(old: str, new: str, count: int = -1, in_place: bool = True) → Dialog

Apply str.replace(old, new, count) to every turn’s text. If count < 0 all occurrences are replaced.

Parameters:
  • old (str) – Substring to be replaced.

  • new (str) – Replacement substring.

  • count (int) – Maximum number of replacements per text; if < 0 replace all.

  • in_place (bool) – If True modify this Dialog in place; otherwise return a cloned transformed Dialog.

Returns:

The modified (or cloned) Dialog.

Return type:

Dialog

re_sub(pattern: str | Pattern, repl: str | callable, count: int = 0, flags: int = 0, in_place: bool = True) → Dialog

Apply re.sub(pattern, repl, text, count=count, flags=flags) to every turn’s text. If pattern is a compiled regex, flags are ignored.

Parameters:
  • pattern (Union[str, Pattern]) – Regex pattern (string or compiled).

  • repl (Union[str, Callable]) – Replacement string or callable.

  • count (int) – Max substitutions per text (0 means unlimited).

  • flags (int) – Regex flags (ignored if compiled pattern provided).

  • in_place (bool) – Mutate this Dialog if True; else return a cloned transformed Dialog.

Returns:

The modified (or cloned) Dialog.

Return type:

Dialog

length(mode: str = 'words', words_per_minute: int = 130) → int

Returns the length of the dialogue according to the specified mode (number of words by default).

Parameters:
  • mode (str) –

    The mode for measuring length. Options:

    • "turns": Number of turns (default)

    • "words": Total number of words in all turns

    • "minutes" / "time": Approximate duration in minutes (words_per_minute/minute)

  • words_per_minute (int) – Words per minute for “minutes” mode (default is 130, which is a common estimate).

Returns:

The computed length according to the mode.

Return type:

int

Raises:

ValueError – If an unknown mode is specified.

clone(new_id: int = None) → Dialog

Creates a deep copy of the dialogue.

Parameters:

new_id (int, optional) – Optional ID to assign to the cloned dialog. If None, a new universal ID is generated.

Returns:

A new Dialog object that is a deep copy of this one, with updated id and parentId.

Return type:

Dialog

description(turn_template: str = None)

Returns a human-readable string representation of the dialogue.

Parameters:

turn_template (str) – Template for formatting each turn (default “{speaker}: {text}”).

Returns:

The formatted dialogue.

Return type:

str

prompt() → str

Generates a prompt string for the entire dialogue.

json(string: bool = False, indent: int = 2, ensure_ascii: bool = False)

Serializes the dialogue to JSON.

Parameters:
  • string (bool) – If True, returns a JSON string; otherwise, returns a dict.

  • indent (int) – Indentation level for pretty-printing.

Returns:

The serialized dialogue.

Return type:

Union[str, dict]

print(*a, **kw)

Pretty-prints a dialogue to the console, with optional scenario and orchestration details.

Parameters:
  • scenario (bool) – If True, prints scenario information.

  • orchestration (bool) – If True, prints also orchestration events.

  • think (bool) – If True, prints “thinking” events.

  • all (bool) – If True, prints all types of events.

to_file(path: str = None, type: str = 'auto', makedir: bool = True, overwrite: bool = True, ensure_ascii: bool = False)

Saves the dialogue to a file in JSON, CSV, or plain text format.

Parameters:
  • path (str) – Output file path, if not provided, uses the same path used to load the dialogue.

  • type (str) – “json”, “csv”, “txt”, or “auto” (determined by file extension).

  • makedir (bool) – If True, creates parent directories as needed.

  • overwrite (bool) – If False and the file exists, raise FileExistsError instead of overwriting.

  • ensure_ascii (bool) – If True and type is “json”, escape non-ASCII characters in the output.

save(path: str = None, type: str = 'auto', makedir: bool = True, overwrite: bool = True, ensure_ascii: bool = False)

Alias for to_file().

Parameters:
  • path (str) – Output file path, if not provided, uses the same path used to load the dialogue.

  • type (str) – “json”, “csv”, “txt”, or “auto” (determined by file extension).

  • makedir (bool) – If True, creates parent directories as needed.

  • overwrite (bool) – If False and the file exists, raise FileExistsError instead of overwriting.

  • ensure_ascii (bool) – If True and type is “json”, escape non-ASCII characters in the output.

to_audio(path: str = None, preset: str = None, voices: str | dict = 'db', stereo: bool = False, sample_rate: int = 16000, seed: int = None, **kwargs)

Converts the dialogue into audio, with ground-truth annotations (who speaks when, what is said).

Uses the Dia2 dialogue TTS model by default. See sdialog.audio.synthesis.to_audio() for all the options (voice_database, tts, pauses, overlap, max_overlap, reverb, noise, channel, level_jitter_db, audio_format, …).

Example:

audio = dialog.to_audio()                                   # clean, persona-matched voices
audio = dialog.to_audio(preset="call_center", stereo=True)  # one channel per speaker
audio = dialog.to_audio(voices="random", reverb="large", noise=10, overlap=0.2, seed=0)
audio.save("output/dialog")                                 # .wav + .json + .rttm
Parameters:
  • path (str) – If given, saves <path>.wav (.flac with audio_format="flac"), <path>.json (annotations) and <path>.rttm.

  • preset (str) – Scene preset: “clean”, “conversational”, “room”, “call_center”, “far_field” or “hard”.

  • voices (Union[str, dict]) – “db” (voice database matching the personas), “design” (designed from the persona description), “random”, or a {speaker: voice} dictionary.

  • stereo (bool) – If True, output one channel per speaker; otherwise mono.

  • sample_rate (int) – Output sample rate (Hz).

  • seed (int) – Random seed for reproducible audio.

Returns:

The audio and its annotations.

Return type:

sdialog.audio.DialogAudio

Raises:
  • ImportError – If the audio dependencies are not installed.

  • TypeError – If arguments of the removed legacy audio pipeline are given.

static from_huggingface(repo_id: str, local_dir: str = None, collapse_consecutive_speakers: bool = False, collapse_separator: str = '\n') → List[Dialog] | Dict[str, List[Dialog]]

Loads dialogues from a HuggingFace dataset.

This method downloads a dataset from HuggingFace Hub and loads dialogues from it. The dataset must follow the SDialog format with a ‘data’ folder containing dialogue files. If the data folder contains train/test/val split subdirectories, dialogues are loaded from all splits and returned as a dictionary mapping split names to dialogue lists. Otherwise, all dialogues from the data folder are returned as a single list.

Parameters:
  • repo_id (str) – HuggingFace repository ID (e.g., “sdialog/Primock-57”).

  • local_dir (str, optional) – Local directory to download to. If None, uses a temporary directory.

  • collapse_consecutive_speakers (bool) – If True, collapses consecutive turns by the same speaker.

  • collapse_separator (str) – Separator used when collapsing consecutive turns.

Returns:

List of dialogs or dict mapping splits to lists of dialogs.

Return type:

Union[List[Dialog], Dict[str, List[Dialog]]]

Raises:
  • ImportError – If huggingface_hub is not installed.

  • ValueError – If the dataset is not a valid sdialog dataset.

static from_folder(path: str, type: str = 'auto', txt_template: str = '{speaker}: {text}', csv_speaker_col: int | str = 'speaker', csv_text_col: int | str = 'text', collapse_consecutive_speakers: bool = False, collapse_separator: str = '\n') → List[Dialog]

Loads all dialogues from a folder.

Parameters:
  • path (str) – Path to the directory containing dialogue files.

  • type (str) – "json", "txt", "csv", "tsv", or "auto" (determined by file extension).

  • txt_template (str) – Template for parsing text dialogue turns (default “{speaker}: {text}”).

  • csv_speaker_col (Union[int, str]) – Column identifier for speaker in CSV/TSV files (can be index or header name).

  • csv_text_col (Union[int, str]) – Column identifier for text in CSV/TSV files (can be index or header name).

  • collapse_consecutive_speakers (bool) – If True, collapses consecutive turns by the same speaker into one turn.

  • collapse_separator (str) – String used to join texts when collapsing consecutive turns (default: "\n").

Returns:

A list of loaded dialogue objects from the folder.

Return type:

List[Dialog]

Raises:

ValueError – If the path is not a directory.

static from_file(path: str, type: str = 'auto', txt_template: str = '{speaker}: {text}', csv_speaker_col: int | str = 'speaker', csv_text_col: int | str = 'text', collapse_consecutive_speakers: bool = False, collapse_separator: str = '\n') → Dialog | List[Dialog]

Loads a dialogue from a file.

Parameters:
  • path (str) – Path to the dialogue file or directory. In case of a directory, all dialogues in the directory will be loaded and returned as a list of Dialog objects.

  • type (str) – "json", "txt", "csv", "tsv", or "auto" (determined by file extension).

  • txt_template (str) – Template for parsing text dialogue turns (default “{speaker}: {text}”).

  • csv_speaker_col (Union[int, str]) – Column identifier for speaker in CSV/TSV files (can be index or header name).

  • csv_text_col (Union[int, str]) – Column identifier for text in CSV/TSV files (can be index or header name).

  • collapse_consecutive_speakers (bool) – If True, collapses consecutive turns by the same speaker into one turn.

  • collapse_separator (str) – String used to join texts when collapsing consecutive turns (default: "\n").

Returns:

The loaded dialogue object.

Return type:

Dialog

Raises:

ValueError – If the file format is not recognized or if required columns are missing.

classmethod open(path: str, type: str = 'auto', txt_template: str = '{speaker}: {text}', csv_speaker_col: int | str = 'speaker', csv_text_col: int | str = 'text', collapse_consecutive_speakers: bool = False, collapse_separator: str = '\n') → Dialog | List[Dialog]

Alias for from_file().

Parameters:
  • path (str) – Path to the dialogue file or directory.

  • type (str) – "json", "txt", "csv", "tsv", or "auto".

  • txt_template (str) – Template for parsing text dialogue turns.

  • csv_speaker_col (Union[int, str]) – Column identifier for speaker in CSV/TSV files.

  • csv_text_col (Union[int, str]) – Column identifier for text in CSV/TSV files.

  • collapse_consecutive_speakers (bool) – If True, collapses consecutive turns by the same speaker.

  • collapse_separator (str) – String used to join texts when collapsing consecutive turns.

Returns:

The loaded dialogue object or list of dialogue objects.

Return type:

Union[Dialog, List[Dialog]]

classmethod load(path: str, type: str = 'auto', txt_template: str = '{speaker}: {text}', csv_speaker_col: int | str = 'speaker', csv_text_col: int | str = 'text', collapse_consecutive_speakers: bool = False, collapse_separator: str = '\n') → Dialog | List[Dialog]

Alias for from_file().

Parameters:
  • path (str) – Path to the dialogue file or directory.

  • type (str) – "json", "txt", "csv", "tsv", or "auto".

  • txt_template (str) – Template for parsing text dialogue turns.

  • csv_speaker_col (Union[int, str]) – Column identifier for speaker in CSV/TSV files.

  • csv_text_col (Union[int, str]) – Column identifier for text in CSV/TSV files.

  • collapse_consecutive_speakers (bool) – If True, collapses consecutive turns by the same speaker.

  • collapse_separator (str) – String used to join texts when collapsing consecutive turns.

Returns:

The loaded dialogue object or list of dialogue objects.

Return type:

Union[Dialog, List[Dialog]]

classmethod load_folder(path: str, type: str = 'auto', txt_template: str = '{speaker}: {text}', csv_speaker_col: int | str = 'speaker', csv_text_col: int | str = 'text', collapse_consecutive_speakers: bool = False, collapse_separator: str = '\n') → List[Dialog]

Alias for from_folder().

Parameters:
  • path (str) – Path to the directory containing dialogue files.

  • type (str) – "json", "txt", "csv", "tsv", or "auto".

  • txt_template (str) – Template for parsing text dialogue turns.

  • csv_speaker_col (Union[int, str]) – Column identifier for speaker in CSV/TSV files.

  • csv_text_col (Union[int, str]) – Column identifier for text in CSV/TSV files.

  • collapse_consecutive_speakers (bool) – If True, collapses consecutive turns by the same speaker.

  • collapse_separator (str) – String used to join texts when collapsing consecutive turns.

Returns:

A list of loaded dialogue objects from the folder.

Return type:

List[Dialog]

static from_str(dialog_text: str, template: str = '{speaker}: {text}', default_speakers: List[str] = None, id: str | int = None) → Dialog

Creates a Dialog object from a string representation of a dialogue.

Parameters:
  • dialog_text (str) – The dialogue text, with each turn on a new line.

  • template (str) – The template for parsing each turn. Default is “{speaker}: {text}”.

  • default_speakers (List[str]) – Optional list of default speakers to use if no present in the text or template. The speakers will be assigned in order of appearance, in alternating turns. Default is None (speaker field will be empty in each turn).

  • id (Union[str, int]) – Optional ID for the dialogue. If not provided, a universal ID will be generated.

Returns:

The created Dialog object.

Return type:

Dialog

static from_dict(data: dict)

Creates a Dialog object from a dictionary.

Parameters:

data (dict) – The dictionary containing dialogue data.

Returns:

The created Dialog object.

Return type:

Dialog

static from_json(json_str: str)

Creates a Dialog object from a JSON string.

Parameters:

json_str (str) – The JSON string containing dialogue data.

Returns:

The created Dialog object.

Return type:

Dialog

rename_speaker(old_name: str, new_name: str, case_sensitive: bool = False, in_events: bool = True) → Dialog

Renames all occurrences of a speaker in the dialogue’s turns (and optionally events).

Parameters:
  • old_name (str) – The current speaker name to replace.

  • new_name (str) – The new speaker name.

  • case_sensitive (bool) – Whether to match speaker names case-sensitively (default: False).

  • in_events (bool) – Whether to also rename in events’ agent fields (default: True).

Returns:

Self (the same Dialog instance) after in-place modification.

Return type:

Dialog

get_speakers(keep_case: bool = True) → List[str]

Returns a list of unique speaker names in the dialogue.

Parameters:

keep_case (bool) – Whether to keep the original case of speaker names or convert them to lowercase (default: True).

Returns:

A list of unique speaker names.

Return type:

List[str]

filter(speaker: str) → Dialog

Filters the dialogue turns by speaker.

Parameters:

speaker (str) – The speaker name to filter by (case-insensitive).

Returns:

A new Dialog containing only that speaker’s turns; returns None if speaker not found.

Return type:

Optional[Dialog]

class sdialog.Context(*, location: str | None = None, datetime: str | None = None, environment: str | None = None, objects: str | List[str] | None = None, participants_shared_knowledge: str | None = None, circumstances: str | List[str] | None = None, goals: str | List[str] | None = None, constraints: str | List[str] | None = None, topics: str | List[str] | None = None, style_guidelines: str | List[str] | None = None, notes: str | None = None)

Bases: BaseAttributeModel

Dialogue-shared context class.

Parameters:
  • location (Optional[str]) – Physical or virtual location where the dialogue occurs.

  • datetime (Optional[str]) – Timestamp or temporal setting relevant to the dialogue.

  • environment (Optional[str]) – Physical environment description, environmental conditions, or contextual atmosphere.

  • objects (Optional[Union[str, List[str]]]) – Relevant objects (single value or list of values).

  • participants_shared_knowledge (Optional[str]) – Information all participants are assumed to know.

  • circumstances (Optional[Union[str, List[str]]]) – Situational circumstances impacting the dialogue.

  • goals (Optional[Union[str, List[str]]]) – Stated or implicit goals of the participants.

  • constraints (Optional[Union[str, List[str]]]) – Limitations or constraints affecting actions or dialogue.

  • topics (Optional[Union[str, List[str]]]) – Main topics or themes (single or list).

  • style_guidelines (Optional[Union[str, List[str]]]) – Stylistic or formatting guidelines to follow.

  • notes (Optional[str]) – Additional free-form contextual notes.

location: str | None
datetime: str | None
environment: str | None
objects: str | List[str] | None
participants_shared_knowledge: str | None
circumstances: str | List[str] | None
goals: str | List[str] | None
constraints: str | List[str] | None
topics: str | List[str] | None
style_guidelines: str | List[str] | None
notes: str | None
static attributes(_cls=<class 'sdialog.Context'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.Instruction(*, text: str = None, events: Event | List[Event] | None = None)

Bases: BaseModel

Represents an instruction to an agent, optionally with associated events.

Parameters:
  • text (str) – The instruction text.

  • events (Optional[Union[Event, List[Event]]]) – Associated event(s), either a single Event or a list of Events.

text: str
events: Event | List[Event] | None

sdialog.base

Model foundations for sdialog root module.

Provides:

  • Metadata: common provenance fields (version, timestamp, ids).

  • BaseAttributeModel: pydantic-based abstract base for persona/context-like objects with cloning, serialization, and dynamic subclass discovery utilities.

class sdialog.base.Metadata(*, version: str | None = <factory>, timestamp: str | None = <factory>, model: str | Dict | None = None, seed: int | None = None, id: int | str | None = <factory>, parentId: int | str | None = None, className: str = None, notes: str | None = None)

Bases: BaseModel

Metadata class for object, context and other objects.

Parameters:
  • version (Optional[str]) – Version of the object format (matches sdialog version).

  • timestamp (Optional[str]) – Timestamp of when the object was generated.

  • model (Optional[str]) – The model used to generate the object.

  • seed (Optional[int]) – The random seed used for object generation.

  • id (Optional[Union[int, str]]) – Unique identifier for the object.

  • parentId (Optional[Union[int, str]]) – ID of the parent object, if any.

  • notes (Optional[str]) – Free-text notes or comments about the generated object.

  • className (str) – The class name of the object (a subclass of BaseAttributeModel).

version: str | None
timestamp: str | None
model: str | Dict | None
seed: int | None
id: int | str | None
parentId: int | str | None
className: str
notes: str | None
class sdialog.base.BaseAttributeModel

Bases: BaseModel, ABC

Base class for defining an attribute-based object.

Features:

  • Strict field control.

  • Automatic static attributes() helper listing declared fields.

  • Metadata tracking (id, parentId, version, timestamp).

  • Clone with optional field overrides and proper lineage linkage.

  • JSON / prompt serialization helpers.

clone(new_id: int = None, **kwargs) → BaseAttributeModel

Create a deep copy of this object with optional attribute overrides.

Metadata handling:

  • parentId of clone = original id (if present).

  • id of clone = new_id if provided else a new universal id.

  • Other metadata fields are copied.

Parameters:
  • new_id (Optional[int]) – Optional new unique id for the clone.

  • kwargs (Any) – Field overrides applied to the cloned instance.

Returns:

Independent cloned instance.

Return type:

BaseAttributeModel

description() → str

Returns a string description of the object’s attributes.

Returns:

Description of the object.

Return type:

str

print()

Pretty-prints the object, including its metadata information.

json(string: bool = False, indent=2, output_metadata: bool = True)

Serializes the object to JSON.

Parameters:
  • string (bool) – If True, returns a JSON string; otherwise, returns a dict.

  • indent (int) – Indentation level for pretty-printing.

  • output_metadata (bool) – Include the metadata in the serialization.

Returns:

The serialized object.

Return type:

Union[str, dict]

prompt() → str

Returns the textual representation of the object, used as part of the system prompt.

Returns:

JSON string without metadata (intended for prompt inclusion).

Return type:

str

to_file(path: str, makedir: bool = True)

Saves the object to a file in either JSON or plain text format.

Parameters:
  • path (str) – Output file path.

  • makedir (bool) – If True, creates parent directories as needed.

static from_file(path: str, object_class: BaseAttributeModel | None = None)

Load an object from a JSON file.

Parameters:
  • path (str) – Path to file.

  • object_class (Optional[BaseAttributeModel]) – Optional explicit subclass to force (bypasses className dispatch).

Returns:

Loaded instance.

Return type:

BaseAttributeModel

Raises:

ValueError – If metadata/className is missing or unknown.

static from_dict(data: dict, object_class: BaseAttributeModel | None = None)

Create an object instance from a dictionary.

Dispatch rules:

  • If object_class is provided and is a BaseAttributeModel subclass, it is used directly.

  • Else uses _metadata.className to resolve a registered subclass.

Parameters:
  • data (dict) – Source dictionary (must include _metadata.className).

  • object_class (Optional[BaseAttributeModel]) – Optional explicit subclass.

Returns:

Instantiated object.

Return type:

BaseAttributeModel

Raises:

ValueError – If className missing or cannot be resolved.

static from_json(json_str: str, object_class: BaseAttributeModel | None = None)

Create an object instance from a JSON string.

Parameters:
  • json_str (str) – JSON serialization including _metadata.className.

  • object_class (Optional[BaseAttributeModel]) – Optional explicit subclass override.

Returns:

Instantiated object.

Return type:

BaseAttributeModel


sdialog.personas

This module provides classes for defining personas (character profiles) and simulating agents that role-play these personas in synthetic dialogue generation.

sdialog.personas.BasePersona

Abstract base class for defining personas. Alias for sdialog.base.BaseAttributeModel

class sdialog.personas.Persona(*, name: str = '', age: int | str = '', race: str = '', gender: str = '', language: str = 'English', role: str = '', background: str = '', personality: str = '', circumstances: str = '', rules: str = '')

Bases: BaseAttributeModel

Standard persona class with common attributes for role-play.

Parameters:
  • name (str) – Name of the persona.

  • age (Union[int, str]) – Age of the persona (can be an int or a descriptive string like “middle-aged”).

  • race (str) – Race / ethnicity of the persona.

  • gender (str) – Gender of the persona.

  • language (str) – Preferred language of communication.

  • role (str) – Role, profession, or primary identity descriptor.

  • background (str) – Background or life history summary.

  • personality (str) – Personality traits summary (free text).

  • circumstances (str) – Current situational context (e.g., “recently moved”, “under stress”).

  • rules (str) – Constraints, style or behavioral rules to enforce.

name: str
age: int | str
race: str
gender: str
language: str
role: str
background: str
personality: str
circumstances: str
rules: str
static attributes(_cls=<class 'sdialog.personas.Persona'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.ExtendedPersona(*, name: str = '', age: int | str = '', race: str = '', gender: str = '', language: str = 'English', weight: str | int | float = '', height: str | int | float = '', voice_characteristics: str = '', occupation: str = '', education: str = '', socioeconomic_status: str = '', interests: str = '', hobbies: str = '', politeness: str = '', forgetfulness: str = '', attentiveness: str = '', communication_style: str = '', empathy_level: str = '', political_views: str = '', religious_beliefs: str = '')

Bases: BaseAttributeModel

Extended persona class with additional demographic, personality, and background attributes.

Parameters:
  • name (str) – Name of the persona.

  • age (Union[int, str]) – Age (numeric or descriptive string).

  • race (str) – Race / ethnicity.

  • gender (str) – Gender identity.

  • language (str) – Preferred language.

  • weight (Union[str, int, float]) – Weight (numeric with unit or descriptive string).

  • height (Union[str, int, float]) – Height (numeric with unit or descriptive string).

  • voice_characteristics (str) – Voice, accent, tone, pacing, etc.

  • occupation (str) – Current occupation or professional role.

  • education (str) – Education level or academic background.

  • socioeconomic_status (str) – Socioeconomic status descriptor.

  • interests (str) – General interests (comma-separated or free text).

  • hobbies (str) – Hobbies (comma-separated or free text).

  • politeness (str) – Politeness style/level.

  • forgetfulness (str) – Forgetfulness tendency.

  • attentiveness (str) – Attentiveness or focus tendency.

  • communication_style (str) – Style of communication (e.g., direct, verbose).

  • empathy_level (str) – Empathy level or descriptor.

  • political_views (str) – Political alignment (e.g., conservative, moderate, apolitical).

  • religious_beliefs (str) – Religious stance (e.g., religious, agnostic, atheist).

name: str
age: int | str
race: str
gender: str
language: str
weight: str | int | float
height: str | int | float
voice_characteristics: str
occupation: str
education: str
socioeconomic_status: str
interests: str
hobbies: str
politeness: str
forgetfulness: str
attentiveness: str
communication_style: str
empathy_level: str
political_views: str
religious_beliefs: str
static attributes(_cls=<class 'sdialog.personas.ExtendedPersona'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Customer(*, name: str = '', age: int | str = '', gender: str = '', language: str = 'English', customer_id: str | int = '', occupation: str = '', account_tenure: str = '', membership_level: str = '', loyalty_status: str = '', fidelity_score: str | float | int = '', issue: str = '', issue_category: str = '', issue_description: str = '', issue_history: str = '', desired_outcome: str = '', knowledge_domain: str = '', technical_expertise: str = '', sentiment: str = '', anger_level: str = '', tiredness: str = '', patience_level: str = '', politeness: str = '', personality: str = '', instruction_following: str = '', forgetfulness: str = '', times_called: int | str = '', preferred_channel: str = '', prior_interactions_summary: str = '', urgency: str = '', rules: str = '')

Bases: BaseAttributeModel

Persona for a customer in a customer service interaction.

Parameters:
  • name (str) – Customer name.

  • age (Union[int, str]) – Customer age (numeric or descriptive).

  • gender (str) – Customer gender.

  • language (str) – Preferred language.

  • customer_id (Union[str, int]) – Internal customer identifier.

  • occupation (str) – Customer occupation.

  • account_tenure (str) – How long they have been a customer (e.g., “2 years”).

  • membership_level (str) – Plan/tier (e.g., basic, premium).

  • loyalty_status (str) – Loyalty descriptor (e.g., loyal, at-risk).

  • fidelity_score (Union[str, float, int]) – Loyalty score (numeric or descriptive).

  • issue (str) – Short summary of current problem.

  • issue_category (str) – High-level category (billing, technical, etc.).

  • issue_description (str) – Detailed issue description.

  • issue_history (str) – Brief summary of related past issues.

  • desired_outcome (str) – Customer’s desired resolution / goal.

  • knowledge_domain (str) – Subject/domain familiarity (e.g., novice, expert).

  • technical_expertise (str) – Legacy field for backward compatibility.

  • sentiment (str) – Overall emotional tone (e.g., frustrated, neutral).

  • anger_level (str) – Anger intensity descriptor.

  • tiredness (str) – Fatigue level.

  • patience_level (str) – Patience descriptor.

  • politeness (str) – Politeness style (e.g., polite, curt).

  • personality (str) – Personality descriptor (e.g., analytical).

  • instruction_following (str) – Likelihood of following instructions.

  • forgetfulness (str) – Tendency to forget prior guidance.

  • times_called (Union[int, str]) – Number of prior contacts (numeric or descriptive).

  • preferred_channel (str) – Preferred support channel.

  • prior_interactions_summary (str) – Summary of earlier interactions.

  • urgency (str) – Perceived urgency (e.g., low, high).

  • rules (str) – Constraints or special handling notes.

name: str
age: int | str
gender: str
language: str
customer_id: str | int
occupation: str
account_tenure: str
membership_level: str
loyalty_status: str
fidelity_score: str | float | int
issue: str
issue_category: str
issue_description: str
issue_history: str
desired_outcome: str
knowledge_domain: str
technical_expertise: str
sentiment: str
anger_level: str
tiredness: str
patience_level: str
politeness: str
personality: str
instruction_following: str
forgetfulness: str
times_called: int | str
preferred_channel: str
prior_interactions_summary: str
urgency: str
rules: str
static attributes(_cls=<class 'sdialog.personas.Customer'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.SupportAgent(*, name: str = '', language: str = 'English', agent_id: str | int = '', role: str = 'Customer Support Agent', experience_years: int | str = '', product_scope: str = '', product_knowledge_level: str = '', communication_style: str = '', empathy_level: str = '', politeness: str = '', resolution_authority_level: str = '', escalation_policy: str = '', average_handle_time: int | float | str = '', adherence_notes: str = '', stress_tolerance: str = '', performance_notes: str = '', rules: str = '')

Bases: BaseAttributeModel

Persona for a customer service / support agent.

Parameters:
  • name (str) – Agent name.

  • language (str) – Working language.

  • agent_id (Union[str, int]) – Internal agent identifier.

  • role (str) – Agent role or queue designation.

  • experience_years (Union[int, str]) – Years (or range) of support experience.

  • product_scope (str) – Products or domains covered.

  • product_knowledge_level (str) – Knowledge depth (e.g., basic, expert).

  • communication_style (str) – Communication style (e.g., concise, empathetic).

  • empathy_level (str) – Empathy descriptor.

  • politeness (str) – Politeness level descriptor.

  • resolution_authority_level (str) – Authority level for resolutions/escalations.

  • escalation_policy (str) – Summary of escalation criteria/process.

  • average_handle_time (Union[int, float, str]) – Typical handling time (e.g., “6m”).

  • adherence_notes (str) – Notes on process or QA adherence.

  • stress_tolerance (str) – Stress handling capability descriptor.

  • performance_notes (str) – Performance KPIs or evaluation notes.

  • rules (str) – Internal rules, compliance reminders, or constraints.

name: str
language: str
agent_id: str | int
role: str
experience_years: int | str
product_scope: str
product_knowledge_level: str
communication_style: str
empathy_level: str
politeness: str
resolution_authority_level: str
escalation_policy: str
average_handle_time: int | float | str
adherence_notes: str
stress_tolerance: str
performance_notes: str
rules: str
static attributes(_cls=<class 'sdialog.personas.SupportAgent'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Patient(*, name: str = '', age: int | str = None, race: str = '', gender: str = '', language: str = 'English', forgetfulness: str | float = '', formality: str | float = '', hurriedness: str | float = '', openness: str | float = '', height: str | int | float = '', weight: str | int | float = '', occupation: str = '', marital_status: str = '', insurance: str = '', reason_for_visit: str = '', symptoms: str | List[str] = '', medical_history: str | List[str] = '', medical_conditions: str | List[str] = '', medications: str | List[str] = '', allergies: str | List[str] = '', family_history: str | List[str] = '')

Bases: BaseAttributeModel

Patient persona with essential / minimal plus behavioral and demographic attributes for dialogue generation.

Parameters:
  • name (str) – Patient name.

  • age (Union[int, str]) – Patient age (numeric or descriptive).

  • race (str) – Race / ethnicity.

  • gender (str) – Gender identity.

  • language (str) – Preferred communication language.

  • forgetfulness (Union[str, float]) – Forgetfulness tendency (qualitative or numeric).

  • formality (Union[str, float]) – Formality of speech (qualitative or numeric scale).

  • hurriedness (Union[str, float]) – Degree of impatience / hurriedness.

  • openness (Union[str, float]) – Openness to share information.

  • height (Union[str, int, float]) – Height (numeric with unit or descriptive).

  • weight (Union[str, int, float]) – Weight (numeric with unit or descriptive).

  • occupation (str) – Occupation or employment status.

  • marital_status (str) – Marital status.

  • insurance (str) – Insurance provider / status.

  • reason_for_visit (str) – Chief complaint / presenting problem.

  • symptoms (Union[str, List[str]]) – Reported symptoms.

  • medical_history (Union[str, List[str]]) – Past medical history (string or list of conditions).

  • medical_conditions (Union[str, List[str]]) – Known diagnosed conditions (string or list).

  • medications (Union[str, List[str]]) – Current medications (string or list).

  • allergies (Union[str, List[str]]) – Known allergies (string or list).

  • family_history (Union[str, List[str]]) – Family medical history (string or list).

name: str
age: int | str
race: str
gender: str
language: str
forgetfulness: str | float
formality: str | float
hurriedness: str | float
openness: str | float
height: str | int | float
weight: str | int | float
occupation: str
marital_status: str
insurance: str
reason_for_visit: str
symptoms: str | List[str]
medical_history: str | List[str]
medical_conditions: str | List[str]
medications: str | List[str]
allergies: str | List[str]
family_history: str | List[str]
static attributes(_cls=<class 'sdialog.personas.Patient'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.ExtendedPatient(*, name: str = '', age: int | str = '', race: str = '', gender: str = '', language: str = 'English', weight: str | int | float = '', height: str | int | float = '', voice_characteristics: str = '', occupation: str = '', education: str = '', socioeconomic_status: str = '', interests: str = '', hobbies: str = '', politeness: str = '', forgetfulness: str = '', attentiveness: str = '', communication_style: str = '', empathy_level: str = '', political_views: str = '', religious_beliefs: str = '', reason_for_visit: str = '', symptoms: str | List[str] = '', vital_signs: str = '', health_literacy: str = '', medical_conditions: str | List[str] = '', medications: str | List[str] = '', allergies: str | List[str] = '', family_history: str | List[str] = '')

Bases: ExtendedPersona

ExtendedPatient persona with additional health-related attributes. Inherits all attributes from ExtendedPersona plus medical context fields.

Parameters:
  • reason_for_visit (str) – Chief complaint or reason for consultation.

  • symptoms (Union[str, List[str]]) – Reported symptoms (free text or summarized list).

  • vital_signs (str) – Vital signs summary (e.g., “BP 120/80, HR 72”).

  • health_literacy (str) – Health literacy level descriptor.

  • medical_conditions (Union[str, List[str]]) – Known or chronic conditions (free text summary).

  • medications (Union[str, List[str]]) – Current medications summary.

  • allergies (Union[str, List[str]]) – Allergy list / summary.

  • family_history (Union[str, List[str]]) – Family medical history summary.

reason_for_visit: str
symptoms: str | List[str]
vital_signs: str
health_literacy: str
medical_conditions: str | List[str]
medications: str | List[str]
allergies: str | List[str]
family_history: str | List[str]
static attributes(_cls=<class 'sdialog.personas.ExtendedPatient'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Doctor(*, name: str = '', age: int | str = '', race: str = '', gender: str = '', language: str = 'English', years_of_experience: int | str = '', specialty: str = '', forgetfulness: str = '', formality: str = '', hurriedness: str = '', openness: str = '')

Bases: BaseAttributeModel

Doctor persona with essential professional and behavioral attributes.

Parameters:
  • name (str) – Doctor’s name.

  • age (Union[int, str]) – Doctor’s age (numeric or descriptive).

  • race (str) – Race / ethnicity.

  • gender (str) – Gender identity.

  • language (str) – Working language.

  • years_of_experience (Union[int, str]) – Years (or range) of medical practice.

  • specialty (str) – Medical specialty (as spelled in this class).

  • forgetfulness (str) – Forgetfulness tendency.

  • formality (str) – Formality level in communication.

  • hurriedness (str) – Degree of time pressure / haste.

  • openness (str) – Openness / approachability.

name: str
age: int | str
race: str
gender: str
language: str
years_of_experience: int | str
specialty: str
forgetfulness: str
formality: str
hurriedness: str
openness: str
static attributes(_cls=<class 'sdialog.personas.Doctor'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.ExtendedDoctor(*, name: str = '', age: int | str = '', race: str = '', gender: str = '', language: str = 'English', weight: str | int | float = '', height: str | int | float = '', voice_characteristics: str = '', occupation: str = '', education: str = '', socioeconomic_status: str = '', interests: str = '', hobbies: str = '', politeness: str = '', forgetfulness: str = '', attentiveness: str = '', communication_style: str = '', empathy_level: str = '', political_views: str = '', religious_beliefs: str = '', specialty: str = '', years_of_experience: int | str = '', certifications: str = '', work_experience: str = '')

Bases: ExtendedPersona

ExtendedDoctor persona adding professional credentials. Inherits all attributes from ExtendedPersona plus, the following ones.

Parameters:
  • specialty (str) – Medical specialty / domain focus.

  • years_of_experience (Union[int, str]) – Years (or range) of clinical experience.

  • certifications (str) – Professional certifications / board statuses.

  • work_experience (str) – Summary of prior practice settings / roles.

specialty: str
years_of_experience: int | str
certifications: str
work_experience: str
static attributes(_cls=<class 'sdialog.personas.ExtendedDoctor'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Nurse(*, name: str = '', age: int | str = '', gender: str = '', language: str = 'English', years_of_experience: int | str = '', specialty: str = '', shift: str = '', empathy_level: str = '', politeness: str = '', attentiveness: str = '', stress_tolerance: str = '')

Bases: BaseAttributeModel

Nurse persona for healthcare dialogues.

Parameters:
  • name (str) – Nurse name.

  • age (Union[int, str]) – Nurse age (numeric or descriptive).

  • gender (str) – Gender identity.

  • language (str) – Working language.

  • years_of_experience (Union[int, str]) – Years of nursing experience.

  • specialty (str) – Nursing specialty.

  • shift (str) – Typical work shift.

  • empathy_level (str) – Empathy descriptor.

  • politeness (str) – Politeness style.

  • attentiveness (str) – Attentiveness descriptor.

  • stress_tolerance (str) – Stress handling capability.

name: str
age: int | str
gender: str
language: str
years_of_experience: int | str
specialty: str
shift: str
empathy_level: str
politeness: str
attentiveness: str
stress_tolerance: str
static attributes(_cls=<class 'sdialog.personas.Nurse'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Pharmacist(*, name: str = '', age: int | str = '', gender: str = '', language: str = 'English', years_of_experience: int | str = '', workplace: str = '', expertise: str = '', politeness: str = '', communication_style: str = '')

Bases: BaseAttributeModel

Pharmacist persona for healthcare dialogues.

Parameters:
  • name (str) – Pharmacist name.

  • age (Union[int, str]) – Pharmacist age (numeric or descriptive).

  • gender (str) – Gender identity.

  • language (str) – Working language.

  • years_of_experience (Union[int, str]) – Years of pharmacy experience.

  • workplace (str) – Pharmacy or hospital name.

  • expertise (str) – Pharmaceutical expertise.

  • politeness (str) – Politeness style.

  • communication_style (str) – Communication style.

name: str
age: int | str
gender: str
language: str
years_of_experience: int | str
workplace: str
expertise: str
politeness: str
communication_style: str
static attributes(_cls=<class 'sdialog.personas.Pharmacist'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Caregiver(*, name: str = '', age: int | str = '', gender: str = '', relationship: str = '', experience_years: int | str = '', empathy_level: str = '', attentiveness: str = '')

Bases: BaseAttributeModel

Caregiver persona for healthcare dialogues.

Parameters:
  • name (str) – Caregiver name.

  • age (Union[int, str]) – Caregiver age (numeric or descriptive).

  • gender (str) – Gender identity.

  • relationship (str) – Relationship to care recipient.

  • experience_years (Union[int, str]) – Years of caregiving experience.

  • empathy_level (str) – Empathy descriptor.

  • attentiveness (str) – Attentiveness descriptor.

name: str
age: int | str
gender: str
relationship: str
experience_years: int | str
empathy_level: str
attentiveness: str
static attributes(_cls=<class 'sdialog.personas.Caregiver'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Teacher(*, name: str = '', age: int | str = '', gender: str = '', subject: str = '', years_of_experience: int | str = '', education_level: str = '', politeness: str = '', communication_style: str = '')

Bases: BaseAttributeModel

Teacher persona for education dialogues.

Parameters:
  • name (str) – Teacher name.

  • age (Union[int, str]) – Teacher age (numeric or descriptive).

  • gender (str) – Gender identity.

  • subject (str) – Teaching subject.

  • years_of_experience (Union[int, str]) – Years of teaching experience.

  • education_level (str) – Highest degree.

  • politeness (str) – Politeness style.

  • communication_style (str) – Communication style.

name: str
age: int | str
gender: str
subject: str
years_of_experience: int | str
education_level: str
politeness: str
communication_style: str
static attributes(_cls=<class 'sdialog.personas.Teacher'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Student(*, name: str = '', age: int | str = '', gender: str = '', grade_level: str = '', major: str = '', interests: str = '', politeness: str = '')

Bases: BaseAttributeModel

Student persona for education dialogues.

Parameters:
  • name (str) – Student name.

  • age (Union[int, str]) – Student age (numeric or descriptive).

  • gender (str) – Gender identity.

  • grade_level (str) – Grade or year.

  • major (str) – Major or focus area.

  • interests (str) – Interests.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
grade_level: str
major: str
interests: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Student'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.AcademicAdvisor(*, name: str = '', age: int | str = '', gender: str = '', years_of_experience: int | str = '', specialty: str = '', politeness: str = '')

Bases: BaseAttributeModel

AcademicAdvisor persona for education dialogues.

Parameters:
  • name (str) – Advisor name.

  • age (Union[int, str]) – Advisor age (numeric or descriptive).

  • gender (str) – Gender identity.

  • years_of_experience (Union[int, str]) – Years of advising experience.

  • specialty (str) – Advising specialty.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
years_of_experience: int | str
specialty: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.AcademicAdvisor'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.FinancialAdvisor(*, name: str = '', age: int | str = '', gender: str = '', years_of_experience: int | str = '', certifications: str = '', specialty: str = '', politeness: str = '')

Bases: BaseAttributeModel

FinancialAdvisor persona for finance dialogues.

Parameters:
  • name (str) – Advisor name.

  • age (Union[int, str]) – Advisor age (numeric or descriptive).

  • gender (str) – Gender identity.

  • years_of_experience (Union[int, str]) – Years of financial advising experience.

  • certifications (str) – Certifications.

  • specialty (str) – Financial specialty.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
years_of_experience: int | str
certifications: str
specialty: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.FinancialAdvisor'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Banker(*, name: str = '', age: int | str = '', gender: str = '', branch: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

Banker persona for finance dialogues.

Parameters:
  • name (str) – Banker name.

  • age (Union[int, str]) – Banker age (numeric or descriptive).

  • gender (str) – Gender identity.

  • branch (str) – Bank branch.

  • years_of_experience (Union[int, str]) – Years of banking experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
branch: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Banker'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.InsuranceAgent(*, name: str = '', age: int | str = '', gender: str = '', company: str = '', years_of_experience: int | str = '', specialty: str = '', politeness: str = '')

Bases: BaseAttributeModel

InsuranceAgent persona for finance dialogues.

Parameters:
  • name (str) – Agent name.

  • age (Union[int, str]) – Agent age (numeric or descriptive).

  • gender (str) – Gender identity.

  • company (str) – Insurance company.

  • years_of_experience (Union[int, str]) – Years of insurance experience.

  • specialty (str) – Insurance specialty.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
company: str
years_of_experience: int | str
specialty: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.InsuranceAgent'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.StoreManager(*, name: str = '', age: int | str = '', gender: str = '', store_name: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

StoreManager persona for retail dialogues.

Parameters:
  • name (str) – Manager name.

  • age (Union[int, str]) – Manager age (numeric or descriptive).

  • gender (str) – Gender identity.

  • store_name (str) – Store name.

  • years_of_experience (Union[int, str]) – Years of management experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
store_name: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.StoreManager'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.SalesAssociate(*, name: str = '', age: int | str = '', gender: str = '', store_name: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

SalesAssociate persona for retail dialogues.

Parameters:
  • name (str) – Associate name.

  • age (Union[int, str]) – Associate age (numeric or descriptive).

  • gender (str) – Gender identity.

  • store_name (str) – Store name.

  • years_of_experience (Union[int, str]) – Years of sales experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
store_name: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.SalesAssociate'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Shopper(*, name: str = '', age: int | str = '', gender: str = '', shopping_goal: str = '', loyalty_status: str = '', politeness: str = '')

Bases: BaseAttributeModel

Shopper persona for retail dialogues.

Parameters:
  • name (str) – Shopper name.

  • age (Union[int, str]) – Shopper age (numeric or descriptive).

  • gender (str) – Gender identity.

  • shopping_goal (str) – Shopping goal.

  • loyalty_status (str) – Loyalty descriptor.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
shopping_goal: str
loyalty_status: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Shopper'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.HotelReceptionist(*, name: str = '', age: int | str = '', gender: str = '', hotel_name: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

HotelReceptionist persona for hospitality dialogues.

Parameters:
  • name (str) – Receptionist name.

  • age (Union[int, str]) – Receptionist age (numeric or descriptive).

  • gender (str) – Gender identity.

  • hotel_name (str) – Hotel name.

  • years_of_experience (Union[int, str]) – Years of hospitality experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
hotel_name: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.HotelReceptionist'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.TravelAgent(*, name: str = '', age: int | str = '', gender: str = '', agency_name: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

TravelAgent persona for travel dialogues.

Parameters:
  • name (str) – Agent name.

  • age (Union[int, str]) – Agent age (numeric or descriptive).

  • gender (str) – Gender identity.

  • agency_name (str) – Travel agency name.

  • years_of_experience (Union[int, str]) – Years of travel experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
agency_name: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.TravelAgent'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Tourist(*, name: str = '', age: int | str = '', gender: str = '', travel_goal: str = '', politeness: str = '')

Bases: BaseAttributeModel

Tourist persona for travel dialogues.

Parameters:
  • name (str) – Tourist name.

  • age (Union[int, str]) – Tourist age (numeric or descriptive).

  • gender (str) – Gender identity.

  • travel_goal (str) – Travel goal.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
travel_goal: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Tourist'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Lawyer(*, name: str = '', age: int | str = '', gender: str = '', specialty: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

Lawyer persona for legal dialogues.

Parameters:
  • name (str) – Lawyer name.

  • age (Union[int, str]) – Lawyer age (numeric or descriptive).

  • gender (str) – Gender identity.

  • specialty (str) – Legal specialty.

  • years_of_experience (Union[int, str]) – Years of legal experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
specialty: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Lawyer'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Paralegal(*, name: str = '', age: int | str = '', gender: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

Paralegal persona for legal dialogues.

Parameters:
  • name (str) – Paralegal name.

  • age (Union[int, str]) – Paralegal age (numeric or descriptive).

  • gender (str) – Gender identity.

  • years_of_experience (Union[int, str]) – Years of paralegal experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Paralegal'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.LegalClient(*, name: str = '', age: int | str = '', gender: str = '', case_type: str = '', politeness: str = '')

Bases: BaseAttributeModel

LegalClient persona for legal dialogues.

Parameters:
  • name (str) – Client name.

  • age (Union[int, str]) – Client age (numeric or descriptive).

  • gender (str) – Gender identity.

  • case_type (str) – Type of legal case.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
case_type: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.LegalClient'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.ITSupportSpecialist(*, name: str = '', age: int | str = '', gender: str = '', years_of_experience: int | str = '', expertise_area: str = '', politeness: str = '')

Bases: BaseAttributeModel

ITSupportSpecialist persona for tech support dialogues.

Parameters:
  • name (str) – Specialist name.

  • age (Union[int, str]) – Specialist age (numeric or descriptive).

  • gender (str) – Gender identity.

  • years_of_experience (Union[int, str]) – Years of IT support experience.

  • expertise_area (str) – Area of technical expertise.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
years_of_experience: int | str
expertise_area: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.ITSupportSpecialist'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.HelpdeskTechnician(*, name: str = '', age: int | str = '', gender: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

HelpdeskTechnician persona for tech support dialogues.

Parameters:
  • name (str) – Technician name.

  • age (Union[int, str]) – Technician age (numeric or descriptive).

  • gender (str) – Gender identity.

  • years_of_experience (Union[int, str]) – Years of helpdesk experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.HelpdeskTechnician'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.EndUser(*, name: str = '', age: int | str = '', gender: str = '', device_type: str = '', issue_description: str = '', politeness: str = '')

Bases: BaseAttributeModel

EndUser persona for tech support dialogues.

Parameters:
  • name (str) – End user name.

  • age (Union[int, str]) – End user age (numeric or descriptive).

  • gender (str) – Gender identity.

  • device_type (str) – Type of device used.

  • issue_description (str) – Description of technical issue.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
device_type: str
issue_description: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.EndUser'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.CivilServant(*, name: str = '', age: int | str = '', gender: str = '', department: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

CivilServant persona for government dialogues.

Parameters:
  • name (str) – Civil servant name.

  • age (Union[int, str]) – Civil servant age (numeric or descriptive).

  • gender (str) – Gender identity.

  • department (str) – Government department.

  • years_of_experience (Union[int, str]) – Years of public service.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
department: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.CivilServant'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.SocialWorker(*, name: str = '', age: int | str = '', gender: str = '', years_of_experience: int | str = '', specialty: str = '', politeness: str = '')

Bases: BaseAttributeModel

SocialWorker persona for public service dialogues.

Parameters:
  • name (str) – Social worker name.

  • age (Union[int, str]) – Social worker age (numeric or descriptive).

  • gender (str) – Gender identity.

  • years_of_experience (Union[int, str]) – Years of social work experience.

  • specialty (str) – Social work specialty.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
years_of_experience: int | str
specialty: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.SocialWorker'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Citizen(*, name: str = '', age: int | str = '', gender: str = '', inquiry_topic: str = '', politeness: str = '')

Bases: BaseAttributeModel

Citizen persona for government dialogues.

Parameters:
  • name (str) – Citizen name.

  • age (Union[int, str]) – Citizen age (numeric or descriptive).

  • gender (str) – Gender identity.

  • inquiry_topic (str) – Topic of inquiry.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
inquiry_topic: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Citizen'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Chef(*, name: str = '', age: int | str = '', gender: str = '', restaurant_name: str = '', years_of_experience: int | str = '', cuisine_specialty: str = '', politeness: str = '')

Bases: BaseAttributeModel

Chef persona for food service dialogues.

Parameters:
  • name (str) – Chef name.

  • age (Union[int, str]) – Chef age (numeric or descriptive).

  • gender (str) – Gender identity.

  • restaurant_name (str) – Restaurant name.

  • years_of_experience (Union[int, str]) – Years of culinary experience.

  • cuisine_specialty (str) – Cuisine specialty.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
restaurant_name: str
years_of_experience: int | str
cuisine_specialty: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Chef'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.Waiter(*, name: str = '', age: int | str = '', gender: str = '', restaurant_name: str = '', years_of_experience: int | str = '', politeness: str = '')

Bases: BaseAttributeModel

Waiter persona for food service dialogues.

Parameters:
  • name (str) – Waiter name.

  • age (Union[int, str]) – Waiter age (numeric or descriptive).

  • gender (str) – Gender identity.

  • restaurant_name (str) – Restaurant name.

  • years_of_experience (Union[int, str]) – Years of service experience.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
restaurant_name: str
years_of_experience: int | str
politeness: str
static attributes(_cls=<class 'sdialog.personas.Waiter'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None

class sdialog.personas.RestaurantCustomer(*, name: str = '', age: int | str = '', gender: str = '', dietary_preferences: str = '', politeness: str = '')

Bases: BaseAttributeModel

RestaurantCustomer persona for food service dialogues.

Parameters:
  • name (str) – Customer name.

  • age (Union[int, str]) – Customer age (numeric or descriptive).

  • gender (str) – Gender identity.

  • dietary_preferences (str) – Dietary preferences.

  • politeness (str) – Politeness style.

name: str
age: int | str
gender: str
dietary_preferences: str
politeness: str
static attributes(_cls=<class 'sdialog.personas.RestaurantCustomer'>, print=False)

List (or pretty-print) public attribute field names for this subclass.

Parameters:

print (bool) – If True, pretty-prints instead of returning the list.

Returns:

List of attribute names (if print=False).

Return type:

List[str] | None


sdialog.agents

This module provides classes for Agents and related utilities for simulating persona-conditioned dialogue with Large Language Models (LLMs). Agents maintain structured conversation memory, integrate orchestrators that inject dynamic (persistent or ephemeral) system instructions, and expose inspection / interpretability hooks for token- and layer-level analysis and optional representation steering.

sdialog.agents.final_response_tool(func=None)

Decorator to mark a tool whose raw output should be returned directly as the agent response (bypassing the post-tool LLM synthesis step).

This is useful for pre-formatted outputs (e.g., large markdown tables) where token-by-token regeneration by the LLM is unnecessary.

Usage:

from sdialog.agents import final_response_tool

@final_response_tool
def my_tool(...) -> str:
    ...
Parameters:

func (Optional[callable]) – The tool function to mark.

Returns:

Decorated function.

Return type:

callable

class sdialog.agents.Agent(persona: BaseAttributeModel = None, name: str | None = None, context: str | Context | None = None, first_utterance: str | List[str] | None = None, dialogue_details: str = '', response_details: str = 'Unless necessary, responses SHOULD be only one utterance long, and SHOULD NOT contain many questions or topics in one single turn.', example_dialogs: List[Dialog] | None = None, tools: List | None = None, think: bool = False, thinking_pattern: str | None = '<think>(.*?)</think>', can_finish: bool = True, orchestrators: BaseOrchestrator | List[BaseOrchestrator] | None = None, inspectors: Inspector | List[Inspector] | None = None, preprocessing_fn: callable | None = None, postprocess_fn: callable | None = None, system_prompt: str | None = None, model: str | langchain_core.language_models.base.BaseLanguageModel = None, **llm_kwargs)

Bases: object

Agent that simulates a persona-driven conversational actor using an LLM.

This class wraps:

  • A persona (traits / role)

  • Optional context + exemplar dialogues

  • Orchestrators (dynamic / persistent injected instructions)

  • Interpretability hooks (token / layer events, steering)

  • Simple dialogue loop utilities (dialog_with)

Example:

from sdialog import Persona, Context
from sdialog.agents import Agent

# Create two agents
user = Agent(persona=Persona(name="Dr. Nebula",
                             role="Astrobotanist seeking alien spores"),
             name="Scientist")
bot = Agent(persona=Persona(name="StationCore",
                            role="Sarcastic habitat control AI"),
            name="Bot")

# Create an (optional) context for the conversation
context = Context(location="Orbiting Research Station Theta-9",
                  environment="Zero-gravity greenhouse",
                  objects=["alien spores", "hydroponic garden", "research equipment"])

# Create a dialogue
dialog = user.dialog_with(bot, context=context)

# Print dialog
dialog.print()
Parameters:
  • persona (BasePersona) – The persona to role-play.

  • name (Optional[str]) – Name of the agent (defaults to persona.name if not provided).

  • context (Optional[Union[str, Context]]) – Optional default context for the agent’s conversations.

  • first_utterance (Optional[Union[str, List[str]]]) – Optional fixed first utterance or list of possible first utterances.

  • dialogue_details (str) – Additional details about the dialogue.

  • response_details (str) – Instructions for response style.

  • example_dialogs (Optional[List[Dialog]]) – Optional list of default example dialogues as a reference for the agent.

  • tools (Optional[List[callable]] Tools decorated with @final_response_tool return their raw output directly as the final agent response.) – List of functions to be used as tools by the agent (if supported by the LLM).

  • think (bool) – If True, enables “thinking” segments in responses (if supported by the LLM).

  • thinking_pattern (Optional[str]) – Regex pattern to manually identify “thinking” segments in responses.

  • can_finish (bool) – If True, agent can end the conversation.

  • orchestrators (Optional[Union[BaseOrchestrator, List[BaseOrchestrator]]]) – Orchestrators for agent behavior.

  • inspectors (Optional[Union[Inspector, List[Inspector]]]) – Inspector(s) to add to the agent.

  • preprocessing_fn (Optional[callable]) – Optional function to preprocess each input utterance before calling the LLM (input string, output string).

  • postprocess_fn (Optional[callable]) – Optional function to postprocess each output utterance after calling the LLM (input string, output string).

  • system_prompt (Optional[str]) – Custom system prompt to use as-is (takes precedence over persona; if provided, persona is disabled and this prompt is used directly).

  • model (Union[str, BaseLanguageModel], optional) – The LLM or model name to use (defaults to config[“llm”][“model”]).

  • llm_kwargs (dict) – Additional parameters for the LLM.

property memory: List[langchain_core.messages.base.BaseMessage]

The conversation memory as a list of messages.

property base_model

Return the underlying base (wrapped) model object (e.g., a HuggingFace Transformers model).

Resolution order:
  1. ChatHuggingFace wrapper: self.llm.llm.pipeline.model

  2. Objects exposing pipeline.model

  3. Objects exposing model

If none are found, self.llm is returned as a fallback.

property tokenizer

Return the underlying tokenizer object (e.g., a HuggingFace Transformers tokenizer).

Resolution order:
  1. ChatHuggingFace wrapper: self.llm.llm.tokenizer

  2. Objects exposing pipeline.tokenizer

  3. Objects exposing tokenizer

__call__(utterance: str | List[langchain_core.messages.base.BaseMessage] = '', return_events: bool = False, current_dialog: Dialog = None, return_tool_errors: bool = False) → str

Processes an input utterance and generates a response.

Parameters:
  • utterance (Union[str, List[BaseMessage]]) – The input utterance from the other agent or, in case of stateless operation, the full context as a list of Langchain messages.

  • return_events (bool) – If True, returns a list of events instead of just the response string.

  • current_dialog (Dialog) – The current dialog state as a Dialog object for orchestrators.

  • return_tool_errors (bool) – If True, tool-call failures are converted to tool output and fed back to the LLM.

Returns:

The agent’s response or events, or None if finished.

Return type:

Union[str, List[Event], None]

clone() → Agent

Create a copy of this agent with its own conversation that shares its language model.

The clone shares the model weights and API clients (nothing is loaded again), and everything else that does not change during a conversation (persona, tools, prompts). It gets its own memory, finished flag, LLM settings (e.g. the seed set on reset) and copies of the orchestrators: shallow copies, so heavy resources such as sentence encoders are shared, while e.g. their counters are not. Inspectors are not copied, since their hooks are attached to the shared model.

Useful to run several conversations with the same agent in parallel (see AgentPool).

Example:

from sdialog.agents import Agent

support = Agent(name="Support")
support_2 = support.clone()  # Same LLM, separate memory

support("Hi, I'm Alice")
support_2("Hi, I'm Bob")  # Does not know about Alice
Returns:

The cloned agent.

Return type:

Agent

serve(host: str = '0.0.0.0', port: int = 1333, stateless: bool = True, debug: bool = False, log_level: str = 'info', max_requests_per_minute: int | None = 30, max_requests_per_hour: int | None = 300, max_workers: int | None = None, chat_ui: bool | ChatUI = False)

Starts a REST API server to interact with the agent.

Parameters:
  • host (str) – Host address to bind the server to.

  • port (int) – Port number to listen on.

  • stateless (bool) – If True, the server does not maintain conversation state (as such the full context must be provided with each request).

  • debug (bool) – If True, enables debug mode for the server (errors will be sent back in the response to the LLM).

  • log_level (str) – Logging level for the server.

  • max_requests_per_minute (Optional[int]) – Per-client (IP address) limit of chat requests per minute, for bursts; extra requests get HTTP 429 “Too Many Requests” (None to disable).

  • max_requests_per_hour (Optional[int]) – Per-client (IP address) limit of chat requests per hour, for sustained use (None to disable).

  • max_workers (Optional[int]) – Maximum number of requests processed at the same time, each on a clone of the agent sharing its model (None: 8). Only used when stateless=True; agents with a local Hugging Face model or inspectors serve one request at a time. With several workers, the agent’s tools must be thread-safe.

  • chat_ui (Union[bool, ChatUI]) – If True, also serve a web chat GUI to talk to the agent at /chat (e.g. http://localhost:1333/chat), which can also be embedded in other pages; pass a ChatUI to customize it.

serve_whatsapp(port: int = 1234, host: str = '0.0.0.0', phone_number_id: str | None = None, access_token: str | None = None, verify_token: str | None = None, app_secret: str | None = None, db_path: str = 'whatsapp_sessions.db', webhook_path: str = '/webhook', session_timeout: int | str | None = 'auto', session_retention_days: int | None = 30, tunnel: bool = False, auto_setup: bool = False, max_messages_per_minute: int | None = 6, max_messages_per_hour: int | None = 60, log_level: str = 'info', max_workers: int | None = None, max_message_age: int | None = 120, on_event: Callable[[str, Event], None] | None = None)

Starts a Meta WhatsApp Cloud API webhook server to interact with the agent.

Parameters:
  • port (int) – Port number to bind the server to.

  • host (str) – Host address to bind the server to.

  • phone_number_id (Optional[str]) – Meta WhatsApp Phone Number ID (or WHATSAPP_PHONE_NUMBER_ID env var).

  • access_token (Optional[str]) – Meta Graph API Access Token (or WHATSAPP_ACCESS_TOKEN env var).

  • verify_token (Optional[str]) – Webhook verification token (or WHATSAPP_VERIFY_TOKEN env var; random if unset).

  • app_secret (Optional[str]) – Meta App Secret for HMAC validation (or WHATSAPP_APP_SECRET env var). Required.

  • db_path (str) – Path to the SQLite session database.

  • webhook_path (str) – Webhook URL path.

  • session_timeout (Union[int, str, None]) – Seconds of inactivity before a user’s conversation starts over (None: never). "auto" uses 30 minutes, or 24 hours if welcome messages are enabled on the phone number, since then conversations also start over when the user opens a new chat.

  • session_retention_days (Optional[int]) – Delete the conversations of users inactive for longer than this (None to keep them).

  • tunnel (bool) – If True, attempts to spawn a public ngrok tunnel.

  • auto_setup (bool) – If True (with tunnel=True), overwrites the Meta webhook URL of the WhatsApp Business Account and phone number with the tunnel URL. Use only with test accounts.

  • max_messages_per_minute (Optional[int]) – Per-user limit for bursts of messages; extra messages are dropped (None to disable).

  • max_messages_per_hour (Optional[int]) – Per-user limit for sustained use; extra messages are dropped (None to disable).

  • log_level (str) – Logging level for the server.

  • max_workers (Optional[int]) – Maximum number of users whose messages are processed at the same time, each on a clone of the agent sharing its model (None: 8; a user’s messages are always processed one at a time, in order). Agents with a local Hugging Face model or inspectors serve one message at a time. With several workers, the agent’s tools must be thread-safe.

  • max_message_age (Optional[int]) – Ignore messages sent longer ago than this many seconds (None to answer all). Meta retries webhooks it could not deliver (e.g. while the server was down) for days, and late replies would be out of context.

  • on_event (Optional[Callable[[str, Event], None]]) – Function called as on_event(user_id, event) with each Event of a user’s turn, in order, once the reply is sent: orchestrator instructions (with the orchestrator’s event_label as actionLabel), tool calls, and the reply. The user ID is their phone number. It runs in the server’s threads, so it may block (e.g. to send an email), but it may run at the same time for different users, so it must be thread-safe. Errors are logged and ignored.

response_lookahead(message: str = None)

Generates a response without updating the agent’s memory.

  • If message is None, predicts the next reply given current memory.

  • If message is provided, predicts a reply to that hypothetical input.

Notes: - Orchestrators and inspectors are not invoked. - Tools may be called, but their outputs are not persisted. - Only postprocess_fn is applied (no preprocessing).

Parameters:

message (Optional[str]) – The hypothetical message to reply to (optional).

Returns:

The predicted response text.

Return type:

str

add_orchestrators(orchestrators)

Adds orchestrators to the agent.

Parameters:

orchestrators (Union[BaseOrchestrator, List[BaseOrchestrator]]) – Orchestrator(s) to add.

add_inspectors(inspectors)

Adds inspectors to the agent.

Parameters:

inspectors (Union[Inspector, List[Inspector]]) – Inspector(s) to add.

clear_orchestrators()

Removes all orchestrators from the agent.

clear_inspectors()

Removes all inspectors from the agent.

instruct(instruction: str, persist: bool = False)

Adds a system instruction to the agent’s memory.

Parameters:
  • instruction (str) – The instruction text.

  • persist (bool) – If True, instruction persists across turns.

set_first_utterances(utterances: str | List[str])

Sets the agent’s first utterance(s) for dialogue initialization.

Parameters:

utterances (Union[str, List[str]]) – The greeting(s) to use.

get_name(default: str = 'Me') → str

Returns the agent’s name.

Parameters:

default (str) – Fallback name if agent has no explicit name.

Returns:

The agent’s name.

Return type:

str

prompt() → str

Returns the current system prompt.

Returns:

The system prompt.

Return type:

str

json(string: bool = False, indent=None)

Serializes the agent’s configuration and persona to JSON.

Parameters:
  • string (bool) – If True, returns a JSON string; otherwise, returns a dict.

  • indent (int) – Indentation level for pretty-printing.

Returns:

The serialized agent.

Return type:

Union[str, dict]

reset(seed: int = None, context: str | Context = None, example_dialogs: List[Dialog] = None)

Resets the agent’s memory and orchestrators, optionally reseeding the LLM. Also clears interpretability state and components if any.

Parameters:
  • seed – Random seed for reproducibility (if None, generated).

  • context – Optional context override.

  • example_dialogs – Optional replacement example dialogs for prompt regeneration.

dialog_with(agent: Agent, context: str | Context = None, example_dialogs: List[Dialog] = None, scenario: dict | str | None = None, max_turns: int = 100, id: int = None, parent_id: int = None, seed: int = None, notes: str = None, keep_bar: bool = True)

Simulates a dialogue between this agent and another Agent.

Parameters:
  • agent (Agent) – The other agent to converse with.

  • context (Optional[Union[str, Context]]) – The context for the dialogue (optional).

  • example_dialogs (Optional[List[Dialog]]) – Example dialogues to guide the conversation (optional).

  • scenario (Optional[Union[dict, str]]) – Optional scenario metadata for the dialogue.

  • max_turns (int) – Maximum number of dialogue turns.

  • id (int) – Dialogue ID.

  • parent_id (int) – ID of the parent dialogue, if any.

  • seed (int) – Random seed for reproducibility.

  • notes (str) – Optional notes to include in the dialogue.

  • keep_bar (bool) – If True, keeps the progress bar visible.

Returns:

The generated dialogue object.

Return type:

Dialog

memory_dump(as_dict: bool = False) → list

Returns a copy of the agent’s memory (list of messages).

Parameters:

as_dict (bool) – If True, returns list of message dicts (serialization-friendly).

Returns:

Conversation memory snapshot.

Return type:

list

get_state() → dict

Returns a JSON-serializable snapshot of the agent’s conversation state, which can be restored later (e.g. on a fresh or reset agent) with set_state().

The snapshot includes the conversation memory (excluding the system prompt, which is part of the agent’s configuration), the finished flag, and the internal state of attached orchestrators. It does not include the persona, model, or other configuration (see json() and clone() for that).

Example:

import json
from sdialog.agents import Agent

bot = Agent(name="Bot")
bot("Hi, my name is Alice")

saved = json.dumps(bot.get_state())

# Later, e.g. after a restart, continue the same conversation
bot.reset()
bot.set_state(json.loads(saved))
bot("Do you remember my name?")
Returns:

Serializable state dictionary.

Return type:

dict

set_state(state: dict)

Restores a conversation state previously obtained with get_state(), replacing the current conversation memory while keeping the agent’s current system prompt.

Orchestrator states are restored by position; if the number of attached orchestrators differs from the saved state, orchestrator states are not restored and a warning is logged.

Parameters:

state (dict) – State dictionary as returned by get_state().

Raises:

ValueError – If the state version is not supported.

talk_with(agent: Agent, context: str | Context = None, example_dialogs: List[Dialog] = None, scenario: dict | str | None = None, max_turns: int = 100, id: int = None, parent_id: int = None, seed: int = None, notes: str = None, keep_bar: bool = True)

Alias for Agent.dialog_with().


sdialog.orchestrators

This module provides base and concrete classes for orchestrating agent behavior during synthetic dialogue generation. Orchestrators can inject instructions, control agent responses, and manage dialogue flow for more complex scenarios.

class sdialog.orchestrators.SimpleReflexOrchestrator(condition: callable, instruction: str, persistent: bool = False, event_label: str = None)

Bases: BaseOrchestrator

Simple reflex orchestrator that provides fixed instructions when a condition matches.

Example:

from sdialog.orchestrators import SimpleReflexOrchestrator
from sdialog.agents import Agent
from sdialog.personas import Persona

# If the last utterance contains 'quest', steer to suggest party planning (tutorial style)
reflex = SimpleReflexOrchestrator(
    condition=lambda utt: "quest" in utt.lower(),
    instruction="Acknowledge the quest idea, then suggest one concrete themed activity."
)

bob = Agent(persona=Persona(name="Bob", role="dad")) | reflex
alice = Agent(persona=Persona(name="Alice", role="daughter"))
dialog = bob.talk_with(alice)
dialog.print(orchestration=True)
Parameters:
  • condition (callable) – Predicate function receiving the last utterance; returns True to trigger.

  • instruction (str) – Instruction text to return when condition is satisfied.

  • persistent (bool) – Whether orchestrator persists across turns.

  • event_label (str) – Optional event label override.

instruct(dialog: List[Turn], utterance: str) → str

Return the configured instruction if condition holds.

Parameters:
  • dialog (List[Turn]) – Current dialog (unused except for extensibility).

  • utterance (str) – Last opposite-party utterance.

Returns:

Instruction text or None.

Return type:

Union[str, None]

class sdialog.orchestrators.LengthOrchestrator(min: int = None, max: int = None, persistent: bool = False, event_label: str = None)

Bases: BaseOrchestrator

Orchestrator that encourages continuation or termination based on current number of turns.

Example:

from sdialog.orchestrators import LengthOrchestrator
from sdialog.personas import Persona
from sdialog.agents import Agent

# Keep dialogue going at least 8 turns; try to wrap by turn 12
len_orch = LengthOrchestrator(min=8, max=12)

planner = Agent(persona=Persona(name="Planner", role="organizer"))
guest = Agent(persona=Persona(name="Guest", role="participant"))

# Attach orchestrator to planner
planner = planner | len_orch

dialog = planner.dialog_with(guest)
dialog.print(orchestration=True)
Parameters:
  • min (int) – Minimum turns before allowing termination (encourages continuation if not reached).

  • max (int) – Maximum turns threshold after which termination is enforced.

  • persistent (bool) – Whether orchestrator persists.

  • event_label (str) – Optional event label.

instruct(dialog: List[Turn], utterance: str) → str

Provide an instruction to continue or finish based on dialog length.

Parameters:
  • dialog (List[Turn]) – Current dialog state.

  • utterance (str) – Last opposite-party utterance.

Returns:

Instruction text or None.

Return type:

Union[str, None]

class sdialog.orchestrators.ChangeMindOrchestrator(probability: float = 0.3, reasons: str | List[str] = None, max_times: int = 1, persistent: bool = False, event_label: str = None)

Bases: BaseOrchestrator

Orchestrator that probabilistically injects a ‘change your mind’ instruction a limited number of times.

Example:

from sdialog.orchestrators import ChangeMindOrchestrator
from sdialog.personas import Persona
from sdialog.agents import Agent

# 40% chance (once) to pivot party theme justification
changer = ChangeMindOrchestrator(probability=0.4,
                                 reasons=["a better surprise", "budget constraints"],
                                 max_times=1)

alice = Agent(persona=Persona(name="Alice", role="daughter"))
bob = Agent(persona=Persona(name="Bob", role="dad"))

# Attach orchestrator to Bob
bob = bob | changer

dialog = alice.dialog_with(bob)
dialog.print(orchestration=True)
Parameters:
  • probability (float) – Probability (0-1) each eligible turn to trigger a mind-change.

  • reasons (Union[str, List[str]]) – Optional reason(s) appended; single string or list.

  • max_times (int) – Maximum number of injections allowed.

  • persistent (bool) – Persistence flag.

  • event_label (str) – Event label override.

reset()

Reset internal counter of times triggered.

Returns:

None

Return type:

None

get_state() → dict

Return the internal counter of times triggered.

Returns:

State dictionary.

Return type:

dict

set_state(state: dict)

Restore the internal counter of times triggered.

Parameters:

state (dict) – State dictionary as returned by get_state().

Returns:

None

Return type:

None

instruct(dialog: List[Turn], utterance: str) → str

Possibly return a mind-change instruction based on probability and remaining allowance.

Parameters:
  • dialog (List[Turn]) – Current dialog state.

  • utterance (str) – Last opposite-party utterance.

Returns:

Instruction text or None.

Return type:

Union[str, None]

class sdialog.orchestrators.SimpleResponseOrchestrator(responses: List[str | Dict[str, str]], graph: Dict[str, str] = None, sbert_model: str = 'sergioburdisso/dialog2flow-joint-bert-base', top_k: int = 5)

Bases: BaseOrchestrator

Orchestrator that suggests next responses based on semantic similarity against a response set (or action graph).

Example:

from sdialog.orchestrators import SimpleResponseOrchestrator
from sdialog.agents import Agent
from sdialog.personas import Persona

canned = [
    "Could you clarify that?",
    "Let me summarize the plan.",
    "That sounds exciting—tell me more.",
    "Maybe we should adjust the theme.",
    "Can you give one concrete example?"
]

sugg = SimpleResponseOrchestrator(responses=canned, top_k=3)

guide = Agent(persona=Persona(name="Guide", role="facilitator"))
user = Agent(persona=Persona(name="User", role="participant"))

# Attach orchestrator to guide
guide = guide | sugg

dialog = guide.dialog_with(user)
dialog.print(orchestration=True)
Parameters:
  • responses (List[Union[str, Dict[str, str]]]) – List (plain strings) or dict (action -> response) entries.

  • graph (Dict[str, str]) – Optional action transition graph (current_action -> next_action).

  • sbert_model (str) – SentenceTransformer model name.

  • top_k (int) – Number of top similar responses/actions to surface.

instruct(dialog: List[Turn], utterance: str) → str

Build an Instruction containing candidate responses (and events for traceability).

Parameters:
  • dialog (List[Turn]) – Current dialog.

  • utterance (str) – Last opposite-party utterance (unused directly; similarity uses lookahead / last turn).

Returns:

Instruction object with suggestion list.

Return type:

Instruction

class sdialog.orchestrators.InstructionListOrchestrator(instructions: List[str | Dict[int, str]], persistent: bool = False)

Bases: BaseOrchestrator

Orchestrator that dispenses predefined instructions sequentially or by turn index mapping.

Example:

from sdialog.orchestrators import InstructionListOrchestrator
from sdialog.personas import Persona
from sdialog.agents import Agent

steps = [
    "Greet warmly and ask about preferred theme.",
    "Ask for constraints (budget / space).",
    "Suggest one fitting activity.",
    "Confirm decisions and wrap up politely."
]

coach = Agent(persona=Persona(name="Coach", role="planner"))
client = Agent(persona=Persona(name="Client", role="requester"))

# Attach a new instance of InstructionListOrchestrator to the coach
coach = coach | InstructionListOrchestrator(steps)

dialog = coach.dialog_with(client)
dialog.print(orchestration=True)
Parameters:
  • instructions (List[Union[str, Dict[int, str]]]) – Either list (indexed per agent turn) or dict mapping agent turn index -> instruction.

  • persistent (bool) – Persistence flag.

instruct(dialog: List[Turn], utterance: str) → str

Return the next scheduled instruction if available.

Parameters:
  • dialog (List[Turn]) – Current dialog.

  • utterance (str) – Last opposite-party utterance.

Returns:

Instruction text or None.

Return type:

Union[str, None]

sdialog.orchestrators.base

Base classes for creating custom orchestrators to guide Agent behavior during dialogue generation.

class sdialog.orchestrators.base.BaseOrchestrator(target_agent=None, persistent: bool = None, event_label: str = None)

Bases: ABC

Base abstract class to create orchestrators that control or influence Agent behavior during dialogue generation. Abstract method instruct() must be implemented by subclasses.

Responsibilities:
  • Observe dialogue (agent memory) and produce turn-level instructions.

  • Optionally emit events describing guidance injected.

  • Support persistence across turns when marked persistent.

Example:

from sdialog.orchestrators import BaseOrchestrator
from sdialog.personas import Persona
from sdialog.agents import Agent

# Let's create our own orchestrator
class EncourageDetailOrchestrator(BaseOrchestrator):
    def instruct(self, dialog, utterance):
        if utterance and len(utterance.split()) < 5:
            return "Add a bit more detail in your next reply."
        return None

orch_encourage = EncourageDetailOrchestrator()

bob = Agent(persona=Persona(role="Guide"))
alice = Agent(persona=Persona(role="User"))

# Let's orchestrate bob to provide more detailed answers if alice is brief
bob = bob | orch_encourage

dialog = bob.talk_with(alice)
dialog.print(orchestration=True)
Parameters:
  • target_agent (Agent) – Agent instance to orchestrate (can be set later).

  • persistent (bool) – Whether produced instructions should persist each turn automatically.

  • event_label (str) – Optional label to tag generated events; defaults to class name.

__call__(current_dialog)

Produce an instruction for the target agent given current dialog state.

Returns:

Instruction object/string or None if no instruction is produced.

Return type:

Union[str, Instruction, None]

json(string: bool = False, indent: int = None)

Serialize orchestrator configuration.

Parameters:
  • string (bool) – If True returns JSON string; otherwise a dict.

  • indent (int) – Indentation for pretty JSON output (only if string=True).

Returns:

Serialized configuration.

Return type:

Union[str, dict]

get_event_label() → str

Get the label used for events generated by this orchestrator.

Returns:

Event label.

Return type:

str

get_target_agent()

Get the currently assigned target agent.

Returns:

Agent instance or None.

Return type:

Agent

is_persistent()

Whether this orchestrator is persistent.

Returns:

True if persistent.

Return type:

bool

set_persistent(value: bool)

Set persistence flag.

Parameters:

value (bool) – New persistence state.

agent_response_lookahead()

Retrieve the agent’s lookahead response (preview of next response if available).

Returns:

Lookahead response string.

Return type:

str

abstractmethod instruct(dialog: List[Turn], utterance: str) → str

Abstract method: Subclasses are expected to implement this method. Implementations should analyze the dialog state and optionally the most recent utterance to produce an instruction for the target agent.

Parameters:
  • dialog (List[Turn]) – Current reconstructed dialog (list of turns).

  • utterance (str) – Last opposite-party utterance (may be empty string).

Returns:

Instruction text, Instruction object, or None if no action needed.

Return type:

Union[str, Instruction, None]

reset()

Reset any internal state (overridden in stateful orchestrators).

Returns:

None

Return type:

None

get_state() → dict

Return a JSON-serializable snapshot of the internal state (overridden in stateful orchestrators). Used by sdialog.agents.Agent.get_state().

Returns:

State dictionary (empty for stateless orchestrators).

Return type:

dict

set_state(state: dict)

Restore internal state from get_state() output (overridden in stateful orchestrators). Used by sdialog.agents.Agent.set_state().

Parameters:

state (dict) – State dictionary as returned by get_state().

Returns:

None

Return type:

None

class sdialog.orchestrators.base.BasePersistentOrchestrator(target_agent=None, persistent: bool = None, event_label: str = None)

Bases: BaseOrchestrator

Persistent orchestrator base class to create custom persistent orchestrators. Abstract method instruct() must be implemented by subclasses.

Automatically sets persistence to True; intended for orchestrators that maintain state across the whole dialogue unless explicitly removed.

Example:

from sdialog.orchestrators import BasePersistentOrchestrator
from sdialog.personas import Persona
from sdialog.agents import Agent

# Let's create our custom persistent orchestrator to permanently flip tone after a trigger word
class FlipToneOrchestrator(BasePersistentOrchestrator):
    def __init__(self, trigger=None):
        self.trigger = trigger
    def instruct(self, dialog, utterance):
        if self.trigger and self.trigger in utterance.lower():
            return ("From now on adopt an annoyed, curt tone; keep answers short and a bit irritable.")

# Let's create our agents
alice = Agent(persona=Persona(name="Alice", role="daughter"))
bob = Agent(persona=Persona(name="Bob", role="dad"))

# Let's create our orchestrator using "sweet" as the trigger word
orchestrator = FlipToneOrchestrator(trigger="sweet")

# Let's attach the orchestrator to Alice
alice = alice | orchestrator

dialog = alice.dialog_with(bob)
dialog.print(orchestration=True)
abstractmethod instruct(dialog: List[Turn], utterance: str) → str

Persistent variant of BaseOrchestrator.instruct().

Parameters:
  • dialog (List[Turn]) – Current dialog state.

  • utterance (str) – Last opposite-party utterance.

Returns:

Instruction text/object or None.

Return type:

Union[str, Instruction, None]

reset()

Reset internal persistent state (override as needed).

Returns:

None

Return type:

None


sdialog.generators

This module provides classes for generating synthetic dialogues using LLMs, including support for persona-based role-play and context-driven dialogue generation.

class sdialog.generators.DialogGenerator(dialogue_details: str, context: str | Context | None = None, example_dialogs: List[Dialog] = None, scenario: dict | str | None = None, personas: dict[str, dict[str, ~typing.Any]]=None, output_format: dict | BaseModel = <class 'sdialog.generators.base.LLMDialogOutput'>, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: object

Base class for generating synthetic dialogues using an LLM.

Typical workflow:

  1. Instantiate with default dialogue instructions and optional context / examples.

  2. Call generate(…) to produce a Dialog (or raw structured output).

Example:

from sdialog.generators import DialogGenerator

gen = DialogGenerator("Generate a short friendly greeting between two speakers")

dialog = gen.generate()
dialog.print()
Parameters:
  • dialogue_details (str) – Instructions or details for the dialogue.

  • context (Optional[Union[str, Context]]) – The default context for the dialogue (optional).

  • example_dialogs (List[Dialog]) – Optional default list of example dialogues to guide the generation.

  • scenario (Optional[Union[dict, str]]) – Default scenario metadata for the dialogue.

  • personas (dict[str, dict[str, Any]]) – Optional personas (serialized) involved in the dialogue (e.g., for logging).

  • output_format (Union[dict, BaseModel]) – Output schema / model used to parse LLM output (or None for raw text).

  • model (Union[BaseLanguageModel, str]) – The LLM instance or model name to use.

  • llm_kwargs (dict) – Additional keyword arguments for the LLM (override config).

prompt() → str

Returns the current system prompt used for dialogue generation.

Returns:

The system prompt string.

Return type:

str

generate(dialogue_details: str = None, context: str | Context | None = None, example_dialogs: List[Dialog] = None, scenario: dict | str | None = None, seed: int = None, id: int = None, parent_id: int = None, notes: str = None)

Generates a synthetic dialogue using the LLM.

Parameters:
  • dialogue_details (str) – Override instructions / details for this generation.

  • context (Optional[Union[str, Context]]) – Override context for this generation.

  • example_dialogs (List[Dialog]) – Override example dialogues for few-shot style guidance.

  • scenario (Optional[Union[dict, str]]) – Override scenario metadata.

  • seed (int) – Random seed for reproducibility.

  • id (int) – Optional dialogue ID to assign (otherwise autogenerated).

  • parent_id (int) – Optional parent dialogue ID (thread linkage).

  • notes (str) – Optional free-form notes stored in metadata.

Returns:

Dialog instance if output_format is LLMDialogOutput; BaseModel if custom schema; raw string if output_format is falsy.

Return type:

Union[Dialog, BaseModel, str]

__call__(dialogue_details: str = None, context: str | Context | None = None, example_dialogs: List[Dialog] = None, scenario: dict | str | None = None, seed: int = None, id: int = None, parent_id: int = None, notes: str = None)

Generates a synthetic dialogue using the LLM.

Parameters:
  • dialogue_details (str) – Override instructions / details for this generation.

  • context (Optional[Union[str, Context]]) – Override context for this generation.

  • example_dialogs (List[Dialog]) – Override example dialogues for few-shot style guidance.

  • scenario (Optional[Union[dict, str]]) – Override scenario metadata.

  • seed (int) – Random seed for reproducibility.

  • id (int) – Optional dialogue ID to assign (otherwise autogenerated).

  • parent_id (int) – Optional parent dialogue ID (thread linkage).

  • notes (str) – Optional free-form notes stored in metadata.

Returns:

Dialog instance if output_format is LLMDialogOutput; BaseModel if custom schema; raw string if output_format is falsy.

Return type:

Union[Dialog, BaseModel, str]

class sdialog.generators.PersonaDialogGenerator(persona_a: Persona | Agent, persona_b: Persona | Agent, speaker_a: str = 'SPEAKER_A', speaker_b: str = 'SPEAKER_B', context: str | Context | None = None, example_dialogs: List[Dialog] = None, dialogue_details: str = '', response_details: str = '', scenario: dict | str | None = None, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: DialogGenerator

Generates dialogues between two personas (or Agents wrapping personas) using an LLM.

Example:

from sdialog.personas import Persona
from sdialog.generators import PersonaDialogGenerator

p1 = Persona(name="Alice", role="Curious student")
p2 = Persona(name="Mentor", role="Helpful tutor")

gen = PersonaDialogGenerator(p1, p2, dialogue_details="Explain one concept briefly.")

dialog = gen()
dialog.print()
Parameters:
  • persona_a (Union[Persona, Agent]) – The first persona or an Agent containing one.

  • persona_b (Union[Persona, Agent]) – The second persona or an Agent containing one.

  • speaker_a (str) – Name/ID of the first speaker in the dialogue.

  • speaker_b (str) – Name/ID of the second speaker in the dialogue.

  • context (Optional[Union[str, Context]]) – Default context for the dialogue (optional).

  • example_dialogs (List[Dialog]) – Optional list of example dialogues for guidance.

  • dialogue_details (str) – Additional dialogue-level instructions.

  • response_details (str) – Style / formatting instructions for responses.

  • scenario (Optional[Union[dict, str]]) – Default scenario metadata.

  • model (Union[BaseLanguageModel, str]) – LLM instance or model name.

  • llm_kwargs (dict) – Extra LLM keyword arguments (override config).

generate(context: str | Context | None = None, example_dialogs: List[Dialog] = None, scenario: dict | str | None = None, seed: int = None, id: int = None, parent_id: int = None, max_turns: int = 200, notes: str = None)

Generates a dialogue between two personas (or drives an Agent-to-Agent interaction).

Parameters:
  • context (Optional[Union[str, Context]]) – Override context.

  • example_dialogs (List[Dialog]) – Override example dialogues.

  • scenario (Optional[Union[dict, str]]) – Override scenario metadata.

  • seed (int) – Random seed for reproducibility.

  • id (int) – Dialogue ID override.

  • parent_id (int) – Parent dialogue ID (thread).

  • max_turns (int) – Max turns (only applies when both participants are Agents).

  • notes (str) – Optional metadata notes.

Returns:

Generated dialogue object.

Return type:

Dialog

__call__(context: str | Context | None = None, example_dialogs: List[Dialog] = None, scenario: dict | str | None = None, seed: int = None, id: int = None, parent_id: int = None, max_turns: int = 200, notes: str = None)

Generates a dialogue between two personas (or drives an Agent-to-Agent interaction).

Parameters:
  • context (Optional[Union[str, Context]]) – Override context.

  • example_dialogs (List[Dialog]) – Override example dialogues.

  • scenario (Optional[Union[dict, str]]) – Override scenario metadata.

  • seed (int) – Random seed for reproducibility.

  • id (int) – Dialogue ID override.

  • parent_id (int) – Parent dialogue ID (thread).

  • max_turns (int) – Max turns (only applies when both participants are Agents).

  • notes (str) – Optional metadata notes.

Returns:

Generated dialogue object.

Return type:

Dialog

class sdialog.generators.PersonaGenerator(persona: BaseAttributeModel, generated_attributes: str = 'all', extra_instructions: str = 'Attributes must be in English', model: str = None, **llm_kwargs)

Bases: BaseAttributeModelGenerator

Generates persona objects (subclasses of sdialog.personas.BasePersona) with randomized or LLM-populated attributes (see sdialog.generators.BaseAttributeModelGenerator for more information).

Example:

from sdialog.personas import Doctor
from sdialog.generators import PersonaGenerator

base_persona = Doctor(specialty="Cardiology")

doctor_generator = PersonaGenerator(base_persona)

doctor_generator.set(
    years_of_experience="{4-10}",
    gender=["male", "female", "non-binary"]
)

doctor = doctor_generator.generate()
doctor.print()
Parameters:
  • persona (BasePersona) – Persona instance or class to generate.

  • generated_attributes (Union[str, list, dict]) – Strategy specifying which attributes to fill (“all”, list, or dict).

  • extra_instructions (str) – Additional instructions to include in the LLM prompt.

  • model (str) – LLM model name (optional).

  • llm_kwargs (dict) – Extra LLM keyword arguments.

class sdialog.generators.ContextGenerator(context: Context = None, generated_attributes: str = 'all', extra_instructions: str = 'Attributes must be in English', model: str = None, **llm_kwargs)

Bases: BaseAttributeModelGenerator

Generates Context objects with randomized or LLM-populated attributes (see sdialog.generators.BaseAttributeModelGenerator for more information).

Example:

from sdialog import Context
from sdialog.generators import ContextGenerator

base_context = Context(location="Mars Forward Base Alpha")

ctx_generator = ContextGenerator(base_context)

ctx_generator.set(
    objects=get_objects_from_db,  # callable function
    topics=["terraforming", "resource logistics", "crew morale"]
    circumstances="{csv:circumstances:./data/circumstances.csv}",
    goals="{llm:Suggest a realistic goal for the context}"
)

my_context = ctx_generator.generate()
my_context.print()
Parameters:
  • context (Context) – Context instance or subclass to generate.

  • generated_attributes (Union[str, list, dict]) – Attribute selection strategy (“all”, list, or dict).

  • extra_instructions (str) – Additional instructions to include in the LLM prompt.

  • model (str) – LLM model name (optional).

  • llm_kwargs (dict) – Extra LLM keyword arguments.

class sdialog.generators.Paraphraser(extra_instructions: str = 'Keep entities and values identical while making it sound more natural', target_speaker: str = None, turn_by_turn: bool = False, model: str | langchain_core.language_models.base.BaseLanguageModel = None, **llm_kwargs)

Bases: object

Paraphrases dialogue turns while preserving semantic entities/values.

Usage modes:

  • Whole dialogue paraphrasing (default, returns full set of possibly modified turns).

  • Turn-by-turn paraphrasing (stream-like, for smaller LLMs).

Example:

from sdialog.generators import Paraphraser

# Assume 'original_dialog' is an existing `Dialog` with one of the speaker being "Bot"
paraphraser = Paraphraser("Make the text sound more natural and less robotic",
                          target_speaker="Bot")

new_dialog = paraphraser(original_dialog)
new_dialog.print()
Parameters:
  • extra_instructions (str) – Additional style or behavior instructions for the paraphrase.

  • target_speaker (Optional[str]) – If provided, only paraphrases turns spoken by this speaker.

  • turn_by_turn (bool) – Whether to paraphrase one turn at a time.

  • model (Union[str, BaseLanguageModel]) – The LLM instance or model name to use (falls back to config if None).

  • llm_kwargs (dict) – Additional keyword arguments for the LLM.

__call__(dialog: Dialog, target_speaker: str = None, raise_on_validation_failure: bool = True, seed: int = None) → Dialog

Paraphrase a dialog (entirely or selectively by speaker).

Parameters:
  • dialog (Dialog) – Source dialogue to paraphrase.

  • target_speaker (Optional[str]) – Override target speaker filter for this call.

  • raise_on_validation_failure (bool) – Whether to raise an error if the LLM output fails validation.

  • seed (Optional[int]) – Optional random seed (used for reproducibility where supported).

Returns:

New Dialog instance with paraphrased turns.

Return type:

Dialog

Raises:

ValueError – (Indirectly) if underlying validation fails.

prompt() → str

Returns the combined system prompt and current instruction template.

Returns:

Combined prompt preview.

Return type:

str

sdialog.generators.base

Base and abstract classes for generators in sdialog.

class sdialog.generators.base.BaseAttributeModelGenerator(attribute_model: BaseAttributeModel, generated_attributes: str = 'all', extra_instructions: str = '', model: str = None, system_prompt: str = None, llm_prompt: str = None, llm_prompt_n: str = None, **llm_kwargs)

Bases: ABC

Abstract class to create subclasses for generators with randomized and/or LLM-populated attributes.

Workflow:

  1. Provide a target attribute model instance or class.

  2. Configure attribute generation rules (e.g. .set(...) or generated_attributes='all').

  3. Call generate(n=...) to produce validated instances.

Parameters:
  • attribute_model (BaseAttributeModel) – Instance or subclass of BaseAttributeModel to generate.

  • generated_attributes (Union[str, list, dict]) – Attribute selection strategy (“all”, iterable, or dict of rules).

  • extra_instructions (str) – Additional instructions to include in the LLM prompt.

  • model (str) – LLM model name (overrides config if provided).

  • system_prompt (str) – Override system prompt for generation.

  • llm_prompt (str) – Template for single-object generation.

  • llm_prompt_n (str) – Template for multi-object generation (n > 1).

  • llm_kwargs (dict) – Extra LLM instantiation parameters.

prompt() → str

Returns the single-object prompt template text.

Returns:

The prompt string.

Return type:

str

set(**attributes)

Define per-attribute randomization / generation specifications as attribute_name=<value>.

Where <value> can be:

  • “*”: Defer to LLM.

  • A callable: Invoked (with current partial object as kwargs if compatible).

  • A list: Random element chosen.

  • A fixed scalar / str: Assigned directly.

  • A templated string "{...}":

    • "{min-max}": Random int in inclusive range.

    • "{txt:PATH}": Random non-empty line from file.

    • "{csv:COLUMN:PATH}": Random value from CSV column (name or index).

    • "{tsv:COLUMN:PATH}": Same for TSV.

    • "{llm}": Defer to LLM.

    • "{llm:INSTRUCTION}": Defer with custom instruction.

Example:

from sdialog.generators import ContextGenerator

ctx_gen = ContextGenerator()

ctx_gen.set(
    location=["office", "home", "school"],
    objects=get_objects_from_db,  # callable function
    circumstances="{csv:circumstances:./data/circumstances.csv}",
    goals="{llm:Suggest a realistic goal for the context}"
)

my_context = ctx_gen.generate()
my_context.print()
Parameters:

attributes – Mapping of attribute name -> generation rule.

Raises:

ValueError – If any attribute is not defined on the target model.

generate(n: int = 1, temperature: float = None, seed: int = None, id: int = None, parent_id: int = None, notes: str = None, max_attempts: int = 3) → BaseAttributeModel

Generate one or many model instances using random rules, templates, and/or LLM completion.

Parameters:
  • n (int) – Number of instances to generate.

  • temperature (float) – LLM temperature (if LLM used).

  • seed (int) – Random seed for reproducibility.

  • id (int) – Optional explicit ID for single-object generation (each object gets its own if multiple).

  • parent_id (int) – Optional parent ID linkage.

  • notes (str) – Optional metadata notes.

  • max_attempts (int) – Maximum retries to fill missing attributes.

Returns:

A single instance if n == 1, else a list of instances.

Return type:

Union[BaseAttributeModel, List[BaseAttributeModel]]

Raises:

ValueError – On missing files referenced in template specifications.


sdialog.interpretability

This submodule provides classes and hooks for inspecting and interpreting the internal representations of PyTorch-based language models during forward passes. It enables the registration of hooks on specific model layers to capture token-level and response-level information, facilitating analysis of model behavior and interpretability. The module is designed to work with conversational agents and integrates with tokenizers and memory structures, supporting the extraction and inspection of tokens, representations, and system instructions across responses.

Typical usage involves attaching one or more Inspector objects to an agent, accumulating response and token data during inference, and providing interfaces for downstream interpretability and analysis tasks.

class sdialog.interpretability.DirectionSteerer(direction, inspector=None)

Bases: BaseSteerer

Concrete Steerer binding a direction vector for additive or subtractive steering.

Example:

import torch
from sdialog.agents import Agent
from sdialog.interpretability import Inspector, DirectionSteerer

agent = Agent()
insp = Inspector(target='model.layers.5.post_attention_layernorm')
agent = agent | insp

direction = torch.randn(4096)  # Random direction in activation space
steer = DirectionSteerer(direction)

# Add the direction (push activations along vector)
insp = steer + insp
# Or remove its projection:
insp = steer - insp

agent("Test prompt")  # steering applied during generation
Parameters:
  • direction (Union[torch.Tensor, np.ndarray]) – Direction vector (torch.Tensor or numpy array).

  • inspector (Optional[Inspector]) – Optional Inspector to bind immediately.

class sdialog.interpretability.Inspector(target: Dict | List[str] | str = None, agent: Any | None = None, steering_function: Callable | None = None, steering_interval: Tuple[int, int] | None = ('*', '*'), top_k: int | None = None, lm_head_layer: str | None = 'lm_head', inspect_input: bool = True)

Bases: object

Main class to manage layer hooks, cached activations, and optional steering functions for an Agent.

Example:

from sdialog.agents import Agent
from sdialog.interpretability import Inspector

agent = Agent()
insp = Inspector(target='model.layers.2.post_attention_layernorm')
agent = agent | insp  # pipe attach

agent("Explain gravity briefly.")  # Generates first response
agent("Sounds cool!")  # Generates second response

print("Num responses captured:", len(insp))
print("Last response, first token string:", insp[-1][0])
print("Last response, first token activation:", insp[-1][0].act)
# Output:
# Num responses captured: 2
# Last response, first token string: <bos>
# Last response, first token activation:
# tensor([[-0.0109, -0.1128, -0.1216,  ..., -0.0157,  0.2100, -0.2637]])
Parameters:
  • target (Union[Dict, List[str], str, None]) – Mapping (cache_key->layer_name) or list / single layer name (optional). If None, no hooks are added until add_hooks/add_agent is called. Defaults to None.

  • agent (Optional[Agent]) – Agent instance to attach to (optional). If provided with a non-empty target, hooks are registered immediately. Defaults to None.

  • steering_function (Optional[Union[Callable, List[Callable]]]) – Initial steering function or list of functions (optional). Applied to token activations during generation. Defaults to None.

  • steering_interval (Optional[Tuple[int, int]]) – (min_token, max_token) steering window (optional). Defaults to (“*”, “*”), where “*” means no lower or/and upper bound.

  • top_k (Optional[int]) – Number of top token predictions to store for each token. If None, logits are not captured. If -1, all tokens in the vocabulary are returned with their logits. Defaults to None.

  • lm_head_layer (Optional[str]) – Name of the language model head layer (e.g., “lm_head”). Defaults to “lm_head”. If the specified layer is not found, the code will attempt to auto-detect it.

  • inspect_input (bool) – If True (default), captures activations before the layer processes them (input activations). If False, captures activations after the layer processes them (output activations). Defaults to False.

property input
property vocab_size

Return the vocabulary size of the tokenizer.

Returns:

Vocabulary size (number of tokens in the tokenizer’s vocabulary).

Return type:

int

Raises:

ValueError – If no agent is attached.

add_agent(agent)

Attach an Agent after construction and (re)register hooks if target specified.

Parameters:

agent (Agent) – Agent instance.

add_steering_function(steering_function)

Adds a steering function to the inspector’s list of functions.

Parameters:

steering_function (Callable) – Callable accepting activation tensor.

add_hooks(target)

Adds hooks to the agent’s model based on the provided target mapping.

Parameters:

target (Dict) – Dict mapping cache_key -> layer_name to append.

Raises:

ValueError – If no agent is attached.

recap()

Prints and returns the current hooks assigned to the inspector’s agent. Also prints the ‘target’ mapping in a clean, readable format. Includes any found instructions across responses.

find_instructs(verbose=False)

Return list with ‘index’ and ‘content’ for each SystemMessage (excluding first memory) found in the agent’s memory. If verbose is True, also print each.

Parameters:

verbose (bool) – If True, logs each found instruction.

Returns:

List of dicts with keys ‘index’ and ‘content’.

Return type:

List[Dict[str, Union[int, str]]]


sdialog.evaluation

Evaluation components for dialogue generation and analysis.

This module provides classes for evaluating dialogues, including LLM judges, metrics, and similarity scores.

class sdialog.evaluation.ConversationalFeatures(feature: List[Literal['mean-turn-length', 'hesitation-rate', 'turn-taking-ratio', 'question-rate', 'lexical-diversity', 'back-channel-rate', 'filler-word-density']] | None = None, name: str = None, speaker: str | None = None)

Bases: BaseDialogScore

Compute conversational and dialogue-specific features.

These metrics measure dialogue structure, speech patterns, and interaction dynamics rather than text readability.

Example:

from sdialog.evaluation import ConversationalFeatures

# All conversational features
scorer_all = ConversationalFeatures()
# Single feature
scorer_hes = ConversationalFeatures(feature="hesitation-rate")
# Multiple features
scorer_multi = ConversationalFeatures(feature=["question-rate", "lexical-diversity"])

print(scorer_all(dialog))      # dict with all feature values
print(scorer_hes(dialog))      # single float (hesitation rate)
print(scorer_multi(dialog))    # dict with selected features
Parameters:
  • feature (Optional[List[Literal["mean-turn-length", "hesitation-rate", "turn-taking-ratio", "question-rate", "lexical-diversity", "back-channel-rate", "filler-word-density"]]]) –

    List of feature names to compute. If None (default) compute all. If the resulting set has size 1, __call__ / score returns a single float; otherwise a dict. Available features:

    • "mean-turn-length": average number of words per dialogue turn.

    • "hesitation-rate": percentage of hesitation tokens over total words (%).

    • "turn-taking-ratio": distribution of turns between speakers

      (entropy-based, 0=monopolized, 1=balanced).

    • "question-rate": percentage of turns containing questions (%).

    • "lexical-diversity": type-token ratio measuring vocabulary richness (0-1).

    • "back-channel-rate": percentage of minimal response turns (%).

    • "filler-word-density": percentage of filler words over total words (%).

  • name (str) – Internal score name (defaults to "conversational-features" or the single feature name if only one provided).

  • speaker (Optional[str]) – If set, only turns by this speaker (case-insensitive) are considered. Note: turn-taking-ratio ignores this parameter as it requires multiple speakers.

static count_hesitations(text)

Count hesitation tokens in the provided text (e.g., uh, um, hmm).

Parameters:

text (str) – Input text to search for hesitation markers.

Returns:

Number of detected hesitation tokens in the provided text.

Return type:

int

static count_filler_words(text)

Count filler words in the provided text (e.g., like, you know, I mean, basically).

Parameters:

text (str) – Input text to search for filler words.

Returns:

Number of detected filler words in the provided text.

Return type:

int

static is_back_channel(turn_text)

Check if a turn is a back-channel response (minimal acknowledgment).

Parameters:

turn_text (str) – Text of a single turn.

Returns:

True if the turn is a back-channel response.

Return type:

bool

static calculate_turn_taking_ratio(dialog)

Calculate turn-taking balance using normalized entropy.

Returns a value between 0 (monopolized conversation) and 1 (perfectly balanced). Based on Shannon entropy normalized by maximum possible entropy.

Parameters:

dialog (Dialog) – Dialog object with turns from multiple speakers.

Returns:

Turn-taking ratio (0-1).

Return type:

float

score(dialog: Dialog) → float | dict

Compute one or multiple conversational features for the dialogue.

Parameters:

dialog (Dialog) – Dialogue instance to evaluate.

Returns:

If exactly one feature is requested, returns a single float. Otherwise returns a dict mapping feature-name to numeric value.

Return type:

Union[float, dict]

class sdialog.evaluation.ReadabilityScore(feature: List[Literal['gunning-fog', 'flesch-reading-ease', 'coleman-liau', 'linsear-write', 'dale-chall']] | None = None, name: str = None, speaker: str | None = None)

Bases: BaseDialogScore

Compute one or multiple readability metrics for a dialogue text: Gunning Fog index, Flesch Reading Ease score, Coleman-Liau Index, Linsear Write metric, and Dale-Chall Readability Formula.

These metrics measure text complexity and reading difficulty, not dialogue structure.

Example:

from sdialog.evaluation import ReadabilityScore

# All readability metrics
scorer_all = ReadabilityScore()
# Single metric
scorer_flesch = ReadabilityScore(feature="flesch-reading-ease")
# Subset of metrics
scorer_subset = ReadabilityScore(feature=["gunning-fog", "coleman-liau"])

print(scorer_all(dialog))      # dict with all metric values
print(scorer_flesch(dialog))   # single float (Flesch score)
print(scorer_subset(dialog))   # dict with the two requested metrics
Parameters:
  • feature (Optional[List[Literal["gunning-fog", "flesch-reading-ease", "coleman-liau", "linsear-write", "dale-chall"]]]) –

    List of feature names to compute. If None (default) compute all. If the resulting set has size 1, __call__ / score returns a single float; otherwise a dict. Available features:

    • "gunning-fog": Gunning Fog readability index.

    • "flesch-reading-ease": Flesch Reading Ease score.

    • "coleman-liau": Coleman-Liau Index.

    • "linsear-write": Linsear Write readability metric.

    • "dale-chall": Dale-Chall Readability Formula.

  • name (str) – Internal score name (defaults to "readability-score" or the single feature name if only one provided).

  • speaker (Optional[str]) – If set, only turns by this speaker (case-insensitive) are considered.

static calculate_gunning_fog(text)

Compute the Gunning Fog index of the provided text.

Parameters:

text (str) – Input text.

Returns:

Gunning Fog index value.

Return type:

float

static calculate_flesch_reading_ease(text)

Compute the Flesch Reading Ease score of the provided text.

Parameters:

text (str) – Input text.

Returns:

Reading ease score.

Return type:

float

static calculate_coleman_liau(text)

Compute the Coleman-Liau Index of the provided text.

The Coleman-Liau Index estimates the U.S. grade level needed to understand the text. It uses character counts instead of syllable counts.

Parameters:

text (str) – Input text.

Returns:

Coleman-Liau Index value (minimum 0).

Return type:

float

static calculate_linsear_write(text)

Compute the Linsear Write readability metric of the provided text.

The Linsear Write formula estimates the U.S. grade level needed to understand the text. It focuses on easy vs. difficult words (based on syllable count).

Parameters:

text (str) – Input text.

Returns:

Linsear Write score.

Return type:

float

static calculate_dale_chall(text)

Compute the Dale-Chall Readability Formula score of the provided text.

The Dale-Chall formula uses a list of 3000 familiar words that 80% of 4th-grade students understand. Words not on this list are considered “difficult”.

Note: This implementation uses a simplified approximation based on word length and syllable count as a proxy for the Dale-Chall word list, since the full list is proprietary.

Parameters:

text (str) – Input text.

Returns:

Dale-Chall score.

Return type:

float

score(dialog: Dialog) → float | dict

Compute one or multiple readability metrics for the dialogue.

Parameters:

dialog (Dialog) – Dialogue instance to evaluate.

Returns:

If exactly one metric is requested, returns a single float. Otherwise returns a dict mapping metric-name to numeric value.

Return type:

Union[float, dict]

class sdialog.evaluation.MeanTurnLengthScore(name: str = None, speaker: str | None = None)

Bases: ConversationalFeatures

Compute the mean turn length (average number of words per turn) for a dialogue.

This is a conversational metric that measures dialogue structure, not text readability.

Example:

from sdialog.evaluation import MeanTurnLengthScore

scorer = MeanTurnLengthScore()
print(scorer(dialog))  # Outputs mean turn length as float
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “mean-turn-length”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.TurnLength(name: str = None, speaker: str | None = None)

Bases: BaseDialogScore

Compute individual turn lengths (number of words per turn) for a dialogue.

Returns a list of word counts for each turn in the dialogue. This is a granular metric that captures turn length distribution, often used as raw input for downstream aggregations (e.g., computing mean or median turn length).

Example:

from sdialog.evaluation import TurnLength

scorer = TurnLength()
lengths = scorer(dialog)  # Returns list of integers
print(lengths)  # [5, 12, 3, 18, ...] words per turn

# Filter by speaker
scorer_system = TurnLength(speaker="System")
system_lengths = scorer_system(dialog)
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “turn-length”).

  • speaker (Optional[str]) – If set, only turns by this speaker (case-insensitive) are considered.

score(dialog: Dialog) → List[int]

Compute word count for each turn in the dialogue.

Parameters:

dialog (Dialog) – Dialogue instance to evaluate.

Returns:

List of integers representing word count per turn.

Return type:

List[int]

class sdialog.evaluation.HesitationRateScore(name: str = None, speaker: str | None = None)

Bases: ConversationalFeatures

Compute the hesitation rate (percentage of hesitation tokens) for a dialogue.

This is a conversational metric that measures speech disfluencies, not text readability.

Example:

from sdialog.evaluation import HesitationRateScore

scorer = HesitationRateScore()
print(scorer(dialog))  # Outputs hesitation rate as percentage
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “hesitation-rate”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.TurnTakingRatioScore(name: str = None)

Bases: ConversationalFeatures

Compute the turn-taking ratio (balance of conversation between speakers) for a dialogue.

Returns a value between 0 (monopolized) and 1 (perfectly balanced), based on normalized Shannon entropy of turn distribution across speakers.

Example:

from sdialog.evaluation import TurnTakingRatioScore

scorer = TurnTakingRatioScore()
print(scorer(dialog))  # Outputs turn-taking ratio (0-1)
Parameters:

name (Optional[str]) – Optional score name (defaults to “turn-taking-ratio”).

class sdialog.evaluation.QuestionRateScore(name: str = None, speaker: str | None = None)

Bases: ConversationalFeatures

Compute the question rate (percentage of turns containing questions) for a dialogue.

This metric measures the interrogative nature of the conversation.

Example:

from sdialog.evaluation import QuestionRateScore

scorer = QuestionRateScore()
print(scorer(dialog))  # Outputs question rate as percentage
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “question-rate”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.LexicalDiversityScore(name: str = None, speaker: str | None = None)

Bases: ConversationalFeatures

Compute the lexical diversity (type-token ratio) for a dialogue.

Measures vocabulary richness as the ratio of unique words to total words (0-1). Higher values indicate more varied vocabulary.

Example:

from sdialog.evaluation import LexicalDiversityScore

scorer = LexicalDiversityScore()
print(scorer(dialog))  # Outputs lexical diversity (0-1)
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “lexical-diversity”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.BackChannelRateScore(name: str = None, speaker: str | None = None)

Bases: ConversationalFeatures

Compute the back-channel rate (percentage of minimal response turns) for a dialogue.

Back-channels are brief responses like “yeah”, “okay”, “I see” that indicate active listening without contributing substantial content.

Example:

from sdialog.evaluation import BackChannelRateScore

scorer = BackChannelRateScore()
print(scorer(dialog))  # Outputs back-channel rate as percentage
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “back-channel-rate”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.FillerWordDensityScore(name: str = None, speaker: str | None = None)

Bases: ConversationalFeatures

Compute the filler word density (percentage of filler words) for a dialogue.

Filler words include “like”, “you know”, “I mean”, “basically”, etc. These differ from hesitations and indicate informal speech patterns.

Example:

from sdialog.evaluation import FillerWordDensityScore

scorer = FillerWordDensityScore()
print(scorer(dialog))  # Outputs filler word density as percentage
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “filler-word-density”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.GunningFogScore(name: str = None, speaker: str | None = None)

Bases: ReadabilityScore

Compute the Gunning Fog readability index for a dialogue.

The Gunning Fog index estimates the years of formal education needed to understand the text on a first reading. Higher values indicate more complex text.

Example:

from sdialog.evaluation import GunningFogScore

scorer = GunningFogScore()
print(scorer(dialog))  # Outputs Gunning Fog index as float
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “gunning-fog”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.FleschReadingEaseScore(name: str = None, speaker: str | None = None)

Bases: ReadabilityScore

Compute the Flesch Reading Ease score for a dialogue.

The Flesch Reading Ease score rates text on a 100-point scale. Higher scores indicate text that is easier to read. Scores typically range from 0 (very difficult) to 100 (very easy).

Example:

from sdialog.evaluation import FleschReadingEaseScore

scorer = FleschReadingEaseScore()
print(scorer(dialog))  # Outputs Flesch Reading Ease score as float
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “flesch-reading-ease”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.ColemanLiauScore(name: str = None, speaker: str | None = None)

Bases: ReadabilityScore

Compute the Coleman-Liau Index for a dialogue.

The Coleman-Liau Index estimates the U.S. grade level needed to understand the text. Unlike other readability formulas, it uses character counts instead of syllable counts, making it more suitable for automated text analysis.

Example:

from sdialog.evaluation import ColemanLiauScore

scorer = ColemanLiauScore()
print(scorer(dialog))  # Outputs Coleman-Liau Index as float
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “coleman-liau”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.LinsearWriteScore(name: str = None, speaker: str | None = None)

Bases: ReadabilityScore

Compute the Linsear Write readability metric for a dialogue.

The Linsear Write formula estimates the U.S. grade level needed to understand the text. It focuses on easy versus difficult words (based on syllable count) and is particularly useful for technical writing assessment.

Example:

from sdialog.evaluation import LinsearWriteScore

scorer = LinsearWriteScore()
print(scorer(dialog))  # Outputs Linsear Write score as float
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “linsear-write”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.DaleChallScore(name: str = None, speaker: str | None = None)

Bases: ReadabilityScore

Compute the Dale-Chall Readability Formula score for a dialogue.

The Dale-Chall formula uses a list of familiar words that most 4th-grade students understand. Words not on this list are considered “difficult”. This implementation uses a simplified approximation based on word length and syllable count as a proxy for the Dale-Chall word list.

Example:

from sdialog.evaluation import DaleChallScore

scorer = DaleChallScore()
print(scorer(dialog))  # Outputs Dale-Chall score as float
Parameters:
  • name (Optional[str]) – Optional score name (defaults to “dale-chall”).

  • speaker (Optional[str]) – If set, only turns by this speaker are considered.

class sdialog.evaluation.ToolSequenceValidator(tool_names: List[str], name: str = 'tool-sequence-validator', forbidden_tools: List[str] | None = None)

Bases: BaseDialogScore

Validate that an agent used specific tools in the correct sequence during a dialogue.

This validator checks whether the agent called the specified tools in the expected order based on the dialogue’s event history. It returns 1 if the sequence is valid, 0 otherwise.

Tool names can be prefixed with "not:" to indicate that the tool must NOT be called at that position of the sequence, that is, between the previous and the next tools in the list (from the start or until the end of the dialogue if there are none). This allows for flexible validation of tool usage patterns.

Example 1: Basic sequence validation

from sdialog.evaluation import ToolSequenceValidator

# Validate that tools were called in exact order
validator = ToolSequenceValidator(["search_flights", "book_flight", "confirm_booking"])

score = validator(dialog)
print(score)  # 1 if sequence correct, 0 otherwise

Example 2: Using negative constraints

from sdialog.evaluation import ToolSequenceValidator

# Ensure send_receipt is NOT called before charging payment
# (don't send receipt before actually charging the customer)
# But send_receipt may be called after charge_payment, or not at all
validator = ToolSequenceValidator([
    "not:send_receipt",
    "charge_payment",
    "update_inventory"
])

score = validator(dialog)

Example 3: Forbidden tools (anywhere in the dialogue, regardless of the order)

from sdialog.evaluation import ToolSequenceValidator

# Plans must be retrieved, and the account must never be verified
validator = ToolSequenceValidator(["get_service_plans"], forbidden_tools=["verify_account"])
score = validator(dialog)

Example 4: With evaluators

from sdialog.evaluation import ToolSequenceValidator, FrequencyEvaluator

validator = ToolSequenceValidator(["authenticate", "fetch_data", "logout"])
freq_eval = FrequencyEvaluator(validator)

# Get percentage of dialogues with correct tool sequence
percentage = freq_eval(dialogs)
print(f"{percentage * 100:.1f}% of dialogues follow correct sequence")
Parameters:
  • tool_names (List[str]) –

    List of tool names defining the expected sequence. Each tool name can be:

    • A plain string (e.g., "search_flights"): tool must be called in sequence.

    • Prefixed with "not:" (e.g., "not:verify_account"): tool must NOT be called between the previous and the next required tools (the start and the end of the dialogue if there are none), though it may be called elsewhere or omitted. E.g. ["not:x", "a"]: no x before a; ["a", "not:x"]: no x after a; ["not:x", "a", "not:x"]: no x at all.

  • name (str) – Custom score name (defaults to "tool-sequence-validator").

  • forbidden_tools (Optional[List[str]]) – Tools that must not be called anywhere in the dialogue, regardless of the order.

Note

  • Tools must appear in the specified order within the dialogue’s event history.

  • The first tool in the sequence must come after at least one user utterance.

  • If a required tool (without "not:" prefix) is missing, the score is 0.

  • Tools with "not:" prefix that don’t appear in the dialogue are ignored.

score(dialog: Dialog) → int

Compute the validation score for the dialogue’s tool usage sequence.

Extracts tool calls from the dialogue’s event history and validates that: 1. All required tools (without "not:" prefix) are present. 2. Tools appear in the specified order. 3. Tools with "not:" prefix do not appear between the previous and the next required tools. 4. The first tool call comes after at least one user utterance. 5. Forbidden tools (forbidden_tools) are not called at all.

Parameters:

dialog (Dialog) – Dialogue instance to validate.

Returns:

1 if the tool sequence is valid, 0 otherwise.

Return type:

int

Note

Returns 0 if: - The dialogue has no events, or both tool_names and forbidden_tools are empty. - A required tool is missing from the event history. - Tools appear in incorrect order. - A "not:" prefixed tool appears between the previous and the next required tools. - A forbidden tool is called.

class sdialog.evaluation.DialogFlowPPL(reference_dialogues: str | List[Dialog], ai_speaker: str = None, k_neighbors: int = 64, use_softmax: bool = True, use_only_known_edges: bool = False, name: str = None, verbose: bool = False, **d2f_kwargs)

Bases: BaseDialogFlowScore

Compute flow perplexity-like score of a dialogue against reference dialogues.

Given a collection of reference dialogues, it first builds the dialogue flow graph that represent them. Then, given a candidate dialogue, it computes a flow perplexity-like score (i.e. “how well it fits on the reference graph in terms of perplexity?”).

Example:

from sdialog.evaluation import DialogFlowPPL

# reference_dialogs = [...]
flow_ppl = DialogFlowPPL(reference_dialogs)

value = flow_ppl(candidate_dialog)

print("Flow Perplexity:", value)
Parameters:
  • reference_dialogues (Union[str, List[Dialog]]) – List of reference dialogues or file path.

  • ai_speaker (Optional[str]) – If set, restrict scoring to AI/system turns.

  • k_neighbors (int) – Neighbor count for embedding lookup.

  • use_softmax (bool) – Whether to weight neighbors via softmax.

  • use_only_known_edges (bool) – If True, ignore unknown transitions (penalize less).

  • name (Optional[str]) – Custom score name override.

  • verbose (bool) – Verbosity flag.

  • d2f_kwargs (dict) – Extra kwargs to dialog2graph.

score(dialog: Dialog) → float

Compute flow perplexity-like score (exp of negative average log probability).

Parameters:

dialog (Dialog) – Dialogue to score.

Returns:

Perplexity value or None if insufficient transitions.

Return type:

Optional[float]

class sdialog.evaluation.DialogFlowScore(reference_dialogues: str | List[Dialog], ai_speaker: str = None, k_neighbors: int = 64, use_softmax: bool = True, use_only_ai_speaker: bool = False, use_only_known_edges: bool = False, name: str = None, verbose: bool = False, graph=None, nodes=None, **d2f_kwargs)

Bases: BaseDialogFlowScore

Compute flow likelihood score of a dialogue against reference dialogues.

Given a collection of reference dialogues, it first builds the dialogue flow graph that represent them. Then, given a candidate dialogue, it computes a flow likelihood score based on the geometric mean of edge probabilities (i.e. “how well the dialogue fits on the reference graph”).

Example:

from sdialog.evaluation import DialogFlowScore

flow_score = DialogFlowScore(reference_dialogs)

print(flow_score(candidate_dialog))
Parameters:
  • reference_dialogues (Union[str, List[Dialog]]) – List of reference dialogues or file path.

  • ai_speaker (Optional[str]) – Restrict scoring to AI/system turns if provided.

  • k_neighbors (int) – Neighbor count for embedding lookup.

  • use_softmax (bool) – Whether to weight neighbors via softmax.

  • use_only_ai_speaker (bool) – If True, only AI turns are used to build the graph and compute the scores.

  • use_only_known_edges (bool) – If True, only known edges contribute.

  • name (Optional[str]) – Custom score name.

  • verbose (bool) – Verbosity flag.

  • graph (Any) – Pre-built graph (optional).

  • nodes (dict) – Pre-built node metadata (optional).

  • d2f_kwargs (dict) – Extra kwargs to dialog2graph.

score(dialog: Dialog) → float

Compute geometric mean transition likelihood.

Parameters:

dialog (Dialog) – Dialogue to score.

Returns:

Score value or None if insufficient transitions.

Return type:

Optional[float]

class sdialog.evaluation.LLMJudgeYesNo(prompt_template: str, reason: bool = False, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: BaseDialogScore, BaseLLMJudge

LLM judge for classifying a dialogue as “yes or no” (boolean) output and reason.

Example:

from sdialog.evaluation import LLMJudgeYesNo

magic_judge = LLMJudgeYesNo("Is this dialogue magical?", reason=True)

result = magic_judge.judge(dialog)

print(result.positive)
print(result.reason)
Parameters:
  • prompt_template (str) – Jinja2 template for judging prompt.

  • reason (bool) – Whether to request reason field.

  • model (Optional[Union[BaseLanguageModel, str]]) – Model instance or model name.

  • llm_kwargs (dict) – Extra LLM initialization kwargs.

judge(dialogs: Dialog | List[Dialog], reason: bool = None, **template_kwargs) → LLMJudgeYesNoOutput | int

Run judgment over one or multiple dialogues.

Parameters:
  • dialogs (Union[Dialog, List[Dialog]]) – A single Dialog or list of Dialogs.

  • reason (Optional[bool]) – Override reason flag (falls back to self.reason).

  • template_kwargs (dict) – Extra template kwargs.

Returns:

Structured yes/no output model.

Return type:

LLMJudgeYesNoOutput

score(dialog: Dialog) → int

Computes the score for the provided dialog, 1 if dialogues is judged as real, 0 otherwise.

Parameters:

dialog – The dialog to score.

Returns:

An int representing the score of the dialog.

class sdialog.evaluation.LLMJudgeScore(prompt_template: str, min_score: float = 1, max_score: float = 5, score_type: type = <class 'int'>, reason: bool = False, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: BaseDialogScore, BaseLLMJudge

LLM judge for scoring a dialogue with a numerical score and optional reason.

Example 1:

from sdialog.evaluation import LLMJudgeScore

magic_judge = LLMJudgeScore("From 1 to 5, how magical is this dialogue?", reason=True)

result = magic_judge.judge(dialog)

print(result.score)
print(result.reason)

Example 2:

from sdialog.evaluation import LLMJudgeScore

# You can use the `min_score`, `max_score`, `score_type` and/or `reason` parameters
# as variables in your prompt template.
prompt = (
    "On a scale from {{ min_score }} to {{ max_score }}, "
    "how magical is this dialogue?"
    "Provide a {{ score_type }} score."
)
magic_judge = LLMJudgeScore(prompt,
                            min_score=1,
                            max_score=10,
                            score_type=int)
result = magic_judge.judge(dialog)
print(result.score)
print(result.reason)
Parameters:
  • prompt_template (str) – Jinja2 template text.

  • min_score (float) – Minimum allowed score.

  • max_score (float) – Maximum allowed score.

  • score_type (type) – int or float score type.

  • reason (bool) – Whether to request reason field.

  • model (Optional[Union[BaseLanguageModel, str]]) – Model instance or model name.

  • llm_kwargs (dict) – Extra LLM kwargs.

judge(dialogs: Dialog | List[Dialog], reason: bool = None, **template_kwargs) → LLMJudgeScoreOutput

Produce a numeric judgment for one or more dialogues.

Parameters:
  • dialogs (Union[Dialog, List[Dialog]]) – Dialogue or list of dialogues.

  • reason (Optional[bool]) – Override reason flag.

  • template_kwargs (dict) – Extra template kwargs.

Returns:

Structured output containing the score and an optional reason.

Return type:

LLMJudgeScoreOutput

score(dialog: Dialog, **template_kwargs) → float | int

Return the numeric score.

Parameters:
  • dialog (Dialog) – Dialogue to score.

  • template_kwargs (dict) – Extra template kwargs.

Returns:

Score value.

Return type:

Union[int, float]

Raises:

ValueError – If model output malformed.

class sdialog.evaluation.LLMJudgeRealDialog(reason: bool = False, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: LLMJudgeYesNo

LLM judge for classifying a dialogue as real (human) or synthetic (machine-generated), with boolean output and reason. Returns an instance of LLMJudgeYesNoOutput.

Example:

from sdialog.evaluation import LLMJudgeRealDialog

judge_real = LLMJudgeRealDialog(reason=True)

result = judge_real.judge(dialog)

print("Real?", result.positive)
print("Reason:", result.reason)
Parameters:
  • reason (bool) – Whether to request reason.

  • model (Optional[Union[BaseLanguageModel, str]]) – Model instance or name.

  • llm_kwargs (dict) – Additional LLM kwargs.

class sdialog.evaluation.LLMJudgeRealDialogLikertScore(reason: bool = False, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: LLMJudgeScore

LLM judge for evaluating whether a dialogue appears real (human) or synthetic (machine-generated), providing a Likert score between 1 (definitely synthetic) and 5 (definitely real), with optional reason.

Example:

from sdialog.evaluation import LLMJudgeRealDialogLikertScore

judge_real = LLMJudgeRealDialogLikertScore(reason=True)

result = judge_real.judge(dialog)
# score = judge_real(dialog)

print("Likert Score:", result.score)  # score from 1 to 5
print("Reason:", result.reason)
Parameters:
  • reason (bool) – Request reason flag.

  • model (Optional[Union[BaseLanguageModel, str]]) – Model instance or name.

  • llm_kwargs (dict) – Extra LLM kwargs.

class sdialog.evaluation.LLMJudgeRealDialogScore(min_score: int = 0, max_score: int = 10, reason: bool = False, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: LLMJudgeScore

LLM judge for evaluating how “real” (human-like) or “synthetic” a dialogue appears on a configurable numeric range.

Example:

from sdialog.evaluation import LLMJudgeRealDialogScore

judge_real = LLMJudgeRealDialogScore(min_score=0, max_score=10, reason=True)

result = judge_real.judge(dialog)
# score = judge_real(dialog)

print("Score:", result.score)  # score from 0 to 10
print("Reason:", result.reason)
Parameters:
  • min_score (int) – Minimum realism score.

  • max_score (int) – Maximum realism score.

  • reason (bool) – Request reason flag.

  • model (Optional[Union[BaseLanguageModel, str]]) – Model instance or name.

  • llm_kwargs (dict) – Extra LLM kwargs.

class sdialog.evaluation.LLMJudgeRefusal(reason: bool = False, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: LLMJudgeYesNo

LLM judge for evaluating if a dialogue contains a refusal response.

Example:

from sdialog.evaluation import LLMJudgeRefusal

judge_refusal = LLMJudgeRefusal(reason=True)

result = judge_refusal.judge(dialog)

print("Refused?", result.positive)
print("Reason:", result.reason)
Parameters:
  • reason (bool) – Request reason flag.

  • model (Optional[Union[BaseLanguageModel, str]]) – Model instance or name.

  • llm_kwargs (dict) – Extra LLM kwargs.

class sdialog.evaluation.LLMJudgePersonaAttributes(persona: BaseAttributeModel, speaker: str, reason: bool = False, model: langchain_core.language_models.base.BaseLanguageModel | str = None, **llm_kwargs)

Bases: LLMJudgeYesNo

LLM judge for evaluating if a speaker follows the persona attributes in a dialogue.

Example:

from sdialog.personas import Doctor
from sdialog.evaluation import LLMJudgePersonaAttributes

reference_persona = Doctor(name="Dr. Smith", specialty="cardiology")
judge_persona = LLMJudgePersonaAttributes(persona=reference_persona,
                                          speaker="Doctor",
                                          reason=True)
result = judge_persona.judge(dialog)

print("Matches persona?", result.positive)
print("Reason:", result.reason)
Parameters:
  • persona (BasePersona) – Persona definition object.

  • speaker (str) – Target speaker in dialogue.

  • reason (bool) – Request reason flag.

  • model (Optional[Union[BaseLanguageModel, str]]) – Model instance or name.

  • llm_kwargs (dict) – Additional LLM kwargs.

judge(dialogs: Dialog | List[Dialog], reason: bool = None, **template_kwargs) → LLMJudgeYesNoOutput

Judge whether the speaker matches the persona in one or multiple dialogues.

Parameters:
  • dialogs (Union[Dialog, List[Dialog]]) – A dialogue or list of dialogues.

  • reason (Optional[bool]) – Override whether to ask for a reason.

Returns:

Structured yes/no output.

Return type:

LLMJudgeYesNoOutput

class sdialog.evaluation.SentenceTransformerDialogEmbedder(model_name: str = 'sentence-transformers/LaBSE', mean: bool = True, ai_speaker: str = None, name: str = None, verbose: bool = False)

Bases: BaseDialogEmbedder

Dialog embedder using SentenceTransformer. Can embed a dialog as the mean of turn embeddings or as a single embedding of the whole dialog text.

Example:

from sdialog.evaluation import SentenceTransformerDialogEmbedder

dialog_embedder = SentenceTransformerDialogEmbedder(model_name="sentence-transformers/LaBSE")

emb = dialog_embedder(dialog)

print(emb.shape)
Parameters:
  • model_name (str) – SentenceTransformer model name.

  • mean (bool) – If True average per-turn embeddings; else encode concatenated text.

  • ai_speaker (Optional[str]) – If set, restrict embedding to AI/system turns only.

  • name (Optional[str]) – Optional custom embedder name.

  • verbose (bool) – Show progress bars for encoding.

embed(dialog: Dialog, **encode_kwargs) → numpy.ndarray

Generate embedding for a dialog.

Parameters:
  • dialog (Dialog) – Dialog instance.

  • encode_kwargs (dict) – keyword arguments to pass to the encode function of the SentenceTransformer model.

Returns:

Embedding vector.

Return type:

np.ndarray

class sdialog.evaluation.ReferenceCentroidEmbeddingEvaluator(dialog_embedder: BaseDialogEmbedder, reference_dialogues: str | List[Dialog], name: str = None, enable_plotting: bool = True, verbose: bool = False, plot_title: str = None, plot_xlabel: str = None, plot_ylabel: str = None)

Bases: BaseDatasetEmbeddingEvaluator

Evaluator comparing candidate centroid to a reference centroid via cosine similarity.

Example:

from sdialog.evaluation import SentenceTransformerDialogEmbedder
from sdialog.evaluation import ReferenceCentroidEmbeddingEvaluator

dialog_embedder = SentenceTransformerDialogEmbedder()

evaluator = ReferenceCentroidEmbeddingEvaluator(dialog_embedder, reference_dialogs)

# How far are the candidate dialogs from the reference dialogues? (centroid-wise)
print(evaluator(candidate_dialogs))
Parameters:
  • dialog_embedder (BaseDialogEmbedder) – Dialog embedding component.

  • reference_dialogues (Union[str, List[Dialog]]) – List of reference Dialog objects or path.

  • name (Optional[str]) – Optional evaluator name.

  • enable_plotting (bool) – Store embeddings for plotting if True.

  • verbose (bool) – Verbosity flag.

class sdialog.evaluation.KDEDistanceEvaluator(dialog_score: BaseDialogScore, reference_dialogues: str | List[Dialog] = None, metric: str = 'kl', kde_bw: float = None, name: str = None, enable_plotting: bool = True, verbose: bool = False, plot_title: str = None, plot_xlabel: str = None, plot_ylabel: str = None, **evaluator_kwargs)

Bases: BaseDatasetScoreEvaluator

Evaluate distribution divergence between reference and candidate dialog scores using KDE.

Example:

from sdialog.evaluation import KDEDistanceEvaluator, GunningFogScore

# Any dialog score can be used, let's use `GunningFogScore` as an example
kde_eval = KDEDistanceEvaluator(dialog_score=GunningFogScore(),
                                reference_dialogues=reference_dialogs)

print("KL divergence:", kde_eval(candidate_dialogs))
Parameters:
  • dialog_score (BaseDialogScore) – Per-dialog scoring object.

  • reference_dialogues (Optional[Union[str, List[Dialog]]]) – Reference Dialog list or path (optional if score object has attribute).

  • metric (str) – Divergence metric: “kl”, “cs”, or “all”.

  • kde_bw (Optional[float]) – Bandwidth override for KDE.

  • name (Optional[str]) – Evaluator name.

  • enable_plotting (bool) – Keep distributions for plotting.

  • verbose (bool) – Verbosity flag.

  • evaluator_kwargs (dict) – Extra kwargs to parent initializer.

class sdialog.evaluation.FrechetDistanceEvaluator(dialog_score: BaseDialogScore, reference_dialogues: str | List[Dialog] = None, name: str = None, enable_plotting: bool = True, verbose: bool = False, plot_title: str = None, plot_xlabel: str = None, plot_ylabel: str = None, **evaluator_kwargs)

Bases: BaseDatasetScoreEvaluator

Evaluate Frechet distance between Gaussian fits of reference and candidate score distributions.

Example:

from sdialog.evaluation import FrechetDistanceEvaluator, ConversationalFeatures

# Any dialog score can be used, let's use `ConversationalFeatures` as an example
turn_length = ConversationalFeatures(feature="mean-turn-length")
fd_eval = FrechetDistanceEvaluator(dialog_score=turn_length,
                                   reference_dialogues=reference_dialogs)

print("Frechet distance:", fd_eval(candidate_dialogs))
Parameters:
  • dialog_score (BaseDialogScore) – Per-dialog scoring object.

  • reference_dialogues (Optional[Union[str, List[Dialog]]]) – List or path of reference dialogues.

  • name (Optional[str]) – Evaluator name.

  • enable_plotting (bool) – Retained for API parity (not used directly here).

  • verbose (bool) – Verbosity flag.

  • evaluator_kwargs (dict) – Extra parent kwargs.

class sdialog.evaluation.FrechetBERTDistanceEvaluator(reference_dialogues: str | List[Dialog], ai_speaker: str = None, name: str = None, model_name: str = 'roberta-base', batch_size: int = 128, device: str = None, enable_plotting: bool = False, verbose: bool = False)

Bases: BaseDatasetEvaluator

Frechet distance evaluator based on BERT sentence-pair embeddings. See: https://aclanthology.org/2021.findings-acl.193/

Example:

from sdialog.evaluation import FrechetBERTDistanceEvaluator

fb_distance = FrechetBERTDistanceEvaluator(reference_dialogs)

print(fb_distance(candidate_dialogs))
Parameters:
  • reference_dialogues (Union[str, List[Dialog]]) – Reference dialogues (list or path).

  • ai_speaker (Optional[str]) – If set, restrict to AI response pairs.

  • name (Optional[str]) – Evaluator name.

  • model_name (str) – Underlying transformer model.

  • batch_size (int) – Batch size for encoding.

  • device (Optional[str]) – Torch device override.

  • enable_plotting (bool) – Store embeddings for later plotting.

  • verbose (bool) – Verbosity flag.

__call__(dialogues: str | List[Dialog], dataset_name: str = 'candidate') → float

Compute Frechet distance between reference embedding distribution and candidate.

Parameters:
  • dialogues (Union[str, List[Dialog]]) – Candidate dialogues (list or path).

  • dataset_name (str) – Label for candidate dataset.

Returns:

Frechet distance (>= 0).

Return type:

float

plot(show: bool = True, save_path: str = None)

Plot t-SNE projection of sentence-pair embeddings for reference and candidates.

Parameters:
  • show (bool) – Display the figure.

  • save_path (Optional[str]) – Path to save figure (if provided).

Returns:

None

Return type:

None

class sdialog.evaluation.PrecisionRecallDistanceEvaluator(reference_dialogues: str | List[Dialog], ai_speaker: str = None, num_clusters=20, num_angles=1001, num_runs=10, name: str = None, model_name: str = 'roberta-base', batch_size: int = 128, device: str = None, verbose: bool = False)

Bases: BaseDatasetEvaluator

Precision-Recall distance evaluator based on BERT embeddings. See: https://aclanthology.org/2021.findings-acl.193/

Example:

from sdialog.evaluation import PrecisionRecallDistanceEvaluator

pr_distance = PrecisionRecallDistanceEvaluator(reference_dialogs)

print(pr_distance(candidate_dialogs))
Parameters:
  • reference_dialogues (Union[str, List[Dialog]]) – Reference dialogues (list or path).

  • ai_speaker (Optional[str]) – If set, restrict to AI response pairs.

  • num_clusters (int) – Number of k-means clusters.

  • num_angles (int) – Angular resolution for PRD curve.

  • num_runs (int) – Repetition count when distributions unbalanced.

  • name (Optional[str]) – Evaluator name.

  • model_name (str) – Underlying transformer model.

  • batch_size (int) – Batch size for embedding.

  • device (Optional[str]) – Torch device override.

  • verbose (bool) – Verbosity flag.

__call__(dialogues: str | List[Dialog], dataset_name: str = None) → dict | float

Compute maximum F1 score along PRD curve (averaged if size mismatch).

Parameters:
  • dialogues (Union[str, List[Dialog]]) – Candidate dialogues (list or path).

  • dataset_name (Optional[str]) – Label for candidate dataset.

Returns:

Max F1 value.

Return type:

float

class sdialog.evaluation.StatsEvaluator(dialog_score: BaseDialogScore, stat: Literal['mean', 'std', 'min', 'max', 'median'] | None = None, metric: Literal['mean', 'std', 'min', 'max', 'median'] | None = None, name: str = None, enable_plotting: bool = True, verbose: bool = False, plot_title: str = None, plot_xlabel: str = None, plot_ylabel: str = None)

Bases: BaseDatasetScoreEvaluator

Statistics evaluator (mean/std/min/max/median).

Example:

from sdialog.evaluation import StatsEvaluator, LexicalDiversityScore

# Any dialog score can be used, let's use `LexicalDiversityScore` as an example
lexical_diversity = LexicalDiversityScore()
stats_eval = StatsEvaluator(lexical_diversity)
mean_eval = StatsEvaluator(lexical_diversity, stat="mean")

stats = stats_eval(candidate_dialogs)
mean = mean_eval(candidate_dialogs)

# Print descriptive statistics for hesitation rate
print(stats)  # {'mean': ..., 'std': ..., ...}
print("Mean hesitation rate:", mean)  # Mean hesitation rate: ...
Parameters:
  • dialog_score (BaseDialogScore) – Dialog scoring component.

  • stat (Optional[Literal["mean", "std", "min", "max", "median"]]) – Target statistic to return (one of ‘mean’, ‘std’, ‘min’, ‘max’, ‘median’). If None, return all.

  • metric (Optional[Literal["mean", "std", "min", "max", "median"]]) – Deprecated alias for stat.

  • name (Optional[str]) – Evaluator name.

  • enable_plotting (bool) – Keep per-dataset scores for plotting.

  • verbose (bool) – Verbosity flag.

class sdialog.evaluation.MeanEvaluator(dialog_score: BaseDialogScore, name: str = None, enable_plotting: bool = True, verbose: bool = False, plot_title: str = None, plot_xlabel: str = None, plot_ylabel: str = None)

Bases: StatsEvaluator

Evaluator for computing the mean of dialog scores. This class is a thin wrapper around StatsEvaluator with stat=”mean”.

Example:

from sdialog.evaluation import MeanEvaluator, ReadabilityScore

flesch_score = ReadabilityScore(feature="flesch-reading-ease")

mean_eval = MeanEvaluator(flesch_score)

print("Average Flesch reading ease:", mean_eval(candidate_dialogs))
Parameters:
  • dialog_score (BaseDialogScore) – Dialog scoring component.

  • name (Optional[str]) – Evaluator name.

  • enable_plotting (bool) – Keep scores for plotting.

  • verbose (bool) – Verbosity flag.

class sdialog.evaluation.FrequencyEvaluator(dialog_score: BaseDialogScore, name: str = None, enable_plotting: bool = True, verbose: bool = False, plot_title: str = None, plot_xlabel: str = None, plot_ylabel: str = None)

Bases: BaseDatasetScoreEvaluator

Evaluator for computing the frequency or percentage of dialogues scored as 1 / True (e.g., refusal responses).

Example:

from sdialog.evaluation import FrequencyEvaluator, LLMJudgeRealDialog

judge_real = LLMJudgeRealDialog()

freq = FrequencyEvaluator(judge_real)

print(freq(dialogs))  # Outputs proportion of dialogues judged as real
Parameters:
  • dialog_score (BaseDialogScore) – Dialog scoring component producing binary outputs.

  • name (Optional[str]) – Evaluator name.

  • enable_plotting (bool) – Retained for API parity (not used directly).

  • verbose (bool) – Verbosity flag.

class sdialog.evaluation.DatasetComparator(evaluators: BaseDatasetEvaluator | List[BaseDatasetEvaluator])

Bases: object

Run multiple evaluators over several dialog datasets and collect results.

Example:

from sdialog.evaluation import LLMJudgeRealDialog, DialogFlowPPL
from sdialog.evaluation import FrequencyEvaluator, MeanEvaluator
from sdialog.evaluation import DatasetComparator

# Dialog scores
judge_real = LLMJudgeRealDialog()
flow_score = DialogFlowScore(reference_dialogs)

# Comparator with two evaluators
comparator = DatasetComparator(evaluators=[FrequencyEvaluator(judge_real),
                                           MeanEvaluator(flow_score)])

comparator({"modelA": modelA_dialogs,  # print table by default
            "modelB": modelB_dialogs})
# results = comparator({"modelA": modelA_dialogs,
#                       "modelB": modelB_dialogs},
#                      output="dict")  # return results as dict

comparator.plot()  # plot results for each evaluator that support it
Parameters:

evaluators (Union[BaseDatasetEvaluator, List[BaseDatasetEvaluator]]) – Single evaluator instance or list of evaluator instances.

__call__(candidates: str | List[Dialog] | List[str] | List[List[Dialog]] | Dict[str, str] | Dict[str, List[Dialog]], digits: int = 2, output: str | type = 'markdown') → dict

Evaluate multiple candidate datasets with all evaluators.

Parameters:
  • candidates (Union[str, List[Dialog], List[str], List[List[Dialog]], Dict[str, str], Dict[str, List[Dialog]]]) – Collection of datasets (lists/paths/dicts of Dialog objects).

  • digits (int) – Decimal precision for tabular output.

  • output (Union[str, type]) – Output format: ‘dict’, ‘markdown’, or ‘table’.

Returns:

Results mapping (dataset -> metric -> value) if output=’dict’; otherwise prints a table.

Return type:

Optional[dict]

Raises:

ValueError – If candidates empty or output format unsupported.

plot(show: bool = True, save_folder_path: str = None)

Call plot() on each evaluator that supports it.

Parameters:
  • show (bool) – Whether to display plots.

  • save_folder_path (Optional[str]) – Directory to save plots (one file per evaluator).

Returns:

None

Return type:

None

sdialog.evaluation.Comparator

alias of DatasetComparator

sdialog.evaluation.base

Base and abstract evaluation components.

Provides abstract interfaces and utilities to:

  • Embed a dialog (BaseDialogEmbedder)

  • Score a single dialog (BaseDialogScore / BaseDialogFlowScore)

  • Aggregate dialog scores across datasets (BaseDatasetScoreEvaluator)

  • Aggregate dialog embeddings-based scores across datasets (BaseDatasetEmbeddingEvaluator)

  • Judge dialogs with an LLM (BaseLLMJudge)

These abstractions standardize evaluation pipelines for synthetic dialog generation.

class sdialog.evaluation.base.LLMJudgeYesNoOutput(*, reason: str | List[str] | None = None, positive: bool | List[bool])

Bases: BaseModel

Structured output used by yes/no LLM judgments.

Parameters:
  • positive (Union[bool, List[bool]]) – Boolean (or list of booleans) indicating classification outcome(s).

  • reason (Optional[Union[str, List[str]]]) – Optional explanatory reason (string or list).

reason: str | List[str] | None
positive: bool | List[bool]
class sdialog.evaluation.base.LLMJudgeScoreOutput(*, reason: str | List[str] | None = None, score: int | float | List[float | int] = None)

Bases: BaseModel

Structured output used by numeric score LLM judgments.

Parameters:
  • score (Union[int, float, List[Union[int, float]]]) – Numeric score (int or float), or list of scores (one per dialogue).

  • reason (Optional[Union[str, List[str]]]) – Optional explanatory reason (string or list).

reason: str | List[str] | None
score: int | float | List[float | int]
class sdialog.evaluation.base.BaseDialogEmbedder(name: str | None = None)

Bases: ABC

Base class for dialog embedding models.

Subclasses must implement the abstract method: embed(dialog: Dialog) -> np.ndarray

Example:

from sdialog.evaluation.base import BaseDialogEmbedder
import numpy as np

# Custom embedder to embed dialogues as random N-d embeddings
class RndEmbedder(BaseDialogEmbedder):
    def __init__(self, n=256):
        self.n = n

    def embed(self, dialog):
        return np.random.rand(self.n)

# Create a new embedder for 128-d embeddings and embed some dialogues
rnd_embedder = RndEmbedder(n=128)
for d in dialogues:
    emb = rnd_embedder(d)
    print(emb.shape)  # (128,)
Parameters:

name (Optional[str]) – Optional name identifier for the embedder.

__call__(dialog: Dialog, **encode_kwargs) → numpy.ndarray

Embed a dialog into a vector representation (delegates to embed()).

Parameters:
  • dialog (Dialog) – The dialog instance to embed.

  • encode_kwargs (dict) – Additional keyword arguments for the embedding process.

Returns:

Vector representation of the dialog.

Return type:

np.ndarray

abstractmethod embed(dialog: Dialog, **encode_kwargs) → numpy.ndarray

Produce an embedding vector for the given dialog.

Parameters:
  • dialog (Dialog) – The dialog instance to embed.

  • encode_kwargs (dict) – Additional keyword arguments for the embedding process.

Returns:

Embedding vector.

Return type:

np.ndarray

Raises:

NotImplementedError – If not implemented in subclass.

class sdialog.evaluation.base.BaseDialogScore(name: str | None = None, ai_speaker: str = None)

Bases: ABC

Base class for computing a scalar score for a single dialog.

Subclasses must implement the abstract method: score(dialog: Dialog) -> float

Example:

from sdialog.evaluation.base import BaseDialogScore
from sdialog import Dialog, Turn

# Custom score class to count the number of turns in a dialogue
class TurnCountScore(BaseDialogScore):
    def score(self, dialog):
        return len(dialog.turns)

# Create a new instance of our score
turn_counter = TurnCountScore()

d = Dialog(turns=[Turn(speaker="u", text="Hi"),
                  Turn(speaker="s", text="Hello")])

print(turn_counter(d))  # Outputs: 2
Parameters:
  • name (Optional[str]) – Name of the score (used in reporting).

  • ai_speaker (Optional[str]) – If provided, restrict scoring to turns spoken by this AI speaker (case-insensitive).

__call__(dialog: Dialog, **kwargs)

Compute the score for a given dialog (delegates to score()).

Parameters:
  • dialog (Dialog) – The dialog to score.

  • kwargs (dict) – Additional keyword arguments for scoring.

Returns:

Scalar score value.

Return type:

float

abstractmethod score(dialog: Dialog) → float

Compute the score for the provided dialog.

Parameters:

dialog (Dialog) – The dialog to score.

Returns:

Scalar score value.

Return type:

float

Raises:

NotImplementedError – If not implemented in subclass.

class sdialog.evaluation.base.BaseDialogFlowScore(reference_dialogues: str | List[Dialog], ai_speaker: str = None, k_neighbors: int = 64, use_softmax: bool = True, use_only_ai_speaker: bool = False, use_closest_as_centroid_emb: bool = False, graph=None, nodes=None, name: str = None, verbose: bool = False, **d2f_kwargs)

Bases: BaseDialogScore

Base class for flow-based dialog scores using a reference dialog graph.

Builds (or reuses) a flow graph from reference dialogs, encodes turns, retrieves nearest nodes, and derives transition probabilities. Serves as the foundation for perplexity / likelihood style scores (e.g., DialogFlowPPL, DialogFlowScore).

This is an abstract class (extends BaseDialogScore) and cannot be instantiated directly. Subclasses must implement the abstract method: score(dialog: Dialog) -> float

Parameters:
  • reference_dialogues – List of Dialog objects or path to a serialized dialog file.

  • ai_speaker – If provided, only system/AI speaker turns are considered in scoring.

  • k_neighbors – Number of neighbors for softmax aggregation.

  • use_softmax – If True, weight neighbor probabilities via softmax, else pick top-1.

  • use_only_ai_speaker – If True, only AI turns are used to build the graph and compute the scores.

  • use_closest_as_centroid_emb – If True, use closest utterance embeddings as cluster centroids.

  • graph – Optional precomputed graph object to reuse (bypasses construction).

  • nodes – Optional precomputed node metadata dictionary.

  • name – Optional score name override (auto if None).

  • verbose – Verbosity flag forwarded to graph construction.

  • d2f_kwargs – Additional dialog2graph customization parameters.

Raises:

ValueError – If reference_dialogues is invalid.

get_node_sequence(dialog: Dialog, probs: bool = False) → List[str]

Map each turn to its nearest node and optionally return transition probabilities.

Parameters:
  • dialog (Dialog) – Dialog to map.

  • probs (bool) – If True, also return per-transition probability estimates.

Returns:

List of node IDs or (node_sequence, probability_sequence) if probs=True.

Return type:

Union[List[str], Tuple[List[str], List[Optional[float]]]]

Raises:

ValueError – If a dialog speaker is not found in graph metadata.

compute_dialog_log_likelihood(dialog: Dialog) → Tuple[float, int]

Compute cumulative log-probability statistics for a dialog using Laplace smoothing.

Laplace smoothing approach (add-one smoothing): - For each transition: P_laplace(dest|src) = (count(src→dest) + 1) / (sum_outbound_counts + V) - Known edges: Use edge frequency count + 1 - Unknown edges: Use count of 1 (equivalent to adding a pseudo-count) - Both are normalized by (total_outbound_count + V) where V is vocabulary size

This provides a principled probability distribution that: 1. Smooths all transitions (known and unknown) consistently 2. Avoids zero probabilities for unseen transitions 3. Doesn’t modify the graph structure (scoring-time smoothing)

Returns four values:

sum_log_p_known: Sum of log probabilities only over known edges. n_turns_known: Count of contributing turns with known edges (includes initial offset). sum_log_p: Sum over all considered turns (with Laplace smoothing). n_turns: Total counted turns (includes initial offset; respects ai_speaker filtering).

Parameters:

dialog (Dialog) – Dialog to evaluate.

Returns:

Tuple (sum_log_p_known, n_turns_known, sum_log_p, n_turns).

Return type:

Tuple[float, int, float, int]

Raises:

ValueError – If a speaker is missing from metadata.

abstractmethod score(dialog: Dialog) → float

Compute a flow-based perplexity / likelihood derived score for the dialog.

Parameters:

dialog (Dialog) – Dialog to score.

Returns:

Scalar score value.

Return type:

float

Raises:

NotImplementedError – If not implemented in subclass.

class sdialog.evaluation.base.BaseDatasetEvaluator

Bases: ABC

Base class for dataset evaluators.

Dataset evaluators take a set of dialogs and return an evaluation. Typically, Dataset evaluator subclasses will take a dialogue score (BaseDialogScore object) when created and will return an aggregate of the per-dialog scores.

Subclasses must implement the abstract method: __call__(dialogues, dataset_name: Optional[str] = None, **kwargs) -> Union[dict, float]

Example:

from sdialog.evaluation.base import BaseDatasetEvaluator
from sdialog import Dialog, Turn

class CountDialogsEvaluator(BaseDatasetEvaluator):
    def __call__(self, dialogues, dataset_name=None):
        return len(dialogues)

dialog_counter = CountDialogsEvaluator()

dialogs = [Dialog(turns=[Turn(speaker="u", text="Hi")]) for _ in range(3)]

print(dialog_counter(dialogs))  # Outputs: 3
abstractmethod __call__(dialogues: str | List[Dialog], dataset_name: str = None, **kwargs) → dict | float

Evaluate a collection of dialogues.

Parameters:
  • dialogues (Union[str, List[Dialog]]) – List of Dialog objects or a path to a serialized file.

  • dataset_name (Optional[str]) – Optional label for the dataset.

  • kwargs (dict) – Additional evaluator-specific parameters.

Returns:

Evaluation results (scalar or dict).

Return type:

Union[float, dict]

Raises:

NotImplementedError – If not implemented in subclass.

class sdialog.evaluation.base.BaseDatasetScoreEvaluator(dialog_score: BaseDialogScore, name: str = None, enable_plotting: bool = True, verbose: bool = False, plot_title: str = None, plot_xlabel: str = None, plot_ylabel: str = None)

Bases: BaseDatasetEvaluator

Base class for dataset-level aggregation of per-dialog scores.

Dataset score evaluators take a dialog score (BaseDialogScore object) when created and given a collection of dialogs, aggregate their individual scores to return a single value for the collection.

Subclasses must implement the abstract methods:

  • __eval__(dialog_scores: List[Union[float, int]]) -> Union[dict, float]

  • (Optional) __plot__(dialog_scores: Dict[str, np.ndarray], plot: Optional[plt.Axes] = None) -> None

Example:

import numpy as np
from sdialog.evaluation import QuestionRateScore
from sdialog.evaluation.base import BaseDatasetScoreEvaluator

# Let's create our average score evaluator
# We need to implement only the __eval__ method (and optionally the __plot__ method)
# In practice, don't use this example class for average, but better use the built-in `MeanEvaluator`!
class AverageEvaluator(BaseDatasetScoreEvaluator):
    def __plot__(self, dialog_scores, plot=None): pass  # no-op

    def __eval__(self, dialog_scores):
        return np.mean(dialog_scores)

avg_evaluator = AverageEvaluator(
    dialog_score=QuestionRateScore(speaker="System")
)
print(avg_evaluator(dialogs))  # Outputs average system's question rate across dialogues
Parameters:
  • dialog_score (BaseDialogScore) – Dialog-level scoring component.

  • name (Optional[str]) – Optional evaluator name (auto-derived if None).

  • enable_plotting (bool) – Whether to keep per-dataset scores for plotting.

  • verbose (bool) – Whether to keep tqdm bars visible.

__call__(dialogues: str | List[Dialog], dataset_name: str = None, return_scores: bool = False) → dict | float

Compute per-dialog scores then aggregate.

Parameters:
  • dialogues (Union[str, List[Dialog]]) – Iterable of Dialog objects or path.

  • dataset_name (Optional[str]) – Label for the dataset (default ‘candidate’).

  • return_scores (bool) – If True also return raw score array(s).

Returns:

Aggregated results or (results, raw_scores) if return_scores=True.

Return type:

Union[dict, float, Tuple[Union[dict, float], np.ndarray]]

Raises:

KeyboardInterrupt – If user interrupts (partial results saved).

clear()

Clear stored per-dataset raw scores history.

plot(show: bool = True, save_path: str = None, **kwargs)

Generate plots for stored dataset scores.

Parameters:
  • show (bool) – Whether to display the plot(s).

  • save_path (Optional[str]) – If provided, save figure(s) to this path (metric name appended when multi-metric).

  • kwargs (dict) – Additional keyword arguments for plotting.

Returns:

None

Return type:

None

class sdialog.evaluation.base.BaseDatasetEmbeddingEvaluator(dialog_embedder: BaseDialogEmbedder, name: str = None, enable_plotting: bool = True, verbose: bool = False, plot_title: str = None, plot_xlabel: str = None, plot_ylabel: str = None)

Bases: BaseDatasetEvaluator

Base class for dataset-level evaluation using dialog embeddings.

It takes a dialog embedder (BaseDialogEmbedder object) when created and given a collection of dialogs, computes their embeddings and returns a single value for the collection.

Subclasses must implement: __eval__(dialog_embs: List[np.ndarray]) -> Union[dict, float]`

and __plot__(dialog_embs: Dict[str, np.ndarray], tsne_model: TSNE, plot: Optional[plt.Axes]) -> None

Example:

from sdialog import SentenceTransformerDialogEmbedder
from sdialog.evaluation.base import BaseDatasetEmbeddingEvaluator

# Evaluator that computes the average centroid cosine distance to a reference centroid
# We need to implement only the __eval__ method (and optionally the __plot__ method)
# (in practice, use the built-in ReferenceCentroidEmbeddingEvaluator!)
class ReferenceCentroidEmbeddingEvaluator(BaseDatasetEmbeddingEvaluator):
    def __plot__(self, dialog_embs): pass  # no-op

    def __init__(self, dialog_embedder, reference_dialogs):
        self.reference_centroid = np.mean(
            [dialog_embedder(dialog) for dialog in reference_dialogs], axis=0
        )

    def __eval__(self, dialog_embs):
        centroid = np.mean(dialog_embs, axis=0)
        return cosine(centroid, self.reference_centroid)

dialog_embedder = SentenceTransformerDialogEmbedder(model_name="sentence-transformers/LaBSE")
centroid_evaluator = ReferenceCentroidEmbeddingEvaluator(dialog_embedder=dialog_embedder,
                                                         reference_dialogs=reference_dialogs)

print(centroid_evaluator(dialogs))  # distance between candidate and reference dialogues
                                    # (cosine distance between their centroids)
Parameters:
  • dialog_embedder (BaseDialogEmbedder) – Dialog embedding component.

  • name (Optional[str]) – Optional evaluator name (auto-derived if None).

  • enable_plotting (bool) – Whether to store embeddings for plotting.

  • verbose (bool) – Verbosity flag for progress bars.

__call__(dialogues: str | List[Dialog], dataset_name: str = None, return_embs: bool = False) → dict | float

Embed dialogs and aggregate their embeddings to a single score.

Parameters:
  • dialogues (Union[str, List[Dialog]]) – Iterable of Dialogs or path.

  • dataset_name (Optional[str]) – Dataset label (default ‘candidate’).

  • return_embs (bool) – If True return (results, embeddings_array).

Returns:

Aggregated evaluation or (results, embeddings) if return_embs.

Return type:

Union[dict, float, Tuple[Union[dict, float], np.ndarray]]

clear()

Clear stored per-dataset embeddings.

plot(show: bool = True, save_path: str = None)

Plot embeddings (e.g., via subclass t-SNE projection) for stored datasets.

Parameters:
  • show (bool) – Whether to display the plot.

  • save_path (Optional[str]) – If provided, save plot to this path.

Returns:

None

Return type:

None

class sdialog.evaluation.base.BaseLLMJudge(model: langchain_core.language_models.base.BaseLanguageModel | str = None, prompt_template: str = '', output_format: dict | BaseModel = None, **llm_kwargs)

Bases: ABC

Base class for all LLM-based evaluation judges that render a prompt and return an output. This is the base class of built-in base judges like LLMJudgeYesNo or LLMJudgeScore.

Subclasses must implement the abstract method: judge(dialogs: Union[Dialog, List[Dialog]]) -> dict

Example:

from sdialog.evaluation.base import BaseLLMJudge
from sdialog import Dialog, Turn

class MagicJudge(BaseLLMJudge):
    def judge(self, dialog):
        # Render prompt (dialog -> text)
        prompt = self.prompt_template.render(dialog=dialog)
        raw = self(prompt)  # call underlying LLM
        return raw  # normally you'd parse into structured output

magic_judge = MagicJudge(prompt_template="How magical is the following dialogue? Dialogue:\n{{ dialog }}")
print(magic_judge.judge(dialog))  # Outputs raw LLM response
Parameters:
  • model (Union[BaseLanguageModel, str]) – Model instance or model name (falls back to config if None).

  • prompt_template (str) – Jinja2 template string used to build the human prompt.

  • output_format (Union[dict, BaseModel]) – Optional Pydantic schema or JSON schema dict for structured output.

  • llm_kwargs (dict) – Additional model instantiation parameters overriding config.

__call__(prompt: str) → dict | BaseModel

Invoke the underlying LLM with the given rendered prompt.

Parameters:

prompt (str) – Fully rendered human prompt content.

Returns:

Raw model response or structured output (depending on output_format).

Return type:

Union[dict, BaseModel]

abstractmethod judge(dialogs: Dialog | List[Dialog]) → dict

Judge one or many dialogs using the LLM.

Parameters:

dialogs (Union[Dialog, List[Dialog]]) – A single Dialog or list of Dialog objects.

Returns:

Dictionary of judged metrics / fields extracted.

Return type:

dict

Raises:

NotImplementedError – If not implemented in subclass.

prompt(system: bool = False) → str

Return the current system or human prompt text.

Parameters:

system (bool) – If True return system prompt; else return last human prompt.

Returns:

Prompt text.

Return type:

str


sdialog.datasets

This module provides utilities for loading, parsing, and describing dialogue datasets, including the STAR dataset. It supports extracting scenarios, flowcharts, personas, and constructing dataset-specific Agent objects for simulation.

class sdialog.datasets.STAR

Bases: object

Utility class for interacting with the STAR dialogue dataset.

Provides methods for loading dialogues, extracting scenarios, flowcharts, responses, and constructing Agent objects for simulation and evaluation.

static set_path(path)

Sets the root path for the STAR dataset.

Parameters:

path (str) – Path to the STAR dataset root directory.

Returns:

None

Return type:

None

static read_graph(task_name, as_dot: bool = True)

Read the action graph for a given task.

Parameters:
  • task_name (Union[str, dict]) – Name of the task (folder name under tasks/), or a pre-loaded JSON dict (as returned by the task’s JSON file) to skip disk I/O.

  • as_dot (bool) – If True, return a DOT string; else return the raw graph dict.

Returns:

Graph in DOT format or raw dictionary mapping edges.

Return type:

Union[str, dict]

static read_graph_responses(task_name, as_dict: bool = False)

Read example responses associated with each node/action in a task graph.

Placeholders of the form {variable[:format]} are uppercased for visibility.

Parameters:
  • task_name (Union[str, dict]) – Name of the task, or a pre-loaded responses dict to skip disk I/O.

  • as_dict (bool) – If True, return a dict; otherwise a JSON-formatted string.

Returns:

Mapping node -> example response, or JSON dump.

Return type:

Union[dict, str]

static get_task_names()

List all available task names (directory names under tasks/).

Returns:

List of task names.

Return type:

List[str]

static get_dialog(id)

Load a dialogue by numeric ID.

Parameters:

id (int) – Dialogue ID (filename without extension).

Returns:

Dialog object with turns and events populated.

Return type:

Dialog

static get_dialogs(domain: str = None, task_name: str = None, happy: bool = None, multitask: bool = None)

Load all dialogues matching optional filter criteria.

Parameters:
  • domain (Optional[str]) – Domain filter (must appear in Scenario[‘Domains’]).

  • task_name (Optional[str]) – Task name filter (must appear in WizardCapabilities).

  • happy (Optional[bool]) – Filter by ‘happy path’ flag.

  • multitask (Optional[bool]) – Filter by multitask flag.

Returns:

List of Dialog objects matching filters.

Return type:

List[Dialog]

static get_dialog_scenario(id)

Load scenario metadata for a given dialogue.

Parameters:

id (int) – Dialogue ID.

Returns:

Scenario dictionary.

Return type:

dict

static get_dialog_first_turn(id, speaker: str = None)

Get the first turn for a given dialogue (optionally constrained to a speaker).

Parameters:
  • id (int) – Dialogue ID.

  • speaker (Optional[str]) – Speaker name filter (e.g., ‘User’ or ‘Wizard’); if None, first participant turn is returned.

Returns:

First matching turn or None if not found.

Return type:

Optional[Turn]

static get_dialog_task_names(id)

Get all task names (WizardCapabilities -> Task) for a dialogue.

Parameters:

id (int) – Dialogue ID.

Returns:

List of task names.

Return type:

List[str]

static get_dialog_responses(id)

Get example response dictionaries for each task in a dialogue.

Parameters:

id (int) – Dialogue ID.

Returns:

List of response dicts (one per task).

Return type:

List[dict]

static get_dialog_graphs(id)

Get raw action graphs (dict form) for all tasks in a dialogue.

Parameters:

id (int) – Dialogue ID.

Returns:

List of graph dicts.

Return type:

List[dict]

static get_dialog_events(id)

Get all events for a dialogue.

Parameters:

id (int) – Dialogue ID.

Returns:

List of event dictionaries from the JSON file.

Return type:

List[dict]

static get_dialog_user_instructions(id)

Get user guide instructions mapped to the (user) turn index where each applies.

Parameters:

id (int) – Dialogue ID.

Returns:

Mapping user_turn_index -> instruction text.

Return type:

Dict[int, str]

static get_dialog_graphs_and_responses(id)

Convenience loader returning both graphs and responses for all tasks.

Parameters:

id (int) – Dialogue ID.

Returns:

Tuple (graphs list, responses list).

Return type:

Tuple[List[dict], List[dict]]

static get_scenario_description(scenario)

Build a natural language description of a scenario including embedded DOT graphs and example responses.

Parameters:

scenario (dict) – Scenario dictionary (as returned by get_dialog_scenario).

Returns:

Multi-section textual description.

Return type:

str

static get_dialog_scenario_description(id)

Retrieve scenario metadata and its natural language description.

Parameters:

id (int) – Dialogue ID.

Returns:

Tuple (scenario dict, description string).

Return type:

Tuple[dict, str]

static get_user_persona_for_scenario(scenario)

Construct a Persona object representing the user under the given scenario.

Parameters:

scenario (dict) – Scenario metadata.

Returns:

User persona object.

Return type:

Persona

static get_flowchart_description_for_scenario(scenario)

Build a markdown-like description with DOT graphs and example responses for each task.

Parameters:

scenario (dict) – Scenario metadata.

Returns:

Combined flowchart description text.

Return type:

str

static get_system_persona_for_scenario(scenario)

Construct a Persona object representing the system/assistant for the scenario.

Parameters:

scenario (dict) – Scenario metadata.

Returns:

System persona object.

Return type:

Persona

static get_agents_for_scenario(scenario, model_name: str = None)

Create (system, user) Agent objects for a scenario (personas only; no orchestration).

Parameters:
  • scenario (dict) – Scenario metadata.

  • model_name (Optional[str]) – Optional model name / identifier for agent LLM configuration.

Returns:

Tuple (system_agent, user_agent).

Return type:

Tuple[Agent, Agent]

static get_agents_from_dialogue(id, model_name: str = None, set_first_utterance: bool = False)

Create (system, user) Agent objects derived from a dialogue’s scenario.

Optionally set an initial first system utterance (heuristic).

Parameters:
  • id (int) – Dialogue ID.

  • model_name (Optional[str]) – Optional model name / identifier for agent LLM configuration.

  • set_first_utterance (bool) – If True, assign a first system utterance.

Returns:

Tuple (system_agent, user_agent).

Return type:

Tuple[Agent, Agent]

static get_agents_from_dialogue_with_orchestration(id, model_name: str = None, set_first_utterance: bool = False)

Create (system, user) Agent objects with attached orchestrators for responses/instructions.

Parameters:
  • id (int) – Dialogue ID.

  • model_name (Optional[str]) – Optional model name / identifier for agent LLM configuration.

  • set_first_utterance (bool) – If True, assign a first system utterance.

Returns:

Tuple (system_agent_with_orchestrator, user_agent_with_orchestrator).

Return type:

Tuple[Agent, Agent]


sdialog.config

This module loads and processes the configuration for the sdialog package.

sdialog.config.llm(llm_name, **llm_kwargs)

Update the LLM model setting in the config.

Parameters:

llm_name (str) – The name of the LLM model to set.

sdialog.config.llm_params(**params)

Update the LLM hyperparameters in the config.

Parameters:

params (dict) – Dictionary of hyperparameter names and values.

sdialog.config.cache(enable)

Enable or disable caching.

Parameters:

enable (bool) – Whether to enable caching or not.

sdialog.config.cache_path(path)

Set the path for the cache directory.

Parameters:

path (str) – The new path for the cache directory.

sdialog.config.set_cache(path, enable=True)

Set the cache path and enable/disable caching.

Parameters:
  • path (str) – The path to the cache directory.

  • enable (bool) – Whether to enable caching or not.

sdialog.config.clear_cache()

Clear the cache by deleting all files in the cache directory.

sdialog.config.set_persona_dialog_generator_prompt(path)

Set the path for the persona_dialog_generator prompt.

Parameters:

path (str) – The new path for the prompt file.

sdialog.config.set_persona_generator_prompt(path)

Set the path for the persona_generator prompt.

Parameters:

path (str) – The new path for the prompt file.

sdialog.config.set_dialog_generator_prompt(path)

Set the path for the dialog_generator prompt.

Parameters:

path (str) – The new path for the prompt file.

sdialog.config.set_persona_agent_prompt(path)

Set the path for the persona_agent prompt.

Parameters:

path (str) – The new path for the prompt file.


sdialog.util

Utility Functions for sdialog

This module provides helper functions for the sdialog package, including serialization utilities to ensure objects can be safely converted to JSON for storage or transmission.

class sdialog.util.CacheDialogScore

Bases: object

Static class for caching utility for dialog scoring functions keyed by: (score class name, score object JSON-serializable attributes, dialog._path).

Provides static methods to initialize, enable/disable, persist, and clear cache.

static cache(func)

Decorator adding disk-backed caching for dialog scoring functions.

Cache key includes:

  • score object class name

  • JSON-serializable attributes of score object

  • dialog._path (must exist)

Parameters:

func (callable) – Target scoring function (score_obj, dialog, *args, **kwargs).

Returns:

Wrapped function with caching logic.

Return type:

callable

static clear()

Clear in-memory cache and persist empty structure.

Returns:

None

Return type:

None

static get_cache()

Get internal cache dictionary.

Returns:

Current in-memory cache mapping.

Return type:

dict

static get_cache_path() → str

Get absolute path to cache JSON file.

Returns:

Path to cache file.

Return type:

str

Raises:

ValueError – If init() not called first.

static init(path, enable_cache=True)

Initialize cache system (load existing cache file if present).

Parameters:
  • path (str) – Directory path where cache file resides / will reside.

  • enable_cache (bool) – Whether to enable caching immediately.

Returns:

None

Return type:

None

static is_cache_enabled() → bool

Check if caching is enabled.

Returns:

True if enabled.

Return type:

bool

static save()

Persist cache dictionary to JSON file (if enabled).

Returns:

None

Return type:

None

Raises:

ValueError – If not initialized.

static set_cache_path(path: str)

Set cache file path (creates directory if needed).

Parameters:

path (str) – Base directory for cache file.

Returns:

None

Return type:

None

static set_enable_cache(enable: bool)

Enable or disable the cache.

Parameters:

enable (bool) – True to enable caching, False to disable.

Returns:

None

Return type:

None

class sdialog.util.KNNModel(items, k=3)

Bases: object

Thin wrapper around sklearn NearestNeighbors for cosine similarity retrieval.

Parameters:
  • items (Iterable[Tuple[Any, Sequence[float]]]) – Iterable of (item_id, embedding_vector) pairs.

  • k (int) – Default number of neighbors to retrieve.

__call__(target_emb, k=None)

Retrieve k nearest neighbors by cosine distance.

Accepts either a single embedding vector or a list/array of embedding vectors. Maintains backward compatibility: single embeddings return a single result list, batch embeddings return a list of result lists.

Parameters:
  • target_emb (Union[Sequence[float], np.ndarray, List]) – Query embedding vector (1D) or list/array of vectors (2D). If 1D, returns a single result list. If 2D, returns a list of result lists.

  • k (int) – Override number of neighbors (defaults to self.k).

Returns:

If target_emb is 1D: List of (item_id, distance) tuples (backward compatible). If target_emb is 2D: List of lists of (item_id, distance) tuples.

Return type:

Union[List[Tuple[Any, float]], List[List[Tuple[Any, float]]]]

neighbors(target_emb, k=None)

Retrieve k nearest neighbors by cosine distance.

Accepts either a single embedding vector or a list/array of embedding vectors. Maintains backward compatibility: single embeddings return a single result list, batch embeddings return a list of result lists.

Parameters:
  • target_emb (Union[Sequence[float], np.ndarray, List]) – Query embedding vector (1D) or list/array of vectors (2D). If 1D, returns a single result list. If 2D, returns a list of result lists.

  • k (int) – Override number of neighbors (defaults to self.k).

Returns:

If target_emb is 1D: List of (item_id, distance) tuples (backward compatible). If target_emb is 2D: List of lists of (item_id, distance) tuples.

Return type:

Union[List[Tuple[Any, float]], List[List[Tuple[Any, float]]]]

class sdialog.util.SentencePairTransformer(model_name: str = 'roberta-base', device: str = None, verbose: bool = True)

Bases: object

Transformer wrapper producing CLS embeddings for paired sentences (similar to NLI encoding).

Parameters:
  • model_name (str) – Hugging Face model name.

  • device (str) – Explicit device ("cpu" / "cuda:*"); auto-detected if None.

  • verbose (bool) – Enable verbose progress display.

encode(sent1: str | List[str], sent2: str | List[str], batch_size: int = 128, show_progress_bar: bool = True, progress_bar_desc: str = 'Computing embeddings') → numpy.ndarray

Encode aligned sentence pairs into CLS embeddings.

Parameters:
  • sent1 (Union[str, List[str]]) – First sentence or list of first sentences.

  • sent2 (Union[str, List[str]]) – Second sentence or list of second sentences.

  • batch_size (int) – Batch size for encoding.

  • show_progress_bar (bool) – Whether to show progress bar.

  • progress_bar_desc (str) – Description label for progress bar.

Returns:

Array of shape (N, hidden_size) containing CLS embeddings.

Return type:

np.ndarray

sdialog.util.camel_or_snake_to_words(varname: str) → str

Convert camelCase or snake_case identifier into normalized spaced words.

Parameters:

varname (str) – Identifier string.

Returns:

Human-readable spaced words.

Return type:

str

sdialog.util.check_valid_model_name(func)

Decorator ensuring first argument (model_name) is a string; otherwise short-circuits to False.

Parameters:

func (callable) – The predicate function to wrap.

Returns:

Wrapped function enforcing a str model_name.

Return type:

callable

sdialog.util.dialogs_to_utt_pairs(dialogs: List[BaseModel], ai_speaker: str = None) → Tuple[List[str], List[str]]

Extract utterance -> next utterance (adjacent turn) pairs from dialogs.

Two modes:
  • Sliding window mode (ai_speaker is None): pairs every turn with its successor.

  • QA mode (ai_speaker given): pairs each human turn immediately preceding an AI turn (speaker match).

Parameters:
  • dialogs (List[BaseModel]) – List of dialog-like Pydantic objects each having a .turns list with .text and .speaker.

  • ai_speaker (str) – Optional name (case-insensitive) of the AI speaker to filter answer turns.

Returns:

Tuple (utterances, next_utterances) of equal length.

Return type:

Tuple[List[str], List[str]]

Raises:

ValueError – If no turns found, or lengths mismatch, or ai_speaker filtering yields nothing.

sdialog.util.dict_to_table(data: dict, sort_by: str = None, sort_ascending: bool = True, markdown: bool = False, format: str = '.2f', show: bool = True) → str

Render a dict-of-dicts as a table (Markdown or fancy grid).

Parameters:
  • data (dict) – Mapping where each value is itself a mapping of column -> value.

  • sort_by (str) – Column name to sort by.

  • sort_ascending (bool) – Sort ascending if True.

  • markdown (bool) – If True produce GitHub-flavored Markdown table.

  • format (str) – Float formatting specifier passed to pandas.

  • show (bool) – If True print table to stdout.

Returns:

Table as string.

Return type:

str

sdialog.util.get_llm_default_params(model_name: str, llm_params: dict, retry: bool = True) → float

Get the default parameters for the model if not already specified, and merges them into llm_params.

Parameters:
  • model_name (str) – LLM model name.

  • llm_params (dict) – Existing LLM parameter dictionary to update in-place.

Returns:

Updated llm_params with defaults filled.

Return type:

dict

sdialog.util.get_llm_model(model_name: str, output_format: dict | BaseModel = None, return_model_params: bool = False, think: bool = False, tools: List = None, **llm_kwargs)

Instantiate a LangChain chat model (OpenAI, AWS, Google, Ollama, Hugging Face).

Applies backend-specific adjustments (e.g., removing unsupported params). Optionally wraps model for structured output if output_format provided and supported.

Parameters:
  • model_name (Union[str, Any]) – Model name or instance.

  • output_format (Union[dict, BaseModel, type[BaseModel]]) – Pydantic model class or JSON schema dict for structured output.

  • return_model_params (bool) – If True, return (model, llm_kwargs) tuple instead of just model.

  • think (bool) – If True, enables “thinking” segments in responses.

  • tools (List[langchain_core.tools.structured.StructuredTool]) – Optional list of tool functions to enable.

  • llm_kwargs (dict) – Additional backend-specific model kwargs.

Returns:

Configured LangChain model (possibly wrapped for structured output).

Return type:

Any

Raises:

ValueError – If model_name is invalid type.

sdialog.util.get_timestamp() → str

Return current UTC timestamp in ISO 8601 format (seconds precision, trailing ‘Z’).

Returns:

ISO 8601 UTC timestamp.

Return type:

str

sdialog.util.get_universal_id() → str

Generates a unique identifier (UUID4) for sdialog objects.

Returns:

A unique identifier as a string.

Return type:

str

sdialog.util.is_amazon_model_name(model_name, *args, **kwargs)
sdialog.util.is_anthropic_model_name(model_name, *args, **kwargs)
sdialog.util.is_azure_openai_model_name(model_name, *args, **kwargs)
sdialog.util.is_google_genai_model_name(model_name, *args, **kwargs)
sdialog.util.is_huggingface_model_name(model_name, *args, **kwargs)
sdialog.util.is_ollama_model_name(model_name, *args, **kwargs)
sdialog.util.is_openai_model_name(model_name, *args, **kwargs)
sdialog.util.make_serializable(data: dict) → dict

Convert non-JSON-serializable values in a dictionary to strings (in-place mutation).

Parameters:

data (dict) – Dictionary to sanitize.

Returns:

The mutated dictionary with serializable values.

Return type:

dict

Raises:

TypeError – If input is not a dict.

sdialog.util.ollama_check_and_pull_model(model_name: str) → bool

Ensure an Ollama model is available locally (pull if missing).

Parameters:

model_name (str) – Model name (may include ‘ollama:’ prefix).

Returns:

True if available or successfully pulled; False otherwise.

Return type:

bool

sdialog.util.remove_audio_tags(text: str) → str

Remove tags of the form <…>. (Despite the summary mentioning {}, (), [], only angle brackets are removed.)

Parameters:

text (str) – Input text possibly containing markup tags.

Returns:

Text with angle-bracket tags removed.

Return type:

str

sdialog.util.remove_newlines(s: str) → str

Replace all whitespace (including newlines) with single spaces and collapse repeats.

Parameters:

s (Any) – Input value (non-str inputs are returned unchanged).

Returns:

Normalized single-line string or original object if not str.

Return type:

str

sdialog.util.set_generator_seed(generator, seed)

Attempt to set a deterministic seed on the underlying LLM (if supported); fallback to torch.manual_seed.

Also applies a workaround for certain Ollama caching issues by forcing an initial trivial generation.

Parameters:
  • generator (Any) – Object containing .llm and (optionally) .messages or .memory.

  • seed (int) – Desired seed; if None a random 32-bit value is generated.

Returns:

The seed actually used (or None if unsupported).

Return type:

int

sdialog.util.softmax(values, temperature=0.05, as_list=True)

Compute softmax over a 1D iterable of numeric values.

Parameters:
  • values (Iterable[float]) – Sequence of numeric scores.

  • temperature (float) – Temperature divisor (lower = sharper distribution).

  • as_list (bool) – If True return a Python list; otherwise a torch tensor.

Returns:

Softmax probability distribution.

Return type:

Union[List[float], torch.Tensor]

sdialog.util.upper_camel_to_dash(name: str) → str

Convert UpperCamelCase to dash-case (preserving acronym groups).

Parameters:

name (str) – Class or identifier name.

Returns:

dash-case form.

Return type:

str


sdialog.server

OpenAI-compatible RESTful API server for SDialog agents.

This module provides a Server class that serves SDialog agents as OpenAI-compatible chat completion endpoints, enabling integration with OpenAI-compatible clients like Open WebUI.

class sdialog.server.Server

Bases: object

Static server class for serving SDialog agents as OpenAI-compatible API.

This server provides OpenAI-compatible chat completion endpoints that can be used with clients like Open WebUI. The server handles agent memory internally, only processing new messages while maintaining conversation context.

classmethod add_agent(agent: Agent, model_name: str = None) → None

Add an agent to the server without starting it.

Parameters:
  • agent (Agent) – The SDialog agent to add.

  • model_name (str) – Model name to use for the agent.

classmethod list_agents() → List[str]

List all registered agent model names.

Returns:

List of model names.

Return type:

List[str]

classmethod remove_agent(model_name: str) → None

Remove an agent from the server.

Parameters:

model_name (str) – Model name of the agent to remove.

classmethod reset_agent(model_name: str, seed: int | None = None) → None

Reset an agent’s memory and state.

Parameters:
  • model_name (str) – Model name of the agent to reset.

  • seed (Optional[int]) – Optional seed for the reset.

classmethod serve(agents: Agent | List[Agent], host: str = '0.0.0.0', port: int = 1333, stateless: bool = True, debug: bool = False, model_names: str | List[str] | None = None, log_level: str = 'info', max_requests_per_minute: int | None = 30, max_requests_per_hour: int | None = 300, max_workers: int | None = None, chat_ui: bool | ChatUI = False) → None

Serve SDialog agents as an OpenAI-compatible RESTful API.

This method automatically detects the environment and chooses the appropriate server startup method. In standard environments (command line, scripts), it uses uvicorn.run(). In Jupyter notebooks or other environments with existing event loops, it automatically falls back to a threaded server.

Parameters:
  • agents (Union[Agent, List[Agent]]) – The SDialog agent or a list of agents to serve.

  • host (str) – Host address to bind the server to.

  • port (int) – Port number to bind the server to.

  • stateless (bool) – If True, the agent will not maintain memory between requests and the full context must be provided with each request.

  • debug (bool) – If True, tool-call failures are returned to the agent as tool output.

  • model_names (Optional[Union[str, List[str]]]) – Model names to expose in the API (defaults to agent’s name).

  • log_level (str) – Logging level for the server.

  • max_requests_per_minute (Optional[int]) – Per-client (IP address) limit of chat requests per minute, for bursts; extra requests get HTTP 429 “Too Many Requests” (None to disable).

  • max_requests_per_hour (Optional[int]) – Per-client (IP address) limit of chat requests per hour, for sustained use (None to disable).

  • max_workers (Optional[int]) – Maximum number of requests processed at the same time per agent, each on a clone of the agent sharing its model (None: 8). Agents with a local Hugging Face model or inspectors, and stateful agents (a single conversation), serve one request at a time. With several workers, the agent’s tools must be thread-safe.

  • chat_ui (Union[bool, ChatUI]) – If True, also serve a web chat GUI to talk to the agents at /chat (e.g. http://localhost:1333/chat), which can also be embedded in other pages; pass a ChatUI to customize it.

Example:

from sdialog import Persona
from sdialog.agents import Agent
from sdialog.server import Server

# Create two agents
user = Agent(persona=Persona(name="Dr. Nebula", role="Astrobotanist seeking alien spores"),
             name="Scientist")
bot = Agent(persona=Persona(name="StationCore", role="Sarcastic habitat control AI"),
            name="Bot")

# Serve them as an OpenAI-compatible API
Server.serve([user, bot], port=1333)
# Output:
# Starting server for agents on localhost:1333
# > 2 registered agents: Scientist:latest, Bot:latest

# Or also with a web chat GUI on http://localhost:1333/chat
Server.serve([user, bot], port=1333, chat_ui=True)
async classmethod serve_async(agents: Agent | List[Agent], host: str = '0.0.0.0', port: int = 1333, stateless: bool = True, debug: bool = False, model_names: str | List[str] | None = None, log_level: str = 'info', max_requests_per_minute: int | None = 30, max_requests_per_hour: int | None = 300, max_workers: int | None = None, chat_ui: bool | ChatUI = False) → None

Serve SDialog agents as an OpenAI-compatible RESTful API (async version).

This method is designed for use in environments with existing event loops, such as Jupyter notebooks, where uvicorn.run() would fail.

Parameters:
  • agents (Union[Agent, List[Agent]]) – The SDialog agent or a list of agents to serve.

  • host (str) – Host address to bind the server to.

  • port (int) – Port number to bind the server to.

  • stateless (bool) – If True, the agent will not maintain memory between requests and the full context must be provided with each request.

  • debug (bool) – If True, tool-call failures are returned to the agent as tool output.

  • model_names (Optional[Union[str, List[str]]]) – Model names to expose in the API (defaults to agent’s name).

  • log_level (str) – Logging level for the server.

  • max_requests_per_minute (Optional[int]) – Per-client (IP address) limit of chat requests per minute, for bursts; extra requests get HTTP 429 “Too Many Requests” (None to disable).

  • max_requests_per_hour (Optional[int]) – Per-client (IP address) limit of chat requests per hour, for sustained use (None to disable).

  • max_workers (Optional[int]) – Maximum number of requests processed at the same time per agent, each on a clone of the agent sharing its model (None: 8). Agents with a local Hugging Face model or inspectors, and stateful agents (a single conversation), serve one request at a time. With several workers, the agent’s tools must be thread-safe.

  • chat_ui (Union[bool, ChatUI]) – If True, also serve a web chat GUI to talk to the agents at /chat (e.g. http://localhost:1333/chat), which can also be embedded in other pages; pass a ChatUI to customize it.

classmethod serve_in_thread(agents: Agent | List[Agent], host: str = '0.0.0.0', port: int = 1333, stateless: bool = True, debug: bool = False, model_names: str | List[str] | None = None, log_level: str = 'info', max_requests_per_minute: int | None = 30, max_requests_per_hour: int | None = 300, max_workers: int | None = None, chat_ui: bool | ChatUI = False) → None

Serve SDialog agents in a separate thread (alternative for Jupyter).

This method runs the server in a separate thread, allowing it to coexist with Jupyter’s event loop without conflicts. It’s automatically used as a fallback by the main serve() method when an event loop conflict is detected.

Parameters:
  • agents (Union[Agent, List[Agent]]) – The SDialog agent or a list of agents to serve.

  • host (str) – Host address to bind the server to.

  • port (int) – Port number to bind the server to.

  • stateless (bool) – If True, the agent will not maintain memory between requests and the full context must be provided with each request.

  • debug (bool) – If True, tool-call failures are returned to the agent as tool output.

  • model_names (Optional[Union[str, List[str]]]) – Model names to expose in the API (defaults to agent’s name).

  • log_level (str) – Logging level for the server.

  • max_requests_per_minute (Optional[int]) – Per-client (IP address) limit of chat requests per minute, for bursts; extra requests get HTTP 429 “Too Many Requests” (None to disable).

  • max_requests_per_hour (Optional[int]) – Per-client (IP address) limit of chat requests per hour, for sustained use (None to disable).

  • max_workers (Optional[int]) – Maximum number of requests processed at the same time per agent, each on a clone of the agent sharing its model (None: 8). Agents with a local Hugging Face model or inspectors, and stateful agents (a single conversation), serve one request at a time. With several workers, the agent’s tools must be thread-safe.

  • chat_ui (Union[bool, ChatUI]) – If True, also serve a web chat GUI to talk to the agents at /chat (e.g. http://localhost:1333/chat), which can also be embedded in other pages; pass a ChatUI to customize it.

Returns:

The thread object running the server.

Return type:

threading.Thread

classmethod serve_whatsapp(agent: Agent, port: int = 1234, host: str = '0.0.0.0', phone_number_id: str | None = None, access_token: str | None = None, verify_token: str | None = None, app_secret: str | None = None, db_path: str = 'whatsapp_sessions.db', webhook_path: str = '/webhook', session_timeout: int | str | None = 'auto', session_retention_days: int | None = 30, tunnel: bool = False, auto_setup: bool = False, max_messages_per_minute: int | None = 6, max_messages_per_hour: int | None = 60, log_level: str = 'info', max_workers: int | None = None, max_message_age: int | None = 120, on_event: Callable[[str, Event], None] | None = None) → None

Serve an SDialog agent via Meta WhatsApp Cloud API webhook.

Parameters:
  • agent (Agent) – The SDialog agent to serve.

  • port (int) – Port number to listen on.

  • host (str) – Host address to bind to.

  • phone_number_id (Optional[str]) – Meta WhatsApp Phone Number ID.

  • access_token (Optional[str]) – Meta Graph API Access Token.

  • verify_token (Optional[str]) – Webhook verification token (or WHATSAPP_VERIFY_TOKEN env var; random if unset).

  • app_secret (Optional[str]) – Meta App Secret for HMAC validation (or WHATSAPP_APP_SECRET env var). Required.

  • db_path (str) – Path to the SQLite session database.

  • webhook_path (str) – Webhook URL path.

  • session_timeout (Union[int, str, None]) – Seconds of inactivity before a user’s conversation starts over (None: never). "auto" uses 30 minutes, or 24 hours if welcome messages are enabled on the phone number, since then conversations also start over when the user opens a new chat.

  • session_retention_days (Optional[int]) – Delete the conversations of users inactive for longer than this (None to keep them).

  • tunnel (bool) – If True, attempts to spawn a public ngrok tunnel.

  • auto_setup (bool) – If True (with tunnel=True), overwrites the Meta webhook URL of the WhatsApp Business Account and phone number with the tunnel URL. Use only with test accounts.

  • max_messages_per_minute (Optional[int]) – Per-user limit for bursts of messages; extra messages are dropped (None to disable).

  • max_messages_per_hour (Optional[int]) – Per-user limit for sustained use; extra messages are dropped (None to disable).

  • log_level (str) – Logging level for the server.

  • max_workers (Optional[int]) – Maximum number of users whose messages are processed at the same time, each on a clone of the agent sharing its model (None: 8; a user’s messages are always processed one at a time, in order). Agents with a local Hugging Face model or inspectors serve one message at a time. With several workers, the agent’s tools must be thread-safe.

  • max_message_age (Optional[int]) – Ignore messages sent longer ago than this many seconds (None to answer all). Meta retries webhooks it could not deliver (e.g. while the server was down) for days, and late replies would be out of context.

  • on_event (Optional[Callable[[str, Event], None]]) – Function called as on_event(user_id, event) with each Event of a user’s turn, in order, once the reply is sent: orchestrator instructions (with the orchestrator’s event_label as actionLabel), tool calls, and the reply. The user ID is their phone number. It runs in the server’s threads, so it may block (e.g. to send an email), but it may run at the same time for different users, so it must be thread-safe. Errors are logged and ignored.


sdialog.chat_ui

Web chat GUI for agents served with sdialog.agents.Agent.serve() (chat_ui=True).

The chat is a static page (HTML, JavaScript and CSS, no build step or external resources) served by the same FastAPI app as the REST API. Conversations are kept in the browser (localStorage) and sent in full with each message, so nothing is stored on the server. The page adapts to being opened in its own tab or window, or embedded in another page with an <iframe> or with the floating chat button of widget.js.

class sdialog.chat_ui.ChatUI(path: str = '/chat', title: str | None = None, multiple_conversations: bool = True, markdown: bool = False, show_events: bool = False, embed_origins: List[str] | None = None)

Bases: object

Options of the web chat GUI served along with the agents’ REST API.

Parameters:
  • path (str) – URL path of the chat page (/chat by default), e.g. http://localhost:1333/chat.

  • title (Optional[str]) – Title shown in the chat header and the browser tab (None: the agent’s name, or “Chat” for several agents).

  • multiple_conversations (bool) – If True, users can keep several conversations, listed in a side panel; if False, there is a single conversation and “New chat” replaces it.

  • markdown (bool) – If True, agent replies are rendered as Markdown (bold, italics, lists, headings, links and code); if False, they are shown as plain text.

  • show_events (bool) – If True, the agent’s reasoning, orchestration instructions and tool calls are shown (collapsed) above each reply. Keep it False for end users: these may contain internal information, such as the instructions given to the agent or the output of its tools.

  • embed_origins (Optional[List[str]]) – Origins of the pages allowed to embed the chat in an <iframe> (e.g. ["https://example.org"]), besides the server itself. None (default) allows any page.

Example:

from sdialog.agents import Agent
from sdialog.chat_ui import ChatUI

support = Agent(name="Support")

# Default chat GUI on http://localhost:1333/chat
support.serve(port=1333, chat_ui=True)

# Or with options
support.serve(port=1333, chat_ui=ChatUI(title="Help desk", markdown=True,
                                        embed_origins=["https://example.org"]))
frame_ancestors() → str | None

Value of the CSP frame-ancestors directive (None: any page can embed the chat).

page_config(model_names: List[str]) → Dict[str, Any]

Settings passed to the chat page’s script.

page_headers() → Dict[str, str]

HTTP headers of the chat page: only its own files are loaded, and only listed sites can embed it.

render_page(model_names: List[str]) → str

Return the chat page’s HTML, with its settings embedded as JSON.

embed_origins: List[str] | None = None
markdown: bool = False
multiple_conversations: bool = True
path: str = '/chat'
show_events: bool = False
title: str | None = None
sdialog.chat_ui.display_name(model_name: str) → str

Agent name shown in the chat for a served model name (without the default :latest tag).

sdialog.chat_ui.events_to_ui(events: List) → List[Dict[str, Any]]

Convert the events of an agent turn into what the chat shows above the reply (reasoning, orchestration instructions and tool calls with their output).


sdialog.whatsapp

WhatsApp integration for SDialog agents.

This package provides native WhatsApp serving capabilities for SDialog agents, enabling two-way text conversations over the Meta WhatsApp Cloud API with SQLite persistence and per-user session isolation.

class sdialog.whatsapp.MetaDiscoveryClient(access_token: str, app_secret: str | None = None)

Bases: object

Client for automating Meta WhatsApp Cloud API credentials discovery and webhook setup.

Adapted from WAVoice (MIT License, https://github.com/amitbhakt/wavoice).

async configure_webhooks(callback_url: str, verify_token: str, phone_number_id: str | None = None, waba_id: str | None = None) → Dict[str, bool]

Programmatically synchronize all 3 tiers of Meta WhatsApp webhooks: 1. App-level subscription (POST /{app_id}/subscriptions) 2. WABA-level subscription (POST /{waba_id}/subscribed_apps) 3. Phone-number-level override (POST /{phone_number_id})

async discover_phone_number_id(waba_id: str | None = None) → str | None

Auto-discover the primary WhatsApp Phone Number ID.

async discover_waba_id() → str | None

Auto-discover WhatsApp Business Account (WABA) ID from token permissions.

async inspect_token() → Dict[str, Any]

Inspect the provided User/System Access Token via debug_token endpoint.

Returns metadata including app_id, scopes, user_id, and granular target IDs (WABAs).

async is_welcome_message_enabled(phone_number_id: str) → bool | None

Check whether welcome messages are enabled on a phone number, in which case Meta sends a request_welcome webhook whenever a user opens a new chat with it.

Returns None if the setting could not be read.

async list_phone_numbers(waba_id: str) → List[Dict[str, Any]]

List all phone numbers under a WhatsApp Business Account.

class sdialog.whatsapp.MetaWhatsAppClient(config: WhatsAppConfig)

Bases: object

Async client for interacting with the Meta WhatsApp Cloud API.

async mark_as_read(message_id: str, typing_indicator: bool = False) → bool

Mark an incoming WhatsApp message as read (blue double check).

With typing_indicator=True, also show “typing…” to the user, until the next reply or for 25 seconds.

async send_text_message(to: str, text: str) → bool

Send a text message to a WhatsApp user.

If the text exceeds WhatsApp’s maximum length (4096 characters), it is split and sent in chunks.

class sdialog.whatsapp.SQLiteSessionStore(db_path: str = 'whatsapp_sessions.db')

Bases: object

Thread-safe SQLite store for WhatsApp user sessions and webhook idempotency.

Features: - WAL mode for concurrent non-blocking reads/writes. - Idempotency tracking to reject duplicate Meta webhook deliveries. - Automatic session expiration after inactivity timeout.

cleanup_old_records(retention_days: int = 7, session_retention_days: int | None = None) → None

Purge idempotency records older than retention_days and, if session_retention_days is set, the sessions of users inactive for longer than that.

is_message_processed(wamid: str) → bool

Check whether a message ID has already been received and processed.

load_session(wa_id: str, timeout_seconds: int | None = 1800) → Dict[str, Any] | None

Load session state for a user.

Returns None if session does not exist or has exceeded timeout_seconds of inactivity (sessions never expire if timeout_seconds is None).

mark_message_processed(wamid: str) → None

Record a message ID in the idempotency table.

reset_session(wa_id: str) → None

Reset and remove session state for a user.

save_session(wa_id: str, state: Dict[str, Any]) → None

Save or update the session state for a user with the current timestamp.

class sdialog.whatsapp.WhatsAppConfig(port: int = 1234, host: str = '0.0.0.0', phone_number_id: str | None = None, access_token: str | None = None, verify_token: str | None = None, app_secret: str | None = None, api_version: str = 'v21.0', db_path: str = 'whatsapp_sessions.db', webhook_path: str = '/webhook', session_timeout: int | str | None = 'auto', session_retention_days: int | None = 30, tunnel: bool = False, auto_setup: bool = False, max_history_turns: int = 40, max_messages_per_minute: int | None = 6, max_messages_per_hour: int | None = 60, max_workers: int | None = None, max_message_age: int | None = 120, enforce_signature: bool = True, mark_as_read: bool = True, typing_indicator: bool = True, on_event: Callable[[str, Event], None] | None = None, log_level: str = 'info')

Bases: object

Configuration parameters for serving an SDialog agent on WhatsApp.

Parameters will fall back to standard environment variables if not provided: - WHATSAPP_PHONE_NUMBER_ID - WHATSAPP_ACCESS_TOKEN - WHATSAPP_VERIFY_TOKEN (a random token is generated if not set) - WHATSAPP_APP_SECRET (required unless enforce_signature=False)

validate(dry_run: bool = False) → None

Validate the settings, and that required credentials are set when not in dry_run mode.

access_token: str | None = None
api_version: str = 'v21.0'
app_secret: str | None = None
auto_setup: bool = False
db_path: str = 'whatsapp_sessions.db'
enforce_signature: bool = True
host: str = '0.0.0.0'
log_level: str = 'info'
mark_as_read: bool = True
max_history_turns: int = 40
max_message_age: int | None = 120
max_messages_per_hour: int | None = 60
max_messages_per_minute: int | None = 6
max_workers: int | None = None
on_event: Callable[[str, Event], None] | None = None
phone_number_id: str | None = None
port: int = 1234
session_retention_days: int | None = 30
session_timeout: int | str | None = 'auto'
tunnel: bool = False
typing_indicator: bool = True
verify_token: str | None = None
webhook_path: str = '/webhook'
class sdialog.whatsapp.WhatsAppServer

Bases: object

FastAPI server exposing Meta WhatsApp Cloud API webhook endpoints for SDialog agents.

classmethod create_app(agent: Any, config: WhatsAppConfig) → FastAPI

Create and configure the FastAPI WhatsApp webhook application.

classmethod serve(agent: Any, config: WhatsAppConfig | None = None) → None

Start the WhatsApp webhook server with optional auto-discovery and webhook sync.

classmethod serve_in_thread(agent: Any, config: WhatsAppConfig | None = None) → Thread

Start the WhatsApp webhook server in a background daemon thread (useful for Jupyter / tests).


sdialog.agent_pool

Parallel serving of an agent, running each conversation turn on a fresh clone (used by the SDialog servers).

class sdialog.agent_pool.AgentPool(agent: Agent, max_workers: int | None = None)

Bases: object

Runs conversation turns of an agent in parallel, up to max_workers at a time, each on a fresh clone of the agent (see clone()), which shares its model and is discarded after the turn.

Turns with the same key (e.g. a user ID) run one at a time and in arrival order, so a user’s messages are never processed concurrently, while turns with different keys run in parallel. Callers restore the conversation on the lent agent before each turn (e.g. with set_state()) and save it afterwards.

Parallel turns only help when the model runs elsewhere (an API or a model server), so agents with a local Hugging Face model or with inspectors (whose hooks would mix activations from different conversations) are served one turn at a time. With a single worker, the agent itself is lent instead of a clone.

Agent calls run in the pool’s own threads (see run()). With several workers, the agent’s tools and custom functions (e.g. postprocess_fn) may run at the same time for different conversations, so they must be thread-safe; use max_workers=1 otherwise.

Example:

from sdialog.agents import Agent
from sdialog.agent_pool import AgentPool

pool = AgentPool(Agent(name="Support"))

async def turn(user_id, state, message):
    async with pool.acquire(user_id) as agent:
        agent.reset()
        if state:
            agent.set_state(state)
        reply = await pool.run(agent, message)
        return reply, agent.get_state()
Parameters:
  • agent (Agent) – The agent to serve.

  • max_workers (Optional[int]) – Maximum number of turns processed at the same time. If None, 8, or 1 for agents with a local model or inspectors.

acquire(key: str | None = None) → AsyncIterator[Agent]

Wait for a free worker and lend an agent for one turn: a fresh clone, or the agent itself with a single worker.

Parameters:

key (Optional[str]) – Conversation key (e.g. user ID). Turns with the same key run one at a time, in order. If None, the turn is not ordered with respect to any other.

Returns:

Async context manager yielding the agent.

close() → None

Release the pool’s threads once running calls finish.

async run(func: Callable, *args) → Any

Run a blocking call (e.g. agent(message)) in one of the pool’s threads, without blocking the event loop.

The pool has its own max_workers threads, so the number of turns running at the same time is not limited by asyncio’s default thread pool.

Parameters:

func (Callable) – The function to call.

Returns:

The function’s result.

sdialog.agent_pool.uses_local_model(agent: Agent) → bool

Whether the agent runs a local (Hugging Face) model in this process, rather than calling a model server or API.

Parameters:

agent (Agent) – The agent.

Return type:

bool


sdialog.rate_limit

Sliding window rate limiting, shared by the SDialog servers (REST API and WhatsApp).

class sdialog.rate_limit.RateLimiter(limits: Dict[str, Tuple[int | None, float]])

Bases: object

Per-key sliding window rate limiter (e.g. one key per user or client IP) enforcing several limits at once, such as a per-minute limit for bursts and a per-hour limit for sustained use.

Rejected requests do not count towards the limits, so a client that keeps retrying while blocked is not blocked for longer.

Example:

from sdialog.rate_limit import RateLimiter

limiter = RateLimiter({"minute": (30, 60), "hour": (300, 3600)})

exceeded = limiter.hit("10.0.0.1")
if exceeded:
    limit_name, retry_after = exceeded  # e.g. ("minute", 12.5)
Parameters:

limits (Dict[str, Tuple[Optional[int], float]]) – Limit name -> (maximum requests, window in seconds). Limits whose maximum is None (or 0) are disabled. When several limits are exceeded, the first one is reported.

clear() → None

Forget all recorded requests.

hit(key: str) → Tuple[str, float] | None

Record a request from key if it is within all limits.

Parameters:

key (str) – Who the request comes from (e.g. user ID or client IP).

Returns:

None if the request is allowed, otherwise (limit_name, retry_after): the name of the exceeded limit and the seconds until a request from key would be allowed again.

Return type:

Optional[Tuple[str, float]]


sdialog.audio

Audio generation for dialogues: turn any two-speaker Dialog into realistic audio with ground-truth annotations (who speaks when, what is said), at different levels of difficulty.

The main entry point is dialog.to_audio() (sdialog.audio.synthesis.to_audio()), which uses the Dia2 dialogue TTS model by default and lets you control:

  • Voices: matched to the personas from a voice database, designed from the persona description, random, or given explicitly.

  • Timing: natural pauses, sampled pauses and overlapping speech.

  • Acoustics: room reverberation (random rooms, a Room of your choice, or real rooms measured in BUT ReverbDB with ButReverbDB), background noise, telephone channel, loudness differences.

  • Output: mono or stereo (one channel per speaker), sample rate.

  • Presets: “clean”, “conversational”, “room”, “call_center”, “far_field”, “hard” (or your own).

Example:

audio = dialog.to_audio()                                      # clean audio, persona-matched voices
audio = dialog.to_audio(preset="call_center", stereo=True)     # call center recording, one speaker per channel
audio = dialog.to_audio(voices="random", reverb="medium", noise=(5, 15), overlap=0.2, seed=0)

audio.audio, audio.sample_rate      # waveform
audio.segments                      # turn-level annotations (speaker, text, start, end, word timestamps)
audio.save("output/dialog")         # output/dialog.wav, .json and .rttm

# Many dialogues in parallel (one model per available GPU)
from sdialog.audio import dialogs_to_audio
dialogs_to_audio(dialogs, "output/", preset="room")
sdialog.audio.to_audio(dialog, path: str | None = None, preset: str | None = None, voices: str | dict = 'db', voice_database=None, voice_description: str | Callable | None = None, tts=None, pauses: str | float | Tuple[float, float] | None = None, overlap: float | None = None, max_overlap: float | None = None, reverb: Any = None, noise: Any = None, channel: Any = None, level_jitter_db: float | None = None, stereo: bool = False, sample_rate: int = 16000, seed: int | None = None, audio_format: str = 'wav') → DialogAudio

Converts a two-speaker dialogue into audio, with ground-truth annotations.

Scene parameters left as None take the value of the preset (or the clean default); pass False to explicitly disable an effect set by the preset. Reverb, noise and channel values can be given per speaker as a dictionary keyed by speaker name or index (0 = first speaker); a single value applies to the whole recording (all speakers). A list of values means “pick one at random”.

Parameters:
  • dialog – The Dialog to convert (exactly two speakers).

  • path – If given, saves <path>.<audio_format>, <path>.json and <path>.rttm.

  • preset – Named scene preset: “clean”, “conversational”, “room”, “call_center”, “far_field”, “hard”, or any preset added with sdialog.audio.register_preset().

  • voices – “db” (voice database matching the personas), “design” (designed from the persona description), “random” (made up by the TTS engine), or a {speaker: voice} dictionary (audio path, (array, sample_rate), Voice or engine voice name).

  • voice_database – Voice database, or Hugging Face dataset name, used by voices="db" (default: the TTS engine’s default, “sdialog/voices-libritts” for Dia2).

  • voice_description – Jinja2 template over the persona fields (or function of the persona dict) describing each voice, used by voices="design".

  • tts – TTS engine: a BaseDialogTTS (default: Dia2TTS()), or a classic BaseTTS/BaseVoiceCloneTTS engine (wrapped with PerTurnTTS).

  • pauses – “natural” (the TTS engine’s own timing), a median pause in seconds (log-normal), or a (min, max) range in seconds (uniform).

  • overlap – Probability (0-1) that a turn starts before the previous one ends.

  • max_overlap – Maximum overlap, as a fraction of the previous turn’s duration (default 0.3).

  • reverb – Room reverberation: True or “small”/”medium”/”large” (simulated room of random size and positions), a Room (room of your choice: dimensions, materials or RT60, microphone and speaker positions, microphone directivity), a ButReverbDB (rooms measured in BUT ReverbDB), a path to an impulse response file or folder of files, or an impulse response array.

  • noise – Background noise: an SNR in dB, a (min, max) SNR range, a noise type (“white”, “pink”, “brown”, or “room”: the noise recorded in the measured room of reverb=ButReverbDB(...)) or audio file/folder path, or a dict {"type": ..., "snr": ...}.

  • channel – Telephone channel codec: “telephone” (= “g711”), “g711”, “g729”, “amr” or “amr-wb”.

  • level_jitter_db – Maximum random loudness difference (dB) between speakers.

  • stereo – If True, output one channel per speaker (in order of appearance); otherwise mono.

  • sample_rate – Output sample rate (Hz).

  • seed – Random seed; the same seed reproduces the same audio (a random seed is drawn and saved in the annotations when not given).

  • audio_format – Format of the audio file saved to path: “wav” (default) or “flac” (lossless, about half the size).

Returns:

A DialogAudio with the waveform and the annotations.

Raises:

ValueError – If the dialogue does not have exactly two speakers or a parameter is invalid.

sdialog.audio.dialogs_to_audio(dialogs: Sequence, out_dir: str, devices: str | List[str] | None = None, workers_per_device: int = 1, tts_factory: Callable[[str], BaseDialogTTS] | None = None, seed: int | None = None, **kwargs) → List[dict]

Converts many dialogues to audio in parallel, with one TTS model per worker process.

Every dialogue is saved under out_dir (<dialog_id>.wav, or .flac with audio_format="flac", .json and .rttm; <dialog_id>_<position> for dialogues whose id appears more than once in dialogs) and an index.jsonl file lists all the outputs. Each dialogue gets its own seed (derived from seed and its position in dialogs, or drawn at random if seed is not given), which is saved in its annotations and in index.jsonl; results do not depend on the number of workers.

Parameters:
  • dialogs – Dialogues to convert.

  • out_dir – Output folder.

  • devices – Where to run: None (default) uses all visible GPUs, or the CPU if there is none; "cpu"; "cuda" (all GPUs); a single device like "cuda:1"; or a list of devices.

  • workers_per_device – Number of worker processes (each with its own model) per device.

  • tts_factory – Function device -> BaseDialogTTS creating each worker’s engine (default: Dia2TTS(device=device)). Must be a top-level (picklable) function when using several workers.

  • seed – Base random seed, to make the whole batch reproducible.

  • kwargs – Any other to_audio() argument (preset, voices, stereo, audio_format, …).

Returns:

The rows of index.jsonl (one per dialogue, with output paths and seed, or an “error” field).

Example:

from sdialog.audio import dialogs_to_audio

rows = dialogs_to_audio(dialogs, "audios/", preset="call_center", stereo=True)  # all available GPUs
class sdialog.audio.DialogAudio(audio: numpy.ndarray, sample_rate: int, segments: ~typing.List[~sdialog.audio.result.Segment], speakers: ~typing.List[str], voices: dict = <factory>, config: dict = <factory>, dialog_id: str | None = None)

Bases: object

Audio of a dialogue with its annotations, returned by dialog.to_audio().

Variables:
  • audio – Float32 waveform, shape (samples,) (mono) or (samples, channels) (stereo, one channel per speaker in dialogue speaker order).

  • sample_rate – Sample rate (Hz).

  • segments – One Segment per turn, in dialogue order.

  • speakers – Speaker names, in channel order.

  • voices – Voice used for each speaker (e.g. the voice database identifier, or “random”).

  • config – All the parameters used to generate the audio, including the values drawn at random (room, SNRs, codecs, …), for reproducibility.

  • dialog_id – Id of the source dialogue, if any.

Example:

audio = dialog.to_audio(preset="call_center", stereo=True, seed=0)
audio.save("output/call")       # output/call.wav, output/call.json, output/call.rttm
for seg in audio.segments:
    print(f"{seg.start:6.2f}-{seg.end:6.2f} {seg.speaker}: {seg.text}")
audio: numpy.ndarray
sample_rate: int
segments: List[Segment]
speakers: List[str]
voices: dict
config: dict
dialog_id: str | None = None
property duration: float

Duration of the audio in seconds.

property channels: int

Number of audio channels.

to_dict(words: bool = True) → dict

Returns the annotations (everything but the waveform) as a JSON-serializable dictionary.

to_json(indent: int = 2, words: bool = True) → str

Returns the annotations as a JSON string.

to_rttm(file_id: str | None = None) → str

Returns the speaker turns in RTTM format (speaker diarization ground truth).

save(path: str, audio_format: str = 'wav') → dict

Saves the audio and its annotations as <path>.<audio_format>, <path>.json and <path>.rttm.

Parameters:
  • path – Output path without extension (an audio extension, if given, is removed).

  • audio_format – Audio file format (“wav” or “flac”).

Returns:

The paths of the written files.

display(audio_format: str = 'mp3')

Shows an audio player (in Jupyter notebooks), with the audio normalized to full scale.

The audio is embedded in the notebook as MP3 by default, about 7 times smaller than WAV, so that notebooks saved with their outputs stay small enough to share. Saved files (save()) are not affected.

Parameters:

audio_format (str) – “mp3” (default) or “wav” (the exact samples, as before). MP3 falls back to WAV if the installed soundfile cannot write MP3 (libsndfile < 1.1).

class sdialog.audio.Segment(turn: int, speaker: str, text: str, start: float, end: float, channel: int | None = None, words: Tuple[str, float]]=<factory>)

Bases: object

Ground-truth annotation of one dialogue turn in the audio.

Variables:
  • turn – Index of the turn in the dialogue.

  • speaker – Speaker name.

  • text – Text of the turn.

  • start – Start time (seconds).

  • end – End time (seconds).

  • channel – Channel holding this speaker in stereo output (None for mono output).

  • words – Word timestamps (word, start_seconds) (absolute times), when the TTS engine provides them.

turn: int
speaker: str
text: str
start: float
end: float
channel: int | None = None
words: List[Tuple[str, float]]
property duration: float
class sdialog.audio.Room(*, dimensions: ~typing.Tuple[float, float, float], rt60: float | None = None, materials: str | float | ~typing.Dict[str, str | float] | None = None, mic: ~typing.Tuple[float, float, float] | int | str = 'ceiling', mic_pattern: str = 'omni', mic_direction: ~typing.Tuple[float, float] | int | str | None = None, speakers: ~typing.Dict[int | str, ~typing.Tuple[float, float, float]] = <factory>, max_order: int | None = None, air_absorption: bool = False, ray_tracing: bool = False)

Bases: BaseModel

A shoebox room used to simulate the reverberation of sdialog.audio.synthesis.to_audio() (dialog.to_audio(reverb=Room(...))).

The absorption is given either as a target rt60 or as materials (default: wooden walls, carpet and an absorbing ceiling). Speakers without a position are placed at random (mouth height, at least 0.5 m from the microphone and from each other).

Variables:
  • dimensions (Tuple[float, float, float]) – Width (x), length (y) and height (z) of the room, in meters.

  • rt60 (Optional[float]) – Target reverberation time in seconds (absorption computed with Sabine’s formula).

  • materials (Optional[Union[str, float, Dict[str, Union[str, float]]]]) – Surface materials: a pyroomacoustics material name (e.g. “brickwork”, “plasterboard”) or energy absorption coefficient for all surfaces, or a dictionary by surface (“walls”, “floor”, “ceiling”, or a single wall: “east”, “west”, “north”, “south”).

  • mic (Union[str, int, Tuple[float, float, float]]) – Microphone position: (x, y, z) coordinates, “ceiling” (center of the ceiling), “wall” (middle of the west wall, at standing height), “between_speakers” (midpoint between the speakers), or a speaker name or index (a lapel microphone on that speaker’s chest).

  • mic_pattern (str) – Microphone directivity: “omni”, “cardioid”, “subcardioid”, “hypercardioid” or “figure8”.

  • mic_direction (Optional[Union[str, int, Tuple[float, float]]]) – Where a directional microphone points: a speaker name or index, “speakers” (the midpoint between the speakers, the default; up for the “between_speakers” microphone, right below it), or (azimuth, colatitude) in degrees (azimuth from the x axis; colatitude from the z axis, 90 = horizontal).

  • speakers (Dict[Union[int, str], Tuple[float, float, float]]) – Speaker positions (x, y, z), by speaker name or index (0 = first speaker of the dialogue).

  • max_order (Optional[int]) – Maximum reflection order of the image source method (default: from the RT60, up to 30, or 17 with materials).

  • air_absorption (bool) – Whether to simulate air absorption.

  • ray_tracing (bool) – Whether to add ray tracing to the image source method (more realistic late reverberation, slower).

Example:

from sdialog.audio import Room

room = Room(dimensions=(5, 4, 2.8), materials={"walls": "plasterboard", "floor": "linoleum_on_concrete"},
            mic=(2.5, 2, 0.8), speakers={0: (1.5, 2, 1.2), 1: (3.5, 2, 1.2)})
audio = dialog.to_audio(reverb=room, seed=0)
audio.config["room"]  # the simulated room (positions included)

rirs, info = room.compute_rirs(["Alice", "Bob"], sample_rate=16000)  # the impulse responses only
dimensions: Tuple[float, float, float]
rt60: float | None
materials: str | float | Dict[str, str | float] | None
mic: Tuple[float, float, float] | int | str
mic_pattern: str
mic_direction: Tuple[float, float] | int | str | None
speakers: Dict[int | str, Tuple[float, float, float]]
max_order: int | None
air_absorption: bool
ray_tracing: bool
compute_rirs(speakers: List[str], sample_rate: int, rng: numpy.random.Generator | None = None) → Tuple[List[numpy.ndarray], dict]

Simulates the room and computes the impulse response from each speaker to the microphone.

Parameters:
  • speakers (List[str]) – Names of the speakers to place, in order (positions given by index refer to this list).

  • sample_rate (int) – Sample rate of the returned impulse responses.

  • rng (Optional[np.random.Generator]) – Random generator used to place the speakers without a given position.

Returns:

The impulse response of each speaker, and a dictionary describing the simulated room (dimensions, absorption, microphone and speaker positions).

Return type:

Tuple[List[np.ndarray], dict]

Raises:

ValueError – If the RT60 cannot be reached in the room or a speaker name is not valid.

Example:

rirs, info = Room(dimensions=(6, 4, 3), rt60=0.6).compute_rirs(["Alice", "Bob"], 16000)
class sdialog.audio.ButReverbDB(path: str, rooms: List[str] | None = None, download: bool = False)

Bases: object

Impulse responses and background noise measured in real rooms (BUT ReverbDB), to use as reverb in dialog.to_audio().

For each dialogue, a room and a microphone are drawn at random (from the to_audio seed), and each speaker gets a different loudspeaker position in that room, so both speakers are recorded by the same microphone. Given per speaker (e.g. reverb={"Caller": but}), each speaker gets a position of their own. With noise="room", the background noise is the one recorded by the same microphone, in the same room.

Parameters:
  • path (str) – Path to the extracted BUT ReverbDB (the folder containing the room folders, e.g. VUT_FIT_L207).

  • rooms (Optional[List[str]]) – Names of the rooms to use (default: all of them, see rooms).

  • download (bool) – If True and path does not exist, downloads the database (8.7 GB) and extracts it there.

Raises:
  • FileNotFoundError – If no impulse responses with the BUT ReverbDB layout are found under path.

  • ValueError – If a room in rooms is not in the database.

Example:

from sdialog.audio import ButReverbDB

but = ButReverbDB("BUT_ReverbDB", rooms=["VUT_FIT_L207", "VUT_FIT_Q301"], download=True)
print(but.rooms)
audio = dialog.to_audio(reverb=but, noise="room", seed=0)
audio.config["room"]   # room, microphone, positions and files used
static download(path: str, url: str = 'http://merlin.fit.vutbr.cz/ReverbDB/BUT_ReverbDB_rel_19_06_RIR-Only.tgz') → str

Downloads BUT ReverbDB (RIR-only release, 8.7 GB) and extracts it into path. The archive is removed once extracted; an interrupted download or extraction leaves only .part files, so path exists only when complete.

Parameters:
  • path (str) – Folder to extract the database into (must not exist yet).

  • url (str) – Address of the archive.

Returns:

path.

Return type:

str

property rooms: List[str]

Names of the rooms in use.

json() → dict

Returns a JSON-serializable description (stored in the audio annotations).

compute_rirs(n_sources: int, sample_rate: int, rng: numpy.random.Generator | None = None) → Tuple[List[numpy.ndarray], dict]

Draws a room and a microphone, and loads the impulse response of n_sources different loudspeaker positions in that room (positions are reused only if the room has fewer than n_sources).

Parameters:
  • n_sources (int) – Number of speakers to place.

  • sample_rate (int) – Sample rate of the returned impulse responses.

  • rng (Optional[np.random.Generator]) – Random generator (default: a new unseeded one).

Returns:

The impulse responses (one per speaker) and a description of the room and files used.

Return type:

Tuple[List[np.ndarray], dict]

sdialog.audio.register_preset(name: str, **params) → None

Registers (or replaces) a named scene preset.

Parameters:
  • name – Name of the preset (used as dialog.to_audio(preset=name)).

  • params – Scene parameters; valid keys are: pauses, overlap, max_overlap, reverb, noise, channel and level_jitter_db.

Raises:

ValueError – If an invalid parameter is given (e.g. stereo, which is an output option).

sdialog.audio.list_presets() → dict

Returns a copy of all registered presets.

class sdialog.audio.Voice(*, gender: str = '', age: int = 0, identifier: str = '', voice: Any, language: str = 'english', language_code: str = 'a')

Bases: BaseModel

Data model representing a voice entry in the voice database.

The Voice class encapsulates all metadata associated with a specific voice, including speaker characteristics, language information, and voice identifiers. This model is used throughout the voice database system for voice selection and management.

Key Attributes:

  • gender: Speaker gender for voice selection

  • age: Speaker age for voice selection

  • identifier: Unique identifier for the voice

  • voice: Voice data (file path or voice string identifier)

  • language: Human-readable language name

  • language_code: Language code for TTS engines

Variables:
  • gender (str) – Speaker gender (e.g., “male”, “female”).

  • age (int) – Speaker age in years.

  • identifier (str) – Unique identifier for this voice entry.

  • voice (str) – Voice data - can be a file path or voice string identifier.

  • language (str) – Human-readable language name (default: “english”).

  • language_code (str) – Language code for TTS engines (default: “a”).

gender: str
age: int
identifier: str
voice: Any
language: str
language_code: str
class sdialog.audio.BaseVoiceDatabase

Bases: object

Abstract base class for voice database implementations.

This class provides the foundation for voice database implementations, defining the common interface and data structures used across different voice database types. It manages voice data organization, usage tracking, and provides utility methods for voice selection and statistics.

Key Features:

  • Hierarchical voice organization by language, gender, and age

  • Voice usage tracking to prevent duplicates (optional)

  • Comprehensive statistics and reporting capabilities

  • Abstract interface for different data source implementations

  • Flexible voice selection based on speaker characteristics

Data Structure:

The voice database uses a nested dictionary structure: _data[language][(gender, age)] = [Voice1, Voice2, …]

Variables:
  • _data (dict[str, dict[tuple[str, int], List[Voice]]]) – Nested dictionary organizing voices by language, gender, and age.

  • _used_voices (dict[str, List[str]]) – Dictionary tracking used voice identifiers by language.

get_data() → dict

Retrieves the complete voice database data structure.

Returns:

The nested dictionary containing all voice data organized by language, gender, and age.

Return type:

dict[str, dict[tuple[str, int], List[Voice]]]

populate() → dict

Populates the voice database with voice data.

This abstract method must be implemented by subclasses to load voice data from their specific data source (e.g., Hugging Face datasets, local files, in-memory data).

Returns:

The populated voice data dictionary.

Return type:

dict

Raises:

NotImplementedError – If not implemented by subclass.

reset_used_voices()

Resets the tracking of used voices across all languages.

This method clears the usage tracking, allowing all voices to be available for selection again. Useful for starting a new dialogue generation session or resetting voice allocation.

get_statistics(pretty: bool = False, pretty_format: str = 'markdown') → dict | str

Generates comprehensive statistics about the voice database.

This method analyzes the voice database and provides detailed statistics about the available voices, including language distribution, gender/age breakdowns, and usage patterns. The statistics can be returned as either a structured dictionary or a formatted string for display.

Statistics include:
  • num_languages: Total number of languages in the database

  • overall: Global statistics (total voices, gender distribution, age distribution)

  • languages: Per-language detailed statistics including:
    • total: Total voices for the language

    • by_gender: Voice count by gender (male/female)

    • ages: Voice count by age bins

    • by_gender_age: Cross-tabulation of gender and age

    • unique_speakers: Number of unique voice identifiers

    • language_codes: Observed language codes for TTS engines

    • age_stats: Age statistics (min, max, mean)

Parameters:
  • pretty (bool) – If True, returns a formatted string; if False, returns a dictionary.

  • pretty_format (str) – Format for pretty output - “markdown” for Markdown tables, other values for fancy grid format.

Returns:

Either a dictionary with statistics or a formatted string representation.

Return type:

Union[dict, str]

add_voice(gender: str, age: int, identifier: str, voice: str, lang: str, language_code: str)

Adds a voice entry to the database.

This method creates a new Voice object and adds it to the appropriate location in the hierarchical database structure based on language, gender, and age. The voice is organized for efficient retrieval during voice selection.

Parameters:
  • gender (str) – Speaker gender (e.g., “male”, “female”).

  • age (int) – Speaker age in years.

  • identifier (str) – Unique identifier for this voice entry.

  • voice (str) – Voice data - can be a file path or voice string identifier.

  • lang (str) – Language name (e.g., “english”, “french”).

  • language_code (str) – Language code for TTS engines (e.g., “a”, “f”).

get_voice_by_identifier(identifier: str, lang: str, keep_duplicate: bool = True) → Voice

Retrieves a voice by its unique identifier.

This method searches for a voice with the specified identifier within the given language. It can optionally enforce uniqueness by preventing the reuse of already used voices.

Parameters:
  • identifier (str) – The unique identifier of the voice to retrieve.

  • lang (str) – The language to search within.

  • keep_duplicate (bool) – If True, allows returning voices that have already been used. If False, raises an error if the voice has already been used.

Returns:

The Voice object with the specified identifier.

Return type:

Voice

Raises:
  • ValueError – If the language is not found in the database.

  • ValueError – If the voice identifier is not found.

  • ValueError – If keep_duplicate is False and the voice has already been used.

get_voice(gender: str, age: int, lang: str = 'english', keep_duplicate: bool = False, seed: int = None) → Voice

Retrieves a voice based on speaker characteristics with intelligent matching.

This method selects a voice from the database based on the specified speaker characteristics (gender, age, language). It uses intelligent matching to find the closest available voice when an exact match is not available, and can optionally enforce uniqueness to prevent voice reuse.

Voice selection process: 1. Normalize language and gender parameters 2. Check for exact match (gender, age, language) 3. If no exact match, find closest age for the specified gender 4. Filter out used voices if keep_duplicate is False 5. Randomly select from available voices 6. Track usage if keep_duplicate is False

Parameters:
  • gender (str) – Speaker gender (e.g., “male”, “female”).

  • age (int) – Speaker age in years.

  • lang (str) – Language name (default: “english”).

  • keep_duplicate (bool) – If True, allows voice reuse. If False, ensures each voice is used only once.

  • seed (int) – Seed for random number generator.

Returns:

A Voice object matching the specified characteristics.

Return type:

Voice

Raises:
  • ValueError – If the language is not found in the database.

  • ValueError – If no voice is found for the specified characteristics.

class sdialog.audio.HuggingfaceVoiceDatabase(dataset_name: str = 'sdialog/voices-libritts', subset: str = 'train')

Bases: BaseVoiceDatabase

Voice database implementation using Hugging Face datasets.

This implementation loads voice data from Hugging Face datasets, providing access to large-scale voice collections with standardized metadata. It supports both remote datasets and local dataset caches, making it suitable for research and production use cases.

Key Features:

  • Integration with Hugging Face datasets library

  • Support for both remote and local dataset access

  • Automatic metadata extraction and validation

  • Fallback handling for missing metadata fields

  • Efficient dataset loading and caching

Expected Dataset Format:

The dataset should contain the following fields: - audio: Audio data with path information - voice: Voice identifier (alternative to audio) - gender: Speaker gender (“male”, “female”, “m”, “f”) - age: Speaker age (integer) - identifier: Unique voice identifier - language: Language name (optional, defaults to “english”) - language_code: Language code for TTS engines (optional, defaults to “e”)

Variables:
  • dataset_name (str) – Name or path of the Hugging Face dataset.

  • subset (str) – Dataset subset to use (e.g., “train”, “test”, “validation”).

populate() → dict

Populates the voice database from the Hugging Face dataset.

This method loads voice data from the specified Hugging Face dataset, extracts metadata for each voice entry, and organizes the data in the hierarchical database structure. It handles missing metadata by providing sensible defaults and logging warnings.

Data processing steps: 1. Load dataset from Hugging Face (remote or local cache) 2. Iterate through dataset entries 3. Extract and validate metadata fields 4. Handle missing fields with defaults and warnings 5. Organize voices by language, gender, and age 6. Create Voice objects and add to database

Returns:

The populated voice data dictionary.

Return type:

dict

Raises:
  • ImportError – If the datasets library is not installed.

  • ValueError – If the dataset or subset is not found.

  • ValueError – If required voice data is missing from the dataset.

class sdialog.audio.LocalVoiceDatabase(directory_audios: str, metadata_file: str)

Bases: BaseVoiceDatabase

Voice database implementation using local audio files and metadata.

This implementation loads voice data from local audio files and metadata files (CSV, TSV, or JSON), providing a flexible solution for custom voice collections. It supports various metadata formats and handles both relative and absolute file paths.

Key Features:

  • Support for multiple metadata formats (CSV, TSV, JSON)

  • Flexible file path handling (relative and absolute paths)

  • Comprehensive metadata validation

  • Support for both file paths and voice identifiers

  • Local file system integration

Required Metadata Format:

The metadata file must contain the following columns: - identifier: Unique voice identifier - gender: Speaker gender (“male”, “female”, “m”, “f”) - age: Speaker age (integer) - voice or file_name: Voice identifier or audio file path - language: Language name (optional, defaults to “english”) - language_code: Language code for TTS engines (optional, defaults to “e”)

Variables:
  • directory_audios (str) – Directory containing audio files.

  • metadata_file (str) – Path to the metadata file (CSV, TSV, or JSON).

populate() → dict

Populate the voice database. The metadata file can be a csv, tsv or json file. The metadata file must contain the following columns: identifier, gender, age, voice, language, language_code.

  • “voice” or “file_name” column: path to audio file or voice name (e.g., “am_echo”)

  • language column can be a string like “english” or “french”.

  • language_code column can be a string like “e” or “f”.

  • identifier column can be a string like “am_echo” or “am_echo_2”.

  • gender column can be a string like “male” or “female”.

  • age column can be an integer like 20 or 30.

class sdialog.audio.VoiceDatabase(data: list[dict])

Bases: BaseVoiceDatabase

Voice database implementation using in-memory voice data.

This implementation creates a voice database from a list of voice dictionaries, providing a flexible solution for programmatically creating voice databases or loading voice data from custom sources. It’s particularly useful for testing, small voice collections, or when voice data is already available in memory.

Key Features:

  • In-memory voice data processing

  • Support for custom voice data structures

  • Comprehensive data validation

  • Flexible voice data input format

  • No external file dependencies

Required Data Format:

The input data should be a list of dictionaries, where each dictionary contains the following keys: - identifier: Unique voice identifier - gender: Speaker gender (“male”, “female”, “m”, “f”) - age: Speaker age (integer) - voice: Voice identifier or data - language: Language name (optional, defaults to “english”) - language_code: Language code for TTS engines (optional, defaults to “e”)

Variables:

_input_data (list[dict]) – List of voice dictionaries to process.

populate() → dict

Populates the voice database from in-memory voice data.

This method processes the list of voice dictionaries provided during initialization, validates the data, and organizes it in the hierarchical database structure. It performs comprehensive validation to ensure data integrity and provides detailed error messages for missing or invalid data.

Data processing steps: 1. Validate input data format (list of dictionaries) 2. Iterate through each voice dictionary 3. Extract and validate required fields 4. Handle missing optional fields with defaults 5. Create Voice objects and add to database 6. Log processing statistics

Required fields in each voice dictionary:
  • identifier: Unique voice identifier

  • gender: Speaker gender (“male”, “female”, “m”, “f”)

  • age: Speaker age (integer)

  • voice: Voice identifier or data

  • language: Language name (optional, defaults to “english”)

  • language_code: Language code for TTS engines (optional, defaults to “e”)

Returns:

The populated voice data dictionary.

Return type:

dict

Raises:
  • ValueError – If the input data is not a list of dictionaries.

  • ValueError – If required voice data is missing from any entry.

sdialog.audio.synthesis

Dialogue-to-audio synthesis: the implementation behind dialog.to_audio().

The whole process runs in memory (no temporary files):

  1. Resolve the scene (preset + explicit arguments) and each speaker’s voice.

  2. Generate the audio of every turn with a dialogue TTS engine (Dia2 by default).

  3. Trim silences and normalize the speech level of every turn.

  4. Place the turns on a timeline (pauses / overlapping speech).

  5. Apply per-speaker effects (reverberation, noise, telephone channel) on each speaker’s track.

  6. Mix to mono or stereo (one channel per speaker) and apply the shared effects.

Example:

audio = dialog.to_audio()                                     # clean, Dia2, persona-matched voices
audio = dialog.to_audio(preset="call_center", stereo=True)    # agent / caller channels
audio = dialog.to_audio(voices="random", reverb="large", noise=10, overlap=0.2, seed=0)
audio.save("output/dialog")                                   # .wav + .json + .rttm
dialogs_to_audio(dialogs, "output/", preset="room")          # many dialogues, all available GPUs
sdialog.audio.synthesis.to_audio(dialog, path: str | None = None, preset: str | None = None, voices: str | dict = 'db', voice_database=None, voice_description: str | Callable | None = None, tts=None, pauses: str | float | Tuple[float, float] | None = None, overlap: float | None = None, max_overlap: float | None = None, reverb: Any = None, noise: Any = None, channel: Any = None, level_jitter_db: float | None = None, stereo: bool = False, sample_rate: int = 16000, seed: int | None = None, audio_format: str = 'wav') → DialogAudio

Converts a two-speaker dialogue into audio, with ground-truth annotations.

Scene parameters left as None take the value of the preset (or the clean default); pass False to explicitly disable an effect set by the preset. Reverb, noise and channel values can be given per speaker as a dictionary keyed by speaker name or index (0 = first speaker); a single value applies to the whole recording (all speakers). A list of values means “pick one at random”.

Parameters:
  • dialog – The Dialog to convert (exactly two speakers).

  • path – If given, saves <path>.<audio_format>, <path>.json and <path>.rttm.

  • preset – Named scene preset: “clean”, “conversational”, “room”, “call_center”, “far_field”, “hard”, or any preset added with sdialog.audio.register_preset().

  • voices – “db” (voice database matching the personas), “design” (designed from the persona description), “random” (made up by the TTS engine), or a {speaker: voice} dictionary (audio path, (array, sample_rate), Voice or engine voice name).

  • voice_database – Voice database, or Hugging Face dataset name, used by voices="db" (default: the TTS engine’s default, “sdialog/voices-libritts” for Dia2).

  • voice_description – Jinja2 template over the persona fields (or function of the persona dict) describing each voice, used by voices="design".

  • tts – TTS engine: a BaseDialogTTS (default: Dia2TTS()), or a classic BaseTTS/BaseVoiceCloneTTS engine (wrapped with PerTurnTTS).

  • pauses – “natural” (the TTS engine’s own timing), a median pause in seconds (log-normal), or a (min, max) range in seconds (uniform).

  • overlap – Probability (0-1) that a turn starts before the previous one ends.

  • max_overlap – Maximum overlap, as a fraction of the previous turn’s duration (default 0.3).

  • reverb – Room reverberation: True or “small”/”medium”/”large” (simulated room of random size and positions), a Room (room of your choice: dimensions, materials or RT60, microphone and speaker positions, microphone directivity), a ButReverbDB (rooms measured in BUT ReverbDB), a path to an impulse response file or folder of files, or an impulse response array.

  • noise – Background noise: an SNR in dB, a (min, max) SNR range, a noise type (“white”, “pink”, “brown”, or “room”: the noise recorded in the measured room of reverb=ButReverbDB(...)) or audio file/folder path, or a dict {"type": ..., "snr": ...}.

  • channel – Telephone channel codec: “telephone” (= “g711”), “g711”, “g729”, “amr” or “amr-wb”.

  • level_jitter_db – Maximum random loudness difference (dB) between speakers.

  • stereo – If True, output one channel per speaker (in order of appearance); otherwise mono.

  • sample_rate – Output sample rate (Hz).

  • seed – Random seed; the same seed reproduces the same audio (a random seed is drawn and saved in the annotations when not given).

  • audio_format – Format of the audio file saved to path: “wav” (default) or “flac” (lossless, about half the size).

Returns:

A DialogAudio with the waveform and the annotations.

Raises:

ValueError – If the dialogue does not have exactly two speakers or a parameter is invalid.

sdialog.audio.synthesis.dialogs_to_audio(dialogs: Sequence, out_dir: str, devices: str | List[str] | None = None, workers_per_device: int = 1, tts_factory: Callable[[str], BaseDialogTTS] | None = None, seed: int | None = None, **kwargs) → List[dict]

Converts many dialogues to audio in parallel, with one TTS model per worker process.

Every dialogue is saved under out_dir (<dialog_id>.wav, or .flac with audio_format="flac", .json and .rttm; <dialog_id>_<position> for dialogues whose id appears more than once in dialogs) and an index.jsonl file lists all the outputs. Each dialogue gets its own seed (derived from seed and its position in dialogs, or drawn at random if seed is not given), which is saved in its annotations and in index.jsonl; results do not depend on the number of workers.

Parameters:
  • dialogs – Dialogues to convert.

  • out_dir – Output folder.

  • devices – Where to run: None (default) uses all visible GPUs, or the CPU if there is none; "cpu"; "cuda" (all GPUs); a single device like "cuda:1"; or a list of devices.

  • workers_per_device – Number of worker processes (each with its own model) per device.

  • tts_factory – Function device -> BaseDialogTTS creating each worker’s engine (default: Dia2TTS(device=device)). Must be a top-level (picklable) function when using several workers.

  • seed – Base random seed, to make the whole batch reproducible.

  • kwargs – Any other to_audio() argument (preset, voices, stereo, audio_format, …).

Returns:

The rows of index.jsonl (one per dialogue, with output paths and seed, or an “error” field).

Example:

from sdialog.audio import dialogs_to_audio

rows = dialogs_to_audio(dialogs, "audios/", preset="call_center", stereo=True)  # all available GPUs
sdialog.audio.synthesis.get_default_tts() → BaseDialogTTS

Returns the default TTS engine (Dia2), loaded once per process.

sdialog.audio.result

Result of dialog.to_audio(): the dialogue audio together with its ground-truth annotations.

class sdialog.audio.result.Segment(turn: int, speaker: str, text: str, start: float, end: float, channel: int | None = None, words: Tuple[str, float]]=<factory>)

Bases: object

Ground-truth annotation of one dialogue turn in the audio.

Variables:
  • turn – Index of the turn in the dialogue.

  • speaker – Speaker name.

  • text – Text of the turn.

  • start – Start time (seconds).

  • end – End time (seconds).

  • channel – Channel holding this speaker in stereo output (None for mono output).

  • words – Word timestamps (word, start_seconds) (absolute times), when the TTS engine provides them.

turn: int
speaker: str
text: str
start: float
end: float
channel: int | None = None
words: List[Tuple[str, float]]
property duration: float
class sdialog.audio.result.DialogAudio(audio: numpy.ndarray, sample_rate: int, segments: ~typing.List[~sdialog.audio.result.Segment], speakers: ~typing.List[str], voices: dict = <factory>, config: dict = <factory>, dialog_id: str | None = None)

Bases: object

Audio of a dialogue with its annotations, returned by dialog.to_audio().

Variables:
  • audio – Float32 waveform, shape (samples,) (mono) or (samples, channels) (stereo, one channel per speaker in dialogue speaker order).

  • sample_rate – Sample rate (Hz).

  • segments – One Segment per turn, in dialogue order.

  • speakers – Speaker names, in channel order.

  • voices – Voice used for each speaker (e.g. the voice database identifier, or “random”).

  • config – All the parameters used to generate the audio, including the values drawn at random (room, SNRs, codecs, …), for reproducibility.

  • dialog_id – Id of the source dialogue, if any.

Example:

audio = dialog.to_audio(preset="call_center", stereo=True, seed=0)
audio.save("output/call")       # output/call.wav, output/call.json, output/call.rttm
for seg in audio.segments:
    print(f"{seg.start:6.2f}-{seg.end:6.2f} {seg.speaker}: {seg.text}")
audio: numpy.ndarray
sample_rate: int
segments: List[Segment]
speakers: List[str]
voices: dict
config: dict
dialog_id: str | None = None
property duration: float

Duration of the audio in seconds.

property channels: int

Number of audio channels.

to_dict(words: bool = True) → dict

Returns the annotations (everything but the waveform) as a JSON-serializable dictionary.

to_json(indent: int = 2, words: bool = True) → str

Returns the annotations as a JSON string.

to_rttm(file_id: str | None = None) → str

Returns the speaker turns in RTTM format (speaker diarization ground truth).

save(path: str, audio_format: str = 'wav') → dict

Saves the audio and its annotations as <path>.<audio_format>, <path>.json and <path>.rttm.

Parameters:
  • path – Output path without extension (an audio extension, if given, is removed).

  • audio_format – Audio file format (“wav” or “flac”).

Returns:

The paths of the written files.

display(audio_format: str = 'mp3')

Shows an audio player (in Jupyter notebooks), with the audio normalized to full scale.

The audio is embedded in the notebook as MP3 by default, about 7 times smaller than WAV, so that notebooks saved with their outputs stay small enough to share. Saved files (save()) are not affected.

Parameters:

audio_format (str) – “mp3” (default) or “wav” (the exact samples, as before). MP3 falls back to WAV if the installed soundfile cannot write MP3 (libsndfile < 1.1).

sdialog.audio.presets

Named acoustic scene presets for dialog.to_audio(preset=...).

A preset only sets scene parameters (timing, reverberation, noise, channel and level variation); output-format parameters (stereo, sample_rate, path) are never part of a preset, so any preset can be rendered in mono or stereo. Arguments passed explicitly to to_audio override the preset values.

Per-speaker values are dictionaries keyed by speaker index (0 = first speaker of the dialogue) or by speaker name. A list of values means “pick one at random”.

Example:

from sdialog.audio import register_preset

register_preset("noisy_phone", channel="g711", noise={"type": "pink", "snr": (5, 15)}, overlap=0.2)
audio = dialog.to_audio(preset="noisy_phone", stereo=True)
sdialog.audio.presets.register_preset(name: str, **params) → None

Registers (or replaces) a named scene preset.

Parameters:
  • name – Name of the preset (used as dialog.to_audio(preset=name)).

  • params – Scene parameters; valid keys are: pauses, overlap, max_overlap, reverb, noise, channel and level_jitter_db.

Raises:

ValueError – If an invalid parameter is given (e.g. stereo, which is an output option).

sdialog.audio.presets.list_presets() → dict

Returns a copy of all registered presets.

sdialog.audio.presets.resolve_scene(preset: str | None = None, **overrides) → dict

Returns the full scene parameters: defaults, updated with the preset, updated with the explicit (non-None) overrides.

sdialog.audio.room

Room specification for the reverberation of sdialog.audio.synthesis.to_audio().

A Room describes a shoebox room (dimensions, absorption, microphone and speaker positions, microphone directivity) and computes the impulse response from each speaker to the microphone with pyroomacoustics (image source method), installed with sdialog[audio], so no other dependency is needed. Pass it as reverb to dialog.to_audio(); anything not given (e.g. the speaker positions) is drawn at random from the to_audio seed.

Example:

from sdialog.audio import Room

room = Room(dimensions=(6, 4, 3),                     # width (x), length (y), height (z) in meters
            rt60=0.5,                                 # or materials={"walls": "brickwork", ...}
            mic="between_speakers",
            mic_pattern="cardioid", mic_direction="Alice",
            speakers={"Alice": (2, 1.5, 1.2), "Bob": (4, 2.5, 1.6)})
audio = dialog.to_audio(reverb=room)

# Each speaker in their own room (e.g. both ends of a phone call)
audio = dialog.to_audio(reverb={"Alice": Room(dimensions=(3, 3, 2.5)),
                                "Bob": Room(dimensions=(10, 8, 4), rt60=1.0)},
                        channel="g711")
class sdialog.audio.room.Room(*, dimensions: ~typing.Tuple[float, float, float], rt60: float | None = None, materials: str | float | ~typing.Dict[str, str | float] | None = None, mic: ~typing.Tuple[float, float, float] | int | str = 'ceiling', mic_pattern: str = 'omni', mic_direction: ~typing.Tuple[float, float] | int | str | None = None, speakers: ~typing.Dict[int | str, ~typing.Tuple[float, float, float]] = <factory>, max_order: int | None = None, air_absorption: bool = False, ray_tracing: bool = False)

Bases: BaseModel

A shoebox room used to simulate the reverberation of sdialog.audio.synthesis.to_audio() (dialog.to_audio(reverb=Room(...))).

The absorption is given either as a target rt60 or as materials (default: wooden walls, carpet and an absorbing ceiling). Speakers without a position are placed at random (mouth height, at least 0.5 m from the microphone and from each other).

Variables:
  • dimensions (Tuple[float, float, float]) – Width (x), length (y) and height (z) of the room, in meters.

  • rt60 (Optional[float]) – Target reverberation time in seconds (absorption computed with Sabine’s formula).

  • materials (Optional[Union[str, float, Dict[str, Union[str, float]]]]) – Surface materials: a pyroomacoustics material name (e.g. “brickwork”, “plasterboard”) or energy absorption coefficient for all surfaces, or a dictionary by surface (“walls”, “floor”, “ceiling”, or a single wall: “east”, “west”, “north”, “south”).

  • mic (Union[str, int, Tuple[float, float, float]]) – Microphone position: (x, y, z) coordinates, “ceiling” (center of the ceiling), “wall” (middle of the west wall, at standing height), “between_speakers” (midpoint between the speakers), or a speaker name or index (a lapel microphone on that speaker’s chest).

  • mic_pattern (str) – Microphone directivity: “omni”, “cardioid”, “subcardioid”, “hypercardioid” or “figure8”.

  • mic_direction (Optional[Union[str, int, Tuple[float, float]]]) – Where a directional microphone points: a speaker name or index, “speakers” (the midpoint between the speakers, the default; up for the “between_speakers” microphone, right below it), or (azimuth, colatitude) in degrees (azimuth from the x axis; colatitude from the z axis, 90 = horizontal).

  • speakers (Dict[Union[int, str], Tuple[float, float, float]]) – Speaker positions (x, y, z), by speaker name or index (0 = first speaker of the dialogue).

  • max_order (Optional[int]) – Maximum reflection order of the image source method (default: from the RT60, up to 30, or 17 with materials).

  • air_absorption (bool) – Whether to simulate air absorption.

  • ray_tracing (bool) – Whether to add ray tracing to the image source method (more realistic late reverberation, slower).

Example:

from sdialog.audio import Room

room = Room(dimensions=(5, 4, 2.8), materials={"walls": "plasterboard", "floor": "linoleum_on_concrete"},
            mic=(2.5, 2, 0.8), speakers={0: (1.5, 2, 1.2), 1: (3.5, 2, 1.2)})
audio = dialog.to_audio(reverb=room, seed=0)
audio.config["room"]  # the simulated room (positions included)

rirs, info = room.compute_rirs(["Alice", "Bob"], sample_rate=16000)  # the impulse responses only
dimensions: Tuple[float, float, float]
rt60: float | None
materials: str | float | Dict[str, str | float] | None
mic: Tuple[float, float, float] | int | str
mic_pattern: str
mic_direction: Tuple[float, float] | int | str | None
speakers: Dict[int | str, Tuple[float, float, float]]
max_order: int | None
air_absorption: bool
ray_tracing: bool
compute_rirs(speakers: List[str], sample_rate: int, rng: numpy.random.Generator | None = None) → Tuple[List[numpy.ndarray], dict]

Simulates the room and computes the impulse response from each speaker to the microphone.

Parameters:
  • speakers (List[str]) – Names of the speakers to place, in order (positions given by index refer to this list).

  • sample_rate (int) – Sample rate of the returned impulse responses.

  • rng (Optional[np.random.Generator]) – Random generator used to place the speakers without a given position.

Returns:

The impulse response of each speaker, and a dictionary describing the simulated room (dimensions, absorption, microphone and speaker positions).

Return type:

Tuple[List[np.ndarray], dict]

Raises:

ValueError – If the RT60 cannot be reached in the room or a speaker name is not valid.

Example:

rirs, info = Room(dimensions=(6, 4, 3), rt60=0.6).compute_rirs(["Alice", "Bob"], 16000)

sdialog.audio.but

Measured rooms from the BUT ReverbDB database for the reverberation of sdialog.audio.synthesis.to_audio().

BUT ReverbDB (Brno University of Technology) contains impulse responses measured in 9 real rooms (offices, meeting and lecture rooms, hotel rooms), from several loudspeaker positions to 31 microphones, together with recordings of each room’s own background noise at every microphone. SDialog does not include the database: ButReverbDB(path, download=True) downloads BUT_ReverbDB_rel_19_06_RIR-Only.tgz (8.7 GB, CC BY 4.0) from its website and extracts it into path the first time. It can also be downloaded by hand and extracted into a folder of its own (the archive has no top folder), then given as path:

wget http://merlin.fit.vutbr.cz/ReverbDB/BUT_ReverbDB_rel_19_06_RIR-Only.tgz
mkdir BUT_ReverbDB && tar xzf BUT_ReverbDB_rel_19_06_RIR-Only.tgz -C BUT_ReverbDB

Please cite it when publishing results obtained with it:

I. Szöke, M. Skácel, L. Mošner, J. Paliesek and J. Černocký, “Building and Evaluation of a Real Room Impulse Response Dataset”, IEEE Journal of Selected Topics in Signal Processing, 13(4), 863-876, 2019.

Example:

from sdialog.audio import ButReverbDB

but = ButReverbDB("BUT_ReverbDB", download=True)         # or rooms=["VUT_FIT_L207", ...]
audio = dialog.to_audio(reverb=but, noise="room")        # both speakers in the same measured room,
                                                         # with that room's own background noise
# Only the caller in a measured room (e.g. a phone call), with its room noise at 10-20 dB SNR
audio = dialog.to_audio(reverb={"Caller": but},
                        noise={"Caller": {"type": "room", "snr": (10, 20)}},
                        channel="g711")
class sdialog.audio.but.ButReverbDB(path: str, rooms: List[str] | None = None, download: bool = False)

Bases: object

Impulse responses and background noise measured in real rooms (BUT ReverbDB), to use as reverb in dialog.to_audio().

For each dialogue, a room and a microphone are drawn at random (from the to_audio seed), and each speaker gets a different loudspeaker position in that room, so both speakers are recorded by the same microphone. Given per speaker (e.g. reverb={"Caller": but}), each speaker gets a position of their own. With noise="room", the background noise is the one recorded by the same microphone, in the same room.

Parameters:
  • path (str) – Path to the extracted BUT ReverbDB (the folder containing the room folders, e.g. VUT_FIT_L207).

  • rooms (Optional[List[str]]) – Names of the rooms to use (default: all of them, see rooms).

  • download (bool) – If True and path does not exist, downloads the database (8.7 GB) and extracts it there.

Raises:
  • FileNotFoundError – If no impulse responses with the BUT ReverbDB layout are found under path.

  • ValueError – If a room in rooms is not in the database.

Example:

from sdialog.audio import ButReverbDB

but = ButReverbDB("BUT_ReverbDB", rooms=["VUT_FIT_L207", "VUT_FIT_Q301"], download=True)
print(but.rooms)
audio = dialog.to_audio(reverb=but, noise="room", seed=0)
audio.config["room"]   # room, microphone, positions and files used
static download(path: str, url: str = 'http://merlin.fit.vutbr.cz/ReverbDB/BUT_ReverbDB_rel_19_06_RIR-Only.tgz') → str

Downloads BUT ReverbDB (RIR-only release, 8.7 GB) and extracts it into path. The archive is removed once extracted; an interrupted download or extraction leaves only .part files, so path exists only when complete.

Parameters:
  • path (str) – Folder to extract the database into (must not exist yet).

  • url (str) – Address of the archive.

Returns:

path.

Return type:

str

property rooms: List[str]

Names of the rooms in use.

json() → dict

Returns a JSON-serializable description (stored in the audio annotations).

compute_rirs(n_sources: int, sample_rate: int, rng: numpy.random.Generator | None = None) → Tuple[List[numpy.ndarray], dict]

Draws a room and a microphone, and loads the impulse response of n_sources different loudspeaker positions in that room (positions are reused only if the room has fewer than n_sources).

Parameters:
  • n_sources (int) – Number of speakers to place.

  • sample_rate (int) – Sample rate of the returned impulse responses.

  • rng (Optional[np.random.Generator]) – Random generator (default: a new unseeded one).

Returns:

The impulse responses (one per speaker) and a description of the room and files used.

Return type:

Tuple[List[np.ndarray], dict]

sdialog.audio.effects

Signal-level audio effects used by sdialog.audio.synthesis.to_audio().

Every function here works on in-memory mono np.ndarray signals and is free of side effects (no files are written), so effects can be freely combined and run in parallel. Randomized effects take an explicit np.random.Generator for reproducibility.

Example:

import numpy as np
from sdialog.audio import effects

rng = np.random.default_rng(0)
x = effects.set_active_level(speech, sr=16000, target_db=-26)
rirs, room = effects.simulate_rirs(rng, sr=16000, size="medium", n_sources=2)
x = effects.apply_rir(x, rirs[0], sr=16000)
x, snr = effects.add_noise(x, sr=16000, rng=rng, snr_db=20, kind="pink")
x = effects.telephone(x, sr=16000, codec="g711")
sdialog.audio.effects.resample(x: numpy.ndarray, sr_in: int, sr_out: int) → numpy.ndarray

Resamples a signal with a polyphase filter (scipy.signal.resample_poly).

sdialog.audio.effects.to_mono(x: numpy.ndarray) → numpy.ndarray

Converts a (samples,) or (samples, channels) signal to mono float32.

sdialog.audio.effects.load_audio(path: str, sr: int) → numpy.ndarray

Loads an audio file as mono float32 at sample rate sr.

sdialog.audio.effects.list_audio_files(path: str) → List[str]

Returns [path] if it is a file, or the sorted list of audio files found (recursively) under it.

sdialog.audio.effects.active_level_db(x: numpy.ndarray, sr: int, rel_db: float = 35.0) → float

Simplified active speech level (dBFS): mean power of the frames within rel_db of the loudest one.

Unlike plain RMS, it is not affected by the amount of silence in the signal.

sdialog.audio.effects.set_active_level(x: numpy.ndarray, sr: int, target_db: float = -26.0) → numpy.ndarray

Scales x so that its active speech level is target_db dBFS.

sdialog.audio.effects.trim_silence(x: numpy.ndarray, sr: int, top_db: float = 40.0, pad: float = 0.05) → Tuple[numpy.ndarray, int]

Trims leading and trailing frames more than top_db below the loudest frame.

Returns:

The trimmed signal and the number of samples removed at the beginning.

sdialog.audio.effects.soft_limit(x: numpy.ndarray, threshold: float = 0.9) → numpy.ndarray

Sample-wise soft clipper: samples above threshold are smoothly compressed below 1.0.

sdialog.audio.effects.simulate_rirs(rng: numpy.random.Generator, sr: int, size: str = 'medium', n_sources: int = 2) → Tuple[List[numpy.ndarray], dict]

Simulates the impulse responses from n_sources speaker positions to one microphone in a random shoebox room, using pyroomacoustics (image source method).

Parameters:
  • rng – Random generator used to draw the room, RT60 and positions.

  • sr – Sample rate of the returned impulse responses.

  • size – Room size preset: “small”, “medium” or “large”.

  • n_sources – Number of speaker positions (one impulse response each).

Returns:

The list of impulse responses and a dictionary describing the simulated room.

sdialog.audio.effects.load_rir(path: str, rng: numpy.random.Generator, sr: int) → Tuple[numpy.ndarray, str]

Loads a random impulse response from path (an audio file or a folder of them).

sdialog.audio.effects.apply_rir(x: numpy.ndarray, rir: numpy.ndarray, sr: int) → numpy.ndarray

Convolves x with the impulse response rir.

The impulse response is first aligned on its direct path (the delay before it is removed) so that speech onsets do not move and time annotations stay valid. The output keeps the reverberation tail (it is longer than x) and is re-leveled to the RMS of the input.

sdialog.audio.effects.colored_noise(n: int, rng: numpy.random.Generator, kind: str = 'white') → numpy.ndarray

Generates n samples of unit-RMS “white”, “pink” (1/f) or “brown” (1/f^2) noise.

sdialog.audio.effects.noise_from_files(path: str, n: int, sr: int, rng: numpy.random.Generator) → Tuple[numpy.ndarray, str]

Builds n samples of unit-RMS noise from a random file under path, looped from a random offset.

sdialog.audio.effects.add_noise(x: numpy.ndarray, sr: int, rng: numpy.random.Generator, snr_db: float | Tuple[float, float] = 20.0, kind: str = 'white', speech_level_db: float | None = None) → Tuple[numpy.ndarray, dict]

Adds background noise to x at the given signal-to-noise ratio.

Parameters:
  • snr_db – SNR in dB, or a (min, max) range to draw it from. The signal level is the active speech level of x (so pauses do not lower it).

  • kind – “white”, “pink”, “brown”, or a path to a noise audio file/folder.

  • speech_level_db – Reference speech level; defaults to the active level of x.

Returns:

The noisy signal and a dictionary describing the noise that was added.

sdialog.audio.effects.telephone(x: numpy.ndarray, sr: int, codec: str = 'g711') → numpy.ndarray

Simulates a telephone channel: band-pass filtering, narrowband resampling and mu-law companding with the codec’s quantization (a coarse approximation of the codec’s distortion).

Parameters:

codec – “g711” (alias “telephone”), “g729”, “amr” or “amr-wb”.

Returns:

The processed signal at the original sample rate sr.

sdialog.audio.timeline

Turn placement (pauses and overlapping speech) for sdialog.audio.synthesis.to_audio().

sdialog.audio.timeline.validate_pauses(pauses: str | float | Tuple[float, float]) → str | float | Tuple[float, float]

Checks the pauses argument; raises ValueError if it is invalid.

sdialog.audio.timeline.sample_pause(rng: numpy.random.Generator, pauses: str | float | Tuple[float, float]) → float

Draws a pause duration (seconds) from a median (log-normal) or a (min, max) range (uniform).

sdialog.audio.timeline.place_turns(speakers: List[int], durations: List[float], rng: numpy.random.Generator, pauses: str | float | Tuple[float, float] = 'natural', overlap: float = 0.0, max_overlap: float = 0.3, windows: List[int] | None = None, natural_starts: List[float] | None = None, lead_in: float = 0.3) → Tuple[List[float], List[float]]

Computes the start time of every turn.

Parameters:
  • speakers – Speaker index of each turn.

  • durations – Duration (seconds) of each turn’s audio.

  • rng – Random generator.

  • pauses – “natural” keeps the timing of turns generated together (same window) and draws the other pauses around 0.4 s; a number is the median of log-normal pauses; a (min, max) tuple draws pauses uniformly.

  • overlap – Probability that a turn starts before the previous one ends.

  • max_overlap – Maximum overlap, as a fraction of the previous turn’s duration.

  • windows – Generation window of each turn (needed for “natural” pauses).

  • natural_starts – Start time of each turn within its window (needed for “natural” pauses).

  • lead_in – Silence (seconds) before the first turn.

Returns:

The start time of each turn, and the gap (seconds, negative for overlaps) before each turn.

sdialog.audio.voices

Voice selection for dialog.to_audio(voices=...).

Voices can be:

  • "db": picked from a voice database to match each speaker’s persona (gender, age, language).

  • "design": designed from each speaker’s persona description with Qwen3-TTS VoiceDesign.

  • "random": made up by the TTS engine (a different voice on every generation unless seeded).

  • A dictionary {speaker: voice} with explicit voices (speaker name or index as key), where a voice is an audio path, an (array, sample_rate) tuple, a Voice, or an engine voice name.

sdialog.audio.voices.normalize_age(age: Any, rng: numpy.random.Generator) → int

Converts a persona age (number, “35”, “30s”, “middle-aged”, “”, None, …) to an integer age.

sdialog.audio.voices.normalize_gender(gender: Any, rng: numpy.random.Generator) → str

Converts a persona gender to “male” or “female” (random if unknown).

sdialog.audio.voices.get_voice_database(name_or_db: str | BaseVoiceDatabase) → BaseVoiceDatabase

Returns a voice database, loading (once per process) Hugging Face databases given by name.

sdialog.audio.voices.resolve_voices(speakers: List[str], personas: Dict[str, dict], turns: List[Tuple[int, str]], voices: str | dict, tts, rng: numpy.random.Generator, voice_database: str | BaseVoiceDatabase | None = None, voice_description: str | Callable | None = None) → Tuple[List[Any], Dict[str, dict]]

Resolves the voice of every speaker.

Parameters:
  • speakers – Speaker names, indexed as in turns.

  • personas – Persona dictionary of each speaker (may be missing or incomplete).

  • turns – The (speaker_index, text) turns (used as reference text by “design”).

  • voices – “db”, “design”, “random”, or an explicit {speaker: voice} dictionary (speakers missing from the dictionary get a “db” voice, or a random one if the engine supports it).

  • tts – The BaseDialogTTS engine that will use the voices.

  • rng – Random generator.

  • voice_database – Voice database (or Hugging Face dataset name) for “db” voices.

  • voice_description – Jinja2 template (or function of the persona dict) describing the voice for “design”.

Returns:

The voice of each speaker (None = random) and a description of each speaker’s voice.

sdialog.audio.tts.dialog_tts

Dialogue-level text-to-speech interface used by sdialog.audio.synthesis.to_audio().

A dialogue TTS engine receives all the turns of a dialogue at once (so engines designed for dialogues, like Dia2, can model turn-taking and prosody across turns) and returns one audio clip per turn.

Example:

from sdialog.audio.tts import KokoroTTS, PerTurnTTS

# Use any classic (one utterance at a time) TTS engine with dialog.to_audio()
audio = dialog.to_audio(tts=PerTurnTTS(KokoroTTS()))
class sdialog.audio.tts.dialog_tts.TurnAudio(audio: numpy.ndarray, sample_rate: int, window: int = 0, offset: float = 0.0, words: Tuple[str, float]]=<factory>)

Bases: object

Audio generated for one dialogue turn.

Variables:
  • audio – Mono float32 waveform.

  • sample_rate – Sample rate of audio.

  • window – Index of the generation call that produced this turn; turns generated together share the same window and keep the engine’s own timing between them.

  • offset – Start time (in seconds) of this clip within its window.

  • words – Optional word timestamps (word, start_seconds) relative to the start of audio.

audio: numpy.ndarray
sample_rate: int
window: int = 0
offset: float = 0.0
words: List[Tuple[str, float]]
class sdialog.audio.tts.dialog_tts.BaseDialogTTS

Bases: ABC

Abstract base class for dialogue-level text-to-speech engines.

Subclasses implement synthesize(), which receives the whole dialogue and returns one TurnAudio per turn.

Variables:
  • supports_random_voices – True if the engine can make up voices when no reference voice is given.

  • supports_reference_audio – True if voices can be given as reference audio (path or (array, sr)).

  • default_voice_database – Hugging Face voice database used by voices="db" when none is given.

supports_random_voices: bool = False
supports_reference_audio: bool = False
default_voice_database: str | None = 'sdialog/voices-libritts'
abstractmethod synthesize(turns: List[Tuple[int, str]], voices: List[Any], seed: int | None = None) → List[TurnAudio]

Generates the audio of every turn of a dialogue.

Parameters:
  • turns – List of (speaker_index, text) pairs, in dialogue order.

  • voices – Voice of each speaker (indexed by speaker_index); None lets the engine choose (random voice), otherwise an engine-specific voice (e.g. a reference audio path, an (array, sample_rate) tuple, or a voice name).

  • seed – Random seed for reproducible generation.

Returns:

One TurnAudio per turn, in the same order as turns.

json() → dict

Returns a serializable description of the engine configuration.

class sdialog.audio.tts.dialog_tts.PerTurnTTS(engine, tts_kwargs: dict | None = None)

Bases: BaseDialogTTS

Adapter to use a classic, one-utterance-at-a-time TTS engine (BaseTTS or BaseVoiceCloneTTS, e.g. KokoroTTS or Qwen3TTSVoiceClone) with dialog.to_audio().

Each turn is generated independently, so there is no prosodic continuity between turns.

Parameters:
  • engine – The TTS engine to wrap.

  • tts_kwargs – Extra keyword arguments passed to the engine’s generate method.

supports_random_voices: bool = False
synthesize(turns, voices, seed=None)

Generates the audio of every turn of a dialogue.

Parameters:
  • turns – List of (speaker_index, text) pairs, in dialogue order.

  • voices – Voice of each speaker (indexed by speaker_index); None lets the engine choose (random voice), otherwise an engine-specific voice (e.g. a reference audio path, an (array, sample_rate) tuple, or a voice name).

  • seed – Random seed for reproducible generation.

Returns:

One TurnAudio per turn, in the same order as turns.

json()

Returns a serializable description of the engine configuration.

sdialog.audio.tts.dia2.tts

Dia2 dialogue text-to-speech engine (https://github.com/nari-labs/dia2), the default engine of dialog.to_audio().

Dia2 generates a whole two-speaker conversation in a single pass (natural turn-taking and prosody), optionally conditioned on a reference audio (“prefix”) per speaker, and returns word timestamps.

Example:

from sdialog.audio.tts import Dia2TTS

tts = Dia2TTS("nari-labs/Dia2-2B", device="cuda")
audio = dialog.to_audio(tts=tts, voices="random", seed=0)
sdialog.audio.tts.dia2.tts.check_python_version()

Raises a RuntimeError with a helpful message if the Python version cannot run Dia2.

sdialog.audio.tts.dia2.tts.clean_text(text: str) → str

Prepares a turn text for Dia2: removes speaker tags and newlines.

sdialog.audio.tts.dia2.tts.count_words(text: str) → int

Number of words Dia2 timestamps for text (mirrors the tokenization of its script parser).

class sdialog.audio.tts.dia2.tts.Dia2TTS(model: str = 'nari-labs/Dia2-2B', device: str | None = None, dtype: str = 'auto', cfg_scale: float = 2.0, text_temperature: float = 0.6, audio_temperature: float = 0.8, top_k: int = 50, max_window_words: int = 170, reference_seconds: float = 8.0, use_cuda_graph: bool = True, whisper_model: str = 'openai/whisper-large-v3')

Bases: BaseDialogTTS

Dia2 dialogue TTS engine.

Consecutive turns are generated together in windows of up to max_window_words words (Dia2 can generate up to ~2 minutes per call) and each window is cut into turns using Dia2’s word timestamps. If the timestamps do not match the script, the window is regenerated one turn at a time.

Voices: each speaker can be conditioned on a reference audio (a path or an (array, sample_rate) tuple). Speakers without a reference get a random voice, which is then reused as reference for the following windows so that it stays the same across the whole dialogue.

Parameters:
  • model – Hugging Face repository of the Dia2 model (“nari-labs/Dia2-2B” or “nari-labs/Dia2-1B”).

  • device – Torch device; defaults to “cuda” if available, otherwise “cpu” (very slow).

  • dtype – “auto” (bfloat16 on GPU, float32 on CPU), “bfloat16” or “float32”.

  • cfg_scale – Classifier-free guidance scale (1.0 disables guidance).

  • text_temperature – Sampling temperature of the text stream.

  • audio_temperature – Sampling temperature of the audio stream.

  • top_k – Top-k sampling for both streams.

  • max_window_words – Maximum number of words generated in a single Dia2 call.

  • reference_seconds – Maximum length of reference voice audio, given as an array or a file (longer references are cut).

  • use_cuda_graph – Use CUDA graphs to speed up generation (GPU only).

  • whisper_model – Whisper model used by Dia2 to align the reference voices.

supports_random_voices: bool = True
supports_reference_audio: bool = True
synthesize(turns, voices, seed=None)

Generates the audio of every turn of a dialogue.

Parameters:
  • turns – List of (speaker_index, text) pairs, in dialogue order.

  • voices – Voice of each speaker (indexed by speaker_index); None lets the engine choose (random voice), otherwise an engine-specific voice (e.g. a reference audio path, an (array, sample_rate) tuple, or a voice name).

  • seed – Random seed for reproducible generation.

Returns:

One TurnAudio per turn, in the same order as turns.

json()

Returns a serializable description of the engine configuration.

sdialog.audio.tts

class sdialog.audio.tts.BaseTTS

Bases: ABC

Abstract base class for text-to-speech (TTS) engines.

This class defines the interface that all TTS engine implementations must follow. It provides a common structure for initializing TTS pipelines and generating audio from text input with specified voice characteristics.

Subclasses must implement the generate() method to provide the actual TTS functionality. The pipeline attribute should be initialized in the subclass constructor with the appropriate TTS model or pipeline.

Key Features:

  • Abstract interface for TTS engine implementations

  • Common initialization pattern for TTS pipelines

  • Standardized audio generation interface

  • Support for voice-specific audio generation

Variables:

pipeline (Any) – The TTS pipeline or model instance (initialized by subclasses).

abstractmethod generate(text: str, speaker_voice: str, tts_pipeline_kwargs: dict = {}) → tuple[numpy.ndarray, int]

Generates audio from text using the specified voice.

This abstract method must be implemented by all TTS engine subclasses. It should convert the input text to audio using the specified voice and return both the audio data and sampling rate.

Parameters:
  • text (str) – The text to be converted to speech.

  • speaker_voice (str) – The voice identifier to use for speech generation.

  • tts_pipeline_kwargs (dict) – Additional keyword arguments to be passed to the TTS pipeline.

Returns:

A tuple containing the audio data as a numpy array and the sampling rate.

Return type:

tuple[np.ndarray, int]

Raises:

NotImplementedError – If not implemented by subclass.

class sdialog.audio.tts.BaseVoiceCloneTTS

Bases: ABC

Abstract base class for voice-cloning text-to-speech (TTS) engines.

This class extends the standard TTS interface to support voice cloning, where the speaker can be defined by a reference audio path or a model- specific prompt object. Subclasses must implement the generate() method.

Variables:

pipeline (Any) – The TTS pipeline or model instance (initialized by subclasses).

abstractmethod generate(text: str, speaker_voice: Any = None, tts_pipeline_kwargs: dict = {}) → tuple[numpy.ndarray, int]

Generates audio from text using voice cloning.

Subclasses must accept speaker_voice as either a path to reference audio, a model-specific prompt object, or None for a default voice.

Parameters:
  • text (str) – The text to be converted to speech.

  • speaker_voice (Any) – Reference audio path, prompt object, or None.

  • tts_pipeline_kwargs (dict) – Additional keyword arguments passed to the TTS pipeline.

Returns:

A tuple containing the audio data as a numpy array and the sampling rate.

Return type:

tuple[np.ndarray, int]

Raises:

NotImplementedError – If not implemented by subclass.

class sdialog.audio.tts.BaseDialogTTS

Bases: ABC

Abstract base class for dialogue-level text-to-speech engines.

Subclasses implement synthesize(), which receives the whole dialogue and returns one TurnAudio per turn.

Variables:
  • supports_random_voices – True if the engine can make up voices when no reference voice is given.

  • supports_reference_audio – True if voices can be given as reference audio (path or (array, sr)).

  • default_voice_database – Hugging Face voice database used by voices="db" when none is given.

supports_random_voices: bool = False
supports_reference_audio: bool = False
default_voice_database: str | None = 'sdialog/voices-libritts'
abstractmethod synthesize(turns: List[Tuple[int, str]], voices: List[Any], seed: int | None = None) → List[TurnAudio]

Generates the audio of every turn of a dialogue.

Parameters:
  • turns – List of (speaker_index, text) pairs, in dialogue order.

  • voices – Voice of each speaker (indexed by speaker_index); None lets the engine choose (random voice), otherwise an engine-specific voice (e.g. a reference audio path, an (array, sample_rate) tuple, or a voice name).

  • seed – Random seed for reproducible generation.

Returns:

One TurnAudio per turn, in the same order as turns.

json() → dict

Returns a serializable description of the engine configuration.

class sdialog.audio.tts.PerTurnTTS(engine, tts_kwargs: dict | None = None)

Bases: BaseDialogTTS

Adapter to use a classic, one-utterance-at-a-time TTS engine (BaseTTS or BaseVoiceCloneTTS, e.g. KokoroTTS or Qwen3TTSVoiceClone) with dialog.to_audio().

Each turn is generated independently, so there is no prosodic continuity between turns.

Parameters:
  • engine – The TTS engine to wrap.

  • tts_kwargs – Extra keyword arguments passed to the engine’s generate method.

supports_random_voices: bool = False
synthesize(turns, voices, seed=None)

Generates the audio of every turn of a dialogue.

Parameters:
  • turns – List of (speaker_index, text) pairs, in dialogue order.

  • voices – Voice of each speaker (indexed by speaker_index); None lets the engine choose (random voice), otherwise an engine-specific voice (e.g. a reference audio path, an (array, sample_rate) tuple, or a voice name).

  • seed – Random seed for reproducible generation.

Returns:

One TurnAudio per turn, in the same order as turns.

json()

Returns a serializable description of the engine configuration.

class sdialog.audio.tts.TurnAudio(audio: numpy.ndarray, sample_rate: int, window: int = 0, offset: float = 0.0, words: Tuple[str, float]]=<factory>)

Bases: object

Audio generated for one dialogue turn.

Variables:
  • audio – Mono float32 waveform.

  • sample_rate – Sample rate of audio.

  • window – Index of the generation call that produced this turn; turns generated together share the same window and keep the engine’s own timing between them.

  • offset – Start time (in seconds) of this clip within its window.

  • words – Optional word timestamps (word, start_seconds) relative to the start of audio.

audio: numpy.ndarray
sample_rate: int
window: int = 0
offset: float = 0.0
words: List[Tuple[str, float]]

sdialog.audio.voice_database

This module provides comprehensive voice database management for the sdialog library.

The module includes a base voice database class and multiple implementations for different data sources, enabling flexible voice selection and management for text-to-speech generation with support for multiple languages and speaker characteristics.

Key Components:

  • BaseVoiceDatabase: Abstract base class for voice database implementations

  • Voice: Data model for individual voice entries with metadata

  • HuggingfaceVoiceDatabase: Implementation using Hugging Face datasets

  • LocalVoiceDatabase: Implementation using local audio files and metadata

  • VoiceDatabase: Implementation using in-memory voice data

Voice Database Features:

  • Multi-language voice support with automatic language detection

  • Speaker characteristics (gender, age, language) for voice selection

  • Voice usage tracking to prevent duplicates (optional)

  • Comprehensive statistics and reporting

  • Support for various data sources (Hugging Face, local files, in-memory)

  • Flexible voice selection based on persona characteristics

Example:

from sdialog.audio import HuggingfaceVoiceDatabase, LocalVoiceDatabase

# Initialize with Hugging Face dataset
voice_db = HuggingfaceVoiceDatabase("sdialog/voices-libritts")

# Get voice based on speaker characteristics
voice = voice_db.get_voice(gender="female", age=25, lang="english", seed=42)

# Initialize with local files
local_db = LocalVoiceDatabase(
    directory_audios="voices/",
    metadata_file="voices/metadata.csv"
)

# Get statistics
stats = voice_db.get_statistics(pretty=True)
print(stats)
sdialog.audio.voice_database.is_a_audio_file(file: str) → bool

Checks if a file is an audio file based on its extension.

This utility function determines whether a given file path corresponds to an audio file by checking for common audio file extensions. The check is case-insensitive and supports various audio formats.

Supported audio formats:
  • WAV (.wav)

  • MP3 (.mp3)

  • M4A (.m4a)

  • OGG (.ogg)

  • FLAC (.flac)

  • AIFF (.aiff, .aif)

  • AAC (.aac)

Parameters:

file (str) – The file path to check.

Returns:

True if the file has an audio extension, False otherwise.

Return type:

bool

class sdialog.audio.voice_database.Voice(*, gender: str = '', age: int = 0, identifier: str = '', voice: Any, language: str = 'english', language_code: str = 'a')

Bases: BaseModel

Data model representing a voice entry in the voice database.

The Voice class encapsulates all metadata associated with a specific voice, including speaker characteristics, language information, and voice identifiers. This model is used throughout the voice database system for voice selection and management.

Key Attributes:

  • gender: Speaker gender for voice selection

  • age: Speaker age for voice selection

  • identifier: Unique identifier for the voice

  • voice: Voice data (file path or voice string identifier)

  • language: Human-readable language name

  • language_code: Language code for TTS engines

Variables:
  • gender (str) – Speaker gender (e.g., “male”, “female”).

  • age (int) – Speaker age in years.

  • identifier (str) – Unique identifier for this voice entry.

  • voice (str) – Voice data - can be a file path or voice string identifier.

  • language (str) – Human-readable language name (default: “english”).

  • language_code (str) – Language code for TTS engines (default: “a”).

gender: str
age: int
identifier: str
voice: Any
language: str
language_code: str
class sdialog.audio.voice_database.BaseVoiceDatabase

Bases: object

Abstract base class for voice database implementations.

This class provides the foundation for voice database implementations, defining the common interface and data structures used across different voice database types. It manages voice data organization, usage tracking, and provides utility methods for voice selection and statistics.

Key Features:

  • Hierarchical voice organization by language, gender, and age

  • Voice usage tracking to prevent duplicates (optional)

  • Comprehensive statistics and reporting capabilities

  • Abstract interface for different data source implementations

  • Flexible voice selection based on speaker characteristics

Data Structure:

The voice database uses a nested dictionary structure: _data[language][(gender, age)] = [Voice1, Voice2, …]

Variables:
  • _data (dict[str, dict[tuple[str, int], List[Voice]]]) – Nested dictionary organizing voices by language, gender, and age.

  • _used_voices (dict[str, List[str]]) – Dictionary tracking used voice identifiers by language.

get_data() → dict

Retrieves the complete voice database data structure.

Returns:

The nested dictionary containing all voice data organized by language, gender, and age.

Return type:

dict[str, dict[tuple[str, int], List[Voice]]]

populate() → dict

Populates the voice database with voice data.

This abstract method must be implemented by subclasses to load voice data from their specific data source (e.g., Hugging Face datasets, local files, in-memory data).

Returns:

The populated voice data dictionary.

Return type:

dict

Raises:

NotImplementedError – If not implemented by subclass.

reset_used_voices()

Resets the tracking of used voices across all languages.

This method clears the usage tracking, allowing all voices to be available for selection again. Useful for starting a new dialogue generation session or resetting voice allocation.

get_statistics(pretty: bool = False, pretty_format: str = 'markdown') → dict | str

Generates comprehensive statistics about the voice database.

This method analyzes the voice database and provides detailed statistics about the available voices, including language distribution, gender/age breakdowns, and usage patterns. The statistics can be returned as either a structured dictionary or a formatted string for display.

Statistics include:
  • num_languages: Total number of languages in the database

  • overall: Global statistics (total voices, gender distribution, age distribution)

  • languages: Per-language detailed statistics including:
    • total: Total voices for the language

    • by_gender: Voice count by gender (male/female)

    • ages: Voice count by age bins

    • by_gender_age: Cross-tabulation of gender and age

    • unique_speakers: Number of unique voice identifiers

    • language_codes: Observed language codes for TTS engines

    • age_stats: Age statistics (min, max, mean)

Parameters:
  • pretty (bool) – If True, returns a formatted string; if False, returns a dictionary.

  • pretty_format (str) – Format for pretty output - “markdown” for Markdown tables, other values for fancy grid format.

Returns:

Either a dictionary with statistics or a formatted string representation.

Return type:

Union[dict, str]

add_voice(gender: str, age: int, identifier: str, voice: str, lang: str, language_code: str)

Adds a voice entry to the database.

This method creates a new Voice object and adds it to the appropriate location in the hierarchical database structure based on language, gender, and age. The voice is organized for efficient retrieval during voice selection.

Parameters:
  • gender (str) – Speaker gender (e.g., “male”, “female”).

  • age (int) – Speaker age in years.

  • identifier (str) – Unique identifier for this voice entry.

  • voice (str) – Voice data - can be a file path or voice string identifier.

  • lang (str) – Language name (e.g., “english”, “french”).

  • language_code (str) – Language code for TTS engines (e.g., “a”, “f”).

get_voice_by_identifier(identifier: str, lang: str, keep_duplicate: bool = True) → Voice

Retrieves a voice by its unique identifier.

This method searches for a voice with the specified identifier within the given language. It can optionally enforce uniqueness by preventing the reuse of already used voices.

Parameters:
  • identifier (str) – The unique identifier of the voice to retrieve.

  • lang (str) – The language to search within.

  • keep_duplicate (bool) – If True, allows returning voices that have already been used. If False, raises an error if the voice has already been used.

Returns:

The Voice object with the specified identifier.

Return type:

Voice

Raises:
  • ValueError – If the language is not found in the database.

  • ValueError – If the voice identifier is not found.

  • ValueError – If keep_duplicate is False and the voice has already been used.

get_voice(gender: str, age: int, lang: str = 'english', keep_duplicate: bool = False, seed: int = None) → Voice

Retrieves a voice based on speaker characteristics with intelligent matching.

This method selects a voice from the database based on the specified speaker characteristics (gender, age, language). It uses intelligent matching to find the closest available voice when an exact match is not available, and can optionally enforce uniqueness to prevent voice reuse.

Voice selection process: 1. Normalize language and gender parameters 2. Check for exact match (gender, age, language) 3. If no exact match, find closest age for the specified gender 4. Filter out used voices if keep_duplicate is False 5. Randomly select from available voices 6. Track usage if keep_duplicate is False

Parameters:
  • gender (str) – Speaker gender (e.g., “male”, “female”).

  • age (int) – Speaker age in years.

  • lang (str) – Language name (default: “english”).

  • keep_duplicate (bool) – If True, allows voice reuse. If False, ensures each voice is used only once.

  • seed (int) – Seed for random number generator.

Returns:

A Voice object matching the specified characteristics.

Return type:

Voice

Raises:
  • ValueError – If the language is not found in the database.

  • ValueError – If no voice is found for the specified characteristics.

class sdialog.audio.voice_database.HuggingfaceVoiceDatabase(dataset_name: str = 'sdialog/voices-libritts', subset: str = 'train')

Bases: BaseVoiceDatabase

Voice database implementation using Hugging Face datasets.

This implementation loads voice data from Hugging Face datasets, providing access to large-scale voice collections with standardized metadata. It supports both remote datasets and local dataset caches, making it suitable for research and production use cases.

Key Features:

  • Integration with Hugging Face datasets library

  • Support for both remote and local dataset access

  • Automatic metadata extraction and validation

  • Fallback handling for missing metadata fields

  • Efficient dataset loading and caching

Expected Dataset Format:

The dataset should contain the following fields: - audio: Audio data with path information - voice: Voice identifier (alternative to audio) - gender: Speaker gender (“male”, “female”, “m”, “f”) - age: Speaker age (integer) - identifier: Unique voice identifier - language: Language name (optional, defaults to “english”) - language_code: Language code for TTS engines (optional, defaults to “e”)

Variables:
  • dataset_name (str) – Name or path of the Hugging Face dataset.

  • subset (str) – Dataset subset to use (e.g., “train”, “test”, “validation”).

populate() → dict

Populates the voice database from the Hugging Face dataset.

This method loads voice data from the specified Hugging Face dataset, extracts metadata for each voice entry, and organizes the data in the hierarchical database structure. It handles missing metadata by providing sensible defaults and logging warnings.

Data processing steps: 1. Load dataset from Hugging Face (remote or local cache) 2. Iterate through dataset entries 3. Extract and validate metadata fields 4. Handle missing fields with defaults and warnings 5. Organize voices by language, gender, and age 6. Create Voice objects and add to database

Returns:

The populated voice data dictionary.

Return type:

dict

Raises:
  • ImportError – If the datasets library is not installed.

  • ValueError – If the dataset or subset is not found.

  • ValueError – If required voice data is missing from the dataset.

class sdialog.audio.voice_database.LocalVoiceDatabase(directory_audios: str, metadata_file: str)

Bases: BaseVoiceDatabase

Voice database implementation using local audio files and metadata.

This implementation loads voice data from local audio files and metadata files (CSV, TSV, or JSON), providing a flexible solution for custom voice collections. It supports various metadata formats and handles both relative and absolute file paths.

Key Features:

  • Support for multiple metadata formats (CSV, TSV, JSON)

  • Flexible file path handling (relative and absolute paths)

  • Comprehensive metadata validation

  • Support for both file paths and voice identifiers

  • Local file system integration

Required Metadata Format:

The metadata file must contain the following columns: - identifier: Unique voice identifier - gender: Speaker gender (“male”, “female”, “m”, “f”) - age: Speaker age (integer) - voice or file_name: Voice identifier or audio file path - language: Language name (optional, defaults to “english”) - language_code: Language code for TTS engines (optional, defaults to “e”)

Variables:
  • directory_audios (str) – Directory containing audio files.

  • metadata_file (str) – Path to the metadata file (CSV, TSV, or JSON).

populate() → dict

Populate the voice database. The metadata file can be a csv, tsv or json file. The metadata file must contain the following columns: identifier, gender, age, voice, language, language_code.

  • “voice” or “file_name” column: path to audio file or voice name (e.g., “am_echo”)

  • language column can be a string like “english” or “french”.

  • language_code column can be a string like “e” or “f”.

  • identifier column can be a string like “am_echo” or “am_echo_2”.

  • gender column can be a string like “male” or “female”.

  • age column can be an integer like 20 or 30.

class sdialog.audio.voice_database.VoiceDatabase(data: list[dict])

Bases: BaseVoiceDatabase

Voice database implementation using in-memory voice data.

This implementation creates a voice database from a list of voice dictionaries, providing a flexible solution for programmatically creating voice databases or loading voice data from custom sources. It’s particularly useful for testing, small voice collections, or when voice data is already available in memory.

Key Features:

  • In-memory voice data processing

  • Support for custom voice data structures

  • Comprehensive data validation

  • Flexible voice data input format

  • No external file dependencies

Required Data Format:

The input data should be a list of dictionaries, where each dictionary contains the following keys: - identifier: Unique voice identifier - gender: Speaker gender (“male”, “female”, “m”, “f”) - age: Speaker age (integer) - voice: Voice identifier or data - language: Language name (optional, defaults to “english”) - language_code: Language code for TTS engines (optional, defaults to “e”)

Variables:

_input_data (list[dict]) – List of voice dictionaries to process.

populate() → dict

Populates the voice database from in-memory voice data.

This method processes the list of voice dictionaries provided during initialization, validates the data, and organizes it in the hierarchical database structure. It performs comprehensive validation to ensure data integrity and provides detailed error messages for missing or invalid data.

Data processing steps: 1. Validate input data format (list of dictionaries) 2. Iterate through each voice dictionary 3. Extract and validate required fields 4. Handle missing optional fields with defaults 5. Create Voice objects and add to database 6. Log processing statistics

Required fields in each voice dictionary:
  • identifier: Unique voice identifier

  • gender: Speaker gender (“male”, “female”, “m”, “f”)

  • age: Speaker age (integer)

  • voice: Voice identifier or data

  • language: Language name (optional, defaults to “english”)

  • language_code: Language code for TTS engines (optional, defaults to “e”)

Returns:

The populated voice data dictionary.

Return type:

dict

Raises:
  • ValueError – If the input data is not a list of dictionaries.

  • ValueError – If required voice data is missing from any entry.