API Reference

This page provides detailed documentation for the public API of WizardSData.

Configuration Functions

set_config

wizardsdata.set_config(**kwargs) → List[str]

Set global configuration parameters and validate the resulting configuration.

This function provides a convenient interface to set parameters in the global Config instance. After setting the provided parameters, it automatically validates the configuration and returns any validation errors.

Parameters:

• **kwargs – Key-value pairs for configuration parameters.

• Parameters (Configuration)

• API_KEY (str) – API key for accessing external language model services.

• template_client_prompt (str) – File path to the template used for client prompts.

• template_advisor_prompt (str) – File path to the template used for advisor prompts.

• file_profiles (str) – File path to the JSON containing conversation profiles.

• file_output (str) – File path where generated conversations will be saved.

• model_client (dict) – Model configuration for client responses.

• model_advisor (dict) – Model configuration for advisor responses.

• defaults (Optional parameters with)

• temperature_client (float) – Temperature for client model sampling (default: 0.7).

• top_p_client (float) – Top-p value for client model sampling (default: 0.95).

• frequency_penalty_client (float) – Frequency penalty for client model (default: 0.3).

• max_tokens_client (int) – Maximum tokens for client responses (default: 175).

• max_recommended_questions (int) – Maximum recommended questions to generate (default: 10).

• temperature_advisor (float) – Temperature for advisor model sampling (default: 0.5).

• top_p_advisor (float) – Top-p value for advisor model sampling (default: 0.9).

• frequency_penalty_advisor (float) – Frequency penalty for advisor model (default: 0.1).

• max_tokens_advisor (int) – Maximum tokens for advisor responses (default: 325).

Returns:

A list of validation errors. Empty list if configuration is valid.

Return type:

List[str]

Examples

>>> # Setting only partial mandatory parameters will return validation errors
>>> errors = set_config(API_KEY="my-api-key",
...                     template_client_prompt="templates/client.txt")
>>> if errors:
...     print(f"Configuration is incomplete: {errors}")
...     # Output: Configuration is incomplete: ['template_advisor_prompt', 'file_profiles', 'file_output', 'model_client', 'model_advisor']
>>>
>>> # Setting all mandatory parameters for a valid configuration
>>> errors = set_config(
...     API_KEY="my-api-key",
...     template_client_prompt="templates/client.txt",
...     template_advisor_prompt="templates/advisor.txt",
...     file_profiles="data/profiles.json",
...     file_output="output/conversations.json",
...     model_client={"name": "gpt-4"},
...     model_advisor={"name": "gpt-4"}
... )
>>> if not errors:
...     print("Configuration is valid!")

Notes

• This updates only the parameters specified in kwargs; other parameters

retain their current values. - See the Config class for a complete list of valid parameters.

get_config

wizardsdata.get_config() → Dict[str, Any]

Get the current global configuration.

This function retrieves all current configuration parameters from the global Config instance, including both explicitly set values and default values.

Returns:

Dictionary with all configuration parameters.

Return type:

Dict[str, Any]

Examples

>>> full_config = get_config()
>>> print(f"Client temperature: {full_config['temperature_client']}")
>>>
>>> # Get specific parameters directly from the config instance
>>> from wizardsdata.config import config
>>> print(f"API Key: {config.get('API_KEY')}")

is_config_valid

wizardsdata.is_config_valid() → bool

Check if the current global configuration is valid.

This function checks if all mandatory parameters are set and if specified file paths exist.

Returns:

True if the configuration is valid, False otherwise.

Return type:

bool

Examples

>>> if not is_config_valid():
...     print("Please set all required configuration parameters")
...     # Show what's missing
...     from wizardsdata.config import config
...     print(f"Missing: {config.validate()}")

Notes

• Mandatory parameters are defined in Config.MANDATORY_PARAMS

• The function also checks if specified file paths exist

save_config

wizardsdata.save_config(file_path: str) → bool

Save the current global configuration to a JSON file.

This function exports all configuration parameters (including defaults) to a specified JSON file for later reuse.

Parameters:

file_path (str) – Path where the configuration file will be saved.

Returns:

True if the save operation was successful, False otherwise.

Return type:

bool

Examples

