flowcept 0.8.10__py3-none-any.whl → 0.8.12__py3-none-any.whl

flowcept/agents/gui/agent_gui.py

@@ -0,0 +1,76 @@
+import streamlit as st
+from flowcept.agents.gui import AI, PAGE_TITLE
+from flowcept.agents.gui.gui_utils import (
+    query_agent,
+    display_ai_msg,
+    display_ai_msg_from_tool,
+    display_df_tool_response,
+)
+
+from flowcept.agents.tools.in_memory_queries.in_memory_queries_tools import (
+    generate_result_df,
+    generate_plot_code,
+    run_df_code,
+)
+
+st.set_page_config(page_title=PAGE_TITLE, page_icon=AI)
+st.title(PAGE_TITLE)
+
+GREETING = (
+    "Hi, there! I'm a **Workflow Provenance Specialist**.\n\n"
+    "I am tracking workflow executions and I can:\n"
+    "- 🔍 Analyze running workflows\n"
+    "- 📊 Plot graphs\n"
+    "- 🤖 Answer general questions about provenance data\n\n"
+    "How can I help you today?"
+)
+
+
+display_ai_msg(GREETING)
+
+# if "chat_history" not in st.session_state:
+#     st.session_state.chat_history = [{"role": "system", "content":GREETING}]
+#
+# for msg in st.session_state.chat_history:
+#     with st.chat_message(msg["role"], avatar=AI):
+#         st.markdown(msg["content"])
+
+
+def main():
+    """Main Streamlit Function."""
+    user_input = st.chat_input("Send a message")
+    st.caption("💡 Tip: Ask about workflow metrics, generate plots, or summarize data.")
+
+    if user_input:
+        # st.session_state.chat_history.append({"role": "human", "content": user_input})
+
+        with st.chat_message("human"):
+            st.markdown(user_input)
+
+        try:
+            with st.spinner("🤖 Thinking..."):
+                tool_result = query_agent(user_input)
+            print(tool_result)
+
+            if tool_result.result_is_str():
+                display_ai_msg_from_tool(tool_result)
+            elif tool_result.is_success_dict():
+                tool_name = tool_result.tool_name
+                if tool_name in [generate_result_df.__name__, generate_plot_code.__name__, run_df_code.__name__]:
+                    display_df_tool_response(tool_result)
+                else:
+                    display_ai_msg(f"⚠️ Received unexpected response from agent: {tool_result}")
+                    st.stop()
+            else:
+                display_df_tool_response(tool_result)
+                # display_ai_msg(f"⚠️ Received unexpected response from agent: {tool_result}")
+                st.stop()
+
+        except Exception as e:
+            display_ai_msg(f"❌ Error talking to MCP agent:\n\n```text\n{e}\n```")
+            st.stop()
+
+        # st.session_state.chat_history.append({"role": "system", "content": agent_reply})
+
+
+main()

flowcept/agents/gui/gui_utils.py

