themefinder 0.6.2__py3-none-any.whl → 0.7.0__py3-none-any.whl

themefinder/models.py

@@ -1,138 +1,415 @@
+from typing import List, Optional
+from enum import Enum
 from pydantic import BaseModel, Field, model_validator
 
 
-def validate_non_empty_fields(model: BaseModel) -> BaseModel:
-    """
-    Validate that all string fields in the model are non-empty (after stripping)
-    and that list fields are not empty.
+class Position(str, Enum):
+    """Enum for valid position values"""
 
-    Args:
-        model (BaseModel): A Pydantic model instance.
+    AGREEMENT = "AGREEMENT"
+    DISAGREEMENT = "DISAGREEMENT"
+    UNCLEAR = "UNCLEAR"
 
-    Returns:
-        BaseModel: The same model if validation passes.
 
-    Raises:
-        ValueError: If any string field is empty or any list field is empty.
-    """
-    for field_name, value in model.__dict__.items():
-        if isinstance(value, str) and not value.strip():
-            raise ValueError(f"{field_name} cannot be empty or only whitespace")
-        if isinstance(value, list) and not value:
-            raise ValueError(f"{field_name} cannot be an empty list")
-    return model
+class Stance(str, Enum):
+    """Enum for valid stance values"""
 
+    POSITIVE = "POSITIVE"
+    NEGATIVE = "NEGATIVE"
 
-def validate_position(model: BaseModel) -> BaseModel:
-    """
-    Validate that the model's 'position' field is one of the allowed values.
 
-    Args:
-        model (BaseModel): A Pydantic model instance with a 'position' attribute.
+class EvidenceRich(str, Enum):
+    """Enum for valid evidence_rich values"""
 
-    Returns:
-        BaseModel: The same model if validation passes.
+    YES = "YES"
+    NO = "NO"
 
-    Raises:
-        ValueError: If the 'position' field is not one of the allowed values.
-    """
-    allowed_positions = {"AGREEMENT", "DISAGREEMENT", "UNCLEAR"}
-    if model.position not in allowed_positions:
-        raise ValueError(f"position must be one of {allowed_positions}")
-    return model
 
+class ValidatedModel(BaseModel):
+    """Base model with common validation methods"""
 
-def validate_stances(model: BaseModel) -> BaseModel:
-    """
-    Validate that every stance in the model's 'stances' field is allowed.
+    def validate_non_empty_fields(self) -> "ValidatedModel":
+        """
+        Validate that all string fields are non-empty and all list fields are not empty.
+        """
+        for field_name, value in self.__dict__.items():
+            if isinstance(value, str) and not value.strip():
+                raise ValueError(f"{field_name} cannot be empty or only whitespace")
+            if isinstance(value, list) and not value:
+                raise ValueError(f"{field_name} cannot be an empty list")
+            if isinstance(value, list):
+                for i, item in enumerate(value):
+                    if isinstance(item, str) and not item.strip():
+                        raise ValueError(
+                            f"Item {i} in {field_name} cannot be empty or only whitespace"
+                        )
+        return self
 
-    Args:
-        model (BaseModel): A Pydantic model instance with a 'stances' attribute.
+    def validate_unique_items(
+        self, field_name: str, transform_func: Optional[callable] = None
+    ) -> "ValidatedModel":
+        """
+        Validate that a field contains unique values.
 
