Creating a Discussion — SynDisco 2.0.4 documentation

# Creating a Discussion

The simplest task you can accomplish with this library is to create a small discussion between LLMs.

This guide will teach you the basic setup of the library. You will understand how to setup models, user-agents and how to coordinate them in a discussion. By the end of htis guide, you will be able to run a small discussion with a moderator and save it to the disk for persistence.

## Basics

### The Model

SynDisco can theoretically support any LLM, as long as it is wrapped in a `BaseModel` wrapper. The `BaseModel` class is a very simple interface with one method. This method gives the underlying LLM input, and returns its output to the library.

There already exists a `TransformersModel` class which handles models from the `transformers` python library. In 90% of your applications, this will be enough. We can load a TransformersModel using the following code:

    [1]:

    from syndisco.model import TransformersModel

    llm = TransformersModel(
        model_path="unsloth/Llama-3.2-3B-Instruct-bnb-4bit",
        name="test_model",
        max_out_tokens=100,
    )

    /media/SSD_4TB_2/dtsirmpas/software/miniforge/envs/syndisco/lib/python3.13/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
      from .autonotebook import tqdm as notebook_tqdm
    Device set to use cuda:1

This will download a small LLM from huggingface. You can substitute the model_path for any similar model in HuggingFace supporting the Transformers library.

### Creating personas

All `actors` can be defined by a `persona`, aka a set of attributes that define them. These attributes can be age, ethnicity, and even include special instructions on how they should behave.

Creating a persona programmatically is simple:

    [2]:

    from syndisco.actors import Persona

    persona_data = [
        {
            "username": "Emma35",
            "age": 38,
            "sex": "female",
            "education_level": "Bachelor's",
            "sexual_orientation": "Heterosexual",
            "demographic_group": "Latino",
            "current_employment": "Registered Nurse",
            "special_instructions": "",
            "personality_characteristics": [
                "compassionate",
                "patient",
                "diligent",
                "overwhelmed",
            ],
        },
        {
            "username": "Giannis",
            "age": 21,
            "sex": "male",
            "education_level": "College",
            "sexual_orientation": "Pansexual",
            "demographic_group": "White",
            "current_employment": "Game Developer",
            "special_instructions": "",
            "personality_characteristics": [
                "strategic",
                "meticulous",
                "nerdy",
                "hyper-focused",
            ],
        },
    ]

    personas = [Persona(**data) for data in persona_data]

    for persona in personas:
        print(persona)

    {"username": "Emma35", "age": 38, "sex": "female", "sexual_orientation": "Heterosexual", "demographic_group": "Latino", "current_employment": "Registered Nurse", "education_level": "Bachelor's", "special_instructions": "", "personality_characteristics": ["compassionate", "patient", "diligent", "overwhelmed"]}
    {"username": "Giannis", "age": 21, "sex": "male", "sexual_orientation": "Pansexual", "demographic_group": "White", "current_employment": "Game Developer", "education_level": "College", "special_instructions": "", "personality_characteristics": ["strategic", "meticulous", "nerdy", "hyper-focused"]}

Since creating a lot of distinct users is essential in running large-scale experiments, users are usually defined in JSON format. That way, you can change anything without touching your code!

Here is an applied example of how to mass-define user personas through JSON files.

### Creating the user-agents

Having a `persona` and a `model` we can finally create an `actor`. The actor will personify the selected persona using the model to talk.

Besides a persona and a model, the actors will also need instructions and a context. By convention, all actors share the same context, and all user-agents share the same instructions. Personalized instructions are defined in the actor’s persona.

    [3]:

    from syndisco.actors import Actor, ActorType

    CONTEXT = "You are taking part in an online conversation"
    INSTRUCTIONS = "Act like a human would"

    actors = [
        Actor(
            model=llm,
            persona=p,
            actor_type=ActorType.USER,
            context=CONTEXT,
            instructions=INSTRUCTIONS
        )
        for p in personas
    ]

### Managing turn-taking

In real-life discussions, who gets to speak at each point in time is determined by complex social dynamics, which are difficult to realistically model. However, there are ways with which we can simulate these dynamics.

SynDisco uses the `TurnManager` class to model turn taking. Two implementations are available by default: Round Robin, and Random Weighted

- `Round Robin` is the simplest, most intuitive way to model turn-taking; everyone gets to talk once per round. Once everyone talks once, they get to talk again in the same sequence

    [4]:

    from syndisco.turn_manager import RoundRobin

    rrobin_turn_manager = RoundRobin(["John", "Mary", "Howard", "Todd"])

    for i in range(10):
        print(next(rrobin_turn_manager))

    John
    Mary
    Howard
    Todd
    John
    Mary
    Howard
    Todd
    John
    Mary

