dlgforge

Public package entrypoints for DialogForge.

This module defines the stable, top-level APIs intended for external callers.

HFPushOptions(repo_id='', repo_type='', source_dir='', export_dir='', include_run_state=False, token=None, commit_message='', prepare_export=True, push=True, clean_remote=False) dataclass

CLI override options for export/push operations.

Parameters:

Name	Type	Description	Default
repo_id	str	str value used by this operation.	''
repo_type	str	str value used by this operation.	''
source_dir	str	str value used by this operation.	''
export_dir	str	str value used by this operation.	''
include_run_state	bool	bool value used by this operation.	False
token	Optional[str]	Optional[str] value used by this operation.	None
commit_message	str	str value used by this operation.	''
prepare_export	bool	Boolean flag that controls optional behavior.	True
push	bool	Boolean flag that controls optional behavior.	True
clean_remote	bool	Boolean flag that controls optional behavior.	False

Raises:

Type	Description
Exception	Construction may raise when required dependencies or inputs are invalid.

Side Effects / I/O: - May read from or write to local filesystem artifacts. - May perform network, model, or distributed runtime operations.

Preconditions / Invariants: - Instantiate and use through documented public methods.

Examples:

>>> from dlgforge.pipeline.hf_push import HFPushOptions
>>> HFPushOptions(...)

run_push(config_path, options)

Prepare export artifacts and optionally push them to the Hub.

Parameters:

Name	Type	Description	Default
config_path	str	Path to a configuration file.	required
options	HFPushOptions	Configuration mapping that controls runtime behavior.	required

Returns:

Name	Type	Description
None	None	No value is returned.

Raises:

Type	Description
FileNotFoundError	Raised when validation or runtime requirements are not met.

Side Effects / I/O: - May read from or write to local filesystem artifacts. - May perform network, model, or distributed runtime operations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.pipeline.hf_push import run_push
>>> run_push(...)

run(config_path)

Run synthetic conversation generation from a config file.

Parameters:

Name	Type	Description	Default
config_path	str	Path to a configuration file.	required

Returns:

Name	Type	Description
None	None	No value is returned.

Raises:

Type	Description
FileNotFoundError	Raised when validation or runtime requirements are not met.

Side Effects / I/O: - May perform network, model, or distributed runtime operations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.pipeline.runner import run
>>> run(...)

run_judge_only(config_path)

Run judge evaluation on existing conversation artifacts.

Parameters:

Name	Type	Description	Default
config_path	str	Path to a configuration file.	required

Returns:

Name	Type	Description
None	None	No value is returned.

Raises:

Type	Description
FileNotFoundError	Raised when validation or runtime requirements are not met.
RuntimeError	Raised when validation or runtime requirements are not met.

Side Effects / I/O: - May perform network, model, or distributed runtime operations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.pipeline.runner import run_judge_only
>>> run_judge_only(...)

run_seeds_migrate(config_path, source_file='', dest_file='', overwrite=False)

Run seed-topic migration using project config defaults.

The command resolves source and destination paths from CLI overrides first, then from config, then from repository defaults.

Parameters:

Name	Type	Description	Default
config_path	str	Path to a configuration file.	required
source_file	str	Optional source seed file override (JSON or YAML).	''
dest_file	str	Optional destination YAML path override.	''
overwrite	bool	Whether to overwrite an existing destination file.	False

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Migration summary with source path, destination path,
Dict[str, Any]	variant list, and topic counts.

Raises:

Type	Description
FileNotFoundError	If config_path or the resolved source file does not exist.
ValueError	If the resolved source path points to a directory.

Side Effects / I/O: - Reads config and source files from disk. - Writes migrated YAML output to disk. - Writes log entries.

Examples:

>>> from dlgforge.pipeline.seed_topics_migration import run_seeds_migrate
>>> run_seeds_migrate(...)