Decisions

class sim_panel.decisions.SelectionConfig(allow_empty=True, include_features=True, require_json_only=True, max_selected_soft=None, include_raw_text=True, custom_few_shot_example=None)

Bases: object

YAML-governed config for selection prompting/parsing.

If allow_empty is False and selection output is empty (after filtering), generator can decide a fallback (re-prompt or force one).

Parameters:

• allow_empty (bool)

• include_features (bool)

• require_json_only (bool)

• max_selected_soft (int | None)

• include_raw_text (bool)

• custom_few_shot_example (Dict[str, Any] | None)

allow_empty: bool = True

include_features: bool = True

require_json_only: bool = True

max_selected_soft: int | None = None

include_raw_text: bool = True

custom_few_shot_example: Dict[str, Any] | None = None

class sim_panel.decisions.SelectionContext(panelist_id, t, products_shown, extra=None)

Bases: object

Context used to render a selection prompt.

products_shown should already reflect the exposure policy (choice_set), and each item should include a stable product_id plus panelist-facing product_display.

Parameters:

• panelist_id (str)

• t (int)

• products_shown (List[Dict[str, Any]])

• extra (Dict[str, Any] | None)

panelist_id: str

t: int

products_shown: List[Dict[str, Any]]

extra: Dict[str, Any] | None = None

class sim_panel.decisions.SelectionResult(requested_product_ids, traces=None, raw_text=None, errors=None)

Bases: object

Parsed selection output.

requested_product_ids are what the panelist asked to evaluate (free will). The generator may later apply execution rules to decide what to actually execute.

Parameters:

• requested_product_ids (List[str])

• traces (Dict[str, Any] | None)

• raw_text (str | None)

• errors (List[str] | None)

requested_product_ids: List[str]

traces: Dict[str, Any] | None = None

raw_text: str | None = None

errors: List[str] | None = None

class sim_panel.decisions.ExecutionRules(enforce_subset_of_choice_set=True, max_evals_per_panelist_per_t=None, allow_empty=True, keep_strategy='keep_first')

Bases: object

Generator-side operational rules (NOT panelist constraints).

Applied after parsing requested_product_ids:

• subset filtering

• optional cap

• empty fallback behavior

Parameters:

• enforce_subset_of_choice_set (bool)

• max_evals_per_panelist_per_t (int | None)

• allow_empty (bool)

• keep_strategy (str)

enforce_subset_of_choice_set: bool = True

max_evals_per_panelist_per_t: int | None = None

allow_empty: bool = True

keep_strategy: str = 'keep_first'

sim_panel.decisions.render_selection_prompt(*, ctx, cfg, prompting_strategy='persona')

Render a selection prompt for the panelist.

Return type:

str

Parameters:

• ctx (SelectionContext)

• cfg (SelectionConfig)

• prompting_strategy (str)

The model is asked to return JSON only:

{“selected_product_ids”: […], “traces”: {…}}

The panelist has free will: can select any number of products (including none), unless allow_empty=False (in which case we ask them to pick at least one).

sim_panel.decisions.parse_selection_response(*, raw_text, choice_set_ids, cfg)

Parse the panelist’s selection model output into requested_product_ids.

• Expects JSON object with key ‘selected_product_ids’.

• Filters out invalid ids if enforce_subset_of_choice_set is later enabled. (Filtering is applied in apply_execution_rules; here we only parse.)

Return type:

SelectionResult

Parameters:

• raw_text (str)

• choice_set_ids (Sequence[str])

• cfg (SelectionConfig)

sim_panel.decisions.apply_execution_rules(*, requested_product_ids, choice_set_ids, rules)

Apply generator-side operational rules to the panelist’s requested list.

Returns (executed_product_ids, dropped_product_ids).

Return type:

Tuple[List[str], List[str]]

Parameters:

• requested_product_ids (Sequence[str])

• choice_set_ids (Sequence[str])

• rules (ExecutionRules)

