themefinder 0.0.3__py3-none-any.whl

themefinder-0.0.3.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.3
+Name: themefinder
+Version: 0.0.3
+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
+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 (==0.1.17)
+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
+
+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.0.3.dist-info/RECORD

@@ -0,0 +1,17 @@
+themefinder/__init__.py,sha256=yfIyHWPMM59u23m79igHSllT-w3r4l_euLCDZygo22Q,431
+themefinder/core.py,sha256=J4BJZO8BNN9xbX3LsKah4ZOGkW6YJcg_iYB9HCH7UR0,22768
+themefinder/llm_batch_processor.py,sha256=zdrQH1bvMR9FHWDaDp1tvdiADTHTaNDg_Z-3QQ0771k,17641
+themefinder/models.py,sha256=RN_7WzucXgKWSVXEoizijTgAM63rMVvXW6vdGD3o6Z8,12332
+themefinder/prompts/consultation_system_prompt.txt,sha256=_A07oY_an4hnRx-9pQ0y-TLXJz0dd8vDI-MZne7Mdb4,89
+themefinder/prompts/detail_detection.txt,sha256=6Vr_oN7rF5BCFipnCIHTSF8MmjerGyCixRWRT3vni1U,941
+themefinder/prompts/sentiment_analysis.txt,sha256=vYCDhtEsG5I9xixwVhZbvKPJGU1Gqpw4-xAqGz72xhU,1671
+themefinder/prompts/theme_condensation.txt,sha256=pHWuCtfU58gdtP2BfGZWOTvcb0MnTpb9OhOCGtkJv8U,1672
+themefinder/prompts/theme_generation.txt,sha256=QRKW7DtcMSb2olT6j5jmdEPcXPMeZgogM-NYddEIKRk,1871
+themefinder/prompts/theme_mapping.txt,sha256=HtGuStm-622TIEaqdb9LTaBs9xE-n9lvmcGQTG2_JOQ,2042
+themefinder/prompts/theme_refinement.txt,sha256=evWMCIEdeZCJ8zn4SBNgP6bmfAb0vzKiR5C5wfAjkUk,2649
+themefinder/prompts/theme_target_alignment.txt,sha256=g7AVZLiP_xIH010X5SIZyG3q7gA6OBAplPv3xvmstOY,855
+themefinder/themefinder_logging.py,sha256=n5SUQovEZLC4skEbxicjz_fOGF9mOk3S-Wpj5uXsaL8,314
+themefinder-0.0.3.dist-info/LICENCE,sha256=C9ULIN0ctF60ZxUWH_hw1H434bDLg49Z-Qzn6BUHgqs,1060
+themefinder-0.0.3.dist-info/METADATA,sha256=Ix9gzGyZ-j7ji9tIzpFm0KNLb12UfK94KjxL5id0OsQ,6850
+themefinder-0.0.3.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+themefinder-0.0.3.dist-info/RECORD,,

themefinder-0.0.3.dist-info/WHEEL

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