LLM Functions

def _build_jinx_schema(jinx_obj):
    """Build a self-describing schema string from a jinx's own metadata.

    Only shows params the model must fill: the primary param (first with
    empty default) plus any param with a non-empty default.  Optional
    params with empty defaults are skipped — _execute_jinx fills those
    from the jinx's own defaults so the model can't hallucinate values.
    """
    desc = getattr(jinx_obj, 'description', '') or ''
    inp_list = getattr(jinx_obj, 'inputs', [])
    params = []
    has_primary = False
    for inp in inp_list:
        if isinstance(inp, str):
            params.append(f'"{inp}": "..."')
            has_primary = True
        elif isinstance(inp, dict):
            for k, v in inp.items():
                if isinstance(v, dict) and 'description' in v:
                    params.append(f'"{k}": "...({v["description"]})"')
                    has_primary = True
                elif v:
                    params.append(f'"{k}": "...(default: {v})"')
                else:
                    if not has_primary:
                        params.append(f'"{k}": "..."')
                        has_primary = True
    schema_str = '{' + ', '.join(params) + '}'
    return desc, schema_str

def _execute_jinx(jinx, inputs, npc, team, messages, extra_globals):
    """Execute a jinx and return output."""
    try:
        jinja_env = None
        if npc and hasattr(npc, 'jinja_env'):
            jinja_env = npc.jinja_env
        elif team and hasattr(team, 'forenpc') and team.forenpc:
            jinja_env = getattr(team.forenpc, 'jinja_env', None)

        full_inputs = {}
        for inp in getattr(jinx, 'inputs', []):
            if isinstance(inp, dict):
                key = list(inp.keys())[0]
                default_val = inp[key]
                if isinstance(default_val, str) and default_val.startswith("~"):
                    default_val = os.path.expanduser(default_val)
                full_inputs[key] = default_val
            else:
                full_inputs[inp] = ""
        full_inputs.update(inputs or {})

        result = jinx.execute(
            input_values=full_inputs,
            npc=npc,
            messages=messages,
            extra_globals=extra_globals,
            jinja_env=jinja_env
        )
        if result is None:
            return "Executed with no output."
        if not isinstance(result, dict):
            return str(result)
        return result.get("output", str(result))
    except Exception as e:
        return f"Error: {e}"

def _get_jinxes(npc, team):
    """Get available jinxes from npc (already filtered by jinxes_spec)."""
    jinxes = {}
    if npc and hasattr(npc, 'jinxes_dict'):
        jinxes.update(npc.jinxes_dict)
    return jinxes

def _jinxes_to_tools(jinxes):
    """Convert jinxes to OpenAI-style tool definitions."""
    return [jinx.to_tool_def() for jinx in jinxes.values()]