>>> success = save_config("config/my_project_config.json")
>>> if success:
...     print("Configuration saved successfully!")
... else:
...     print("Failed to save configuration")

Notes

• The saved file uses JSON format with 4-space indentation

• Both explicitly set and default values are saved

load_config

wizardsdata.load_config(file_path: str) → bool

Load a configuration from a JSON file into the global config instance.

This function reads a previously saved configuration file and updates the global Config instance with those values.

Parameters:

file_path (str) – Path to the configuration JSON file.

Returns:

True if the load operation was successful, False otherwise.

Return type:

bool

Examples

>>> success = load_config("config/my_project_config.json")
>>> if success:
...     print("Configuration loaded successfully!")
...     # Check if it's complete
...     if is_config_valid():
...         print("And it's valid!")
... else:
...     print("Failed to load configuration")

Notes

• This overwrites any previously set parameters with values from the file

• Parameters not specified in the file retain their current values

• The function silently catches and handles any exceptions during loading.

Generation Functions

start_generation

wizardsdata.start_generation() → bool

Start generating conversations between roles based on the current configuration.

This function orchestrates the entire conversation generation process. It: 1. Validates the current configuration 2. Initializes the API clients 3. Loads conversation profiles from the configured file 4. Renders prompts for each profile 5. Generates conversations for each profile using the appropriate models 6. Saves all conversations to the configured output file

The function relies on the global configuration instance having all necessary parameters properly set.

Returns:

True if the generation process completed successfully, False otherwise. Returns False in the following cases: - Invalid configuration (missing parameters) - No profiles found in the profile file - Failure to render prompts - Error during API calls - Failure to save conversations

Return type:

bool

Notes

Before calling this function, ensure all required configuration parameters are set: - API_KEY: Required for API access - template_client_prompt: Path to client prompt template - template_advisor_prompt: Path to advisor prompt template - file_profiles: Path to JSON file containing conversation profiles - file_output: Path where generated conversations will be saved - model_client: Model configuration for client responses - model_advisor: Model configuration for advisor responses

The function will log progress and error information to standard output.

Examples

>>> from wizardsdata.config import set_config
>>> from wizardsdata.generator import start_generation
>>>
>>> # Set up configuration
>>> errors = set_config(
...     API_KEY="your-api-key",
...     template_client_prompt="templates/client.txt",
...     template_advisor_prompt="templates/advisor.txt",
...     file_profiles="data/profiles.json",
...     file_output="output/conversations.json",
...     model_client="gpt-4",
...     model_advisor="gpt-4"
... )
>>>
>>> if not errors:
...     # Start generation
...     success = start_generation()
...     if success:
...         print("Generation completed successfully!")
...     else:
...         print("Generation failed.")
... else:
...     print(f"Invalid configuration: {errors}")

Module Details

Config Module

class wizardsdata.config.Config

Bases: object

Configuration manager for the WizardSData conversation generation system. This class handles all configuration parameters needed for generating conversations between clients and advisors, providing methods for setting, retrieving, and validating configuration values. :ivar MANDATORY_PARAMS: Required configuration parameters that must be set before use. :vartype MANDATORY_PARAMS: set :ivar DEFAULT_CONFIG: Default values for optional parameters. :vartype DEFAULT_CONFIG: dict

Configuration Parameters:

API_KEY (str): API key for accessing external language model services. template_client_prompt (str): File path to the template used for client prompts. template_advisor_prompt (str): File path to the template used for advisor prompts. file_profiles (str): File path to the JSON containing conversation profiles. file_output (str): File path where generated conversations will be saved. model_client (dict): Model configuration for client responses. model_advisor (dict): Model configuration for advisor responses. Optional parameters with defaults: temperature_client (float): Temperature for client model sampling (default: 0.7). top_p_client (float): Top-p value for client model sampling (default: 0.95). frequency_penalty_client (float): Frequency penalty for client model (default: 0.3). max_tokens_client (int): Maximum tokens for client responses (default: 175). max_recommended_questions (int): Maximum recommended questions to generate (default: 10). temperature_advisor (float): Temperature for advisor model sampling (default: 0.5). top_p_advisor (float): Top-p value for advisor model sampling (default: 0.9). frequency_penalty_advisor (float): Frequency penalty for advisor model (default: 0.1). max_tokens_advisor (int): Maximum tokens for advisor responses (default: 325).

