themefinder 0.7.4__py3-none-any.whl

themefinder/models.py

@@ -0,0 +1,438 @@
+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: 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_format()
+        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()
+        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")
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "ThemeMappingOutput":
+        """
+        Run all validations for ThemeMappingOutput.
+        """
+        self.validate_non_empty_fields()
+        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
+
+
+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
+
+
+# Cross-Cutting Theme Identification Models
+
+
+class CrossCuttingThemeDefinition(BaseModel):
+    """Model for a high-level cross-cutting theme."""
+
+    name: str = Field(
+        ...,
+        description="Short, descriptive name for the cross-cutting theme (3-7 words)",
+    )
+    description: str = Field(
+        ...,
+        description="2-sentence description of what this cross-cutting theme represents",
+    )
+
+
+class CrossCuttingThemeIdentificationResponse(BaseModel):
+    """Response model for identifying cross-cutting themes."""
+
+    themes: List[CrossCuttingThemeDefinition] = Field(
+        default=[], description="List of identified cross-cutting themes"
+    )
+
+
+class CrossCuttingThemeMapping(BaseModel):
+    """Model for mapping individual themes to a cross-cutting theme."""
+
+    theme_name: str = Field(
+        ..., description="Name of the cross-cutting theme this theme belongs to"
+    )
+    theme_ids: List[str] = Field(
+        ...,
+        description="List of theme IDs that belong to this cross-cutting theme (e.g., ['A', 'B', 'C'])",
+    )
+
+
+class CrossCuttingThemeMappingResponse(BaseModel):
+    """Response model for mapping question themes to cross-cutting themes."""
+
+    mappings: List[CrossCuttingThemeMapping] = Field(
+        default=[], description="List of cross-cutting theme mappings for this question"
+    )

themefinder/prompts/agentic_theme_clustering.txt

@@ -0,0 +1,34 @@
+{system_prompt}
+
+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 {target_themes} 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.
+
+N.B. Under no circumstances should you create a parent theme with a single child. You do not need to return all of the original themes, if they don't belong to a newly created parent feel free to omit them. 

themefinder/prompts/consultation_system_prompt.txt

@@ -0,0 +1 @@
+You are an AI evaluation tool analyzing responses to a UK Government public consultation.

themefinder/prompts/cross_cutting_identification.txt

@@ -0,0 +1,16 @@
+You are helping in the analysis of a consultation (a survey on a proposed policy).
+
+We have already run a topic modelling algorithm on individual questions in the consultation.
+You are going to be shown questions in the consultation and the themes that were extracted from them by the model.
+Your job is to come up with {n_concepts} high level concepts that unify a large number of the themes across the consultation.
+Not every question theme has to belong to one of these concepts but the concepts you identify should capture multiple themes across multiple questions.
+
+These high level concepts should be the type of take homes that policy maker should consider while trying to implement a policy related to this consultation.
+
+IMPORTANT: Each cross-cutting concept should be distinct and non-overlapping. When designing these concepts, ensure that themes would naturally belong to only one concept, not multiple. Avoid creating concepts that could capture the same themes.
+
+You should output a short name of each concept and a 2 sentence description of the concept.
+
+Questions and topics:
+
+{questions_and_themes}

themefinder/prompts/cross_cutting_mapping.txt

@@ -0,0 +1,19 @@
+You are helping to analyse themes extracted in responses to a government consultation.
+You have identified cross-cutting themes that capture topics raised across different questions.
+You are now looking at themes from a specific question and need to determine which themes 
+belong to which cross-cutting themes.
+
+IMPORTANT CONSTRAINTS:
+1. Only assign themes to cross-cutting themes if there is a strong semantic match.
+2. Not every theme needs to be assigned to a cross-cutting theme.
+3. Each theme can be assigned to AT MOST ONE cross-cutting theme - never assign the same theme to multiple cross-cutting themes.
+
+For each cross-cutting theme that has matching themes, provide:
+- theme_name: The exact name of the cross-cutting theme (must match one from the list)
+- theme_ids: List of theme IDs that belong to this cross-cutting theme (e.g., ["A", "B"])
+
+Question themes:
+{question_input}
+
+Cross-cutting themes:
+{concepts_text}

themefinder/prompts/cross_cutting_refinement.txt