-    Returns:
-        BaseModel: The same model if validation passes.
+        Args:
+            field_name: The name of the field to check for uniqueness
+            transform_func: Optional function to transform items before checking uniqueness
+                           (e.g., lowercasing strings)
+        """
+        if not hasattr(self, field_name):
+            raise ValueError(f"Field '{field_name}' does not exist")
+        items = getattr(self, field_name)
+        if not isinstance(items, list):
+            raise ValueError(f"Field '{field_name}' is not a list")
+        if transform_func:
+            transformed_items = [transform_func(item) for item in items]
+        else:
+            transformed_items = items
+        if len(transformed_items) != len(set(transformed_items)):
+            raise ValueError(f"'{field_name}' must contain unique values")
+        return self
 
-    Raises:
-        ValueError: If any stance is not among the allowed stances.
-    """
-    allowed_stances = {"POSITIVE", "NEGATIVE"}
-    for stance in model.stances:
-        if stance not in allowed_stances:
-            raise ValueError(f"stances must be one of {allowed_stances}")
-    return model
+    def validate_unique_attribute_in_list(
+        self, list_field: str, attr_name: str
+    ) -> "ValidatedModel":
+        """
+        Validate that an attribute across all objects in a list field is unique.
 
+        Args:
+            list_field: The name of the list field containing objects
+            attr_name: The attribute within each object to check for uniqueness
+        """
+        if not hasattr(self, list_field):
+            raise ValueError(f"Field '{list_field}' does not exist")
+
+        items = getattr(self, list_field)
+        if not isinstance(items, list):
+            raise ValueError(f"Field '{list_field}' is not a list")
+
+        attr_values = []
+        for item in items:
+            if not hasattr(item, attr_name):
+                raise ValueError(
+                    f"Item in '{list_field}' does not have attribute '{attr_name}'"
+                )
+            attr_values.append(getattr(item, attr_name))
+        if len(attr_values) != len(set(attr_values)):
+            raise ValueError(
+                f"'{attr_name}' must be unique across all items in '{list_field}'"
+            )
+        return self
 
-def validate_mapping_stance_lengths(model: BaseModel) -> BaseModel:
-    """
-    Validate that the lengths of the model's 'stances' and 'labels' fields match.
+    def validate_equal_lengths(self, *field_names) -> "ValidatedModel":
+        """
+        Validate that multiple list fields have the same length.
 
-    Args:
-        model (BaseModel): A Pydantic model instance with 'stances' and 'labels' attributes.
+        Args:
+            *field_names: Variable number of field names to check for equal lengths
+        """
+        if len(field_names) < 2:
+            return self
+        lengths = []
+        for field_name in field_names:
+            if not hasattr(self, field_name):
+                raise ValueError(f"Field '{field_name}' does not exist")
+
+            items = getattr(self, field_name)
+            if not isinstance(items, list):
+                raise ValueError(f"Field '{field_name}' is not a list")
+
+            lengths.append(len(items))
+        if len(set(lengths)) > 1:
+            raise ValueError(
+                f"Fields {', '.join(field_names)} must all have the same length"
+            )
+        return self
 
-    Returns:
-        BaseModel: The same model if validation passes.
+    @model_validator(mode="after")
+    def run_validations(self) -> "ValidatedModel":
+        """
+        Run common validations. Override in subclasses to add specific validations.
+        """
+        return self.validate_non_empty_fields()
 
-    Raises:
-        ValueError: If the lengths of 'stances' and 'labels' do not match.
-    """
-    if len(model.stances) != len(model.labels):
-        raise ValueError("'stances' must have the same length as 'labels'")
-    return model
 
+class SentimentAnalysisOutput(ValidatedModel):
+    """Model for sentiment analysis output"""
 
-def validate_mapping_unique_labels(model: BaseModel) -> BaseModel:
-    """
-    Validate that the model's 'labels' field contains unique values.
+    response_id: int = Field(gt=0)
+    position: Position
 
-    Args:
-        model (BaseModel): A Pydantic model instance with a 'labels' attribute.
 
-    Returns:
-        BaseModel: The same model if validation passes.
+class SentimentAnalysisResponses(ValidatedModel):
+    """Container for all sentiment analysis responses"""
 
-    Raises:
-        ValueError: If 'labels' contains duplicate values.
-    """
-    if len(model.labels) != len(set(model.labels)):
-        raise ValueError("'labels' must be unique")
-    return model
+    responses: List[SentimentAnalysisOutput]
 
+    @model_validator(mode="after")
+    def run_validations(self) -> "SentimentAnalysisResponses":
+        """Validate that response_ids are unique"""
+        self.validate_non_empty_fields()
+        response_ids = [resp.response_id for resp in self.responses]
+        if len(response_ids) != len(set(response_ids)):
+            raise ValueError("Response IDs must be unique")
+        return self
 
