flowcept 0.9.11__tar.gz → 0.9.15__tar.gz

{flowcept-0.9.11 → flowcept-0.9.15}/Makefile

@@ -46,6 +46,7 @@ clean:
 	@find . -type f -name "*nohup*" -exec sh -c 'rm -f "$$@" 2>/dev/null || true' sh {} +
 	@sh -c 'sphinx-build -M clean docs docs/_build > /dev/null 2>&1 || true'
 	@sh -c 'rm -f docs/generated/* 2>/dev/null || true'
+	@sh -c 'rm -f docs/_build/* 2>/dev/null || true'
 
 # Build the HTML documentation using Sphinx
 .PHONY: docs

{flowcept-0.9.11 → flowcept-0.9.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowcept
-Version: 0.9.11
+Version: 0.9.15
 Summary: Capture and query workflow provenance data using data observability
 Author: Oak Ridge National Laboratory
 License-Expression: MIT
@@ -149,11 +149,16 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <picture>
+    <!-- Dark theme -->
+    <source srcset="./docs/img/flowcept-logo-dark.png" media="(prefers-color-scheme: dark)" />
+    <!-- Light theme -->
+    <source srcset="./docs/img/flowcept-logo.png" media="(prefers-color-scheme: light)" />
+    <!-- Fallback -->
     <img src="./docs/img/flowcept-logo.png" alt="Flowcept Logo" width="200"/>
   </picture>
 </p>
-<h3 align="center">Lightweight Distributed Workflow Provenance</h3>
 
+<h3 align="center">Lightweight Distributed Workflow Provenance</h3>
 
 
 ---
@@ -162,6 +167,7 @@ Flowcept captures and queries workflow provenance at runtime with minimal code c
 
 ---
 
+
 [![Documentation](https://img.shields.io/badge/docs-readthedocs.io-green.svg)](https://flowcept.readthedocs.io/)
 [![Build](https://github.com/ORNL/flowcept/actions/workflows/create-release-n-publish.yml/badge.svg)](https://github.com/ORNL/flowcept/actions/workflows/create-release-n-publish.yml)
 [![PyPI](https://badge.fury.io/py/flowcept.svg)](https://pypi.org/project/flowcept)
@@ -169,6 +175,15 @@ Flowcept captures and queries workflow provenance at runtime with minimal code c
 [![Code Formatting](https://github.com/ORNL/flowcept/actions/workflows/checks.yml/badge.svg?branch=dev)](https://github.com/ORNL/flowcept/actions/workflows/checks.yml)
 [![License: MIT](https://img.shields.io/github/license/ORNL/flowcept)](LICENSE)
 
+
+
+
+<h4 align="center">
+  <a href="https://flowcept.readthedocs.io/">Documentation</a> &#8226; 
+  <a href="./docs/publications">Publications</a>
+</h4>
+
+
 ---
 
 # Quickstart

{flowcept-0.9.11 → flowcept-0.9.15}/README.md

@@ -1,10 +1,15 @@
 <p align="center">
   <picture>
+    <!-- Dark theme -->
+    <source srcset="./docs/img/flowcept-logo-dark.png" media="(prefers-color-scheme: dark)" />
+    <!-- Light theme -->
+    <source srcset="./docs/img/flowcept-logo.png" media="(prefers-color-scheme: light)" />
+    <!-- Fallback -->
     <img src="./docs/img/flowcept-logo.png" alt="Flowcept Logo" width="200"/>
   </picture>
 </p>
-<h3 align="center">Lightweight Distributed Workflow Provenance</h3>
 
+<h3 align="center">Lightweight Distributed Workflow Provenance</h3>
 
 
 ---
@@ -13,6 +18,7 @@ Flowcept captures and queries workflow provenance at runtime with minimal code c
 
 ---
 
+
 [![Documentation](https://img.shields.io/badge/docs-readthedocs.io-green.svg)](https://flowcept.readthedocs.io/)
 [![Build](https://github.com/ORNL/flowcept/actions/workflows/create-release-n-publish.yml/badge.svg)](https://github.com/ORNL/flowcept/actions/workflows/create-release-n-publish.yml)
 [![PyPI](https://badge.fury.io/py/flowcept.svg)](https://pypi.org/project/flowcept)
@@ -20,6 +26,15 @@ Flowcept captures and queries workflow provenance at runtime with minimal code c
 [![Code Formatting](https://github.com/ORNL/flowcept/actions/workflows/checks.yml/badge.svg?branch=dev)](https://github.com/ORNL/flowcept/actions/workflows/checks.yml)
 [![License: MIT](https://img.shields.io/github/license/ORNL/flowcept)](LICENSE)
 
+
+
+
+<h4 align="center">
+  <a href="https://flowcept.readthedocs.io/">Documentation</a> &#8226; 
+  <a href="./docs/publications">Publications</a>
+</h4>
+
+
 ---
 
 # Quickstart

{flowcept-0.9.11 → flowcept-0.9.15}/docs/conf.py

@@ -1,31 +1,39 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 project = "Flowcept"
 copyright = "Oak Ridge National Lab"
 author = "Oak Ridge National Lab"
 
 # -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
 ]
-
 autosummary_generate = True
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
+# -- HTML output -------------------------------------------------------------
 html_theme = "furo"
 html_title = "Flowcept"
+
+# Keep using your existing 'img' folder as the static path so you don't have to move files.
+# Sphinx will treat everything inside 'img/' as static assets.
 html_static_path = ["img"]
-html_logo = "img/flowcept-logo.png"
+
+# Furo supports automatic dark/light logo switching.
+# IMPORTANT: Paths below are relative to the *root* of each static path ('img' here),
+# so do NOT prefix with 'img/'.
+html_theme_options = {
+    "light_logo": "flowcept-logo.png",
+    "dark_logo": "flowcept-logo-dark.png",
+    # Optional extras:
+    "sidebar_hide_name": True,
+    # "light_css_variables": {},
+    # "dark_css_variables": {},
+}
+
+# html_logo = "img/flowcept-logo.png

flowcept-0.9.15/docs/index.rst

@@ -0,0 +1,49 @@
+Flowcept
+========
+
+.. raw:: html
+
+   <style>
+     /* Show/hide logos based on Furo's theme attribute */
+     .logo-light { display: inline; }
+     .logo-dark  { display: none; }
+
+     html[data-theme="dark"] .logo-light { display: none; }
+     html[data-theme="dark"] .logo-dark  { display: inline; }
+
+     /* When Furo is in 'auto', follow the OS preference */
+     html[data-theme="auto"] .logo-light { display: inline; }
+     html[data-theme="auto"] .logo-dark  { display: none; }
+     @media (prefers-color-scheme: dark) {
+       html[data-theme="auto"] .logo-light { display: none; }
+       html[data-theme="auto"] .logo-dark  { display: inline; }
+     }
+   </style>
+
+   <p align="center">
+     <!-- Keep both images in the DOM and toggle via CSS -->
+     <img src="_static/flowcept-logo.png" alt="Flowcept Logo" width="200" class="logo-light">
+     <img src="_static/flowcept-logo-dark.png" alt="Flowcept Logo (Dark)" width="200" class="logo-dark">
+   </p>
+
+.. image:: https://img.shields.io/badge/GitHub-Flowcept-black?logo=github&logoColor=white
+   :target: https://github.com/ORNL/flowcept
+   :alt: GitHub
+   :align: center
+   :width: 120px
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   quick_start
+   architecture
+   setup
+   prov_capture
+   telemetry_capture
+   prov_storage
+   prov_query
+   schemas
+   contributing
+   cli-reference
+   api-reference

{flowcept-0.9.11 → flowcept-0.9.15}/docs/prov_storage.rst

@@ -70,6 +70,7 @@ Dump the buffer (during or at the end of a run):
        f.dump_buffer()                   # uses settings path
        f.dump_buffer("my_buffer.jsonl") # custom path
 
+
 Read the buffer file later (as list or DataFrame):
 
 .. code-block:: python
@@ -85,6 +86,7 @@ Read the buffer file later (as list or DataFrame):
    # 3) DataFrame with dotted columns (normalized)
    df_norm = Flowcept.read_buffer_file("flowcept_buffer.jsonl", return_df=True, normalize_df=True)
 
+
 Delete a buffer file if needed:
 
 .. code-block:: python
@@ -93,6 +95,7 @@ Delete a buffer file if needed:
    Flowcept.delete_buffer_file()                  # deletes default path from settings
    Flowcept.delete_buffer_file("my_buffer.jsonl")
 
+
 .. note::
 
    The file-based method is **best suited for offline mode** or small, centralized runs.
@@ -104,6 +107,7 @@ Delete a buffer file if needed:
    captured provenance into a single database automatically.
    Alternatively, implement a **custom consumer** to centralize message ingestion and
    enable real-time analysis.
+
 See also
 ^^^^^^^^
 
@@ -169,6 +173,7 @@ This can serve as a template for building custom provenance consumers.
        consumer = MyConsumer()
        consumer.start(daemon=False)
 
+
 **Notes**:
 
 - See also: `Explicit publish example <file:///Users/rsr/Documents/GDrive/ORNL/dev/flowcept/docs/_build/html/prov_capture.html#custom-task-creation-fully-customizable>`_

flowcept-0.9.15/docs/publications/README.md

@@ -0,0 +1,91 @@
+
+### Flowcept Papers
+
+Bibtex is available below.
+
+---
+
+**Towards Lightweight Data Integration using Multi-workflow Provenance and Data Observability**  
+R. Souza, T. J. Skluzacek, S. R. Wilkinson, M. Ziatdinov, and R. Ferreira da Silva,  
+*IEEE International Conference on e-Science*, Limassol, Cyprus, 2023.  
+doi: [10.1109/e-Science58273.2023.10254822](https://doi.org/10.1109/e-Science58273.2023.10254822)  
+PDF: https://arxiv.org/pdf/2308.09004.pdf  
+
+---
+
+**PROV-AGENT: Unified Provenance for Tracking AI Agent Interactions in Agentic Workflows**  
+R. Souza, A. Gueroudji, S. DeWitt, D. Rosendo, T. Ghosal, R. Ross, P. Balaprakash, and R. Ferreira da Silva,  
+*IEEE International Conference on e-Science*, Chicago, USA., 2025.  
+Publisher: IEEE.  
+PDF: https://arxiv.org/pdf/2508.02866  
+
+---
+
+**Workflow Provenance in the Computing Continuum for Responsible, Trustworthy, and Energy-Efficient AI**  
+R. Souza, S. Caino-Lores, M. Coletti, T. J. Skluzacek, A. Costan, F. Suter, M. Mattoso, and R. Ferreira da Silva,  
+*IEEE International Conference on e-Science*, Osaka, Japan, 2024.  
+doi: [10.1109/e-Science62913.2024.10678731](https://doi.org/10.1109/e-Science62913.2024.10678731)  
+PDF: https://hal.science/hal-04902079v1/document  
+
+---
+
+**LLM Agents for Interactive Workflow Provenance: Reference Architecture and Evaluation Methodology**  
+R. Souza, T. Poteet, B. Etz, D. Rosendo, A. Gueroudji, W. Shin, P. Balaprakash, and R. Ferreira da Silva,  
+*Workflows in Support of Large-Scale Science (WORKS) co-located with the ACM/IEEE International Conference for High Performance Computing, Networking, Storage, and Analysis (SC)*, St. Louis, USA, 2025.  
+doi: [10.1145/3731599.3767582](https://doi.org/10.1145/3731599.3767582)  
+
+### Bixtex
+
+```
+@inproceedings{souza2023towards,
+  title={Towards Lightweight Data Integration using Multi-workflow Provenance and Data Observability},
+  author={Souza, Renan and Skluzacek, Tyler J and Wilkinson, Sean R and Ziatdinov, Maxim and da Silva, Rafael Ferreira},
+  booktitle={IEEE International Conference on e-Science},
+  doi={10.1109/e-Science58273.2023.10254822},
+  url={https://doi.org/10.1109/e-Science58273.2023.10254822},
+  pdf={https://arxiv.org/pdf/2308.09004.pdf},
+  year={2023},
+  abstract={Modern large-scale scientific discovery requires multidisciplinary collaboration across diverse computing facilities, including High Performance Computing (HPC) machines and the Edge-to-Cloud continuum. Integrated data analysis plays a crucial role in scientific discovery, especially in the current AI era, by enabling Responsible AI development, FAIR, Reproducibility, and User Steering. However, the heterogeneous nature of science poses challenges such as dealing with multiple supporting tools, cross-facility environments, and efficient HPC execution. Building on data observability, adapter system design, and provenance, we propose MIDA: an approach for lightweight runtime Multi-workflow Integrated Data Analysis. MIDA defines data observability strategies and adaptability methods for various parallel systems and machine learning tools. With observability, it intercepts the dataflows in the background without requiring instrumentation while integrating domain, provenance, and telemetry data at runtime into a unified database ready for user steering queries. We conduct experiments showing end-to-end multi-workflow analysis integrating data from Dask and MLFlow in a real distributed deep learning use case for materials science that runs on multiple environments with up to 276 GPUs in parallel. We show near-zero overhead running up to 100,000 tasks on 1,680 CPU cores on the Summit supercomputer.}
+}
+
+```
+
+```latex
+@inproceedings{souza_prov_agent_2025,
+  author    = {Renan Souza and Amal Gueroudji and Stephen DeWitt and Daniel Rosendo and Tirthankar Ghosal and Robert Ross and Prasanna Balaprakash and Rafael Ferreira da Silva},
+  title     = {PROV-AGENT: Unified Provenance for Tracking {AI} Agent Interactions in Agentic Workflows},
+  booktitle = {IEEE International Conference on e-Science},
+  year      = {2025},
+  pdf = {https://arxiv.org/pdf/2508.02866},
+  publisher = {IEEE},
+  keywords = {Workflows, Agentic Workflows, Provenance, Lineage, Responsible AI, LLM, Agentic AI},
+  abstract = {Large Language Models (LLMs) and other foundation models are increasingly used as the core of AI agents. In agentic workflows, these agents plan tasks, interact with humans and peers, and influence scientific outcomes across federated and heterogeneous environments. However, agents can hallucinate or reason incorrectly, propagating errors when one agent's output becomes another's input. Thus, assuring that agents' actions are transparent, traceable, reproducible, and reliable is critical to assess hallucination risks and mitigate their workflow impacts. While provenance techniques have long supported these principles, existing methods fail to capture and relate agent-centric metadata such as prompts, responses, and decisions with the broader workflow context and downstream outcomes. In this paper, we introduce PROV-AGENT, a provenance model that extends W3C PROV and leverages the Model Context Protocol (MCP) and data observability to integrate agent interactions into end-to-end workflow provenance. Our contributions include: (1) a provenance model tailored for agentic workflows, (2) a near real-time, open-source system for capturing agentic provenance, and (3) a cross-facility evaluation spanning edge, cloud, and HPC environments, demonstrating support for critical provenance queries and agent reliability analysis.}
+}
+```
+
+```latex
+@inproceedings{souza_rtai_2024,
+  author    = {Renan Souza and Silvina Caino-Lores and Mark Coletti and Tyler J. Skluzacek and Alexandru Costan and Frederic Suter and Marta Mattoso and Rafael Ferreira da Silva},
+  title     = {Workflow Provenance in the Computing Continuum for Responsible, Trustworthy, and Energy-Efficient {AI}},
+  booktitle = {IEEE International Conference on e-Science},
+  year      = {2024},
+  location  = {Osaka, Japan},
+  doi = {https://doi.org/10.1109/e-Science62913.2024.10678731},
+  pdf = {https://hal.science/hal-04902079v1/document},
+  publisher = {IEEE},
+  keywords = {Artificial Intelligence, Provenance, Machine Learning, AI workflows, ML workflows, Responsible AI, Trustworthy AI, Reproducibility, AI Lifecycle, Energy-efficient AI},
+  abstract = {As Artificial Intelligence (AI) becomes more pervasive in our society, it is crucial to develop, deploy, and assess Responsible and Trustworthy AI (RTAI) models, i.e., those that consider not only accuracy but also other aspects, such as explainability, fairness, and energy efficiency. Workflow provenance data have historically enabled critical capabilities towards RTAI. Provenance data derivation paths contribute to responsible workflows through transparency in tracking artifacts and resource consumption. Provenance data are well-known for their trustworthiness, helping explainability, reproducibility, and accountability. However, there are complex challenges to achieving RTAI, which are further complicated by the heterogeneous infrastructure in the computing continuum (Edge-Cloud-HPC) used to develop and deploy models. As a result, a significant research and development gap remains between workflow provenance data management and RTAI. In this paper, we present a vision of the pivotal role of workflow provenance in supporting RTAI and discuss related challenges. We present a schematic view of the relationship between RTAI and provenance, and highlight open research directions.}
+}
+```
+
+```latex
+@inproceedings{souza_llm_agents_works_sc25,
+  title     = {{LLM} Agents for Interactive Workflow Provenance: Reference Architecture and Evaluation Methodology},
+  author    = {Souza, Renan and Poteet, Timothy and Etz, Brian and Rosendo, Daniel and Gueroudji, Amal and others},
+  booktitle = {Workflows in Support of Large-Scale Science ({WORKS}) co-located with the {ACM}/{IEEE} International Conference for High Performance Computing, Networking, Storage, and Analysis ({SC})},
+  year      = {2025},
+  address   = {St Louis, MO, USA},
+  doi       = {10.1145/3731599.3767582},
+  keywords  = {scientific workflows, provenance, LLM agents, Large language models, AI agents, agentic workflows, agentic provenance}
+}
+```

{flowcept-0.9.11 → flowcept-0.9.15}/resources/sample_settings.yaml

@@ -1,4 +1,4 @@
-flowcept_version: 0.9.11 # Version of the Flowcept package. This setting file is compatible with this version.
+flowcept_version: 0.9.15 # 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.

{flowcept-0.9.11 → flowcept-0.9.15}/src/flowcept/cli.py

@@ -66,7 +66,7 @@ def init_settings(full: bool = False):
     settings_path_env = os.getenv("FLOWCEPT_SETTINGS_PATH", None)
     if settings_path_env is not None:
         print(f"FLOWCEPT_SETTINGS_PATH environment variable is set to {settings_path_env}.")
-        dest_path = settings_path_env
+        dest_path = Path(settings_path_env)
     else:
         dest_path = Path(os.path.join(configs._SETTINGS_DIR, "settings.yaml"))
 

{flowcept-0.9.11 → flowcept-0.9.15}/src/flowcept/version.py

@@ -4,4 +4,4 @@
 # The expected format is: <Major>.<Minor>.<Patch>
 # This file is supposed to be automatically modified by the CI Bot.
 # See .github/workflows/version_bumper.py
-__version__ = "0.9.11"
+__version__ = "0.9.15"

flowcept-0.9.11/docs/index.rst

@@ -1,29 +0,0 @@
-Flowcept
-========
-
-.. image:: img/flowcept-logo.png
-   :alt: Flowcept Logo
-   :align: center
-   :width: 200px
-
-.. image:: https://img.shields.io/badge/GitHub-Flowcept-black?logo=github&logoColor=white
-   :target: https://github.com/ORNL/flowcept
-   :alt: GitHub
-   :align: center
-   :width: 120px
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   quick_start
-   architecture
-   setup
-   prov_capture
-   telemetry_capture
-   prov_storage
-   prov_query
-   schemas
-   contributing
-   cli-reference
-   api-reference