class sim_panel.decisions.types.SelectionContext(panelist_id, t, products_shown, extra=None)

Bases: object

Context used to render a selection prompt.

products_shown should already reflect the exposure policy (choice_set), and each item should include a stable product_id plus panelist-facing product_display.

Parameters:

• panelist_id (str)

• t (int)

• products_shown (List[Dict[str, Any]])

• extra (Dict[str, Any] | None)

panelist_id: str

t: int

products_shown: List[Dict[str, Any]]

extra: Dict[str, Any] | None = None

class sim_panel.decisions.types.SelectionResult(requested_product_ids, traces=None, raw_text=None, errors=None)

Bases: object

Parsed selection output.

requested_product_ids are what the panelist asked to evaluate (free will). The generator may later apply execution rules to decide what to actually execute.

Parameters:

• requested_product_ids (List[str])

• traces (Dict[str, Any] | None)

• raw_text (str | None)

• errors (List[str] | None)

requested_product_ids: List[str]

traces: Dict[str, Any] | None = None

raw_text: str | None = None

errors: List[str] | None = None

class sim_panel.decisions.types.SelectionConfig(allow_empty=True, include_features=True, require_json_only=True, max_selected_soft=None, include_raw_text=True, custom_few_shot_example=None)

Bases: object

YAML-governed config for selection prompting/parsing.

If allow_empty is False and selection output is empty (after filtering), generator can decide a fallback (re-prompt or force one).

Parameters:

• allow_empty (bool)

• include_features (bool)

• require_json_only (bool)

• max_selected_soft (int | None)

• include_raw_text (bool)

• custom_few_shot_example (Dict[str, Any] | None)

allow_empty: bool = True

include_features: bool = True

require_json_only: bool = True

max_selected_soft: int | None = None

include_raw_text: bool = True

custom_few_shot_example: Dict[str, Any] | None = None

class sim_panel.decisions.types.ExecutionRules(enforce_subset_of_choice_set=True, max_evals_per_panelist_per_t=None, allow_empty=True, keep_strategy='keep_first')

Bases: object

Generator-side operational rules (NOT panelist constraints).

Applied after parsing requested_product_ids:

• subset filtering

• optional cap

• empty fallback behavior

Parameters:

• enforce_subset_of_choice_set (bool)

• max_evals_per_panelist_per_t (int | None)

• allow_empty (bool)

• keep_strategy (str)

enforce_subset_of_choice_set: bool = True

max_evals_per_panelist_per_t: int | None = None

allow_empty: bool = True

keep_strategy: str = 'keep_first'

sim_panel.decisions.selection.render_selection_prompt(*, ctx, cfg, prompting_strategy='persona')

Render a selection prompt for the panelist.

Return type:

str

Parameters:

• ctx (SelectionContext)

• cfg (SelectionConfig)

• prompting_strategy (str)

The model is asked to return JSON only:

{“selected_product_ids”: […], “traces”: {…}}

The panelist has free will: can select any number of products (including none), unless allow_empty=False (in which case we ask them to pick at least one).

sim_panel.decisions.selection.parse_selection_response(*, raw_text, choice_set_ids, cfg)

Parse the panelist’s selection model output into requested_product_ids.

• Expects JSON object with key ‘selected_product_ids’.

• Filters out invalid ids if enforce_subset_of_choice_set is later enabled. (Filtering is applied in apply_execution_rules; here we only parse.)

Return type:

SelectionResult

Parameters:

• raw_text (str)

• choice_set_ids (Sequence[str])

• cfg (SelectionConfig)

sim_panel.decisions.selection.apply_execution_rules(*, requested_product_ids, choice_set_ids, rules)

Apply generator-side operational rules to the panelist’s requested list.

Returns (executed_product_ids, dropped_product_ids).

Return type:

Tuple[List[str], List[str]]

Parameters:

• requested_product_ids (Sequence[str])

• choice_set_ids (Sequence[str])

• rules (ExecutionRules)