def abstract(groups, 
             model, 
             provider, 
             npc=None,
             context: str = None, 
             **kwargs):
    """
    Create more abstract terms from groups.
    """
    sample_groups = random.sample(groups, min(len(groups), max(3, len(groups) // 2)))

    groups_text_for_prompt = "\n".join([f'- "{g["name"]}"' for g in sample_groups])

    prompt = f"""
        Create more abstract categories from this list of groups.

        Groups:
        {groups_text_for_prompt}

        You will create higher-level concepts that interrelate between the given groups. 

        Create abstract categories that encompass multiple related facts, but do not unnecessarily combine facts with conjunctions. For example, do not try to combine "characters", "settings", and "physical reactions" into a
        compound group like "Characters, Setting, and Physical Reactions". This kind of grouping is not productive and only obfuscates true abstractions. 
        For example, a group that might encompass the three aforermentioned names might be "Literary Themes" or "Video Editing Functionis", depending on the context.
        Your aim is to abstract, not to just arbitrarily generate associations. 

        Group names should never be more than two words. They should not contain gerunds. They should never contain conjunctions like "AND" or "OR".
        Generate no more than 5 new concepts and no fewer than 2. 

        Respond with JSON:
        """ + '{"groups": [{"name": "abstract category name"}]}'

    response = get_llm_response(prompt,
                                model=model,
                                provider=provider,
                                format="json",
                                npc=npc,
                                context=context,
                                **kwargs)

    return response["response"].get("groups", [])

def assign_groups_to_fact(
    fact: str,
    groups: List[str],
    model = None,
    provider = None,
    npc = None, 
    context: str = None,
    **kwargs
) -> Dict[str, List[str]]:
    """Assign facts to the identified groups"""
    json_format = """Return a JSON object with the following structure:
        {
            "groups": ["list of group names"]
        }

    Do not include any additional markdown formatting or leading json characters."""

    prompt = f"""Given this fact, assign it to any relevant groups.

    A fact can belong to multiple groups if it fits.

    Here is the fact: {fact}

    Here are the groups: {groups}

    {json_format}
    """

    response = get_llm_response(
        prompt,
        model=model,
        provider=provider,
        format="json",
        npc=npc,
        context=context,
        **kwargs
    )
    return response["response"]

def asymptotic_freedom(parent_concept, 
                       supporting_facts, 
                       model=None, 
                       provider=None, 
                       npc = None,
                       context: str = None, 
                       **kwargs):
    """Given a concept and its facts, proposes an intermediate layer of sub-concepts."""
    print(f"  Step Sleep-B: Attempting to deepen concept '{parent_concept['name']}'...")
    fact_statements = []
    for f in supporting_facts:
        fact_statements.append(f['statement'])

    prompt = f"""
    The concept "{parent_concept['name']}" is supported by many diverse facts.
    Propose a layer of 2-4 more specific sub-concepts to better organize these facts.
    These new concepts will exist as nodes that link to "{parent_concept['name']}".

    Supporting Facts: {json.dumps(fact_statements, indent=2)}
    Respond with JSON:
    """ + '{"new_sub_concepts": ["sub_layer1", "sub_layer2"]}'
    response = get_llm_response(prompt, 
                                model=model, 
                                provider=provider,
                                format="json", 
                                context=context, npc=npc,
                                **kwargs)
    return response['response'].get('new_sub_concepts', [])

def bootstrap(
    prompt: str,
    model: str = None,
    provider: str = None,
    npc: Any = None,
    team: Any = None,
    sample_params: Dict[str, Any] = None,
    sync_strategy: str = "consensus",
    context: str = None,
    n_samples: int = 3,
    **kwargs
) -> Dict[str, Any]:
    """Bootstrap by sampling multiple agents from team or varying parameters"""

    if team and hasattr(team, 'npcs') and len(team.npcs) >= n_samples:

        sampled_npcs = list(team.npcs.values())[:n_samples]
        results = []

        for i, agent in enumerate(sampled_npcs):
            response = get_llm_response(
                f"Sample {i+1}: {prompt}\nContext: {context}",
                npc=agent,
                context=context,
                **kwargs
            )
            results.append({
                'agent': agent.name,
                'response': response.get("response", "")
            })
    else:

        if sample_params is None:
            sample_params = {"temperature": [0.3, 0.7, 1.0]}

        results = []
        for i in range(n_samples):
            temp = sample_params.get('temperature', [0.7])[i % len(sample_params.get('temperature', [0.7]))]
            response = get_llm_response(
                f"Sample {i+1}: {prompt}\nContext: {context}",
                model=model,
                provider=provider,
                npc=npc,
                temperature=temp,
                context=context,
                **kwargs
            )
            results.append({
                'variation': f'temp_{temp}',
                'response': response.get("response", "")
            })


    response_texts = [r['response'] for r in results]
    return synthesize(response_texts, sync_strategy, model, provider, npc or (team.forenpc if team else None), context)

def breathe(
    messages: List[Dict[str, str]],
    model: str = None,
    provider: str = None, 
    npc =  None,
    context: str = None,
    **kwargs: Any
) -> Dict[str, Any]:
    """Condense the conversation context into a small set of key extractions."""
    if not messages:
        return {"output": {}, "messages": []}

    if 'stream' in kwargs:
        kwargs['stream'] = False
    conversation_text = "\n".join([f"{m['role']}: {m['content']}" for m in messages])

    prompt = f'''
    Read the following conversation:

    {conversation_text}

    ''' +'''

    Now identify the following items:

    1. The high level objective
    2. The most recent task
    3. The accomplishments thus far
    4. The failures thus far

    Return a JSON like so:

    {
        "high_level_objective": "the overall goal so far for the user", 
        "most_recent_task": "The currently ongoing task", 
        "accomplishments": ["accomplishment1", "accomplishment2"], 
        "failures": ["falures1", "failures2"], 
    }

    '''


    result = get_llm_response(prompt, 
                           model=model, 
                           provider=provider, 
                           npc=npc, 
                           context=context, 
                           format='json', 
                           **kwargs)

    res = result.get('response', {})
    if isinstance(res, str):
        raise Exception
    format_output = f"""Here is a summary of the previous session. 
    The high level objective was: {res.get('high_level_objective')} \n The accomplishments were: {res.get('accomplishments')}, 
    the failures were: {res.get('failures')} and the most recent task was: {res.get('most_recent_task')}   """
    return {'output': format_output,
            'summary': res,
            'messages': [
                         {
                           'content': format_output,
                           'role': 'assistant'}
                           ]
                          }

def check_llm_command(
    command: str,
    model: str = None,
    provider: str = None,
    api_url: str = None,
    api_key: str = None,
    npc: Any = None,
    team: Any = None,
    messages: List[Dict[str, str]] = None,
    images: list = None,
    stream=False,
    context=None,
    actions: Dict[str, Dict] = None,
    extra_globals=None,
    max_iterations: int = 5,
    jinxes: Dict = None,
    tool_capable: bool = None,
    **kwargs,
):
    """Plan and execute: decide whether to answer directly or use jinxes, then do it.

    When stream=True, returns a generator yielding (event_type, data) tuples.
    When stream=False, returns a dict.
    """
    if messages is None:
        messages = []

    if jinxes is None:
        jinxes = _get_jinxes(npc, team)

    # No jinxes — just answer directly
    if not jinxes:
        print('no jinxes detected')

        response = get_llm_response(
            command,
            model=model,
            provider=provider,
            api_url=api_url,
            api_key=api_key,
            messages=messages[-10:],
            npc=npc,
            team=team,
            images=images,
            stream=False,
            context=context,
            **kwargs,
        )
        messages.append({"role": "user", "content": command})
        out = response.get("response", "")
        if out and isinstance(out, str):
            messages.append({"role": "assistant", "content": out})
        return {"messages": messages, "output": out, "usage": response.get("usage", {})}


    prompt = f"""


          A user submitted this request: {command}


          Determine the nature of the user's request:

          1. Should a jinx be invoked to fulfill the request? A jinx is a jinja-template execution script.

          2. Is it a general question that requires an informative answer or a highly specific question that
              requires information on the web?


              Use jinxes when it is obvious that the answer needs to be as up-to-date as possible. For example,
                  a question about where mount everest is does not necessarily need to be answered by a jinx call or an agent pass.

              If a user asks to explain the plot of the aeneid, this can be answered without a jinx call or agent pass.

              If a user were to ask for the current weather in tokyo or the current price of bitcoin or who the mayor of a city is,
                  then a jinx call is appropriate.

              If the user wants you to read a file, it must use a jinx to read the file.

              If the user asks you to edit a file, you must use a jinx to edit the file.

              If the user asks you to take a screenshot, you must to use a jinx to take the screenshot if available

              If a user asks you to search or to take a screenshot or to open a program or to write a program most likely it is
              appropriate to use a jinx. 


              remember, in your output, return only the action sequence. do not include and leading ```json or other markdown tags.

              """

    if messages:
        prompt += f"\nRecent conversation: {messages[-5:]}"

    response = get_llm_response(
        prompt,
        model=model,
        provider=provider,
        api_url=api_url,
        api_key=api_key,
        npc=npc,
        team=team,
        format="json",
        messages=[],
        context=context,
        **kwargs,
    )

    actions = response.get("response", {})
    #import pdb
    #pdb.set_trace()
    # Display plan
    print(actions)

    if not isinstance(actions,list) and isinstance(actions,dict): # the llm returned only one action
        actions = [actions]

    def _execute():
        step_outputs = []
        all_jinx_calls = []
        current_messages = messages.copy()
        last_jinx_output = None

        for i, action_data in enumerate(actions):
            render_markdown(f"- {action_data}")
            action_name = action_data.get("action", "")
            is_jinx = action_name == "invoke_jinx" or "jinx_name" in action_data
            jname = action_data.get("jinx_name", "")

            if stream and is_jinx and jname:
                yield ('tool_start', {'name': jname, 'args': action_data.get('inputs', {})})

            action_result = handle_action_choice(
                         command,
                         action_data,
                         jinxes,
                         model = model,
                         provider = provider,
                         api_url = api_url,
                         api_key = api_key,
                         npc = npc,
                         team = team,
                         messages = current_messages,
                         stream = stream,
                         extra_globals = extra_globals,
                         last_jinx_output = last_jinx_output,
                         step_outputs = step_outputs,
                         context = context,
                         **kwargs,
            )
            current_messages = action_result.get('messages', [])
            output = action_result.get('output', [])
            all_jinx_calls.extend(action_result.get('jinx_calls', []))
            if output == 'INVALID_ACTION':
                for evt in check_llm_command(
                    f"""In the previous attempt, the correct action name was not provided and a jinx could not be deciphered. only select from available jinxes.
                Original request: {command}""",
                    model=model, provider=provider, api_url=api_url, api_key=api_key,
                    npc=npc, team=team, messages=messages, stream=stream,
                    context=context, extra_globals=extra_globals, **kwargs,
                ):
                    yield evt
                return

            if stream:
                # Yield any sub-events from delegation before the tool_result
                for evt in action_result.get('stream_events', []):
                    yield evt
                if is_jinx and jname:
                    yield ('tool_result', {'name': jname, 'result': output, 'args': action_data.get('inputs', {})})
                else:
                    yield ('content', output)

            step_outputs.append(output)
            last_jinx_output = output

        final_output = step_outputs[0] if len(step_outputs) == 1 else "\n".join(str(o) for o in step_outputs)
        yield ('result', {
            "messages": current_messages,
            "output": final_output,
            "usage": response.get("usage", {}),
            "jinx_calls": all_jinx_calls,
        })

    if stream:
        return _execute()

    # Non-streaming: consume the generator and return the result dict
    result = None
    for event_type, data in _execute():
        if event_type == 'result':
            result = data
    return result or {"messages": messages, "output": "", "jinx_calls": []}

def consolidate_facts_llm(new_fact, 
                          existing_facts, 
                          model, 
                          provider, 
                          npc=None,
                          context: str =None,
                          **kwargs):
    """
    Uses an LLM to decide if a new fact is novel or redundant.
    """
    prompt = f"""
        Analyze the "New Fact" in the context of the "Existing Facts" list.
        Your task is to determine if the new fact provides genuinely new information or if it is essentially a repeat or minor rephrasing of information already present.

        New Fact:
        "{new_fact['statement']}"

        Existing Facts:
        {json.dumps([f['statement'] for f in existing_facts], indent=2)}

        Possible decisions:
        - 'novel': The fact introduces new, distinct information not covered by the existing facts.
        - 'redundant': The fact repeats information already present in the existing facts.

        Respond with a JSON object:
        """ + '{"decision": "novel or redundant", "reason": "A brief explanation for your decision."}'
    response = get_llm_response(prompt,
                                model=model, 
                                provider=provider, 
                                format="json", 
                                npc=npc,
                                context=context,
                                **kwargs)
    return response['response']

def criticize(
    prompt: str,
    model: str = None,
    provider: str = None,
    npc: Any = None,
    team: Any = None,
    context: str = None,
    **kwargs
) -> Dict[str, Any]:
    """Provide critical analysis and constructive criticism"""
    critique_prompt = f"""
    Provide a critical analysis and constructive criticism of the following:
    {prompt}

    Focus on identifying weaknesses, potential improvements, and alternative approaches.
    Be specific and provide actionable feedback.
    """

    return get_llm_response(
        critique_prompt,
        model=model,
        provider=provider,
        npc=npc,
        team=team,
        context=context,
        **kwargs
    )

def execute_llm_command(
    command: str,
    model: Optional[str] = None,
    provider: Optional[str] = None,
    api_url: str = None,
    api_key: str = None,
    npc: Optional[Any] = None,
    messages: Optional[List[Dict[str, str]]] = None,
    stream=False,
    context=None,
) -> str:
    """This function executes an LLM command.
    Args:
        command (str): The command to execute.

    Keyword Args:
        model (Optional[str]): The model to use for executing the command.
        provider (Optional[str]): The provider to use for executing the command.
        npc (Optional[Any]): The NPC object.
        messages (Optional[List[Dict[str, str]]): The list of messages.
    Returns:
        str: The result of the LLM command.
    """
    if messages is None:
        messages = []
    max_attempts = 5
    attempt = 0
    subcommands = []


    context = ""
    while attempt < max_attempts:
        prompt = f"""
        A user submitted this query: {command}.
        You need to generate a bash command that will accomplish the user's intent.
        Respond ONLY with the bash command that should be executed. 
        Do not include markdown formatting
        """
        response = get_llm_response(
            prompt,
            model=model,
            provider=provider,
            api_url=api_url,
            api_key=api_key,
            messages=messages,
            npc=npc,
            context=context,
        )

        bash_command = response.get("response", {})

        print(f"LLM suggests the following bash command: {bash_command}")
        subcommands.append(bash_command)

        try:
            print(f"Running command: {bash_command}")
            result = subprocess.run(
                bash_command, shell=True, text=True, capture_output=True, check=True
            )
            print(f"Command executed with output: {result.stdout}")

            prompt = f"""
                Here was the output of the result for the {command} inquiry
                which ran this bash command {bash_command}:

                {result.stdout}

                Provide a simple response to the user that explains to them
                what you did and how it accomplishes what they asked for.
                """

            messages.append({"role": "user", "content": prompt})

            response = get_llm_response(
                prompt,
                model=model,
                provider=provider,
                api_url=api_url,
                api_key=api_key,
                npc=npc,
                messages=messages,
                context=context,
                stream =stream
            )

            return response
        except subprocess.CalledProcessError as e:
            print(f"Command failed with error:")
            print(e.stderr)

            error_prompt = f"""
            The command '{bash_command}' failed with the following error:
            {e.stderr}
            Please suggest a fix or an alternative command.
            Respond with a JSON object containing the key "bash_command" with the suggested command.
            Do not include any additional markdown formatting.

            """

            fix_suggestion = get_llm_response(
                error_prompt,
                model=model,
                provider=provider,
                npc=npc,
                api_url=api_url,
                api_key=api_key,
                format="json",
                messages=messages,
                context=context,
            )

            fix_suggestion_response = fix_suggestion.get("response", {})

            try:
                if isinstance(fix_suggestion_response, str):
                    fix_suggestion_response = json.loads(fix_suggestion_response)

                if (
                    isinstance(fix_suggestion_response, dict)
                    and "bash_command" in fix_suggestion_response
                ):
                    print(
                        f"LLM suggests fix: {fix_suggestion_response['bash_command']}"
                    )
                    command = fix_suggestion_response["bash_command"]
                else:
                    raise ValueError(
                        "Invalid response format from LLM for fix suggestion"
                    )
            except (json.JSONDecodeError, ValueError) as e:
                print(f"Error parsing LLM fix suggestion: {e}")

        attempt += 1

    return {
        "messages": messages,
        "output": "Max attempts reached. Unable to execute the command successfully.",
    }

def find_best_link_concept_llm(candidate_concept_name, 
                               existing_concept_names, 
                               model = None,
                               provider = None,
                               npc = None,
                               context: str = None,
                               **kwargs   ):
    """
    Finds the best existing concept to link a new candidate concept to.
    This prompt now uses neutral "association" language.
    """
    prompt = f"""
    Here is a new candidate concept: "{candidate_concept_name}"

    Which of the following existing concepts is it most closely related to? The relationship could be as a sub-category, a similar idea, or a related domain.

    Existing Concepts:
    {json.dumps(existing_concept_names, indent=2)}

    Respond with the single best-fit concept to link to from the list, or respond with "none" if it is a genuinely new root idea.
    """ + '{"best_link_concept": "The single best concept name OR none"}'
    response = get_llm_response(prompt, 
                                model=model, 
                                provider=provider, 
                                format="json", 
                                npc=npc,
                                context=context,
                                **kwargs)
    return response['response'].get('best_link_concept')

def gen_image(
    prompt: str,
    model: str = None,
    provider: str = None,
    npc: Any = None,
    height: int = 1024,
    width: int = 1024,
    n_images: int=1, 
    input_images: List[Union[str, bytes, PIL.Image.Image]] = None,
    save = False, 
    filename = '',
    api_key: str = None,
):
    """This function generates an image using the specified provider and model.
    Args:
        prompt (str): The prompt for generating the image.
    Keyword Args:
        model (str): The model to use for generating the image.
        provider (str): The provider to use for generating the image.
        filename (str): The filename to save the image to.
        npc (Any): The NPC object.
        api_key (str): The API key for the image generation service.
    Returns:
        List[PIL.Image.Image]: A list of generated PIL Image objects.
    """
    if model is not None and provider is not None:
        pass
    elif model is not None and provider is None:
        provider = lookup_provider(model)
    elif npc is not None:
        if npc.provider is not None:
            provider = npc.provider
        if npc.model is not None:
            model = npc.model
        if npc.api_url is not None:
            api_url = npc.api_url

    images = generate_image(
        prompt=prompt,
        model=model,
        provider=provider,
        height=height,
        width=width, 
        attachments=input_images,
        n_images=n_images, 
        api_key=api_key,

    )
    if save:
        if len(filename) == 0 :
            todays_date = datetime.now().strftime("%Y-%m-%d")
            filename = 'vixynt_gen'
        for i, image in enumerate(images):

            image.save(filename+'_'+str(i)+'.png')
    return images

def gen_video(
    prompt,
    model: str = None,
    provider: str = None,
    npc: Any = None,
    device: str = "cpu",
    output_path="",
    num_inference_steps=10,
    num_frames=25,
    height=256,
    width=256,
    negative_prompt="",
    messages: list = None,
):
    """
    Function Description:
        This function generates a video using either Diffusers or Veo 3 via Gemini API.
    Args:
        prompt (str): The prompt for generating the video.
    Keyword Args:
        model (str): The model to use for generating the video.
        provider (str): The provider to use for generating the video (gemini for Veo 3).
        device (str): The device to run the model on ('cpu' or 'cuda').
        negative_prompt (str): What to avoid in the video (Veo 3 only).
    Returns:
        dict: Response with output path and messages.
    """

    if provider == "gemini":

        try:
            output_path = generate_video_veo3(
                prompt=prompt,
                model=model,
                negative_prompt=negative_prompt,
                output_path=output_path,
            )
            return {
                "output": f"High-fidelity video with synchronized audio generated at {output_path}",
                "messages": messages
            }
        except Exception as e:
            print(f"Veo 3 generation failed: {e}")
            print("Falling back to diffusers...")
            provider = "diffusers"

    if provider == "diffusers" or provider is None:

        output_path = generate_video_diffusers(
            prompt,
            model,
            npc=npc,
            device=device,
            output_path=output_path,
            num_inference_steps=num_inference_steps,
            num_frames=num_frames,
            height=height,
            width=width,
        )
        return {
            "output": f"Video generated at {output_path}",
            "messages": messages
        }

    return {
        "output": f"Unsupported provider: {provider}",
        "messages": messages
    }

def generate_group_candidates(
    items: List[str],
    item_type: str,
    model: str = None,
    provider: str =None,
    npc = None,
    context: str = None,
    n_passes: int = 3,
    subset_size: int = 10, 
    **kwargs
) -> List[str]:
    """Generate candidate groups for items (facts or groups) based on core semantic meaning."""
    all_candidates = []

    for pass_num in range(n_passes):
        if len(items) > subset_size:
            item_subset = random.sample(items, min(subset_size, len(items)))
        else:
            item_subset = items


        prompt = f"""From the following {item_type}, identify specific and relevant conceptual groups.
        Think about the core subject or entity being discussed.

        GUIDELINES FOR GROUP NAMES:
        1.  **Prioritize Specificity:** Names should be precise and directly reflect the content.
        2.  **Favor Nouns and Noun Phrases:** Use descriptive nouns or noun phrases.
        3.  **AVOID:**
            *   Gerunds (words ending in -ing when used as nouns, like "Understanding", "Analyzing", "Processing"). If a gerund is unavoidable, try to make it a specific action (e.g., "User Authentication Module" is better than "Authenticating Users").
            *   Adverbs or descriptive adjectives that don't form a core part of the subject's identity (e.g., "Quickly calculating", "Effectively managing").
            *   Overly generic terms (e.g., "Concepts", "Processes", "Dynamics", "Mechanics", "Analysis", "Understanding", "Interactions", "Relationships", "Properties", "Structures", "Systems", "Frameworks", "Predictions", "Outcomes", "Effects", "Considerations", "Methods", "Techniques", "Data", "Theoretical", "Physical", "Spatial", "Temporal").
        4.  **Direct Naming:** If an item is a specific entity or action, it can be a group name itself (e.g., "Earth", "Lamb Shank Braising", "World War I").

        EXAMPLE:
        Input {item_type.capitalize()}: ["Self-intersection shocks drive accretion disk formation.", "Gravity stretches star into stream.", "Energy dissipation in shocks influences capture fraction."]
        Desired Output Groups: ["Accretion Disk Formation (Self-Intersection Shocks)", "Stellar Tidal Stretching", "Energy Dissipation from Shocks"]

        ---

        Now, analyze the following {item_type}:
        {item_type.capitalize()}: {json.dumps(item_subset)}

        Return a JSON object:
        """ + '{"groups": ["list of specific, precise, and relevant group names"]}'


        response = get_llm_response(
            prompt,
            model=model,
            provider=provider,
            format="json",
            npc=npc,
            context=context,
            **kwargs
        )

        candidates = response["response"].get("groups", [])
        all_candidates.extend(candidates)

    return list(set(all_candidates))

def generate_groups(facts, 
                    model=None,
                    provider=None,
                    npc=None,
                    context: str =None, 
                    **kwargs):
    """Generate conceptual groups for facts"""

    facts_text = "\n".join([f"- {fact['statement']}" for fact in facts])

    prompt = f"""
    Generate conceptual groups for this group off facts:

    {facts_text}

    Create categories that encompass multiple related facts, but do not unnecessarily combine facts with conjunctions. 

    Your aim is to generalize commonly occurring ideas into groups, not to just arbitrarily generate associations. 
    Focus on the key commonly occurring items and expresions.     

    Group names should never be more than two words. They should not contain gerunds. They should never contain conjunctions like "AND" or "OR".
    Respond with JSON:
    """ + '{"groups": [{"name": "group name"}]}'

    response = get_llm_response(prompt,
                                model=model,
                                provider=provider,
                                format="json",
                                context=context,
                                npc=npc,
                                **kwargs)

    return response["response"].get("groups", [])

def generate_image(
    prompt: str,
    model: str ,
    provider: str ,
    height: int = 1024,
    width: int = 1024,
    n_images: int = 1,
    api_key: Optional[str] = None,
    api_url: Optional[str] = None,
    attachments: Union[List[Union[str, bytes, Image.Image]], None] = None,
    save_path: Optional[str] = None,
    custom_model_path: Optional[str] = None,

):
    """
    Unified function to generate or edit images using various providers.

    Args:
        prompt (str): The prompt for generating/editing the image.
        model (str): The model to use.
        provider (str): The provider to use ('openai', 'diffusers', 'gemini', 'ollama').
        height (int): The height of the output image.
        width (int): The width of the output image.
        n_images (int): Number of images to generate.
        api_key (str): API key for the provider.
        api_url (str): API URL for the provider.
        attachments (list): List of images for editing. Can be file paths, bytes, or PIL Images.
        save_path (str): Path to save the generated image.
        custom_model_path (str): Path to a locally fine-tuned Diffusers model.

    Returns:
        List[PIL.Image.Image]: A list of generated PIL Image objects.
    """
    from urllib.request import urlopen
    import os

    if model is None and custom_model_path is None:
        if provider == "openai":
            model = "dall-e-2"
        elif provider == "diffusers":
            model = "runwayml/stable-diffusion-v1-5"
        elif provider == "gemini":
            model = "gemini-2.5-flash-image"
        elif provider == "ollama":
            model = "x/z-image-turbo"

    all_generated_pil_images = []

    if provider == "diffusers":
        if custom_model_path and os.path.isdir(custom_model_path):
            print(f"🌋 Using custom Diffusers model from path: {custom_model_path}")
            model_to_use = custom_model_path
        else:
            model_to_use = model
            print(f"🌋 Using standard Diffusers model: {model_to_use}")

        for _ in range(n_images):
            try:
                image = generate_image_diffusers(
                    prompt=prompt, 
                    model=model_to_use,
                    height=height, 
                    width=width
                )
                all_generated_pil_images.append(image)
            except MemoryError as e:
                raise e
            except Exception as e:
                raise e

    elif provider == "openai":
        images = openai_image_gen(
            prompt=prompt,
            model=model,
            attachments=attachments,
            height=height,
            width=width,
            n_images=n_images,
            api_key=api_key

        )
        all_generated_pil_images.extend(images)

    elif provider == "gemini":
        images = gemini_image_gen(
            prompt=prompt,
            model=model,
            attachments=attachments,
            n_images=n_images,
            api_key=api_key
        )
        all_generated_pil_images.extend(images)

    elif provider == "ollama":
        images = ollama_image_gen(
            prompt=prompt,
            model=model,
            height=height,
            width=width,
            n_images=n_images,
            api_url=api_url
        )
        all_generated_pil_images.extend(images)

    else:
        valid_sizes = ["256x256", "512x512", "1024x1024", "1024x1792", "1792x1024"]
        size = f"{width}x{height}"

        if attachments is not None:
            raise ValueError("Image editing not supported with litellm provider")

        litellm_model_string = f"{provider}/{model}" if provider and model else model

        image_response = image_generation(
            prompt=prompt,
            model=litellm_model_string,
            n=n_images,
            size=size,
            api_key=api_key,
            api_base=api_url,
        )
        for item_data in image_response.data:
            if hasattr(item_data, 'url') and item_data.url:
                with urlopen(item_data.url) as response:
                    all_generated_pil_images.append(Image.open(response))
            elif hasattr(item_data, 'b64_json') and item_data.b64_json:
                image_bytes = base64.b64decode(item_data.b64_json)
                all_generated_pil_images.append(Image.open(io.BytesIO(image_bytes)))
            else:
                print(f"Warning: litellm ImageResponse item has no URL or b64_json: {item_data}")

    if save_path:
        for i, img_item in enumerate(all_generated_pil_images):
            temp_save_path = f"{os.path.splitext(save_path)[0]}_{i}{os.path.splitext(save_path)[1]}"
            if isinstance(img_item, Image.Image):
                img_item.save(temp_save_path)
            else:
                print(f"Warning: Attempting to save non-PIL image item: {type(img_item)}. Skipping save for this item.")

    return all_generated_pil_images