cat-llm 0.0.31__py3-none-any.whl → 0.0.33__py3-none-any.whl

cat_llm-0.0.33.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: cat-llm
+Version: 0.0.33
+Summary: A tool for categorizing text data and images using LLMs and vision models
+Project-URL: Documentation, https://github.com/chrissoria/cat-llm#readme
+Project-URL: Issues, https://github.com/chrissoria/cat-llm/issues
+Project-URL: Source, https://github.com/chrissoria/cat-llm
+Author-email: Christopher Soria <chrissoria@berkeley.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: categorizer,image classification,llm,structured output,survey data,text classification
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+Requires-Dist: pandas
+Requires-Dist: tqdm
+Description-Content-Type: text/markdown
+
+![catllm Logo](https://github.com/chrissoria/cat-llm/blob/main/images/logo.png?raw=True)
+
+# catllm
+
+[![PyPI - Version](https://img.shields.io/pypi/v/cat-llm.svg)](https://pypi.org/project/cat-llm)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cat-llm.svg)](https://pypi.org/project/cat-llm)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Supported Models](#supported-models)
+- [API Reference](#api-reference)
+- [Academic Research](#academic-research)
+- [License](#license)
+
+## Installation
+
+```console
+pip install cat-llm
+```
+
+## Quick Start
+
+The `explore_corpus` function extracts a list of all categories present in the corpus as identified by the model.
+```
+import catllm as cat
+import os
+
+categories = cat.explore_corpus(
+survey_question="What motivates you most at work?",
+survey_input=["flexible schedule", "good pay", "interesting projects"],
+api_key="OPENAI_API_KEY",
+cat_num=5,
+divisions=10
+)
+print(categories)
+```
+
+## Configuration
+
+### Get Your OpenAI API Key
+
+1. **Create an OpenAI Developer Account**:
+   - Go to [platform.openai.com](https://platform.openai.com) (separate from regular ChatGPT)
+   - Sign up with email, Google, Microsoft, or Apple
+
+2. **Generate an API Key**:
+   - Log into your account and click your name in the top right corner
+   - Click "View API keys" or navigate to the "API keys" section
+   - Click "Create new secret key"
+   - Give your key a descriptive name
+   - Set permissions (choose "All" for full access)
+
+3. **Add Payment Details**:
+   - Add a payment method to your OpenAI account
+   - Purchase credits (start with $5 - it lasts a long time for most research use)
+   - **Important**: Your API key won't work without credits
+
+4. **Save Your Key Securely**:
+   - Copy the key immediately (you won't be able to see it again)
+   - Store it safely and never share it publicly
+
+5. Copy and paste your key into catllm in the api_key parameter
+
+## Supported Models
+
+- **OpenAI**: GPT-4o, GPT-4, GPT-3.5-turbo, etc.
+- **Anthropic**: Claude Sonnet 3.7, Claude Haiku, etc.
+- **Perplexity**: Sonnar Large, Sonnar Small, etc.
+- **Mistral**: Mistral Large, Mistral Small, etc.
+
+## API Reference
+
+### `explore_corpus()`
+
+Extracts categories from a corpus of text responses and returns frequency counts.
+
+**Methodology:**
+The function divides the corpus into random chunks to address the probabilistic nature of LLM outputs. By processing multiple chunks and averaging results across many API calls rather than relying on a single call, this approach significantly improves reproducibility and provides more stable categorical frequency estimates.
+
+**Parameters:**
+- `survey_question` (str): The survey question being analyzed
+- `survey_input` (list): List of text responses to categorize
+- `api_key` (str): API key for the LLM service
+- `cat_num` (int, default=10): Number of categories to extract in each iteration
+- `divisions` (int, default=5): Number of chunks to divide the data into (larger corpora might require larger divisions)
+- `specificity` (str, default="broad"): Category precision level (e.g., "broad", "narrow")
+- `model_source` (str, default="OpenAI"): Model provider ("OpenAI", "Anthropic", "Perplexity", "Mistral")
+- `user_model` (str, default="got-4o"): Specific model (e.g., "gpt-4o", "claude-opus-4-20250514")
+- `creativity` (float, default=0): Temperature/randomness setting (0.0-1.0)
+- `filename` (str, optional): Output file path for saving results
+
+**Returns:**
+- `pandas.DataFrame`: Two-column dataset with category names and frequencies
+
+**Example:***
+
+```
+import catllm as cat
+
+categories = cat.explore_corpus(
+survey_question="What motivates you most at work?",
+survey_input=["flexible schedule", "good pay", "interesting projects"],
+api_key="OPENAI_API_KEY",
+cat_num=5,
+divisions=10
+)
+```
+
+### `explore_common_categories()`
+
+Identifies the most frequently occurring categories across a text corpus and returns the top N categories by frequency count.
+
+**Methodology:**
+Divides the corpus into random chunks and averages results across multiple API calls to improve reproducibility and provide stable frequency estimates for the most prevalent categories, addressing the probabilistic nature of LLM outputs.
+
+**Parameters:**
+- `survey_question` (str): Survey question being analyzed
+- `survey_input` (list): Text responses to categorize
+- `api_key` (str): API key for the LLM service
+- `top_n` (int, default=10): Number of top categories to return by frequency
+- `cat_num` (int, default=10): Number of categories to extract per iteration
+- `divisions` (int, default=5): Number of data chunks (increase for larger corpora)
+- `user_model` (str, default="gpt-4o"): Specific model to use
+- `creativity` (float, default=0): Temperature/randomness setting (0.0-1.0)
+- `specificity` (str, default="broad"): Category precision level ("broad", "narrow")
+- `research_question` (str, optional): Contextual research question to guide categorization
+- `filename` (str, optional): File path to save output dataset
+- `model_source` (str, default="OpenAI"): Model provider ("OpenAI", "Anthropic", "Perplexity", "Mistral")
+
+**Returns:**
+- `pandas.DataFrame`: Dataset with category names and frequencies, limited to top N most common categories
+
+**Example:**
+
+```
+import catllm as cat
+
+top_10_categories = cat.explore_common_categories(
+survey_question="What motivates you most at work?",
+survey_input=["flexible schedule", "good pay", "interesting projects"],
+api_key="OPENAI_API_KEY",
+top_n=10,
+cat_num=5,
+divisions=10
+)
+print(categories)
+```
+### `multi_class()`
+
+Performs multi-label classification of text responses into user-defined categories, returning structured results with optional CSV export.
+
+**Methodology:**
+Processes each text response individually, assigning one or more categories from the provided list. Supports flexible output formatting and optional saving of results to CSV for easy integration with data analysis workflows[2].
+
+**Parameters:**
+- `survey_question` (str): The survey question being analyzed
+- `survey_input` (list): List of text responses to classify
+- `categories` (list): List of predefined categories for classification
+- `api_key` (str): API key for the LLM service
+- `user_model` (str, default="gpt-4o"): Specific model to use
+- `creativity` (float, default=0): Temperature/randomness setting (0.0-1.0)
+- `safety` (bool, default=False): Enable safety checks on responses and saves to CSV at each API call step
+- `filename` (str, default="categorized_data.csv"): Filename for CSV output
+- `save_directory` (str, optional): Directory path to save the CSV file
+- `model_source` (str, default="OpenAI"): Model provider ("OpenAI", "Anthropic", "Perplexity", "Mistral")
+
+**Returns:**
+- `pandas.DataFrame`: DataFrame with classification results, columns formatted as specified
+
+**Example:**
+
+```
+import catllm as cat
+
+user_categories = ["to start living with or to stay with partner/spouse",
+                   "relationship change (divorce, breakup, etc)",
+                   "the person had a job or school or career change, including transferred and retired",
+                   "the person's partner's job or school or career change, including transferred and retired",
+                   "financial reasons (rent is too expensive, pay raise, etc)",
+                   "related specifically features of the home, such as a bigger or smaller yard"]
+
+question = "Why did you move?"                   
+
+move_reasons = cat.multi_class(
+    survey_question=question, 
+    survey_input= df[column1], 
+    user_model="gpt-4o",
+    creativity=0,
+    categories=user_categories,
+    safety =TRUE,
+    api_key="OPENAI_API_KEY")
+```
+
+## Academic Research
+
+This package implements methodology from research on LLM performance in social science applications, including the UC Berkeley Social Networks Study. The package addresses reproducibility challenges in LLM-assisted research by providing standardized interfaces and consistent output formatting.
+
+## License
+
+`cat-llm` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

cat_llm-0.0.33.dist-info/RECORD

@@ -0,0 +1,9 @@
+catllm/CERAD_functions.py,sha256=fiSiBnCcFgNp5XmGhZULnToEoMyP5z6JMcH-aWC8q5o,18787
+catllm/__about__.py,sha256=QD4n_jc9pZ_DH4rnRx892q9STG4YDuOKqS8li05uQnw,404
+catllm/__init__.py,sha256=BpAG8nPhM3ZQRd0WqkubI_36-VCOs4eCYtGVgzz48Bs,337
+catllm/image_functions.py,sha256=9e4V1IEMZUFrH00yEjyowwTUKeXWGsln0U1iQ-DELTY,31359
+catllm/text_functions.py,sha256=K6oetWYk25PwsllWSZP4cFrz7kyxJg0plPRvpmQkCsU,16846
+cat_llm-0.0.33.dist-info/METADATA,sha256=XiSskbffmKcIABIrm7vnJqJmDgZGOh6Qi_JABdU5Uls,9260
+cat_llm-0.0.33.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cat_llm-0.0.33.dist-info/licenses/LICENSE,sha256=wJLsvOr6lrFUDcoPXExa01HOKFWrS3JC9f0RudRw8uw,1075
+cat_llm-0.0.33.dist-info/RECORD,,

catllm/__about__.py

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: 2025-present Christopher Soria <chrissoria@berkeley.edu>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "0.0.31"
+__version__ = "0.0.33"
 __author__ = "Chris Soria"
 __email__ = "chrissoria@berkeley.edu"
 __title__ = "cat-llm"

catllm/__init__.py

@@ -11,6 +11,6 @@ from .__about__ import (
     __license__,
 )
 
-from .cat_llm import *
+from .text_functions import *
 from .CERAD_functions import * 
 from .image_functions import * 

catllm/image_functions.py

@@ -72,7 +72,7 @@ def image_multi_class(
     
     # Handle extension safely
         ext = Path(img_path).suffix.lstrip(".").lower()
-        if model_source == "OpenAI":
+        if model_source == "OpenAI" or model_source == "Mistral":
             encoded_image = f"data:image/{ext};base64,{encoded}"
             prompt = [
                 {
@@ -309,7 +309,7 @@ def image_score(
         ext = Path(img_path).suffix.lstrip(".").lower()
         encoded_image = f"data:image/{ext};base64,{encoded}"
 
-        if model_source == "OpenAI":
+        if model_source == "OpenAI" or model_source == "Mistral":
             prompt = [
                 {
                     "type": "text",
@@ -575,7 +575,7 @@ def image_features(
         ext = Path(img_path).suffix.lstrip(".").lower()
         encoded_image = f"data:image/{ext};base64,{encoded}"
 
-        if model_source == "OpenAI":
+        if model_source == "OpenAI" or model_source == "Mistral":
             prompt = [
                 {
                     "type": "text",

catllm/{cat_llm.py → text_functions.py}

@@ -106,7 +106,7 @@ def explore_common_categories(
     top_n=10,
     cat_num=10,
     divisions=5,
-    user_model="gpt-4o-2024-11-20",
+    user_model="gpt-4o",
     creativity=0,
     specificity="broad",
     research_question=None,
@@ -224,10 +224,8 @@ def multi_class(
     survey_input,
     categories,
     api_key,
-    columns="numbered",
-    user_model="gpt-4o-2024-11-20",
+    user_model="gpt-4o",
     creativity=0,
-    to_csv=False,
     safety=False,
     filename="categorized_data.csv",
     save_directory=None,

cat_llm-0.0.31.dist-info/METADATA

@@ -1,48 +0,0 @@
-Metadata-Version: 2.4
-Name: cat-llm
-Version: 0.0.31
-Summary: A tool for categorizing text data and images using LLMs and vision models
-Project-URL: Documentation, https://github.com/chrissoria/cat-llm#readme
-Project-URL: Issues, https://github.com/chrissoria/cat-llm/issues
-Project-URL: Source, https://github.com/chrissoria/cat-llm
-Author-email: Christopher Soria <chrissoria@berkeley.edu>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: categorizer,image classification,llm,structured output,survey data,text classification
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: >=3.8
-Requires-Dist: pandas
-Requires-Dist: tqdm
-Description-Content-Type: text/markdown
-
-![catllm Logo](https://github.com/chrissoria/cat-llm/blob/main/images/logo.png?raw=True)
-
-# catllm
-
-[![PyPI - Version](https://img.shields.io/pypi/v/cat-llm.svg)](https://pypi.org/project/cat-llm)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cat-llm.svg)](https://pypi.org/project/cat-llm)
-
------
-
-## Table of Contents
-
-- [Installation](#installation)
-- [License](#license)
-
-## Installation
-
-```console
-pip install cat-llm
-```
-
-## License
-
-`cat-llm` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

cat_llm-0.0.31.dist-info/RECORD

@@ -1,9 +0,0 @@
-catllm/CERAD_functions.py,sha256=fiSiBnCcFgNp5XmGhZULnToEoMyP5z6JMcH-aWC8q5o,18787
-catllm/__about__.py,sha256=9jcX8w9s2lkH7rxfvscK-WEBKVFhqbPqque6B-Xa2QA,404
-catllm/__init__.py,sha256=kLk180aJna1s-wU6CLr4_hKkbjoeET-11jGmC1pdhQw,330
-catllm/cat_llm.py,sha256=TNsjYKpr8ZH9jeAYN-4DcFcrnR8x2eRl99oXzpdhE0Q,16910
-catllm/image_functions.py,sha256=JLlv5qQhAQzgsRIY18rUPtM1P7x1Fw2UlWlI1dpv3dA,31272
-cat_llm-0.0.31.dist-info/METADATA,sha256=5Gu7C5gBkMWYgVy8M4OSK6B8Zi2nT6HHiybtv4O_KqM,1679
-cat_llm-0.0.31.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cat_llm-0.0.31.dist-info/licenses/LICENSE,sha256=wJLsvOr6lrFUDcoPXExa01HOKFWrS3JC9f0RudRw8uw,1075
-cat_llm-0.0.31.dist-info/RECORD,,