cat-llm 0.0.19__py3-none-any.whl → 0.0.21__py3-none-any.whl

{cat_llm-0.0.19.dist-info → cat_llm-0.0.21.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cat-llm
-Version: 0.0.19
+Version: 0.0.21
 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

cat_llm-0.0.21.dist-info/RECORD

@@ -0,0 +1,8 @@
+catllm/CERAD_functions.py,sha256=Qb6-X4147pLkiGYnhCiTZbUllnI_Phc78NeEGm9IYic,14560
+catllm/__about__.py,sha256=TunDrsvgMTHUI-XmOUy6ZvCm0jyzgtPLSTQ4FQ-i1EE,404
+catllm/__init__.py,sha256=bgH_2K70m3WP9B8GZNciAr7ld7bSNwgpzhYgkoAC8Bo,299
+catllm/cat_llm.py,sha256=z3ohaq2sXrcI6ygvQTKNNlAN5ptmNmwCimkM625j7LQ,58205
+cat_llm-0.0.21.dist-info/METADATA,sha256=1AzIw7qX1yrWpsozHM-XfTvzk2R8nSY35yrogvt93uY,1679
+cat_llm-0.0.21.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cat_llm-0.0.21.dist-info/licenses/LICENSE,sha256=wJLsvOr6lrFUDcoPXExa01HOKFWrS3JC9f0RudRw8uw,1075
+cat_llm-0.0.21.dist-info/RECORD,,

catllm/CERAD_functions.py

@@ -0,0 +1,330 @@
+# image multi-class (binary) function
+def cerad_score(
+    shape, 
+    image_input,
+    api_key,
+    user_model="gpt-4o-2024-11-20",
+    creativity=0,
+    safety=False,
+    filename="categorized_data.csv",
+    model_source="OpenAI"
+):
+    import os
+    import json
+    import pandas as pd
+    import regex
+    from tqdm import tqdm
+    import glob
+    import base64
+    from pathlib import Path
+
+    shape = shape.lower()
+
+    if shape == "circle":
+        categories = ["It has a drawing of a circle",
+                    "The drawing does not resemble a circle",
+                    "The drawing resembles a circle",
+                    "The circle is closed",
+                    "The circle is almost closed",
+                    "The circle is circular",
+                    "The circle is almost circular",
+                    "None of the above descriptions apply"]
+    elif shape == "diamond":
+        categories = ["It has a drawing of a diamond",
+                    "It has a drawing of a square",
+                    "A drawn shape DOES NOT resemble a diamond",
+                    "A drawn shape resembles a diamond",
+                    "The drawn shape has 4 sides",
+                    "The drawn shape sides are about equal",
+                    "If a diamond is drawn it's more elaborate than a simple diamond (such as overlapping diamonds or a diamond with an extras lines inside)",
+                    "None of the above descriptions apply"]
+    elif shape == "rectangles" or shape == "overlapping rectangles":
+        categories = ["It has a drawing of overlapping rectangles",
+                    "A drawn shape DOES NOT resemble a overlapping rectangles",
+                    "A drawn shape resembles a overlapping rectangles",
+                    "Rectangle 1 has 4 sides",
+                    "Rectangle 2 has 4 sides",
+                    "The rectangles are overlapping",
+                    "The rectangles overlap contains a longer vertical rectangle with top and bottom portruding",
+                    "None of the above descriptions apply"]
+    elif shape == "cube":
+        categories = ["The image contains a drawing that clearly represents a cube (3D box shape)",
+                    "The image does NOT contain any drawing that resembles a cube or 3D box",
+                    "The image contains a WELL-DRAWN recognizable cube with proper 3D perspective",
+                    "If a cube is present: the front face appears as a square or diamond shape",
+                    "If a cube is present: internal/hidden edges are visible (showing 3D depth, not just an outline)",
+                    "If a cube is present: the front and back faces appear parallel to each other",
+                    "The image contains only a 2D square (flat shape, no 3D appearance)",
+                    "None of the above descriptions apply"]
+    else:
+        raise ValueError("Invalid shape! Choose from 'circle', 'diamond', 'rectangles', or 'cube'.")
+
+    image_extensions = [
+    '*.png', '*.jpg', '*.jpeg',
+    '*.gif', '*.webp', '*.svg', '*.svgz', '*.avif', '*.apng',
+    '*.tif', '*.tiff', '*.bmp',
+    '*.heif', '*.heic', '*.ico',
+    '*.psd'
+    ]
+
+    if not isinstance(image_input, list):
+        # If image_input is a filepath (string)
+        image_files = []
+        for ext in image_extensions:
+            image_files.extend(glob.glob(os.path.join(image_input, ext)))
+    
+        print(f"Found {len(image_files)} images.")
+    else:
+        # If image_files is already a list
+        image_files = image_input
+        print(f"Provided a list of {len(image_input)} images.")
+    
+    categories_str = "\n".join(f"{i + 1}. {cat}" for i, cat in enumerate(categories))
+    cat_num = len(categories)
+    category_dict = {str(i+1): "0" for i in range(cat_num)}
+    example_JSON = json.dumps(category_dict, indent=4)
+    
+    link1 = []
+    extracted_jsons = []
+
+    for i, img_path in enumerate(tqdm(image_files, desc="Categorising images"), start=0):
+    # Check validity first
+        if img_path is None or not os.path.exists(img_path):
+            link1.append("Skipped NaN input or invalid path")
+            extracted_jsons.append("""{"no_valid_image": 1}""")
+            continue  # Skip the rest of the loop iteration
+        
+    # Only open the file if path is valid
+        with open(img_path, "rb") as f:
+            encoded = base64.b64encode(f.read()).decode("utf-8")
+    
+    # Handle extension safely
+        ext = Path(img_path).suffix.lstrip(".").lower()
+        encoded_image = f"data:image/{ext};base64,{encoded}"
+    
+        prompt = [
+            {
+                "type": "text",
+                "text": (
+                    f"You are an image-tagging assistant trained in the CERAD Constructional Praxis test.\n"
+                    f"Task ► Examine the attached image and decide, **for each category below**, "
+                    f"whether it is PRESENT (1) or NOT PRESENT (0).\n\n"
+                    f"Image is expected to show within it a drawing of a {shape}.\n\n"
+                    f"Categories:\n{categories_str}\n\n"
+                    f"Output format ► Respond with **only** a JSON object whose keys are the "
+                    f"quoted category numbers ('1', '2', …) and whose values are 1 or 0. "
+                    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"},
+            },
+        ]
+        if model_source == "OpenAI":
+            from openai import OpenAI
+            client = OpenAI(api_key=api_key)
+            try:
+                response_obj = client.chat.completions.create(
+                    model=user_model,
+                    messages=[{'role': 'user', 'content': prompt}],
+                    temperature=creativity
+                )
+                reply = response_obj.choices[0].message.content
+                link1.append(reply)
+            except Exception as e:
+                print(f"An error occurred: {e}")
+                link1.append(f"Error processing input: {e}")
+
+        elif model_source == "Perplexity":
+            from openai import OpenAI
+            client = OpenAI(api_key=api_key, base_url="https://api.perplexity.ai")
+            try:
+                response_obj = client.chat.completions.create(
+                    model=user_model,
+                    messages=[{'role': 'user', 'content': prompt}],
+                    temperature=creativity
+                )
+                reply = response_obj.choices[0].message.content
+                link1.append(reply)
+            except Exception as e:
+                print(f"An error occurred: {e}")
+                link1.append(f"Error processing input: {e}")
+        elif model_source == "Anthropic":
+            import anthropic
+            client = anthropic.Anthropic(api_key=api_key)
+            try:
+                message = client.messages.create(
+                    model=user_model,
+                    max_tokens=1024,
+                    temperature=creativity,
+                    messages=[{"role": "user", "content": prompt}]
+                )
+                reply = message.content[0].text  # Anthropic returns content as list
+                link1.append(reply)
+            except Exception as e:
+                print(f"An error occurred: {e}")
+                link1.append(f"Error processing input: {e}")
+        elif model_source == "Mistral":
+            from mistralai import Mistral
+            client = Mistral(api_key=api_key)
+            try:
+                response = client.chat.complete(
+                    model=user_model,
+                    messages=[
+                    {'role': 'user', 'content': prompt}
+                ],
+                temperature=creativity
+                )
+                reply = response.choices[0].message.content
+                link1.append(reply)
+            except Exception as e:
+                print(f"An error occurred: {e}")
+                link1.append(f"Error processing input: {e}")
+        else:
+            raise ValueError("Unknown source! Choose from OpenAI, Anthropic, Perplexity, or Mistral")
+            # in situation that no JSON is found
+        if reply is not None:
+            extracted_json = regex.findall(r'\{(?:[^{}]|(?R))*\}', reply, regex.DOTALL)
+            if extracted_json:
+                cleaned_json = extracted_json[0].replace('[', '').replace(']', '').replace('\n', '').replace(" ", '').replace("  ", '')
+                extracted_jsons.append(cleaned_json)
+                #print(cleaned_json)
+            else:
+                error_message = """{"1":"e"}"""
+                extracted_jsons.append(error_message)
+                print(error_message)
+        else:
+            error_message = """{"1":"e"}"""
+            extracted_jsons.append(error_message)
+            #print(error_message)
+
+        # --- Safety Save ---
+        if safety:
+            #print(f"Saving CSV to: {save_directory}")
+            # Save progress so far
+            temp_df = pd.DataFrame({
+                'image_input': image_files[:i+1],
+                'link1': link1,
+                'json': extracted_jsons
+            })
+            # Normalize processed jsons so far
+            normalized_data_list = []
+            for json_str in extracted_jsons:
+                try:
+                    parsed_obj = json.loads(json_str)
+                    normalized_data_list.append(pd.json_normalize(parsed_obj))
+                except json.JSONDecodeError:
+                    normalized_data_list.append(pd.DataFrame({"1": ["e"]}))
+            normalized_data = pd.concat(normalized_data_list, ignore_index=True)
+            temp_df = pd.concat([temp_df, normalized_data], axis=1)
+            # Save to CSV
+            if filename is None:
+                filepath = os.path.join(os.getcwd(), 'catllm_data.csv')
+            else:
+                filepath = filename
+            temp_df.to_csv(filepath, index=False)
+
+    # --- Final DataFrame ---
+    normalized_data_list = []
+    for json_str in extracted_jsons:
+        try:
+            parsed_obj = json.loads(json_str)
+            normalized_data_list.append(pd.json_normalize(parsed_obj))
+        except json.JSONDecodeError:
+            normalized_data_list.append(pd.DataFrame({"1": ["e"]}))
+    normalized_data = pd.concat(normalized_data_list, ignore_index=True)
+
+    categorized_data = pd.DataFrame({
+        'image_input': image_files,
+        'link1': pd.Series(link1).reset_index(drop=True),
+        'json': pd.Series(extracted_jsons).reset_index(drop=True)
+    })
+    categorized_data = pd.concat([categorized_data, normalized_data], axis=1)
+    columns_to_convert = ["1", "2", "3", "4", "5", "6", "7"]
+    categorized_data[columns_to_convert] = categorized_data[columns_to_convert].apply(pd.to_numeric, errors='coerce').fillna(0).astype(int)
+
+    if shape == "circle":
+
+        categorized_data = categorized_data.rename(columns={
+            "1": "drawing_present",
+            "2": "not_similar",
+            "3": "similar",
+            "4": "cir_closed",
+            "5": "cir_almost_closed",
+            "6": "cir_round",
+            "7": "cir_almost_round",
+            "8": "none"
+        })
+
+        categorized_data['score'] = categorized_data['cir_almost_closed'] + categorized_data['cir_closed'] + categorized_data['cir_round'] + categorized_data['cir_almost_round']
+        categorized_data.loc[categorized_data['none'] == 1, 'score'] = 0
+        categorized_data.loc[(categorized_data['drawing_present'] == 0) & (categorized_data['score'] == 0), 'score'] = 0
+
+    elif shape == "diamond":
+
+        categorized_data = categorized_data.rename(columns={
+            "1": "drawing_present",
+            "2": "diamond_square",
+            "3": "not_similar",
+            "4": "similar",
+            "5": "diamond_4_sides",
+            "6": "diamond_equal_sides",
+            "7": "complex_diamond",
+            "8": "none"
+        })
+
+        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
+
+    elif shape == "rectangles" or shape == "overlapping rectangles":
+
+        categorized_data = categorized_data.rename(columns={
+            "1":"drawing_present",
+            "2": "not_similar",
+            "3": "similar",
+            "4": "r1_4_sides",
+            "5": "r2_4_sides",
+            "6": "rectangles_overlap",
+            "7": "rectangles_cross",
+            "8": "none"
+        })
+
+        categorized_data['score'] = 0
+        categorized_data.loc[(categorized_data['r1_4_sides'] == 1) & (categorized_data['r2_4_sides'] == 1), 'score'] = 1
+        categorized_data.loc[(categorized_data['rectangles_overlap'] == 1) & (categorized_data['rectangles_cross'] == 1), 'score'] += 1
+        categorized_data.loc[categorized_data['none'] == 1, 'score'] = 0
+
+    elif shape == "cube":
+
+        categorized_data = categorized_data.rename(columns={
+            "1": "drawing_present",
+            "2": "not_similar",
+            "3": "similar", 
+            "4": "cube_front_face",
+            "5": "cube_internal_lines",
+            "6": "cube_opposite_sides",
+            "7": "square_only",
+            "8": "none"
+        })
+
+        categorized_data['score'] = categorized_data['cube_front_face'] + categorized_data['cube_internal_lines'] + categorized_data['cube_opposite_sides'] + categorized_data['similar']
+        categorized_data.loc[categorized_data['similar'] == 1, 'score'] = categorized_data['score'] + 1
+        categorized_data.loc[categorized_data['none'] == 1, 'score'] = 0
+        categorized_data.loc[(categorized_data['drawing_present'] == 0) & (categorized_data['score'] == 0), 'score'] = 0
+        categorized_data.loc[(categorized_data['not_similar'] == 1) & (categorized_data['score'] == 0), 'score'] = 0
+        categorized_data.loc[categorized_data['score'] > 4, 'score'] = 4
+
+    else:
+        raise ValueError("Invalid shape! Choose from 'circle', 'diamond', 'rectangles', or 'cube'.")
+
+    categorized_data.loc[categorized_data['no_valid_image'] == 1, 'score'] = None
+
+    if filename is not None:
+        categorized_data.to_csv(filename, index=False)
+    
+    return categorized_data

catllm/__about__.py

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

catllm/__init__.py

@@ -11,4 +11,5 @@ from .__about__ import (
     __license__,
 )
 
-from .cat_llm import *
+from .cat_llm import *
+#from .CERAD_functions import * 

catllm/cat_llm.py

@@ -1,3 +1,223 @@
+#extract categories from corpus
+def explore_corpus(
+    survey_question, 
+    survey_input,
+    api_key,
+    research_question=None,
+    specificity="broad",
+    cat_num=10,
+    divisions=5,
+    user_model="gpt-4o-2024-11-20",
+    creativity=0,
+    filename="corpus_exploration.csv",
+    model_source="OpenAI"
+):
+    import os
+    import pandas as pd
+    import random
+    from openai import OpenAI
+    from openai import OpenAI, BadRequestError
+    from tqdm import tqdm
+
+    print(f"Exploring class for question: '{survey_question}'.\n          {cat_num * divisions} unique categories to be extracted.")
+    print()
+
+    chunk_size = round(max(1, len(survey_input) / divisions),0)
+    chunk_size = int(chunk_size)
+
+    if chunk_size < (cat_num/2):
+        raise ValueError(f"Cannot extract {cat_num} {specificity} categories from chunks of only {chunk_size} responses. \n" 
+                    f"Choose one solution: \n"
+                    f"(1) Reduce 'divisions' parameter (currently {divisions}) to create larger chunks, or \n"
+                    f"(2) Reduce 'cat_num' parameter (currently {cat_num}) to extract fewer categories per chunk.")
+
+    random_chunks = []
+    for i in range(divisions):
+        chunk = survey_input.sample(n=chunk_size).tolist()
+        random_chunks.append(chunk)
+    
+    responses = []
+    responses_list = []
+    
+    for i in tqdm(range(divisions), desc="Processing chunks"):
+        survey_participant_chunks = '; '.join(random_chunks[i])
+        prompt = f"""Identify {cat_num} {specificity} categories of responses to the question "{survey_question}" in the following list of responses. \
+Responses are each separated by a semicolon. \
+Responses are contained within triple backticks here: ```{survey_participant_chunks}``` \
+Number your categories from 1 through {cat_num} and be concise with the category labels and provide no description of the categories."""
+        
+        if model_source == "OpenAI":
+            client = OpenAI(api_key=api_key)
+            try:
+                response_obj = client.chat.completions.create(
+                    model=user_model,
+                    messages=[
+                        {'role': 'system', 'content': f"""You are a helpful assistant that extracts categories from survey responses. \
+                                                    The specific task is to identify {specificity} categories of responses to a survey question. \
+                         The research question is: {research_question}""" if research_question else "You are a helpful assistant."},
+                        {'role': 'user', 'content': prompt}
+                    ]
+                    temperature=creativity
+                )
+                reply = response_obj.choices[0].message.content
+                responses.append(reply)
+            except BadRequestError as e:
+                if "context_length_exceeded" in str(e) or "maximum context length" in str(e):
+                    error_msg = (f"Token limit exceeded for model {user_model}. "
+                        f"Try increasing the 'iterations' parameter to create smaller chunks.")
+                    raise ValueError(error_msg)
+                else:
+                    print(f"OpenAI API error: {e}")
+            except Exception as e:
+                print(f"An error occurred: {e}")
+        else:
+            raise ValueError(f"Unsupported model_source: {model_source}")
+        
+        # Extract just the text as a list
+        items = []
+        for line in responses[i].split('\n'):
+            if '. ' in line:
+                try:
+                    items.append(line.split('. ', 1)[1])
+                except IndexError:
+                    pass
+
+        responses_list.append(items)
+
+    flat_list = [item.lower() for sublist in responses_list for item in sublist]
+
+    #convert flat_list to a df
+    df = pd.DataFrame(flat_list, columns=['Category'])
+    counts = pd.Series(flat_list).value_counts()  # Use original list before conversion
+    df['counts'] = df['Category'].map(counts)
+    df = df.sort_values(by='counts', ascending=False).reset_index(drop=True)
+    df = df.drop_duplicates(subset='Category', keep='first').reset_index(drop=True)
+
+    if filename is not None:
+        df.to_csv(filename, index=False)
+    
+    return df
+
+#extract top categories from corpus
+def explore_common_categories(
+    survey_question, 
+    survey_input,
+    api_key,
+    top_n=10,
+    cat_num=10,
+    divisions=5,
+    user_model="gpt-4o-2024-11-20",
+    creativity=0,
+    specificity="broad",
+    research_question=None,
+    filename=None,
+    model_source="OpenAI"
+):
+    import os
+    import pandas as pd
+    import random
+    from openai import OpenAI
+    from openai import OpenAI, BadRequestError
+    from tqdm import tqdm
+
+    print(f"Exploring class for question: '{survey_question}'.\n          {cat_num * divisions} unique categories to be extracted and {top_n} to be identified as the most common.")
+    print()
+
+    chunk_size = round(max(1, len(survey_input) / divisions),0)
+    chunk_size = int(chunk_size)
+
+    if chunk_size < (cat_num/2):
+        raise ValueError(f"Cannot extract {cat_num} categories from chunks of only {chunk_size} responses. \n" 
+                    f"Choose one solution: \n"
+                    f"(1) Reduce 'divisions' parameter (currently {divisions}) to create larger chunks, or \n"
+                    f"(2) Reduce 'cat_num' parameter (currently {cat_num}) to extract fewer categories per chunk.")
+
+    random_chunks = []
+    for i in range(divisions):
+        chunk = survey_input.sample(n=chunk_size).tolist()
+        random_chunks.append(chunk)
+    
+    responses = []
+    responses_list = []
+    
+    for i in tqdm(range(divisions), desc="Processing chunks"):
+        survey_participant_chunks = '; '.join(random_chunks[i])
+        prompt = f"""Identify {cat_num} {specificity} categories of responses to the question "{survey_question}" in the following list of responses. \
+Responses are each separated by a semicolon. \
+Responses are contained within triple backticks here: ```{survey_participant_chunks}``` \
+Number your categories from 1 through {cat_num} and be concise with the category labels and provide no description of the categories."""
+        
+        if model_source == "OpenAI":
+            client = OpenAI(api_key=api_key)
+            try:
+                response_obj = client.chat.completions.create(
+                    model=user_model,
+                    messages=[
+                        {'role': 'system', 'content': f"""You are a helpful assistant that extracts categories from survey responses. \
+                                                    The specific task is to identify {specificity} categories of responses to a survey question. \
+                         The research question is: {research_question}""" if research_question else "You are a helpful assistant."},
+                        {'role': 'user', 'content': prompt}
+                    ],
+                    temperature=creativity
+                )
+                reply = response_obj.choices[0].message.content
+                responses.append(reply)
+            except BadRequestError as e:
+                if "context_length_exceeded" in str(e) or "maximum context length" in str(e):
+                    error_msg = (f"Token limit exceeded for model {user_model}. "
+                        f"Try increasing the 'iterations' parameter to create smaller chunks.")
+                    raise ValueError(error_msg)
+                else:
+                    print(f"OpenAI API error: {e}")
+            except Exception as e:
+                print(f"An error occurred: {e}")
+        else:
+            raise ValueError(f"Unsupported model_source: {model_source}")
+        
+        # Extract just the text as a list
+        items = []
+        for line in responses[i].split('\n'):
+            if '. ' in line:
+                try:
+                    items.append(line.split('. ', 1)[1])
+                except IndexError:
+                    pass
+
+        responses_list.append(items)
+
+    flat_list = [item.lower() for sublist in responses_list for item in sublist]
+
+    #convert flat_list to a df
+    df = pd.DataFrame(flat_list, columns=['Category'])
+    counts = pd.Series(flat_list).value_counts()  # Use original list before conversion
+    df['counts'] = df['Category'].map(counts)
+    df = df.sort_values(by='counts', ascending=False).reset_index(drop=True)
+    df = df.drop_duplicates(subset='Category', keep='first').reset_index(drop=True)
+
+    second_prompt = f"""From this list of categories, extract the top {top_n} most common categories. \
+The categories are contained within triple backticks here: ```{df['Category'].tolist()}``` \
+Return the top {top_n} categories as a numbered list sorted from the most to least common and keep the categories {specificity}, with no additional text or explanation."""
+        
+    if model_source == "OpenAI":
+        client = OpenAI(api_key=api_key)
+        response_obj = client.chat.completions.create(
+            model=user_model,
+            messages=[{'role': 'user', 'content': second_prompt}],
+            temperature=creativity
+        )
+    top_categories = response_obj.choices[0].message.content
+    print(top_categories)
+
+    top_categories_final = []
+    for line in top_categories.split('\n'):
+        if '. ' in line:
+            try:
+                top_categories_final.append(line.split('. ', 1)[1])
+            except IndexError:
+                pass
+
+    return top_categories_final
+
 #multi-class text classification
 def extract_multi_class(
     survey_question, 
@@ -843,9 +1063,6 @@ def extract_image_features(
         'json': pd.Series(extracted_jsons).reset_index(drop=True)
     })
     categorized_data = pd.concat([categorized_data, normalized_data], axis=1)
-    
-    if columns != "numbered": #if user wants text columns
-        categorized_data.columns = list(categorized_data.columns[:3]) + categories[:len(categorized_data.columns) - 3]
 
     if to_csv:
         if save_directory is None:
@@ -854,222 +1071,333 @@ def extract_image_features(
     
     return categorized_data
 
-#extract categories from corpus
-def explore_corpus(
-    survey_question, 
-    survey_input,
+# image multi-class (binary) function
+def cerad_score(
+    shape, 
+    image_input,
     api_key,
-    research_question=None,
-    specificity="broad",
-    cat_num=10,
-    divisions=5,
     user_model="gpt-4o-2024-11-20",
     creativity=0,
-    filename="corpus_exploration.csv",
+    safety=False,
+    filename="categorized_data.csv",
     model_source="OpenAI"
 ):
     import os
+    import json
     import pandas as pd
-    import random
-    from openai import OpenAI
-    from openai import OpenAI, BadRequestError
+    import regex
     from tqdm import tqdm
+    import glob
+    import base64
+    from pathlib import Path
 
-    print(f"Exploring class for question: '{survey_question}'.\n          {cat_num * divisions} unique categories to be extracted.")
-    print()
-
-    chunk_size = round(max(1, len(survey_input) / divisions),0)
-    chunk_size = int(chunk_size)
+    shape = shape.lower()
 
-    if chunk_size < (cat_num/2):
-        raise ValueError(f"Cannot extract {cat_num} {specificity} categories from chunks of only {chunk_size} responses. \n" 
-                    f"Choose one solution: \n"
-                    f"(1) Reduce 'divisions' parameter (currently {divisions}) to create larger chunks, or \n"
-                    f"(2) Reduce 'cat_num' parameter (currently {cat_num}) to extract fewer categories per chunk.")
+    if shape == "circle":
+        categories = ["It has a drawing of a circle",
+                    "The drawing does not resemble a circle",
+                    "The drawing resembles a circle",
+                    "The circle is closed",
+                    "The circle is almost closed",
+                    "The circle is circular",
+                    "The circle is almost circular",
+                    "None of the above descriptions apply"]
+    elif shape == "diamond":
+        categories = ["It has a drawing of a diamond",
+                    "It has a drawing of a square",
+                    "A drawn shape DOES NOT resemble a diamond",
+                    "A drawn shape resembles a diamond",
+                    "The drawn shape has 4 sides",
+                    "The drawn shape sides are about equal",
+                    "If a diamond is drawn it's more elaborate than a simple diamond (such as overlapping diamonds or a diamond with an extras lines inside)",
+                    "None of the above descriptions apply"]
+    elif shape == "rectangles" or shape == "overlapping rectangles":
+        categories = ["It has a drawing of overlapping rectangles",
+                    "A drawn shape DOES NOT resemble a overlapping rectangles",
+                    "A drawn shape resembles a overlapping rectangles",
+                    "Rectangle 1 has 4 sides",
+                    "Rectangle 2 has 4 sides",
+                    "The rectangles are overlapping",
+                    "The rectangles overlap contains a longer vertical rectangle with top and bottom portruding",
+                    "None of the above descriptions apply"]
+    elif shape == "cube":
+        categories = ["The image contains a drawing that clearly represents a cube (3D box shape)",
+                    "The image does NOT contain any drawing that resembles a cube or 3D box",
+                    "The image contains a WELL-DRAWN recognizable cube with proper 3D perspective",
+                    "If a cube is present: the front face appears as a square or diamond shape",
+                    "If a cube is present: internal/hidden edges are visible (showing 3D depth, not just an outline)",
+                    "If a cube is present: the front and back faces appear parallel to each other",
+                    "The image contains only a 2D square (flat shape, no 3D appearance)",
+                    "None of the above descriptions apply"]
+    else:
+        raise ValueError("Invalid shape! Choose from 'circle', 'diamond', 'rectangles', or 'cube'.")
 
-    random_chunks = []
-    for i in range(divisions):
-        chunk = survey_input.sample(n=chunk_size).tolist()
-        random_chunks.append(chunk)
+    image_extensions = [
+    '*.png', '*.jpg', '*.jpeg',
+    '*.gif', '*.webp', '*.svg', '*.svgz', '*.avif', '*.apng',
+    '*.tif', '*.tiff', '*.bmp',
+    '*.heif', '*.heic', '*.ico',
+    '*.psd'
+    ]
+
+    if not isinstance(image_input, list):
+        # If image_input is a filepath (string)
+        image_files = []
+        for ext in image_extensions:
+            image_files.extend(glob.glob(os.path.join(image_input, ext)))
     
-    responses = []
-    responses_list = []
+        print(f"Found {len(image_files)} images.")
+    else:
+        # If image_files is already a list
+        image_files = image_input
+        print(f"Provided a list of {len(image_input)} images.")
     
-    for i in tqdm(range(divisions), desc="Processing chunks"):
-        survey_participant_chunks = '; '.join(random_chunks[i])
-        prompt = f"""Identify {cat_num} {specificity} categories of responses to the question "{survey_question}" in the following list of responses. \
-Responses are each separated by a semicolon. \
-Responses are contained within triple backticks here: ```{survey_participant_chunks}``` \
-Number your categories from 1 through {cat_num} and be concise with the category labels and provide no description of the categories."""
+    categories_str = "\n".join(f"{i + 1}. {cat}" for i, cat in enumerate(categories))
+    cat_num = len(categories)
+    category_dict = {str(i+1): "0" for i in range(cat_num)}
+    example_JSON = json.dumps(category_dict, indent=4)
+    
+    link1 = []
+    extracted_jsons = []
+
+    for i, img_path in enumerate(tqdm(image_files, desc="Categorising images"), start=0):
+    # Check validity first
+        if img_path is None or not os.path.exists(img_path):
+            link1.append("Skipped NaN input or invalid path")
+            extracted_jsons.append("""{"no_valid_image": 1}""")
+            continue  # Skip the rest of the loop iteration
         
+    # Only open the file if path is valid
+        with open(img_path, "rb") as f:
+            encoded = base64.b64encode(f.read()).decode("utf-8")
+    
+    # Handle extension safely
+        ext = Path(img_path).suffix.lstrip(".").lower()
+        encoded_image = f"data:image/{ext};base64,{encoded}"
+    
+        prompt = [
+            {
+                "type": "text",
+                "text": (
+                    f"You are an image-tagging assistant trained in the CERAD Constructional Praxis test.\n"
+                    f"Task ► Examine the attached image and decide, **for each category below**, "
+                    f"whether it is PRESENT (1) or NOT PRESENT (0).\n\n"
+                    f"Image is expected to show within it a drawing of a {shape}.\n\n"
+                    f"Categories:\n{categories_str}\n\n"
+                    f"Output format ► Respond with **only** a JSON object whose keys are the "
+                    f"quoted category numbers ('1', '2', …) and whose values are 1 or 0. "
+                    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"},
+            },
+        ]
         if model_source == "OpenAI":
+            from openai import OpenAI
             client = OpenAI(api_key=api_key)
             try:
                 response_obj = client.chat.completions.create(
                     model=user_model,
-                    messages=[
-                        {'role': 'system', 'content': f"""You are a helpful assistant that extracts categories from survey responses. \
-                                                    The specific task is to identify {specificity} categories of responses to a survey question. \
-                         The research question is: {research_question}""" if research_question else "You are a helpful assistant."},
-                        {'role': 'user', 'content': prompt}
-                    ]
+                    messages=[{'role': 'user', 'content': prompt}],
                     temperature=creativity
                 )
                 reply = response_obj.choices[0].message.content
-                responses.append(reply)
-            except BadRequestError as e:
-                if "context_length_exceeded" in str(e) or "maximum context length" in str(e):
-                    error_msg = (f"Token limit exceeded for model {user_model}. "
-                        f"Try increasing the 'iterations' parameter to create smaller chunks.")
-                    raise ValueError(error_msg)
-                else:
-                    print(f"OpenAI API error: {e}")
+                link1.append(reply)
             except Exception as e:
                 print(f"An error occurred: {e}")
-        else:
-            raise ValueError(f"Unsupported model_source: {model_source}")
-        
-        # Extract just the text as a list
-        items = []
-        for line in responses[i].split('\n'):
-            if '. ' in line:
-                try:
-                    items.append(line.split('. ', 1)[1])
-                except IndexError:
-                    pass
-
-        responses_list.append(items)
-
-    flat_list = [item.lower() for sublist in responses_list for item in sublist]
-
-    #convert flat_list to a df
-    df = pd.DataFrame(flat_list, columns=['Category'])
-    counts = pd.Series(flat_list).value_counts()  # Use original list before conversion
-    df['counts'] = df['Category'].map(counts)
-    df = df.sort_values(by='counts', ascending=False).reset_index(drop=True)
-    df = df.drop_duplicates(subset='Category', keep='first').reset_index(drop=True)
-
-    if filename is not None:
-        df.to_csv(filename, index=False)
-    
-    return df
-
-#extract top categories from corpus
-def explore_common_categories(
-    survey_question, 
-    survey_input,
-    api_key,
-    top_n=10,
-    cat_num=10,
-    divisions=5,
-    user_model="gpt-4o-2024-11-20",
-    creativity=0,
-    specificity="broad",
-    research_question=None,
-    filename=None,
-    model_source="OpenAI"
-):
-    import os
-    import pandas as pd
-    import random
-    from openai import OpenAI
-    from openai import OpenAI, BadRequestError
-    from tqdm import tqdm
-
-    print(f"Exploring class for question: '{survey_question}'.\n          {cat_num * divisions} unique categories to be extracted and {top_n} to be identified as the most common.")
-    print()
-
-    chunk_size = round(max(1, len(survey_input) / divisions),0)
-    chunk_size = int(chunk_size)
-
-    if chunk_size < (cat_num/2):
-        raise ValueError(f"Cannot extract {cat_num} categories from chunks of only {chunk_size} responses. \n" 
-                    f"Choose one solution: \n"
-                    f"(1) Reduce 'divisions' parameter (currently {divisions}) to create larger chunks, or \n"
-                    f"(2) Reduce 'cat_num' parameter (currently {cat_num}) to extract fewer categories per chunk.")
+                link1.append(f"Error processing input: {e}")
 
-    random_chunks = []
-    for i in range(divisions):
-        chunk = survey_input.sample(n=chunk_size).tolist()
-        random_chunks.append(chunk)
-    
-    responses = []
-    responses_list = []
-    
-    for i in tqdm(range(divisions), desc="Processing chunks"):
-        survey_participant_chunks = '; '.join(random_chunks[i])
-        prompt = f"""Identify {cat_num} {specificity} categories of responses to the question "{survey_question}" in the following list of responses. \
-Responses are each separated by a semicolon. \
-Responses are contained within triple backticks here: ```{survey_participant_chunks}``` \
-Number your categories from 1 through {cat_num} and be concise with the category labels and provide no description of the categories."""
-        
-        if model_source == "OpenAI":
-            client = OpenAI(api_key=api_key)
+        elif model_source == "Perplexity":
+            from openai import OpenAI
+            client = OpenAI(api_key=api_key, base_url="https://api.perplexity.ai")
             try:
                 response_obj = client.chat.completions.create(
                     model=user_model,
-                    messages=[
-                        {'role': 'system', 'content': f"""You are a helpful assistant that extracts categories from survey responses. \
-                                                    The specific task is to identify {specificity} categories of responses to a survey question. \
-                         The research question is: {research_question}""" if research_question else "You are a helpful assistant."},
-                        {'role': 'user', 'content': prompt}
-                    ],
+                    messages=[{'role': 'user', 'content': prompt}],
                     temperature=creativity
                 )
                 reply = response_obj.choices[0].message.content
-                responses.append(reply)
-            except BadRequestError as e:
-                if "context_length_exceeded" in str(e) or "maximum context length" in str(e):
-                    error_msg = (f"Token limit exceeded for model {user_model}. "
-                        f"Try increasing the 'iterations' parameter to create smaller chunks.")
-                    raise ValueError(error_msg)
-                else:
-                    print(f"OpenAI API error: {e}")
+                link1.append(reply)
+            except Exception as e:
+                print(f"An error occurred: {e}")
+                link1.append(f"Error processing input: {e}")
+        elif model_source == "Anthropic":
+            import anthropic
+            client = anthropic.Anthropic(api_key=api_key)
+            try:
+                message = client.messages.create(
+                    model=user_model,
+                    max_tokens=1024,
+                    temperature=creativity,
+                    messages=[{"role": "user", "content": prompt}]
+                )
+                reply = message.content[0].text  # Anthropic returns content as list
+                link1.append(reply)
+            except Exception as e:
+                print(f"An error occurred: {e}")
+                link1.append(f"Error processing input: {e}")
+        elif model_source == "Mistral":
+            from mistralai import Mistral
+            client = Mistral(api_key=api_key)
+            try:
+                response = client.chat.complete(
+                    model=user_model,
+                    messages=[
+                    {'role': 'user', 'content': prompt}
+                ],
+                temperature=creativity
+                )
+                reply = response.choices[0].message.content
+                link1.append(reply)
             except Exception as e:
                 print(f"An error occurred: {e}")
+                link1.append(f"Error processing input: {e}")
         else:
-            raise ValueError(f"Unsupported model_source: {model_source}")
-        
-        # Extract just the text as a list
-        items = []
-        for line in responses[i].split('\n'):
-            if '. ' in line:
+            raise ValueError("Unknown source! Choose from OpenAI, Anthropic, Perplexity, or Mistral")
+            # in situation that no JSON is found
+        if reply is not None:
+            extracted_json = regex.findall(r'\{(?:[^{}]|(?R))*\}', reply, regex.DOTALL)
+            if extracted_json:
+                cleaned_json = extracted_json[0].replace('[', '').replace(']', '').replace('\n', '').replace(" ", '').replace("  ", '')
+                extracted_jsons.append(cleaned_json)
+                #print(cleaned_json)
+            else:
+                error_message = """{"1":"e"}"""
+                extracted_jsons.append(error_message)
+                print(error_message)
+        else:
+            error_message = """{"1":"e"}"""
+            extracted_jsons.append(error_message)
+            #print(error_message)
+
+        # --- Safety Save ---
+        if safety:
+            #print(f"Saving CSV to: {save_directory}")
+            # Save progress so far
+            temp_df = pd.DataFrame({
+                'image_input': image_files[:i+1],
+                'link1': link1,
+                'json': extracted_jsons
+            })
+            # Normalize processed jsons so far
+            normalized_data_list = []
+            for json_str in extracted_jsons:
                 try:
-                    items.append(line.split('. ', 1)[1])
-                except IndexError:
-                    pass
+                    parsed_obj = json.loads(json_str)
+                    normalized_data_list.append(pd.json_normalize(parsed_obj))
+                except json.JSONDecodeError:
+                    normalized_data_list.append(pd.DataFrame({"1": ["e"]}))
+            normalized_data = pd.concat(normalized_data_list, ignore_index=True)
+            temp_df = pd.concat([temp_df, normalized_data], axis=1)
+            # Save to CSV
+            if filename is None:
+                filepath = os.path.join(os.getcwd(), 'catllm_data.csv')
+            else:
+                filepath = filename
+            temp_df.to_csv(filepath, index=False)
 
-        responses_list.append(items)
+    # --- Final DataFrame ---
+    normalized_data_list = []
+    for json_str in extracted_jsons:
+        try:
+            parsed_obj = json.loads(json_str)
+            normalized_data_list.append(pd.json_normalize(parsed_obj))
+        except json.JSONDecodeError:
+            normalized_data_list.append(pd.DataFrame({"1": ["e"]}))
+    normalized_data = pd.concat(normalized_data_list, ignore_index=True)
 
-    flat_list = [item.lower() for sublist in responses_list for item in sublist]
+    categorized_data = pd.DataFrame({
+        'image_input': image_files,
+        'link1': pd.Series(link1).reset_index(drop=True),
+        'json': pd.Series(extracted_jsons).reset_index(drop=True)
+    })
+    categorized_data = pd.concat([categorized_data, normalized_data], axis=1)
+    columns_to_convert = ["1", "2", "3", "4", "5", "6", "7"]
+    categorized_data[columns_to_convert] = categorized_data[columns_to_convert].apply(pd.to_numeric, errors='coerce').fillna(0).astype(int)
 
-    #convert flat_list to a df
-    df = pd.DataFrame(flat_list, columns=['Category'])
-    counts = pd.Series(flat_list).value_counts()  # Use original list before conversion
-    df['counts'] = df['Category'].map(counts)
-    df = df.sort_values(by='counts', ascending=False).reset_index(drop=True)
-    df = df.drop_duplicates(subset='Category', keep='first').reset_index(drop=True)
+    if shape == "circle":
 
-    second_prompt = f"""From this list of categories, extract the top {top_n} most common categories. \
-The categories are contained within triple backticks here: ```{df['Category'].tolist()}``` \
-Return the top {top_n} categories as a numbered list sorted from the most to least common and keep the categories {specificity}, with no additional text or explanation."""
-        
-    if model_source == "OpenAI":
-        client = OpenAI(api_key=api_key)
-        response_obj = client.chat.completions.create(
-            model=user_model,
-            messages=[{'role': 'user', 'content': second_prompt}],
-            temperature=creativity
-        )
-    top_categories = response_obj.choices[0].message.content
-    print(top_categories)
+        categorized_data = categorized_data.rename(columns={
+            "1": "drawing_present",
+            "2": "not_similar",
+            "3": "similar",
+            "4": "cir_closed",
+            "5": "cir_almost_closed",
+            "6": "cir_round",
+            "7": "cir_almost_round",
+            "8": "none"
+        })
 
-    top_categories_final = []
-    for line in top_categories.split('\n'):
-        if '. ' in line:
-            try:
-                top_categories_final.append(line.split('. ', 1)[1])
-            except IndexError:
-                pass
+        categorized_data['score'] = categorized_data['cir_almost_closed'] + categorized_data['cir_closed'] + categorized_data['cir_round'] + categorized_data['cir_almost_round']
+        categorized_data.loc[categorized_data['none'] == 1, 'score'] = 0
+        categorized_data.loc[(categorized_data['drawing_present'] == 0) & (categorized_data['score'] == 0), 'score'] = 0
+
+    elif shape == "diamond":
+
+        categorized_data = categorized_data.rename(columns={
+            "1": "drawing_present",
+            "2": "diamond_square",
+            "3": "not_similar",
+            "4": "similar",
+            "5": "diamond_4_sides",
+            "6": "diamond_equal_sides",
+            "7": "complex_diamond",
+            "8": "none"
+        })
+
+        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
+
+    elif shape == "rectangles" or shape == "overlapping rectangles":
+
+        categorized_data = categorized_data.rename(columns={
+            "1":"drawing_present",
+            "2": "not_similar",
+            "3": "similar",
+            "4": "r1_4_sides",
+            "5": "r2_4_sides",
+            "6": "rectangles_overlap",
+            "7": "rectangles_cross",
+            "8": "none"
+        })
 
-    return top_categories_final
+        categorized_data['score'] = 0
+        categorized_data.loc[(categorized_data['r1_4_sides'] == 1) & (categorized_data['r2_4_sides'] == 1), 'score'] = 1
+        categorized_data.loc[(categorized_data['rectangles_overlap'] == 1) & (categorized_data['rectangles_cross'] == 1), 'score'] += 1
+        categorized_data.loc[categorized_data['none'] == 1, 'score'] = 0
+
+    elif shape == "cube":
+
+        categorized_data = categorized_data.rename(columns={
+            "1": "drawing_present",
+            "2": "not_similar",
+            "3": "similar", 
+            "4": "cube_front_face",
+            "5": "cube_internal_lines",
+            "6": "cube_opposite_sides",
+            "7": "square_only",
+            "8": "none"
+        })
+
+        categorized_data['score'] = categorized_data['cube_front_face'] + categorized_data['cube_internal_lines'] + categorized_data['cube_opposite_sides'] + categorized_data['similar']
+        categorized_data.loc[categorized_data['similar'] == 1, 'score'] = categorized_data['score'] + 1
+        categorized_data.loc[categorized_data['none'] == 1, 'score'] = 0
+        categorized_data.loc[(categorized_data['drawing_present'] == 0) & (categorized_data['score'] == 0), 'score'] = 0
+        categorized_data.loc[(categorized_data['not_similar'] == 1) & (categorized_data['score'] == 0), 'score'] = 0
+        categorized_data.loc[categorized_data['score'] > 4, 'score'] = 4
+
+    else:
+        raise ValueError("Invalid shape! Choose from 'circle', 'diamond', 'rectangles', or 'cube'.")
+
+    categorized_data.loc[categorized_data['no_valid_image'] == 1, 'score'] = None
+
+    if filename is not None:
+        categorized_data.to_csv(filename, index=False)
+    
+    return categorized_data

cat_llm-0.0.19.dist-info/RECORD

@@ -1,7 +0,0 @@
-catllm/__about__.py,sha256=ht639_Zw-BmQ-6TW3sLLeC_s67LbW9TFDrYT8b4xpIg,404
-catllm/__init__.py,sha256=xDin9x4jymeccuxE9Xf-27ncR9h7247IwLbeYN-m3j8,266
-catllm/cat_llm.py,sha256=pj_xcsFA5OQVhMv9-73YT7tDn_3Ol3UowqYAbPrlrZI,43825
-cat_llm-0.0.19.dist-info/METADATA,sha256=Ln27uQy5nspYHg0-iFH_XvAlDJFlfxREKeye2llHteI,1679
-cat_llm-0.0.19.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cat_llm-0.0.19.dist-info/licenses/LICENSE,sha256=wJLsvOr6lrFUDcoPXExa01HOKFWrS3JC9f0RudRw8uw,1075
-cat_llm-0.0.19.dist-info/RECORD,,