Examples

>>> config = Config()
>>> config.set(API_KEY="your-api-key",
...           template_client_prompt="path/to/client_template.txt",
...           template_advisor_prompt="path/to/advisor_template.txt",
...           file_profiles="path/to/profiles.json",
...           file_output="path/to/output.json",
...           model_client={"name": "gpt-4"},
...           model_advisor={"name": "gpt-4"})
>>> if config.is_valid():
...     print("Configuration is valid!")
... else:
...     print(f"Missing parameters: {config.validate()}")
# Get specific configuration parameters
>>> client_temp = config.get("temperature_client")
>>> all_params = config.get_all()

Notes

• The validate() method checks if all mandatory parameters are set and if specified file paths exist.

• Configuration parameters can be overridden by calling set() multiple times.

Initialize the configuration with default values. This method initializes a new configuration object with the following steps: 1. Creates an empty configuration dictionary (_config) 2. Populates it with default values:

# Client configuration ‘temperature_client’: 0.7, ‘top_p_client’: 0.95, ‘frequency_penalty_client’: 0.3, ‘max_tokens_client’: 175, ‘max_recommended_questions’: 10,

# Advisor configuration ‘temperature_advisor’: 0.5, ‘top_p_advisor’: 0.9, ‘frequency_penalty_advisor’: 0.1, ‘max_tokens_advisor’: 325,

3. Initializes an empty set to track which parameters have been explicitly set by the user (_set_params)

No parameters are required as it uses class-defined defaults. :returns: None

MANDATORY_PARAMS = {'API_KEY', 'file_output', 'file_profiles', 'model_advisor', 'model_client', 'template_advisor_prompt', 'template_client_prompt'}

DEFAULT_CONFIG = {'frequency_penalty_advisor': 0.1, 'frequency_penalty_client': 0.3, 'max_recommended_questions': 10, 'max_tokens_advisor': 325, 'max_tokens_client': 175, 'temperature_advisor': 0.5, 'temperature_client': 0.7, 'top_p_advisor': 0.9, 'top_p_client': 0.95}

set(**kwargs) → None

Set a configuration parameter

get(param: str, default: Any = None) → Any

Get a configuration parameter.

Parameters:

• param – Parameter name.

• default – Default value if parameter doesn’t exist.

Returns:

The parameter value or the default value.

get_all() → Dict[str, Any]

Get all configuration parameters.

Returns:

Dictionary with all parameters.

validate() → List[str]

Validate the configuration.

Returns:

List of missing mandatory parameters.

is_valid() → bool

Check if configuration is valid.

Returns:

True if valid, False otherwise.

wizardsdata.config.set_config(**kwargs) → List[str]

Set global configuration parameters and validate the resulting configuration.

This function provides a convenient interface to set parameters in the global Config instance. After setting the provided parameters, it automatically validates the configuration and returns any validation errors.

Parameters:

• **kwargs – Key-value pairs for configuration parameters.

• Parameters (Configuration)

• API_KEY (str) – API key for accessing external language model services.

• template_client_prompt (str) – File path to the template used for client prompts.

• template_advisor_prompt (str) – File path to the template used for advisor prompts.

• file_profiles (str) – File path to the JSON containing conversation profiles.

• file_output (str) – File path where generated conversations will be saved.

• model_client (dict) – Model configuration for client responses.

• model_advisor (dict) – Model configuration for advisor responses.

• defaults (Optional parameters with)

• temperature_client (float) – Temperature for client model sampling (default: 0.7).

• top_p_client (float) – Top-p value for client model sampling (default: 0.95).

• frequency_penalty_client (float) – Frequency penalty for client model (default: 0.3).

• max_tokens_client (int) – Maximum tokens for client responses (default: 175).

• max_recommended_questions (int) – Maximum recommended questions to generate (default: 10).

• temperature_advisor (float) – Temperature for advisor model sampling (default: 0.5).

• top_p_advisor (float) – Top-p value for advisor model sampling (default: 0.9).

• frequency_penalty_advisor (float) – Frequency penalty for advisor model (default: 0.1).

• max_tokens_advisor (int) – Maximum tokens for advisor responses (default: 325).