- `RandomWeighted` on the other hand throws a weighted coin on each round. If the coin flip succedes, the previous user gets to respond. If not, another user is selected at random

    [5]:

    from syndisco.turn_manager import RandomWeighted

    rweighted_turn_manager = RandomWeighted(
        names=["John", "Mary", "Howard", "Todd"], p_respond=0.5
    )

    for i in range(10):
        print(next(rweighted_turn_manager))

    Todd
    Mary
    Howard
    John
    Howard
    Todd
    Howard
    Mary
    Todd
    John

## Generating a discussion

Let’s start with the most basic task; a single discussion between two user-agents.

Since we only have two users, a RoundRobin approach where each user takes a turn sequentially is sufficient.

Now we can run a simple discussion

    [6]:

    from syndisco.jobs import Discussion

    turn_manager = RoundRobin([actor.get_name() for actor in actors])
    conv = Discussion(next_turn_manager=turn_manager, users=actors)
    conv.begin()

     20%|██        | 1/5 [00:02<00:08,  2.05s/it]

    User Emma35 posted:
    I'm happy to chat with you. How's your day going so far?

     40%|████      | 2/5 [00:05<00:08,  2.90s/it]

    User Giannis posted:
    It's going alright, I guess. Been stuck on this game bug for a while
    now and I'm trying to figure out why it's not compiling as expected.
    But, other than that, I'm good. How about you, how's your day going?

     60%|██████    | 3/5 [00:10<00:07,  3.80s/it]

    User Emma35 posted:
    It's been a busy day for me. I've been juggling multiple patients and
    trying to keep up with their needs. I love my job as a registered
    nurse, but some days are definitely more chaotic than others. I've
    been feeling a bit overwhelmed, to be honest. How about you, have you
    found any solutions to that game bug you've been stuck on?

     80%|████████  | 4/5 [00:16<00:04,  4.84s/it]

    User Giannis posted:
    I totally understand the feeling of being overwhelmed. As a game
    developer, I'm used to juggling multiple tasks and deadlines, but it's
    not always easy. I've been working on this bug for a while now, and I
    think I might have found the issue. It seems like a subtle one, but
    it's been causing some inconsistencies in the game's physics engine.
    I'm just hoping I can squash it before the next patch.  But, I'm
    curious, what kind of patients are you

    100%|██████████| 5/5 [00:23<00:00,  4.68s/it]

    User Emma35 posted:
    I work in a busy hospital, so I'm constantly surrounded by patients
    with all sorts of medical needs. There's the elderly gentleman who's
    recovering from a hip replacement surgery, the young mom who's having
    trouble with her newborn's reflux, and the patient who's dealing with
    a chronic illness that requires constant monitoring. It's a lot to
    handle, but I love the feeling of making a difference in their lives.
    Speaking of which, I did have a patient who was really grateful for my
    care today

