condition_axis.character_conditions

Character condition generation system.

This module implements a structured, rule-based system for generating coherent character state descriptions across multiple axes (physique, wealth, health, facial signals, etc.).

Unlike simple text file lookups, this system uses: - Weighted probability distributions for realistic populations - Semantic exclusion rules to prevent illogical combinations - Mandatory and optional axis policies to control complexity - Reproducible generation via random seeds

The system is designed for procedural character generation in both visual (image generation prompts) and narrative (MUD/game) contexts.

Example usage:

>>> from pipeworks.core.condition_axis import generate_condition, condition_to_prompt
>>> condition = generate_condition(seed=42)
>>> prompt_fragment = condition_to_prompt(condition)
>>> print(prompt_fragment)
'skinny, poor, weary, alert'

Note: The condition dict may also include ‘facial_signal’ as an optional axis.

Architecture:

1. CONDITION_AXES: Define all possible values for each axis (including facial_signal)

2. AXIS_POLICY: Rules for mandatory vs optional axes

3. WEIGHTS: Statistical distribution for realistic populations

4. EXCLUSIONS: Semantic constraints to prevent nonsense (including cross-system rules)

5. Generator: Produces constrained random combinations

6. Converter: Transforms structured data into prompt text

condition_axis.character_conditions.condition_to_prompt(condition_dict)

Convert structured condition data to a comma-separated prompt fragment.

This is the only place structured data becomes prose text. The output is designed to be clean and diffusion-friendly.

Parameters:

condition_dict (dict[str, str]) – Dictionary mapping axis names to values (output from generate_condition)

Return type:

str

Returns:

Comma-separated string of condition values

Examples

>>> condition_to_prompt({"physique": "wiry", "wealth": "poor"})
'wiry, poor'

>>> condition_to_prompt({"physique": "stocky", "wealth": "modest", "age": "old"})
'stocky, modest, old'

Notes

• Order is determined by dict iteration (Python 3.7+ preserves insertion order)

• If you need deterministic ordering, consider sorting by axis name

• Empty dict returns empty string

condition_axis.character_conditions.generate_condition(seed=None)

Generate a coherent character condition using weighted random selection.

This function applies the full rule system: 1. Select mandatory axes (always included) 2. Select 0-N optional axes (controlled by policy) 3. Apply weighted probability distributions 4. Apply semantic exclusion rules 5. Return structured condition data

Parameters:

seed (int | None) – Optional random seed for reproducible generation. If None, uses system entropy (non-reproducible).

Return type:

dict[str, str]

Returns:

Dictionary mapping axis names to selected values. Example: {“physique”: “wiry”, “wealth”: “poor”, “demeanor”: “alert”}

Examples

>>> # Reproducible generation
>>> cond1 = generate_condition(seed=42)
>>> cond2 = generate_condition(seed=42)
>>> cond1 == cond2
True

>>> # Non-reproducible (different each call)
>>> generate_condition()
{'physique': 'stocky', 'wealth': 'modest', 'health': 'weary'}

condition_axis.character_conditions.get_available_axes()

Get list of all defined condition axes.

Return type:

list[str]

Returns:

List of axis names (e.g., [‘physique’, ‘wealth’, ‘health’, ‘facial_signal’, …])

Example

>>> get_available_axes()
['physique', 'wealth', 'health', 'demeanor', 'age', 'facial_signal']

condition_axis.character_conditions.get_axis_values(axis)

Get all possible values for a specific axis.

Parameters:

axis (str) – Name of the axis (e.g., ‘physique’, ‘wealth’)

Return type:

list[str]

Returns:

List of possible values for that axis

Raises:

KeyError – If axis is not defined in CONDITION_AXES

Example

>>> get_axis_values('wealth')
['poor', 'modest', 'well-kept', 'wealthy', 'decadent']