syndisco package — SynDisco 2.0.4 documentation

# syndisco package

## Submodules

## syndisco.actors module

Module defining LLM users in discussions and their characteristics.

class syndisco.actors.Actor(model: BaseModel, persona: Persona, context: str, instructions: str, actor_type: ActorType, stop_words: list[str] = [])

  Bases: `object`

  An abstract class representing an actor which responds according to an underlying LLM instance.

  describe() → str

    Get a description of the actor’s internals.

    Returns:

      A brief description of the actor

    Return type:

      dict

  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

class syndisco.actors.ActorType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Bases: `str`, `Enum`

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

  ANNOTATOR = '2'
  USER = '1'

class syndisco.actors.Persona(username: str = '', age: int = -1, sex: str = '', sexual_orientation: str = '', demographic_group: str = '', current_employment: str = '', education_level: str = '', special_instructions: str = '', personality_characteristics: list[str] = <factory>)

  Bases: `object`

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

  age: int = -1
  current_employment: str = ''
  demographic_group: str = ''
  education_level: str = ''
  static from_json_file(file_path: Path) → list

    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]

  personality_characteristics: list[str]
  sex: str = ''
  sexual_orientation: str = ''
  special_instructions: str = ''
  to_dict()
  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.experiments module

Module automating and managing batches of discussion/annotation tasks defined in the syndisco.jobs module.

class syndisco.experiments.AnnotationExperiment(annotators: list[Actor], history_ctx_len: int = 3, include_mod_comments: bool = True)

  Bases: `object`

  An experiment that uses LLM annotators to label synthetic discussion logs.

  begin(discussions_dir: Path, output_dir: Path, verbose: bool = True) → None

    Start the annotation process over all discussion logs in a directory.

    Parameters:

      - discussions_dir (Path) – Directory containing discussion logs.

      - output_dir (Path) – Directory to write annotation outputs.

      - verbose (bool, defaults to True) – Whether to display annotation progress.

class syndisco.experiments.DiscussionExperiment(users: list[Actor], seed_opinions: list[list[str]] | None = None, moderator: Actor | None = None, next_turn_manager: TurnManager | None = None, history_ctx_len: int = 3, num_turns: int = 10, num_active_users: int = 2, num_discussions: int = 5)

  Bases: `object`

  An experiment that creates, manages, and executes multiple synthetic discussions using LLM-based agents.

  begin(discussions_output_dir: Path = PosixPath('output'), verbose: bool = True) → None

    Generate and run all configured discussions.

    Parameters:

      - discussions_output_dir (Path) – Directory to write output JSON files.

      - verbose (bool) – Whether to print intermediate progress and outputs.

## syndisco.jobs module

Module handling the execution of LLM discussion and annotation tasks.

class syndisco.jobs.Annotation(annotator: Actor, conv_logs_path: str | Path, include_moderator_comments: bool, history_ctx_len: int = 2)

  Bases: `object`

  An annotation job modelled as a discussion between the system writing the logs of a finished discussion, and the LLM Annotator.

  begin(verbose=True) → None

    Begin the conversation-modelled annotation job.

    Parameters:

      verbose (bool, optional) – whether to print the results of the annotation to the console, defaults to True

  to_dict(timestamp_format: str = '%y-%m-%d-%H-%M') → dict[str, Any]

    Get a dictionary view of the data and metadata contained in the annotation.

    Parameters:

      timestamp_format (str, optional) – the format for the conversation’s creation time, defaults to “%y-%m-%d-%H-%M”

    Returns:

      a dict representing the conversation

    Return type:

      dict[str, Any]

  to_json_file(output_path: str | Path) → None

    Export the data and metadata of the conversation as a json file.

    Parameters:

      output_path (str) – the path for the exported file

class syndisco.jobs.Discussion(next_turn_manager: TurnManager, users: list[Actor], moderator: Actor | None = None, history_context_len: int = 5, conv_len: int = 5, seed_opinions: list[str] | None = None, seed_opinion_usernames: list[str] | None = None)

  Bases: `object`

  A job conducting a discussion between different actors (`actors.Actor`).

  begin(verbose: bool = True) → None
  to_dict(timestamp_format: str = '%y-%m-%d-%H-%M') → dict[str, Any]

    Get a dictionary view of the data and metadata contained in the discussion.

    Parameters:

      timestamp_format (str, optional) – the format for the conversation’s creation time, defaults to “%y-%m-%d-%H-%M”

    Returns:

      a dict representing the conversation

    Return type:

      dict[str, Any]

  to_json_file(output_path: str | Path) → None

    Export the data and metadata of the conversation as a json file.

    Parameters:

      output_path (str) – the path for the exported file

## syndisco.logging_util module

Module handling logging for LLM discussion and annotation tasks.

syndisco.logging_util.logging_setup(print_to_terminal: bool, write_to_file: bool, logs_dir: str | Path | None = None, level: str = 'debug', use_colors: bool = True, log_warnings: bool = True) → None

  Create the logger configuration.

  Parameters:

    - print_to_terminal (bool) – whether to print logs to the screen

    - write_to_file (bool) – whether to write logs to a file. Needs logs_dir to be specified.

    - logs_dir (Optional[str | Path], optional) – the directory where the logs will be placed, defaults to None

    - level – the logging level, defaults to logging.DEBUG

    - use_colors (bool, defaults to True) – whether to color the output.

    - log_warnings (bool, defaults to True) – whether to log library warnings

syndisco.logging_util.timing(f: Callable) → Any

  Decorator which logs the execution time of a function.

  Parameters:

    f (Function) – the function to be timed

  Returns:

    the result of the function

  Return type:

    _type_

## syndisco.model module

Module containing wrappers for local LLMs loaded with various Python libraries.

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

  Bases: `ABC`

  Interface for all local LLM wrappers

  final get_name() → str

    Get the model’s assigned pseudoname.

    Returns:

      The name of the model.

    Return type:

      str

  final prompt(system_prompt: str, user_prompt: str) → str

    Generate the model’s response based on a prompt.

    Parameters:

      - system_prompt (str) – The system prompt.

      - user_prompt (str) – The user prompt.

      - stop_words (list[str]) – Strings to be removed after generation.

    Returns:

      the model’s response

    Return type:

      str

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

  Bases: `BaseModel`

  HuggingFace Transformers model wrapper.

## syndisco.postprocessing module

Module responsible for exporting discussions and their annotations in CSV format.

syndisco.postprocessing.import_annotations(annot_dir: str | Path) → DataFrame

  Import annotation data from JSON files in a directory and process it into a DataFrame.

  This function reads JSON files containing annotation data, processes the data to standardize columns, and includes structured user traits.

  Parameters:

    annot_dir (str | Path) – Directory containing JSON files with annotation data.

  Returns:

    A DataFrame containing processed annotation data.

  Return type:

    pd.DataFrame

syndisco.postprocessing.import_discussions(conv_dir: Path) → DataFrame
  Import discussion output (logs) from JSON files in a directory and process

    it into a DataFrame.

  This function reads JSON files containing conversation data, processes the

    data to

  standardize columns, and adds derived attributes such as user traits and

    prompts.

  Parameters:

    conv_dir (str | Path) – Directory containing JSON files with conversation data.

  Returns:

    A DataFrame containing processed conversation data.

  Return type:

    pd.DataFrame

## syndisco.turn_manager module

Module handling the turn order of LLM participants in discussions.

class syndisco.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.turn_manager.RoundRobin(names: Iterable[str] | None = None)

  Bases: `TurnManager`

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

class syndisco.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 (Iterable[str]) – the usernames of the participants

## Module contents