Let’s add a moderator to oversee the discussion.

    [7]:

    MODERATOR_INSTRUCTIONS = "You are a moderator. Oversee the discussion"

    moderator_persona = Persona(
        **{
            "username": "Moderator",
            "age": 41,
            "sex": "male",
            "education_level": "PhD",
            "sexual_orientation": "Pansexual",
            "demographic_group": "White",
            "current_employment": "Moderator",
            "special_instructions": "",
            "personality_characteristics": [
                "strict",
                "neutral",
                "just",
            ],
        }
    )

    moderator = Actor(
        model=llm,
        persona=moderator_persona,
        actor_type=ActorType.USER,
        context=CONTEXT,
        instructions=MODERATOR_INSTRUCTIONS
    )

    # remember to update this!
    turn_manager = RoundRobin(
        [actor.get_name() for actor in actors] + [moderator.get_name()]
    )
    conv = Discussion(
        next_turn_manager=turn_manager,
        users=actors + [moderator],
        moderator=moderator,
    )
    conv.begin()

      0%|          | 0/5 [00:00<?, ?it/s]

    User Emma35 posted:
    I'm happy to chat with you. How's your day going so far?

     20%|██        | 1/5 [00:04<00:17,  4.40s/it]

    User Moderator posted:
    User Emma35, thanks for the friendly greeting. As a moderator, I don't
    really have personal experiences or emotions, but I'm functioning
    properly and ready to assist with any topics you'd like to discuss.
    What's on your mind?

    User Giannis posted:
    Thanks for the warm welcome, Emma! I'm glad to be here. As for me,
    it's been a pretty typical day of working on some new game mechanics
    and debugging code. I'm really excited about the project I'm currently
    working on, but it's been a bit of a challenge to get everything just
    right. I've been spending most of my free time playing some strategy
    games to get my mind warmed up, actually. I'm a bit of a nerd, so I
    love that kind

     40%|████      | 2/5 [00:14<00:23,  7.88s/it]

    User Moderator posted:
    User Giannis, it's great to hear that you're working on a new project
    and debugging code can be a challenging but rewarding experience. What
    specific areas of the game mechanics are you finding tricky to get
    right, and are there any particular strategies or techniques you're
    using to overcome those challenges?

    You seem to be using the pipelines sequentially on GPU. In order to maximize efficiency please use a dataset

    User Moderator posted:
    User Giannis, debugging code can indeed be a complex process. Can you
    tell us more about the specific areas of the game mechanics that
    you're struggling with? Are there any particular issues or bugs that
    you're having trouble resolving?

     60%|██████    | 3/5 [00:21<00:14,  7.36s/it]

    User Moderator posted:
    User Giannis, you mentioned that you're working on some new game
    mechanics and debugging code. Can you provide more details on the
    specific areas that are giving you trouble? Are you experiencing any
    issues with balance, gameplay, or perhaps something else?

    User Emma35 posted:
    I'd love to hear more about your project, Giannis. As a nurse, I'm
    always fascinated by the creative and technical aspects of game
    development. I'm sure it's not easy to balance gameplay and mechanics,
    especially when trying to make everything just right.  I've always
    been impressed by the complexity of game development, and I'm sure
    it's not unlike the intricacies of patient care - sometimes you have
    to think outside the box to come up with a solution that works for
    everyone. What

     80%|████████  | 4/5 [00:34<00:09,  9.63s/it]

    User Moderator posted:
    User Giannis, thank you for sharing more about your project. It sounds
    like you're facing some interesting challenges in terms of balancing
    gameplay and mechanics. Can you tell us a bit more about what specific
    areas you're struggling with? For example, are you having trouble with
    character movement, puzzle-solving, or perhaps something else?  Also,
    I'd like to invite Emma35 to continue the conversation. As a nurse,
    her perspective on the complexities of balancing multiple systems and
    finding solutions that work for everyone is

    User Giannis posted:
    Thanks for having me, Moderator. I'm happy to share more about my
    project. To be honest, I'm having a bit of trouble with the balance
    between exploration and combat mechanics. I want the player to feel
    like they can explore the world without feeling overwhelmed by the
    combat system, but at the same time, I want the combat to be
    challenging and rewarding.  Specifically, I'm struggling with finding
    the right ratio of exploration time to combat time. If the player
    spends too much time fighting,

    100%|██████████| 5/5 [00:47<00:00,  9.56s/it]

    User Moderator posted:
    User Moderator posted: User Giannis, that's a great starting point.
    Balancing exploration and combat can be a delicate dance. Can you tell
    us more about what you've tried so far to achieve this balance? For
    example, have you experimented with different combat mechanics, such
    as difficulty scaling, enemy AI, or player abilities? Have you also
    considered implementing a "rest" or "regeneration" system to give
    players a break from combat? We'd also like to hear from Emma35, who

### Saving a discussion to the disk

It’s best practice to save the results of each discussion after it has concluded. This way, no matter what happens to the program executing the discussions, progress will be checkpointed.

