flowcept 0.9.6__tar.gz → 0.9.7__tar.gz

{flowcept-0.9.6 → flowcept-0.9.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowcept
-Version: 0.9.6
+Version: 0.9.7
 Summary: Capture and query workflow provenance data using data observability
 Author: Oak Ridge National Laboratory
 License-Expression: MIT
@@ -38,6 +38,7 @@ 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: pymupdf; extra == 'all'
 Requires-Dist: pytest; extra == 'all'
 Requires-Dist: pyyaml; extra == 'all'
 Requires-Dist: redis; extra == 'all'
@@ -88,12 +89,24 @@ Provides-Extra: llm-agent
 Requires-Dist: langchain-community; extra == 'llm-agent'
 Requires-Dist: langchain-openai; extra == 'llm-agent'
 Requires-Dist: mcp[cli]; extra == 'llm-agent'
+Requires-Dist: pymupdf; extra == 'llm-agent'
 Requires-Dist: streamlit; extra == 'llm-agent'
+Provides-Extra: llm-agent-audio
+Requires-Dist: gtts; extra == 'llm-agent-audio'
+Requires-Dist: langchain-community; extra == 'llm-agent-audio'
+Requires-Dist: langchain-openai; extra == 'llm-agent-audio'
+Requires-Dist: mcp[cli]; extra == 'llm-agent-audio'
+Requires-Dist: pydub; extra == 'llm-agent-audio'
+Requires-Dist: pymupdf; extra == 'llm-agent-audio'
+Requires-Dist: speechrecognition; extra == 'llm-agent-audio'
+Requires-Dist: streamlit; extra == 'llm-agent-audio'
+Requires-Dist: streamlit-mic-recorder; extra == 'llm-agent-audio'
 Provides-Extra: llm-google
 Requires-Dist: google-genai; extra == 'llm-google'
 Requires-Dist: langchain-community; extra == 'llm-google'
 Requires-Dist: langchain-openai; extra == 'llm-google'
 Requires-Dist: mcp[cli]; extra == 'llm-google'
+Requires-Dist: pymupdf; extra == 'llm-google'
 Requires-Dist: streamlit; extra == 'llm-google'
 Provides-Extra: lmdb
 Requires-Dist: lmdb; extra == 'lmdb'

flowcept-0.9.7/docs/task_schema.rst

@@ -0,0 +1,157 @@
+Task Data Schema
+================
+
+This document describes the schema of a task record used to capture metadata, telemetry, and provenance in a workflow. 
+A task represents one unit of work, including inputs, outputs, execution context, system telemetry, and runtime provenance.
+
+Each task record may include fields for identifiers, timing, telemetry, user and system context, dependencies, and custom metadata.
+
+Task Fields
+-----------
+
+- **type**: Constant type label (``"task"``) (string)
+- **subtype**: Optional subtype of the task, e.g., iteration, ML step, custom (string)
+
+Identifiers
+~~~~~~~~~~~
+
+- **task_id**: Unique identifier for the task (string)
+- **workflow_id**: Identifier for the workflow this task belongs to (string)
+- **workflow_name**: Name of the workflow this task belongs to (string)
+- **campaign_id**: Identifier for the campaign this task belongs to (string)
+- **activity_id**: Identifier for the activity performed by the task (usually a function name) (string)
+- **group_id**: Identifier grouping related tasks, e.g., loop iterations (string)
+- **parent_task_id**: Identifier of the parent task, if nested (string)
+- **agent_id**: Identifier of the agent responsible for executing the task (string)
+- **adapter_id**: Identifier of the adapter that produced this task (string)
+- **environment_id**: Identifier of the environment where the task ran (string)
+
+Timing
+~~~~~~
+
+- **utc_timestamp**: UTC timestamp when the task object was created (float)
+- **submitted_at**: Timestamp when the task was submitted (float)
+- **started_at**: Timestamp when execution started (float)
+- **ended_at**: Timestamp when execution ended (float)
+- **registered_at**: Timestamp when registered in storage (float)
+
+Provenance Data
+~~~~~~~~~~~~~~~
+
+- **used**: Inputs consumed by the task, such as parameters, files, or resources (dictionary)
+- **generated**: Outputs produced by the task, e.g., results, artifacts, files (dictionary)
+- **dependencies**: List of task IDs this task depends on (list)
+- **dependents**: List of task IDs that depend on this task (list)
+
+Execution Metadata
+~~~~~~~~~~~~~~~~~~
+
+- **status**: Execution status of the task (e.g., FINISHED, ERROR) (string)
+- **stdout**: Captured standard output (string or dictionary)
+- **stderr**: Captured standard error (string or dictionary)
+- **data**: Arbitrary raw payload associated with the task (any type)
+- **custom_metadata**: User- or developer-provided metadata dictionary (dictionary)
+- **tags**: User-defined tags attached to the task (list)
+
+User and System Context
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- **user**: User who executed or triggered the task (string)
+- **login_name**: Login name of the user in the environment (string)
+- **node_name**: Node where the task executed (string)
+- **hostname**: Hostname of the machine executing the task (string)
+- **public_ip**: Public IP address (string)
+- **private_ip**: Private IP address (string)
+- **address**: Optional network address (string)
+- **mq_host**: Message queue host associated with the task (string)
+
+Telemetry Data Schema
+---------------------
+
+If telemetry capture is enabled, telemetry snapshots are stored in ``telemetry_at_start`` and ``telemetry_at_end``. 
+Each is a dictionary with the following structure:
+
+CPU
+~~~
+
+- **times_avg**: Dictionary with CPU times
+  - **user**, **nice**, **system**, **idle**
+- **percent_all**: Overall CPU usage percentage
+- **frequency**: CPU frequency
+- **times_per_cpu**: List of dictionaries of per-core times
+- **percent_per_cpu**: List of per-core usage percentages
+
+Process
+~~~~~~~
+
+- **pid**: Process ID
+- **memory**: Dictionary with memory stats
+  - **rss**, **vms**, **pfaults**, **pageins**
+- **memory_percent**: Memory usage percentage
+- **cpu_times**: Dictionary with CPU times
+  - **user**, **system**, **children_user**, **children_system**
+- **cpu_percent**: CPU usage percentage
+- **executable**: Path to executable
+- **cmd_line**: Command line arguments
+- **num_open_file_descriptors**, **num_connections**, **num_open_files**, **num_threads**
+- **num_ctx_switches**: Dictionary with
+  - **voluntary**, **involuntary**
+
+Memory
+~~~~~~
+
+- **virtual**: Dictionary with virtual memory stats
+  - **total**, **available**, **percent**, **used**, **free**, **active**, **inactive**, **wired**
+- **swap**: Dictionary with swap memory stats
+  - **total**, **used**, **free**, **percent**, **sin**, **sout**
+
+Disk
+~~~~
+
+- **disk_usage**: Dictionary with usage stats
+  - **total**, **used**, **free**, **percent**
+- **io_sum**: Dictionary with I/O stats
+  - **read_count**, **write_count**, **read_bytes**, **write_bytes**, **read_time**, **write_time**
+
+Network
+~~~~~~~
+
+- **netio_sum**: Dictionary with aggregate network I/O
+  - **bytes_sent**, **bytes_recv**, **packets_sent**, **packets_recv**, **errin**, **errout**, **dropin**, **dropout**
+- **netio_per_interface**: Dictionary keyed by interface with same metrics
+
+GPU
+~~~
+
+GPU telemetry data, if available, is in the ``gpu`` field. Structure depends on vendor.
+
+**Common Fields**
+
+- **gpu_ix**: GPU index (int)
+- **used**: Memory used (bytes)
+- **temperature**: Dictionary or integer temperature
+- **power**: Dictionary or value of power usage
+- **id**: Device UUID
+- **name**: GPU name (NVIDIA only)
+- **activity**: GPU activity percentage (AMD only)
+- **others**: Clock/performance data (AMD only)
+
+**AMD GPU**
+
+- **temperature**: edge, hotspot, mem, vrgfx, vrmem, hbm, fan_speed
+- **power**: average_socket_power, energy_accumulator
+- **others**: current_gfxclk, current_socclk, current_uclk, current_vclk0, current_dclk0
+
+**NVIDIA GPU**
+
+- **temperature**: Celsius value
+- **power**: Milliwatts usage
+- **used**: Memory used (bytes)
+- **name**: Model name
+- **id**: Device UUID
+
+Notes
+-----
+
+Telemetry values vary depending on system capabilities, GPU vendor APIs, 
+and what is enabled in the configuration.

{flowcept-0.9.6 → flowcept-0.9.7}/pyproject.toml

@@ -65,8 +65,14 @@ mlflow = ["mlflow-skinny", "SQLAlchemy", "alembic", "watchdog", "cryptography"]
 nvidia = ["nvidia-ml-py"]
 mqtt = ["paho-mqtt"]
 tensorboard = ["tensorboard", "tensorflow", "tbparse"]
-llm_agent = ["mcp[cli]", "langchain_community", "streamlit", "langchain_openai"]
+llm_agent = ["mcp[cli]", "langchain_community", "langchain_openai", "streamlit", "PyMuPDF"]
 llm_google = ["flowcept[llm_agent]", "google-genai"]
+llm_agent_audio = ["flowcept[llm_agent]", "streamlit-mic-recorder", "SpeechRecognition", "pydub", "gTTS"]
+# System dependency (required for pydub)
+# Install ffmpeg on the system (not a pip package):
+# macOS (Homebrew): brew install ffmpeg
+# Conda (any OS): conda install -c conda-forge ffmpeg
+# Debian/Ubuntu: sudo apt-get install ffmpeg
 
 dev = [
     "flowcept[docs]",

{flowcept-0.9.6 → flowcept-0.9.7}/resources/sample_settings.yaml

@@ -1,4 +1,4 @@
-flowcept_version: 0.9.6 # Version of the Flowcept package. This setting file is compatible with this version.
+flowcept_version: 0.9.7 # Version of the Flowcept package. This setting file is compatible with this version.
 
 project:
   debug: true # Toggle debug mode. This will add a property `debug: true` to all saved data, making it easier to retrieve/delete them later.
@@ -91,6 +91,7 @@ agent:
   model: '?'
   service_provider: '?'
   model_kwargs: {}
+  audio_enabled: false
 
 databases:
 

{flowcept-0.9.6 → flowcept-0.9.7}/src/flowcept/agents/gui/agent_gui.py

@@ -1,76 +1,87 @@
 import streamlit as st
+
 from flowcept.agents.gui import AI, PAGE_TITLE
+from flowcept.agents.gui.audio_utils import get_audio_text
 from flowcept.agents.gui.gui_utils import (
     query_agent,
     display_ai_msg,
     display_ai_msg_from_tool,
     display_df_tool_response,
+    resolve_logo_path,
+    render_title_with_logo,
 )
-
 from flowcept.agents.tools.in_memory_queries.in_memory_queries_tools import (
     generate_result_df,
     generate_plot_code,
     run_df_code,
 )
+from flowcept.configs import AGENT_AUDIO
 
+# ---- Page setup & header with logo ----
 st.set_page_config(page_title=PAGE_TITLE, page_icon=AI)
-st.title(PAGE_TITLE)
+
+LOGO_PATH = resolve_logo_path(package="flowcept", resource="docs/img/flowcept-logo.png")
+render_title_with_logo(PAGE_TITLE, LOGO_PATH, logo_width=150, add_to_sidebar=False, debug=False)
 
 GREETING = (
-    "Hi, there! I'm a **Workflow Provenance Specialist**.\n\n"
+    "Hi, there! I'm your **Workflow Provenance Assistant**.\n\n"
     "I am tracking workflow executions and I can:\n"
-    "- 🔍 Analyze running workflows\n"
+    "- 🔍 Query 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."""
+    """Main Agent GUI function."""
+    st.caption(
+        "💡 Tip: Ask about workflow metrics, generate plots, or summarize data. "
+        "Inputs are mapped to `used` and outputs to `generated` fields. "
+        "Use @record <your query guidance> if you have custom guidance."
+    )
+
     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})
+        st.session_state["speak_reply"] = False
+
+    if AGENT_AUDIO:
+        user_input = get_audio_text(user_input)
 
+    if 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__]:
+                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})
 
