bertrend 0.3.13__tar.gz → 0.3.14__tar.gz

{bertrend-0.3.13 → bertrend-0.3.14}/PKG-INFO

@@ -1,8 +1,10 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: bertrend
-Version: 0.3.13
+Version: 0.3.14
 Summary: BERTrend analyses topic evolution over time using state-of-the-art transformer models: topic modelling and LLM
 License: LICENSE.md
+License-File: AUTHORS.txt
+License-File: LICENSE.md
 Keywords: topics,BERTopic,transformers,weak signals,LLM
 Author: Jérôme Picault
 Author-email: jerome.picault@rte-france.com
@@ -42,14 +44,17 @@ Requires-Dist: newspaper4k (>=0.9.3.1) ; extra == "apps"
 Requires-Dist: nltk (>=3.9.1)
 Requires-Dist: numpy (<2)
 Requires-Dist: openai (>=1.77.0)
+Requires-Dist: openai-agents[litellm] (>=0.2.5)
 Requires-Dist: openpyxl (>=3.1.5)
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (==1.25.0)
 Requires-Dist: pandas (>=2.2.2)
 Requires-Dist: plotly (>=5.24.1)
 Requires-Dist: plotly-resampler (>=0.10.0)
+Requires-Dist: pyarrow (>=21.0.0)
 Requires-Dist: pygooglenews (>=0.1.3) ; extra == "apps"
 Requires-Dist: pylabeladjust (==0.1.13)
 Requires-Dist: pytest (>=8.4.0)
+Requires-Dist: pytest-asyncio
 Requires-Dist: requests (>=2.32.3)
 Requires-Dist: scikit-learn (>=1.5.2)
 Requires-Dist: scipy (==1.12)
@@ -57,9 +62,8 @@ Requires-Dist: seaborn (>=0.13.2)
 Requires-Dist: sentence-transformers (==3.0.1)
 Requires-Dist: sentencepiece (>=0.2.0)
 Requires-Dist: starlette (>=0.46.2)
-Requires-Dist: streamlit (>=1.46)
+Requires-Dist: streamlit (>=1.48)
 Requires-Dist: streamlit-code-editor (>=0.1.22)
-Requires-Dist: streamlit-tags
 Requires-Dist: supervisor (>=4.2.5)
 Requires-Dist: thefuzz (>=0.22.1)
 Requires-Dist: tiktoken (>=0.8.0)
@@ -229,6 +233,8 @@ Recommended public datasets:
 
 For custom dataset creation, please refer to the documentation page about [data providers](./docs/data_provider.md).
 
+For email configuration and newsletter sending (optional), please refer to the [mail configuration guide](./docs/mail_configuration.md).
+
 
 In order to use the provided demos, datasets :
 - can be stored on the server in: `$BERTREND_BASE_DIR/data/bertrend/`

{bertrend-0.3.13 → bertrend-0.3.14}/README.md

@@ -152,6 +152,8 @@ Recommended public datasets:
 
 For custom dataset creation, please refer to the documentation page about [data providers](./docs/data_provider.md).
 
+For email configuration and newsletter sending (optional), please refer to the [mail configuration guide](./docs/mail_configuration.md).
+
 
 In order to use the provided demos, datasets :
 - can be stored on the server in: `$BERTREND_BASE_DIR/data/bertrend/`

bertrend-0.3.14/bertrend/article_scoring/article_scoring.py

