syndisco package — SynDisco 1.0.0 documentation

# syndisco package

## Subpackages

- syndisco.backend package
  - Submodules
  - syndisco.backend.actors module
    - `ActorType`
      - `ActorType.ANNOTATOR`
      - `ActorType.USER`
    - `LLMActor`
      - `LLMActor.describe()`
      - `LLMActor.get_name()`
      - `LLMActor.speak()`
    - `create_users()`
    - `create_users_from_file()`
  - syndisco.backend.model module
    - `BaseModel`
      - `BaseModel.generate_response()`
      - `BaseModel.prompt()`
    - `TransformersModel`
      - `TransformersModel.generate_response()`
  - syndisco.backend.persona module
    - `LLMPersona`
      - `LLMPersona.age`
      - `LLMPersona.current_employment`
      - `LLMPersona.demographic_group`
      - `LLMPersona.education_level`
      - `LLMPersona.personality_characteristics`
      - `LLMPersona.sex`
      - `LLMPersona.sexual_orientation`
      - `LLMPersona.special_instructions`
      - `LLMPersona.to_attribute_list()`
      - `LLMPersona.to_json_file()`
      - `LLMPersona.username`
    - `from_json_file()`
  - syndisco.backend.turn_manager module
    - `RandomWeighted`
      - `RandomWeighted.DEFAULT_RESPOND_PROBABILITY`
    - `RoundRobbin`
    - `TurnManager`
      - `TurnManager.next()`
      - `TurnManager.set_names()`
  - Module contents
- syndisco.util package
  - Submodules
  - syndisco.util.file_util module
    - `dict_to_json()`
    - `ensure_parent_directories_exist()`
    - `generate_datetime_filename()`
    - `read_file()`
    - `read_files_from_directory()`
    - `read_json_file()`
  - syndisco.util.logging_util module
    - `logging_setup()`
    - `timing()`
  - syndisco.util.model_util module
    - `ModelManager`
      - `ModelManager.get()`
  - Module contents

## Submodules

## syndisco.experiments 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.experiments.AnnotationExperiment(annotators: list[LLMActor], history_ctx_len: int = 3, include_mod_comments: bool = True)

  Bases: `object`

  An Experiment where multiple synthetic discussions are annotated by LLM-based annotators.

  begin(discussions_dir: Path, output_dir: Path) → None

    Begin the annotation experiment by generating and executing annotation jobs. The results will be written as JSON files in the specified output directory.

class syndisco.experiments.DiscussionExperiment(users: list[LLMActor], seed_opinions: list[str] = [], moderator: LLMActor | 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 which creates, manages and executes multiple synthetic discussions.

  begin(discussions_output_dir: Path = PosixPath('output')) → None

    Begin the experiment by generating and executing a set of discussions. The results will be written as JSON files at the specified output directory

## syndisco.jobs 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.jobs.Annotation(annotator: LLMActor, 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[LLMActor], moderator: LLMActor | None = None, history_context_len: int = 5, conv_len: int = 5, seed_opinion: str = '', seed_opinion_user: str = '')

  Bases: `object`

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

  begin(verbose: bool = True) → None

    Begin the discussion between the actors.

    Parameters:

      verbose (bool, optional) – whether to print the messages on the screen as they are generated, defaults to True

    Raises:

      RuntimeError – if the object has already been used to generate a conversation

  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.postprocessing 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

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 optionally includes SDB information for annotators.

  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

## Module contents