+if "speak_reply" not in st.session_state:
+    st.session_state["speak_reply"] = False
 
 main()

flowcept-0.9.7/src/flowcept/agents/gui/audio_utils.py

@@ -0,0 +1,129 @@
+import re
+import tempfile
+from io import BytesIO
+import base64
+
+import streamlit as st
+from gtts import gTTS
+from streamlit_mic_recorder import mic_recorder
+import speech_recognition as sr
+from pydub import AudioSegment  # needs ffmpeg installed
+
+
+def _normalize_mic_output(out) -> bytes | None:
+    """Handle different return shapes from streamlit-mic-recorder."""
+    if not isinstance(out, dict):
+        return None
+    if out.get("wav"):
+        return out["wav"]
+    if out.get("bytes"):
+        return out["bytes"]
+    if out.get("b64"):
+        return base64.b64decode(out["b64"])
+    return None
+
+
+def _is_wav_pcm(blob: bytes) -> bool:
+    """Quick RIFF/WAVE header check."""
+    h = blob[:12]
+    return h.startswith(b"RIFF") and h[8:12] == b"WAVE"
+
+
+def _to_pcm_wav_16k(blob: bytes) -> bytes:
+    """
+    Convert arbitrary audio bytes (webm/ogg/mp3/…) to 16-bit PCM WAV mono @16k.
+    Requires ffmpeg via pydub.
+    """
+    if _is_wav_pcm(blob):
+        return blob
+    seg = AudioSegment.from_file(BytesIO(blob))  # ffmpeg does the heavy lifting
+    seg = seg.set_channels(1).set_frame_rate(16000).set_sample_width(2)
+    buf = BytesIO()
+    seg.export(buf, format="wav")
+    return buf.getvalue()
+
+
+def get_audio_text(user_input: str) -> str:
+    """
+    User Audio Getter.
+    """
+    # Voice input expander
+    with st.expander("🎤 Voice input", expanded=False):
+        st.caption("Click **Speak**, talk, then **Stop**. Allow mic permission in your browser.")
+        out = mic_recorder(
+            start_prompt="🎙️ Speak",
+            stop_prompt="⏹️ Stop",
+            key="mic_rec_1",
+            use_container_width=True,
+        )
+
+        # Normalize outputs from the component
+        raw_audio = _normalize_mic_output(out)
+
+        if raw_audio:
+            try:
+                wav_bytes = _to_pcm_wav_16k(raw_audio)
+            except Exception as e:
+                st.error(f"Could not convert audio to WAV (need ffmpeg/ffprobe?): {e}")
+                wav_bytes = None
+
+            if wav_bytes:
+                st.audio(wav_bytes, format="audio/wav")
+
+                # Transcribe with SpeechRecognition
+                r = sr.Recognizer()
+                try:
+                    with sr.AudioFile(BytesIO(wav_bytes)) as source:
+                        audio = r.record(source)
+                    voice_text = r.recognize_google(audio)  # type: ignore[attr-defined]
+                    st.success(f"You said: {voice_text}")
+                    if not user_input:
+                        user_input = voice_text
+                        st.session_state["speak_reply"] = True  # speak back only when voice was used
+                        print(f"Setting session state to {st.session_state['speak_reply']}")
+                except Exception as e:
+                    st.warning(f"Transcription failed: {e}")
+
+    return user_input
+
+
+def speech_to_text():
+    """Record from mic, return transcribed text or None."""
+    rec = mic_recorder(
+        start_prompt="🎙️ Speak",
+        stop_prompt="⏹️ Stop",
+        key="mic",
+        use_container_width=True,
+    )
+    if rec and "wav" in rec:
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as tmp:
+            tmp.write(rec["wav"])
+            tmp.flush()
+            r = sr.Recognizer()
+            with sr.AudioFile(tmp.name) as source:
+                audio = r.record(source)
+            try:
+                return r.recognize_google(audio)
+            except Exception as e:
+                st.warning(f"Speech recognition failed: {e}")
+    return None
+
+
+def speak(text: str):
+    """Synthesize speech for the agent reply and play it."""
+    if not text:
+        return
+    try:
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".mp3") as tmp:
+            gTTS(text).save(tmp.name)
+            st.audio(tmp.name, format="audio/mp3")
+    except Exception as e:
+        st.warning(f"TTS failed: {e}")
+
+
+def _md_to_plain_text(s: str) -> str:
+    """Very light Markdown cleanup for TTS."""
+    s = re.sub(r"```.*?```", lambda m: m.group(0).replace("```", ""), s, flags=re.S)  # drop fences
+    s = s.replace("`", "")  # inline code ticks
+    s = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", s)  # links: [text](url) -> text
+    return s.strip()