@@ -0,0 +1,239 @@
+import io
+import json
+
+import streamlit as st
+from flowcept.agents import prompt_handler
+from flowcept.agents.agent_client import run_tool
+from flowcept.agents.agents_utils import ToolResult
+import pandas as pd
+
+from flowcept.agents.gui import AI
+
+
+def query_agent(user_input: str) -> ToolResult:
+    """
+    Send a user query to the agent and parse the response.
+
+    This function forwards the user input to the registered prompt handler
+    via ``run_tool``. The raw string response is then parsed into a
+    ``ToolResult`` for structured handling of success and error cases.
+
+    Parameters
+    ----------
+    user_input : str
+        The text query provided by the user.
+
+    Returns
+    -------
+    ToolResult
+        - ``code=400`` if the agent call fails.
+        - ``code=404`` if the agent response could not be parsed.
+        - ``code=499`` if JSON parsing fails.
+        - Otherwise, the parsed ``ToolResult`` object from the agent.
+
+    Examples
+    --------
+    >>> result = query_agent("Summarize the latest report.")
+    >>> if result.is_success():
+    ...     print(result.result)
+    """
+    try:
+        response_str = run_tool(prompt_handler.__name__, kwargs={"message": user_input})[0]
+    except Exception as e:
+        return ToolResult(code=400, result=f"Failed to communicate with the Agent. Error: {e}")
+    try:
+        tool_result = ToolResult(**json.loads(response_str))
+        if tool_result is None:
+            ToolResult(code=404, result=f"Could not parse agent output:\n{response_str}")
+        return tool_result
+    except Exception as e:
+        return ToolResult(code=499, result=f"Failed to parse agent output:\n{response_str}.\n\nError: {e}")
+
+
+def display_ai_msg(msg: str):
+    """
+    Display an AI message in the Streamlit chat interface.
+
+    This function creates a new chat message block with the "AI" role and
+    renders the given string as Markdown.
+
+    Parameters
+    ----------
+    msg : str
+        The AI message to display.
+
+    Returns
+    -------
+    str
+        The same message string, useful for chaining or logging.
+
+    Examples
+    --------
+    >>> display_ai_msg("Hello! How can I help you today?")
+    """
+    with st.chat_message("AI", avatar=AI):
+        st.markdown(msg)
+    return msg
+
+
+def display_ai_msg_from_tool(tool_result: ToolResult):
+    """
+    Display an AI message based on a ToolResult.
+
+    This function inspects the ``ToolResult`` to determine whether it
+    represents an error or a normal response. It then displays the
+    corresponding message in the Streamlit chat with the "AI" role.
+
+    Parameters
+    ----------
+    tool_result : ToolResult
+        The tool result containing the agent's reply or error.
+
+    Returns
+    -------
+    str
+        The final message displayed in the chat.
+
+    Notes
+    -----
+    - If the result indicates an error (4xx codes), the message is shown in
+      a formatted error block with the error code.
+    - Otherwise, the raw result is displayed as Markdown.
+
+    Examples
+    --------
+    >>> res = ToolResult(code=301, result="Here is the summary you requested.")
+    >>> display_ai_msg_from_tool(res)
+
+    >>> err = ToolResult(code=405, result="Invalid JSON response")
+    >>> display_ai_msg_from_tool(err)
+    """
+    has_error = tool_result.is_error_string()
+    with st.chat_message("AI", avatar=AI):
+        if has_error:
+            agent_reply = (
+                f"❌ Agent encountered an error, code {tool_result.code}:\n\n```text\n{tool_result.result}\n```"
+            )
+        else:
+            agent_reply = tool_result.result
+
+        st.markdown(agent_reply)
+
+    return agent_reply
+
+
+def display_df_tool_response(tool_result: ToolResult):
+    r"""
+    Display the DataFrame contained in a ToolResult.
+
+    This function extracts and displays the DataFrame (if present) from a
+    ``ToolResult`` object, typically after executing a query or code
+    generation tool. It is intended for interactive use in environments
+    where DataFrame output should be visualized or printed.
+
+    Parameters
+    ----------
+    tool_result : ToolResult
+        The tool result object containing the output of a previous operation.
+        Expected to include a CSV-formatted DataFrame string in its ``result``
+        field when ``code`` indicates success.
+
+    Notes
+    -----
+    - If the result does not contain a DataFrame, the function may print or
+      display an error message.
+    - The display method may vary depending on the environment (e.g., console,
+      Streamlit, or notebook).
+
+    Examples
+    --------
+    >>> result = ToolResult(code=301, result={"result_df": "col1,col2\\n1,2\\n3,4"})
+    >>> display_df_tool_response(result)
+    col1  col2
+    0     1     2
+    1     3     4
+    """
+    result_dict = tool_result.result
+    result_code = result_dict.get("result_code", "")
+    result_df_str = result_dict.get("result_df", "").strip()
+
+    summary = result_dict.get("summary", "")
+    summary_error = result_dict.get("summary_error", "")
+
+    plot_code = result_dict.get("plot_code", "")
+    with st.chat_message("AI", avatar=AI):
+        st.markdown("📊 Here's the code:")
+        st.markdown(f"```python\n{result_code}")
+        print(result_code)
+
+        try:
+            df = pd.read_csv(io.StringIO(result_df_str))
+            print("The result is a df")
+            if not df.empty:
+                st.dataframe(df, hide_index=False)
+                print("Columns", str(df.columns))
+                print("Number of columns", len(df.columns))
+            else:
+                st.text("⚠️ Result DataFrame is empty.")
+        except Exception as e:
+            st.markdown(f"❌ {e}")
+            return
+
+        if plot_code:
+            st.markdown("Here's the plot code:")
+            st.markdown(f"```python\n{plot_code}")
+            st.markdown("📊 Here's the plot:")
+            try:
+                exec_st_plot_code(plot_code, df, st)
+            except Exception as e:
+                st.markdown(f"❌ {e}")
+
+        if summary:
+            st.markdown("📝 Summary:")
+            st.markdown(summary)
+        elif summary_error:
+            st.markdown(f"⚠️ Encountered this error when summarizing the result dataframe:\n```text\n{summary_error}")
+
+
+def exec_st_plot_code(code, result_df, st_module):
+    """
+    Execute plotting code dynamically with a given DataFrame and plotting modules.
+
+    This function runs a block of Python code (typically generated by an LLM)
+    to produce visualizations. It injects the provided DataFrame and plotting
+    libraries into the execution context, allowing the code to reference them
+    directly.
+
+    Parameters
+    ----------
+    code : str
+        The Python code to execute, expected to contain plotting logic.
+    result_df : pandas.DataFrame
+        The DataFrame to be used within the plotting code (available as ``result``).
+    st_module : module
+        The Streamlit module (``st``) to be used within the plotting code.
+
+    Notes
+    -----
+    - The execution context includes:
+      - ``result`` : the provided DataFrame.
+      - ``st`` : the given Streamlit module.
+      - ``plt`` : ``matplotlib.pyplot`` for standard plotting.
+      - ``alt`` : ``altair`` for declarative plotting.
+    - The function uses Python's built-in ``exec``; malformed or unsafe code
+      may raise exceptions or cause side effects.
+    - Designed primarily for controlled scenarios such as running generated
+      plotting code inside an application.
+
+    Examples
+    --------
+    >>> import streamlit as st
+    >>> df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
+    >>> code = "st.line_chart(result)"
+    >>> exec_st_plot_code(code, df, st)
+    """
+    print("Plot code \n", code)
+    exec(
+        code,
+        {"result": result_df, "st": st_module, "plt": __import__("matplotlib.pyplot"), "alt": __import__("altair")},
+    )

