flowcept 0.8.11__tar.gz → 0.9.1__tar.gz

{flowcept-0.8.11 → flowcept-0.9.1}/.github/workflows/run-llm-tests.yml

@@ -37,7 +37,7 @@ jobs:
           python --version
 
       - name: Install dependencies
-        run: pip install .[ml_dev,dask,mongo]
+        run: pip install .[extras,ml_dev,dask,mongo]
 
       - name: Test LLM with Dask cluster
         run: python examples/llm_complex/llm_main_example.py --start-dask-cluster

{flowcept-0.8.11 → flowcept-0.9.1}/.github/workflows/run-tests-py313.yml

@@ -36,11 +36,9 @@ jobs:
           python -m pip install --upgrade pip
           python --version
 
-      - name: Install dependencies that work on py3.13
+      - name: Install dependencies
         run: |
-          pip install . --no-deps
-          pip install flask-restful msgpack omegaconf pandas psutil py-cpuinfo redis requests pyarrow
-          pip install .[mongo,analytics,dask,docs,kafka,mlflow,dev]
+          pip install .[all]
 
       - name: List installed packages
         run: pip list

{flowcept-0.8.11 → flowcept-0.9.1}/.github/workflows/run-tests.yml

@@ -29,16 +29,25 @@ jobs:
           cache: "pip"
 
       - name: Show OS Info
-        run: '[[ "$OSTYPE" == "linux-gnu"* ]] && { echo "OS Type: Linux"; (command -v lsb_release &> /dev/null && lsb_release -a) || cat /etc/os-release; uname -r; } || [[ "$OSTYPE" == "darwin"* ]] && { echo "OS Type: macOS"; sw_vers; uname -r; } || echo "Unsupported OS type: $OSTYPE"'
-
-      - name: Start docker compose with redis
-        run: make services-mongo
+        run: 'case "${OSTYPE:-}" in linux*) echo "OS Type: Linux"; (command -v lsb_release >/dev/null 2>&1 && lsb_release -a || cat /etc/os-release); uname -r ;; darwin*) echo "OS Type: macOS"; sw_vers || true; uname -r ;; *) echo "Unsupported OS type: ${OSTYPE:-unknown}" ;; esac'
 
       - name: Upgrade pip
         run: |  
           python -m pip install --upgrade pip
           python --version
 
+      - name: Test basic example without any external service
+        run: |
+          pip install .
+          pip list
+          flowcept --init-settings
+          python examples/start_here.py
+          pip uninstall flowcept -y 
+          rm ~/.flowcept/settings.yaml
+
+      - name: Start docker compose with redis
+        run: make services-mongo
+
       - name: Test examples
         run: bash .github/workflows/run_examples.sh examples true # with mongo
 

{flowcept-0.8.11 → flowcept-0.9.1}/.github/workflows/run_examples.sh

