dlgforge.config.personas

Persona loading, formatting, and sampling utilities.

UniformPersonaSampler(user_personas, assistant_personas, rng)

Cycle-based sampler for user/assistant personas.

The sampler shuffles each persona pool and pops items until exhausted, then reshuffles. This prevents early repetition while keeping distribution near uniform over long runs.

Parameters:

Name	Type	Description	Default
user_personas	List[Dict[str, Any]]	User persona records.	required
assistant_personas	List[Dict[str, Any]]	Assistant persona records.	required
rng	Random	Random generator used for deterministic shuffling.	required

Side Effects / I/O: - Mutates internal in-memory cycles as samples are drawn.

Preconditions / Invariants: - Persona entries are expected to be mapping-like objects. - Empty pools are supported and return empty persona text/ids.

Examples:

>>> from dlgforge.config.personas import UniformPersonaSampler
>>> import random
>>> sampler = UniformPersonaSampler([{"id": "u1"}], [{"id": "a1"}], random.Random(7))
>>> sampler.sample()[2]["user_id"]
'u1'

sample()

Sample one user persona and one assistant persona.

Returns:

Type	Description
str	Tuple[str, str, Dict[str, str]]: `(user_text, assistant_text,
str	metadata)wheremetadataincludesuser_idandassistant_id`.

Side Effects / I/O: - Advances in-memory sampling cycles.

Examples:

>>> from dlgforge.config.personas import UniformPersonaSampler
>>> import random
>>> sampler = UniformPersonaSampler([{"id": "u1"}], [{"id": "a1"}], random.Random(0))
>>> sample = sampler.sample()
>>> sample[2]["assistant_id"]
'a1'

select_personas(cfg, project_root, config_path)

Select one user persona and one assistant persona for a conversation.

Returns empty values when personas are disabled.

Parameters:

Name	Type	Description	Default
cfg	Dict[str, Any]	Loaded runtime configuration.	required
project_root	Path	Project root used for resolving relative paths.	required
config_path	Path	Path to the active config file.	required

Returns:

Type	Description
str	Tuple[str, str, Dict[str, str]]: `(user_text, assistant_text,
str	metadata)` with selected persona ids in metadata.

Side Effects / I/O: - Reads persona files when persona loading is enabled.

Examples:

>>> from dlgforge.config.personas import select_personas
>>> select_personas(...)

resolve_personas_enabled(cfg)

Return whether persona sampling is enabled in configuration.

Parameters:

Name	Type	Description	Default
cfg	Dict[str, Any]	Loaded runtime configuration.	required

Returns:

Name	Type	Description
bool	bool	True when personas.enabled is truthy, otherwise False.

Examples:

>>> from dlgforge.config.personas import resolve_personas_enabled
>>> resolve_personas_enabled({"personas": {"enabled": True}})
True

resolve_personas_path(cfg)

Return the configured personas file path.

Parameters:

Name	Type	Description	Default
cfg	Dict[str, Any]	Loaded runtime configuration.	required

Returns:

Name	Type	Description
str	str	Raw value of personas.path, or an empty string when unset.

Examples:

>>> from dlgforge.config.personas import resolve_personas_path
>>> resolve_personas_path({"personas": {"path": "data/personas.yaml"}})
'data/personas.yaml'

resolve_question_seed(cfg)

Return the run-level question seed used for persona RNG initialization.

Parameters:

Name	Type	Description	Default
cfg	Dict[str, Any]	Loaded runtime configuration.	required

Returns:

Name	Type	Description
str	str	Value of run.question_seed, or an empty string when unset.

Examples:

>>> from dlgforge.config.personas import resolve_question_seed
>>> resolve_question_seed({"run": {"question_seed": "seed-1"}})
'seed-1'

build_persona_rng(cfg)

Build a deterministic RNG for persona selection.

Uses run.question_seed when present; otherwise falls back to current UTC timestamp for non-deterministic runs.

Parameters:

Name	Type	Description	Default
cfg	Dict[str, Any]	Loaded runtime configuration.	required

Returns:

Type	Description
Random	random.Random: RNG seeded with a persona-specific seed namespace.

Examples:

>>> from dlgforge.config.personas import build_persona_rng
>>> build_persona_rng(...)

build_uniform_persona_sampler(cfg, project_root, config_path)

Build a UniformPersonaSampler from config and persona assets.

Parameters:

Name	Type	Description	Default
cfg	Dict[str, Any]	Loaded runtime configuration.	required
project_root	Path	Project root used for resolving relative paths.	required
config_path	Path	Path to the active config file.	required

Returns:

Name	Type	Description
UniformPersonaSampler	UniformPersonaSampler	Initialized sampler with user/assistant pools.

Side Effects / I/O: - Reads persona files when enabled.

Examples:

>>> from dlgforge.config.personas import build_uniform_persona_sampler
>>> build_uniform_persona_sampler(...)

load_personas(cfg, project_root, config_path)

Load user and assistant personas from configuration.

Falls back to built-in defaults when the configured file is missing, unreadable, or malformed.

Parameters:

Name	Type	Description	Default
cfg	Dict[str, Any]	Loaded runtime configuration.	required
project_root	Path	Project root used for resolving relative paths.	required
config_path	Path	Path to the active config file.	required

Returns:

Type	Description
Dict[str, List[Dict[str, Any]]]	Dict[str, List[Dict[str, Any]]]: Mapping with user and assistant
Dict[str, List[Dict[str, Any]]]	persona lists.

Side Effects / I/O: - Reads YAML from disk when a personas file is configured.

Examples:

>>> from dlgforge.config.personas import load_personas
>>> load_personas(...)

default_personas()

Return the built-in fallback persona set.

Returns:

Type	Description
Dict[str, List[Dict[str, Any]]]	Dict[str, List[Dict[str, Any]]]: Mapping with one default user persona
Dict[str, List[Dict[str, Any]]]	and one default assistant persona.

Examples:

>>> from dlgforge.config.personas import default_personas
>>> sorted(default_personas().keys())
['assistant', 'user']

format_persona(persona)

Format a persona record into a compact display string.

Parameters:

Name	Type	Description	Default
persona	Dict[str, Any]	Persona mapping with optional name, traits, and style keys.	required

Returns:

Name	Type	Description
str	str	Human-readable persona string. Returns an empty string for empty
	str	persona input.

Examples:

>>> from dlgforge.config.personas import format_persona
>>> format_persona({'name': 'Tutor', 'traits': ['patient'], 'style': 'Explains step-by-step'})
'Tutor | patient | Explains step-by-step'