syndisco.backend package — SynDisco 1.0.0 documentation

# syndisco.backend package

## Submodules

## syndisco.backend.actors module

SynDisco: Automated experiment creation and execution using only LLM agents Copyright (C) 2025 Dimitris Tsirmpas

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

You may contact the author at tsirbasdim@gmail.com

class syndisco.backend.actors.ActorType(*values)

  Bases: `Enum`

  The purpose of the LLMActor, used to determine proper prompt structure

  ANNOTATOR = 2
  USER = 1

class syndisco.backend.actors.LLMActor(model: BaseModel, name: str, attributes: list[str], context: str, instructions: str, actor_type: ActorType)

  Bases: `object`

  An abstract class representing an actor which responds according to an underlying LLM instance. The LLM instance can be of any type.

  describe()

    Get a description of the actor’s internals.

    Returns:

      A brief description of the actor

    Return type:

      str

  final get_name() → str

    Get the actor’s assigned name within the conversation.

    Returns:

      The name of the actor.

    Return type:

      str

  final speak(history: list[str]) → str

    Prompt the actor to speak, given a history of previous messages in the conversation.

    Parameters:

      history (list[str]) – A list of previous messages.

    Returns:

      The actor’s new message

    Return type:

      str

syndisco.backend.actors.create_users(llm: BaseModel, usernames: list[str], attributes: list[list[str]], context: str, instructions: str, actor_type: ActorType) → list[LLMActor]

  Create runtime LLMActor objects with the specified information.

  Parameters:

    - llm (model.BaseModel) – The LLM

    - usernames (list[str]) – A list of usernames for each of the users

    - attributes (list[list[str]]) – A list containing a list of personality/mood attributes for each user

    - context (str) – The context of the experiment

    - instructions (str) – The instructions given to all LLM users (not the moderator)

  Returns:

    A list of initialized LLMActors

  Return type:

    list[LLMActor]

syndisco.backend.actors.create_users_from_file(llm: BaseModel, persona_path: Path, instruction_path: Path, context: str, actor_type: ActorType) → list[LLMActor]

  Create a list of users by using information from files.

  Parameters:

    - llm (model.BaseModel) – The LLM

    - persona_path (Path) – The path to the JSON file containing the personas

    - instruction_path (Path) – The path to the file containing the user’s instructions

    - context (str) – The context of the experiment

  Returns:

    A list of initialized LLMActors

  Return type:

    list[LLMActor]

## syndisco.backend.model module

SynDisco: Automated experiment creation and execution using only LLM agents Copyright (C) 2025 Dimitris Tsirmpas

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

You may contact the author at tsirbasdim@gmail.com

class syndisco.backend.model.BaseModel(name: str, max_out_tokens: int, stop_list: list[str] | None = None)

  Bases: `ABC`

  Interface for all local LLM wrappers

  abstractmethod generate_response(json_prompt: tuple[Any, Any], stop_words) → str

    Model-specific method which generates the LLM’s response

    Parameters:

      - json_prompt (tuple[Any, Any]) – A tuple containing the system and user prompt. Could be strings, or a dictionary.

      - stop_words (list[str]) – Strings where the model should stop generating

    Returns:

      the model’s response

    Return type:

      str

  final prompt(json_prompt: tuple[Any, Any], stop_words: list[str]) → str

    Generate the model’s response based on a prompt.

    Parameters:

      - json_prompt (tuple[Any, Any]) – A tuple containing the system and user prompt. Could be strings, or a dictionary.

      - stop_words (list[str]) – Strings where the model should stop generating

    Returns:

      the model’s response

    Return type:

      str

class syndisco.backend.model.TransformersModel(model_path: str | Path, name: str, max_out_tokens: int, remove_string_list: list[str] | None = None)

  Bases: `BaseModel`

  A class encapsulating Transformers HuggingFace models.

  generate_response(json_prompt: tuple[Any, Any], stop_words: list[str]) → str

    Generate a response using the model’s chat template.

    Parameters:

      - chat_prompt – A list of dictionaries representing the chat history.

      - stop_words – A list of stop words to prevent overflow in responses.

## syndisco.backend.persona module

SynDisco: Automated experiment creation and execution using only LLM agents Copyright (C) 2025 Dimitris Tsirmpas

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

You may contact the author at tsirbasdim@gmail.com

class syndisco.backend.persona.LLMPersona(username: str, age: int, sex: str, sexual_orientation: str, demographic_group: str, current_employment: str, education_level: str, special_instructions: str, personality_characteristics: list[str])

  Bases: `object`

  A dataclass holding information about the synthetic persona of a LLM actor. Includes name, Sociodemographic Background, personality and special instructions.

  age: int
  current_employment: str
  demographic_group: str
  education_level: str
  personality_characteristics: list[str]
  sex: str
  sexual_orientation: str
  special_instructions: str
  to_attribute_list() → list[str]

    Turn the various attributes of a persona into a cohesive list of attributes.

  to_json_file(output_path: str) → None

    Serialize the data to a .json file.

    Parameters:

      output_path (str) – The path of the new file

  username: str

syndisco.backend.persona.from_json_file(file_path: Path) → list[LLMPersona]

  Generate a list of personas from a properly formatted persona JSON file.

  Parameters:

    file_path (Path) – the path to the JSON file containing the personas

  Returns:

    a list of LlmPersona objects for each of the file entries

  Return type:

    list[LlmPersona]

## syndisco.backend.turn_manager module

SynDisco: Automated experiment creation and execution using only LLM agents Copyright (C) 2025 Dimitris Tsirmpas

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

You may contact the author at tsirbasdim@gmail.com

class syndisco.backend.turn_manager.RandomWeighted(p_respond: float = -1, names: Iterable[str] | None = None)

  Bases: `TurnManager`

  Enable a participant to reply with a set probability, else randomly select another participant.

  DEFAULT_RESPOND_PROBABILITY = 0.5

class syndisco.backend.turn_manager.RoundRobbin(names: Iterable[str] | None = None)

  Bases: `TurnManager`

  A simple turn manager which gives priority to the next user in the queue.

class syndisco.backend.turn_manager.TurnManager(names: Iterable[str] | None = None)

  Bases: `Iterable`

  A class that handles which handles turns between users.

  final next() → str

    Get the username of the next speaker.

    Raises:

      ValueError – if no names have been provided from the constructor, or from the TurnManager.set() method

    Returns:

      the next speaker’s username

    Return type:

      str

  final set_names(names: Iterable[str]) → None

    Initialize the manager by providing the names of the users.

    Parameters:

      names (list[str]) – the usernames of the participants

## Module contents