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

themefinder/models.py

@@ -1,138 +1,351 @@
+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 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 SentimentAnalysisOutput(BaseModel):
-    response_id: int = Field(gt=0)
-    position: str
+
+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 that topic contains a label and description separated by a colon.
         """
-        validate_position(self)
-        validate_non_empty_fields(self)
+        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
+
+
+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)"
+    )
+
 
-        Validates that:
-         - 'stances' are only 'POSITIVE' or 'NEGATIVE'.
-         - The 'stances' and 'labels' have matching lengths.
-         - 'labels' are unique.
+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 that response_ids are unique.
         """
-        validate_stances(self)
-        validate_mapping_stance_lengths(self)
-        validate_mapping_unique_labels(self)
+        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

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}

themefinder/prompts/theme_mapping.txt

@@ -1,12 +1,12 @@
 {system_prompt}
 
-Your job is to help identify which topics come up in responses to a question.
+Your job is to help identify which topics come up in free_text_responses to a question.
 
 You will be given:
     - a QUESTION that has been asked
-    - a TOPIC LIST of topics that are known to be present in responses to this question. These will be structured as follows:
+    - a TOPIC LIST of topics that are known to be present in free_text_responses to this question. These will be structured as follows:
         {{'topic_id': 'topic_description}}
-    - a list of RESPONSES to the question. These will be structured as follows:
+    - a list of FREE_TEXT_RESPONSES to the question. These will be structured as follows:
         {{'response_id': 'free text response'}}
 
 Your task is to analyze each response and decide which topics are present. Guidelines:
@@ -14,10 +14,11 @@ Your task is to analyze each response and decide which topics are present. Guide
     - A response doesn't need to exactly match the language used in the TOPIC LIST, it should be considered a match if it expresses a similar sentiment.
     - You must use the alphabetic 'topic_id' to indicate which topic you have assigned. Do not use the full topic description
     - Each response can be assigned to multiple topics if it matches more than one topic from the TOPIC LIST.
+    - Each topic can only be assigned once per response, if the topic is mentioned more than once use the first mention for reasoning and stance.
     - There is no limit on how many topics can be assigned to a response.
     - For each assignment provide a single rationale for why you have chosen the label.
     - For each topic identified in a response, indicate whether the response expresses a positive or negative stance toward that topic (options: 'POSITIVE' or 'NEGATIVE')
-    - You MUST use either 'POSTIVE' or 'NEGATIVE'
+    - You MUST use either 'POSITIVE' or 'NEGATIVE'
     - The order of reasons and stances must align with the order of labels (e.g., stance_a applies to topic_a)
 
 You MUST include every response ID in the output.
@@ -25,24 +26,6 @@ If the response can not be labelled return empty sections where appropriate but
 with the correct response ID for each input object.
 You must only return the alphabetic topic_ids in the labels section.
 
-The final output should be in the following JSON format:
-
-{{
-  "responses": [
-    {{
-      "response_id": response_id_1,
-      "reasons": ["reason_a", "reason_b"],
-      "labels": ["topic_a", "topic_b"],
-      "stances": ["stance_a", "stance_b"],
-    }},
-    {{
-      "response_id": response_id_2,
-      "reasons": ["reason_c"],
-      "labels": ["topic_c"],
-      "stances": ["stance_c"],
-    }}
-  ]
-}}
 
 QUESTION:
 
@@ -52,6 +35,6 @@ TOPIC LIST:
 
 {refined_themes}
 
-RESPONSES:
+FREE_TEXT_RESPONSES:
 
 {responses}

themefinder/prompts/theme_refinement.txt

@@ -9,6 +9,8 @@ You will receive a list of TOPICS. These topics explicitly tie opinions to wheth
 You will produce a list of CLEAR STANCE TOPICS based on the input. Each topic should have two parts:
 1. A brief, clear topic label (3-7 words)
 2. A more detailed topic description (1-2 sentences)
+3. The source_topic_count field should be included for each topic and should reflect the number of original source topics that were merged to create this refined topic. If multiple source topics were combined, sum their individual counts. If only one source topic was used, simply retain its original count value.
+
 
 ## Guidelines
 
@@ -49,17 +51,5 @@ You will produce a list of CLEAR STANCE TOPICS based on the input. Each topic sh
 5. Assign each output topic a topic_id a single uppercase letters (starting from 'A', for the 27th element use AA)
 6. Combine the topic label and description with a colon separator
 
-Return your output in the following JSON format:
-{{
-   "responses": [
-       {{"topic_id": "A", "topic": "{{topic label 1}}: {{topic description 1}}", "source_topic_count": {{count1}}}},
-       {{"topic_id": "B", "topic": "{{topic label 2}}: {{topic description 2}}", "source_topic_count": {{count2}}}},
-       {{"topic_id": "C", "topic": "{{topic label 3}}: {{topic description 3}}", "source_topic_count": {{count3}}}},
-      // Additional topics as necessary
-   ]
-}}
-
-
-
 TOPICS:
 {responses}