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

themefinder/models.py

@@ -0,0 +1,351 @@
+from typing import List, Optional
+from enum import Enum
+from pydantic import BaseModel, Field, model_validator
+
+
+class Position(str, Enum):
+    """Enum for valid position values"""
+
+    AGREEMENT = "AGREEMENT"
+    DISAGREEMENT = "DISAGREEMENT"
+    UNCLEAR = "UNCLEAR"
+
+
+class Stance(str, Enum):
+    """Enum for valid stance values"""
+
+    POSITIVE = "POSITIVE"
+    NEGATIVE = "NEGATIVE"
+
+
+class EvidenceRich(str, Enum):
+    """Enum for valid evidence_rich values"""
+
+    YES = "YES"
+    NO = "NO"
+
+
+class ValidatedModel(BaseModel):
+    """Base model with common validation methods"""
+
+    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
+
+    def validate_unique_items(
+        self, field_name: str, transform_func: Optional[callable] = None
+    ) -> "ValidatedModel":
+        """
+        Validate that a field contains unique values.
+
+        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
+
+    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_equal_lengths(self, *field_names) -> "ValidatedModel":
+        """
+        Validate that multiple list fields have the same length.
+
+        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
+
+    @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()
+
+
+class SentimentAnalysisOutput(ValidatedModel):
+    """Model for sentiment analysis output"""
+
+    response_id: int = Field(gt=0)
+    position: Position
+
+
+class SentimentAnalysisResponses(ValidatedModel):
+    """Container for all sentiment analysis responses"""
+
+    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 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) -> "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.).
+        """
+        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
+
+    def validate_topic_format(self) -> "RefinedTheme":
+        """
+        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 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)"
+    )
+
+
+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.
+        """
+        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

@@ -3,41 +3,30 @@
 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:
 
-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}},
-    }}
-    ...
-]}}
+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]
 
 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
 
+You MUST pick one of the given POSITION values.
+You MUST not return an empty value for the POSITION of a response.
+
 ## EXAMPLE
 Example 1:
 Question: \n What are your thoughts on the proposed government changes to the policy about reducing school holidays?
 Response: \n as a parent I have no idea why you would make this change. I guess you were thinking about increasing productivity but any productivity gains would be totally offset by the decrease in family time. \n
 
 Output:
-POSITION: disagreement
+POSITION: DISAGREEMENT
 
 Example 2:
 Question: \n What are your thoughts on the proposed government changes to the policy about reducing school holidays?
 Response: \n I think this is a great idea, our children will learn more if they are in school more \n
 
 Output:
-POSITION: agreement
+POSITION: AGREEMENT
 
 Example 3:
 Question: \n What are your thoughts on the proposed government changes to the policy about reducing school holidays?
@@ -45,7 +34,7 @@ Response: \n it will be good for our children to be around their friends more bu
 less time with their children \n
 
 Output:
-POSITION: unclear
+POSITION: UNCLEAR
 
 
 QUESTION: \n {question}

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')
-    - If a response contains both positive and negative statements about a topic within the same response, choose the stance that receives more emphasis or appears more central to the argument
+    - 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

@@ -1,15 +1,16 @@
 {system_prompt}
 
-You are tasked with refining and neutralizing a list of topics generated from responses to a question. 
-Your goal is to transform opinionated topics into neutral, well-structured, and distinct topics while preserving the essential information.
+You are tasked with refining a list of topics generated from responses to a question. 
 
 ## Input
-You will receive a list of OPINIONATED TOPICS. These topics explicitly tie opinions to whether a person agrees or disagrees with the question.
+You will receive a list of TOPICS. These topics explicitly tie opinions to whether a person agrees or disagrees with the question.
 
 ## Output
-You will produce a list of NEUTRAL TOPICS based on the input. Each neutral topic should have two parts:
+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
 
@@ -17,10 +18,11 @@ You will produce a list of NEUTRAL TOPICS based on the input. Each neutral topic
    - Preserve all key information, details and concepts from the original topics.
    - Ensure no significant details are lost in the refinement process.
 
-2. Neutrality:
-   - Remove all language indicating agreement or disagreement.
-   - Present topics objectively without favoring any particular stance.
-   - Avoid phrases like "supporters believe" or "critics argue".
+2. Clear Stance Formulation:
+   - Reformulate topics to express a clear stance that can be agreed or disagreed with.
+   - Use direct language like "Increased risk of X" rather than "X"
+   - Avoid double negatives and ambiguous phrasing.
+   - Phrase topics as definitive statements.
 
 3. Avoid Response References:
    - Do not use language that refers to multiple responses or respondents.
@@ -39,43 +41,15 @@ You will produce a list of NEUTRAL TOPICS based on the input. Each neutral topic
 
 ## Process
 
-1. Analyze the OPINIONATED TOPICS to identify key themes and information.
+1. Analyze the TOPICS to identify key themes and information.
 2. Group closely related topics together.
 3. For each group or individual topic:
    a. Distill the core concept, removing any bias or opinion.
    b. Create a neutral, concise topic label.
    c. Write a more detailed description that provides context without taking sides.
 4. Review the entire list to ensure distinctiveness and adjust as needed.
-5. Double-check that all topics are truly neutral and free of response references.
-6. Assign each output topic a topic_id a single uppercase letters (starting from 'A')
-7. 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
-   ]
-}}
-
-
-## EXAMPLE
-
-OPINIONATED TOPIC:
-"Economic impact: Many respondents who support the policy believe it will create jobs and boost the economy, it could raise GDP by 2%. [source_topic_count: 15]"
-
-NEUTRAL TOPIC:
-{{
-  "topic_id": "A",
-  "topic": "Economic Impact on Employment: The policy's potential effects on job creation and overall economic growth, including potential for a 2% increase in GDP.",
-  "source_topic_count": 15
-}}
-
-Remember, your goal is to create a list of neutral, informative, and distinct topics that accurately represent the content of the original opinionated topics without any bias or references to responses.
-
-
+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
 
-OPINIONATED TOPIC:
+TOPICS:
 {responses}