Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 34 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [0.12.0] - 2026-11-03

### Added

- The task item factories in `bead.items` (`ordinal_scale`, `binary`, `categorical`,
`free_text`, `magnitude`, `span_labeling`, `cloze`) take keyword-only `text_element`
and `prompt_element` naming the rendered elements they write, plus `unit_element`
in `magnitude` and `instructions_element` in `cloze`. Every batch helper in those
modules threads the names through, and the defaults keep `"text"`, `"prompt"`,
`"unit"` and `"instructions"`. Span items key `tokenized_elements` and
`token_space_after` by `text_element`, and `add_spans_to_item` reads the prompt
from `prompt_element`. Two roles declared with the same name are refused with a
`ValueError`.
- `family_to_item_template`, `realization_to_item`, `protocol_to_item_templates`
and `realize_protocol_to_items` take `text_element` and `prompt_element`.
`realization_to_item` refuses a name its template does not declare, so the item's
rendered elements always agree with the template's elements under `validate_item`,
and the spans it derives reference the declared text element.

### Changed

- `create_cross_product_items`, `create_filtered_cross_product_items` and
`create_stratified_cross_product_items` require `cross_product_slot`; the `"verb"`
default is removed. The `<slot>_lemma` and `<slot>_form` rendered elements are
named after the slot the caller declares.

### Fixed

- `StratifiedStrategy` resolves each segment of `grouping_property` as a mapping key
as well as an attribute, so `"features.<key>"` groups lexical items by that feature
value; previously every item fell into the `"unknown"` group.

## [0.11.0] - 2026-10-25

### Added
Expand Down Expand Up @@ -734,7 +766,8 @@ guards as type-checkers.
- CI/CD: GitHub Actions for testing, docs, PyPI publishing
- Read the Docs integration

