dlgforge.pipeline.seed_topics_migration

Seed-topic migration utilities for legacy topic files.

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(...)

migrate_seed_topics_file(source_file, destination_file, overwrite=False)

Convert a legacy seed-topic file into canonical YAML format.

Parameters:

Name	Type	Description	Default
source_file	Path	Legacy source file containing seed topics.	required
destination_file	Path	Output path for canonical YAML.	required
overwrite	bool	Whether to overwrite destination_file if it exists.	False

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Migration summary with written files, variants, and topic
Dict[str, Any]	counts.

Raises:

Type	Description
ValueError	If source data is not a mapping or has no valid topics.
FileExistsError	If destination exists and overwrite is False.

Side Effects / I/O: - Reads source content from disk. - Creates destination parent directories as needed. - Writes canonical YAML to destination_file.

Examples:

>>> from pathlib import Path
>>> from dlgforge.pipeline.seed_topics_migration import migrate_seed_topics_file
>>> migrate_seed_topics_file(Path("seed_topics.json"), Path("data/seeds/topics.yaml"), overwrite=True)