Returns:

A list of validation errors. Empty list if configuration is valid.

Return type:

List[str]

Examples

>>> # Setting only partial mandatory parameters will return validation errors
>>> errors = set_config(API_KEY="my-api-key",
...                     template_client_prompt="templates/client.txt")
>>> if errors:
...     print(f"Configuration is incomplete: {errors}")
...     # Output: Configuration is incomplete: ['template_advisor_prompt', 'file_profiles', 'file_output', 'model_client', 'model_advisor']
>>>
>>> # Setting all mandatory parameters for a valid configuration
>>> errors = set_config(
...     API_KEY="my-api-key",
...     template_client_prompt="templates/client.txt",
...     template_advisor_prompt="templates/advisor.txt",
...     file_profiles="data/profiles.json",
...     file_output="output/conversations.json",
...     model_client={"name": "gpt-4"},
...     model_advisor={"name": "gpt-4"}
... )
>>> if not errors:
...     print("Configuration is valid!")

Notes

• This updates only the parameters specified in kwargs; other parameters

retain their current values. - See the Config class for a complete list of valid parameters.

wizardsdata.config.get_config() → Dict[str, Any]

Get the current global configuration.

This function retrieves all current configuration parameters from the global Config instance, including both explicitly set values and default values.

Returns:

Dictionary with all configuration parameters.

Return type:

Dict[str, Any]

Examples

>>> full_config = get_config()
>>> print(f"Client temperature: {full_config['temperature_client']}")
>>>
>>> # Get specific parameters directly from the config instance
>>> from wizardsdata.config import config
>>> print(f"API Key: {config.get('API_KEY')}")

wizardsdata.config.is_config_valid() → bool

Check if the current global configuration is valid.

This function checks if all mandatory parameters are set and if specified file paths exist.

Returns:

True if the configuration is valid, False otherwise.

Return type:

bool

Examples

>>> if not is_config_valid():
...     print("Please set all required configuration parameters")
...     # Show what's missing
...     from wizardsdata.config import config
...     print(f"Missing: {config.validate()}")

Notes

• Mandatory parameters are defined in Config.MANDATORY_PARAMS

• The function also checks if specified file paths exist

wizardsdata.config.save_config(file_path: str) → bool

Save the current global configuration to a JSON file.

This function exports all configuration parameters (including defaults) to a specified JSON file for later reuse.

Parameters:

file_path (str) – Path where the configuration file will be saved.

Returns:

True if the save operation was successful, False otherwise.

Return type:

bool

Examples

>>> success = save_config("config/my_project_config.json")
>>> if success:
...     print("Configuration saved successfully!")
... else:
...     print("Failed to save configuration")

Notes

• The saved file uses JSON format with 4-space indentation

• Both explicitly set and default values are saved

wizardsdata.config.load_config(file_path: str) → bool

Load a configuration from a JSON file into the global config instance.

This function reads a previously saved configuration file and updates the global Config instance with those values.

Parameters:

file_path (str) – Path to the configuration JSON file.

Returns:

True if the load operation was successful, False otherwise.

Return type:

bool

Examples

>>> success = load_config("config/my_project_config.json")
>>> if success:
...     print("Configuration loaded successfully!")
...     # Check if it's complete
...     if is_config_valid():
...         print("And it's valid!")
... else:
...     print("Failed to load configuration")

Notes

• This overwrites any previously set parameters with values from the file

• Parameters not specified in the file retain their current values

• The function silently catches and handles any exceptions during loading.

Generator Module

Conversation generator for WizardSData.

wizardsdata.generator.initialize_apis(api_key: str | None = None) → tuple

Initialize API clients for OpenAI.

Parameters:

api_key – Optional API key to use. If None, uses the one from config.

Returns:

Tuple with (client_api, advisor_api)

wizardsdata.generator.get_model_response(api_client, model: str, messages: List[Dict[str, str]], temperature: float, top_p: float, frequency_penalty: float, max_tokens: int | None) → str

Get response from a model using the OpenAI API.

Parameters:

• api_client – OpenAI client instance.

• model – Model name to use.

• messages – List of message dictionaries (role and content).

• temperature – Temperature setting for response randomness.

• top_p – Top p setting for response diversity.