{flowcept-0.9.6 → flowcept-0.9.7}/src/flowcept/agents/gui/gui_utils.py

@@ -2,14 +2,20 @@ import base64
 import ast
 import io
 import json
+from pathlib import Path
+from importlib.resources import files as pkg_files
+
+import pandas as pd
 
 import streamlit as st
+from flowcept.agents.gui import AI
 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
+
+from flowcept.agents.gui.audio_utils import _md_to_plain_text, speak
+from flowcept.configs import AGENT_AUDIO
 
 
 def query_agent(user_input: str) -> ToolResult:
@@ -125,6 +131,8 @@ def display_ai_msg_from_tool(tool_result: ToolResult):
 
 
 def _sniff_mime(b: bytes) -> str:
+    if b.startswith(b"%PDF-"):
+        return "application/pdf"
     if b.startswith(b"\x89PNG\r\n\x1a\n"):
         return "image/png"
     if b.startswith(b"\xff\xd8\xff"):
@@ -138,23 +146,72 @@ def _sniff_mime(b: bytes) -> str:
     return "application/octet-stream"
 
 
+def _pdf_first_page_to_png(pdf_bytes: bytes, zoom: float = 2.0) -> bytes:
+    """
+    Convert the first page of a PDF to PNG bytes using PyMuPDF (fitz).
+    zoom ~2.0 gives a good thumbnail; increase for higher resolution.
+    """
+    try:
+        import fitz  # PyMuPDF
+    except Exception as e:
+        # PyMuPDF not installed; caller can decide how to handle
+        raise ImportError("PyMuPDF (fitz) is required to render PDF thumbnails") from e
+
+    doc = fitz.open(stream=pdf_bytes, filetype="pdf")
+    try:
+        page = doc.load_page(0)
+        pix = page.get_pixmap(matrix=fitz.Matrix(zoom, zoom), alpha=False)
+        return pix.tobytes("png")
+    finally:
+        doc.close()
+
+
 def ensure_data_uri(val):
