themefinder 0.7.4__py3-none-any.whl

themefinder-0.7.4.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: themefinder
+Version: 0.7.4
+Summary: A topic modelling Python package designed for analysing one-to-many question-answer data eg free-text survey responses.
+License: MIT
+License-File: LICENCE
+Author: i.AI
+Author-email: packages@cabinetoffice.gov.uk
+Requires-Python: >=3.10,<3.13
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Dist: boto3 (>=1.29,<2.0)
+Requires-Dist: langchain
+Requires-Dist: langchain-openai
+Requires-Dist: langfuse (==2.29.1)
+Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
+Requires-Dist: pandas (>=2.2.2,<3.0.0)
+Requires-Dist: pyarrow (>=15.0.0,<16.0.0)
+Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
+Requires-Dist: scikit-learn
+Requires-Dist: toml (>=0.10.2,<0.11.0)
+Project-URL: Documentation, https://i-dot-ai.github.io/themefinder/
+Project-URL: Repository, https://github.com/i-dot-ai/themefinder/
+Description-Content-Type: text/markdown
+
+# ThemeFinder
+
+ThemeFinder is a topic modelling Python package designed for analysing one-to-many question-answer data (i.e. survey responses, public consultations, etc.). See the [docs](https://i-dot-ai.github.io/themefinder/) for more info.
+
+> [!IMPORTANT]
+> Incubation project: This project is an incubation project; as such, we don't recommend using this for critical use cases yet. We are currently in a research stage, trialling the tool for case studies across the Civil Service. Find out more about our projects at https://ai.gov.uk/. 
+
+
+## Quickstart
+
+### Install using your package manager of choice
+
+For example `pip install themefinder` or `poetry add themefinder`.
+
+### Usage
+
+ThemeFinder takes as input a [pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) with two columns:
+- `response_id`: A unique identifier for each response
+- `response`: The free text survey response
+
+ThemeFinder now supports a range of language models through structured outputs.
+
+The function `find_themes` identifies common themes in responses and labels them, it also outputs results from intermediate steps in the theme finding pipeline.
+
+For this example, import the following Python packages into your virtual environment: `asyncio`, `pandas`, `lanchain`. And import `themefinder` as described above.
+
+If you are using environment variables (eg for API keys), you can use `python-dotenv` to read variables from a `.env` file. 
+
+If you are using an Azure OpenAI endpoint, you will need the following variables:
+
+- `AZURE_OPENAI_API_KEY`
+- `AZURE_OPENAI_ENDPOINT`
+- `OPENAI_API_VERSION`
+- `DEPLOYMENT_NAME`
+- `AZURE_OPENAI_BASE_URL`
+
+Otherwise you will need whichever variables [LangChain](https://www.langchain.com/) requires for your LLM of choice.
+
+```python
+import asyncio
+from dotenv import load_dotenv
+import pandas as pd
+from langchain_openai import AzureChatOpenAI
+from themefinder import find_themes
+
+# If needed, load LLM API settings from .env file
+load_dotenv()
+
+# Initialise your LLM of choice using langchain
+llm = AzureChatOpenAI(
+    model="gpt-4o",
+    temperature=0,
+)
+
+# Set up your data
+responses_df = pd.DataFrame({
+   "response_id": ["1", "2", "3", "4", "5"],
+   "response": ["I think it's awesome, I can use it for consultation analysis.", 
+   "It's great.", "It's a good approach to topic modelling.", "I'm not sure, I need to trial it more.", "I don't like it so much."]
+})
+
+# Add your question
+question = "What do you think of ThemeFinder?"
+
+# Make the system prompt specific to your use case 
+system_prompt = "You are an AI evaluation tool analyzing survey responses about a Python package."
+
+# 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=system_prompt)
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## ThemeFinder pipeline
+
+ThemeFinder's pipeline consists of five distinct stages, each utilizing a specialized LLM prompt:
+
+### Sentiment analysis
+- Analyses the emotional tone and position of each response using sentiment-focused prompts
+- Provides structured sentiment categorisation based on LLM analysis
+
+### Theme generation
+- Uses exploratory prompts to identify initial themes from response batches
+- Groups related responses for better context through guided theme extraction
+
+### Theme condensation
+- Employs comparative prompts to combine similar or overlapping themes
+- Reduces redundancy in identified topics through systematic theme evaluation
+
+### Theme refinement
+- Leverages standardisation prompts to normalise theme descriptions
+- Creates clear, consistent theme definitions through structured refinement
+
+### Theme target alignment
+- Optional step to consolidate themes down to a target number
+
+### Theme mapping
+- Utilizes classification prompts to map individual responses to refined themes
+- Supports multiple theme assignments per response through detailed analysis
+
+
+The prompts used at each stage can be found in `src/themefinder/prompts/`.
+
+The file `src/themefinder.core.py` contains the function `find_themes` which runs the pipline. It also contains functions fo each individual stage.
+
+
+**For more detail - see the docs: [https://i-dot-ai.github.io/themefinder/](https://i-dot-ai.github.io/themefinder/).**
+
+
+## Model Compatibility
+
+ThemeFinder's structured output approach makes it compatible with a wide range of language models from various providers. This list is non-exhaustive, and other models may also work effectively:
+
+### OpenAI Models
+- GPT-4, GPT-4o, GPT-4.1
+- All Azure OpenAI deployments
+
+### Google Models
+- Gemini series (1.5 Pro, 2.0 Pro, etc.)
+
+### Anthropic Models
+- Claude series (Claude 3 Opus, Sonnet, Haiku, etc.)
+
+### Open Source Models
+- Llama 2, Llama 3
+- Mistral models (e.g., Mistral 7B, Mixtral)
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+The documentation is [© Crown copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government 3.0 licence](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
+
+
+## Feedback
+
+Contact us with questions or feedback at packages@cabinetoffice.gov.uk.
+

themefinder-0.7.4.dist-info/RECORD

@@ -0,0 +1,24 @@
+themefinder/__init__.py,sha256=DosVY1CPiL179NnPvLhXr-7bkZDbqFp93XcJh3AswhE,474
+themefinder/advanced_tasks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+themefinder/advanced_tasks/cross_cutting_themes_agent.py,sha256=tCG1bwMXXa4Iy1rX8cJPbxps8VamhndPc9RCbbkjf5Q,15074
+themefinder/advanced_tasks/theme_clustering_agent.py,sha256=HGUEpsutBIQ80TL6stjE2zMruNwbRQkxRYpYjKnxi1E,13734
+themefinder/llm_batch_processor.py,sha256=Z9jm9Kr-6GD8g8kLkgdW97onjUbLLQ2M1YKwok39Q6Y,17652
+themefinder/models.py,sha256=iN-chIm0ojyfRPr_cj9wQU3Q4I3yrwFI3FgnYb7IjWA,15072
+themefinder/prompts/agentic_theme_clustering.txt,sha256=FuvHD4jjCDBQ1ptTKYg0W9Bpsbwy7VeK1l-NzRoEmNM,2155
+themefinder/prompts/consultation_system_prompt.txt,sha256=_A07oY_an4hnRx-9pQ0y-TLXJz0dd8vDI-MZne7Mdb4,89
+themefinder/prompts/cross_cutting_identification.txt,sha256=Dm7BwIZV21HgnAOQd3EMatuhwRtQS-pxttQC_ekAb9g,1115
+themefinder/prompts/cross_cutting_mapping.txt,sha256=d7w1SFEyQ6IQWUuzzlvVWW9yYW4WByoIP0Ls6lHg9JU,929
+themefinder/prompts/cross_cutting_refinement.txt,sha256=5nWH-lbpVJD9BRvxjnHifmjVb0oGAIfJaBxL4f6XOss,860
+themefinder/prompts/detail_detection.txt,sha256=hMB8yQR5y855TJLYSW3CNZDkLTPaA2lf9UJwH_GpkD4,1515
+themefinder/prompts/sentiment_analysis.txt,sha256=vYCDhtEsG5I9xixwVhZbvKPJGU1Gqpw4-xAqGz72xhU,1671
+themefinder/prompts/theme_condensation.txt,sha256=jqWKuPaSKrRGeYwNWTlVx45hfyWWhX1CvnKXrIiXxa0,1714
+themefinder/prompts/theme_generation.txt,sha256=QRKW7DtcMSb2olT6j5jmdEPcXPMeZgogM-NYddEIKRk,1871
+themefinder/prompts/theme_mapping.txt,sha256=0z6ddfYxRn1Ew4W3Su-16qTbWn2C6J2LMnK7Biu1tno,1621
+themefinder/prompts/theme_refinement.txt,sha256=JDSYs2sdXqN-Yw9OWjfbmsl9x4Bn1J3oNVSsb_PQ5Ik,2433
+themefinder/prompts/theme_target_alignment.txt,sha256=g7AVZLiP_xIH010X5SIZyG3q7gA6OBAplPv3xvmstOY,855
+themefinder/tasks.py,sha256=FIBC9-0aUDuAuxAFa7zqIgMo5-5WSbkkIZBT0QtF5Co,26946
+themefinder/themefinder_logging.py,sha256=n5SUQovEZLC4skEbxicjz_fOGF9mOk3S-Wpj5uXsaL8,314
+themefinder-0.7.4.dist-info/METADATA,sha256=OVi-63REBmQ7-ptHAKe_kxB_K2oVSiAYQPflhKJADSU,6748
+themefinder-0.7.4.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+themefinder-0.7.4.dist-info/licenses/LICENCE,sha256=C9ULIN0ctF60ZxUWH_hw1H434bDLg49Z-Qzn6BUHgqs,1060
+themefinder-0.7.4.dist-info/RECORD,,

themefinder-0.7.4.dist-info/WHEEL

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

themefinder-0.7.4.dist-info/licenses/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 i.AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.