[Unreleased]: https://github.com/FACTSlab/bead/compare/v0.11.0...HEAD
[Unreleased]: https://github.com/FACTSlab/bead/compare/v0.12.0...HEAD
[0.12.0]: https://github.com/FACTSlab/bead/compare/v0.11.0...v0.12.0
[0.11.0]: https://github.com/FACTSlab/bead/compare/v0.10.0...v0.11.0
[0.10.0]: https://github.com/FACTSlab/bead/compare/v0.9.0...v0.10.0
[0.9.0]: https://github.com/FACTSlab/bead/compare/v0.8.0...v0.9.0
Expand Down
73 changes: 69 additions & 4 deletions bead/items/binary.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ def create_binary_item(
binary_options: tuple[str, str] = ("yes", "no"),
item_template_id: UUID | None = None,
metadata: dict[str, MetadataValue] | None = None,
*,
text_element: str = "text",
prompt_element: str = "prompt",
) -> Item:
"""Create a binary judgment item for a single stimulus.

Expand All @@ -46,16 +49,23 @@ def create_binary_item(
Template ID for the item. If None, generates new UUID.
metadata : dict[str, MetadataValue] | None
Additional metadata for item_metadata field.
text_element : str
Name of the rendered element that holds the stimulus text
(default: "text").
prompt_element : str
Name of the rendered element that holds the prompt (default: "prompt").

Returns
-------
Item
Binary item with text and prompt in rendered_elements.
Binary item with the stimulus and prompt stored under the declared
element names.

Raises
------
ValueError
If text is empty or if binary_options doesn't have exactly 2 values.
If text is empty, if binary_options doesn't have exactly 2 values,
or if text_element and prompt_element name the same element.

Examples
--------
Expand All @@ -79,6 +89,13 @@ def create_binary_item(
... )
>>> item.item_metadata["binary_options"]
['true', 'false']

>>> # Declared element names
>>> item = create_binary_item(
... "The sky is blue.", text_element="sentence", prompt_element="question"
... )
>>> item.rendered_elements["sentence"]
'The sky is blue.'
"""
if not text or not text.strip():
raise ValueError("text cannot be empty")
Expand All @@ -89,9 +106,12 @@ def create_binary_item(
if item_template_id is None:
item_template_id = uuid4()

if text_element == prompt_element:
raise ValueError("text_element and prompt_element must name different elements")

rendered_elements: dict[str, str] = {
"text": text,
"prompt": prompt,
text_element: text,
prompt_element: prompt,
}

# Build item metadata
Expand All @@ -115,6 +135,8 @@ def create_binary_items_from_texts(
*,
item_template_id: UUID | None = None,
metadata_fn: Callable[[str], dict[str, MetadataValue]] | None = None,
text_element: str = "text",
prompt_element: str = "prompt",
) -> list[Item]:
"""Create binary items from a list of texts with the same prompt.

Expand All @@ -130,6 +152,11 @@ def create_binary_items_from_texts(
Template ID for all created items. If None, generates one per item.
metadata_fn : Callable[[str], dict[str, MetadataValue]] | None
Function to generate metadata from each text.
text_element : str
Name of the rendered element that holds the stimulus text
(default: "text").
prompt_element : str
Name of the rendered element that holds the prompt (default: "prompt").

Returns
-------
Expand Down Expand Up @@ -167,6 +194,8 @@ def create_binary_items_from_texts(
binary_options=binary_options,
item_template_id=item_template_id,
metadata=metadata,
text_element=text_element,
prompt_element=prompt_element,
)
binary_items.append(item)

Expand All @@ -183,6 +212,8 @@ def create_binary_items_with_context(
target_label: str = "Statement",
item_template_id: UUID | None = None,
metadata_fn: (Callable[[str, str], dict[str, MetadataValue]] | None) = None,
text_element: str = "text",
prompt_element: str = "prompt",
) -> list[Item]:
"""Create binary items with context + target structure.

Expand All @@ -206,6 +237,11 @@ def create_binary_items_with_context(
Template ID for all created items. If None, generates one per item.
metadata_fn : Callable[[str, str], dict[str, MetadataValue]] | None
Function to generate metadata from (context, target).
text_element : str
Name of the rendered element that holds the stimulus text
(default: "text").
prompt_element : str
Name of the rendered element that holds the prompt (default: "prompt").

Returns
-------
Expand Down Expand Up @@ -254,6 +290,8 @@ def create_binary_items_with_context(
binary_options=binary_options,
item_template_id=item_template_id,
metadata=metadata,
text_element=text_element,
prompt_element=prompt_element,
)
binary_items.append(item)

Expand All @@ -269,6 +307,8 @@ def create_binary_items_from_groups(
extract_text: Callable[[Item], str] | None = None,
include_group_metadata: bool = True,
item_template_id: UUID | None = None,
text_element: str = "text",
prompt_element: str = "prompt",
) -> list[Item]:
"""Create binary items from grouped source items.

Expand All @@ -291,6 +331,11 @@ def create_binary_items_from_groups(
Whether to include group key in item metadata.
item_template_id : UUID | None
Template ID for all created items. If None, generates one per item.
text_element : str
Name of the rendered element that holds the stimulus text
(default: "text").
prompt_element : str
Name of the rendered element that holds the prompt (default: "prompt").

Returns
-------
Expand Down Expand Up @@ -349,6 +394,8 @@ def create_binary_items_from_groups(
binary_options=binary_options,
item_template_id=item_template_id,
metadata=metadata,
text_element=text_element,
prompt_element=prompt_element,
)
binary_items.append(binary_item)

Expand All @@ -362,6 +409,8 @@ def create_binary_items_cross_product(
*,
item_template_id: UUID | None = None,
metadata_fn: (Callable[[str, str], dict[str, MetadataValue]] | None) = None,
text_element: str = "text",
prompt_element: str = "prompt",
) -> list[Item]:
"""Create binary items from cross-product of texts and prompts.

Expand All @@ -379,6 +428,11 @@ def create_binary_items_cross_product(
Template ID for all created items.
metadata_fn : Callable[[str, str], dict[str, MetadataValue]] | None
Function to generate metadata from (text, prompt).
text_element : str
Name of the rendered element that holds the stimulus text
(default: "text").
prompt_element : str
Name of the rendered element that holds the prompt (default: "prompt").

Returns
-------
Expand Down Expand Up @@ -406,6 +460,8 @@ def create_binary_items_cross_product(
binary_options=binary_options,
item_template_id=item_template_id,
metadata=metadata,
text_element=text_element,
prompt_element=prompt_element,
)
binary_items.append(item)

Expand All @@ -420,6 +476,8 @@ def create_filtered_binary_items(
item_filter: Callable[[Item], bool] | None = None,
extract_text: Callable[[Item], str] | None = None,
item_template_id: UUID | None = None,
text_element: str = "text",
prompt_element: str = "prompt",
) -> list[Item]:
"""Create binary items with filtering.

Expand All @@ -437,6 +495,11 @@ def create_filtered_binary_items(
Text extraction function.
item_template_id : UUID | None
Template ID for created items.
text_element : str
Name of the rendered element that holds the stimulus text
(default: "text").
prompt_element : str
Name of the rendered element that holds the prompt (default: "prompt").

Returns
-------
Expand Down Expand Up @@ -476,6 +539,8 @@ def create_filtered_binary_items(
binary_options=binary_options,
item_template_id=item_template_id,
metadata=metadata,
text_element=text_element,
prompt_element=prompt_element,
)
binary_items.append(binary_item)

Expand Down
Loading
Loading