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

themefinder/models.py

@@ -0,0 +1,138 @@
+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.
+
+    Args:
+        model (BaseModel): A Pydantic model instance.
+
+    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
+
+
+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.
+
+    Returns:
+        BaseModel: The same model if validation passes.
+
+    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
+
+
+def validate_stances(model: BaseModel) -> BaseModel:
+    """
+    Validate that every stance in the model's 'stances' field is allowed.
+
+    Args:
+        model (BaseModel): A Pydantic model instance with a 'stances' attribute.
+
+    Returns:
+        BaseModel: The same model if validation passes.
+
+    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_mapping_stance_lengths(model: BaseModel) -> BaseModel:
+    """
+    Validate that the lengths of the model's 'stances' and 'labels' fields match.
+
+    Args:
+        model (BaseModel): A Pydantic model instance with 'stances' and 'labels' attributes.
+
+    Returns:
+        BaseModel: The same model if validation passes.
+
+    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
+
+
+def validate_mapping_unique_labels(model: BaseModel) -> BaseModel:
+    """
+    Validate that the model's 'labels' field contains unique values.
+
+    Args:
+        model (BaseModel): A Pydantic model instance with a 'labels' attribute.
+
+    Returns:
+        BaseModel: The same model if validation passes.
+
+    Raises:
+        ValueError: If 'labels' contains duplicate values.
+    """
+    if len(model.labels) != len(set(model.labels)):
+        raise ValueError("'labels' must be unique")
+    return model
+
+
+class SentimentAnalysisOutput(BaseModel):
+    response_id: int = Field(gt=0)
+    position: str
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "SentimentAnalysisOutput":
+        """
+        Run all validations for SentimentAnalysisOutput.
+
+        Validates that:
+         - 'position' is one of the allowed values.
+         - No fields are empty or only whitespace (for strings) and no lists are empty.
+        """
+        validate_position(self)
+        validate_non_empty_fields(self)
+        return self
+
+
+class ThemeMappingOutput(BaseModel):
+    response_id: int = Field(gt=0)
+    labels: list[str]
+    reasons: list[str]
+    stances: list[str]
+
+    @model_validator(mode="after")
+    def run_validations(self) -> "ThemeMappingOutput":
+        """
+        Run all validations for ThemeMappingOutput.
+
+        Validates that:
+         - 'stances' are only 'POSITIVE' or 'NEGATIVE'.
+         - The 'stances' and 'labels' have matching lengths.
+         - 'labels' are unique.
+        """
+        validate_stances(self)
+        validate_mapping_stance_lengths(self)
+        validate_mapping_unique_labels(self)
+        return self

themefinder/prompts/sentiment_analysis.txt

@@ -3,8 +3,8 @@
 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]
+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:
 
@@ -24,20 +24,23 @@ 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 +48,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

@@ -1,30 +1,43 @@
 {system_prompt}
 
-Below is a question and a list of topics extracted from answers to that question. Each topic has a topic_label and a topic_description.
+Below is a question and a list of topics extracted from answers to that question. 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. Identifies and preserves core themes that appear frequently
 2. Combines redundant topics while maintaining nuanced differences
 3. Ensures the final list represents the full spectrum of viewpoints present in the original data
+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
-
-Return at most 30 topics
+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}}"}},
-    {{"topic_label": "{{label for condensed topic 2}}", "topic_description": "{{description for condensed topic 2}}"}},
-    {{"topic_label": "{{label for condensed topic 3}}", "topic_description": "{{description for condensed topic 3}}"}},
+    {{"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
 ]}}
 

themefinder/prompts/theme_mapping.txt

@@ -17,7 +17,7 @@ Your task is to analyze each response and decide which topics are present. Guide
     - 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 'POSTIVE' 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.
