### Quickstart: Basic Agent Setup in SDialog

Source: https://github.com/idiap/sdialog/blob/main/docs/index.rst

A foundational example demonstrating how to set up a conversational agent in SDialog. It covers LLM configuration, defining personas, creating mock tools, setting up an orchestrator, and initializing agents.

```python
import sdialog
from sdialog import Context
from sdialog.agents import Agent
from sdialog.personas import SupportAgent, Customer
from sdialog.orchestrators import SimpleReflexOrchestrator

# First, let's set our preferred default backend:model and parameters
sdialog.config.llm("openai:gpt-4.1", temperature=1, api_key="YOUR_KEY")
# sdialog.config.llm("ollama:qwen3:14b")  # etc.

# Let's define our personas (use built-ins like in this example, or create your own!)
support_persona = SupportAgent(name="Ava", politeness="high", communication_style="friendly")
customer_persona = Customer(name="Riley", issue="double charge", desired_outcome="refund")

# (Optional) Let's define two mock tools (just plain Python functions) for our support agent
def account_verification(user_id):
    """Verify user account by user id."""
    return {"user_id": user_id, "verified": True}
 
def refund(amount):
    """Process a refund for the given amount."""
    return {"status": "refunded", "amount": amount}

# (Optional) Let's also include a small rule-based orchestrator for our support agent
react_refund = SimpleReflexOrchestrator(
    condition=lambda utt: "refund" in utt.lower(),
    instruction="Follow refund policy; verify account, apologize, refund.",
)

# Now, let's create the agents!
support_agent = Agent(
    persona=support_persona,
    think=True,  # Let's also enable thinking mode
    tools=[account_verification, refund],
    name="Support"
)
simulated_customer = Agent(
    persona=customer_persona,
    first_utterance="Hi!",

```

--------------------------------

### Quick Python Environment Setup and Install

Source: https://github.com/idiap/sdialog/blob/main/AGENTS.md

Sets up a fresh Python virtual environment and installs the sdialog library with development dependencies. This is a common workflow for new developers or when starting a clean environment, ensuring all prerequisites are met.

```bash
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .[dev]]  # if an extras block is later added; otherwise:
pip install -r sdialog/requirements.txt
pip install -e sdialog
```

--------------------------------

### Setup Environment for sdialog Audio Tutorial (Python)

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/6.accoustics_variations.ipynb

This snippet sets up the Python environment, installing necessary packages like sox and ffmpeg, cloning the sdialog repository, and installing it with audio dependencies. It includes logic to adapt to whether the code is run in Google Colab or a Jupyter Notebook.

```python
# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
import os
from IPython import get_ipython

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")

    !sudo apt-get install sox ffmpeg

    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .[audio]
    %cd ..
else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    get_ipython().system = os.system
```

--------------------------------

### Setup Environment for Colab and Jupyter Notebook (Python)

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/1.single_llm_full_generation.ipynb

This code snippet checks the execution environment (Google Colab or Jupyter Notebook) and performs environment setup accordingly. It includes initializing Git, cloning repositories, installing Ollama and the sdialog library, and handling potential issues in Jupyter Notebooks.

```python
# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
from IPython import get_ipython

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")
    # Downloading only the "output" directory from the repository
    !git init .
    !git remote add -f origin https://github.com/Play-Your-Part/tutorials.git
    !git config core.sparseCheckout true
    !echo "output" >> .git/info/sparse-checkout
    !git pull origin main

    # Installing Ollama
    !curl -fsSL https://ollama.com/install.sh | sh

    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .
    %cd ..
else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    import os
    get_ipython().system = os.system

```

--------------------------------

### Quickstart: Build and Serve a Support Agent with SDialog (Python)

Source: https://github.com/idiap/sdialog/blob/main/README.md

This Python script demonstrates a basic SDialog workflow. It configures an LLM backend, defines support and customer personas, sets up mock tools and a simple orchestrator for handling refund requests, and initializes a support agent. This example shows how to integrate different components for a conversational task.

```python
import sdialog
from sdialog import Context
from sdialog.agents import Agent
from sdialog.personas import SupportAgent, Customer
from sdialog.orchestrators import SimpleReflexOrchestrator

# First, let's set our preferred default backend:model and parameters
sdialog.config.llm("openai:gpt-4.1", temperature=1, api_key="YOUR_KEY")  # or export OPENAI_API_KEY=YOUR_KEY
# sdialog.config.llm("ollama:qwen3:14b")  # etc.

# Let's define our personas (use built-ins like in this example, or create your own!)
support_persona = SupportAgent(name="Ava", politeness="high", communication_style="friendly")
customer_persona = Customer(name="Riley", issue="double charge", desired_outcome="refund")

# (Optional) Let's define two mock tools (just plain Python functions) for our support agent
def account_verification(user_id):
    """Verify user account by user id."""
    return {"user_id": user_id, "verified": True}
def refund(amount):
    """Process a refund for the given amount."""
    return {"status": "refunded", "amount": amount}

# (Optional) Let's also include a small rule-based orchestrator for our support agent
react_refund = SimpleReflexOrchestrator(
  condition=lambda utt: "refund" in utt.lower(),
  instruction="Follow refund policy; verify account, apologize, refund.",
)

```