@@ -0,0 +1,15 @@
+You are going to be given a number of themes extracted from survey responses to a range of questions.
+Each theme will be presented alongside the question it was raised in.
+All of the themes were grouped together under the following parent theme:
+{concept_name}
+
+Your task is to read each of the themes and generate a brief 2-3 sentence synthesis of what these themes represent collectively. 
+Capture interesting nuances and details from each of the themes in the list. 
+Produce a concise, insightful summary rather than a lengthy description that simply combines all original theme descriptions. 
+Focus on insights that would be valuable for policy makers reviewing this survey and implementing changes.
+
+Return only the description text without any preamble.
+Do not begin the description with the name of the parent theme.
+
+QUESTIONS AND THEMES:
+{theme_lines}

themefinder/prompts/detail_detection.txt

@@ -0,0 +1,31 @@
+{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.
+
+A response is evidence-rich only if it satisfies both of the following:
+
+Relevance and depth:
+    - It clearly answers the question
+    - AND provides insights that go beyond generic opinion, such as nuanced reasoning, contextual explanation, or argumentation that could inform decision-making
+
+Substantive evidence, including at least one of:
+    - Specific, verifiable facts or data (e.g., statistics, dates, named reports or studies)
+    - Concrete, illustrative examples that clearly support a broader claim
+    - Detailed personal or professional experiences that include contextual information (e.g., roles, locations, timelines)
+
+Do NOT classify a response as evidence-rich if it:
+    - Uses vague or general language with no supporting detail
+    - Restates commonly known points without adding new information
+    - Shares personal anecdotes without sufficient context or a clear takeaway
+
+Before answering, ask: Would this response provide useful input to someone drafting policy, beyond what is already commonly known or expected?
+
+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

@@ -0,0 +1,41 @@
+{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:
+
+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
+
+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
+
+Example 3:
+Question: \n What are your thoughts on the proposed government changes to the policy about reducing school holidays?
+Response: \n it will be good for our children to be around their friends more but it will be hard for some parents spend
+less time with their children \n
+
+Output:
+POSITION: UNCLEAR
+
+
+QUESTION: \n {question}
+RESPONSES: \n {responses}

themefinder/prompts/theme_condensation.txt

@@ -0,0 +1,34 @@
+{system_prompt}
+
+Below is a question and a list of topics extracted from answers to that question. 
+
+This list contains a large number of duplicate and redundant topics that present the same concept with different phrasing.
+
+Each topic has a topic_label, topic_description, and may have a source_topic_count field indicating how many original topics it represents.
+
+Your task is to analyze these topics and produce a refined list that:
+1. Significantly reduces the total number of topics
+2. Identifies and preserves core themes that appear frequently
+3. Combines redundant topics
+4. Tracks the total number of original topics combined into each new topic
+
+Guidelines for Topic Analysis:
+- Begin by identifying distinct concept clusters in the topics
+- Consider the context of the question when determining topic relevance
+- Look for complementary perspectives that could enrich understanding of the same core concept
+- Consider the key ideas behind themes when merging, don't simply focus on the words used in the label and description
+- When combining topics:
+  * For topics without a source_topic_count field, assume count = 1
+  * For topics with source_topic_count, use their existing count
+  * The new topic's count should be the sum of all combined topics' counts
+
+For each topic in your output:
+1. Choose a clear, representative label that captures the essence of the combined or preserved topic
+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)
+
+QUESTION:
+{question}
+
+TOPICS:
+{responses}

themefinder/prompts/theme_generation.txt

@@ -0,0 +1,38 @@
+{system_prompt}
+
+Below is a question and a list of responses to that question.
+
+Your task is to analyze the RESPONSES below and extract TOPICS such that: 
+1. Each topic summarizes a point of view expressed in the responses 
+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"
+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:
+
+## EXAMPLE
+
+QUESTION 
+What are your views on the proposed change by the government to introduce a 2% tax on fast food meat products. 
+
+RESPONSES 
+[
+    {{"response": "I wish the government would stop interfering in the lves of its citizens. It only ever makes things worse. This change will just cost us all more money, and especially poorer people", "position": "disagreement"}},
+    {{"response": "Even though it will make people eat more healthier, I beleibe the government should interfer less and not more!", "position": "disagreement"}},
+    {{"response": "I hate grapes", "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}
+
+RESPONSES:
+{responses}