Panelists

class sim_panel.panelists.Panelist(*, panelist_id, persona_text, attributes=None, backend=None, state=None, eval_settings=None, select_settings=None)[source]

Bases: object

Runtime agent. The only required thing for LLM-based actions is persona_text.

Parameters:

  • panelist_id (str)

  • persona_text (str)

  • attributes (Optional[Dict[str, Any]])

  • backend (Optional[Backend])

  • state (Optional[PanelistState])

  • eval_settings (Optional[EvalSettings])

  • select_settings (Optional[SelectSettings])

select(*, task_prompt, choice_set, temperature=None, max_tokens=None, metadata=None, system_prompt=None)[source]

Run a selection call. The generator/policy provides the choice_set (IDs), while the prompt should typically include product_display text.

Returns raw model text. Parsing into selected_product_ids should be handled by a SelectionParser / ResponseCleaner layer (later), not inside Panelist.

Return type:

str

Parameters:

  • task_prompt (str)

  • choice_set (Sequence[str])

  • temperature (float | None)

  • max_tokens (int | None)

  • metadata (dict[str, Any] | None)

  • system_prompt (str | None)

evaluate(*, task_prompt, temperature=None, max_tokens=None, metadata=None, system_prompt=None)[source]

Run an evaluation call (panelist evaluating a single product). Returns raw model text; parsing into structured outcomes/traces is handled elsewhere.

Return type:

str

Parameters:

  • task_prompt (str)

  • temperature (float | None)

  • max_tokens (int | None)

  • metadata (dict[str, Any] | None)

  • system_prompt (str | None)

class sim_panel.panelists.PanelistState(t=0, history=<factory>, memory=<factory>)[source]

Bases: object

Parameters:

  • t (int)

  • history (list[dict[str, Any]])

  • memory (dict[str, Any])

t: int = 0
history: list[dict[str, Any]]
memory: dict[str, Any]
class sim_panel.panelists.EvalSettings(temperature=0.2, max_tokens=None, metadata=None)[source]

Bases: object

Default LLM call settings for Panelist evaluation.

These are governed by YAML and applied to Panelist.evaluate() unless overridden.

Parameters:

  • temperature (float)

  • max_tokens (int | None)

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

temperature: float = 0.2
max_tokens: int | None = None
metadata: Dict[str, Any] | None = None
class sim_panel.panelists.PersonaRecord(persona_id, persona_text=None, attributes=None, schema_version='0.1.0', persona_text_variant='default', spec_key=None, text_key=None, provenance=<factory>)[source]

Bases: object

Canonical on-disk persona artifact (JSONL/CSV row). Evaluation needs persona_text; attributes are optional.

Supports:

  • text-only personas (attributes=None)

  • spec-only personas (persona_text=None, attributes present)

  • both

Parameters:

  • persona_id (str)

  • persona_text (str | None)

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

  • schema_version (str)

  • persona_text_variant (str)

  • spec_key (str | None)

  • text_key (str | None)

  • provenance (Dict[str, Any])

persona_id: str
persona_text: str | None = None
attributes: Dict[str, Any] | None = None
schema_version: str = '0.1.0'
persona_text_variant: str = 'default'
spec_key: str | None = None
text_key: str | None = None
provenance: Dict[str, Any]
compute_keys()[source]

Compute stable keys from current fields (in-place).

Return type:

None

to_dict()[source]
Return type:

Dict[str, Any]

static from_dict(d)[source]
Return type:

PersonaRecord

Parameters:

d (Dict[str, Any])

sim_panel.panelists.load_persona_records(path)[source]
Return type:

List[PersonaRecord]

Parameters:

path (str | Path)

sim_panel.panelists.save_persona_records(path, records)[source]
Return type:

None

Parameters:
sim_panel.panelists.merge_persona_records(base, incoming, *, prefer_incoming_attributes=True, prefer_incoming_text=True)[source]

Merge by (persona_id, persona_text_variant). Rewrite-friendly.

  • attributes: prefer incoming by default

  • persona_text: prefer incoming by default

Return type:

List[PersonaRecord]

Parameters:
class sim_panel.panelists.PersonaTextGenSettings(prompt_version='v1', temperature=0.2, max_tokens=None, metadata=None, max_workers=1)[source]

Bases: object

Parameters:

  • prompt_version (str)

  • temperature (float)

  • max_tokens (int | None)

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

  • max_workers (int)

prompt_version: str = 'v1'
temperature: float = 0.2
max_tokens: int | None = None
metadata: Dict[str, Any] | None = None
max_workers: int = 1
sim_panel.panelists.ensure_persona_text(records, *, backend, settings, variant='default', overwrite=False, progress=True)[source]
Return type:

List[PersonaRecord]

Parameters:
For each record of the given variant:

  • if persona_text missing (or overwrite=True), generate from attributes

  • write provenance fields