-class SentimentAnalysisOutput(BaseModel):
-    response_id: int = Field(gt=0)
-    position: str
+
+class Theme(ValidatedModel):
+    """Model for a single extracted theme"""
+
+    topic_label: str = Field(
+        ..., description="Short label summarizing the topic in a few words"
+    )
+    topic_description: str = Field(
+        ..., description="More detailed description of the topic in 1-2 sentences"
+    )
+    position: Position = Field(
+        ...,
+        description="SENTIMENT ABOUT THIS TOPIC (AGREEMENT, DISAGREEMENT, OR UNCLEAR)",
+    )
+
+
+class ThemeGenerationResponses(ValidatedModel):
+    """Container for all extracted themes"""
+
+    responses: List[Theme] = Field(..., description="List of extracted themes")
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "ThemeGenerationResponses":
+        """Ensure there are no duplicate themes"""
+        self.validate_non_empty_fields()
+        labels = [theme.topic_label.lower().strip() for theme in self.responses]
+        if len(labels) != len(set(labels)):
+            raise ValueError("Duplicate topic labels detected")
+        return self
+
+
+class CondensedTheme(ValidatedModel):
+    """Model for a single condensed theme"""
+
+    topic_label: str = Field(
+        ..., description="Representative label for the condensed topic"
+    )
+    topic_description: str = Field(
+        ...,
+        description="Concise description incorporating key insights from constituent topics",
+    )
+    source_topic_count: int = Field(
+        ..., gt=0, description="Sum of source_topic_counts from combined topics"
+    )
+
+
+class ThemeCondensationResponses(ValidatedModel):
+    """Container for all condensed themes"""
+
+    responses: List[CondensedTheme] = Field(..., description="List of condensed themes")
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "ThemeCondensationResponses":
+        """Ensure there are no duplicate themes"""
+        self.validate_non_empty_fields()
+        labels = [theme.topic_label.lower().strip() for theme in self.responses]
+        if len(labels) != len(set(labels)):
+            raise ValueError("Duplicate topic labels detected")
+        return self
+
+
+class RefinedTheme(ValidatedModel):
+    """Model for a single refined theme"""
+
+    topic_id: str = Field(
+        ..., description="Single uppercase letter ID (A-Z, then AA, AB, etc.)"
+    )
+    topic: str = Field(
+        ..., description="Topic label and description combined with a colon separator"
+    )
+    source_topic_count: int = Field(
+        ..., gt=0, description="Count of source topics combined"
+    )
 
     @model_validator(mode="after")
-    def run_validations(self) -> "SentimentAnalysisOutput":
+    def run_validations(self) -> "RefinedTheme":
+        """Run all validations for RefinedTheme"""
+        self.validate_non_empty_fields()
+        self.validate_topic_id_format()
+        self.validate_topic_format()
+        return self
+
+    def validate_topic_id_format(self) -> "RefinedTheme":
+        """
+        Validate that topic_id follows the expected format (A-Z, then AA, AB, etc.).
         """
-        Run all validations for SentimentAnalysisOutput.
+        topic_id = self.topic_id.strip()
+        if not topic_id.isupper() or not topic_id.isalpha():
+            raise ValueError(f"topic_id must be uppercase letters only: {topic_id}")
+        return self
 
-        Validates that:
-         - 'position' is one of the allowed values.
-         - No fields are empty or only whitespace (for strings) and no lists are empty.
+    def validate_topic_format(self) -> "RefinedTheme":
         """
-        validate_position(self)
-        validate_non_empty_fields(self)
+        Validate that topic contains a label and description separated by a colon.
+        """
+        if ":" not in self.topic:
+            raise ValueError(
+                "Topic must contain a label and description separated by a colon"
+            )
+
+        label, description = self.topic.split(":", 1)
+        if not label.strip() or not description.strip():
+            raise ValueError("Both label and description must be non-empty")
+
+        word_count = len(label.strip().split())
+        if word_count > 10:
+            raise ValueError(f"Topic label must be under 10 words (found {word_count})")
+
         return self
 
 