@@ -30,13 +30,13 @@ The final output should be in the following JSON format:
 {{
   "responses": [
     {{
-      "response_id": "response_id_1",
+      "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",
+      "response_id": response_id_2,
       "reasons": ["reason_c"],
       "labels": ["topic_c"],
       "stances": ["stance_c"],

themefinder/prompts/theme_refinement.txt

@@ -1,13 +1,12 @@
 {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)
 
@@ -17,10 +16,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,40 +39,27 @@ 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
+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}}"}},
-       {{"topic_id": "B", "topic": "{{topic label 2}}: {{topic description 2}}"}},
-       {{"topic_id": "C", "topic": "{{topic label 3}}: {{topic description 3}}"}},
+       {{"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%."
-
-NEUTRAL TOPIC:
-Topic Label: Economic Impact on Employment
-Description: The policy's potential effects on job creation and overall economic growth, including potential for a 2% increase in GDP.
-
-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.
-
-
-
-OPINIONATED TOPIC:
+TOPICS:
 {responses}

{themefinder-0.5.3.dist-info → themefinder-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: themefinder
-Version: 0.5.3
+Version: 0.6.2
 Summary: A topic modelling Python package designed for analysing one-to-many question-answer data eg free-text survey responses.
 License: MIT
 Author: i.AI
@@ -100,7 +100,7 @@ system_prompt = "You are an AI evaluation tool analyzing survey responses about
 # Run the function to find themes
 # We use asyncio to query LLM endpoints asynchronously, so we need to await our function
 async def main():
-    result = await find_themes(responses_df, llm, question, system_prompt)
+    result = await find_themes(responses_df, llm, question, system_prompt=system_prompt)
     print(result)
 
 if __name__ == "__main__":
@@ -155,3 +155,4 @@ The documentation is [© Crown copyright](https://www.nationalarchives.gov.uk/in
 ## Feedback
 
 If you have feedback on this package, please fill in our [feedback form](https://forms.gle/85xUSMvxGzSSKQ499) or contact us with questions or feedback at packages@cabinetoffice.gov.uk.
+

themefinder-0.6.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+themefinder/__init__.py,sha256=wSpW2fEnC4gTzbeNC78nSD3DpJq43-h_H-LK_cqt1cw,327
+themefinder/core.py,sha256=u1DY9gbzn-tFhQS3hrXQ8_1mIbR-iBWYVAdKeAX1BdE,18304
+themefinder/llm_batch_processor.py,sha256=OrFEl1nSi5ninbSZSiE1HFMcYZiQ-NzuYPj_iDcPPoE,19988
+themefinder/models.py,sha256=Y5-okndYwtBO09n_qUlYNVmHRVNEnJviArQZukm8Ox8,4251
+themefinder/prompts/consultation_system_prompt.txt,sha256=_A07oY_an4hnRx-9pQ0y-TLXJz0dd8vDI-MZne7Mdb4,89
+themefinder/prompts/sentiment_analysis.txt,sha256=9-LkdR95JTHXRKUXknAgNf86uVdv6jSaXMf-OtFL9_0,1948
+themefinder/prompts/theme_condensation.txt,sha256=DB4pqUmMpo0OG4AZWGTj0FfLFfjbX6wOMUr44HBxZ1o,2433
+themefinder/prompts/theme_generation.txt,sha256=JMXuNojxdSAcxPRU1Jg12Xunv_dX4hNvXYU2pXMWTAw,2500
+themefinder/prompts/theme_mapping.txt,sha256=YcRGMkuTyTPzPQPtsDY31DUwX60c8AdmdHKw0XeUejQ,2258
+themefinder/prompts/theme_refinement.txt,sha256=hBXwZnNZmhmoEFXpY5OJinp-7xxdoDRf_5LmgrilYgc,2713
+themefinder/prompts/theme_target_alignment.txt,sha256=-_ghr4--KAN6Tz8ExO9s2IXvI6pjWaEA_nG5L83GV5I,1035
+themefinder/themefinder_logging.py,sha256=n5SUQovEZLC4skEbxicjz_fOGF9mOk3S-Wpj5uXsaL8,314
+themefinder-0.6.2.dist-info/LICENCE,sha256=C9ULIN0ctF60ZxUWH_hw1H434bDLg49Z-Qzn6BUHgqs,1060
+themefinder-0.6.2.dist-info/METADATA,sha256=gI9Hp754EjopJQWw0QZIPb9dex8TalPMGnorUEOJlp0,6498
+themefinder-0.6.2.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+themefinder-0.6.2.dist-info/RECORD,,

{themefinder-0.5.3.dist-info → themefinder-0.6.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.1
+Generator: poetry-core 2.1.2
 Root-Is-Purelib: true
 Tag: py3-none-any

themefinder-0.5.3.dist-info/RECORD

@@ -1,15 +0,0 @@
-themefinder/__init__.py,sha256=p6QoCgA-BYWljk8yPOeTgkNcN5m_gA_o3Q86Eh0QjSM,327
-themefinder/core.py,sha256=B6Du59rPsZbBcP8tkKmXQn6h5vvLN_PZIferPnF3LNY,17538
-themefinder/llm_batch_processor.py,sha256=SDDeMJeX1J3u7FGFddRhVSxty6U8lFVXwG4eNI_0C5o,12573
-themefinder/prompts/consultation_system_prompt.txt,sha256=_A07oY_an4hnRx-9pQ0y-TLXJz0dd8vDI-MZne7Mdb4,89
-themefinder/prompts/sentiment_analysis.txt,sha256=e3DcUKga6pSFcfeo2TAq8x9LXk0YDV-D7P2gtymcyuc,1832
-themefinder/prompts/theme_condensation.txt,sha256=GFwwQO_oZHhqhPnAfTn887fDzAIVxKoCyj0hXagyBIU,1645
-themefinder/prompts/theme_generation.txt,sha256=JMXuNojxdSAcxPRU1Jg12Xunv_dX4hNvXYU2pXMWTAw,2500
-themefinder/prompts/theme_mapping.txt,sha256=nb_D7gwKGd8BzrAlzSZC3mQIPYaCRXdE6XmoJaJEKZQ,2405
-themefinder/prompts/theme_refinement.txt,sha256=HCgvWAoz-cpFgjX_QS_VVY0X06d4ds0ekBgcoWyFyfg,3360
-themefinder/prompts/theme_target_alignment.txt,sha256=-_ghr4--KAN6Tz8ExO9s2IXvI6pjWaEA_nG5L83GV5I,1035
-themefinder/themefinder_logging.py,sha256=n5SUQovEZLC4skEbxicjz_fOGF9mOk3S-Wpj5uXsaL8,314
-themefinder-0.5.3.dist-info/LICENCE,sha256=C9ULIN0ctF60ZxUWH_hw1H434bDLg49Z-Qzn6BUHgqs,1060
-themefinder-0.5.3.dist-info/METADATA,sha256=o9rzrhRK-4PMAv9wS8ZrnmTw1rTSYGU8zfPbB31r1DU,6483
-themefinder-0.5.3.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-themefinder-0.5.3.dist-info/RECORD,,