@@ -34,6 +34,8 @@ run_test() {
   pip uninstall flowcept -y > /dev/null 2>&1 || true  # Ignore errors during uninstall
 
   pip install . > /dev/null 2>&1
+  pip install .[extras] > /dev/null 2>&1
+  pip list
 
   if [[ "$with_mongo" == "true" ]]; then
     pip install .[mongo] > /dev/null 2>&1

{flowcept-0.8.11 → flowcept-0.9.1}/PKG-INFO

@@ -1,45 +1,52 @@
 Metadata-Version: 2.4
 Name: flowcept
-Version: 0.8.11
+Version: 0.9.1
 Summary: Capture and query workflow provenance data using data observability
-Project-URL: GitHub, https://github.com/ORNL/flowcept
 Author: Oak Ridge National Laboratory
 License-Expression: MIT
 License-File: LICENSE
-Keywords: ai,big-data,dask,data-analytics,data-integration,databases,lineage,machine-learning,ml,mlflow,model-management,parallel-processing,provenance,reproducibility,responsible-ai,scientific-workflows,tensorboard,workflows
+Keywords: agentic-ai,agentic-workflows,ai,big-data,dask,data-analytics,data-integration,databases,lineage,llm,machine-learning,ml,mlflow,model-management,parallel-processing,provenance,reproducibility,responsible-ai,scientific-workflows,tensorboard,workflows
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
-Requires-Dist: flask-restful
-Requires-Dist: lmdb
 Requires-Dist: msgpack
+Requires-Dist: numpy
 Requires-Dist: omegaconf
-Requires-Dist: pandas
-Requires-Dist: psutil>=6.1.1
-Requires-Dist: py-cpuinfo
-Requires-Dist: pyarrow
-Requires-Dist: redis
-Requires-Dist: requests
+Requires-Dist: orjson
 Provides-Extra: all
 Requires-Dist: alembic; extra == 'all'
 Requires-Dist: confluent-kafka<=2.8.0; extra == 'all'
+Requires-Dist: cryptography; extra == 'all'
 Requires-Dist: dask[distributed]<=2024.10.0; extra == 'all'
+Requires-Dist: flask-restful; extra == 'all'
 Requires-Dist: furo; extra == 'all'
+Requires-Dist: gitpython; extra == 'all'
+Requires-Dist: google-genai; extra == 'all'
 Requires-Dist: jupyterlab; extra == 'all'
+Requires-Dist: langchain-community; extra == 'all'
+Requires-Dist: lmdb; extra == 'all'
+Requires-Dist: mcp[cli]; extra == 'all'
 Requires-Dist: mlflow-skinny; extra == 'all'
 Requires-Dist: nbmake; extra == 'all'
 Requires-Dist: paho-mqtt; extra == 'all'
+Requires-Dist: pandas; extra == 'all'
 Requires-Dist: pika; extra == 'all'
 Requires-Dist: plotly; extra == 'all'
+Requires-Dist: psutil>=6.1.1; extra == 'all'
+Requires-Dist: py-cpuinfo; extra == 'all'
+Requires-Dist: pyarrow; extra == 'all'
 Requires-Dist: pymongo; extra == 'all'
 Requires-Dist: pytest; extra == 'all'
 Requires-Dist: pyyaml; extra == 'all'
+Requires-Dist: redis; extra == 'all'
+Requires-Dist: requests; extra == 'all'
 Requires-Dist: ruff; extra == 'all'
 Requires-Dist: scipy; extra == 'all'
 Requires-Dist: seaborn; extra == 'all'
 Requires-Dist: sphinx; extra == 'all'
 Requires-Dist: sqlalchemy; extra == 'all'
+Requires-Dist: streamlit; extra == 'all'
 Requires-Dist: tbparse; extra == 'all'
 Requires-Dist: tensorboard; extra == 'all'
 Requires-Dist: tensorflow; extra == 'all'
@@ -64,14 +71,28 @@ Requires-Dist: sphinx; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: furo; extra == 'docs'
 Requires-Dist: sphinx; extra == 'docs'
+Provides-Extra: extras
+Requires-Dist: flask-restful; extra == 'extras'
+Requires-Dist: gitpython; extra == 'extras'
+Requires-Dist: lmdb; extra == 'extras'
+Requires-Dist: pandas; extra == 'extras'
+Requires-Dist: psutil>=6.1.1; extra == 'extras'
+Requires-Dist: py-cpuinfo; extra == 'extras'
+Requires-Dist: redis; extra == 'extras'
+Requires-Dist: requests; extra == 'extras'
 Provides-Extra: kafka
 Requires-Dist: confluent-kafka<=2.8.0; extra == 'kafka'
 Provides-Extra: llm-agent
-Requires-Dist: faiss-cpu; extra == 'llm-agent'
 Requires-Dist: langchain-community; extra == 'llm-agent'
 Requires-Dist: mcp[cli]; extra == 'llm-agent'
-Requires-Dist: sentence-transformers; extra == 'llm-agent'
-Requires-Dist: tiktoken; extra == 'llm-agent'
+Requires-Dist: streamlit; extra == 'llm-agent'
+Provides-Extra: llm-google
+Requires-Dist: google-genai; extra == 'llm-google'
+Requires-Dist: langchain-community; extra == 'llm-google'
+Requires-Dist: mcp[cli]; extra == 'llm-google'
+Requires-Dist: streamlit; extra == 'llm-google'
+Provides-Extra: lmdb
+Requires-Dist: lmdb; extra == 'lmdb'
 Provides-Extra: ml-dev
 Requires-Dist: datasets==2.17.0; extra == 'ml-dev'
 Requires-Dist: nltk; extra == 'ml-dev'
@@ -82,15 +103,22 @@ Requires-Dist: torchtext==0.17.2; extra == 'ml-dev'
 Requires-Dist: torchvision==0.17.2; extra == 'ml-dev'
 Provides-Extra: mlflow
 Requires-Dist: alembic; extra == 'mlflow'
+Requires-Dist: cryptography; extra == 'mlflow'
 Requires-Dist: mlflow-skinny; extra == 'mlflow'
 Requires-Dist: sqlalchemy; extra == 'mlflow'
 Requires-Dist: watchdog; extra == 'mlflow'
 Provides-Extra: mongo
+Requires-Dist: pyarrow; extra == 'mongo'
 Requires-Dist: pymongo; extra == 'mongo'
 Provides-Extra: mqtt
 Requires-Dist: paho-mqtt; extra == 'mqtt'
 Provides-Extra: nvidia
 Requires-Dist: nvidia-ml-py; extra == 'nvidia'
+Provides-Extra: redis
+Requires-Dist: redis; extra == 'redis'
+Provides-Extra: telemetry
+Requires-Dist: psutil>=6.1.1; extra == 'telemetry'
+Requires-Dist: py-cpuinfo; extra == 'telemetry'
 Provides-Extra: tensorboard
 Requires-Dist: tbparse; extra == 'tensorboard'
 Requires-Dist: tensorboard; extra == 'tensorboard'

flowcept-0.9.1/examples/agents/a2a/README.md

@@ -0,0 +1,27 @@
+This simple example shows communication between two agents through Flowcept's provenance messages.
+
+### Setup:
+
+- Agent1 runs on localhost:8000
+- Agent2 runs on localhost:8001
+- Client talks to agent1
+
+### Running
+
+1. Run Agent1
+2. Run Agent2
+3. Activate agent2 (this step has to be skipped but couldn't find out how yet): curl -X POST http://localhost:8001/mcp/agent/Agent2/action/liveness      -H "Content-Type: application/json"
+
+The sequence begins by running
+
+`flowcept --agent-client --tool-name  agent_task1`
+
+### Sequence of Message Passing
+
+1. Client starts by calling Agent 1's tool: agent_task1
+2. Instrumented Agent Action agent_task1 sends its completion message 
+3. Agent 1 sends "call_agent_task" message to call agent_task2
+4. Agent 2 receives it
+5. Agent 2 runs its tool agent_task2
+6. Instrumented Agent Action agent_task2 sends its completion message (subtype 'agent_task')
+7. Agent 1 receives it. Prints and finishes.

flowcept-0.9.1/examples/agents/a2a/agent1.py

@@ -0,0 +1,60 @@
+import random
+from typing import Dict
+
+import uvicorn
+from flowcept.flowceptor.consumers.agent.base_agent_context_manager import BaseAgentContextManager
+from flowcept.instrumentation.flowcept_agent_task import agent_flowcept_task
+from flowcept.instrumentation.flowcept_task import flowcept_task
+from mcp.server.fastmcp import FastMCP
+
+from flowcept.configs import AGENT
+
+
+@flowcept_task(subtype="call_agent_task")
+def agent_task2(**kwargs):
+    return
+
+
+class Agent1ContextManager(BaseAgentContextManager):
+
+    def __init__(self):
+        super().__init__()
+
+    def message_handler(self, msg_obj: Dict) -> bool:
+        if msg_obj.get('type', '') == 'task':
+            subtype = msg_obj.get("subtype", '')
+            if subtype == 'agent_task':
+                print(msg_obj)
+                tool_name = msg_obj["activity_id"]
+                generated = msg_obj["generated"]
+                if tool_name == 'agent_task1':
+                    self.logger.debug(f"Ok, Agent 1 executed agent_task1. Now going to send Message to Agent 2")
+                    agent_task2(**generated)
+                elif tool_name == "agent_task2":
+                    self.logger.debug(f"Ok, Agent 2 executed agent_task2. All good. Its output was: {generated}")
+        return True
+
+
+agent_controller = Agent1ContextManager()
+mcp = FastMCP("Agent1", require_session=True, lifespan=agent_controller.lifespan)
+
+
+@mcp.tool()
+@agent_flowcept_task  # Must be in this order. @mcp.tool then @flowcept_task
+def agent_task1(campaign_id=None):
+    return {
+        "msg": "I'm agent 1 and I wish to talk to agent 2!",
+        "data": random.randint(0, 350)
+    }
+
+def main():
+    """
+    Start the MCP server.
+    """
+    uvicorn.run(
+        mcp.streamable_http_app, host=AGENT.get("mcp_host", "0.0.0.0"), port=AGENT.get("mcp_port", 8000), lifespan="on"
+    )
+
+
+if __name__ == "__main__":
+    main()

flowcept-0.9.1/examples/agents/a2a/agent2.py

@@ -0,0 +1,60 @@
+from typing import Dict
+
+import uvicorn
+from flowcept.flowceptor.consumers.agent.base_agent_context_manager import BaseAgentContextManager
+from flowcept.flowceptor.consumers.agent.client_agent import run_tool
+from flowcept.instrumentation.flowcept_agent_task import agent_flowcept_task
+from mcp.server.fastmcp import FastMCP
+
+from flowcept.configs import AGENT
+
+
+class Agent2ContextManager(BaseAgentContextManager):
+
+    def __init__(self):
+        super().__init__()
+
+    def message_handler(self, msg_obj: Dict) -> bool:
+        print(msg_obj)
+        if msg_obj.get('type', '') == 'task':
+            subtype = msg_obj.get("subtype", '')
+            if subtype == 'call_agent_task':
+                tool_name = msg_obj["activity_id"]
+                args = msg_obj["used"]
+                if tool_name == 'agent_task2':
+                    self.logger.debug(f"I am Agent 2. I saw that Agent 1 executed agent_task1 and sent its message to the MQ.\nNow I'm going to execute my action.")
+                    self.logger.debug(f"Args for agent_task2: {args}")
+                    r = run_tool(tool_name="agent_task2", kwargs={"data": args["data"]}, port=8001)
+                    self.logger.info(f"Response: {r}")
+        return True
+
+
+agent_controller = Agent2ContextManager()
+mcp = FastMCP("Agent2", require_session=True, lifespan=agent_controller.lifespan)
+
+
+@mcp.tool()
+@agent_flowcept_task  # Must be in this order. @mcp.tool then @flowcept_task
+def agent_task2(data):
+    print(f"This is the data generated by Agent 1: {data}")
+    return {
+        "msg": "I'm agent 2 and I executed!",
+    }
+
+@mcp.tool()
+def liveness():
+    return "Im alive"
+
+
+def main():
+    """
+    Start the MCP server.
+    """
+    uvicorn.run(
+        mcp.streamable_http_app, host=AGENT.get("mcp_host", "0.0.0.0"), port=8001, lifespan="on"
+    )
+
+
+if __name__ == "__main__":
+    main()
+

flowcept-0.9.1/examples/agents/aec_agent_context_manager.py

@@ -0,0 +1,67 @@
+from dataclasses import dataclass
+from typing import Dict, List
+import json
+
+from flowcept.flowceptor.consumers.agent.base_agent_context_manager import BaseAgentContextManager
+from flowcept.agents.agent_client import run_tool
+
+
+@dataclass
+class AeCContext:
+    """
+    Container for storing agent context data during the lifespan of an application session.
+
+    Attributes
+    ----------
+    tasks : list of dict
+        A list of task messages received from the message queue. Each task message is stored as a dictionary.
+    """
+
+    history: List[Dict]
+
+
+class AdamantineAeCContextManager(BaseAgentContextManager):
+
+    def __init__(self):
+        super().__init__()
+        self.reset_context()
+
+    def message_handler(self, msg_obj: Dict) -> bool:
+        if msg_obj.get('type', '') == 'task':
+            subtype = msg_obj.get("subtype", '')
+            if subtype == 'call_agent_task':
+                print(msg_obj)
+                tool_name = msg_obj["activity_id"]
+                campaign_id = msg_obj.get("campaign_id", None)
+                tool_args = msg_obj.get("used", {})
+                tool_args["campaign_id"] = campaign_id
+                self.logger.debug(f"Going to run {tool_name}, {tool_args}")
+                tool_result = run_tool(tool_name, kwargs=tool_args)
+                if len(tool_result):
+                    if tool_name == 'choose_option':
+                        this_history = dict()
+                        tool_result = tool_result[0]
+                        this_history.update(tool_args["scores"])
+                        tool_result = json.loads(tool_result)
+                        this_history["chosen_option"] = tool_result["option"]
+                        this_history["explanation"] = tool_result["explanation"]
+                        self.context.history.append(this_history)
+                else:
+                    self.logger.error(f"Something wrong happened when running tool {tool_name}.")
+            elif subtype == 'agent_task':
+                print('Tool result', msg_obj["activity_id"])
+            if msg_obj.get("subtype", '') == "llm_query":
+                print("Msg from agent.")
+                #
+                # msg_output = msg_obj.get("generated", {})["response"]
+                #
+                # simulation_output = simulate_layer(self._layers_count, msg_output)
+                #
+                # run_tool_async("ask_agent", simulation_output)
+
+        else:
+            print(f"We got a msg with different type: {msg_obj.get("type", None)}")
+        return True
+
+    def reset_context(self):
+        self.context = AeCContext(history=[])

flowcept-0.9.1/examples/agents/aec_agent_mock.py

@@ -0,0 +1,110 @@
+import json
+from typing import Dict, List
+
+import numpy as np
+import uvicorn
+from flowcept.instrumentation.flowcept_agent_task import agent_flowcept_task
+from mcp.server.fastmcp import FastMCP
+
+from flowcept.configs import AGENT
+from flowcept.agents.agents_utils import build_llm_model
+
+from examples.agents.aec_agent_context_manager import AdamantineAeCContextManager
+from examples.agents.aec_prompts import choose_option_prompt, generate_options_set_prompt
+
+
+agent_controller = AdamantineAeCContextManager()
+mcp = FastMCP("AnC_Agent_mock", require_session=True, lifespan=agent_controller.lifespan)
+
+
+
+#################################################
+# TOOLS
+#################################################
+
+
+@mcp.tool()
+@agent_flowcept_task  # Must be in this order. @mcp.tool then @flowcept_task
+def generate_options_set(layer: int, planned_controls, number_of_options=4, campaign_id=None):
+    llm = build_llm_model()
+    ctx = mcp.get_context()
+    history = ctx.request_context.lifespan_context.history
+    messages = generate_options_set_prompt(layer, planned_controls, history, number_of_options)
+    response = llm.invoke(messages)
+
+    try:
+        control_options = json.loads(response)
+    except Exception as e:
+        raise Exception(f"Could not parse json in generate_options_set. Error {e}. Likely an LLM output problem. "
+                        f"This is the JSON we tried to parse: {response}")
+
+    assert len(control_options) == number_of_options
+    return {"control_options": control_options}
+
+
+@mcp.tool()
+@agent_flowcept_task  # Must be in this order. @mcp.tool then @flowcept_task
+def choose_option(scores: Dict, planned_controls: List[Dict], campaign_id: str=None):
+    llm = build_llm_model()
+    ctx = mcp.get_context()
+    history = ctx.request_context.lifespan_context.history
+    messages = choose_option_prompt(scores, planned_controls, history)
+    response = llm.invoke(messages)
+    try:
+        result = json.loads(response)
+    except Exception as e:
+        raise Exception(f"Could not parse json in choose_option. Error {e}. Likely an LLM output problem. "
+                        f"This is the JSON we tried to parse: {response}")
+
+    human_option = int(np.argmin(scores["scores"]))
+
+    result["human_option"] = human_option
+    result["attention"] = True if human_option != result["option"] else False
+
+    return result
+
+
+@mcp.tool()
+def get_latest(n: int = None) -> str:
+    """
+    Return the latest task(s) as a JSON string.
+    """
+    ctx = mcp.get_context()
+    tasks = ctx.request_context.lifespan_context.tasks
+    if not tasks:
+        return "No tasks available."
+    if n is None:
+        return json.dumps(tasks[-1])
+    return json.dumps(tasks[-n])
+
+
+@mcp.tool()
+def check_liveness() -> str:
+    """
+    Check if the agent is running.
+    """
+
+    return f"I'm {mcp.name} and I'm ready!"
+
+
+@mcp.tool()
+def check_llm() -> str:
+    """
+    Check if the agent can talk to the LLM service.
+    """
+    llm = build_llm_model()
+    response = llm.invoke("Hello, are you there?")
+    return response
+
+
+def main():
+    """
+    Start the MCP server.
+    """
+    uvicorn.run(
+        mcp.streamable_http_app, host=AGENT.get("mcp_host", "0.0.0.0"), port=AGENT.get("mcp_port", 8000), lifespan="on"
+    )
+
+
+if __name__ == "__main__":
+    main()

flowcept-0.9.1/examples/agents/aec_prompts.py

@@ -0,0 +1,113 @@
+from typing import Dict, List
+
+
+def generate_options_set_prompt(layer: int, planned_controls: List[Dict], history: List[Dict] = None,
+                                number_of_options=4) -> str:
+    max_layers = len(planned_controls)
+    prompt_str = f"""
+    Role: You are a decision-making expert in Advanced Additive Manufacturing Technologies at the Manufacturing Demonstration Facility.
+    Background: You are analyzing layers being printed in a 3D printer. A control decision must be made for each layer to optimize printing outcomes.
+
+    Task: Generate exactly {number_of_options} control options for layer {layer} in a print job with {max_layers} layers.
+
+    Domain Constraints: Each control option must be a JSON object with the following fields: 'power', 'dwell_0', and 'dwell_1'.
+    Domain Constraints: 'power' is a float in the range [0, 350]. 'dwell_0' and 'dwell_1' are integers from 10 to 120, divisible by 5.
+    """
+
+    if history:
+        prompt_str += """
+    Context: Use both the original pre-calculated control plan and the full history of previously generated options to inform your decision.
+    """
+    else:
+        prompt_str += """
+    Context: Use only the original pre-calculated control plan to inform your decision.
+    """
+
+    prompt_str += f"""
+    Input - Pre-calculated Control Plan:
+    {planned_controls}
+    """
+
+    if history:
+        prompt_str += f"""
+    Input - Full Decision History:
+    {history}
+
+    History Format: The history is a list of JSON objects. Each entry includes: the layer index, control options generated for that layer, and the calculated score for each option.
+    Scoring Note: Typically (but not always), a lower score indicates a better option.
+    """
+
+    prompt_str += f"""
+    Format Constraints: Output a list with exactly {number_of_options} elements.
+    Format Constraints: Each element must be a JSON object with the format: {{'power': float, 'dwell_0': int, 'dwell_1': int}}.
+    Output Restriction: DO NOT WRITE ANYTHING ELSE. Only output the JSON list. The response will be parsed automatically.
+    """
+    return prompt_str
+
+
+def choose_option_prompt(scores: Dict, planned_controls: List[Dict], history=None) -> str:
+    """
+    Prompt: Write the prompt following according to these:
+
+      1. Analyze the prompt. Perform any improvements that you believe will  help the LLM model answer better. Improve the prompt to try to make it more clear, less redundant for the LLM model.
+     2. Additionally, the LLM model is often making confusion because it analyzes arrays like [2, 3, 5] to choose a score from it, but it hallucinates saying that it chose the score 5 because it's the lowest score, when it's clearly not the case. Improve the prompt to try to make it more clear for the LLM model.
+    3. Analyze each message in the list and use your judgement to identify whether this message is better classified as "human" or as "system.
+    4. Rewrite the function to return an array of pairs ("role", "message"), i.e., each element in the array is a tuple of two strings, where "role" should be either "human" or "system". Do not use any MCP message stuff.
+    5. Reorganize the function for better readability. Check "if history" only once. Use array.extends to reduce the number of appends. It's fine to use more than 120 characters per line.
+    6. Adjust the prompts to better structure the messages themselves, e.g., informing when the message is defining a role, the message content should be "Role: rest of the message"
+    Clearly label :
+    tasks,
+    background,
+     format constraints,
+     domain constraints,
+
+    """
+    current_layer = scores.get("layer")
+    max_layers = len(planned_controls)
+
+    prompt_str = f"""
+    Role: You are a decision-making expert in Advanced Additive Manufacturing Technologies at the Manufacturing Demonstration Facility.
+    Background: You are analyzing a layer-by-layer 3D printing process to help select optimal control decisions based on simulation scores.
+    Task: Choose the best control option for layer {current_layer} out of a set of possible options. You will receive the scores and control options computed by an HPC simulation.
+
+    Domain Constraints: Each control option is a dictionary with the fields 'power', 'dwell_0', and 'dwell_1'.
+    Domain Constraints: 'power' is a float between 0 and 350. 'dwell_0' and 'dwell_1' are integers between 10 and 120, and must be divisible by 5.
+
+    Score Format: The input is a dictionary with:
+    - 'layer': current layer index
+    - 'control_options': a list of candidate control option dictionaries
+    - 'scores': a list of floats of same length, where scores[i] is the score of control_options[i].
+
+    Scoring Hint: Typically (but not always), a lower score indicates better quality. For example, in [5, 10], option 0 is preferred since 5 < 10.
+    ⚠️ Caution: Do NOT hallucinate reasoning. For example, if scores = [2, 3, 5], do NOT say 5 is the lowest. Use correct comparisons only.
+    Labeling: If your chosen option has the lowest score, label it 'expected'. If it does not, label it 'surprise' and explain your reasoning.
+
+    Input - Scores for layer {current_layer}:
+    {scores}
+
+    Input - Pre-calculated Control Plan:
+    {planned_controls}
+    """
+
+    if history:
+        prompt_str += f"""
+
+    Input - Full History of previous control decisions and scores:
+    {history}
+
+    History Format: Each item in the history is a dictionary with keys: 'layer', 'control_options', and 'scores'. Use this to reason based on past behavior.
+    """
+    else:
+        prompt_str += "\nContext: No prior decision history is available. Use only the current inputs.\n"
+
+    prompt_str += """
+    Format Constraints: Return a JSON object like:
+    {"option": index_of_best_option, "explanation": your_reasoning, "agent_label": "expected" or "surprise"}
+
+    Output Restriction: 
+        - DO NOT SAY 'Here is the output'
+        - ONLY WRITE THE VALID JSON. NO EXPLANATIONS AT ALL.
+        - YOUR OUTPUT MUST BE A VALID JSON! Your output will be parsed programmatically.
+    """
+    return prompt_str
+