-class ThemeMappingOutput(BaseModel):
-    response_id: int = Field(gt=0)
-    labels: list[str]
-    reasons: list[str]
-    stances: list[str]
+class ThemeRefinementResponses(ValidatedModel):
+    """Container for all refined themes"""
+
+    responses: List[RefinedTheme] = Field(..., description="List of refined themes")
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "ThemeRefinementResponses":
+        """Ensure there are no duplicate themes"""
+        self.validate_non_empty_fields()
+        topic_ids = [theme.topic_id for theme in self.responses]
+        if len(topic_ids) != len(set(topic_ids)):
+            raise ValueError("Duplicate topic_ids detected")
+        topics = [theme.topic.lower().strip() for theme in self.responses]
+        if len(topics) != len(set(topics)):
+            raise ValueError("Duplicate topics detected")
+
+        return self
+
+
+class ThemeMappingOutput(ValidatedModel):
+    """Model for theme mapping output"""
+
+    response_id: int = Field(gt=0, description="Response ID, must be greater than 0")
+    labels: List[str] = Field(..., description="List of theme labels")
+    reasons: List[str] = Field(..., description="List of reasons for mapping")
+    stances: List[Stance] = Field(
+        ..., description="List of stances (POSITIVE or NEGATIVE)"
+    )
 
     @model_validator(mode="after")
     def run_validations(self) -> "ThemeMappingOutput":
         """
         Run all validations for ThemeMappingOutput.
+        """
+        self.validate_non_empty_fields()
+        self.validate_equal_lengths("stances", "labels", "reasons")
+        self.validate_unique_items("labels")
+        return self
+
+
+class ThemeMappingResponses(ValidatedModel):
+    """Container for all theme mapping responses"""
+
+    responses: List[ThemeMappingOutput] = Field(
+        ..., description="List of theme mapping outputs"
+    )
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "ThemeMappingResponses":
+        """
+        Validate that response_ids are unique.
+        """
+        self.validate_non_empty_fields()
+        response_ids = [resp.response_id for resp in self.responses]
+        if len(response_ids) != len(set(response_ids)):
+            raise ValueError("Response IDs must be unique")
+        return self
+
 
-        Validates that:
-         - 'stances' are only 'POSITIVE' or 'NEGATIVE'.
-         - The 'stances' and 'labels' have matching lengths.
-         - 'labels' are unique.
+class DetailDetectionOutput(ValidatedModel):
+    """Model for detail detection output"""
+
+    response_id: int = Field(gt=0, description="Response ID, must be greater than 0")
+    evidence_rich: EvidenceRich = Field(
+        ..., description="Whether the response is evidence-rich (YES or NO)"
+    )
+
+
+class DetailDetectionResponses(ValidatedModel):
+    """Container for all detail detection responses"""
+
+    responses: List[DetailDetectionOutput] = Field(
+        ..., description="List of detail detection outputs"
+    )
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "DetailDetectionResponses":
         """
-        validate_stances(self)
-        validate_mapping_stance_lengths(self)
-        validate_mapping_unique_labels(self)
+        Validate that response_ids are unique.
+        """
+        self.validate_non_empty_fields()
+        response_ids = [resp.response_id for resp in self.responses]
+        if len(response_ids) != len(set(response_ids)):
+            raise ValueError("Response IDs must be unique")
+        return self
+
+
+class ThemeNode(ValidatedModel):
+    """Model for topic nodes created during hierarchical clustering"""
+
+    topic_id: str = Field(
+        ...,
+        description="Short alphabetic ID (e.g. 'A', 'B', 'C') - iteration prefix will be added automatically",
+    )
+    topic_label: str = Field(
+        ..., description="4-5 word label encompassing merged child topics"
+    )
+    topic_description: str = Field(
+        ..., description="1-2 sentences combining key aspects of child topics"
+    )
+    source_topic_count: int = Field(gt=0, description="Sum of all child topic counts")
+    parent_id: Optional[str] = Field(
+        default=None,
+        description="Internal field: ID of parent topic node, managed by clustering agent, not set by LLM",
+    )
+    children: List[str] = Field(
+        default_factory=list, description="List of topic_ids of merged child topics"
+    )
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "ThemeNode":
+        """Validate topic node constraints"""
+        if self.children:
+            # Each parent must have at least 2 children
+            if len(self.children) < 2:
+                raise ValueError("Each topic node must have at least 2 children")
+            # Validate children are unique
+            if len(self.children) != len(set(self.children)):
+                raise ValueError("Child topic IDs must be unique")
+
+        return self
+
+
+class HierarchicalClusteringResponse(ValidatedModel):
+    """Model for hierarchical clustering agent response"""
+
+    parent_themes: List[ThemeNode] = Field(
+        default=[],
+        description="List of parent themes created by merging similar themes",
+    )
+    should_terminate: bool = Field(
+        ...,
+        description="True if no more meaningful clustering is possible, false otherwise",
+    )
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "HierarchicalClusteringResponse":
+        """Validate clustering response constraints"""
+        self.validate_non_empty_fields()
+
+        # Validate that no child appears in multiple parents
+        all_children = []
+        for parent in self.parent_themes:
+            all_children.extend(parent.children)
+
+        if len(all_children) != len(set(all_children)):
+            raise ValueError("Each child theme can have at most one parent")
+
         return self