@@ -0,0 +1,326 @@
+#  Copyright (c) 2024, RTE (https://www.rte-france.com)
+#  See AUTHORS.txt
+#  SPDX-License-Identifier: MPL-2.0
+#  This file is part of BERTrend.
+import json
+from functools import total_ordering
+
+from pydantic import (
+    BaseModel,
+    Field,
+    model_validator,
+    ConfigDict,
+    computed_field,
+    model_serializer,
+)
+from typing import Optional, List, Dict, Any
+from enum import Enum
+
+
+@total_ordering
+class QualityLevel(Enum):
+    """Quality level categories based on score ranges"""
+
+    POOR = "Poor"  # (0.0-0.25)
+    FAIR = "Fair"  # (0.25-0.50)
+    AVERAGE = "Average"  # (0.50-0.65)
+    GOOD = "Good"  # (0.65-0.8)
+    EXCELLENT = "Excellent"  # (0.8-1.0)
+
+    def __lt__(self, other):
+        if not isinstance(other, QualityLevel):
+            return NotImplemented
+        return self.index < other.index
+
+    def __eq__(self, other):
+        if not isinstance(other, QualityLevel):
+            return NotImplemented
+        return self.name == other.name
+
+    @classmethod
+    def from_string(cls, value):
+        """Create a QualityLevel from a string (case-insensitive)"""
+        if isinstance(value, cls):
+            return value
+
+        value_lower = str(value).lower().strip()
+        for level in cls:
+            if level.value.lower() == value_lower:
+                return level
+
+        valid_values = [level.value for level in cls]
+        raise ValueError(
+            f"'{value}' is not a valid QualityLevel. Valid values are: {valid_values}"
+        )
+
+    @property
+    def index(self):
+        """Get the index (position) of this QualityLevel in the enum definition order"""
+        return list(QualityLevel).index(self)
+
+
+class CriteriaScores(BaseModel):
+    """Individual scores for each quality criterion"""
+
+    model_config = ConfigDict(validate_assignment=True, extra="forbid")
+
+    depth_of_reporting: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="How well the article provides background, context, explanations, and connects to broader trends",
+    )
+    originality_and_exclusivity: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Unique information, exclusive insights, original reporting, or fresh perspectives",
+    )
+    source_quality_and_transparency: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Quality and transparency of sources, credibility, independence, and conflict disclosure",
+    )
+    accuracy_and_fact_checking_rigor: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Precision, verifiability, appropriate evidence strength, and error handling",
+    )
+    clarity_and_accessibility: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Clear communication, logical hierarchy, and accessibility for target audience",
+    )
+    balance_and_fairness: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Fair presentation of viewpoints, absence of bias, acknowledgment of uncertainties",
+    )
+    narrative_and_engagement: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Reader engagement, storytelling effectiveness, and balance with journalistic integrity",
+    )
+    timeliness_and_relevance: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Currency of information, relevance to current context, and appropriate timing",
+    )
+    ethical_considerations_and_sensitivity: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Ethical reporting standards, sensitivity to affected populations, avoiding sensationalism",
+    )
+    rte_relevance_and_strategic_impact: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Relevance to RTE operations, energy transmission, grid management, and strategic planning",
+    )
+
+    @classmethod
+    def get_criterion_names(cls) -> List[str]:
+        """Get list of all criterion names"""
+        return list(cls.model_fields.keys())
+
+    def to_dict(self) -> Dict[str, float]:
+        """Convert scores to dictionary"""
+        return {name: getattr(self, name) for name in self.get_criterion_names()}
+
+
+class WeightConfig(BaseModel):
+    """Configurable weights for each criterion"""
+
+    model_config = ConfigDict(validate_assignment=True, extra="forbid")
+    depth_of_reporting: float = Field(0.15, ge=0.0, le=1.0)
+    originality_and_exclusivity: float = Field(0.10, ge=0.0, le=1.0)
+    source_quality_and_transparency: float = Field(0.15, ge=0.0, le=1.0)
+    accuracy_and_fact_checking_rigor: float = Field(0.15, ge=0.0, le=1.0)
+    clarity_and_accessibility: float = Field(0.10, ge=0.0, le=1.0)
+    balance_and_fairness: float = Field(0.10, ge=0.0, le=1.0)
+    narrative_and_engagement: float = Field(0.10, ge=0.0, le=1.0)
+    timeliness_and_relevance: float = Field(0.05, ge=0.0, le=1.0)
+    ethical_considerations_and_sensitivity: float = Field(0.05, ge=0.0, le=1.0)
+    rte_relevance_and_strategic_impact: float = Field(0.05, ge=0.0, le=1.0)
+
+    @model_validator(mode="after")
+    def weights_validator(self) -> "WeightConfig":
+        """Ensure all weights sum to less than the number of criteria"""
+        total = sum(
+            getattr(self, name) for name in CriteriaScores.get_criterion_names()
+        )
+        if not total <= len(CriteriaScores.get_criterion_names()):
+            raise ValueError(
+                f"Weights must not exceed {len(CriteriaScores.get_criterion_names())}, got {total:.6f}"
+            )
+        return self
+
+    def to_dict(self) -> Dict[str, float]:
+        """Convert weights to dictionary"""
+        return {
+            name: getattr(self, name) for name in CriteriaScores.get_criterion_names()
+        }
+
+
+class ArticleScore(BaseModel):
+    """Complete article scoring with individual scores and final result"""
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid",
+        arbitrary_types_allowed=True,
+        use_enum_values=True,  # to serialize enum values
+    )
+
+    # Required fields
+    scores: CriteriaScores
+
+    # Optional configuration
+    weights: WeightConfig = Field(default_factory=WeightConfig)
+
+    # Assessment metadata
+    assessment_summary: Optional[str] = Field(
+        None, description="Brief summary of strengths and weaknesses"
+    )
+
+    @computed_field
+    @property
+    def final_score(self) -> float:
+        """Calculate weighted final score"""
+        score_dict = self.scores.to_dict()
+        weight_dict = self.weights.to_dict()
+
+        weighted_sum = sum(
+            score_dict[name] * weight_dict[name] for name in score_dict.keys()
+        )
+        return round(weighted_sum, 3) / len(score_dict)
+
+    @computed_field
+    @property
+    def quality_level(self) -> QualityLevel:
+        """Determine quality level based on final score"""
+        score = self.final_score
+        if 0.0 <= score < 0.25:
+            return QualityLevel.POOR
+        elif 0.25 <= score < 0.50:
+            return QualityLevel.FAIR
+        elif 0.5 <= score < 0.65:
+            return QualityLevel.AVERAGE
+        elif 0.65 <= score < 0.8:
+            return QualityLevel.GOOD
+        else:  # 0.8 <= score <= 1.0
+            return QualityLevel.EXCELLENT
+
+    def get_detailed_breakdown(self) -> Dict[str, Dict[str, float]]:
+        """Get detailed score breakdown with weights and contributions"""
+        score_dict = self.scores.to_dict()
+        weight_dict = self.weights.to_dict()
+
+        return {
+            criterion: {
+                "score": score_dict[criterion],
+                "weight": weight_dict[criterion],
+                "weighted_contribution": round(
+                    score_dict[criterion] * weight_dict[criterion], 3
+                ),
+            }
+            for criterion in score_dict.keys()
+        }
+
+    def get_top_strengths(self, n: int = 3) -> List[tuple[str, float]]:
+        """Get top N scoring criteria"""
+        score_dict = self.scores.to_dict()
+        sorted_scores = sorted(score_dict.items(), key=lambda x: x[1], reverse=True)
+        return sorted_scores[:n]
+
+    def get_top_weaknesses(self, n: int = 3) -> List[tuple[str, float]]:
+        """Get bottom N scoring criteria"""
+        score_dict = self.scores.to_dict()
+        sorted_scores = sorted(score_dict.items(), key=lambda x: x[1])
+        return sorted_scores[:n]
+
+    def to_report(self, include_breakdown: bool = True) -> str:
+        """Generate a formatted assessment report"""
+        report_lines = [
+            "ARTICLE QUALITY ASSESSMENT REPORT",
+            "=" * 50,
+            "",
+            f"FINAL SCORE: {self.final_score}/1.0 ({self.quality_level.value})",
+            "",
+        ]
+
+        if include_breakdown:
+            report_lines.append("INDIVIDUAL SCORES:")
+            breakdown = self.get_detailed_breakdown()
+            for i, (criterion, data) in enumerate(breakdown.items(), 1):
+                criterion_name = criterion.replace("_", " ").title()
+                report_lines.append(
+                    f"{i:2d}. {criterion_name}: {data['score']:.2f}/1.0 "
+                    f"(Weight: {data['weight']:.0%}, Contribution: {data['weighted_contribution']:.3f})"
+                )
+            report_lines.append("")
+
+        # Add strengths and weaknesses
+        strengths = self.get_top_strengths(3)
+        weaknesses = self.get_top_weaknesses(3)
+
+        report_lines.extend(
+            [
+                "TOP STRENGTHS:",
+                *[
+                    f"• {name.replace('_', ' ').title()}: {score:.2f}"
+                    for name, score in strengths
+                ],
+                "",
+                "AREAS FOR IMPROVEMENT:",
+                *[
+                    f"• {name.replace('_', ' ').title()}: {score:.2f}"
+                    for name, score in weaknesses
+                ],
+                "",
+            ]
+        )
+
+        if self.assessment_summary:
+            report_lines.extend(
+                [
+                    "OVERALL ASSESSMENT:",
+                    self.assessment_summary,
+                    "",
+                ]
+            )
+
+        return "\n".join(report_lines)
+
+    def export_to_dict(self) -> Dict[str, Any]:
+        """Export complete assessment to dictionary for serialization"""
+        return {
+            "scores": self.scores.model_dump(),
+            "weights": self.weights.model_dump(),
+            "final_score": self.final_score,
+            "quality_level": self.quality_level.value,  # Explicitly convert enum to string
+            "assessment_summary": self.assessment_summary,
+            "detailed_breakdown": self.get_detailed_breakdown(),
+        }
+
+    def to_json(self) -> str:
+        """Export to JSON string"""
+        return json.dumps(self.export_to_dict(), indent=2)
+
+    @model_serializer
+    def serialize_model(self) -> Dict[str, Any]:
+        """Custom serializer to handle QualityLevel enum"""
+        return {
+            "scores": self.scores.model_dump(),
+            "weights": self.weights.model_dump(),
+            "final_score": self.final_score,
+            "quality_level": self.quality_level.value,
+            "assessment_summary": self.assessment_summary,
+        }