-    r"""Accepts bytes/bytearray/memoryview or a repr like \"b'\\x89PNG...'\" and returns a data URL."""
+    r"""Accept bytes/bytearray/memoryview or a repr like "b'\x89PNG...'", or a file path/URL.
+    Returns a data URL suitable for st.column_config.ImageColumn. If input is a PDF, converts
+    the first page to PNG (requires PyMuPDF).
+    """
+    # Already a data URI?
     if isinstance(val, str) and val.startswith("data:"):
         return val
+
+    # Bytes repr string? -> real bytes
     if isinstance(val, str) and val.startswith("b'"):
         try:
-            val = ast.literal_eval(val)  # turn repr into bytes
+            val = ast.literal_eval(val)
         except Exception:
             return None
+
+    # Paths that point to a PDF: convert
+    if isinstance(val, str) and val.lower().endswith(".pdf") and Path(val).is_file():
+        try:
+            pdf_bytes = Path(val).read_bytes()
+            png_bytes = _pdf_first_page_to_png(pdf_bytes)
+            return f"data:image/png;base64,{base64.b64encode(png_bytes).decode('ascii')}"
+        except Exception:
+            # Fallback: no preview; caller will show blank cell
+            return None
+
+    # Normalize to bytes if memoryview/bytearray
     if isinstance(val, memoryview):
         val = val.tobytes()
     if isinstance(val, bytearray):
         val = bytes(val)