themefinder/prompts/agentic_theme_clustering.txt

@@ -0,0 +1,31 @@
+Analyze these topics and identify which ones should be merged based on semantic similarity.
+Your goal is to significantly reduce the number of topics by creating meaningful parent topics.
+Be aggressive in finding opportunities to merge topics that share any semantic relationship.
+
+TOPICS:
+{themes_json}
+
+For each group of similar topics that should be merged, create a new parent topic.
+
+Guidelines:
+- Each parent topic must have at least 2 children, it can have more than 2 if appropriate
+- Each child topic can have at most 1 parent
+- topic_id should be a simple alphabetic ID (e.g. 'A', 'B', 'C') - the iteration prefix will be added automatically
+- Be creative and look for higher-level abstractions that can combine seemingly different topics
+- When creating parent topics, follow these naming rules:
+    * The label should read naturally as a single coherent topic
+    * Choose labels that can encompass broader categories of topics
+    * If merging different topics, the topic with the higher source_topic_count should dominate the label
+    * Never combine different topics with "and" or "/" in the label
+- topic_description must be 1 or 2 sentences that:
+    * preserves key information from the child topics
+- source_topic_count must be the sum of all child topic counts
+- children must be a list of valid topic_ids from the input
+- should_terminate should only be true if ALL of these conditions are met:
+    * There are fewer than 10 active topics remaining
+    * The remaining topics are fundamentally incompatible semantically
+    * Any further merging would create meaninglessly broad categories
+
+If no topics should be merged in this iteration but future iterations might still yield meaningful merges, set should_terminate to false with an empty parent_themes list.
+
+If no topics should be merged and the termination conditions are met, set should_terminate to true with an empty parent_themes list.

themefinder/prompts/detail_detection.txt

@@ -0,0 +1,19 @@
+{system_prompt}
+
+You will receive a list of RESPONSES, each containing a response_id and a response.
+Your job is to analyze each response to the QUESTION below and decide if a response contains rich evidence.
+You MUST include every response ID in the output.
+
+Evidence-rich responses contain one or more of the following:
+- Specific facts or figures that shed new light on the issue (e.g., statistics, percentages, measurements, dates)
+- Concrete examples and specific insights that could inform decision-making
+- Detailed personal or professional experiences with clear contextual information or specific incidents
+In addition to the above an evidence rich response should answer the question and provide deeper insights than an average response.
+
+For each response, determine:
+EVIDENCE_RICH - does the response contain significant evidence as defined above?
+Choose one from ['YES', 'NO']
+
+
+QUESTION: \n {question}
+RESPONSES: \n {responses}

themefinder/prompts/sentiment_analysis.txt

@@ -6,20 +6,6 @@ Your job is to analyze each response to the QUESTION below and decide:
 POSITION - is the response AGREEING or DISAGREEING or is it UNCLEAR about the change being proposed in the question.
 Choose one from [AGREEMENT, DISAGREEMENT, UNCLEAR]
 