bertrend-0.3.14/bertrend/article_scoring/prompts.py

@@ -0,0 +1,143 @@
+#  Copyright (c) 2024, RTE (https://www.rte-france.com)
+#  See AUTHORS.txt
+#  SPDX-License-Identifier: MPL-2.0
+#  This file is part of BERTrend.
+
+ARTICLE_SCORING_PROMPT = """
+# News Article Quality Assessment Prompt
+
+You are an expert news analyst tasked with evaluating the quality of a news article. Please assess the article across 10 key criteria score between 0 (poor) and 1 (excellent).
+
+## Assessment Instructions
+
+For each criterion below, assign a score from 0 to 1 based on how well the article meets the specified requirements. 
+
+### Scoring Scale:
+- **0.0-0.25**: Poor - Fails to meet basic standards
+- **0.25-0.5**: Fair - Meets some requirements but has significant gaps
+- **0.5-0.65**: Average - Meets most basic requirements
+- **0.65-0.8**: Good - Exceeds expectations in most areas
+- **0.8-1.0**: Excellent - Exceptional quality, sets the standard
+
+## Evaluation Criteria
+
+### 1. Depth of Reporting
+**Score: ___/1.0**
+
+Evaluate:
+- How well does the article provide background, context, and explanations?
+- Does it go beyond surface facts to explain why or how?
+- Does it cover implications and consequences?
+- Are expert opinions or analysis included?
+- Does it connect current events to broader trends or historical patterns?
+
+### 2. Originality and Exclusivity
+**Score: ___/1.0**
+
+Evaluate:
+- Does the article provide unique information or exclusive insights not found elsewhere?
+- Are there original interviews, data, or on-the-ground reporting?
+- Does it offer a fresh angle or perspective on a familiar story?
+
+### 3. Source Quality and Transparency
+**Score: ___/1.0**
+
+Evaluate:
+- Are sources explicitly named and credible (experts, official data, witnesses)?
+- Are multiple, independent sources cited to avoid reliance on a single perspective?
+- Is there a clear distinction between primary and secondary sources?
+- Are potential conflicts of interest disclosed?
+
+### 4. Accuracy and Fact-Checking Rigor
+**Score: ___/1.0**
+
+Evaluate:
+- Is every fact precise and verifiable?
+- Are statistics and data presented with references or links?
+- Are potential errors or corrections addressed openly?
+- Are claims substantiated with appropriate evidence strength (avoiding over-interpretation of preliminary data)?
+
+### 5. Clarity and Accessibility 
+**Score: ___/1.0**
+
+Evaluate:
+- Is complex information broken down clearly for the target audience?
+- Does the article avoid ambiguity or confusion?
+- Are technical terms well defined or minimized?
+- Is the information hierarchy logical and easy to follow?
+
+### 6. Balance and Fairness 
+**Score: ___/1.0**
+
+Evaluate:
+- Does the article fairly present conflicting viewpoints or relevant nuances?
+- Is it free from hidden biases or agenda-driven language?
+- Does it acknowledge uncertainties and limitations in the information presented?
+
+### 7. Narrative and Engagement
+**Score: ___/1.0**
+
+Evaluate:
+- How well does the article maintain reader interest?
+- Does it use storytelling, vivid examples, or quotes effectively?
+- Is the headline catchy but truthful?
+- Does it strike the right balance between engagement and journalistic integrity?
+
+### 8. Timeliness and Relevance
+**Score: ___/1.0**
+
+Evaluate:
+- Is the article up-to-date with the latest developments?
+- Does it highlight why the topic matters now?
+- Does it provide appropriate context about what has changed since previous reporting?
+
+### 9. Ethical Considerations and Sensitivity 
+**Score: ___/1.0**
+
+Evaluate:
+- Does the article avoid sensationalism or fearmongering?
+- Does it respect privacy and avoid harm?
+- Does it consider the potential impact on vulnerable populations or communities mentioned?
+
+### 10. RTE Relevance and Strategic Impact
+**Score: ___/1.0**
+
+Evaluate:
+- Does the article address issues directly impacting electricity transmission, grid management, or energy infrastructure?
+- Are there implications for French energy security, grid stability, or electricity market operations?
+- Does it cover regulatory changes, policy decisions, or geopolitical events affecting energy supply chains?
+- Are there connections to renewable energy integration, nuclear policy, or European energy interconnections?
+- Does it address energy transition challenges relevant to transmission system operations?
+- Are there economic, political, or environmental factors that could influence RTE's strategic planning or operations?
+
+## Assessment Output Format
+
+Please provide your assessment in the following format:
+
+---
+
+**Article Title:** [Insert title]
+
+**Individual Scores:**
+1. Depth of Reporting: ___
+2. Originality and Exclusivity: ___
+3. Source Quality and Transparency: ___
+4. Accuracy and Fact-Checking Rigor: ___
+5. Clarity and Accessibility: ___
+6. Balance and Fairness: ___
+7. Narrative and Engagement: ___
+8. Timeliness and Relevance: ___
+9. Ethical Considerations and Sensitivity: ___
+10. RTE Relevance and Strategic Impact: ___
+
+**Overall Assessment:** [Brief summary of strengths and weaknesses]
+
+---
+
+## Important Notes:
+- Consider the article type (breaking news, investigative, opinion, analysis) when evaluating
+- Weight journalistic fundamentals (accuracy, sources, ethics) more heavily than stylistic elements
+- Be objective and evidence-based in your scoring
+- Provide specific examples from the article to support your scores
+
+"""

