syndisco package

Subpackages

• syndisco.backend package
  • Submodules
  • syndisco.backend.actors module
  • syndisco.backend.model module
  • syndisco.backend.persona module
  • syndisco.backend.turn_manager module
  • Module contents
• syndisco.util package
  • Submodules
  • syndisco.util.file_util module
  • syndisco.util.logging_util module
  • syndisco.util.model_util module
  • Module contents

Submodules

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[str] = [], 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_opinion: str = '', seed_opinion_username: 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

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

Module contents