+
+    # Raw bytes? detect and convert if PDF
     if isinstance(val, bytes):
         mime = _sniff_mime(val)
+        if mime == "application/pdf":
+            try:
+                png_bytes = _pdf_first_page_to_png(val)
+                return f"data:image/png;base64,{base64.b64encode(png_bytes).decode('ascii')}"
+            except Exception:
+                return None
+        # Regular image bytes -> data URI
         return f"data:{mime};base64,{base64.b64encode(val).decode('ascii')}"
-    return val  # path/URL, etc.
+
+    # Otherwise (URL/path to an image) let Streamlit try; PDFs won’t render as images
+    return val
 
 
 def _render_df(df: pd.DataFrame, image_width: int = 90, row_height: int = 90):
@@ -242,6 +299,17 @@ def display_df_tool_response(tool_result: ToolResult):
             st.markdown("📝 Summary:")
             print(f"THIS IS THE SUMMARY\n{summary}")
             st.markdown(summary)
+
+            if AGENT_AUDIO:
+                # 🔊 Speak only if user spoke to us this turn
+                print(f"This is the session state nowww: {st.session_state['speak_reply']}")
+                if st.session_state.get("speak_reply"):
+                    try:
+                        plain_text = _md_to_plain_text(summary)
+                        print(f"Trying to speak plain text {plain_text}")
+                        speak(plain_text)  # uses your existing gTTS-based speak()
+                    except Exception as e:
+                        st.warning(f"TTS failed: {e}")
         elif summary_error:
             st.markdown(f"⚠️ Encountered this error when summarizing the result dataframe:\n```text\n{summary_error}")
 