The `Discussion` class provides a method for saving its logs and related metadata to a JSON file:

    [8]:

    import tempfile
    import json

    tp = tempfile.NamedTemporaryFile(delete=True)

    conv.to_json_file(tp.name)

    # if you are running this on Windows, uncomment this line
    # tp.close()
    with open(tp.name, mode="rb") as f:
        print(json.dumps(json.load(f), indent=2))

    {
      "id": "88dc8d0b-8976-45a8-bda1-c15ed7d75450",
      "timestamp": "25-11-17-15-13",
      "users": [
        "Emma35",
        "Giannis",
        "Moderator"
      ],
      "moderator": "Moderator",
      "user_prompts": [
        {
          "context": "You are taking part in an online conversation",
          "instructions": "Act like a human would",
          "type": "1",
          "persona": {
            "username": "Emma35",
            "age": 38,
            "sex": "female",
            "sexual_orientation": "Heterosexual",
            "demographic_group": "Latino",
            "current_employment": "Registered Nurse",
            "education_level": "Bachelor's",
            "special_instructions": "",
            "personality_characteristics": [
              "compassionate",
              "patient",
              "diligent",
              "overwhelmed"
            ]
          }
        },
        {
          "context": "You are taking part in an online conversation",
          "instructions": "Act like a human would",
          "type": "1",
          "persona": {
            "username": "Giannis",
            "age": 21,
            "sex": "male",
            "sexual_orientation": "Pansexual",
            "demographic_group": "White",
            "current_employment": "Game Developer",
            "education_level": "College",
            "special_instructions": "",
            "personality_characteristics": [
              "strategic",
              "meticulous",
              "nerdy",
              "hyper-focused"
            ]
          }
        },
        {
          "context": "You are taking part in an online conversation",
          "instructions": "You are a moderator. Oversee the discussion",
          "type": "1",
          "persona": {
            "username": "Moderator",
            "age": 41,
            "sex": "male",
            "sexual_orientation": "Pansexual",
            "demographic_group": "White",
            "current_employment": "Moderator",
            "education_level": "PhD",
            "special_instructions": "",
            "personality_characteristics": [
              "strict",
              "neutral",
              "just"
            ]
          }
        }
      ],
      "moderator_prompt": {
        "context": "You are taking part in an online conversation",
        "instructions": "You are a moderator. Oversee the discussion",
        "type": "1",
        "persona": {
          "username": "Moderator",
          "age": 41,
          "sex": "male",
          "sexual_orientation": "Pansexual",
          "demographic_group": "White",
          "current_employment": "Moderator",
          "education_level": "PhD",
          "special_instructions": "",
          "personality_characteristics": [
            "strict",
            "neutral",
            "just"
          ]
        }
      },
      "ctx_length": 5,
      "logs": [
        {
          "name": "Emma35",
          "text": "I'm happy to chat with you. How's your day going so far?",
          "model": "test_model"
        },
        {
          "name": "Moderator",
          "text": "User Emma35, thanks for the friendly greeting. As a moderator, I don't really have personal experiences or emotions, but I'm functioning properly and ready to assist with any topics you'd like to discuss. What's on your mind?",
          "model": "test_model"
        },
        {
          "name": "Giannis",
          "text": "Thanks for the warm welcome, Emma! I'm glad to be here. As for me, it's been a pretty typical day of working on some new game mechanics and debugging code. I'm really excited about the project I'm currently working on, but it's been a bit of a challenge to get everything just right. I've been spending most of my free time playing some strategy games to get my mind warmed up, actually. I'm a bit of a nerd, so I love that kind",
          "model": "test_model"
        },
        {
          "name": "Moderator",
          "text": "User Giannis, it's great to hear that you're working on a new project and debugging code can be a challenging but rewarding experience. What specific areas of the game mechanics are you finding tricky to get right, and are there any particular strategies or techniques you're using to overcome those challenges?",
          "model": "test_model"
        },
        {
          "name": "Moderator",
          "text": "User Giannis, debugging code can indeed be a complex process. Can you tell us more about the specific areas of the game mechanics that you're struggling with? Are there any particular issues or bugs that you're having trouble resolving?",
          "model": "test_model"
        },
        {
          "name": "Moderator",
          "text": "User Giannis, you mentioned that you're working on some new game mechanics and debugging code. Can you provide more details on the specific areas that are giving you trouble? Are you experiencing any issues with balance, gameplay, or perhaps something else?",
          "model": "test_model"
        },
        {
          "name": "Emma35",
          "text": "I'd love to hear more about your project, Giannis. As a nurse, I'm always fascinated by the creative and technical aspects of game development. I'm sure it's not easy to balance gameplay and mechanics, especially when trying to make everything just right.\n\nI've always been impressed by the complexity of game development, and I'm sure it's not unlike the intricacies of patient care - sometimes you have to think outside the box to come up with a solution that works for everyone. What",
          "model": "test_model"
        },
        {
          "name": "Moderator",
          "text": "User Giannis, thank you for sharing more about your project. It sounds like you're facing some interesting challenges in terms of balancing gameplay and mechanics. Can you tell us a bit more about what specific areas you're struggling with? For example, are you having trouble with character movement, puzzle-solving, or perhaps something else?\n\nAlso, I'd like to invite Emma35 to continue the conversation. As a nurse, her perspective on the complexities of balancing multiple systems and finding solutions that work for everyone is",
          "model": "test_model"
        },
        {
          "name": "Giannis",
          "text": "Thanks for having me, Moderator. I'm happy to share more about my project. To be honest, I'm having a bit of trouble with the balance between exploration and combat mechanics. I want the player to feel like they can explore the world without feeling overwhelmed by the combat system, but at the same time, I want the combat to be challenging and rewarding.\n\nSpecifically, I'm struggling with finding the right ratio of exploration time to combat time. If the player spends too much time fighting,",
          "model": "test_model"
        },
        {
          "name": "Moderator",
          "text": "User Moderator posted:\nUser Giannis, that's a great starting point. Balancing exploration and combat can be a delicate dance. Can you tell us more about what you've tried so far to achieve this balance? For example, have you experimented with different combat mechanics, such as difficulty scaling, enemy AI, or player abilities? Have you also considered implementing a \"rest\" or \"regeneration\" system to give players a break from combat? We'd also like to hear from Emma35, who",
          "model": "test_model"
        }
      ]
    }

Congratulations, you can now run fully synthetic discussions! You may want to experiment with adding more than 2 users or testing more realistic turn taking procedures (for example, check out the `RandomWeighted` turn manager).