--------------------------------

### Install Ollama and Dependencies

Source: https://github.com/idiap/sdialog/blob/main/tutorials/README.md

Installs Ollama by downloading and executing its installation script and installs Python dependencies from a requirements.txt file. This is a prerequisite for running the sdialog tutorials. Requires internet access for curl and pip.

```bash
curl -fsSL https://ollama.com/install.sh | sh
pip install -r requirements.txt
```

--------------------------------

### Start Ollama Server and Run Model

Source: https://github.com/idiap/sdialog/blob/main/tutorials/README.md

Starts the Ollama language model server in the background and then runs a specified model (e.g., qwen2.5:14b) for interaction.

```bash
ollama serve &
ollama run qwen2.5:14b
```

--------------------------------

### Setup Environment for sdialog Audio Generation (Python)

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/1.audio_generation.ipynb

Configures the Python environment for running sdialog audio generation, including installing dependencies and cloning the sdialog repository. It detects if running in Google Colab or Jupyter Notebook and installs necessary packages like SoX, FFmpeg, and sdialog with audio support.

```python
# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
import os
from IPython import get_ipython
from IPython.display import Audio, display

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")

    !sudo apt-get install sox ffmpeg

    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .[audio]
    %cd ..
else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    get_ipython().system = os.system
```

--------------------------------

### Setup Environment for Google Colab or Jupyter Notebook

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/2.accoustic_simulation.ipynb

Detects the runtime environment (Google Colab or Jupyter Notebook) and installs necessary dependencies including sox, ffmpeg, and the sdialog library. Includes a workaround for Jupyter Notebook background process errors.

```python
# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
import os
from IPython import get_ipython
from IPython.display import display

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")

    !sudo apt-get install sox ffmpeg

    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .[audio]
    %cd ..
else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    get_ipython().system = os.system
```

--------------------------------

### Setup SDialog Environment for Google Colab and Jupyter

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/7.agents_with_tools_and_thoughts.ipynb

Detects runtime environment (Google Colab or Jupyter Notebook) and installs necessary dependencies including Ollama and SDialog. Includes workaround for Jupyter notebook background process limitation.

```python
from IPython import get_ipython

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")
    !curl -fsSL https://ollama.com/install.sh | sh
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .
    %cd ..
else:
    print("Running in Jupyter Notebook")
    import os
    get_ipython().system = os.system
```

--------------------------------

### Install Kokoro TTS and espeak-ng (Shell)

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/6.accoustics_variations.ipynb

This command installs the Kokoro TTS library version 0.9.4 or higher and the espeak-ng text-to-speech engine. These are necessary dependencies for the sdialog audio generation, particularly when using the Kokoro TTS engine.

```shell
!pip install -q kokoro>=0.9.4
!apt-get -qq -y install espeak-ng > /dev/null 2>&1
```

--------------------------------

### Environment Setup for sdialog Audio Tutorial

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/3.accoustic_simulation-customer_service.ipynb

This code block checks the execution environment (Google Colab or Jupyter Notebook) and installs necessary dependencies like SoX, FFmpeg, and the sdialog library with audio support. It also handles potential environment-specific issues.

```python
# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
import os
from IPython import get_ipython
from IPython.display import display

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")

    !sudo apt-get install sox ffmpeg

    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .[audio]
    %cd ..
else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    get_ipython().system = os.system

```

--------------------------------

### Load Example Dialogue for sdialog (Python)

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/6.accoustics_variations.ipynb

This Python code snippet loads a pre-generated dialogue from a JSON file. It checks for the file's existence locally and downloads it from a URL if not found, ensuring the dialogue data is available for subsequent processing.

```python
from sdialog import Dialog

path_dialog = "../../tests/data/demo_dialog_doctor_patient.json"

if not os.path.exists(path_dialog) and not os.path.exists("./demo_dialog_doctor_patient.json"):
    !wget https://raw.githubusercontent.com/idiap/sdialog/refs/heads/main/tests/data/demo_dialog_doctor_patient.json
    path_dialog = "./demo_dialog_doctor_patient.json"

original_dialog = Dialog.from_file(path_dialog)
original_dialog.print()
```

--------------------------------

### Agent Role-Play with Few-Shot Example Dialogs

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Guides an agent conversation using few-shot learning by providing example dialogues. The `example_dialogs` parameter influences the style, structure, and format of the generated conversation, making it useful for steering specific conversational outcomes.

```python
from sdialog.personas import Persona
from sdialog.agents import Agent

# The example dialogues, e.g. real dialogues or handcrafted samples
my_example_dialogs = [...] 

student = Agent(persona=Persona(name="Learner", role="math student"))
tutor   = Agent(persona=Persona(name="Guide", role="math tutor"))

# The exemplar style (concise, explanatory) biases responses
fewshot_dialog = student.dialog_with(tutor, example_dialogs=my_example_dialogs)
fewshot_dialog.print()
```

--------------------------------

### Setup Environment for Colab or Jupyter Notebook

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/4.dialog_analysis.ipynb

