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

{cat_llm-0.0.33.dist-info → cat_llm-0.0.35.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cat-llm
-Version: 0.0.33
+Version: 0.0.35
 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
@@ -39,6 +39,12 @@ Description-Content-Type: text/markdown
 - [Configuration](#configuration)
 - [Supported Models](#supported-models)
 - [API Reference](#api-reference)
+  - [explore_corpus()](#explore_corpus)
+  - [explore_common_categories()](#explore_common_categories)
+  - [multi_class()](#multi_class)
+  - [image_score()](#image_score)
+  - [image_features()](#image_features)
+  - [cerad_drawn_score()](#cerad_drawn_score)
 - [Academic Research](#academic-research)
 - [License](#license)
 
@@ -180,7 +186,7 @@ print(categories)
 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].
+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.
 
 **Parameters:**
 - `survey_question` (str): The survey question being analyzed
@@ -221,10 +227,173 @@ move_reasons = cat.multi_class(
     api_key="OPENAI_API_KEY")
 ```
 
+### `image_multi_class()`
+
+Performs multi-label image classification into user-defined categories, returning structured results with optional CSV export.
+
+**Methodology:**
+Processes each image 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.
+
+**Parameters:**
+- `image_description` (str): A description of what the model should expect to see
+- `image_input` (list): List of file paths or a folder to pull file paths from
+- `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 = ["has a cat somewhere in it",
+                   "looks cartoonish",
+                   "Adrian Brody is in it"]
+
+description = "Should be an image of a child's drawing"                   
+
+image_categories = cat.image_multi_class(
+    image_description=description, 
+    image_input= ['desktop/image1.jpg','desktop/image2.jpg', desktop/image3.jpg'], 
+    user_model="gpt-4o",
+    creativity=0,
+    categories=user_categories,
+    safety =TRUE,
+    api_key="OPENAI_API_KEY")
+```
+
+### `image_score()`
+
+Performs quality scoring of images against a reference description, returning structured results with optional CSV export.
+
+**Methodology:**
+Processes each image individually, assigning a quality score on a 5-point scale based on similarity to the expected description:
+
+- **1**: No meaningful similarity (fundamentally different)
+- **2**: Barely recognizable similarity (25% match)  
+- **3**: Partial match (50% key features)
+- **4**: Strong alignment (75% features)
+- **5**: Near-perfect match (90%+ similarity)
+
+Supports flexible output formatting and optional saving of results to CSV for easy integration with data analysis workflows[5].
+
+**Parameters:**
+- `reference_image_description` (str): A description of what the model should expect to see
+- `image_input` (list): List of image file paths or folder path containing images
+- `reference_image` (str): A file path to the reference image
+- `api_key` (str): API key for the LLM service
+- `user_model` (str, default="gpt-4o"): Specific vision model to use
+- `creativity` (float, default=0): Temperature/randomness setting (0.0-1.0)
+- `safety` (bool, default=False): Enable safety checks and save results at each API call step
+- `filename` (str, default="image_scores.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 image paths, quality scores, and analysis details
+
+**Example:**
+
+```
+import catllm as cat          
+
+image_scores = cat.image_score(
+    reference_image_description='Adrien Brody sitting in a lawn chair, 
+    image_input= ['desktop/image1.jpg','desktop/image2.jpg', desktop/image3.jpg'], 
+    user_model="gpt-4o",
+    creativity=0,
+    safety =TRUE,
+    api_key="OPENAI_API_KEY")
+```
+
+### `image_features()`
+
+Extracts specific features and attributes from images, returning exact answers to user-defined questions (e.g., counts, colors, presence of objects).
+
+**Methodology:**
+Processes each image individually using vision models to extract precise information about specified features. Unlike scoring and multi-class functions, this returns factual data such as object counts, color identification, or presence/absence of specific elements. Supports flexible output formatting and optional CSV export for quantitative analysis workflows.
+
+**Parameters:**
+- `image_description` (str): A description of what the model should expect to see
+- `image_input` (list): List of image file paths or folder path containing images
+- `features_to_extract` (list): List of specific features to extract (e.g., ["number of people", "primary color", "contains text"])
+- `api_key` (str): API key for the LLM service
+- `user_model` (str, default="gpt-4o"): Specific vision model to use
+- `creativity` (float, default=0): Temperature/randomness setting (0.0-1.0)
+- `to_csv` (bool, default=False): Whether to save the output to a CSV file
+- `safety` (bool, default=False): Enable safety checks and save results 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 image paths and extracted feature values for each specified attribute[1][4]
+
+**Example:**
+
+```
+import catllm as cat          
+
+image_scores = cat.image_features(
+    image_description='An AI generated image of Spongebob dancing with Patrick', 
+    features_to_extract=['Spongebob is yellow','Both are smiling','Patrick is chunky']
+    image_input= ['desktop/image1.jpg','desktop/image2.jpg', desktop/image3.jpg'], 
+    model_source= 'OpenAI',
+    user_model="gpt-4o",
+    creativity=0,
+    safety =TRUE,
+    api_key="OPENAI_API_KEY")
+```
+
+### `cerad_drawn_score()`
+
+Automatically scores drawings of circles, diamonds, overlapping rectangles, and cubes according to the official Consortium to Establish a Registry for Alzheimer's Disease (CERAD) scoring system, returning structured results with optional CSV export. Works even with images that contain other drawings or writing.
+
+**Methodology:**
+Processes each image individually, evaluating the drawn shapes based on CERAD criteria. Supports optional inclusion of reference shapes within images and can provide reference examples if requested. The function outputs standardized scores facilitating reproducible analysis and integrates optional safety checks and CSV export for research workflows.
+
+**Parameters:**
+- `shape` (str): The type of shape to score (e.g., "circle", "diamond", "overlapping rectangles", "cube")
+- `image_input` (list): List of image file paths or folder path containing images
+- `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)
+- `reference_in_image` (bool, default=False): Whether a reference shape is present in the image for comparison
+- `provide_reference` (bool, default=False): Whether to provide a reference example image or description
+- `safety` (bool, default=False): Enable safety checks and save results at each API call step
+- `filename` (str, default="categorized_data.csv"): Filename for CSV output
+- `model_source` (str, default="OpenAI"): Model provider ("OpenAI", "Anthropic", "Perplexity", "Mistral")
+
+**Returns:**
+- `pandas.DataFrame`: DataFrame with image paths, CERAD scores, and analysis details
+
+**Example:**
+
+```
+import catllm as cat  
+
+diamond_scores = cat.cerad_score(
+    shape="diamond",
+    image_input=df['diamond_pic_path'],
+    api_key=open_ai_key,
+    safety=True,
+    filename="diamond_gpt_score.csv",
+)
+```
+
+
 ## 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` is distributed under the terms of the [GNU](https://www.gnu.org/licenses/gpl-3.0.en.html) license.

cat_llm-0.0.35.dist-info/RECORD

@@ -0,0 +1,9 @@
+catllm/CERAD_functions.py,sha256=lAsp4LIQljLvRMSHsQ370xy64SjxuqpXhe67TKUNbp0,19599
+catllm/__about__.py,sha256=lb4phssjPwS1P2N0rFiuJsycy3UuRJwVqs1hs3N247o,404
+catllm/__init__.py,sha256=BpAG8nPhM3ZQRd0WqkubI_36-VCOs4eCYtGVgzz48Bs,337
+catllm/image_functions.py,sha256=7nw0HDvacYUVo_VLcy-6Pi8QcmDbPtKVKPJITAK19RQ,31311
+catllm/text_functions.py,sha256=K6oetWYk25PwsllWSZP4cFrz7kyxJg0plPRvpmQkCsU,16846
+cat_llm-0.0.35.dist-info/METADATA,sha256=23wj7L2KrPkH6QKUEr22TMlY8mBosmGZVwDIbiDJ9Hs,17232
+cat_llm-0.0.35.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cat_llm-0.0.35.dist-info/licenses/LICENSE,sha256=YYp5RSBpti1KKIJO0aV0GTRgQNLIsB7TEYivC3QkCOo,788
+cat_llm-0.0.35.dist-info/RECORD,,

cat_llm-0.0.35.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+GNU License
+
+CatLLM is a framework for categorizing text and images in a structured output.
+    Copyright (C) 2025  Christopher Soria
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.

catllm/CERAD_functions.py

@@ -41,9 +41,10 @@ def cerad_drawn_score(
     import glob
     import base64
     from pathlib import Path
+    import pkg_resources
 
     shape = shape.lower()
-
+    shape = "rectangles" if shape == "overlapping rectangles" else shape
     if shape == "circle":
         categories = ["The image contains a drawing that clearly represents a circle",
                     "The image does NOT contain any drawing that resembles a circle",
@@ -107,6 +108,16 @@ def cerad_drawn_score(
     cat_num = len(categories)
     category_dict = {str(i+1): "0" for i in range(cat_num)}
     example_JSON = json.dumps(category_dict, indent=4)
+    #pulling in the reference image if provided
+    if provide_reference:
+        reference_image = pkg_resources.resource_filename(
+            'catllm', 
+            f'images/{shape}.png'  # e.g., "circle.png"
+        )
+        ext = Path(reference_image_path).suffix[1:]
+        with open(reference_image_path, 'rb') as f:
+            encoded_ref = base64.b64encode(f.read()).decode('utf-8')
+        encoded_ref_image = f"data:image/{ext};base64,{encoded_ref}"
     
     link1 = []
     extracted_jsons = []
@@ -146,13 +157,21 @@ def cerad_drawn_score(
                         f"No additional keys, comments, or text.\n\n"
                         f"Example:\n"
                         f"{example_JSON}"
-                        ),
-                        },
-                        {
-                            "type": "image_url",
-                            "image_url": {"url": encoded_image, "detail": "high"},
-                            }
+                        )
+                }
             ]
+                        # Conditionally add reference image
+            if provide_reference:
+                prompt.append({
+                    "type": "image_url", 
+                    "image_url": {"url": reference_image, "detail": "high"}
+                })
+                                
+            prompt.append({
+                "type": "image_url",
+                "image_url": {"url": encoded_image, "detail": "high"}
+            })
+ 
         elif model_source == "Anthropic":
             prompt = [
                 {
@@ -347,7 +366,7 @@ def cerad_drawn_score(
         categorized_data['score'] = categorized_data['diamond_4_sides'] + categorized_data['diamond_equal_sides'] + categorized_data['similar']
 
         categorized_data.loc[categorized_data['none'] == 1, 'score'] = 0
-        categorized_data.loc[(categorized_data['diamond_square'] == 1) & (categorized_data['score'] == 0), 'score'] = 2
+        #categorized_data.loc[(categorized_data['diamond_square'] == 1) & (categorized_data['score'] == 0), 'score'] = 2
 
     elif shape == "rectangles" or shape == "overlapping rectangles":
 

catllm/__about__.py

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

catllm/image_functions.py

@@ -4,7 +4,6 @@ def image_multi_class(
     image_input,
     categories,
     api_key,
-    columns="numbered",
     user_model="gpt-4o",
     creativity=0,
     to_csv=False,
@@ -508,7 +507,6 @@ def image_features(
     image_input,
     features_to_extract,
     api_key,
-    columns="numbered",
     user_model="gpt-4o-2024-11-20",
     creativity=0,
     to_csv=False,

cat_llm-0.0.33.dist-info/RECORD

@@ -1,9 +0,0 @@
-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,,

cat_llm-0.0.33.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Christopher Soria 
-
-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.