flowcept/agents/llms/__init__.py

@@ -0,0 +1 @@
+"""LLMs subpackage."""

flowcept/agents/llms/claude_gcp.py

@@ -0,0 +1,139 @@
+import requests
+
+
+class ClaudeOnGCPLLM:
+    """
+    ClaudeOnGCPLLM is a wrapper for invoking Anthropic's Claude models
+    hosted on Google Cloud Vertex AI. It handles authentication, request
+    payload construction, and response parsing for text generation.
+
+    Parameters
+    ----------
+    project_id : str
+        Google Cloud project ID used for Vertex AI requests.
+    google_token_auth : str
+        Bearer token for Google Cloud authentication.
+    location : str, default="us-east5"
+        Vertex AI location where the Claude model is hosted.
+    model_id : str, default="claude-opus-4"
+        Identifier of the Claude model to use.
+    anthropic_version : str, default="vertex-2023-10-16"
+        API version of Anthropic's Claude model on Vertex AI.
+    temperature : float, default=0.5
+        Sampling temperature controlling randomness of output.
+    max_tokens : int, default=512
+        Maximum number of tokens to generate in the response.
+    top_p : float, default=0.95
+        Nucleus sampling parameter; restricts tokens to a top cumulative probability.
+    top_k : int, default=1
+        Top-k sampling parameter; restricts tokens to the top-k most likely options.
+
+    Attributes
+    ----------
+    url : str
+        Full REST endpoint URL for the Claude model on Vertex AI.
+    headers : dict
+        HTTP headers including authentication and content type.
+    temperature : float
+        Current temperature value used in requests.
+    max_tokens : int
+        Maximum number of tokens configured for output.
+    top_p : float
+        Probability cutoff for nucleus sampling.
+    top_k : int
+        Cutoff for top-k sampling.
+
+    Examples
+    --------
+    >>> llm = ClaudeOnGCPLLM(project_id="my-gcp-project", google_token_auth="ya29.a0...")
+    >>> response = llm.invoke("Write a poem about the sunrise.")
+    >>> print(response)
+    "A golden light spills across the horizon..."
+    """
+
+    def __init__(
+        self,
+        project_id: str,
+        google_token_auth: str,
+        location: str = "us-east5",
+        model_id: str = "claude-opus-4",
+        anthropic_version: str = "vertex-2023-10-16",
+        temperature: float = 0.5,
+        max_tokens: int = 512,
+        top_p: float = 0.95,
+        top_k: int = 1,
+    ):
+        self.project_id = project_id
+        self.location = location
+        self.model_id = model_id
+        self.anthropic_version = anthropic_version
+        self.endpoint = f"{location}-aiplatform.googleapis.com"
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.top_p = top_p
+        self.top_k = top_k
+
+        self.url = (
+            f"https://{self.endpoint}/v1/projects/{self.project_id}/locations/{self.location}"
+            f"/publishers/anthropic/models/{self.model_id}:rawPredict"
+        )
+        self.headers = {
+            "Authorization": f"Bearer {google_token_auth}",
+            "Content-Type": "application/json; charset=utf-8",
+        }
+
+    def invoke(self, prompt: str, **kwargs) -> str:
+        """
+        Invoke the Claude model with a user prompt.
+
+        This method sends a prompt to the configured Claude model via Google
+        Cloud Vertex AI, waits for a response, and returns the generated text.
+
+        Parameters
+        ----------
+        prompt : str
+            The user input to send to the Claude model.
+        **kwargs : dict, optional
+            Additional keyword arguments (currently unused, kept for extensibility).
+
+        Returns
+        -------
+        str
+            The generated text from the Claude model.
+
+        Raises
+        ------
+        RuntimeError
+            If the Claude API call fails with a non-200 status code.
+
+        Examples
+        --------
+        >>> llm = ClaudeOnGCPLLM(project_id="my-gcp-project", google_token_auth="ya29.a0...")
+        >>> llm.invoke("Summarize the plot of Hamlet in two sentences.")
+        "Hamlet seeks to avenge his father’s death, feigns madness, and struggles with indecision.
+        Ultimately, nearly all the major characters perish, including Hamlet himself."
+        """
+        payload = {
+            "anthropic_version": self.anthropic_version,
+            "stream": False,
+            "max_tokens": self.max_tokens,
+            "temperature": self.temperature,
+            "top_p": self.top_p,
+            "top_k": self.top_k,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [{"type": "text", "text": prompt}],
+                }
+            ],
+        }
+
+        response = requests.post(self.url, headers=self.headers, json=payload)
+
+        if response.status_code != 200:
+            raise RuntimeError(f"Claude request failed: {response.status_code} {response.text}")
+
+        response_json = response.json()
+
+        # Return the text of the first content block
+        return response_json["content"][0]["text"]