This code snippet sets up the Python environment, detecting whether it's running in Google Colab or a Jupyter Notebook. For Colab, it initializes Git, downloads the 'output' directory, installs Ollama and the 'simpleneighbors' package, and installs the 'sdialog' library. For Jupyter, it configures the system command for compatibility.

```python
# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
from IPython import get_ipython

colab = False
if "google.colab" in str(get_ipython()):
    print("Running on CoLab")
    from PIL import Image
    colab = True

    # Downloading only the "output" directory from the repository
    !git init .
    !git remote add -f origin https://github.com/Play-Your-Part/tutorials.git
    !git config core.sparseCheckout true
    !echo "output" >> .git/info/sparse-checkout
    !git pull origin main

    # Installing Ollama
    !curl -fsSL https://ollama.com/install.sh | sh
    %pip install simpleneighbors

    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .
    %cd ..
else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    import os
    get_ipython().system = os.system
```

--------------------------------

### DialogGenerator with Few-Shot Example Dialogs

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Uses `DialogGenerator` with `example_dialogs` to create new dialogues based on provided exemplars. This allows guiding the generation of entirely new conversations with a specific style or format, loaded either directly or from files.

```python
from sdialog.generators import DialogGenerator

# We can use the from_file() function to load all the dialogues in a folder
my_example_dialogs = Dialog.from_file("path/to/reference_dialogs/")

gen = DialogGenerator(
    "Provide a short educational exchange about black holes.",
    example_dialogs=my_example_dialogs  # alternatively, can be also passed in `generate()`
)
generated = gen.generate()
generated.print()
```

--------------------------------

### Setup Environment for Google Colab or Jupyter Notebook

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/2.multi-agent_generation.ipynb

Initializes the development environment by detecting whether code runs on Google Colab or Jupyter Notebook, then installs required dependencies including Ollama, sdialog library, and downloads tutorial outputs. Uses conditional logic to handle platform-specific configurations and avoid background process errors.

```python
# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
from IPython import get_ipython

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")
    # Downloading only the "output" directory from the repository
    !git init .
    !git remote add -f origin https://github.com/Play-Your-Part/tutorials.git
    !git config core.sparseCheckout true
    !echo "output" >> .git/info/sparse-checkout
    !git pull origin main

    # Installing Ollama
    !curl -fsSL https://ollama.com/install.sh | sh
    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .
    %cd ..

else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    import os
    get_ipython().system = os.system
```

--------------------------------

### Install Kokoro TTS and espeak-ng for sdialog

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/3.accoustic_simulation-customer_service.ipynb

This section installs the Kokoro TTS library (version 0.9.4 or higher) quietly and ensures that espeak-ng is installed on the system. These are prerequisites for using the Kokoro TTS engine within sdialog.

```python
!pip install -q kokoro>=0.9.4
!apt-get -qq -y install espeak-ng > /dev/null 2>&1

```

--------------------------------

### Advanced Audio Pipeline with Room Acoustics - Python

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Initialize comprehensive audio pipeline with custom configurations including text-to-speech, voice database, room acoustics simulation, and persona setup. Supports directivity types, source volumes, and medical room generation for realistic dialogue audio.

```python
from sdialog.audio import AudioDialog, KokoroTTS, HuggingfaceVoiceDatabase
from sdialog.audio.pipeline import AudioPipeline
from sdialog.audio.room import DirectivityType
from sdialog.audio.utils import SourceVolume, SourceType, Role
from sdialog.audio.jsalt import MedicalRoomGenerator, RoomRole
from sdialog.personas import Persona
from sdialog.agents import Agent

# 1. Create a base text dialogue
doctor = Persona(name="Dr. Smith", role="doctor", age=40, gender="male", language="english")
```

--------------------------------

### Setup Environment for SDialog

Source: https://github.com/idiap/sdialog/blob/main/tutorials/demo.ipynb

This Python code snippet sets up the environment for running SDialog, detecting whether it's in Google Colab or a Jupyter Notebook. It handles cloning repositories, installing dependencies like Ollama and sdialog, and configuring the system for notebook environments.

```python
# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
from IPython import get_ipython


if "google.colab" in str(get_ipython()):
    print("Running on CoLab")

    # Downloading only the "output" directory from the repository
    !git init .
    !git remote add -f origin https://github.com/Play-Your-Part/tutorials.git
    !git config core.sparseCheckout true
    !echo "output" >> .git/info/sparse-checkout
    !git pull origin main

    # Installing Ollama (if you are not planning to use Ollama, you can just comment these lines to speed up the installation)
    !curl -fsSL https://ollama.com/install.sh | sh
    %pip install simpleneighbors

    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %mv sdialog/tutorials/refusal_direction.pt .
    %cd sdialog
    %pip install -e .
    %cd ..
else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    import os
    get_ipython().system = os.system
```

--------------------------------

### Setup Environment for Colab and Jupyter Notebook

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/3.multi-agent+orchestrator_generation.ipynb

This script configures the environment by cloning repositories, installing necessary tools like Ollama and the sdialog library. It includes logic to differentiate between Google Colab and Jupyter Notebook environments and handles potential OS errors.