Requires attributes to be present for generation.

sim_panel.panelists.build_panelists(records, *, backend=None, variant='default', eval_settings=None, select_settings=None)[source]

Build runtime Panelist objects from PersonaRecord rows.

Parameters:

  • records (List[PersonaRecord]) – PersonaRecord list (typically loaded from personas.jsonl).

  • backend (Optional[Backend]) – Optional Backend instance. Required if you intend to call Panelist.evaluate().

  • variant (str) – Which persona_text_variant to use (default: “default”).

  • eval_settings (Optional[EvalSettings]) – YAML-governed default evaluation settings applied to each Panelist. If None, Panelist will use its internal defaults.

  • select_settings (Optional[SelectSettings]) – YAML-governed default selection settings applied to each Panelist. If None, Panelist will use its internal defaults.

Return type:

List[Panelist]

class sim_panel.panelists.records.PersonaRecord(persona_id, persona_text=None, attributes=None, schema_version='0.1.0', persona_text_variant='default', spec_key=None, text_key=None, provenance=<factory>)[source]

Bases: object

Canonical on-disk persona artifact (JSONL/CSV row). Evaluation needs persona_text; attributes are optional.

Supports:

  • text-only personas (attributes=None)

  • spec-only personas (persona_text=None, attributes present)

  • both

Parameters:

  • persona_id (str)

  • persona_text (str | None)

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

  • schema_version (str)

  • persona_text_variant (str)

  • spec_key (str | None)

  • text_key (str | None)

  • provenance (Dict[str, Any])

persona_id: str
persona_text: str | None = None
attributes: Dict[str, Any] | None = None
schema_version: str = '0.1.0'
persona_text_variant: str = 'default'
spec_key: str | None = None
text_key: str | None = None
provenance: Dict[str, Any]
compute_keys()[source]

Compute stable keys from current fields (in-place).

Return type:

None

to_dict()[source]
Return type:

Dict[str, Any]

static from_dict(d)[source]
Return type:

PersonaRecord

Parameters:

d (Dict[str, Any])

class sim_panel.panelists.panelist.PanelistState(t=0, history=<factory>, memory=<factory>)[source]

Bases: object

Parameters:

  • t (int)

  • history (list[dict[str, Any]])

  • memory (dict[str, Any])

t: int = 0
history: list[dict[str, Any]]
memory: dict[str, Any]
class sim_panel.panelists.panelist.EvalSettings(temperature=0.2, max_tokens=None, metadata=None)[source]

Bases: object

Default LLM call settings for Panelist evaluation.

These are governed by YAML and applied to Panelist.evaluate() unless overridden.

Parameters:

  • temperature (float)

  • max_tokens (int | None)

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

temperature: float = 0.2
max_tokens: int | None = None
metadata: Dict[str, Any] | None = None
class sim_panel.panelists.panelist.SelectSettings(temperature=0.2, max_tokens=None, metadata=None)[source]

Bases: object

Default LLM call settings for Panelist selection.

These are governed by YAML and applied to Panelist.select() unless overridden.

Parameters:

  • temperature (float)

  • max_tokens (int | None)

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

temperature: float = 0.2
max_tokens: int | None = None
metadata: Dict[str, Any] | None = None
class sim_panel.panelists.panelist.Panelist(*, panelist_id, persona_text, attributes=None, backend=None, state=None, eval_settings=None, select_settings=None)[source]

Bases: object

Runtime agent. The only required thing for LLM-based actions is persona_text.

Parameters:

  • panelist_id (str)

  • persona_text (str)

  • attributes (Dict[str, Any])

  • backend (Optional[Backend])

  • state (Optional[PanelistState])

  • eval_settings (Optional[EvalSettings])

  • select_settings (Optional[SelectSettings])

attributes: Dict[str, Any]
select(*, task_prompt, choice_set, temperature=None, max_tokens=None, metadata=None, system_prompt=None)[source]

Run a selection call. The generator/policy provides the choice_set (IDs), while the prompt should typically include product_display text.

Returns raw model text. Parsing into selected_product_ids should be handled by a SelectionParser / ResponseCleaner layer (later), not inside Panelist.

Return type:

str

Parameters:

  • task_prompt (str)

  • choice_set (Sequence[str])

  • temperature (float | None)

  • max_tokens (int | None)

  • metadata (dict[str, Any] | None)

  • system_prompt (str | None)

evaluate(*, task_prompt, temperature=None, max_tokens=None, metadata=None, system_prompt=None)[source]

Run an evaluation call (panelist evaluating a single product). Returns raw model text; parsing into structured outcomes/traces is handled elsewhere.

Return type:

str

Parameters:

  • task_prompt (str)

  • temperature (float | None)

  • max_tokens (int | None)

  • metadata (dict[str, Any] | None)

  • system_prompt (str | None)