flowcept/agents/llms/gemini25.py

@@ -0,0 +1,119 @@
+from google import genai
+from google.genai import types
+import os
+
+
+class Gemini25LLM:
+    """
+    Gemini25LLM is a lightweight wrapper around Google's Gemini 2.5 models
+    for text generation. It simplifies configuration and provides a unified
+    interface for invoking LLM completions with or without streaming.
+
+    Parameters
+    ----------
+    project_id : str
+        Google Cloud project ID for authentication.
+    location : str, default="us-east5"
+        Vertex AI location where the model is hosted.
+    model : str, default="gemini-2.5-flash-lite"
+        The Gemini model to use (e.g., "gemini-2.5-flash", "gemini-2.5-pro").
+    temperature : float, default=0.7
+        Sampling temperature for controlling output randomness.
+    top_p : float, default=0.95
+        Nucleus sampling parameter; limits tokens to the top cumulative probability.
+    max_output_tokens : int, default=2048
+        Maximum number of tokens to generate in the response.
+    stream : bool, default=False
+        Whether to return responses incrementally (streaming) or as a single string.
+
+    Attributes
+    ----------
+    model_name : str
+        Name of the Gemini model used for generation.
+    client : genai.Client
+        Underlying Google GenAI client instance.
+    config : types.GenerateContentConfig
+        Default generation configuration for the model.
+    stream : bool
+        Indicates whether streaming responses are enabled.
+
+    Examples
+    --------
+    Create a client and run a simple query:
+
+    >>> llm = Gemini25LLM(project_id="my-gcp-project")
+    >>> response = llm.invoke("Write a haiku about the ocean.")
+    >>> print(response)
+    "Blue waves rise and fall / endless dance beneath the sky / whispers of the deep"
+    """
+
+    def __init__(
+        self,
+        project_id: str,
+        location: str = "us-east5",
+        model: str = "gemini-2.5-flash-lite",
+        temperature: float = 0.7,
+        top_p: float = 0.95,
+        max_output_tokens: int = 2048,
+        stream: bool = False,
+    ):
+        self.model_name = model
+        os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
+        self.stream = stream
+        self.client = genai.Client(vertexai=True, project=project_id, location=location)
+        self.config = types.GenerateContentConfig(
+            temperature=temperature,
+            top_p=top_p,
+            max_output_tokens=max_output_tokens,
+        )
+
+    def invoke(self, prompt: str, **kwargs) -> str:
+        r"""
+        Invoke the Gemini LLM with a user prompt.
+
+        This method sends the prompt to the configured Gemini model and returns
+        the generated text. It supports both streaming and non-streaming modes.
+
+        Parameters
+        ----------
+        prompt : str
+            The input text prompt to send to the model.
+        **kwargs : dict, optional
+            Additional arguments (currently unused, kept for extensibility).
+
+        Returns
+        -------
+        str
+            The generated text response from the model. In streaming mode,
+            partial outputs are concatenated and returned as a single string.
+
+        Examples
+        --------
+        Basic invocation:
+
+        >>> llm = Gemini25LLM(project_id="my-gcp-project")
+        >>> llm.invoke("Explain quantum entanglement in simple terms.")
+        "A phenomenon where particles remain connected so that the state of one..."
+
+        Streaming invocation:
+
+        >>> llm = Gemini25LLM(project_id="my-gcp-project", stream=True)
+        >>> llm.invoke("List five creative startup ideas.")
+        "1. AI gardening assistant\n2. Virtual museum curator\n..."
+        """
+        contents = [types.Content(role="user", parts=[types.Part.from_text(text=prompt)])]
+
+        if self.stream:
+            stream = self.client.models.generate_content_stream(
+                model=self.model_name,
+                contents=contents,
+                config=self.config,
+            )
+            return "".join(chunk.text for chunk in stream if chunk.text)
+        else:
+            result = self.client.models.generate_content(
+                model=self.model_name,
+                contents=contents,
+                config=self.config,
+            )
+            return result.text