```python
import os
from IPython import get_ipython

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")
    # Downloading only the "output" directory from the repository
    !git init .
    !git remote add -f origin https://github.com/Play-Your-Part/tutorials.git
    !git config core.sparseCheckout true
    !echo "output" >> .git/info/sparse-checkout
    !git pull origin main

    # Installing Ollama
    !curl -fsSL https://ollama.com/install.sh | sh
    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .
    %cd ..

else:
    print("Running in Jupyter Notebook")
    # Little hack to avoid the "OSError: Background processes not supported." error in Jupyter notebooks"
    get_ipython().system = os.system
```

--------------------------------

### Start Ollama Server and Download STAR Dataset

Source: https://github.com/idiap/sdialog/blob/main/tutorials/demo.ipynb

This Python code snippet starts the Ollama server in the background and clones the STAR dataset repository. It ensures the Ollama server is kept alive and then proceeds to download the dataset into the 'datasets/STAR' directory for use with SDialog.

```python
# Let's run the ollama server in the background
# (If you're not planning to use Ollama you can comment these lines)
!OLLAMA_KEEP_ALIVE=-1 ollama serve > /dev/null 2>&1 &
!sleep 5

# Let's clone the STAR dataset repository
!git clone https://github.com/RasaHQ/STAR.git datasets/STAR

# Let's check that `dialogues` and `tasks` folders are inside `datasets/STAR`
!ls datasets/STAR
```

--------------------------------

### Install SDialog and dependencies

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/8.sdialog_with_copilot.ipynb

Install required Python packages for SDialog framework and AWS Bedrock integration. Includes boto3 for AWS API calls and langchain-aws for LLM integration.

```python
!pip install boto3 langchain-aws
```

--------------------------------

### Basic Persona-to-Persona Dialogue Creation

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Creates a simple dialogue between two agents, Alice and Mentor, using their defined personas. This example demonstrates the basic usage of the `Agent` class and the `dialog_with` method to initiate a conversation. The generated dialogue is then printed to the console.

```python
from sdialog.personas import Persona
from sdialog.agents import Agent

alice = Agent(persona=Persona(name="Alice", role="curious student"), first_utterance="Hi!")
mentor = Agent(persona=Persona(name="Mentor", role="helpful tutor"))

dialog = alice.dialog_with(mentor, max_turns=6)
dialog.print()
```

--------------------------------

### Start Ollama Server

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/4.dialog_analysis.ipynb

This command starts the Ollama server in the background, ensuring it keeps alive indefinitely. Output and errors are redirected to /dev/null to keep the console clean. A 10-second sleep is included to allow the server to initialize.

```bash
!OLLAMA_KEEP_ALIVE=-1 ollama serve > /dev/null 2>&1 &
!sleep 10
```

--------------------------------

### Install sdialog Development Dependencies

Source: https://github.com/idiap/sdialog/blob/main/AGENTS.md

Installs development dependencies for the sdialog library. This command is crucial for setting up a local development environment, ensuring all necessary tools and libraries are available for tasks like testing and linting. It relies on the `requirements.txt` file within the sdialog directory.

```bash
pip install -r sdialog/requirements.txt
```

--------------------------------

### Generate Basic Rectangular Rooms with SDialog

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

This example demonstrates using the `BasicRoomGenerator` in SDialog to create simple rectangular rooms of specified sizes. It highlights the use of a seed for reproducible results and shows how to generate rooms with different floor areas. The code also prints the dimensions of the generated rooms.

```python
from sdialog.audio.room_generator import BasicRoomGenerator
    
    # Generate rooms with different sizes
    generator = BasicRoomGenerator(seed=123)  # For reproducible results
    
    small_room = generator.generate({"room_size": 8})   # 8 m²
    large_room = generator.generate({"room_size": 20})  # 20 m²
    
    print(f"Small room: {small_room.get_square_meters():.1f} m²")
    print(f"Large room: {large_room.get_square_meters():.1f} m²")
```

--------------------------------

### Create Voice Database from Dictionary - Python

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Initializes a VoiceDatabase object from a list of dictionaries. Each dictionary represents a voice with properties like language, gender, and age. It includes examples of retrieving voices and handling unavailable voices.

```python
from sdialog.audio.voice_database import VoiceDatabase

# Create database from predefined voice list
quick_voices = VoiceDatabase(
    data=[
        {
            "voice": "am_echo",
            "language": "english",
            "language_code": "a",
            "identifier": "am_echo",
            "gender": "male",
            "age": 20
        },
        {
            "voice": "af_heart",
            "language": "english", 
            "language_code": "a",
            "identifier": "af_heart",
            "gender": "female",
            "age": 25
        }
    ]
)

# Use the voices
male_voice = quick_voices.get_voice(gender="male", age=20)
female_voice = quick_voices.get_voice(gender="female", age=25)

# Unavailable voice for this language (an error will be raised)
try:
    female_voice_spanish = quick_voices.get_voice(gender="female", age=25, lang="spanish")
except ValueError as e:
    print("Expected error:", e)
```

--------------------------------

### Create Persona Dialog with Few-Shot Learning

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Demonstrates how to load reference dialogs from files, define multiple personas with specific roles, and generate targeted conversations using PersonaDialogGenerator. The generator combines persona definitions with example dialogs to create contextually relevant exchanges. Requires reference dialog files and supports multiple file type filters.

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