bertrend-0.3.14/bertrend/article_scoring/scoring_agent.py

@@ -0,0 +1,55 @@
+import asyncio
+from pathlib import Path
+
+from agents import ModelSettings
+
+from bertrend.article_scoring.article_scoring import ArticleScore
+from bertrend.article_scoring.prompts import ARTICLE_SCORING_PROMPT
+from bertrend.llm_utils.agent_utils import (
+    BaseAgentFactory,
+    AsyncAgentConcurrentProcessor,
+    progress_reporter,
+)
+from bertrend.utils.data_loading import load_data
+
+DEFAULT_CHUNK_SIZE = 25
+DEFAULT_MAX_CONCURRENT_TASKS = 25
+
+
+async def score_articles(articles: list[str]):
+    agent = BaseAgentFactory().create_agent(
+        name="scoring_agent",
+        instructions=ARTICLE_SCORING_PROMPT,
+        output_type=ArticleScore,
+        model_settings=ModelSettings(temperature=0.1),
+    )
+
+    # Initialize processor
+    processor = AsyncAgentConcurrentProcessor(
+        agent=agent, max_concurrent=DEFAULT_MAX_CONCURRENT_TASKS
+    )
+
+    # Uncomment to process multiple items:
+    results = await processor.process_list_concurrent(
+        articles, progress_callback=progress_reporter, chunk_size=DEFAULT_CHUNK_SIZE
+    )
+    return results
+
+
+if __name__ == "__main__":
+
+    path = Path("/DSIA/nlp/bertrend/data/feeds/feed_nlp/2025-01-07_feed_nlp.jsonl")
+    df = load_data(path)
+    print(len(df), df.columns)
+    l = list(df.text)
+    results = asyncio.run(score_articles(l))
+
+    assert len(results) == len(df)
+    df["quality_metrics"] = [r.output if not r.error else None for r in results]
+    df["overall_quality"] = df["quality_metrics"].apply(
+        lambda x: x.quality_level.name if x else None
+    )
+    print(df.overall_quality)
+    category_percentages = df["overall_quality"].value_counts(normalize=True) * 100
+    # Display percentages
+    print(category_percentages)