flowcept/agents/prompts/__init__.py

@@ -0,0 +1 @@
+"""Prompts subpackage."""

flowcept/agents/prompts/general_prompts.py

@@ -0,0 +1,69 @@
+# flake8: noqa: E501
+# flake8: noqa: D103
+
+from mcp.server.fastmcp.prompts import base
+
+BASE_ROLE = (
+    "You are a helpful assistant analyzing provenance data from a large-scale workflow composed of multiple tasks."
+)
+
+DATA_SCHEMA_PROMPT = (
+    "A task object has its provenance: input data is stored in the 'used' field, output in the 'generated' field. "
+    "Tasks sharing the same 'workflow_id' belong to the same workflow execution trace. "
+    "Pay attention to the 'tags' field, as it may indicate critical tasks. "
+    "The 'telemetry_summary' field reports CPU, disk, memory, and network usage, along with 'duration_sec'. "
+    "Task placement is stored in the 'hostname' field."
+)
+
+QUESTION_PROMPT = "I am particularly more interested in the following question: %QUESTION%."
+
+SMALL_TALK_PROMPT = "Act as a Workflow Provenance Specialist. I would like to interact with you, but please be concise and brief. This is my message:\n"
+
+ROUTING_PROMPT = (
+    "You are a routing assistant for a provenance AI agent. "
+    "Given the following user message, classify it into one of the following routes:\n"
+    "- small_talk: if it's casual conversation or some random word (e.g., 'hausdn', 'a', hello, how are you, what can you do, what's your name)\n"
+    "- plot: if user is requesting plots (e.g., plot, chart, visualize)\n"
+    "- historical_prov_query: if the user wants to query historical provenance data\n"
+    "- in_context_query: if the user appears to ask questions about tasks or data in running workflow (or a workflow that ran recently) or if the user mentions the in-memory 'df' or a dataframe.\n"
+    "- in_chat_query: if the user appears to be asking about something that has said recently in this chat.\n"
+    "- unknown: if you don't know.\n"
+    "Respond with only the route label."
+    "User message is below:\n "
+)
+
+
+def get_question_prompt(question: str):
+    """Generates a user prompt with the given question filled in."""
+    return base.UserMessage(QUESTION_PROMPT.replace("%QUESTION%", question))
+
+
+SINGLE_TASK_PROMPT = {
+    "role": f"{BASE_ROLE} You are focusing now on a particular task object which I will provide below.",
+    "data_schema": DATA_SCHEMA_PROMPT,
+    "job": (
+        "Your job is to analyze this single task. Find any anomalies, relationships, or correlations between input,"
+        " output, resource usage metrics, task duration, and task placement. "
+        "Correlations involving 'used' vs 'generated' data are especially important. "
+        "So are relationships between (used or generated) data and resource metrics. "
+        "Highlight outliers or critical information and give actionable insights or recommendations. "
+        "Explain what this task may be doing, using the data provided."
+    ),
+}
+
+MULTITASK_PROMPTS = {
+    "role": BASE_ROLE,
+    "data_schema": DATA_SCHEMA_PROMPT,
+    "job": (
+        "Your job is to analyze a list of task objects to identify patterns across tasks, anomalies, relationships,"
+        " or correlations between inputs, outputs, resource usage, duration, and task placement. "
+        "Correlations involving 'used' vs 'generated' data are especially important. "
+        "So are relationships between (used or generated) data and resource metrics. "
+        "Try to infer the purpose of the workflow. "
+        "Highlight outliers or critical tasks and give actionable insights or recommendations. "
+        "Use the data provided to justify your analysis."
+    ),
+}
+
+BASE_SINGLETASK_PROMPT = [base.UserMessage(SINGLE_TASK_PROMPT[k]) for k in ("role", "data_schema", "job")]
+BASE_MULTITASK_PROMPT = [base.UserMessage(MULTITASK_PROMPTS[k]) for k in ("role", "data_schema", "job")]