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)¶
Bases:
object
An abstract class representing an actor which responds according to an underlying LLM instance.
- describe() dict ¶
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(*values)¶
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 = ''¶
- classmethod from_json_file() 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) 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) – 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.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
- 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 get_name() str ¶
Get the model’s assigned pseudoname.
- Returns:
The name of the model.
- 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.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.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