{bertrend-0.3.13 → bertrend-0.3.14}/bertrend/demos/demos_utils/icons.py

@@ -34,6 +34,7 @@ STRONG_SIGNAL_ICON = ":material/signal_cellular_3_bar:"
 DOWNLOAD_ICON = ":material/download:"
 EMAIL_ICON = ":material/mail:"
 RESTART_ICON = ":material/restart_alt:"
+PERSON_ADD_ICON = ":material/person_add:"
 
 JSON_ICON = "🧾"
 PARQUET_ICON = "📦️"

bertrend-0.3.14/bertrend/demos/streamlit_components/input_with_pills_components.py

@@ -0,0 +1,83 @@
+import streamlit as st
+from typing import Callable, Optional, List
+
+from bertrend.demos.demos_utils.icons import PERSON_ADD_ICON
+
+
+@st.fragment
+def input_with_pills(
+    label: str,
+    key: str,
+    placeholder: str = "",
+    validate_fn: Optional[Callable[[str], bool]] = None,
+    label_visibility="hidden",
+) -> List[str]:
+    """
+    A simple Streamlit component that auto-adds valid input to pills.
+    Dialog-safe version that doesn't use st.rerun()
+    """
+
+    # Initialize session state
+    all_items_key = f"{key}_all_items"
+    selected_items_key = f"{key}_selected_items"
+    input_key = f"{key}_input"
+
+    if all_items_key not in st.session_state:
+        st.session_state[all_items_key] = []
+    if selected_items_key not in st.session_state:
+        st.session_state[selected_items_key] = []
+
+    # Create columns: input on left, pills on right
+    col1, col2 = st.columns([3, 3])
+
+    with col1:
+        # Create a form to handle Enter key press without rerun
+        with st.form(key=f"{key}_form", clear_on_submit=True, border=False):
+            current_input = st.text_input(
+                label,
+                placeholder=placeholder,
+                key=input_key,
+                label_visibility=label_visibility,
+            )
+            # Submit button is required but will be hidden
+            submitted = st.form_submit_button(PERSON_ADD_ICON)
+
+            if submitted and current_input.strip():
+                is_valid = True
+                error_msg = ""
+
+                if validate_fn and not validate_fn(current_input.strip()):
+                    is_valid = False
+                    error_msg = "Invalid format"
+                elif current_input.strip() in st.session_state[all_items_key]:
+                    is_valid = False
+                    error_msg = "Already exists"
+
+                if is_valid:
+                    # Add to both lists
+                    st.session_state[all_items_key].append(current_input.strip())
+                    st.session_state[selected_items_key].append(current_input.strip())
+                else:
+                    st.error(error_msg)
+
+    with col2:
+        # Display pills
+        if st.session_state[all_items_key]:
+            st.markdown("<div style='margin-top: 8px;'></div>", unsafe_allow_html=True)
+
+            # Use a callback to handle selection changes
+            def on_pills_change():
+                selected = st.session_state[f"{key}_pills_widget"]
+                st.session_state[selected_items_key] = selected
+
+            selected_pills = st.pills(
+                "Items",
+                st.session_state[all_items_key],
+                selection_mode="multi",
+                key=f"{key}_pills_widget",
+                label_visibility="collapsed",
+                default=st.session_state[selected_items_key],
+                on_change=on_pills_change,
+            )
+
+    return st.session_state[selected_items_key]