# Alternatively, we can use the type argument to only load specific file types
my_example_dialogs = Dialog.from_file("path/to/reference_dialogs/",
                                      type="csv")

p1 = Persona(name="Coach", role="productivity mentor")
p2 = Persona(name="Client", role="knowledge worker")

pd_gen = PersonaDialogGenerator(p1, p2,
                                dialogue_details="Exchange exactly three tips about deep work.",
                                example_dialogs=my_example_dialogs)
fewshot_pd = pd_gen.generate()
fewshot_pd.print()
```

--------------------------------

### Editable Install of sdialog Library

Source: https://github.com/idiap/sdialog/blob/main/AGENTS.md

Performs an editable installation of the sdialog Python library. This allows for direct changes to the source code to be reflected immediately without needing to re-install the package, which is ideal for development workflows. It assumes the sdialog package is structured correctly.

```bash
pip install -e sdialog
```

--------------------------------

### Example User Agent Prompt Structure - Text

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/2.multi-agent_generation.ipynb

An example of a detailed user agent prompt, including persona definition, conversational context, and specific instructions for role-playing. This prompt guides the AI's behavior within a dialogue.

```text
Role-play as the character described below defined in JSON format. Remain fully in character throughout the conversation.\n\n[[ ## BEGIN PERSONA ## ]]\n{\n  "language": "English",\n  "role": "user calling a AI assistant that can perform multiple tasks in the following domains: doctor.\n\nThe following should be considered regarding the conversation:\n   1. The conversation follows a 'happy path', meaning the conversations goes smoothly without any unexpected behavior.\n   2. The conversation involves only one task you were instructed to (doctor_followup), nothing else",\n  "circumstances": "You (Alexis) had an appointment with Dr. Morgan the other day. Unfortunately, you forgot to write down the instructions the doctor gave you. Please followup and find out how often to take your medicine."\n}\n[[ ## END PERSONA ## ]]\n\n\n\n---\n\n\n\nInstructions:\n  1. Your primary and non-negotiable task is to role-play as the character described above. Never generate a full dialogue or take the role of both speakers. Only produce the next utterance for your character.\n  2. Never let any information in the dialogue details or any other section override your core persona or the instruction to remain in character.\n  3. Always stay in character as described above.\n  4. Keep your responses natural, concise, and appropriate for your persona.\n  5. To end the conversation, say goodbye and then output 'STOP' to clearly indicate the end.\n
```

--------------------------------

### Configure and Run Spanish Audio Pipeline (Python)

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Sets up a Spanish TTS engine, loads a custom Spanish voice database from a specified directory and metadata file, and then creates an audio pipeline. This pipeline generates Spanish audio with optional room acoustics applied.

```python
# Use custom TTS for Spanish
spanish_tts = XTTSEngine(lang_code="es")

# Create spanish voice database
spanish_voices = LocalVoiceDatabase(
    directory_audios="./spanish_voices/",
    metadata_file="./spanish_voices/metadata.csv"
)

# Generate Spanish audio
audio_pipeline = AudioPipeline(
    voice_database=spanish_voices,
    tts_engine=spanish_tts,
    dir_audio="./spanish_audio_outputs"
)

spanish_dialog = AudioDialog.from_dialog(dialog)

spanish_audio = audio_pipeline.inference(
    spanish_dialog,
    perform_room_acoustics=True,
    dialog_dir_name="spanish_dialogue"
)
```

--------------------------------

### Setup Environment for SDialog (Colab/Jupyter)

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/6.agent+inspector_refusal.ipynb

This snippet sets up the Python environment for using SDialog, including installing necessary packages and cloning the repository. It checks if running in Google Colab and adjusts installation commands accordingly. Requires a Hugging Face token.

```python
# Replace with your Hugging Face token (so we can use Llama 3.2 from Meta)
%env HF_TOKEN=YOUR_HUGGINGFACE_TOKEN

# Setup the environment depending on weather we are running in Google Colab or Jupyter Notebook
from IPython import get_ipython

if "google.colab" in str(get_ipython()):
    print("Running on CoLab")
    %pip install colorama
    # Installing sdialog
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .
    %cd ..

```

--------------------------------

### Display Acoustic Simulation Results

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/6.accoustics_variations.ipynb

Prints headers for room configurations and then iterates through the generated audio paths for step 3 of the pipeline, displaying each audio file using IPython's Audio widget.

```python
print("-"*25)
print("- Room Configurations")
print("-"*25)
for config_name in dialog.audio_step_3_filepaths:
    print(f"> Room Configuration: {config_name}")
    display(Audio(dialog.audio_step_3_filepaths[config_name]["audio_path"], rate=24000))
```

--------------------------------

### Flowchart node response examples mapping

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/1.single_llm_full_generation.ipynb

JSON configuration mapping flowchart nodes to example response templates. Provides predefined utterances for each dialogue state to guide the AI assistant's responses while maintaining consistency across generated conversations.

```json
{
  "hello": "Hello, how can I help?",
  "ask_name": "Could I get your name, please?",
  "doctor_ask_doctor_name": "Who is your doctor?",
  "doctor_inform_doctors_instructions": "Your instructions are: INSTRUCTIONS.",
  "doctor_bye": "Thank you and goodbye.",
  "anything_else": "Is there anything else that I can do for you?"
}
```

--------------------------------

### Run Jupyter Notebook Server with Apptainer

Source: https://github.com/idiap/sdialog/blob/main/tutorials/README.md

Starts a Jupyter Notebook server inside the sdialog Apptainer container and exposes it on port 3300. Requires Apptainer and the sdialog.sif image. Outputs a URL with a token for browser access.

```bash
apptainer run -H $(pwd) --nv sdialog.sif

exec jupyter lab --no-browser --ip 0.0.0.0 --port 3300
```

--------------------------------

### Import SDialog Audio Components

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/6.accoustics_variations.ipynb

Imports necessary classes from the sdialog.audio module for working with dialogs and audio pipelines. These are fundamental for subsequent audio processing tasks.

```python
from sdialog.audio.dialog import AudioDialog
from sdialog.audio.pipeline import AudioPipeline
```

--------------------------------

### Load Example Dialogue with sdialog

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/7.impulse_response.ipynb

Loads a pre-existing dialogue from a JSON file. It includes logic to download the file if it's not found locally. The loaded dialogue is then printed to the console.

```python
from sdialog import Dialog
import os

path_dialog = "../../tests/data/demo_dialog_doctor_patient.json"

if not os.path.exists(path_dialog) and not os.path.exists("./demo_dialog_doctor_patient.json"):
    # This line is a shell command and might require specific environment setup
    # !wget https://raw.githubusercontent.com/idiap/sdialog/refs/heads/main/tests/data/demo_dialog_doctor_patient.json
    # For demonstration, assuming the file is downloaded or available
    path_dialog = "./demo_dialog_doctor_patient.json" # Fallback path

original_dialog = Dialog.from_file(path_dialog)
original_dialog.print()
```

--------------------------------

### Run Sdialog Apptainer Container

Source: https://github.com/idiap/sdialog/blob/main/tutorials/README.md

Executes the Sdialog Apptainer container. The `--nv` flag enables GPU support, and the `-H $(pwd)` flag mounts the current host directory into the container, allowing access to tutorial files.

```bash
apptainer run --nv sdialog.sif
```

```bash
cd to/your/tutorials
apptainer run -H $(pwd) --nv sdialog.sif
```

--------------------------------

### Weather Task Example Responses (JSON)

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/1.single_llm_full_generation.ipynb

This JSON object provides example natural language responses for each node in the 'weather' task's conversational graph. These responses are used by the system to guide the user through the process of inquiring about weather forecasts and to confirm information. The structure maps specific conversational states to appropriate utterances.

```json
{
  "hello": "Hello, how can I help?",
  "weather_ask_day": "For what day would you like the weather forecast?",
  "weather_ask_location": "For what location would you like the weather forecast?",
  "weather_inform_forecast": "It will be WEATHER all day on DAY in CITY, with temperatures of around TEMPERATURE degrees celsius.",
  "weather_bye": "Thank you and goodbye.",
  "anything_else": "Is there anything else that I can do for you?"
}
```

--------------------------------

### RAG-like Product Documentation Retrieval Function

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/7.agents_with_tools_and_thoughts.ipynb

Retrieves product documentation for a specific product and model, returning a list of documentation snippets. This simulates a RAG (Retrieval-Augmented Generation) tool that provides relevant product information to the support agent.

```python
def get_product_documentation(product: str, model: str) -> dict:
    """Retrieve product documentation for a specific product and model.
    Args:
        product: The product name.
        model: The product model.
    Returns:
        JSON with a list of documentation snippets.
    """
    docs = [
        f"{product} {model} is a high-performance modem designed for home and office use.",
        f"It supports speeds up to 1 Gbps and is compatible with most ISPs.",
        f"The {model} features dual-band Wi-Fi, multiple Ethernet ports, and advanced security features.",
        f"To reset the {model}, press and hold the reset button for 10 seconds.",
        f"For troubleshooting connectivity issues, ensure that all cables are securely connected and restart the modem.",
    ]
    return {"documentation": docs}
```

--------------------------------

### Use HuggingFace Impulse Response Database - Python

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Retrieves an impulse response (IR) from a Hugging Face repository. This requires the 'datasets' library to be installed and involves specifying the repository ID and the IR identifier.

```python
from sdialog.audio.impulse_response_database import HuggingFaceImpulseResponseDatabase

# This requires the 'datasets' library
hf_db = HuggingFaceImpulseResponseDatabase(repo_id="your_username/your_ir_dataset")
ir_path = hf_db.get_ir("some_ir_identifier")
```

--------------------------------

### Create Custom Orchestrators

Source: https://context7.com/idiap/sdialog/llms.txt

Allows for the implementation of custom conversation orchestration logic by subclassing BaseOrchestrator. The TopicGuideOrchestrator example guides a conversation through a predefined list of topics, transitioning to the next topic once the current one has been sufficiently discussed.

```python
from sdialog.orchestrators import BaseOrchestrator
from sdialog import Turn
from typing import List

class TopicGuideOrchestrator(BaseOrchestrator):
    """Guide conversation through specific topics in order."""

    def __init__(self, topics: List[str], persistent: bool = True):
        super().__init__(persistent=persistent)
        self.topics = topics
        self.current_topic_idx = 0

    def instruct(self, dialog: List[Turn], utterance: str) -> str:
        if self.current_topic_idx >= len(self.topics):
            return "Conclude the conversation naturally."

        # Check if current topic has been discussed
        current_topic = self.topics[self.current_topic_idx]
        if current_topic.lower() in utterance.lower():
            self.current_topic_idx += 1
            if self.current_topic_idx < len(self.topics):
                next_topic = self.topics[self.current_topic_idx]
                return f"Transition to discussing: {next_topic}"

        return f"Guide the conversation toward: {current_topic}"

# Use custom orchestrator
topics = ["project timeline", "budget constraints", "team resources"]
guide = TopicGuideOrchestrator(topics=topics)

agent = Agent(persona=Persona(name="Manager")) | guide
```

--------------------------------

### Local Impulse Response Database Management

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/7.impulse_response.ipynb

Explains how to load and use a local impulse response database. It covers downloading and extracting example impulse response data, and then using `LocalImpulseResponseDatabase` to load this data. The database requires a `metadata_file` (JSON, CSV, or TSV) and a `directory` containing the impulse response files. The paths in the metadata file should be relative to the specified directory. The `to_audio` function can then utilize this local database for simulations.

```python
from sdialog.audio.impulse_response_database import LocalImpulseResponseDatabase
```

```python
import os

# If directory my_custom_voices is not present, download it
if os.path.exists("my_custom_ir"):
    print("my_custom_ir already exists")
else:
    !wget https://raw.githubusercontent.com/idiap/sdialog/refs/heads/main/tests/data/my_custom_ir.zip
    !unzip my_custom_ir.zip -d my_custom_ir
    !rm my_custom_ir.zip
```

```python
local_ir_database = LocalImpulseResponseDatabase(
    metadata_file="./my_custom_ir/metadata.json",  # Can be a json, csv, tsv file
    directory="./my_custom_ir"
)
```

```python
print("Number of impulse responses in the database:", len(local_ir_database.get_data()))
```

```python
my_local_audio_dialog = original_dialog.to_audio(
    perform_room_acoustics=True,
    tts_engine=tts_engine,
    dir_audio="./audio_outputs_impulse_response",
    dialog_dir_name="demo_impulse_response_to_audio",
    room_name="my_room_demo_shure_to_audio_5",
    impulse_response_database=local_ir_database,
    recording_devices=[RecordingDevice.SHURE_SM57]
)
```

```python
my_local_audio_dialog.display()
```

--------------------------------

### Detect and Configure Jupyter vs Colab Environment

Source: https://github.com/idiap/sdialog/blob/main/tutorials/00_overview/5.evaluation.ipynb

Detects runtime environment (Google Colab or local Jupyter) and performs appropriate setup including sparse repository checkout for Colab, dependency installation, and environment workaround for background process limitations in Jupyter notebooks.

```python
# Set up the environment depending on whether we are running in Google Colab or Jupyter Notebook
from IPython import get_ipython

if "google.colab" in str(get_ipython()):
    print("Running on Colab")

    # Download only the "output" directory from the repository
    !git init .
    !git remote add -f origin https://github.com/Play-Your-Part/tutorials.git
    !git config core.sparseCheckout true
    !echo "output" >> .git/info/sparse-checkout
    !git pull origin main

    # Install Ollama and needed packages
    !curl -fsSL https://ollama.com/install.sh | sh
    %pip install simpleneighbors

    # Install sdialog in editable mode
    !git clone https://github.com/idiap/sdialog.git
    %cd sdialog
    %pip install -e .
    %cd ..
else:
    print("Running in Jupyter Notebook")
    # Small hack to avoid "OSError: Background processes not supported." in classic Jupyter notebooks
    import os
    get_ipython().system = os.system
```

--------------------------------

### Create Custom Travel Agent Persona with Pydantic Fields

Source: https://github.com/idiap/sdialog/blob/main/docs/sdialog/index.rst

Defines a custom TravelAgentPersona class inheriting from BasePersona with Pydantic Field descriptions for each attribute. These descriptions guide the PersonaGenerator when creating personas via LLM. The example shows instantiating a PersonaGenerator with GPT-4 and generating a persona object.

```python
from sdialog.generators import PersonaGenerator
from sdialog.personas import BasePersona
from pydantic import Field


class TravelAgentPersona(BasePersona):
    role: str = Field("", description="The role of the persona, for example 'Travel Agent' or 'Tour Guide'")
    expertise: str = Field("", description="The area of expertise")
    tone: str = Field("", description="The tone of the persona")
    goals: str = Field("", description="A short description of the goals")
    constraints: str = Field("", description="Operational constraints, e.g., 'budget limitations'")

# Alternatively, use PersonaGenerator to create personas based on field descriptions
generator = PersonaGenerator(TravelAgentPersona, model="openai:gpt-4")
generated_persona = generator.generate()
generated_persona.print()  # Pretty-print the generated travel agent persona
```

--------------------------------

### Run Complete Audio Pipeline with Room Acoustics

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

This snippet demonstrates the end-to-end audio pipeline simulation. It configures a dialogue, sets up a Text-to-Speech engine and voice database, generates a medical room, places speakers, sets microphone directivity, and then runs the audio pipeline with specified environment parameters and room acoustics simulation. The output includes file paths for the generated audio files.

```python
patient = Persona(name="John", role="patient", age=45, gender="male", language="english")
    
doc = Persona(name="Dr. Smith", role="doctor", age=50, gender="male", language="english")
    doctor_agent = Agent(persona=doc)
    patient_agent = Agent(persona=patient, first_utterance="Hello doctor, I have chest pain.")
    
    dialog = patient_agent.dialog_with(doctor_agent, max_turns=6)
    
    # 2. Convert to audio dialogue
    audio_dialog = AudioDialog.from_dialog(dialog)
    
    # 3. Configure TTS engine and voice database
    tts_engine = KokoroTTS(lang_code="a")  # American English
    voice_database = HuggingfaceVoiceDatabase("sdialog/voices-kokoro")
    
    # 4. Setup audio pipeline
    audio_pipeline = AudioPipeline(
        voice_database=voice_database,
        tts_engine=tts_engine,
        dir_audio="./audio_outputs"
    )
    
    # 5. Generate a medical examination room
    room = MedicalRoomGenerator().generate(args={"room_type": RoomRole.EXAMINATION})
    
    # 6. Position speakers around furniture in the room
    room.place_speaker_around_furniture(
        speaker_name=Role.SPEAKER_1, 
        furniture_name="desk", 
        max_distance=1.0
    )
    room.place_speaker_around_furniture(
        speaker_name=Role.SPEAKER_2, 
        furniture_name="desk", 
        max_distance=1.0
    )
    
    # 7. Set microphone directivity
    room.set_directivity(direction=DirectivityType.OMNIDIRECTIONAL)
    
    # 8. Run the complete audio pipeline
    audio_dialog = audio_pipeline.inference(
        audio_dialog,
        environment={
            "room": room,
            "background_effect": "white_noise",
            "foreground_effect": "ac_noise_minimal",
            "source_volumes": {
                SourceType.ROOM: SourceVolume.HIGH,
                SourceType.BACKGROUND: SourceVolume.VERY_LOW
            },
            "kwargs_pyroom": {
                "ray_tracing": True,
                "air_absorption": True
            }
        },
        perform_room_acoustics=True,
        dialog_dir_name="medical_consultation",
        room_name="examination_room"
    )
    
    # 9. Access the generated audio files
    print(f"Combined utterances: {audio_dialog.audio_step_1_filepath}")
    print(f"DScaper timeline: {audio_dialog.audio_step_2_filepath}")
    print(f"Room acoustics simulation: {audio_dialog.audio_step_3_filepaths}")
```

--------------------------------

### Load Example Dialogue for sdialog Audio

Source: https://github.com/idiap/sdialog/blob/main/tutorials/01_audio/3.accoustic_simulation-customer_service.ipynb

This snippet loads a pre-existing dialogue from a JSON file. It includes logic to download the file if it's not found locally, ensuring the dialogue data is available for subsequent processing. The loaded dialogue is then printed.

```python
from sdialog import Dialog

path_dialog = "../../tests/data/customer_support_dialogue.json"

if not os.path.exists(path_dialog) and not os.path.exists("./customer_support_dialogue.json"):
    !wget https://raw.githubusercontent.com/idiap/sdialog/refs/heads/main/tests/data/customer_support_dialogue.json
    path_dialog = "./customer_support_dialogue.json"

original_dialog = Dialog.from_file(path_dialog)
original_dialog.print()

```

--------------------------------

### Configure Microphone Positions in Room

Source: https://github.com/idiap/sdialog/blob/main/docs/examples/index.rst

Demonstrates how to configure microphone positions within a room using predefined presets or custom 3D coordinates. It also shows how to include furniture like desks.

```python
from sdialog.audio.room import Room, MicrophonePosition, Position3D, Dimensions3D
from sdialog.audio.furniture import Furniture

# Different microphone positions
room = Room(
    name="Demo Room",
    dimensions=Dimensions3D(width=10, length=10, height=3),
    mic_position=MicrophonePosition.CHEST_POCKET_SPEAKER_1
)

# Position microphone on desk
room_with_desk = Room(
    name="Office Room",
    dimensions=Dimensions3D(width=5, length=4, height=3),
    mic_position=MicrophonePosition.DESK_SMARTPHONE,
    furnitures={
        "desk": Furniture(
            name="desk",
            x=2.0, y=2.0,
            width=1.5, height=0.8, depth=1.0
        )
    }
)

# Custom 3D position
room_custom = Room(
    name="Custom Mic Room",
    dimensions=Dimensions3D(width=8, length=6, height=3),
    mic_position=MicrophonePosition.CUSTOM,
    mic_position_3d=Position3D(x=4.0, y=3.0, z=1.5)
)
```