-The final output should be in the following JSON format:
-
-{{"responses": [
-    {{
-        "response_id": "{{response_id_1}}",
-        "position": {{position_1}},
-    }},
-    {{
-        "response_id": "{{response_id_2}}",
-        "position": {{position_2}},
-    }}
-    ...
-]}}
-
 You MUST include every response ID in the output.
 If the response can not be labelled return empty sections where appropriate but you MUST return an entry
 with the correct response ID for each input object

themefinder/prompts/theme_condensation.txt

@@ -23,28 +23,8 @@ For each topic in your output:
 2. Write a concise description that incorporates key insights from all constituent topics, this should only be a single sentence
 3. Include the total count of original topics combined by summing the source_topic_counts of merged topics (or 1 for topics without a count)
 
-The final output should be in the following JSON format:
-
-{{"responses": [
-    {{"topic_label": "{{label for condensed topic 1}}", 
-      "topic_description": "{{description for condensed topic 1}}",
-      "source_topic_count": {{sum of source_topic_counts from combined topics}}
-    }},
-    {{"topic_label": "{{label for condensed topic 2}}", 
-      "topic_description": "{{description for condensed topic 2}}",
-      "source_topic_count": {{sum of source_topic_counts from combined topics}}
-    }},
-    {{"topic_label": "{{label for condensed topic 3}}", 
-      "topic_description": "{{description for condensed topic 3}}",
-      "source_topic_count": {{sum of source_topic_counts from combined topics}}
-    }},
-    // Additional topics as necessary
-]}}
-
-[Question]
-
+QUESTION:
 {question}
 
-[Themes]
-
+TOPICS:
 {responses}

themefinder/prompts/theme_generation.txt

@@ -7,28 +7,12 @@ Your task is to analyze the RESPONSES below and extract TOPICS such that:
 2. Every distinct and relevant point of view in the responses should be captured by a topic 
 3. Each topic has a topic_label which summarizes the topic in a few words
 4. Each topic has a topic_description which gives more detail about the topic in one or two sentences
-5. The position field should just be the sentiment stated, and is either "agreement" or "disagreement" or "unclear"
+5. The position field should just be the sentiment stated, and is either "AGREEMENT" or "DISAGREEMENT" or "UNCLEAR"
 6. There should be no duplicate topics 
 
 The topics identified will be used by policy makers to understand what the public like and don't like about the proposals. 
 
-Here is an example of how to extract topics from some responses
-
-The final output should be in the following JSON format:
-
-{{"responses": [
-    {{
-        "topic_label": "{{label_1}}",
-        "topic_description": "{{description_1}}",
-        "position": "{{position_1}}"
-    }},
-    {{
-        "topic_label": "{{label_2}}",
-        "topic_description": "{{description_2}}",
-        "position": "{{position_2}}"
-    }},
-    // Additional topics as necessary
-]}}
+Here is an example of how to extract topics from some responses:
 
 ## EXAMPLE
 
@@ -42,26 +26,10 @@ RESPONSES
     {{"response": "I hate grapes", "position": "disagreement"}},
 ]
 
-OUTPUTS
-
-{{"responses": [
-    {{
-        "topic_label": "Government overreach",
-        "topic_description": "The proposals would result in government interfering too much with citizen's lives",
-        "position": "disagreement"
-    }},
-    {{
-        "topic_label": "Regressive change",
-        "topic_description": "The change would have a larger negative impact on poorer people",
-        "position": "disagreement"
-    }},
-    {{
-        "topic_label": "Health",
-        "topic_description": "The change would result in people eating healthier diets",
-        "position": "disagreement"
-    }},
-]}}
-
+EXAMPLE OUTPUT (showing the structure)
+- Topic 1: Government overreach (The proposals would result in government interfering too much with citizen's lives) - DISAGREEMENT
+- Topic 2: Regressive change (The change would have a larger negative impact on poorer people) - DISAGREEMENT
+- Topic 3: Health (The change would result in people eating healthier diets) - DISAGREEMENT
 
 QUESTION:
 {question}