@@ -288,3 +356,87 @@ def exec_st_plot_code(code, result_df, st_module):
         code,
         {"result": result_df, "st": st_module, "plt": __import__("matplotlib.pyplot"), "alt": __import__("altair")},
     )
+
+
+def _resolve_logo() -> str | None:
+    # Try package resource
+    try:
+        p = pkg_files("flowcept").joinpath("docs/img/flowcept-logo.png")
+        if p.is_file():
+            return str(p)
+    except Exception:
+        pass
+    # Fallbacks for dev checkouts
+    here = Path(__file__).resolve()
+    candidates = [
+        here.parents[3] / "docs/img/flowcept-logo.png",
+        here.parents[2] / "docs/img/flowcept-logo.png",
+        here.parents[1] / "docs/img/flowcept-logo.png",
+        Path("flowcept/docs/img/flowcept-logo.png"),
+    ]
+    for c in candidates:
+        if c.is_file():
+            return str(c)
+    print(str(c))
+    return None
+
+
+def resolve_logo_path(package: str = "flowcept", resource: str = "docs/img/flowcept-logo.png") -> str | None:
+    """
+    Resolve the Flowcept logo whether running from an installed package or a src/ layout repo.
+    Returns an absolute string path or None if not found.
+    """
+    # 1) Try packaged resource (works if docs/img is included in the wheel/sdist)
+    try:
+        p = pkg_files(package).joinpath(resource)
+        if hasattr(p, "is_file") and p.is_file():
+            return str(p)
+    except Exception:
+        pass
+
+    here = Path(__file__).resolve()
+
+    # 2) src/ layout repo: .../<repo>/flowcept/src/flowcept/agents/gui/gui_utils.py
+    #    Find the nearest 'src' ancestor, then go to repo root (src/..), then docs/img/...
+    try:
+        src_dir = next(p for p in here.parents if p.name == "src")
+        repo_root = src_dir.parent  # <repo>/flowcept
+        cand = repo_root / "docs" / "img" / "flowcept-logo.png"
+        if cand.is_file():
+            return str(cand)
+    except StopIteration:
+        pass
+
+    # 3) Editable install package dir: .../src/flowcept (package root)
+    pkg_dir = here.parents[2]  # .../src/flowcept
+    cand = pkg_dir / "docs" / "img" / "flowcept-logo.png"
+    if cand.is_file():
+        return str(cand)
+
+    # 4) CWD fallback
+    cand = Path.cwd() / "flowcept" / "docs" / "img" / "flowcept-logo.png"
+    if cand.is_file():
+        return str(cand)
+
+    return None
+
+
+def render_title_with_logo(
+    page_title: str, logo_path: str | None, logo_width: int = 150, add_to_sidebar: bool = True, debug: bool = False
+):
+    """
+    Render a header row with an optional logo next to the title; optionally mirror it in the sidebar.
+    """
+    if debug:
+        st.caption(f"Logo path resolved to: {logo_path or 'NOT FOUND'}")
+
+    if logo_path and Path(logo_path).is_file():
+        col_logo, col_title = st.columns([1, 6])
+        with col_logo:
+            st.image(logo_path, width=logo_width)
+        with col_title:
+            st.title(page_title)
+        if add_to_sidebar:
+            st.sidebar.image(logo_path, width=logo_width)
+    else:
+        st.title(page_title)