• frequency_penalty – Frequency penalty to apply.

• max_tokens – Maximum number of tokens to generate.

Returns:

The generated response as a string.

wizardsdata.generator.save_conversation(conversations: List[Dict[str, Any]], file_path: str) → bool

Save the conversation dataset to a JSON file.

Parameters:

• conversations – List of conversation dictionaries.

• file_path – Path to save the conversations.

Returns:

True if successful, False otherwise.

wizardsdata.generator.initiate_conversation(client_prompt: str, advisor_prompt: str, financial_goal: str, client_api, advisor_api, max_questions: int) → List[Dict[str, Any]]

Initiate a continuous conversation between client and advisor models.

Parameters:

• client_prompt – System prompt for the client model.

• advisor_prompt – System prompt for the advisor model.

• financial_goal – Financial goal for this conversation.

• client_api – OpenAI client for the client model.

• advisor_api – OpenAI client for the advisor model.

• max_questions – Maximum number of interactions.

Returns:

List of dictionaries representing the conversation.

wizardsdata.generator.start_generation() → bool

Start generating conversations between roles based on the current configuration.

This function orchestrates the entire conversation generation process. It: 1. Validates the current configuration 2. Initializes the API clients 3. Loads conversation profiles from the configured file 4. Renders prompts for each profile 5. Generates conversations for each profile using the appropriate models 6. Saves all conversations to the configured output file

The function relies on the global configuration instance having all necessary parameters properly set.

Returns:

True if the generation process completed successfully, False otherwise. Returns False in the following cases: - Invalid configuration (missing parameters) - No profiles found in the profile file - Failure to render prompts - Error during API calls - Failure to save conversations

Return type:

bool

Notes

Before calling this function, ensure all required configuration parameters are set: - API_KEY: Required for API access - template_client_prompt: Path to client prompt template - template_advisor_prompt: Path to advisor prompt template - file_profiles: Path to JSON file containing conversation profiles - file_output: Path where generated conversations will be saved - model_client: Model configuration for client responses - model_advisor: Model configuration for advisor responses

The function will log progress and error information to standard output.

Examples

>>> from wizardsdata.config import set_config
>>> from wizardsdata.generator import start_generation
>>>
>>> # Set up configuration
>>> errors = set_config(
...     API_KEY="your-api-key",
...     template_client_prompt="templates/client.txt",
...     template_advisor_prompt="templates/advisor.txt",
...     file_profiles="data/profiles.json",
...     file_output="output/conversations.json",
...     model_client="gpt-4",
...     model_advisor="gpt-4"
... )
>>>
>>> if not errors:
...     # Start generation
...     success = start_generation()
...     if success:
...         print("Generation completed successfully!")
...     else:
...         print("Generation failed.")
... else:
...     print(f"Invalid configuration: {errors}")

Templates Module

Template handling for WizardSData.

wizardsdata.templates.render_prompt_from_path(template_path: str, profile: Dict[str, Any], **kwargs) → str

Render a prompt template from a specific file path with the given profile and additional variables.

Parameters:

• template_path – Path to the template file.

• profile – Dictionary with profile data.

• **kwargs – Additional variables to use in the template.

Returns:

The rendered template as a string, or empty string if failed.

Utilities Module

Utility functions for WizardSData.

wizardsdata.utils.ensure_directory_exists(file_path: str) → bool

Ensure the directory for a file exists, creating it if necessary.

Parameters:

file_path – Path to the file.

Returns:

True if directory exists or was created, False otherwise.

wizardsdata.utils.load_json(file_path: str) → Dict[str, Any] | None

Load JSON data from a file.

Parameters:

file_path – Path to the JSON file.

Returns:

Dictionary with JSON data, or None if failed.

wizardsdata.utils.save_json(data: Any, file_path: str) → bool

Save data to a JSON file.

Parameters:

• data – Data to save.

• file_path – Path to save the JSON file.

Returns:

True if successful, False otherwise.

CLI Module

Command-line interface for WizardSData.

wizardsdata.cli.parse_args()

Parse command line arguments.

wizardsdata.cli.clean_args(args_dict: Dict[str, Any]) → Dict[str, Any]

Clean argument dictionary by removing None values.

wizardsdata.cli.main()

Run the command-line interface.